feat(edge): release region-aware Java tunnels

CONTRIBUTING.md

@@ -50,7 +50,7 @@ Use the smallest test that exercises the behavior:
 - fake-engine integration tests for runtime control-channel and stream behavior;
 - opt-in e2e tests for real engines and managed environments.
 
-See [docs/TESTING.md](docs/TESTING.md) for the e2e matrix.
+See [docs/004-testing.md](docs/004-testing.md) for the e2e matrix.
 
 ## Generated code
 

README.md

@@ -93,11 +93,13 @@ SDKs:
 | `RSTREAM_MTLS_CERT_FILE` | Client certificate file for mTLS authentication. |
 | `RSTREAM_MTLS_KEY_FILE` | Client private key file for mTLS authentication. |
 | `RSTREAM_API_URL` | Control plane API URL for managed project discovery. |
+| `RSTREAM_REGION` | Authorized region to select for a managed project. |
+| `RSTREAM_CONTROL_PLANE_HEADERS` | Additional Control plane request headers encoded as a JSON object. |
 
 `RSTREAM_ENGINE_ADDRESS` is also accepted for compatibility with older local
 SDK workflows. Prefer `RSTREAM_ENGINE` in new code.
 
-See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for supported YAML fields and
+See [docs/001-configuration.md](docs/001-configuration.md) for supported YAML fields and
 error behavior.
 
 ## Published HTTP tunnel
@@ -177,7 +179,7 @@ if (event.type().wireValue().equals("tunnel.created")) {
 `event.id()` is suitable for idempotency. Keep the raw request body unchanged
 when verifying the signature.
 
-See [docs/WEBHOOKS.md](docs/WEBHOOKS.md) for the payload shape and headers.
+See [docs/003-webhooks.md](docs/003-webhooks.md) for the payload shape and headers.
 
 ## Examples
 
@@ -207,7 +209,7 @@ Real-engine tests are opt-in:
 RSTREAM_JAVA_E2E=1 mvn verify
 ```
 
-See [docs/TESTING.md](docs/TESTING.md) for local-engine and managed-environment
+See [docs/004-testing.md](docs/004-testing.md) for local-engine and managed-environment
 test commands.
 
 ## Repository setup and release
@@ -217,7 +219,7 @@ secret for normal pull request checks. Release automation uses release-please an
 requires the maintainer-managed `RELEASE_PLEASE_TOKEN` secret plus the
 `CI_ALLOWED_ACTOR` repository variable.
 
-See [docs/GITHUB_SETUP.md](docs/GITHUB_SETUP.md) before creating or publishing
+See [docs/006-github-setup.md](docs/006-github-setup.md) before creating or publishing
 the repository.
 
 ## License

docs/CONFIGURATION.md → docs/001-configuration.md

@@ -26,12 +26,20 @@ Set `RSTREAM_CONFIG` to use another file.
 | `RSTREAM_MTLS_CERT_FILE` | mTLS client certificate path. |
 | `RSTREAM_MTLS_KEY_FILE` | mTLS client key path. |
 | `RSTREAM_API_URL` | Control plane API URL for managed project discovery. |
+| `RSTREAM_REGION` | Authorized region to select for a managed project. |
+| `RSTREAM_CONTROL_PLANE_HEADERS` | Additional Control plane request headers encoded as a JSON object. |
 | `RSTREAM_TUNNEL_TRANSPORT` | `auto`, `tls`, or `quic`. Java maps `auto` to TLS and rejects explicit `quic`. |
 | `RSTREAM_QUIC_TRANSPORT` | Legacy selector. Prefer `RSTREAM_TUNNEL_TRANSPORT`. |
 
 The SDK also accepts `RSTREAM_ENGINE_ADDRESS` for compatibility with older local
 SDK workflows. Prefer `RSTREAM_ENGINE` in new code.
 
+Region selection requires a managed project endpoint and cannot be combined
+with an explicit engine override. Control plane headers may satisfy a separate
+deployment access layer. Authentication, forwarding, and hop-by-hop headers are
+reserved; malformed values and case-insensitive duplicates are rejected before
+network I/O.
+
 ## Config file
 
 ```yaml

docs/TESTING.md → docs/004-testing.md

@@ -18,7 +18,7 @@ The default suite includes:
 JaCoCo coverage is enforced on maintained SDK code. Generated Protobuf classes
 are excluded from the coverage threshold.
 
-See [TEST_MATRIX.md](TEST_MATRIX.md) for the pre-release coverage matrix.
+See [005-test-matrix.md](005-test-matrix.md) for the pre-release coverage matrix.
 
 ## Real-engine e2e
 

docs/README.md

@@ -0,0 +1,10 @@
+# Java SDK documentation
+
+Read these documents in order:
+
+1. [Configuration](001-configuration.md) documents SDK configuration.
+2. [Tunnels](002-tunnels.md) documents tunnel APIs and behavior.
+3. [Webhooks](003-webhooks.md) documents webhook support.
+4. [Testing](004-testing.md) describes local and CI validation.
+5. [Test matrix](005-test-matrix.md) defines supported runtime combinations.
+6. [GitHub setup](006-github-setup.md) documents repository CI configuration.

examples/forward-local-port/pom.xml

@@ -20,7 +20,7 @@
       <plugin>
         <groupId>org.codehaus.mojo</groupId>
         <artifactId>exec-maven-plugin</artifactId>
-        <version>3.6.2</version>
+        <version>3.6.3</version>
         <configuration>
           <mainClass>io.rstream.examples.ForwardLocalPort</mainClass>
         </configuration>

examples/micronaut-published-http/pom.xml

@@ -36,14 +36,14 @@
     <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-databind</artifactId>
-      <version>2.20.1</version>
+      <version>2.22.1</version>
     </dependency>
   </dependencies>
   <build>
     <plugins>
       <plugin>
         <artifactId>maven-compiler-plugin</artifactId>
-        <version>3.14.1</version>
+        <version>3.15.0</version>
         <configuration>
           <annotationProcessorPaths>
             <path>
@@ -71,7 +71,7 @@
       <plugin>
         <groupId>org.codehaus.mojo</groupId>
         <artifactId>exec-maven-plugin</artifactId>
-        <version>3.6.2</version>
+        <version>3.6.3</version>
         <configuration>
           <mainClass>io.rstream.examples.micronaut.PublishedHttpApplication</mainClass>
         </configuration>

examples/micronaut-webhook-receiver/pom.xml

@@ -49,7 +49,7 @@
       </plugin>
       <plugin>
         <artifactId>maven-compiler-plugin</artifactId>
-        <version>3.14.1</version>
+        <version>3.15.0</version>
         <configuration>
           <annotationProcessorPaths>
             <path>
@@ -82,7 +82,7 @@
       <plugin>
         <groupId>org.codehaus.mojo</groupId>
         <artifactId>exec-maven-plugin</artifactId>
-        <version>3.6.2</version>
+        <version>3.6.3</version>
         <configuration>
           <mainClass>io.rstream.examples.micronaut.WebhookReceiverApplication</mainClass>
         </configuration>

examples/private-dial/pom.xml

@@ -20,7 +20,7 @@
       <plugin>
         <groupId>org.codehaus.mojo</groupId>
         <artifactId>exec-maven-plugin</artifactId>
-        <version>3.6.2</version>
+        <version>3.6.3</version>
         <configuration>
           <mainClass>io.rstream.examples.PrivateDial</mainClass>
         </configuration>

examples/published-http-server/pom.xml

@@ -20,7 +20,7 @@
       <plugin>
         <groupId>org.codehaus.mojo</groupId>
         <artifactId>exec-maven-plugin</artifactId>
-        <version>3.6.2</version>
+        <version>3.6.3</version>
         <configuration>
           <mainClass>io.rstream.examples.PublishedHttpServer</mainClass>
         </configuration>

examples/quarkus-published-http/pom.xml

@@ -6,7 +6,7 @@
   <version>0.3.0</version>
   <name>rstream Quarkus published HTTP example</name>
   <properties>
-    <compiler-plugin.version>3.14.1</compiler-plugin.version>
+    <compiler-plugin.version>3.15.0</compiler-plugin.version>
     <java.version>17</java.version>
     <maven.compiler.release>${java.version}</maven.compiler.release>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

examples/spring-boot-published-http/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-parent</artifactId>
-    <version>3.5.14</version>
+    <version>4.1.0</version>
     <relativePath/>
   </parent>
   <groupId>io.rstream.examples</groupId>

examples/spring-boot-webhook-receiver/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-parent</artifactId>
-    <version>3.5.14</version>
+    <version>4.1.0</version>
     <relativePath/>
   </parent>
   <groupId>io.rstream.examples</groupId>

examples/vertx-published-http/pom.xml

@@ -9,7 +9,7 @@
     <java.version>17</java.version>
     <maven.compiler.release>${java.version}</maven.compiler.release>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <vertx.version>5.1.1</vertx.version>
+    <vertx.version>5.1.5</vertx.version>
   </properties>
   <dependencies>
     <dependency>
@@ -33,7 +33,7 @@
     <plugins>
       <plugin>
         <artifactId>maven-compiler-plugin</artifactId>
-        <version>3.14.1</version>
+        <version>3.15.0</version>
         <configuration>
           <compilerArgs>
             <arg>-Xlint:all</arg>
@@ -45,7 +45,7 @@
       <plugin>
         <groupId>org.codehaus.mojo</groupId>
         <artifactId>exec-maven-plugin</artifactId>
-        <version>3.6.2</version>
+        <version>3.6.3</version>
         <configuration>
           <mainClass>io.rstream.examples.vertx.PublishedHttpVerticle</mainClass>
         </configuration>

examples/webhook-receiver/pom.xml

@@ -20,7 +20,7 @@
       <plugin>
         <groupId>org.codehaus.mojo</groupId>
         <artifactId>exec-maven-plugin</artifactId>
-        <version>3.6.2</version>
+        <version>3.6.3</version>
         <configuration>
           <mainClass>io.rstream.examples.WebhookReceiver</mainClass>
         </configuration>

pom.xml

@@ -33,10 +33,10 @@
     <java.version>17</java.version>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.release>${java.version}</maven.compiler.release>
-    <protobuf.version>4.33.1</protobuf.version>
-    <jackson.version>2.20.1</jackson.version>
-    <junit.version>5.14.1</junit.version>
-    <assertj.version>3.27.6</assertj.version>
+    <protobuf.version>4.35.1</protobuf.version>
+    <jackson.version>2.22.1</jackson.version>
+    <junit.version>6.1.2</junit.version>
+    <assertj.version>3.27.7</assertj.version>
   </properties>
   <dependencies>
     <dependency>
@@ -47,7 +47,7 @@
     <dependency>
       <groupId>org.snakeyaml</groupId>
       <artifactId>snakeyaml-engine</artifactId>
-      <version>2.10</version>
+      <version>3.0.1</version>
     </dependency>
     <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
@@ -78,7 +78,7 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-enforcer-plugin</artifactId>
-        <version>3.6.2</version>
+        <version>3.6.3</version>
         <executions>
           <execution>
             <id>enforce</id>
@@ -117,7 +117,7 @@
       <plugin>
         <groupId>com.diffplug.spotless</groupId>
         <artifactId>spotless-maven-plugin</artifactId>
-        <version>3.1.0</version>
+        <version>3.8.0</version>
         <configuration>
           <java>
             <googleJavaFormat>
@@ -133,7 +133,7 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-compiler-plugin</artifactId>
-        <version>3.14.1</version>
+        <version>3.15.0</version>
         <configuration>
           <showWarnings>true</showWarnings>
           <compilerArgs>
@@ -164,7 +164,7 @@
       <plugin>
         <groupId>org.jacoco</groupId>
         <artifactId>jacoco-maven-plugin</artifactId>
-        <version>0.8.14</version>
+        <version>0.8.15</version>
         <configuration>
           <excludes>
             <exclude>rstream/io_rstrm/protobuf/**</exclude>
@@ -208,7 +208,7 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-source-plugin</artifactId>
-        <version>3.3.1</version>
+        <version>3.4.0</version>
         <executions>
           <execution>
             <id>attach-sources</id>

src/main/java/io/rstream/ClientOptions.java

@@ -1,12 +1,14 @@
 package io.rstream;
 
 import java.time.Duration;
+import java.util.Map;
 
 /** Options accepted by {@link RstreamClient}. */
 public record ClientOptions(
     String apiUrl,
     String configPath,
     String context,
+    Map<String, String> controlPlaneHeaders,
     String engine,
     boolean heartbeat,
     Duration heartbeatInterval,
@@ -15,11 +17,13 @@ public record ClientOptions(
     Boolean noToken,
     String projectEndpoint,
     boolean readConfigFile,
+    String region,
     boolean requireToken,
     String token,
     TlsOptions tls,
     boolean zeroRtt) {
   public ClientOptions {
+    controlPlaneHeaders = controlPlaneHeaders == null ? Map.of() : Map.copyOf(controlPlaneHeaders);
     heartbeatInterval = heartbeatInterval == null ? Duration.ofSeconds(5) : heartbeatInterval;
     connectTimeout = connectTimeout == null ? Duration.ofSeconds(15) : connectTimeout;
     operationTimeout = operationTimeout == null ? Duration.ofSeconds(30) : operationTimeout;
@@ -43,6 +47,7 @@ public static final class Builder {
     private String apiUrl;
     private String configPath;
     private String context;
+    private Map<String, String> controlPlaneHeaders = Map.of();
     private String engine;
     private boolean heartbeat = true;
     private Duration heartbeatInterval = Duration.ofSeconds(5);
@@ -51,6 +56,7 @@ public static final class Builder {
     private Boolean noToken;
     private String projectEndpoint;
     private boolean readConfigFile = true;
+    private String region;
     private boolean requireToken;
     private String token;
     private TlsOptions tls;
@@ -71,6 +77,11 @@ public Builder context(String context) {
       return this;
     }
 
+    public Builder controlPlaneHeaders(Map<String, String> controlPlaneHeaders) {
+      this.controlPlaneHeaders = Map.copyOf(controlPlaneHeaders);
+      return this;
+    }
+
     public Builder engine(String engine) {
       this.engine = engine;
       return this;
@@ -111,6 +122,11 @@ public Builder readConfigFile(boolean readConfigFile) {
       return this;
     }
 
+    public Builder region(String region) {
+      this.region = region;
+      return this;
+    }
+
     public Builder requireToken(boolean requireToken) {
       this.requireToken = requireToken;
       return this;
@@ -136,6 +152,7 @@ public ClientOptions build() {
           apiUrl,
           configPath,
           context,
+          controlPlaneHeaders,
           engine,
           heartbeat,
           heartbeatInterval,
@@ -144,6 +161,7 @@ public ClientOptions build() {
           noToken,
           projectEndpoint,
           readConfigFile,
+          region,
           requireToken,
           token,
           tls,