http: sticky echo headers + Fly.io quickstart helpers

[rustyconover]

Summary

• PR 2 of 3 in the sticky-sessions series. Stacked on http: opt-in sticky sessions (HTTP-only, header transport, DELETE endpoint) #9 (sticky core); base is sticky-sessions-core so it'll cleanly rebase onto main once http: opt-in sticky sessions (HTTP-only, header transport, DELETE endpoint) #9 merges.
• New server config sticky_echo_headers={name: value} on make_wsgi_app tells the client to echo arbitrary headers on every subsequent request in the session. Used for client-driven routing on platforms like Fly.io.
• New vgi_rpc/http/fly.py (~25 lines): auto_server_id() + fly_sticky_echo_headers() — Fly.io quickstart helpers. Two-line setup, zero LB config.
• Capability header VGI-Sticky-Echo-Headers advertises the configured names; HttpServerCapabilities.sticky_echo_headers: tuple[str, ...] surfaces them.
• New canonical conformance test TestSticky::test_echo_header_round_trip (capability-gated on VGI-Sticky-Echo-Headers so deployments without echo support skip cleanly).

Wire contract

Server side: when sticky_echo_headers={"fly-force-instance-id": \"abc\"} is configured, every session-opening response carries VGI-Echo-fly-force-instance-id: abc. Emitted once only — subsequent responses MUST NOT re-emit. Capability header VGI-Sticky-Echo-Headers: fly-force-instance-id advertises the contract.

Client side: with_session_token() view's _SessionTrackingClient captures every VGI-Echo-<name> response header (case-insensitive, prefix-stripped) and replays the inner header on every subsequent request in the same block. Captured map exposed via sess.current_echo_headers(); cleared on VGI-Session-Close: true.

Caller-supplied request headers take precedence: _merge_headers uses setdefault, so passing an explicit per-call header overrides the captured echo header for that one request.

Fly quickstart

from vgi_rpc import RpcServer
from vgi_rpc.http import make_wsgi_app
from vgi_rpc.http.fly import auto_server_id, fly_sticky_echo_headers

server = RpcServer(MyService, MyServiceImpl(), server_id=auto_server_id())
app = make_wsgi_app(
    server,
    enable_sticky=True,
    sticky_echo_headers=fly_sticky_echo_headers(),
)

Off Fly both helpers return None so the same code is a no-op — no conditional branches.

Test plan

• uv run ruff format .
• uv run ruff check . → clean
• uv run mypy vgi_rpc/ → clean
• uv run ty check vgi_rpc/ → clean (pre-existing pyarrow note only)
• uv run pytest --timeout=50 → 3316 passed, 0 failed in ~82s
• All 10 canonical TestSticky tests pass (was 9 in PR1; +1 echo round-trip)
• All 26 Python-only sticky tests pass (was 16; +10 for echo + Fly helper)
• Stateless conformance + non-sticky wire path still byte-identical

What's next

• PR 3: graceful drain (RpcServer.drain() + SIGTERM handler + drain_grace_seconds + access-log session_id/session_action fields). Independent of this PR.

🤖 Generated with Claude Code

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}