Transport (WebSocket)
A transport turns a socket into a Connection the engine can drive and forwards inbound frames to the app. That's all it does — every protocol rule lives in the engine. mekik ships two transports: @mekik/ws for Node, Mekik.AspNetCore for ASP.NET Core. Both speak the same mekik/1 wire.
WebSocket is the reference transport in v1. The frame shapes are transport-agnostic, so SSE / Socket.IO / SignalR profiles could be added later carrying identical frames — but only WebSocket ships today.
Serving a MekikApp
- TypeScript
- .NET
import { mekik } from "@mekik/core";
import { serveWs } from "@mekik/ws";
const app = mekik({ graph });
const handle = serveWs(app, { port: 8800, path: "/ws" }); // omit `path` to accept any path
using Mekik; // Mekik.Core and Mekik.AspNetCore both live in the `Mekik` namespace
var web = WebApplication.CreateBuilder(args).Build();
web.UseWebSockets();
web.MapMekik("/ws", new MekikApp(new MekikOptions { Graph = graph }));
web.Run();
MapMekik extends IEndpointRouteBuilder, so it slots into ordinary ASP.NET Core routing alongside your other endpoints. A plain (non-WebSocket) HTTP request to that path gets 400. Same wire, same engine behind it.
Node options (@mekik/ws)
serveWs options:
interface ServeWsOptions {
port?: number; // port to listen on (ignored when `server` is supplied)
path?: string; // only accept upgrades on this path; omit to accept ANY path
server?: Server; // attach to an existing http.Server instead of creating one
}
It returns a ServeWsHandle — { server, wss, close() } — so a test or process can shut it and every live socket down:
process.on("SIGINT", () => void handle.close().then(() => process.exit(0)));
Attaching to an existing server
To share a port with your HTTP app, pass an existing http.Server:
import { createServer } from "node:http";
const server = createServer(myHttpHandler);
serveWs(app, { server, path: "/ws" });
server.listen(3000);
Omit path to accept anything
path filters which upgrade requests are accepted. Omit it and the transport accepts the upgrade on any path — useful when a client might point at /chat while you were thinking /ws. The repo's refund.ts --serve does exactly this so the demo just connects.
How identity reaches the engine
Identity can arrive two ways, and the transport merges them at connect, with the hello frame winning on conflict:
- The WS query string —
wss://host/ws?userId=u-1&conversationId=conv-9&watermark=12&token=…. Read from the upgrade request URL. This is the only channel available to something upstream of mekik (an edge proxy authenticating at the HTTP handshake), because it can't see thehelloframe. - The first
helloframe —{type:"hello", userId, conversationId, watermark, token, meta}. The richer channel; it also carriesmeta, which the query string can't. Thatmetareaches nodes asctx.meta.clientonly through youracceptClientMetaallowlist (see Concepts → Graph context).
The transport also reads an Authorization: Bearer header into the credential if no token came another way (browsers can't set WebSocket headers, but a non-browser client or a proxy can).
Each field is taken only in its declared type — non-empty strings for userId, conversationId and token, a finite number for watermark, an object for meta — and anything else is ignored as if absent. So ?watermark=abc replays the whole transcript rather than nothing, and a hello carrying userId: 42 falls back to the query string's userId, or a minted one. (Mekik.AspNetCore applies the same type checks, empty strings included, except that it takes watermark only as an integer.)
The merged result is a ConnectParams — { hello, credential } — handed to app.connect(conn, params). The credential carries the token, the raw headers (for a cookie/session authenticator), and the raw query params. See Authentication.
Ordering guarantees the transport keeps
The Node transport serializes per socket so the protocol invariants hold:
- The handshake finishes before any frame is delivered.
app.connectmust complete before the firstapp.receive, or replay would race live frames. - Frames stay in order. Inbound frames chain through a per-socket promise, so
receivecalls never overlap or reorder. - A non-
hellofirst frame (identity came via the query string) is still processed after the handshake, not dropped. - A close never overtakes the handshake. A socket that closes while
app.connectis still awaiting (a slow authenticator or store) is disconnected only once the connect has landed — otherwise the engine would register it afterwards and keep it, and its declared client tools would linger in every later turn.
Mekik.AspNetCore gets the same guarantees from its read loop: it awaits ConnectAsync, then each ReceiveAsync, one frame at a time, and calls Disconnect only for a socket whose connect ran.
These are transport responsibilities precisely because they're about the socket, not the protocol. The engine assumes ordered, post-handshake delivery; the transport provides it.
Errors and close codes
- A handler that throws surfaces as an
error{code:"internal"}frame (itsmessageis the exception's) if the socket is still open — it doesn't take the connection down silently, and the socket keeps serving later frames. Both transports behave this way. - An auth reject closes with WebSocket code 4401 (
AUTH_CLOSE_CODE/Protocol.AuthCloseCode) after theerror{unauthorized}frame, in both transports. (WS requires close codes in1000/1002–1014/3000–4999; 4401 sits in the app range.) See Authentication.
Writing another transport
Because the engine is transport-free, a new transport is small: implement Connection (send(frame), close(code?, reason?)), build a ConnectParams from whatever your transport carries, and call connect / receive / disconnect on the MekikApp. Keep the ordering guarantees above and every protocol rule comes along for free. The @mekik/ws source is under 200 lines and is the reference to copy.
Where to go next
- Authentication — the credential the transport assembles and how it's verified.
- Protocol → Identity & resume — what the merged
helloparams mean. - Engine & turn lifecycle — what the engine does with
connect/receive/disconnect.