Skip to content

docs(00894): sharpen What/Why for application-managed WebSocket sessions #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
shaneutt wants to merge 1 commit into from
Closed

docs(00894): sharpen What/Why for application-managed WebSocket sessions #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 29 additions & 8 deletions proposals/00894_application-managed-websocket-sessions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,22 +93,35 @@ lifecycle; extensions own application semantics.
modify messages or initiate independent upstream work.
- Acting as a general-purpose forward proxy or TLS interception
proxy.
- Reviving generic per-frame WebSocket filter hooks on every
connection. That shape was closed as not planned in
praxis-proxy/praxis#44 and was an explicit non-goal in
praxis-proxy/ai#439. This capability is opt-in, message-level session
ownership for routes that terminate in Praxis, not a frame-level hook
applied to all upgraded traffic.

### Required Capabilities

**Explicit session selection**

Application management is selected by trusted configuration and
request processing before the upgrade completes. An arbitrary
client-supplied header cannot activate an application handler or
choose its protected configuration.
Application management is selected by operator-authored, server-side
configuration, evaluated during request processing before the upgrade
completes. Praxis has no notion of client-supplied trust, so an

@praxis-bot praxis-bot Aug 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Medium] "Praxis has no notion of client-supplied trust" is overly broad. Praxis does verify and trust client-supplied credentials (bearer tokens, mTLS certificates) for authentication and authorization. The narrower claim -- that handler/session selection is never client-triggered -- is correct and already stated in the next clause. Replace with a scoped formulation, e.g.:

Handler selection is not derived from client-supplied input, so an arbitrary client header can never activate an application handler or choose its protected configuration.

arbitrary client header can never activate an application handler or
choose its protected configuration. Whether an application must
additionally declare a capability to terminate a WebSocket, in the
spirit of existing filter security classification, is an open question
for the How? iteration.

**Framework-owned WebSocket transport**

Praxis performs the downstream handshake and owns protocol correctness
for the resulting connection. Extensions interact with bounded
message-level primitives rather than client masking, frame fragments,
or raw upgraded-body chunks.
or raw upgraded-body chunks. Negotiated extensions are declined by
default; permessage-deflate and similar are enabled only where a route
requires them, because decoding them adds an amplification surface that
the transparent tunnel never exposed.

**Asynchronous bidirectional execution**

Expand Down Expand Up @@ -185,11 +198,19 @@ Responses API provides a compatible native WebSocket upstream, so a
Praxis AI application can mediate WebSocket messages while retaining
the upstream protocol and streaming behavior. OpenAI documents this
transport at `wss://api.openai.com/v1/responses`, with repeated
`response.create` events on one connection.
`response.create` events on one connection. That upstream serves one
in-flight response at a time, bounds connection lifetime, and keeps
incremental continuation bound to the connection, so the framework must
own session lifecycle, resource limits, and upstream reconnection

@praxis-bot praxis-bot Aug 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Medium] This sentence introduces "upstream reconnection beneath a longer-lived downstream session" as a framework responsibility, but neither the Goals nor the Required Capabilities sections capture it. If a downstream WebSocket session can outlive a bounded upstream connection (as described here for OpenAI), transparent upstream reconnection is a distinct capability the framework must provide. Add a goal or required capability for session continuity across upstream disconnects so the How? iteration inherits the requirement explicitly.

beneath a longer-lived downstream session rather than leaving them to
each extension.

vLLM provides the Responses API over HTTP, returning JSON or
server-sent events for streaming responses. It does not need to expose
the same WebSocket transport for Praxis to serve the Codex client. A
server-sent events for streaming responses, and it does not thread

@praxis-bot praxis-bot Aug 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Medium] "thread" is heavily overloaded in a systems/proxy context (OS threads, HTTP/2 stream multiplexing, connection threading). Here it means "link prior conversational turns together," but a reader scanning quickly will likely parse it as execution threading. Use an unambiguous verb: e.g. "it does not retain prior turns server-side" or "it does not chain prior turns server-side."

prior turns server-side, so an application targeting vLLM must
reconstruct the context that Codex would otherwise reference with
`previous_response_id`. It does not need to expose the same WebSocket
transport for Praxis to serve the Codex client. A
Praxis AI application should be able to accept the downstream
WebSocket, hydrate and validate each logical Responses request, invoke
vLLM over HTTP/SSE, and emit the resulting Responses events as
Expand Down