tunnel (#127)

Author: slinkydeveloper

Cargo.toml

@@ -10,58 +10,149 @@ rust-version = "1.90.0"
 [[example]]
 name = "tracing"
 path = "examples/tracing.rs"
-required-features = ["tracing-span-filter"]
+required-features = ["http_server", "tracing-span-filter"]
 
 [[example]]
 name = "schema"
 path = "examples/schema.rs"
-required-features = ["schemars"]
+required-features = ["http_server", "schemars"]
+
+[[example]]
+name = "counter"
+path = "examples/counter.rs"
+required-features = ["http_server"]
+
+[[example]]
+name = "cron"
+path = "examples/cron.rs"
+required-features = ["http_server"]
+
+[[example]]
+name = "failures"
+path = "examples/failures.rs"
+required-features = ["http_server"]
+
+[[example]]
+name = "fan_out"
+path = "examples/fan_out.rs"
+required-features = ["http_server"]
+
+[[example]]
+name = "greeter"
+path = "examples/greeter.rs"
+required-features = ["http_server"]
+
+[[example]]
+name = "run"
+path = "examples/run.rs"
+required-features = ["http_server"]
+
+[[example]]
+name = "signals"
+path = "examples/signals.rs"
+required-features = ["http_server"]
 
 [[example]]
 name = "ingress_client"
 path = "examples/ingress_client.rs"
 required-features = ["reqwest-client"]
 
+[[example]]
+name = "tunnel"
+path = "examples/tunnel.rs"
+required-features = ["tunnel", "tracing-span-filter"]
+
 [features]
 default = ["http_server", "rand", "uuid", "tracing-span-filter", "rust_crypto"]
 reqwest-client = ["dep:reqwest"]
+rand = ["dep:rand"]
+uuid = ["dep:uuid"]
 hyper = ["dep:hyper", "restate-sdk-shared-core/http"]
-http_server = ["hyper", "hyper/server", "hyper/http2", "hyper-util", "tokio/net", "tokio/signal", "tokio/macros"]
+http_server = [
+    "hyper",
+    "hyper/server",
+    "hyper/http2",
+    "dep:hyper-util",
+    "hyper-util/tokio",
+    "hyper-util/server",
+    "hyper-util/server-graceful",
+    "hyper-util/http2",
+    "tokio/net",
+    "tokio/signal",
+    "tokio/macros",
+]
 tracing-span-filter = ["dep:tracing-subscriber"]
 lambda = [ "dep:http-serde", "dep:lambda_runtime", "dep:aws_lambda_events"]
 # jsonwebtoken crypto backend pass-through for request identity verification.
 # Enable exactly one (or call jsonwebtoken's CryptoProvider::install_default yourself).
-rust_crypto = ["restate-sdk-shared-core/rust_crypto"]
-aws_lc_rs = ["restate-sdk-shared-core/aws_lc_rs"]
+rust_crypto = ["restate-sdk-shared-core/rust_crypto", "jsonwebtoken?/rust_crypto", "rustls?/ring"]
+aws_lc_rs = ["restate-sdk-shared-core/aws_lc_rs", "jsonwebtoken?/aws_lc_rs", "rustls?/aws_lc_rs"]
+tunnel = [
+    "hyper",
+    "hyper/server",
+    "hyper/http2",
+    "dep:hickory-resolver",
+    "dep:hostname",
+    "dep:hyper-util",
+    "dep:jsonwebtoken",
+    "hyper-util/tokio",
+    "rand",
+    "dep:rustls",
+    "dep:rustls-native-certs",
+    "dep:socket2",
+    "dep:tokio-rustls",
+    "dep:tokio-util",
+    "dep:url",
+    "tokio/io-util",
+    "tokio/macros",
+    "tokio/net",
+    "tokio/rt",
+    "tokio/signal",
+    "uuid",
+    "uuid/v4",
+]
 
 [dependencies]
 bytes = "1.11"
 futures = "0.3"
+hickory-resolver = { version = "0.26", default-features = false, features = ["system-config", "tokio"], optional = true }
+hostname = { version = "0.4", optional = true }
 http = "1.4"
 http-body = "1.0.1"
 http-body-util = "0.1"
 hyper = { version = "1.8", optional = true}
-hyper-util = { version = "0.1", features = ["tokio", "server", "server-graceful", "http2"], optional = true }
+hyper-util = { version = "0.1", default-features = false, optional = true }
+jsonwebtoken = { version = "10.3", default-features = false, optional = true }
 pin-project-lite = "0.2"
 percent-encoding = "2.3"
 rand = { version = "0.10", optional = true }
 regress = "0.10"
 reqwest = { version = "0.13", optional = true }
 restate-sdk-macros = { version = "0.11", path = "macros" }
 restate-sdk-shared-core = { version = "=7.0.3", features = ["request_identity", "sha2_random_seed", "http"] }
+rustls = { version = "0.23", default-features = false, features = ["std", "tls12"], optional = true }
+rustls-native-certs = { version = "0.8", optional = true }
 schemars = { version = "1.2", optional = true }
 serde = "1.0"
 serde_json = "1.0"
+socket2 = { version = "0.6", optional = true }
 thiserror = "2.0"
 tokio = { version = "1.49", default-features = false, features = ["sync", "time"] }
+tokio-rustls = { version = "0.26", default-features = false, features = ["tls12"], optional = true }
+tokio-util = { version = "0.7", default-features = false, features = ["rt"], optional = true }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["registry"], optional = true }
+url = { version = "2.5", optional = true }
 uuid = { version = "1.20", optional = true }
 http-serde = { version = "2.1.1", optional = true }
 aws_lambda_events = { version = "1.0", optional = true }
 lambda_runtime = { version = "1.0", optional = true }
 
 [dev-dependencies]
+base64 = "0.22"
+bs58 = "0.5"
+ed25519-dalek = "2"
+hyper = { version = "1.8", default-features = false, features = ["client", "http2"] }
 tokio = { version = "1", features = ["full"] }
 tracing-subscriber = { version = "0.3", features = ["env-filter", "registry"] }
 trybuild = "1.0"

README.md

@@ -98,6 +98,37 @@ Generated object and workflow ingress clients additionally take their key in `fr
 generic `Client<E>` and generated clients are available without `reqwest-client`; implement
 `RequestExecutor` to use another buffered HTTP transport.
 
+## Connecting through a Restate Cloud tunnel
+
+The optional Unix-only in-process tunnel lets a service connect outbound to Restate Cloud, so the
+service does not need to expose an inbound HTTP port. Enable the `tunnel` feature:
+
+```toml
+[dependencies]
+restate-sdk = { version = "0.11", features = ["tunnel"] }
+tokio = { version = "1", features = ["full"] }
+```
+
+When default features are disabled, select a crypto provider explicitly by adding either
+`rust_crypto` or `aws_lc_rs` alongside `tunnel`. If both are enabled, `rust_crypto` is selected
+deterministically.
+
+The Restate operator injects the discovery and authentication settings, so an operator-managed
+deployment needs no application-side tunnel configuration:
+
+```rust
+use restate_sdk::prelude::*;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let endpoint = Endpoint::builder().bind(Greeter).build();
+    Tunnel::new(endpoint).run().await?;
+    Ok(())
+}
+```
+
+See the [complete tunnel example](examples/tunnel.rs).
+
 ## Running on Lambda
 
 The Restate Rust SDK supports running services on AWS Lambda using Lambda Function URLs. This allows you to deploy your Restate services as serverless functions.

examples/services/my_service.rs

@@ -13,7 +13,10 @@ impl MyService {
 #[tokio::main]
 async fn main() {
     tracing_subscriber::fmt::init();
-    HttpServer::new(Endpoint::builder().bind(MyService).build())
-        .listen_and_serve("0.0.0.0:9080".parse().unwrap())
-        .await;
+    #[cfg(feature = "http_server")]
+    {
+        HttpServer::new(Endpoint::builder().bind(MyService).build())
+            .listen_and_serve("0.0.0.0:9080".parse().unwrap())
+            .await;
+    }
 }

examples/services/my_virtual_object.rs

@@ -22,7 +22,10 @@ impl MyVirtualObject {
 #[tokio::main]
 async fn main() {
     tracing_subscriber::fmt::init();
-    HttpServer::new(Endpoint::builder().bind(MyVirtualObject).build())
-        .listen_and_serve("0.0.0.0:9080".parse().unwrap())
-        .await;
+    #[cfg(feature = "http_server")]
+    {
+        HttpServer::new(Endpoint::builder().bind(MyVirtualObject).build())
+            .listen_and_serve("0.0.0.0:9080".parse().unwrap())
+            .await;
+    }
 }

examples/services/my_workflow.rs

@@ -26,7 +26,10 @@ impl MyWorkflow {
 #[tokio::main]
 async fn main() {
     tracing_subscriber::fmt::init();
-    HttpServer::new(Endpoint::builder().bind(MyWorkflow).build())
-        .listen_and_serve("0.0.0.0:9080".parse().unwrap())
-        .await;
+    #[cfg(feature = "http_server")]
+    {
+        HttpServer::new(Endpoint::builder().bind(MyWorkflow).build())
+            .listen_and_serve("0.0.0.0:9080".parse().unwrap())
+            .await;
+    }
 }

examples/tunnel.rs

@@ -0,0 +1,26 @@
+use restate_sdk::prelude::*;
+
+struct Greeter;
+
+#[service]
+impl Greeter {
+    #[handler]
+    async fn greet(&self, _ctx: Context<'_>, name: String) -> HandlerResult<String> {
+        Ok(format!("Greetings {name}"))
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Install a subscriber so the tunnel's startup line (including the
+    // deployment URL to register) is printed.
+    tracing_subscriber::fmt::init();
+
+    let endpoint = Endpoint::builder().bind(Greeter).build();
+
+    // The Restate operator supplies the tunnel configuration through the
+    // RESTATE_INPROC_* environment variables and its projected token Secret.
+    Tunnel::new(endpoint).run().await?;
+
+    Ok(())
+}

justfile

@@ -52,11 +52,19 @@ check-fmt:
     cargo fmt --all -- --check
 
 clippy: (_target-installed target)
-    cargo clippy {{ _target-option }} --all-targets --workspace -- -D warnings
+    cargo clippy {{ _target-option }} --all-targets --all-features --workspace -- -D warnings
 
 # Runs all lints (fmt, clippy, deny)
 lint: check-fmt clippy
 
+# Checks the SDK's minimal build and both tunnel crypto-provider configurations.
+check-sdk-features: (_target-installed target)
+    cargo check {{ _target-option }} -p restate-sdk --no-default-features
+    cargo check {{ _target-option }} -p restate-sdk --no-default-features --features tunnel,rust_crypto
+    cargo check {{ _target-option }} -p restate-sdk --no-default-features --features tunnel,aws_lc_rs
+    cargo check {{ _target-option }} -p restate-sdk --features tunnel --example tunnel
+    cargo tree -p restate-sdk --no-default-features
+
 build *flags: (_target-installed target)
     cargo build {{ _target-option }} {{ _features }} {{ flags }}
 
@@ -66,11 +74,16 @@ print-target:
 test: (_target-installed target)
     cargo nextest run {{ _target-option }} --all-features --workspace
 
-doctest:
-    cargo test --doc
+test-tunnel: (_target-installed target)
+    cargo test {{ _target-option }} -p restate-sdk --no-default-features --features tunnel,rust_crypto
+    cargo test {{ _target-option }} -p restate-sdk --no-default-features --features tunnel,aws_lc_rs
+    cargo test {{ _target-option }} -p restate-sdk --doc --features tunnel
+
+doctest: (_target-installed target)
+    cargo test {{ _target-option }} --doc --workspace --all-features
 
 # Runs lints and tests
-verify: lint test doctest
+verify: lint check-sdk-features test-tunnel test doctest
 
 udeps *flags:
     RUSTC_BOOTSTRAP=1 cargo udeps --all-features --all-targets {{ flags }}

release-notes/unreleased/127-tunnel-client.md

@@ -0,0 +1,30 @@
+# Release Notes for Issue #127: In-process Restate Cloud tunnel
+
+## New Feature
+
+The SDK can now serve an endpoint over outbound HTTP/2 connections to Restate Cloud, so a
+service no longer needs an inbound HTTP port. It is Unix-only and behind the non-default `tunnel`
+feature (plus a crypto backend, `rust_crypto` or `aws_lc_rs`):
+
+```toml
+restate-sdk = { version = "0.11", features = ["tunnel"] }
+```
+
+The operator supplies the `RESTATE_INPROC_*` environment variables and a projected token Secret, so
+the application just runs the tunnel:
+
+```rust
+use restate_sdk::prelude::*;
+
+let endpoint = Endpoint::builder().bind(Greeter).build();
+Tunnel::new(endpoint).run().await?;
+```
+
+`run()` handles SIGINT/SIGTERM: the first signal drains gracefully, a second forces close. For an
+application-managed lifecycle, use `connect()` (returns after the first successful handshake):
+
+```rust
+let connection = Tunnel::new(endpoint).connect().await?;
+println!("{}", connection.info().deployment_url());
+connection.shutdown().await?; // graceful drain; or .close() for abrupt
+```