Mixed-Protocol Blueprints

A Lane7 Blueprint does not have to use a single protocol across all pods. Individual pods can override the network-level protocol, allowing HTTP, WebSocket, and gRPC pods to coexist in the same application network — each leg carrying exactly the communication pattern it needs.

The Armored Carrier — Zero Trust AI Pipeline is the catalog example: boundary and orchestration pods use HTTP while the LLM inference and tool execution legs use WebSocket for persistent, low-latency sessions.

---

How protocol mixing works

The network-level protocol: field sets the default for all pods. Any pod can declare its own protocol: to override it:

network:
  id: my-mixed-network
  protocol: http          # network default

pods:
  - id: gateway
    template: http-gateway     # effective protocol: http (inherits default)

  - id: llm-gateway
    template: llm-gateway
    protocol: websocket        # override: this pod uses WebSocket

  - id: tool-executor
    template: tool-executor
    protocol: websocket        # override: this pod uses WebSocket

  - id: sink
    template: http-sink        # effective protocol: http (inherits default)

The compose tool records the effective_protocol for each pod in blueprint.yaml and in the generated README pod map, so the protocol of every leg is always visible.

---

HTTP + WebSocket mixing

This is the most common mixed-protocol pattern. Use it when some pods need persistent, full-duplex connections (streaming inference, real-time tool feedback) while boundary and aggregation pods use standard HTTP request/response.

xtra4 (Armored Tunnel) handles HTTP and WebSocket identically at L4 — the WASM filter operates on raw TCP byte streams before any protocol framing is parsed. Both sides of a cross-protocol connection are protected by AMTD session-level key rotation without any special configuration.

The compose tool emits a W15 informational warning on cross-protocol connections. This is not an error — it is confirmation that the mixed wiring is intentional and has been processed correctly.

W15 [Protocol] Connection ai-orchestrator → llm-gateway crosses protocol families
    (http → websocket). Non-fatal: xtra4.wasm applies AMTD at L4 for both sides.

xtra4 required

Mixed-protocol blueprints must use Armored Tunnel (wasm_filter: xtra4). Armored Car (xtra7) is an HTTP-layer filter and cannot protect WebSocket or gRPC connections. The validator blocks xtra7 on any topology with non-HTTP pods (error E20).

AI Pipeline example

flowchart TD
    A["AI Gateway\n(http-gateway)\nHTTP"]
    B["AI Orchestrator\n(ai-orchestrator)\nHTTP"]
    C["LLM Gateway\n(llm-gateway)\nWebSocket"]
    D["Tool Executor\n(tool-executor)\nWebSocket"]
    E["NLP Processor\n(nlp-processor)\nHTTP"]
    F["AI Results Sink\n(http-sink)\nHTTP"]
    A -->|"HTTP / WoSP xtra4"| B
    B -->|"HTTP / WoSP xtra4"| C
    B -->|"HTTP / WoSP xtra4"| D
    C -->|"WebSocket / WoSP xtra4"| E
    D -->|"WebSocket / WoSP xtra4"| E
    E -->|"HTTP / WoSP xtra4"| F

The WebSocket legs give llm-gateway and tool-executor the persistent sessions they need for streaming LLM responses and real-time tool feedback. The boundary pods (ai-gateway, ai-results-sink) and the aggregation pod (nlp-processor) use HTTP. xtra4 applies AMTD key rotation uniformly across all six legs.

---

HTTP + gRPC bridging

HTTP↔gRPC mixing requires a different approach. xtra4 tunnels raw TCP bytes — it does not translate between HTTP/1.1 and gRPC/HTTP2 framing. A direct connection from an http-* pod to a grpc-* pod would fail at the application layer even though WoSP authenticated it. The validator blocks this with error E21.

The solution is a pair of bridge templates that perform protocol translation in the application layer:

Template	Role	Used As
http-grpc-gateway	HTTP ingress (port 8000) + gRPC BidiStream egress	Boundary entry pod
grpc-http-sink	gRPC BidiStream ingress (port 50051) + HTTP /output egress	Boundary exit pod

These templates handle the HTTP↔gRPC translation in app.py. From xtra4's perspective they are ordinary pods — it sees raw gRPC bytes on the egress side and raw HTTP bytes on the ingress side, both tunnelled correctly.

flowchart TD
    subgraph "External Caller"
        EXT["HTTP Client"]
    end
    subgraph "Blueprint"
        A["http-grpc-gateway\n(bridge entry)\nHTTP in / gRPC out"]
        B["grpc-relay\n(gRPC)"]
        C["grpc-http-sink\n(bridge exit)\ngRPC in / HTTP out"]
    end
    EXT -->|"HTTP POST /trigger"| A
    A -->|"gRPC BidiStream / WoSP xtra4"| B
    B -->|"gRPC BidiStream / WoSP xtra4"| C
    C -->|"HTTP GET /output"| EXT

Connections at bridge boundaries are exempt from E21 — the validator recognises http-grpc-gateway and grpc-http-sink as intentional translation points.

gRPC-only legs require care

Inside the bridge, all pods must use the gRPC family (grpc-relay, grpc-sink, etc.). Do not connect http-* templates directly to grpc-* templates — use a bridge template at the boundary.

---

Choosing the right pattern

You need...	Pattern
HTTP boundary + WebSocket streaming legs (e.g., LLM inference)	HTTP + WebSocket mixing via per-pod protocol: websocket override
External HTTP callers + internal gRPC mesh	HTTP↔gRPC bridging via http-grpc-gateway + grpc-http-sink
Uniform protocol throughout	Single-protocol blueprint (no override needed)

All mixed-protocol blueprints require wasm_filter: xtra4. Contact lane7@hopr.co to request a custom mixed-protocol blueprint topology.