Skip to content

Support HTTP/2 on sandbox application routes #5828

Description

@shiju-nv

User Story

I use OpenShell on Kubernetes to run an agent service. I need an HTTP/2 application route so a native gRPC client can call the server inside the sandbox.

Problem Statement

openshell service expose registers HTTP services, including services that use WebSocket upgrades. In OpenShell v0.1.9, the supervisor application listener uses HTTP/1.1 on both the client and loopback hops. Clients cannot negotiate HTTP/2 on this route, which blocks services that require it.

Impact / Why This Matters

In my Kubernetes deployment, an adapter outside the sandbox receives gRPC calls and forwards them to the agent service over HTTPS. This adds a deployment to operate and an application-specific HTTP interface to maintain.

HTTP/2 also enables bidirectional streaming with Connect RPC. Browser dashboards, REST APIs, webhooks, and MCP servers using Streamable HTTP can already use HTTP/1.1. With HTTP/2, a client can keep a server-sent events (SSE) stream open while making other requests over the same connection.

Proposed Design

When the supervisor application listener is enabled, offer h2 and http/1.1 by default through TLS ALPN. HTTPS clients can negotiate HTTP/2 with existing service declarations. The supervisor forwards ordinary HTTP requests to their HTTP/1.1 backends. WebSocket upgrades use HTTP/1.1.

Let operators set the backend HTTP version for services that require HTTP/2 at their sandbox port. The flag applies to the supervisor-to-sandbox connection. For example:

openshell service expose demo 50051 agent --backend-http-version 2

Version 2 uses cleartext HTTP/2 with prior knowledge on the loopback hop. The explicit setting lets the supervisor select the HTTP version before forwarding any request, since that hop has no TLS negotiation. The backend defaults to HTTP/1.1. If the configured version and the server disagree, fail the request without replaying it. When an ingress proxy terminates TLS, it must use HTTP/2 to the supervisor for services that require HTTP/2 on both hops.

On routes using HTTP/2 on both hops, preserve bidirectional streaming, trailers, and per-stream cancellation. Native gRPC uses this route with its deadline metadata and status trailers. Apply the existing route ownership, expiry, discovery access, and authorization-header rules. The application or ingress edge authenticates callers as configured. Check each HTTP/2 request's authority against the TLS server name and the installed route.

Acceptance Criteria

  • With the application listener enabled, a standard HTTPS client negotiates HTTP/2 and reaches an existing HTTP/1.1 sandbox service without changing its declaration. HTTP/1.1 requests and WebSocket upgrades work on the same listener.
  • A service declared with backend HTTP version 2 handles ordinary HTTP/2 requests. With that same setting, a native gRPC service supports unary and bidirectional streaming calls at its service hostname. The client receives status trailers, and the backend receives deadline metadata and observes stream cancellation while other streams can continue.
  • A backend protocol mismatch fails the request without replaying it.
  • Requests with a mismatched authority or an undeclared or expired route are rejected before reaching a sandbox port. Withdrawing a route removes it from discovery and closes its active connections under the existing rules.
  • HTTP/2 routes enforce the same authorization-header behavior and discovery access as existing service routes.

Alternatives Considered

The HTTPS adapter works for the current calls and adds a bridge to operate.

TLS passthrough to the sandbox would let the client and sandbox server negotiate the HTTP version directly. The supervisor could select a route by TLS server name, and the sandbox would terminate TLS. Request authority and headers would be encrypted from the supervisor's point of view, so the sandbox or another HTTP proxy would need to enforce the existing per-request rules. The proposed HTTP reverse proxy keeps those checks at the supervisor. HTTP intermediaries · Sandbox service routing and policy

service expose already implies HTTP, so --protocol http would repeat the service family. A gRPC service type would describe one application protocol. The backend HTTP version is shared by ordinary HTTP/2, Connect RPC, and gRPC services.

An HTTPS backend could negotiate its HTTP version using TLS ALPN if OpenShell added backend TLS and certificate validation. Probing the current cleartext backend would add a connection attempt on fallback and could confuse a timeout with a protocol mismatch. The explicit version gives the supervisor the information it needs to open the cleartext connection. HTTP/2 startup and negotiation

Agent Investigation

No response

Checklist

  • I've reviewed existing issues and the published docs
  • This is a design proposal, not a "please build this" request

Activity

  1. added theissue type on Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions