Add Envoy TCP Routing example demonstrating source-based dynamic cluster selection by SiiiTschiii · Pull Request #332 · proxy-wasm/proxy-wasm-rust-sdk

SiiiTschiii · 2025-11-20T03:21:44Z

Introduce a new Proxy-Wasm TCP filter example that demonstrates dynamic routing of TCP connections based on source IP addresses at the TCP stream context (L4). This example showcases application-layer routing decisions without HTTP processing, filling a gap in the existing HTTP-focused examples.

Inspired by the wasmerang project, this example demonstrates advanced TCP routing patterns in Envoy/Istio/K8s environments using WASM filters.

Key Features

Source-based routing: Dynamic cluster selection based on source IP last octet (even → egress-router1, odd → egress-router2)
TCP stream context: Operates at L4 rather than HTTP layer for protocol-agnostic routing
Envoy filter state API: Uses set_envoy_filter_state foreign function with protobuf encoding
Complete Docker setup: Includes Docker Compose environment for testing with httpbin.org
Comprehensive documentation: Usage examples, expected output, and technical context

Implementation Details

Protobuf definitions for Envoy's filter state API with build-time code generation
MSRV-compatible dependencies (Rust 1.65) with explicit pinning for CI compatibility
Envoy v1.34.1 configuration with dual upstream clusters

Documentation Highlights

Links to Proxy-Wasm spec for TCP stream context
Explanation of TCP vs HTTP layer routing trade-offs
Future enhancement ideas: PROXY protocol support for source-based egress routing in managed K8s environments

This example is useful for scenarios requiring performance-critical or protocol-agnostic routing decisions where application-layer processing should be avoided.

PiotrSikora

Thanks, this is great real-world example!

SiiiTschiii · 2025-11-29T01:28:34Z

@PiotrSikora thanks for the review. I believe I addressed all of them.

Introduce a new Proxy-Wasm TCP filter example that demonstrates dynamic routing of TCP connections based on source IP addresses. This example showcases TCP-level filtering, filling a gap in the existing HTTP-focused examples. Key features: - Dynamic cluster selection based on source IP last octet (even/odd) - Uses Envoy's set_envoy_filter_state foreign function with protobuf encoding - Includes comprehensive Docker Compose setup for testing - Full documentation with usage examples and expected output Implementation details: - Protobuf definitions for Envoy's filter state API - Build script for code generation from proto files - Unit tests for IP parsing and routing logic - Envoy configuration with dual upstream clusters Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

- Remove trailing whitespace - Use next_back() instead of last() for better performance Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

- Update log 0.4.27 → 0.4.28 - Update proc-macro2 1.0.101 → 1.0.103 - Update quote 1.0.41 → 1.0.42 - Update unicode-ident 1.0.19 → 1.0.22 Generated by: bazelisk run //bazel/cargo:crates_vendor -- --repin all Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Pin proc-macro2 and quote in build-dependencies to versions compatible with Rust 1.65 (the SDK's MSRV). Without these pins, cargo may select newer versions (e.g., quote 1.0.42) that require Rust 1.68+, causing CI builds to fail. This follows best practices by explicitly pinning problematic transitive dependencies rather than setting rust-version, which is not used by other examples. Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

- Add Apache 2.0 license header to set_envoy_filter_state.proto - Remove rust-version field from tcp_rerouting example Cargo.toml - Keep explicit dependency pins for proc-macro2 and quote to ensure Rust 1.65 compatibility This approach follows the pattern of other examples (no rust-version) while ensuring MSRV compatibility through explicit dependency pinning rather than relying on rust-version, which doesn't prevent Cargo from selecting incompatible dependency versions. Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Remove examples/tcp_rerouting/src/generated/ from git tracking and add to .gitignore. Generated code should not be committed as it: - Can be regenerated from the .proto file via build.rs - Creates unnecessary diff noise when dependencies update - Can get out of sync with source The file is automatically generated during build by prost-build, so this does not affect functionality. Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Rename tcp_rerouting to envoy_tcp_routing to: - Clearly indicate this is an Envoy-specific example - Use "routing" instead of "rerouting" for better terminology Changes: - Renamed directory: examples/tcp_rerouting → examples/envoy_tcp_routing - Updated package name: proxy-wasm-example-envoy-tcp-routing - Updated all references in README.md files - Updated Docker Compose network name and WASM filename - Updated Envoy config filter names and WASM path - Updated .gitignore path Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Remove the statement about most examples focusing on HTTP, as it's not essential information for the README. Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Add explanation that the example operates at the TCP stream context (L4) rather than the HTTP application layer, highlighting its usefulness for scenarios where application-layer processing should be avoided. Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Add links to TCP stream and HTTP stream contexts in the Proxy-Wasm spec, and clarify that operating at the TCP level is useful for performance and protocol-agnostic routing decisions. Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

…ure enhancements - Fix grammar: "In separate terminals" → "In a separate terminal" - Add consistency: "routes to" → "routes via" in output examples - Add "Note on Destination Information" section explaining: - Hardcoded httpbin.org endpoints in both clusters - PROXY protocol for preserving metadata across TCP hops - Implementation approach using WASM stream context + Envoy config - Document future enhancement for source-based egress router use case: - Routing via different external IPs (e.g., even vs. odd source IP) - Explain conventional network approach (routing tables + IP rules) - Note challenges in managed K8s (requires plugins like Multus CNI) - Clarify how K8s abstracts layer 3 routing configuration Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

This reverts commit 467e8d6. The Bazel dependency updates are not related to the envoy_tcp_routing example, which builds using cargo with wasm32-wasip1 target. The example has its own dependency pins in Cargo.toml for MSRV compatibility and does not use the Bazel build system. Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

…ble deps - Change build target from wasm32-wasip1 to wasm32-wasi for MSRV (1.65) compatibility - Update docker-compose.yaml to mount wasm32-wasi artifact path - Pin build dependencies to latest MSRV-compatible versions: - prost-build 0.11.9, quote 1.0.41, proc-macro2 1.0 (existing pins) - indexmap 2.11.4, home 0.5.5 (pinned transitive deps) - Update README.md build instructions to reflect new target The wasm32-wasip1 target is not available in Rust 1.65. By switching to wasm32-wasi and constraining transitive dependencies that require newer Rust editions (indexmap 2.12+ needs edition 2024, home 0.5.12+ needs edition 2024), we ensure the example builds with the project's MSRV. Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

SiiiTschiii · 2025-11-29T05:06:42Z

@PiotrSikora Note on cargo outdated CI Check that is failing

The cargo outdated check in CI currently fails for this example because it runs with the latest stable Rust (1.83) rather than the project's MSRV (1.65). When analyzing available updates, it encounters transitive dependencies like home 0.5.12 which require edition 2024 (not yet stabilized in Rust 1.83).

The example itself builds successfully with MSRV 1.65 because we've pinned the problematic transitive dependencies (indexmap = "=2.11.4", home = "=0.5.5"). However, cargo outdated doesn't respect these pins when checking the crates.io index for newer versions—it attempts to parse manifests of all available versions and fails on edition 2024 crates.

Potential solutions:

Run the cargo outdated CI step with the MSRV toolchain (1.65)
Skip the outdated check for examples that explicitly manage MSRV-constrained dependencies
Document this as a known limitation when maintaining MSRV-compatible examples

The dependency pins are intentional and necessary to maintain MSRV compatibility while still using the latest compatible versions of direct dependencies.

PiotrSikora · 2025-12-05T07:38:30Z

@SiiiTschiii does #340 help?

PiotrSikora · 2025-12-05T21:18:57Z

@SiiiTschiii does #340 help?

@SiiiTschiii it fixed the edition2024 error, so now the outdated check only complains about the pinned dependencies.

But I don't think that all examples have to be MSRV-compatible (and I don't believe that we enforce that in the CI), so I'd ignore MSRV in this example.

SiiiTschiii · 2025-12-05T22:05:20Z

@SiiiTschiii does #340 help?

@SiiiTschiii it fixed the edition2024 error, so now the outdated check only complains about the pinned dependencies.

But I don't think that all examples have to be MSRV-compatible (and I don't believe that we enforce that in the CI), so I'd ignore MSRV in this example.

Alright, done

SiiiTschiii · 2025-12-15T00:23:43Z

@PiotrSikora can you trigger the workflow again please?

SiiiTschiii · 2026-02-02T05:33:25Z

@PiotrSikora alright I added the missing license. Can I run those blocked CI steps locally myself? That would be better than waiting 1 month until I figure out that a license header is missing.

Anyway it would be great if you could try again and hopefully we can merge it now.

PiotrSikora · 2026-02-02T05:48:07Z

@PiotrSikora alright I added the missing license. Can I run those blocked CI steps locally myself?

Yes, see: https://github.com/proxy-wasm/proxy-wasm-rust-sdk/blob/main/DEVELOPMENT.md#testing

Although, some Google org-wide checks like: CLA, DCO and Actions Workflow Security Scan aren't there.

PiotrSikora · 2026-05-13T20:07:35Z

You need to fix DCO (add Signed-off-by line to all your commits).

Addresses: #332 (comment) Addresses: #332 (comment) Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

…conventions Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

… review nits Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Keep only the intended removal of target cleanup in envoy_tcp_routing jobs. Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

SiiiTschiii · 2026-05-13T20:30:34Z

@PiotrSikora thanks for the review feedback. I implemented it! The nightly pipeline seem to fail when you run it previously but I don't see how it is related to my code changes. Can you have a look?

PiotrSikora · 2026-05-13T21:03:39Z

It's unrelated to your changes, see: #365.

SiiiTschiii · 2026-05-13T21:09:59Z

It's unrelated to your changes, see: #365.

@PiotrSikora Ok, so what's the plan? Wait for merge of #365 and then rebase. Or go ahead and merge?

SiiiTschiii · 2026-05-20T15:18:11Z

Run cargo outdated --root-deps-only --exit-code 1
Name       Project  Compat  Latest  Kind    Platform
----       -------  ------  ------  ----    --------
hashbrown  0.16.1   ---     0.17.1  Normal  ---
Error: Process completed with exit code 1.

Unrelated. Adressed in #364 (comment)

SiiiTschiii · 2026-05-20T15:19:12Z

@PiotrSikora let me know once we are are a step further here. Since all other CI/CD steps are successful can we consider merging this?

PiotrSikora

@SiiiTschiii that should be the last round of it, pretty much only style fixes.

PiotrSikora · 2026-05-20T18:39:16Z

The outdated check should be fixed once you merge with main.

Also, I'm happy to apply those style changes myself if that's easier, assuming that you don't disagree with them.

SiiiTschiii · 2026-05-20T19:00:42Z

The outdated check should be fixed once you merge with main.

Also, I'm happy to apply those style changes myself if that's easier, assuming that you don't disagree with them.

@PiotrSikora go ahead. I agree with all of them.

Signed-off-by: Piotr Sikora <code@piotrsikora.dev>

…cp-re-routing Signed-off-by: Piotr Sikora <code@piotrsikora.dev>

PiotrSikora

Thank you!

SiiiTschiii · 2026-05-20T20:19:59Z

@PiotrSikora thanks for your thorough review and contribution. Can you please merge the PR? I seem to lack permissions

PiotrSikora · 2026-05-20T20:36:53Z

Done, thank you again!

SiiiTschiii requested a review from PiotrSikora as a code owner November 20, 2025 03:21

SiiiTschiii force-pushed the SiiiTschiii/example-tcp-re-routing branch from 01cba93 to 0d6580d Compare November 20, 2025 03:43

PiotrSikora requested changes Nov 28, 2025

View reviewed changes

SiiiTschiii force-pushed the SiiiTschiii/example-tcp-re-routing branch from ec7f2b2 to 82184ae Compare November 29, 2025 01:26

SiiiTschiii changed the title ~~Add TCP rerouting example with dynamic cluster selection~~ Add TCP routing example with dynamic cluster selection Nov 29, 2025

SiiiTschiii changed the title ~~Add TCP routing example with dynamic cluster selection~~ Add Envoy TCP Routing example demonstrating source-based dynamic cluster selection Nov 29, 2025

SiiiTschiii added 15 commits November 28, 2025 16:48

Fix formatting and clippy warning in tcp_rerouting example

633ad4f

- Remove trailing whitespace - Use next_back() instead of last() for better performance Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Add TCP rerouting example to main README

94d5d0f

Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Add Apache 2.0 license headers to tcp_rerouting example files

d4bd7c3

Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Remove unnecessary statement from README

a497acb

Remove the statement about most examples focusing on HTTP, as it's not essential information for the README. Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

SiiiTschiii force-pushed the SiiiTschiii/example-tcp-re-routing branch from 0e3019b to 1745d75 Compare November 29, 2025 02:48

SiiiTschiii force-pushed the SiiiTschiii/example-tcp-re-routing branch from 5cf4bbe to 80a3c46 Compare May 13, 2026 15:06

Merge branch 'main' into SiiiTschiii/example-tcp-re-routing

40c119e

SiiiTschiii force-pushed the SiiiTschiii/example-tcp-re-routing branch 2 times, most recently from a4dcafb to d3bf4b4 Compare May 13, 2026 20:07

SiiiTschiii added 7 commits May 13, 2026 22:07

ci: stop cleaning target in envoy_tcp_routing jobs

89ce18d

Addresses: #332 (comment) Addresses: #332 (comment) Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

example(envoy_tcp_routing): refactor tcp routing flow and logging

8b3df6b

Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

docs(example/envoy_tcp_routing): align README and build metadata with…

4094003

… review nits Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Addresses: #332 (comment) Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

ci: restore rust workflow formatting

0496823

Keep only the intended removal of target cleanup in envoy_tcp_routing jobs. Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Fix network configuration for envoy-tcp-routing example

f735ce0

Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Update envoy.yaml configuration

37878af

Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

SiiiTschiii force-pushed the SiiiTschiii/example-tcp-re-routing branch from d3bf4b4 to 37878af Compare May 13, 2026 20:08

examples/envoy_tcp_routing: use latest go-httpbin image

54fdc84

Signed-off-by: Christof Gerber <christof.gerber1@gmail.com>

Merge branch 'main' into SiiiTschiii/example-tcp-re-routing

ec914d9

PiotrSikora reviewed May 20, 2026

View reviewed changes

PiotrSikora added 2 commits May 20, 2026 15:57

review: style.

1ca09bf

Signed-off-by: Piotr Sikora <code@piotrsikora.dev>

Merge remote-tracking branch 'origin/main' into SiiiTschiii/example-t…

9c9fea4

…cp-re-routing Signed-off-by: Piotr Sikora <code@piotrsikora.dev>

PiotrSikora approved these changes May 20, 2026

View reviewed changes

PiotrSikora merged commit 4ac9fb8 into proxy-wasm:main May 20, 2026
26 checks passed

SiiiTschiii deleted the SiiiTschiii/example-tcp-re-routing branch May 22, 2026 19:27

Conversation

SiiiTschiii commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Features

Implementation Details

Documentation Highlights

Uh oh!

PiotrSikora left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SiiiTschiii commented Nov 29, 2025

Uh oh!

SiiiTschiii commented Nov 29, 2025

Uh oh!

PiotrSikora commented Dec 5, 2025

Uh oh!

PiotrSikora commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SiiiTschiii commented Dec 5, 2025

Uh oh!

SiiiTschiii commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SiiiTschiii commented Feb 2, 2026

Uh oh!

PiotrSikora commented Feb 2, 2026

Uh oh!

PiotrSikora commented May 13, 2026

Uh oh!

SiiiTschiii commented May 13, 2026

Uh oh!

PiotrSikora commented May 13, 2026

Uh oh!

SiiiTschiii commented May 13, 2026

Uh oh!

SiiiTschiii commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SiiiTschiii commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

PiotrSikora left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

PiotrSikora commented May 20, 2026

Uh oh!

SiiiTschiii commented May 20, 2026

Uh oh!

PiotrSikora left a comment

Choose a reason for hiding this comment

Uh oh!

SiiiTschiii commented May 20, 2026

Uh oh!

Uh oh!

PiotrSikora commented May 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

SiiiTschiii commented Nov 20, 2025 •

edited

Loading

PiotrSikora commented Dec 5, 2025 •

edited

Loading

SiiiTschiii commented Dec 15, 2025 •

edited

Loading

SiiiTschiii commented May 20, 2026 •

edited

Loading

SiiiTschiii commented May 20, 2026 •

edited

Loading