Sessions & Streams
DocsProtocol ConceptsSessions & Streams

Sessions & Streams

Understanding KSP sessions and stream multiplexing

The Kush Secure Protocol (KSP) separates communication into two logical layers: Sessions and Streams. A session represents the underlying physical and cryptographic channel established between a client and a server, while streams represent logical, independent, bidirectional pipelines multiplexed within that session.

Stream Multiplexing

Multiplexing allows multiple applications or request-response pairs to run concurrently over a single TCP connection. This solves the Head-of-Line (HoL) blocking issue at the application layer, allowing a slow request on stream A to not delay data transmission on stream B.

Stream ID Allocation Schema: +-------------------+----------------------------+ | Stream ID Value | Assignment / Owner | +-------------------+----------------------------+ | 0 | Control Frames (GoAway...) | | Odd (1, 3, 5...) | Client-initiated streams | | Even (2, 4, 6...) | Server-initiated streams | +-------------------+----------------------------+

Stream Lifecycle & State Transitions

Every stream progresses through a set of formal lifecycle states to ensure both endpoints agree on data framing limits and resource deallocation.

          [ Idle ]
             │
             ├─────────────────────────────────────────┐
             ▼ (Send StreamOpen)                       ▼ (Recv StreamOpen)
        [ Open (Local) ]                        [ Open (Remote) ]
             │                                         │
             ▼ (Send/Recv StreamData)                  ▼ (Recv/Send StreamData)
        [ Open (Active) ]                       [ Open (Active) ]
             │                                         │
             ├──────────────────────────┐              ├──────────────────────────┐
             ▼ (Send END_STREAM)        ▼ (Recv Reset) ▼ (Recv END_STREAM)        ▼ (Send Reset)
      [ Half-Closed (Local) ]       [ Closed ]   [ Half-Closed (Remote) ]     [ Closed ]
             │                                         │
             ▼ (Recv END_STREAM)                       ▼ (Send END_STREAM)
        [ Closed ]                              [ Closed ]

State Definitions:

  • IDLE: No frames have been exchanged on this Stream ID. Resources are unallocated.
  • OPEN: Initiated by sending or receiving a StreamOpen frame. Active payload data can now flow bidirectional.
  • HALF-CLOSED (local): The local endpoint sent a frame with the END_STREAM flag. It can no longer transmit data but will continue to process incoming frames.
  • HALF-CLOSED (remote): The remote endpoint sent a frame with the END_STREAM flag. The local endpoint can send data, but expects no more incoming data.
  • CLOSED: Both endpoints have sent and received END_STREAM, or a GoAway/StreamReset frame was processed. Resources are immediately freed.
Developer Implementation Note

Stream ID counters MUST never wrap around. If a client exhausts its pool of odd IDs (2^32 - 1), it must initiate a graceful shutdown via GoAway and establish a brand new cryptographic session.

NextHandshake Flow