Documentation / @super-line/server / Conn

Class: Conn<Ev, Ctx, Role, Data, Env>

Defined in: conn.ts:15

A single client connection, passed to handlers as the third argument.

Node-local: conn objects live on the node that accepted the connection, so don't stash one to reach a user later — cross-node delivery goes through the Adapter (use a per-user room instead). Generic over the events it may emit (scoped by role), its ctx, and its role.

Type Parameters

Ev

Ev = Record<string, ServerMessageDef>

Ctx

Ctx = unknown

Role

Role extends string = string

Data

Data = unknown

Env

Env = unknown

Constructors

Constructor

new Conn<Ev, Ctx, Role, Data, Env>(raw, id, role, ctx, serializer, onEmit?, envSchema?, onSetEnv?): Conn<Ev, Ctx, Role, Data, Env>

Defined in: conn.ts:54

Parameters

raw

RawConn

The underlying transport connection. conn.terminate() simulates a drop in tests.

id

string

Server-assigned unique id for this connection (stable for its lifetime).

role

Role

This connection's role (the literal resolved by authenticate).

ctx

Ctx

The context authenticate returned for this connection.

serializer

Serializer

onEmit?

(event, data) => void

Optional inspector tap: called with each emit so the server can mirror it to inspectors.

envSchema?

Schema

The role's env schema (ADR-0012); Conn.setEnv validates against it. Absent ⇒ no validation.

onSetEnv?

(env) => void

Optional inspector tap for env.set (called with the new env on every Conn.setEnv).

Returns

Conn<Ev, Ctx, Role, Data, Env>

Properties

channels

readonly channels: Set<string>

Defined in: conn.ts:23

Namespaced channels (rooms + topics) this connection belongs to.

---

connectedAt

readonly connectedAt: number

Defined in: conn.ts:46

When this connection was accepted (Date.now()).

---

ctx

readonly ctx: Ctx

Defined in: conn.ts:62

The context authenticate returned for this connection.

---

data

data: Data

Defined in: conn.ts:25

Mutable per-connection scratch state, typed per role by the contract's data schema.

---

env

env: Env

Defined in: conn.ts:33

Server-vended, CLIENT-VISIBLE per-connection state, typed per role by the contract's env schema (ADR-0012). Seeded at connect (from authenticate's env), mutated via Conn.setEnv, and mirrored to the client as client.env. null when the role declares no env. Holds live external credentials — never written to the cluster presence directory. A transport that keeps connection snapshots (ADR-0027) does store it, server-side, so a resumed connection keeps its env.

---

id

readonly id: string

Defined in: conn.ts:58

Server-assigned unique id for this connection (stable for its lifetime).

---

lastPingAt?

optional lastPingAt?: number

Defined in: conn.ts:48

When the server last sent a heartbeat ping to this connection (managed by the server).

---

lastPongAt?

optional lastPongAt?: number

Defined in: conn.ts:50

When a heartbeat pong was last received — liveness signal (managed by the server).

---

missedPongs

missedPongs: number = 0

Defined in: conn.ts:52

Pings sent since the last pong; drives reaping (managed by the server).

---

principal?

optional principal?: string

Defined in: conn.ts:37

ACL identity for stores: identify(conn) ?? conn.id, set by the server at accept (always defined there).

---

raw

readonly raw: RawConn

Defined in: conn.ts:56

The underlying transport connection. conn.terminate() simulates a drop in tests.

---

registered?

optional registered?: Promise<void>

Defined in: conn.ts:43

Resolves once this connection's descriptor has been written to the cluster presence directory (set by the server at accept). Presence mutations — a room join or leave — chain on it, because they read-modify-write that descriptor and silently do nothing when it is not there yet.

---

role

readonly role: Role

Defined in: conn.ts:60

This connection's role (the literal resolved by authenticate).

---

transport?

optional transport?: string

Defined in: conn.ts:35

The client↔server transport (wire) this connection was accepted on (set by the server at accept).

Methods

close()

close(): void

Defined in: conn.ts:105

Graceful close of the underlying transport connection.

Returns

void

---

emit()

emit<E>(event, data): void

Defined in: conn.ts:99

Push an event to THIS connection (node-local). Scoped to the role's events.

Type Parameters

E

E extends string | number | symbol

Parameters

event

E

data

EmitData<Ev[E]>

Returns

void

---

send()

send(frame): void

Defined in: conn.ts:86

Encode and send a frame (unicast, e.g. req/res).

Parameters

frame

ServerFrame

Returns

void

---

sendRaw()

sendRaw(payload): void

Defined in: conn.ts:93

Forward an already-encoded frame (fan-out path; encoded once at the source).

Parameters

payload

string | Uint8Array<ArrayBufferLike>

Returns

void

---

setEnv()

setEnv(value): void

Defined in: conn.ts:78

Vend (or update) this connection's client-visible Conn.env (ADR-0012). Validates a non-null value against the role's env schema, stores it, and pushes the full value to the client as an env frame (last-write-wins). null clears it (no validation). Node-local — for a user's connections on other nodes use srv.toUser(id).setEnv(...).

Parameters

value

Env

Returns

void

---

terminate()

terminate(): void

Defined in: conn.ts:110

Hard close with no handshake — used by heartbeat reaping.

Returns

void