Session¶
Spec table of contents · Next: 01. STREAM Server Session
One external client connection enters the server and is joined to an Actor, then goes through replacement, disconnection, and relocation until it closes — this topic covers that one connection's lifecycle and the path leading to the Actor.
1. Session Overview¶
The application doesn't read the STREAM connection directly. When a client connects, the framework builds one STREAM session and hands packets to the session callback. The application decides the domain identity in this callback and finds or creates an Actor to bind to the session. Once bind finishes, the session relays payload to that Actor, and returns the reply or push the Actor sends back over the same connection. Even if the Actor moves to a different MeshNode, the connection isn't dropped — only the route is refreshed — and when the connection drops, the Spot the Actor belongs to is notified.
2. Who Decides What¶
| Party | Decides/owns |
|---|---|
| Application | Decides the domain identity in the session callback and binds ActorRef. Doesn't directly build a route or a global proxy between sessions. |
| Framework (session owner) | Handles header framing and queue admission, retains the binding token, route, and generation, and performs route switches during relay, rebind, disconnect, and relocation. |
| Actor owner | Validates bind/rebind requests, registers the binding generation, and keeps exactly one current binding. |
| Relocation runtime | Chooses the target for Actor/Spot moves, decides readiness, and accesses the Location Store — the store holding each Spot's current owner and state. Only requests seal installation and route application from the session owner. |
| Core | Handles the actual STREAM transport send/receive and the receive pipe HWM. |
3. Seeing One Flow¶
%%{init: {'sequence': {'actorFontSize': '18px', 'messageFontSize': '18px', 'noteFontSize': '18px', 'boxMargin': 8, 'width': 140}, 'themeVariables': {'fontSize': '18px'}}}%%
sequenceDiagram
participant Client
participant SO as Session owner
participant AO as Actor owner
participant AQ as Actor queue
Client->>SO: accept STREAM connection
SO->>SO: run session callback
SO->>AO: bind request
AO-->>SO: return bind terminal
Client->>SO: send business packet
SO->>AO: relay with binding generation
AO->>AQ: submit Actor message
AO-->>SO: reply or push
SO-->>Client: deliver response
Client-xSO: connection ends
SO->>AO: disconnect notificationThis diagram shows only one normal path. Rebind, where a new connection attaches to the same Actor, is defined by Session And Actor Binding "6. Rebind And Replacing The Previous Connection", relocation, where the Actor moves to a different node, is defined by Session And Actor Binding "8. The Session's Responsibility During Actor Relocation", and failures at each step are defined by the sections that §5 points to.
4. Documents in This Topic¶
| Document | Covers | Layer |
|---|---|---|
| STREAM Server Session | Accepting one connection, registration, packet framing, and the codec and error boundaries — the contract the application observes | Contract |
| Session And Actor Binding | The bind/relay/rebind/disconnect/relocation contract connecting a session to an Actor, and the execution-structure decisions every language runtime follows so the result is the same everywhere | Contract + implementation spec (decisions every language runtime follows) |
5. Find by Question¶
6. Reading Order¶
A developer reading this for the first time
- Read §1–§3 of this document to get the whole picture.
- Read STREAM Server Session "1. STREAM Session Overview" · "2. Roles And Responsibilities" · "4. From Connection Accept To The Session Callback" to follow a connection's path to the callback.
- Read Session And Actor Binding "1. Session–Actor Binding Overview" · "2. Roles And Responsibilities" · "5. Bind And Relay" to follow the path leading to the Actor.
A developer porting to a new language — the following sections hold the rules and verification requirements that every runtime must follow in the same structure, so read them before implementing a language runtime. Wherever languages may differ, the body marks such differences only as Language-specific discretion.
- STREAM Server Session "2. Roles And Responsibilities" (recv mode), "4. From Connection Accept To The Session Callback" (managed queue), "10. Verification Requirements"
- Session And Actor Binding "2. Roles And Responsibilities" (validation boundary), "5. Bind And Relay" (execution-authority separation, control records), "6. Rebind And Replacing The Previous Connection" (rebind), "8. The Session's Responsibility During Actor Relocation" · "8.1 Seal, Held Messages, And Route Switchover" (seal), "11. Execution Engine And Lane Policy Types", "14. Verification Requirements"
An application developer
- Read STREAM Server Session "1. STREAM Session Overview" through "3. Registration And Startup Validation" to learn how to register a session and receive packets.
- Read Session And Actor Binding "1. Session–Actor Binding Overview" · "4. What Binding Connects And What It Stores" · "13. Public Interface Excerpt" for the public interface to bind and relay to an Actor.
- Read Session And Actor Binding "9. Distinguishing Reconnection From Relocation" to confirm the difference between reconnection and relocation.
7. What This Topic Does Not Define¶
| Content | Owning document |
|---|---|
| The client-side connector contract | Stream Connector Common Spec |
| The relocation source/target procedure | Complete Actor And Spot Relocation Flow |
| The Actor model and its queue | Actor Model |
| Shared permits and the byte HWM | Application Job Queue And Backpressure |
| Error kind definitions | Framework Error Model |