<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>Overview on Protobuf for Apache Flink DataStream</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/</link><description>Recent content in Overview on Protobuf for Apache Flink DataStream</description><generator>Hugo</generator><language>en-us</language><atom:link href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/index.xml" rel="self" type="application/rss+xml"/><item><title>Quickstart</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/quickstart/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/quickstart/</guid><description>&lt;h1 id="run-a-native-protobuf-datastream-job"&gt;Run a native Protobuf DataStream job&lt;a class="anchor" href="#run-a-native-protobuf-datastream-job"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;Run the standalone &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/blob/0cbc2e7fe405eb12814b0aeddf7bcb636b77d1df/examples/datastream/pom.xml"&gt;application example&lt;/a&gt;
 against a local build of the library, installed into an isolated Maven repository, or against the &lt;a href="#run-against-the-published-library"&gt;published library&lt;/a&gt;
.
Maven Central publishes &lt;code&gt;1.0.0&lt;/code&gt; for Flink 2.x and &lt;code&gt;1.0.0-1.20&lt;/code&gt; for Flink 1.20 LTS.&lt;/p&gt;
&lt;h2 id="build-the-development-artifact"&gt;Build the development artifact&lt;a class="anchor" href="#build-the-development-artifact"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Install &lt;a href="https://mise.jdx.dev/"&gt;mise&lt;/a&gt;
, then clone this repository.
&lt;code&gt;mise install&lt;/code&gt; provides Python 3.14 and uv for the recipe&amp;rsquo;s standard-library checks.
Run these commands from its root with JDK 17:&lt;/p&gt;</description></item><item><title>Usage and configuration</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/usage/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/usage/</guid><description>&lt;h1 id="configure-native-protobuf-values"&gt;Configure native Protobuf values&lt;a class="anchor" href="#configure-native-protobuf-values"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;The &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/quickstart/"&gt;quickstart&lt;/a&gt;
 builds and runs the application examples.
The public application entrypoints are &lt;code&gt;ProtobufTypeInformation&lt;/code&gt; and &lt;code&gt;ProtobufTypeInfoFactory&lt;/code&gt;.
The serializer and snapshot classes are internal machinery; construct types through the public factory or builder.&lt;/p&gt;
&lt;h2 id="explicit-type-information"&gt;Explicit type information&lt;a class="anchor" href="#explicit-type-information"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Use explicit type information for &lt;code&gt;.returns(...)&lt;/code&gt; and per-type settings.
The following construction example uses the generated full-runtime &lt;code&gt;Event&lt;/code&gt; class from the quickstart.
The &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/blob/0cbc2e7fe405eb12814b0aeddf7bcb636b77d1df/examples/datastream/src/main/java/io/github/flink/gcp/protobuf/examples/ExplicitExample.java"&gt;explicit example&lt;/a&gt;
 shows the imports for these types.&lt;/p&gt;
&lt;p&gt;&lt;code&gt;ProtobufTypeInformation&lt;/code&gt; comes from this library; &lt;code&gt;Event&lt;/code&gt; comes from the application&amp;rsquo;s generated code.
Replace the &lt;code&gt;Event&lt;/code&gt; import and class reference with the application&amp;rsquo;s message type.
The example&amp;rsquo;s &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/blob/0cbc2e7fe405eb12814b0aeddf7bcb636b77d1df/examples/datastream/src/main/proto/event.proto"&gt;&lt;code&gt;event.proto&lt;/code&gt;&lt;/a&gt;
 sets &lt;code&gt;java_package = &amp;quot;io.github.flink.gcp.protobuf.examples.generated&amp;quot;&lt;/code&gt; and &lt;code&gt;java_multiple_files = true&lt;/code&gt;, so &lt;code&gt;Event&lt;/code&gt; is a top-level class in that Java package.&lt;/p&gt;</description></item><item><title>DynamicMessage values</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/dynamic-messages/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/dynamic-messages/</guid><description>&lt;h1 id="dynamicmessage-values"&gt;DynamicMessage values&lt;a class="anchor" href="#dynamicmessage-values"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;&lt;code&gt;com.google.protobuf.DynamicMessage&lt;/code&gt; holds a Protobuf message whose schema comes from a descriptor at runtime rather than from a generated class.
The library transports these values and keeps them in managed state when the application supplies type information bound to a root descriptor.&lt;/p&gt;
&lt;p&gt;The &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/blob/0cbc2e7fe405eb12814b0aeddf7bcb636b77d1df/examples/datastream/src/main/java/io/github/flink/gcp/protobuf/examples/DynamicExample.java"&gt;DynamicMessage example&lt;/a&gt;
 is compiled and run with the other &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/quickstart/"&gt;quickstart&lt;/a&gt;
 examples; the snippets below come from it.
&lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0005-descriptor-bound-dynamic-messages/"&gt;ADR-0005&lt;/a&gt;
 records the design.&lt;/p&gt;
&lt;h2 id="dynamicmessage-and-generated-common-types"&gt;DynamicMessage and generated common types&lt;a class="anchor" href="#dynamicmessage-and-generated-common-types"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Several generated message types also carry data whose shape varies at runtime.
They are a different tool: their schema is fixed and known to the library through their generated class.&lt;/p&gt;</description></item><item><title>State compatibility</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/compatibility/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/compatibility/</guid><description>&lt;h1 id="protobuf-updates-and-state-compatibility"&gt;Protobuf updates and state compatibility&lt;a class="anchor" href="#protobuf-updates-and-state-compatibility"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;Adding a field can preserve Protobuf binary compatibility, and the current development library restores state across that change.
It accepts unchanged schemas and the &lt;a href="#schema-changes"&gt;supported schema changes&lt;/a&gt;
, and it rejects other changes to the declarations that saved values reach when the job restores its state.
Version 1.0.0 is the first release published to Maven Central; the 0.x versions were unpublished development milestones.&lt;/p&gt;
&lt;h2 id="development-builds-before-100"&gt;Development builds before 1.0.0&lt;a class="anchor" href="#development-builds-before-100"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A build of this source is the development version &lt;code&gt;1.0.0-SNAPSHOT&lt;/code&gt;, which restores supported schema changes.
The 0.x versions are development milestones, not releases, and their APIs, defaults, runtime requirements, and state formats are not compatibility contracts.
Retain the exact source revision and artifact checksums alongside schemas and state; a SNAPSHOT version alone does not identify their writer.&lt;/p&gt;</description></item><item><title>Supported types</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/common-types/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/common-types/</guid><description>&lt;h1 id="google-well-known-types-and-opentelemetry-values"&gt;Google Well-Known Types and OpenTelemetry values&lt;a class="anchor" href="#google-well-known-types-and-opentelemetry-values"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;Google Well-Known Types (WKT) and OpenTelemetry composite values use generated message classes with declared descriptors.
They use the same &lt;code&gt;ProtobufTypeInformation&lt;/code&gt; and serializer as application messages.
Changing a Struct key or choosing another AnyValue variant changes the data within that descriptor, so unchanged-schema restoration supports those changes.&lt;/p&gt;
&lt;h2 id="tested-types"&gt;Tested types&lt;a class="anchor" href="#tested-types"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;table&gt;
	&lt;thead&gt;
			&lt;tr&gt;
					&lt;th&gt;Types&lt;/th&gt;
					&lt;th&gt;Tested values&lt;/th&gt;
			&lt;/tr&gt;
	&lt;/thead&gt;
	&lt;tbody&gt;
			&lt;tr&gt;
					&lt;td&gt;Google &lt;code&gt;Struct&lt;/code&gt;, &lt;code&gt;Value&lt;/code&gt;, &lt;code&gt;ListValue&lt;/code&gt;&lt;/td&gt;
					&lt;td&gt;Nested maps and lists, null, booleans, strings, numbers, empty containers, and unset versus present-default oneof cases&lt;/td&gt;
			&lt;/tr&gt;
			&lt;tr&gt;
					&lt;td&gt;Google &lt;code&gt;Any&lt;/code&gt;&lt;/td&gt;
					&lt;td&gt;Default values, a type URL and opaque bytes, and nesting inside an application message&lt;/td&gt;
			&lt;/tr&gt;
			&lt;tr&gt;
					&lt;td&gt;Google &lt;code&gt;Timestamp&lt;/code&gt;, &lt;code&gt;Duration&lt;/code&gt;, &lt;code&gt;Empty&lt;/code&gt;, &lt;code&gt;FieldMask&lt;/code&gt;&lt;/td&gt;
					&lt;td&gt;Defaults, representative populated messages, and nested use&lt;/td&gt;
			&lt;/tr&gt;
			&lt;tr&gt;
					&lt;td&gt;Google &lt;code&gt;DoubleValue&lt;/code&gt;, &lt;code&gt;FloatValue&lt;/code&gt;, &lt;code&gt;Int64Value&lt;/code&gt;, &lt;code&gt;UInt64Value&lt;/code&gt;, &lt;code&gt;Int32Value&lt;/code&gt;, &lt;code&gt;UInt32Value&lt;/code&gt;, &lt;code&gt;BoolValue&lt;/code&gt;, &lt;code&gt;StringValue&lt;/code&gt;, &lt;code&gt;BytesValue&lt;/code&gt;&lt;/td&gt;
					&lt;td&gt;Default and populated wrappers, including a present wrapper containing a default scalar&lt;/td&gt;
			&lt;/tr&gt;
			&lt;tr&gt;
					&lt;td&gt;OTel &lt;code&gt;AnyValue&lt;/code&gt;, &lt;code&gt;ArrayValue&lt;/code&gt;, &lt;code&gt;KeyValueList&lt;/code&gt;, &lt;code&gt;KeyValue&lt;/code&gt;&lt;/td&gt;
					&lt;td&gt;Nested heterogeneous values, bytes, empty containers, unset and all eight present oneof cases, and profiling string/key dictionary indices&lt;/td&gt;
			&lt;/tr&gt;
	&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;Wrappers remain supported for existing schemas.
For new schemas, prefer explicit field presence, such as proto3 &lt;code&gt;optional&lt;/code&gt;, as described in the &lt;a href="https://protobuf.dev/reference/protobuf/google.protobuf/"&gt;WKT guidance&lt;/a&gt;
.&lt;/p&gt;</description></item><item><title>Development</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/development/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/development/</guid><description>&lt;h1 id="development"&gt;Development&lt;a class="anchor" href="#development"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;h2 id="toolchain"&gt;Toolchain&lt;a class="anchor" href="#toolchain"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The Maven Wrapper pins Maven 3.10.0; all Maven recipes in just invoke the wrapper.
The default local JDK is Temurin 17, and CI runs Temurin 17 and 21.
Java output targets release 17.
&lt;code&gt;mise.toml&lt;/code&gt; supplies just, the workflow and Markdown linters, pinact, Python 3.14, uv, Hugo Extended 0.164.0, and Go 1.26.5.
Maven supplies Java build plugins and protoc; protoc does not need to be on PATH.
The repository&amp;rsquo;s Python tools and their tests use the non-packaged uv project at the root.
&lt;code&gt;mise.toml&lt;/code&gt; provides Python 3.14, &lt;code&gt;requires-python = &amp;quot;==3.14.*&amp;quot;&lt;/code&gt; in &lt;code&gt;pyproject.toml&lt;/code&gt; limits uv to that minor, and &lt;code&gt;uv.lock&lt;/code&gt; locks pytest and PyYAML as development dependencies.
&lt;code&gt;pyproject.toml&lt;/code&gt; sets &lt;code&gt;python-preference = &amp;quot;only-system&amp;quot;&lt;/code&gt; and &lt;code&gt;python-downloads = &amp;quot;never&amp;quot;&lt;/code&gt;, so uv takes Python 3.14 from PATH, where &lt;code&gt;mise x&lt;/code&gt; and mise activation put the &lt;code&gt;mise.toml&lt;/code&gt; interpreter, and fails rather than download one.
An activated virtual environment or an existing &lt;code&gt;.venv&lt;/code&gt; takes precedence over PATH; deactivate other environments and delete a &lt;code&gt;.venv&lt;/code&gt; built from another interpreter.
Manage Python with mise, including the global default, rather than &lt;code&gt;uv python install&lt;/code&gt; or &lt;code&gt;uv python pin --global&lt;/code&gt;; the repository has no &lt;code&gt;.python-version&lt;/code&gt;, so a global uv pin can override the mise interpreter or make the recipes fail.
Recipes run the tools with &lt;code&gt;uv run --locked --isolated --no-dev&lt;/code&gt;: each run uses a temporary environment with only the standard library, and a stale lock fails instead of being rewritten.
These recipes take &lt;code&gt;uv&lt;/code&gt; from PATH, which &lt;code&gt;mise x -- just&lt;/code&gt; or a mise-activated shell provides.&lt;/p&gt;</description></item><item><title>Documentation versions</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/versions/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/versions/</guid><description>&lt;h1 id="documentation-versions"&gt;Documentation versions&lt;a class="anchor" href="#documentation-versions"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;Before 1.0.0, the site contains Development from &lt;code&gt;main&lt;/code&gt; and each 0.x development milestone.
A milestone is a published GitHub pre-release tagged &lt;code&gt;v0.Y.Z&lt;/code&gt;; the site keeps the latest patch of each 0.x minor and labels it, for example, &lt;code&gt;0.1 (development milestone)&lt;/code&gt;.
A milestone page shows only its tagged source, so behavior added on &lt;code&gt;main&lt;/code&gt; afterwards appears only in Development.
Neither Development nor milestone documentation implies that artifacts are available on Maven Central.
Existing development evidence remains in the source tree.
Milestones leave the site when the first stable release is published.&lt;/p&gt;</description></item><item><title/><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0006-central-portal-releases/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0006-central-portal-releases/</guid><description>&lt;h1 id="adr-0006-releases-stage-both-artifact-lines-on-the-central-portal-and-publish-after-both-validate"&gt;ADR-0006: Releases stage both artifact lines on the Central Portal and publish after both validate&lt;a class="anchor" href="#adr-0006-releases-stage-both-artifact-lines-on-the-central-portal-and-publish-after-both-validate"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;ul&gt;
&lt;li&gt;Status: Accepted&lt;/li&gt;
&lt;li&gt;Date: 2026-10-31&lt;/li&gt;
&lt;li&gt;Issue: &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/13"&gt;#13&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Implements: The publication requirements of &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0003-flink-version-compatibility/#state-and-release-acceptance"&gt;ADR-0003&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Implementation: The release build, bundle inspection, unsigned CI rehearsal, &lt;code&gt;Release&lt;/code&gt; workflow, and Central Portal helper are implemented; version 1.0.0 is the first publication through them&lt;/li&gt;
&lt;li&gt;Current instructions: &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/development/#release-artifacts"&gt;Release artifacts&lt;/a&gt;
 and &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/development/#publishing-a-release"&gt;Publishing a release&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id="context"&gt;Context&lt;a class="anchor" href="#context"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Version 1.0.0 is the first Maven Central publication of &lt;code&gt;io.github.flink-gcp:flink-datastream-protobuf&lt;/code&gt;.
Central never deletes or replaces a published version, so a defect found after publication requires a new version.
ADR-0003 requires two artifact lines from one source revision, &lt;code&gt;X.Y.Z&lt;/code&gt; built at the Flink 2.x floor and &lt;code&gt;X.Y.Z-1.20&lt;/code&gt; built for Flink 1.20, a guard on Maven&amp;rsquo;s effective model before publication, and validation of both before either is published.&lt;/p&gt;</description></item><item><title>ADR-0001: Native Protobuf type integration for DataStream</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0001-native-protobuf-type-integration/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0001-native-protobuf-type-integration/</guid><description>&lt;h1 id="adr-0001-native-protobuf-type-integration-for-datastream"&gt;ADR-0001: Native Protobuf type integration for DataStream&lt;a class="anchor" href="#adr-0001-native-protobuf-type-integration-for-datastream"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;ul&gt;
&lt;li&gt;Status: Accepted&lt;/li&gt;
&lt;li&gt;Date: 2026-09-06&lt;/li&gt;
&lt;li&gt;Publication policy amended: 2026-09-13; 0.x versions are unpublished development milestones and 1.0.0 is the first Maven Central release&lt;/li&gt;
&lt;li&gt;Release contract amended: 2026-09-08, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/7"&gt;issue #7&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Frame buffering amended: 2026-10-11, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/42"&gt;issue #42&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Sizing traversal amended: 2026-10-19, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/43"&gt;issue #43&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Generated sizes for bounded types amended: 2026-10-22, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/112"&gt;issue #112&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Large-frame reads amended: 2026-10-25, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/113"&gt;issue #113&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;DynamicMessage design: 2026-10-29, extended by &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0005-descriptor-bound-dynamic-messages/"&gt;ADR-0005&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;1.0.0 persisted-format restart amended: 2026-10-29, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/140"&gt;issue #140&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Protobuf 4 build baseline amended: 2026-10-30, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/141"&gt;issue #141&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Implementation: Serializer, type integration, and descriptor snapshots implemented; the 0.2.0 descriptor evaluator is implemented, tested with descriptor pairs, and used by snapshot restore; MiniCluster tests verify runtime recovery with unchanged schemas and supported schema changes from state written by the same development build (&lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/16"&gt;issue #16&lt;/a&gt;
); the 1.0.0 format restart is implemented, and the library does not read state written by 0.x milestones (&lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/140"&gt;issue #140&lt;/a&gt;
)&lt;/li&gt;
&lt;li&gt;Evidence: &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/spike-0/"&gt;Spike 0&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Runtime scope superseded: 2026-09-10, &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0003-flink-version-compatibility/"&gt;ADR-0003&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id="context"&gt;Context&lt;a class="anchor" href="#context"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Flink uses TypeInformation to select serializers for operator transport and managed state.
Generated Protobuf messages otherwise fall back to generic serialization in the tested configuration.
The goal is an explicit native integration that works with &lt;code&gt;pipeline.generic-types: false&lt;/code&gt; and owns a documented checkpoint/savepoint compatibility policy.
Connector boundary SerializationSchema and DeserializationSchema implementations, and Table/SQL formats, are separate concerns.&lt;/p&gt;</description></item><item><title>ADR-0002: A single Maven module with a shared local and CI workflow</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0002-build-and-development-workflow/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0002-build-and-development-workflow/</guid><description>&lt;h1 id="adr-0002-a-single-maven-module-with-a-shared-local-and-ci-workflow"&gt;ADR-0002: A single Maven module with a shared local and CI workflow&lt;a class="anchor" href="#adr-0002-a-single-maven-module-with-a-shared-local-and-ci-workflow"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;ul&gt;
&lt;li&gt;Status: Accepted&lt;/li&gt;
&lt;li&gt;Date: 2026-09-06&lt;/li&gt;
&lt;li&gt;Release contract amended: 2026-09-08, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/7"&gt;issue #7&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Dependency update policy amended: 2026-09-12&lt;/li&gt;
&lt;li&gt;Benchmark Avro and Jackson update exclusions amended: 2026-10-11&lt;/li&gt;
&lt;li&gt;Benchmark Avro and Jackson convergence check amended: 2026-10-12, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/84"&gt;issue #84&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Maven dependency graph submission amended: 2026-10-12, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/82"&gt;issue #82&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Development bundle tooling amended: 2026-09-16, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/40"&gt;issue #40&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;CI compiler reuse and job budgets amended: 2026-10-11, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/46"&gt;issue #46&lt;/a&gt;
; evidence: &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/ci-budget/"&gt;CI budget measurements&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Retained baseline retrieval amended: 2026-10-11, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/61"&gt;issue #61&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Python tooling through uv amended: 2026-10-12, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/96"&gt;issue #96&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Development milestone documentation amended: 2026-10-19, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/62"&gt;issue #62&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Required &lt;code&gt;CI passed&lt;/code&gt; ruleset amended: 2026-10-19&lt;/li&gt;
&lt;li&gt;CI Maven mirror and shared repository cache amended: 2026-10-30, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/135"&gt;issue #135&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Retained 0.x checks ended by the 1.0.0 format restart: 2026-10-31, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/140"&gt;issue #140&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Current instructions: &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/development/"&gt;Development&lt;/a&gt;
 and &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/blob/0cbc2e7fe405eb12814b0aeddf7bcb636b77d1df/CONTRIBUTING.md"&gt;Contributing&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id="decision"&gt;Decision&lt;a class="anchor" href="#decision"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Use one jar module with Maven coordinates &lt;code&gt;io.github.flink-gcp:flink-datastream-protobuf&lt;/code&gt;, starting at &lt;code&gt;0.1.0-SNAPSHOT&lt;/code&gt;.
Develop it in the flink-gcp organization without depending on flink-connector-gcp.
Reuse that project&amp;rsquo;s Apache-2.0 licensing, collective copyright identity, Maven Wrapper, connector parent 2.0.0, mise/just entry points, Java formatting, Checkstyle, Apache RAT, JUnit 5, and AssertJ conventions.
The project metadata and packaged notices identify The flink-gcp authors rather than inheriting ASF ownership.
Keep third-party attribution on the Apache-derived Checkstyle files.&lt;/p&gt;</description></item><item><title>ADR-0003: Support current/previous Flink 2.x minors and Flink 1.20 LTS</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0003-flink-version-compatibility/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0003-flink-version-compatibility/</guid><description>&lt;h1 id="adr-0003-support-currentprevious-flink-2x-minors-and-flink-120-lts"&gt;ADR-0003: Support current/previous Flink 2.x minors and Flink 1.20 LTS&lt;a class="anchor" href="#adr-0003-support-currentprevious-flink-2x-minors-and-flink-120-lts"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;ul&gt;
&lt;li&gt;Status: Accepted&lt;/li&gt;
&lt;li&gt;Date: 2026-09-10&lt;/li&gt;
&lt;li&gt;Supersedes: The Flink 2.3-only runtime scope in &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0001-native-protobuf-type-integration/"&gt;ADR-0001&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Amends: The build matrix in &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0002-build-and-development-workflow/"&gt;ADR-0002&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Unchanged-jar check amended: 2026-10-30, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/141"&gt;issue #141&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Release discovery amended: 2026-10-31, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/142"&gt;issue #142&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Current instructions: &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/development/"&gt;Development&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id="context"&gt;Context&lt;a class="anchor" href="#context"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The maintainer wants Flink 1.20 and 2.x support under the same policy as flink-connector-gcp.
Compiling separately on each runtime establishes source compatibility but cannot prove that a released jar works on both supported 2.x minors.
The 1.20 TypeInformation API still requires &lt;code&gt;createSerializer(ExecutionConfig)&lt;/code&gt;, while Flink 2.x removed it.
The existing test factory therefore needs a small adapter, even though the production serializer currently compiles unchanged.
Flink 1.20 also does not infer native list element information from the probe&amp;rsquo;s TypeHint.&lt;/p&gt;</description></item><item><title>ADR-0004: Opt-in serializer benchmarks with explicit comparison contracts</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0004-serializer-benchmarks/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0004-serializer-benchmarks/</guid><description>&lt;h1 id="adr-0004-opt-in-serializer-benchmarks-with-explicit-comparison-contracts"&gt;ADR-0004: Opt-in serializer benchmarks with explicit comparison contracts&lt;a class="anchor" href="#adr-0004-opt-in-serializer-benchmarks-with-explicit-comparison-contracts"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;ul&gt;
&lt;li&gt;Status: Accepted&lt;/li&gt;
&lt;li&gt;Date: 2026-09-12&lt;/li&gt;
&lt;li&gt;Evidence content gate added: 2026-09-18, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/41"&gt;issue #41&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Temporary GCE execution added: 2026-10-11, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/44"&gt;issue #44&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Paired native/Chill mode added: 2026-10-11, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/42"&gt;issue #42&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Variant placement calibrated: 2026-10-21, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/109"&gt;issue #109&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Pairwise comparison placement added: 2026-10-22, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/115"&gt;issue #115&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;DynamicMessage lanes added: 2026-10-31, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/45"&gt;issue #45&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Issue: &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/30"&gt;#30&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id="decision"&gt;Decision&lt;a class="anchor" href="#decision"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Keep the single production Maven module and add a &lt;code&gt;benchmarks&lt;/code&gt; profile with test-scoped JMH, Avro, Thrift, Chill, and Jackson result-reader dependencies.
Compile handwritten benchmark sources and generated records into test outputs only.
Keep the compiler toolchain optional and generated Java under &lt;code&gt;target&lt;/code&gt;.
Do not publish a benchmark classifier, add production dependencies, or change the native serializer API for measurement.&lt;/p&gt;</description></item><item><title>ADR-0005: Descriptor-bound DynamicMessage type and snapshot contracts</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0005-descriptor-bound-dynamic-messages/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0005-descriptor-bound-dynamic-messages/</guid><description>&lt;h1 id="adr-0005-descriptor-bound-dynamicmessage-type-and-snapshot-contracts"&gt;ADR-0005: Descriptor-bound DynamicMessage type and snapshot contracts&lt;a class="anchor" href="#adr-0005-descriptor-bound-dynamicmessage-type-and-snapshot-contracts"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;ul&gt;
&lt;li&gt;Status: Accepted&lt;/li&gt;
&lt;li&gt;Date: 2026-10-29&lt;/li&gt;
&lt;li&gt;Issue: &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/21"&gt;#21&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Extends: The generated-message contracts in &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0001-native-protobuf-type-integration/"&gt;ADR-0001&lt;/a&gt;
, which apply here except where this record states otherwise&lt;/li&gt;
&lt;li&gt;Implementation: Implemented by &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/22"&gt;issue #22&lt;/a&gt;
; &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/23"&gt;issue #23&lt;/a&gt;
 validated state recovery and the upgrade paths and documented usage&lt;/li&gt;
&lt;li&gt;1.0.0 persisted-format restart: 2026-10-31, &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/140"&gt;issue #140&lt;/a&gt;
 renamed the dynamic snapshot class and kept its layout&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id="context"&gt;Context&lt;a class="anchor" href="#context"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The 0.1.0 and 0.2.0 development milestones support generated full-runtime messages only.
Type information, serializers, and snapshots identify a payload type by its generated class, and the class supplies the descriptor, parser, and default instance.
The 0.3.0 milestone adds &lt;code&gt;com.google.protobuf.DynamicMessage&lt;/code&gt;, which an application creates from a descriptor without a generated class.&lt;/p&gt;</description></item><item><title>Aliased large-frame reads in the native serializer</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-large-read/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-large-read/</guid><description>&lt;h1 id="aliased-large-frame-reads-in-the-native-serializer"&gt;Aliased large-frame reads in the native serializer&lt;a class="anchor" href="#aliased-large-frame-reads-in-the-native-serializer"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;This report measures the large-frame read path changed for &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/113"&gt;#113&lt;/a&gt;
.
After the &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-generated-size/"&gt;generated-size change&lt;/a&gt;
, large &lt;code&gt;deserialize&lt;/code&gt; and &lt;code&gt;deserializeReuse&lt;/code&gt; were the only cells that missed the ADR-0004 native/Chill tolerance on both profiles, at 1.26 to 1.27 times Chill&amp;rsquo;s time with about 132 KB/op allocated for a 64 KiB payload.
One plan on temporary GCE VMs compares the change with the unchanged serializer.
The measurement contract is &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0004-serializer-benchmarks/"&gt;ADR-0004&lt;/a&gt;
; the comparison does not establish whole-job throughput, heap retention, or state compatibility.&lt;/p&gt;</description></item><item><title>Architecture decisions</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/readme/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/readme/</guid><description>&lt;h1 id="architecture-decisions"&gt;Architecture decisions&lt;a class="anchor" href="#architecture-decisions"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;table&gt;
	&lt;thead&gt;
			&lt;tr&gt;
					&lt;th&gt;Record&lt;/th&gt;
					&lt;th&gt;Decision&lt;/th&gt;
					&lt;th&gt;Status&lt;/th&gt;
			&lt;/tr&gt;
	&lt;/thead&gt;
	&lt;tbody&gt;
			&lt;tr&gt;
					&lt;td&gt;&lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0001-native-protobuf-type-integration/"&gt;ADR-0001&lt;/a&gt;
&lt;/td&gt;
					&lt;td&gt;Native Protobuf type integration for DataStream&lt;/td&gt;
					&lt;td&gt;Accepted&lt;/td&gt;
			&lt;/tr&gt;
			&lt;tr&gt;
					&lt;td&gt;&lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0002-build-and-development-workflow/"&gt;ADR-0002&lt;/a&gt;
&lt;/td&gt;
					&lt;td&gt;A single Maven module with a shared local and CI workflow&lt;/td&gt;
					&lt;td&gt;Accepted&lt;/td&gt;
			&lt;/tr&gt;
			&lt;tr&gt;
					&lt;td&gt;&lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0003-flink-version-compatibility/"&gt;ADR-0003&lt;/a&gt;
&lt;/td&gt;
					&lt;td&gt;Current/previous Flink 2.x minors and a separate 1.20 LTS build&lt;/td&gt;
					&lt;td&gt;Accepted; replaces ADR-0001&amp;rsquo;s runtime scope&lt;/td&gt;
			&lt;/tr&gt;
			&lt;tr&gt;
					&lt;td&gt;&lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0004-serializer-benchmarks/"&gt;ADR-0004&lt;/a&gt;
&lt;/td&gt;
					&lt;td&gt;Opt-in serializer benchmarks and practical comparison contract&lt;/td&gt;
					&lt;td&gt;Accepted&lt;/td&gt;
			&lt;/tr&gt;
			&lt;tr&gt;
					&lt;td&gt;&lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0005-descriptor-bound-dynamic-messages/"&gt;ADR-0005&lt;/a&gt;
&lt;/td&gt;
					&lt;td&gt;Descriptor-bound DynamicMessage type and snapshot contracts&lt;/td&gt;
					&lt;td&gt;Accepted; extends ADR-0001; implemented and validated&lt;/td&gt;
			&lt;/tr&gt;
			&lt;tr&gt;
					&lt;td&gt;&lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0006-central-portal-releases/"&gt;ADR-0006&lt;/a&gt;
&lt;/td&gt;
					&lt;td&gt;Both artifact lines are staged on the Central Portal and published after both validate&lt;/td&gt;
					&lt;td&gt;Accepted; implemented&lt;/td&gt;
			&lt;/tr&gt;
	&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;These records distinguish accepted design from implemented behavior.
The native serializer, application-facing type integration, and versioned descriptor snapshots are implemented.
MiniCluster tests verify checkpoint recovery and savepoint restoration with HashMap and RocksDB state backends, including supported schema changes.
A refinement updates its existing record; a reversal adds a new record and marks the old one as superseded.&lt;/p&gt;</description></item><item><title>CI compiler reuse and job budgets</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/ci-budget/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/ci-budget/</guid><description>&lt;h1 id="ci-compiler-reuse-and-job-budgets"&gt;CI compiler reuse and job budgets&lt;a class="anchor" href="#ci-compiler-reuse-and-job-budgets"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;This page records the GitHub runner durations behind the Verify job limits and the benchmark compiler cache from &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/46"&gt;#46&lt;/a&gt;
.
The &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/development/#ci-compiler-reuse-and-job-budgets"&gt;development guide&lt;/a&gt;
 describes the current procedure, and &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0002-build-and-development-workflow/"&gt;ADR-0002&lt;/a&gt;
 records the decision and the rejected alternatives.
These are budget measurements on shared runners, not benchmark results; no CI check compares them with a threshold.&lt;/p&gt;
&lt;h2 id="method"&gt;Method&lt;a class="anchor" href="#method"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Durations come from the &lt;code&gt;started_at&lt;/code&gt; and &lt;code&gt;completed_at&lt;/code&gt; timestamps of jobs and steps in the GitHub Actions jobs API.
Only successful jobs are counted, including successful jobs in runs where another job failed or the run was cancelled; every step value is that step&amp;rsquo;s own duration.
All jobs ran on &lt;code&gt;ubuntu-latest&lt;/code&gt; standard runners; the measured runs after the change reported Ubuntu 24.04 on x86_64 in the compiler cache key.
Medians of an even number of jobs are the mean of the two middle values.
GitHub &lt;a href="https://github.com/actions/runner-images/issues/14748"&gt;announced&lt;/a&gt;
 that &lt;code&gt;ubuntu-latest&lt;/code&gt; moves to Ubuntu 26 from 2026-10-19; that changes the distribution release in the key, and these durations do not describe the new image.
A matrix job is one of the ten runtime/JDK/Protobuf builds; the binary compatibility and development bundle jobs are reported as whole jobs.&lt;/p&gt;</description></item><item><title>Coded-stream buffer allocation in the native serializer</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-buffer-allocation/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-buffer-allocation/</guid><description>&lt;h1 id="coded-stream-buffer-allocation-in-the-native-serializer"&gt;Coded-stream buffer allocation in the native serializer&lt;a class="anchor" href="#coded-stream-buffer-allocation-in-the-native-serializer"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;This report measures the per-record coded-stream buffers investigated in &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/42"&gt;#42&lt;/a&gt;
.
It separates the output and input buffers with controlled variants of one source tree and compares each with the unchanged serializer on the same VM.
The measurement contract is &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0004-serializer-benchmarks/"&gt;ADR-0004&lt;/a&gt;
; the comparison does not establish whole-job throughput or state compatibility.&lt;/p&gt;
&lt;h2 id="change-under-test"&gt;Change under test&lt;a class="anchor" href="#change-under-test"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Before the change, every &lt;code&gt;serialize&lt;/code&gt; call wrapped the target view in &lt;code&gt;CodedOutputStream.newInstance(OutputStream)&lt;/code&gt;, and every &lt;code&gt;deserialize&lt;/code&gt; call wrapped a bounded frame stream in &lt;code&gt;CodedInputStream.newInstance(InputStream)&lt;/code&gt;.
In the pinned Protobuf 3.25.9 and 4.33.6 runtimes, both factories allocate a 4,096-byte buffer for each call.&lt;/p&gt;</description></item><item><title>Development artifact bundles</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/development-baselines/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/development-baselines/</guid><description>&lt;h1 id="development-artifact-bundles"&gt;Development artifact bundles&lt;a class="anchor" href="#development-artifact-bundles"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;Issue &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/40"&gt;#40&lt;/a&gt;
 prepared fixed development inputs for the state and API checks in #16 and #17.
The final v0.1.0, v0.2.0, and v0.3.0 bundles are retained as assets of the &lt;a href="#retained-v010-baseline"&gt;&lt;code&gt;v0.1.0&lt;/code&gt; pre-release&lt;/a&gt;
, the &lt;a href="#retained-v020-baseline"&gt;&lt;code&gt;v0.2.0&lt;/code&gt; pre-release&lt;/a&gt;
, and the &lt;a href="#retained-v030-baseline"&gt;&lt;code&gt;v0.3.0&lt;/code&gt; pre-release&lt;/a&gt;
.
The tooling labels a development capture &lt;code&gt;development-tooling-baseline&lt;/code&gt; with &lt;code&gt;milestone.final=false&lt;/code&gt;; a successful capture alone does not designate a milestone baseline.
No 0.x coordinates are published to Maven Central.
The 1.0.0 format restart (&lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/140"&gt;#140&lt;/a&gt;
) removed the 0.x snapshot classes, so the current library does not restore the state in these bundles; they remain retained development records.
The capture, check, read, restore, API, and consumer commands also apply to bundles that published releases write, starting with 1.0.0; &lt;a href="#retain-a-published-release"&gt;retain a published release&lt;/a&gt;
 describes their capture and retention.&lt;/p&gt;</description></item><item><title>Generated sizes for small writes in the native serializer</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-generated-size/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-generated-size/</guid><description>&lt;h1 id="generated-sizes-for-small-writes-in-the-native-serializer"&gt;Generated sizes for small writes in the native serializer&lt;a class="anchor" href="#generated-sizes-for-small-writes-in-the-native-serializer"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;This report measures the generated-size path added for &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/112"&gt;#112&lt;/a&gt;
.
After the &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-sizing-allocation/"&gt;sizing-traversal change&lt;/a&gt;
, scalar and nested &lt;code&gt;serialize&lt;/code&gt; and &lt;code&gt;serializeSameInstance&lt;/code&gt; still took 2.4 to 2.9 times Chill&amp;rsquo;s time, collections writes 2.0 to 2.5 times, and scalar and nested &lt;code&gt;buildAndSerialize&lt;/code&gt; 1.5 to 1.6 times, while a diagnostic variant without safe sizing met the ADR-0004 tolerance in almost every cell.
One plan on temporary GCE VMs compares the change with the unchanged serializer.
The measurement contract is &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0004-serializer-benchmarks/"&gt;ADR-0004&lt;/a&gt;
; the comparison does not establish whole-job throughput or state compatibility.&lt;/p&gt;</description></item><item><title>Runtime state recovery</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/runtime-recovery/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/runtime-recovery/</guid><description>&lt;h1 id="runtime-state-recovery"&gt;Runtime state recovery&lt;a class="anchor" href="#runtime-state-recovery"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;For resource locations, build/test invocation, capture, and dependency updates, see &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/development/#test-resources-and-version-updates"&gt;Test resources and version updates&lt;/a&gt;
.
This page records the recovery scenarios and their measured scope.&lt;/p&gt;
&lt;p&gt;&lt;code&gt;ProtobufRecoveryITCase&lt;/code&gt; executes the production serializer in a two-TaskManager MiniCluster with parallelism 2 and max parallelism 16.
It uses stable integer stream keys, string MapState user keys, and generated messages as values in ValueState, MapState, and operator ListState.
HashMap and RocksDB backends run the same cases.
The ValueState implementation is checked at runtime to distinguish the selected backends.&lt;/p&gt;</description></item><item><title>Serializer benchmarks for the 0.1.0 development milestone</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-benchmarks-v0.1.0/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-benchmarks-v0.1.0/</guid><description>&lt;h1 id="serializer-benchmarks-for-the-010-development-milestone"&gt;Serializer benchmarks for the 0.1.0 development milestone&lt;a class="anchor" href="#serializer-benchmarks-for-the-010-development-milestone"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;This report compares equivalent logical records through Flink serializers.
The benchmark is development tooling and makes no production API or state-compatibility promise.
The measurement contract is &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0004-serializer-benchmarks/"&gt;ADR-0004&lt;/a&gt;
.&lt;/p&gt;
&lt;h2 id="reproduce"&gt;Reproduce&lt;a class="anchor" href="#reproduce"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The ordinary build does not require benchmark tools.
Run these commands from the &lt;code&gt;v0.1.0&lt;/code&gt; tag, whose benchmark pins differ from later revisions, with a compiler cache directory that has not built another Thrift version.
For opt-in generation, install CMake, Flex, Bison 3.8 or newer, and a C++ compiler; build the pinned Thrift 0.23.0 compiler in an external cache:&lt;/p&gt;</description></item><item><title>Serializer benchmarks for the 1.0.0 release candidate</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-benchmarks-v1.0.0/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-benchmarks-v1.0.0/</guid><description>&lt;h1 id="serializer-benchmarks-for-the-100-release-candidate"&gt;Serializer benchmarks for the 1.0.0 release candidate&lt;a class="anchor" href="#serializer-benchmarks-for-the-100-release-candidate"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;This report is the release-candidate performance evidence for 1.0.0 that &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/45"&gt;#45&lt;/a&gt;
 requires.
It repeats the long serializer benchmarks of the &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-benchmarks-v0.1.0/"&gt;0.1.0 report&lt;/a&gt;
 on temporary Google Compute Engine VMs, with the same corpus, lanes, operations, fork and iteration settings, paired blocks, and practical tolerance, all defined in &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0004-serializer-benchmarks/"&gt;ADR-0004&lt;/a&gt;
.
It adds the two DynamicMessage lanes that ADR-0004 describes.
The results describe the recorded VMs and runtimes; they do not rank serializers universally and do not establish whole-job throughput or saved-state compatibility.&lt;/p&gt;</description></item><item><title>Serializer implementation performance check</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-performance/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-performance/</guid><description>&lt;h1 id="serializer-implementation-performance-check"&gt;Serializer implementation performance check&lt;a class="anchor" href="#serializer-implementation-performance-check"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;This local comparison measures the getter-name removal, metadata cache, and sizing refactor against commit &lt;code&gt;f6a6e33d272f74da80f82e9d77718399cda9702e&lt;/code&gt;.
The candidate is the implementation accompanying this report.
It is a small implementation comparison, not a ranking against other formats or an end-to-end Flink throughput result.
The maintained cross-format harness and its v0.1.0 baseline work are described in the &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-benchmarks-v0.1.0/"&gt;serializer benchmark report&lt;/a&gt;
, tracked in &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/30"&gt;#30&lt;/a&gt;
.&lt;/p&gt;
&lt;h2 id="conditions"&gt;Conditions&lt;a class="anchor" href="#conditions"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Measurements ran on 2026-09-11 using an Apple M1 Pro with 32 GiB RAM, macOS 26.6.2, and Temurin 17.0.20+8.
Both variants used Flink 2.3.0, JMH 1.37, G1 GC, a fixed 256 MiB heap, and one benchmark thread.
Protobuf runtime and generated fixtures were paired at 3.25.8 and 4.33.6 in separate classpaths.
Each case used two JVM forks, three 500 ms warmup iterations, five 500 ms measurement iterations, average time mode, and the JMH GC profiler.
Final comparisons ran sequentially without concurrent builds or another benchmark.
The table reports the JMH mean and its 99.9% confidence interval half-width; allocated bytes are rounded per operation.
These short runs on a development machine cannot establish small performance differences reliably.&lt;/p&gt;</description></item><item><title>Site licenses</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/licenses/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/licenses/</guid><description>&lt;h1 id="site-licenses"&gt;Site licenses&lt;a class="anchor" href="#site-licenses"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;The shared design and version controls are licensed under Apache-2.0 by The flink-gcp authors.
The &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/blob/0cbc2e7fe405eb12814b0aeddf7bcb636b77d1df/LICENSE"&gt;Apache-2.0 license&lt;/a&gt;
 also covers this library.
Fuse.js v7.3.0 is Copyright (c) 2026 Kiro Risk and is distributed under Apache-2.0; its notice is retained in the bundled search module.
The following notices accompany the theme and its bundled normalization stylesheet.&lt;/p&gt;
&lt;h2 id="hugo-book-v0140"&gt;Hugo Book v0.14.0&lt;a class="anchor" href="#hugo-book-v0140"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;The MIT License (MIT)
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;Copyright (c) 2018 Alex Shpak
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;Permission is hereby granted, free of charge, to any person obtaining a copy of
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;this software and associated documentation files (the &amp;#34;Software&amp;#34;), to deal in
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;the Software without restriction, including without limitation the rights to
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;the Software, and to permit persons to whom the Software is furnished to do so,
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;subject to the following conditions:
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;The above copyright notice and this permission notice shall be included in all
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;copies or substantial portions of the Software.
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;THE SOFTWARE IS PROVIDED &amp;#34;AS IS&amp;#34;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;h2 id="modern-normalize-v301"&gt;modern-normalize v3.0.1&lt;a class="anchor" href="#modern-normalize-v301"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;MIT License
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;Copyright (c) Sindre Sorhus &amp;lt;sindresorhus@gmail.com&amp;gt; (https://sindresorhus.com)
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;Copyright (c) Jonathan Neal
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;Copyright (c) Nicolas Gallagher
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the &amp;#34;Software&amp;#34;), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;THE SOFTWARE IS PROVIDED &amp;#34;AS IS&amp;#34;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;</description></item><item><title>Sizing traversal allocation in the native serializer</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-sizing-allocation/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-sizing-allocation/</guid><description>&lt;h1 id="sizing-traversal-allocation-in-the-native-serializer"&gt;Sizing traversal allocation in the native serializer&lt;a class="anchor" href="#sizing-traversal-allocation-in-the-native-serializer"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;This report measures the safe-sizing traversal investigated in &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/43"&gt;#43&lt;/a&gt;
.
After the &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/serializer-buffer-allocation/"&gt;buffer-allocation change&lt;/a&gt;
, scalar and nested &lt;code&gt;serialize&lt;/code&gt; and &lt;code&gt;serializeSameInstance&lt;/code&gt; still took 6.2 to 7.0 times Chill&amp;rsquo;s time and allocated 1.9 to 2.2 KB/op; the 0.1.0 diagnostics had sampled allocation sites in the safe-sizing traversal.
Two plans measure the change on temporary GCE VMs: one compares the final change with the unchanged serializer, and an earlier one separates the traversal bookkeeping, the descriptor work, and the remaining sizing cost from the output work with controlled variants.
The measurement contract is &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0004-serializer-benchmarks/"&gt;ADR-0004&lt;/a&gt;
; the comparison does not establish whole-job throughput or state compatibility.&lt;/p&gt;</description></item><item><title>Spike 0 validation</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/spike-0/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/spike-0/</guid><description>&lt;h1 id="spike-0-validation"&gt;Spike 0 validation&lt;a class="anchor" href="#spike-0-validation"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;h2 id="outcome"&gt;Outcome&lt;a class="anchor" href="#outcome"&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;On 2026-09-06, the required superclass-registration and three transport paths passed on Flink 2.3.0 with both tested Protobuf runtimes and both JDKs.
The stop condition did not occur, so the project can proceed with configuration registration as a supported design path alongside explicit TypeInformation.&lt;/p&gt;
&lt;p&gt;The initial Chill transport succeeded: Chill 0.7.6 transported a StringValue while Kryo 5.6.2 was loaded.
H1 is not supported by this observation.
The experiment did find both Kryo major versions in the dependency graph; their coexistence did not make this particular job fail.&lt;/p&gt;</description></item><item><title>Variant placement across temporary GCE VMs</title><link>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/gce-placement-calibration/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/validation/gce-placement-calibration/</guid><description>&lt;h1 id="variant-placement-across-temporary-gce-vms"&gt;Variant placement across temporary GCE VMs&lt;a class="anchor" href="#variant-placement-across-temporary-gce-vms"&gt;#&lt;/a&gt;&lt;/h1&gt;
&lt;p&gt;This report calibrates the comparison of benchmark variants that run on different VMs of one plan, for &lt;a href="https://github.com/flink-gcp/flink-datastream-protobuf/issues/109"&gt;#109&lt;/a&gt;
.
The &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/development/#temporary-gce-execution"&gt;temporary GCE procedure&lt;/a&gt;
 measured every variant of a profile sequentially on one VM, so a plan&amp;rsquo;s wall-clock time grows with its variant count: each &lt;code&gt;just benchmark-pair&lt;/code&gt; variant takes about 70 minutes.
Placing each variant on its own VM would make that time independent of the variant count, but it compares variants across hosts.
The &lt;a href="https://flink-gcp.github.io/flink-datastream-protobuf/1.0/docs/adr/0004-serializer-benchmarks/"&gt;ADR-0004&lt;/a&gt;
 native/Chill protocol controls host speed within each block, and this calibration measures how much of the between-VM difference that control leaves.&lt;/p&gt;</description></item></channel></rss>