Documentation / @super-line/server / PluginConnection

Interface: PluginConnection

Defined in: index.ts:376

A plugin-owned connection class (ADR-0005 phase 2): a reserved role the transport negotiates (never one of the user contract's roles), dispatched against the plugin's own fixed contract — never merged into the user's. Matching conns are observer-invisible (excluded from conns/presence/heartbeat/user hooks). The inspector's Control-Center channel is one such class.

Properties

authenticate?

optional authenticate?: (handshake) => unknown

Defined in: index.ts:393

Authorize admission to this class (ADR-0022). The host's authenticate resolves CONTRACT roles and never sees a reserved connection, so the declaring plugin decides instead. Called by the transport BEFORE accepting: the resolved value becomes conn.ctx, and a throw rejects (the WS transport closes 4401 with the message, without ever surfacing the connection to the core). Omit to admit unconditionally — which is the pre-ADR-0022 behaviour, still the default.

It does not return a role: the role is fixed here at declaration, so a class cannot name a host role and mint a connection the host never authenticated.

Parameters

handshake

Handshake

Returns

unknown

---

contract

contract: Contract

Defined in: index.ts:395

The parallel contract these connections speak (its clientToServer = requests, subscribe topics = feeds).

---

handlers?

optional handlers?: (ctx) => Record<string, (input, conn) => Awaitable<unknown>>

Defined in: index.ts:400

Request handlers for contract's clientToServer, built with the PluginContext. A subscribe to one of contract's topics bridges the conn to the plugin's PluginChannel of the same name.

Parameters

ctx

PluginContext

Returns

Record<string, (input, conn) => Awaitable<unknown>>

---

match?

optional match?: (handshake) => boolean

Defined in: index.ts:382

Predicate for transports without a subprotocol (SSE/libp2p): match on the normalized handshake.

Parameters

handshake

Handshake

Returns

boolean

---

role

role: string

Defined in: index.ts:378

The reserved role; must be unique across the server (user roles + other reserved classes).

---

subprotocol?

optional subprotocol?: string

Defined in: index.ts:380

WebSocket subprotocol to advertise + match (browsers set this where they can't set headers).