Skip to content

vox-core: refactor SessionHandle control plane (multi-channel + unbounded) #280

@fasterthanlime

Description

@fasterthanlime

Problem

SessionHandle currently carries multiple internal control channels (open_tx, close_tx, resume_tx, control_tx) and one of them is unbounded.

Reference: rust/vox-core/src/session/mod.rs around SessionHandle fields.

Current shape is hard to reason about and feels unsafe from an API/runtime perspective:

  • 4 separate control paths for one logical handle
  • mixed bounded/unbounded semantics
  • potential for hidden queue growth and uneven backpressure behavior
  • exposes internal plumbing shape too directly in a high-level handle

Why this matters

We are exploring a simpler top-level API (vox::connect(...).client().await?) where generated clients may hold/access session internals. We should harden the control-plane shape before baking it into public ergonomics.

Proposed direction

  • Collapse control operations behind a single control mailbox (typed enum) instead of multiple channels
  • Remove unbounded control path by default; make backpressure behavior explicit
  • Keep SessionHandle as a stable facade, but hide transport/control internals behind an internal state object
  • Revisit shutdown/close semantics so they are explicit and consistent

Acceptance criteria

  • Design doc or ADR for new SessionHandle control-plane architecture
  • No unbounded channel in default session control path (or explicit documented justification if retained)
  • Consistent backpressure behavior across open/close/resume/shutdown requests
  • Existing session/virtual-connection tests remain green
  • Follow-up migration notes for upcoming connect/client/serve API simplification

Notes

This issue is intentionally scoped as architecture debt cleanup; no API break required in first pass if we can preserve current method signatures.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions