@polyweave/session (1.0.7)
Installation
@polyweave:registry=https://hub.kl1.tenere.ai/api/packages/Polyweave/npm/npm install @polyweave/session@1.0.7"@polyweave/session": "1.0.7"About this package
@polyweave/session
Session management wrapper — auto-creates sessions, stamps sessionId on frames, tracks stream-to-session mappings, and integrates with durability for crash recovery.
Synopsis
import { createSessionManager, createSessionControlFrame } from '@polyweave/session';
const sessionManager = createSessionManager(innerDuplex, {
maxSessions: 1000,
sessionTTL: 3600000,
onSessionCreate: (session) => console.log('new session:', session.sessionId)
});
innerDuplex.sink.write({ type: 'TEXT', content: { text: 'Hello' } });
// Frame is transparently stamped with metadata.sessionId before reaching innerDuplex
sessionManager.sessionStore.destroy();
Install
npm install @polyweave/session
Why
Every frame flowing through a Polyweave pipeline needs a sessionId for cost tracking, durability, and session-scoped state. Manually stamping every frame is error-prone. createSessionManager is a bidirectional wrapper that transparently assigns and maintains session identity on every request frame, auto-creates sessions on first contact, and maps stream IDs to sessions so that START...END frame sequences stay in the same session. It also supports explicit session control via META frames and integrates with the durability subsystem for crash recovery.
API
createSessionManager(innerDuplex, options)
Creates a bidirectional wrapper around innerDuplex that stamps sessionId on all request frames, auto-creates session stores, and manages stream-to-session mapping.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
innerDuplex |
IFrameDuplex |
yes | — | The duplex to wrap. Must have .sink and .source. |
options.maxSessions |
number |
no | 1000 |
Maximum concurrent sessions. |
options.sessionTTL |
number |
no | 3600000 |
Session TTL in milliseconds (1 hour). |
options.getSessionId |
function(frame): string |
no | undefined |
Custom function to extract sessionId from a frame. If not provided, the wrapper checks frame.metadata.sessionId. |
options.onSessionCreate |
function(session) |
no | undefined |
Callback invoked when a new session is created. Receives the session object. Errors caught and logged. |
options.onSessionExpire |
function(sessionId) |
no | undefined |
Callback invoked when a session is explicitly deleted. |
options.durability |
object |
no | {} |
Durability configuration. |
options.durability.enabled |
boolean |
no | false |
Enable durability META message passthrough. |
options.durability.wrapperId |
string |
no | undefined |
Unique wrapper ID to identify this instance in durability restore META messages. |
options.name |
string |
no | null |
Name passed to the bidirectional wrapper. |
Returns: { sink, source, sessionStore, destroy }
| Field | Type | Description |
|---|---|---|
sink |
IFrameSink |
Split sink that routes frames to both the wrapper and the session store. |
source |
IFrameSource |
Joined source that merges wrapper output with session store META emissions. |
sessionStore |
object |
The internal session store instance. Exposes createSession, getSession, hasSession, deleteSession, restoreState, destroy, and source/sink for META passthrough. |
destroy |
function() |
Cleans up the session store. |
Frame Protocol
The wrapper intercepts the following META frame types:
| Frame Type | Content | Action |
|---|---|---|
META |
{ durability: { restoreState, wrapperId, state } } |
Restores the session store state from a durability snapshot if wrapperId matches. Frame is consumed (not forwarded). |
META |
{ session: { create: true, sessionId?, metadata? } } |
Explicitly creates a session. Frame is consumed. |
META |
{ session: { delete: true, sessionId } } |
Explicitly deletes a session. Frame is consumed. |
META |
{ session: { create: true } } |
Creates a new session without a predefined ID. Frame is consumed. |
On request path (non-META frames): the wrapper calls ensureSession(frame) which:
- Tries
getSessionIdcallback if provided. - Falls back to
frame.metadata.sessionId. - Checks stream-to-session mapping via
frame.streamId || frame.id. - If an existing session is found, touches it (updates
lastAccess). - Otherwise creates a new session.
- Returns a new frame with
metadata.sessionIdstamped.
On response path: the wrapper cleans up streamId from stream-to-session mapping on END frames. All other frames pass through unchanged.
Session Lifecycle
- Creation: Auto-created on first request frame without a recognized
sessionId. - Active: Last access timestamp updated on every frame.
- Expiry: Managed by the internal session store's TTL.
- Deletion: Explicit via control META frame or
sessionStore.deleteSession(). - Recovery: Restored from durability META frame on crash recovery.
Error conditions:
- No explicit throw conditions. Errors in
onSessionCreateare caught and logged toconsole.error. Errors inonSessionExpireare not caught (callbacks are fire-and-forget after deletion).
createSessionControlFrame(control)
Creates a META frame for explicit session control.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
control.create |
boolean |
no | undefined |
If true, create a new session. |
control.delete |
boolean |
no | undefined |
If true, delete the specified session. |
control.sessionId |
string |
no | undefined |
Target session ID for create or delete. |
control.metadata |
object |
no | undefined |
Metadata for session creation. |
Returns: { type: 'META', content: { session: control }, metadata: {} } — A META frame that, when written to a session manager's sink, triggers the corresponding session operation.
Error conditions: None. This is a pure data constructor.
Tests
npm test
Runs node --test test/rigor.test.js test/sessionManager.test.js. Covers session creation, sessionId stamping, session control META frames, stream-to-session mapping, and durability restore.
Requirements
Node.js 22 or later. ESM only.
Peer dependencies: @polyweave/core — for createBidirectionalWrapper, createSessionStore, createJoinSource, createSplitSink, and FrameType.
Dependencies
Development Dependencies
| ID | Version |
|---|---|
| @rigor/core | * |
Peer Dependencies
| ID | Version |
|---|---|
| @polyweave/core | * |
| @polyweave/errors | * |