@replit/river 0.11.0 → 0.12.0

package/dist/transport/impls/ws/server.cjs

@@ -24,52 +24,6 @@ __export(server_exports, {
 });
 module.exports = __toCommonJS(server_exports);
 
-// codec/json.ts
-var encoder = new TextEncoder();
-var decoder = new TextDecoder();
-function uint8ArrayToBase64(uint8Array) {
-  let binary = "";
-  uint8Array.forEach((byte) => {
-    binary += String.fromCharCode(byte);
-  });
-  return btoa(binary);
-}
-function base64ToUint8Array(base64) {
-  const binaryString = atob(base64);
-  const uint8Array = new Uint8Array(binaryString.length);
-  for (let i = 0; i < binaryString.length; i++) {
-    uint8Array[i] = binaryString.charCodeAt(i);
-  }
-  return uint8Array;
-}
-var NaiveJsonCodec = {
-  toBuffer: (obj) => {
-    return encoder.encode(
-      JSON.stringify(obj, function replacer(key) {
-        let val = this[key];
-        if (val instanceof Uint8Array) {
-          return { $t: uint8ArrayToBase64(val) };
-        } else {
-          return val;
-        }
-      })
-    );
-  },
-  fromBuffer: (buff) => {
-    try {
-      return JSON.parse(decoder.decode(buff), function reviver(_key, val) {
-        if (val?.$t) {
-          return base64ToUint8Array(val.$t);
-        } else {
-          return val;
-        }
-      });
-    } catch {
-      return null;
-    }
-  }
-};
-
 // logging/index.ts
 var log;
 
@@ -83,31 +37,69 @@ var TransportMessageSchema = (t) => import_typebox.Type.Object({
   id: import_typebox.Type.String(),
   from: import_typebox.Type.String(),
   to: import_typebox.Type.String(),
+  seq: import_typebox.Type.Integer(),
+  ack: import_typebox.Type.Integer(),
   serviceName: import_typebox.Type.Optional(import_typebox.Type.Union([import_typebox.Type.String(), import_typebox.Type.Null()])),
   procedureName: import_typebox.Type.Optional(import_typebox.Type.Union([import_typebox.Type.String(), import_typebox.Type.Null()])),
   streamId: import_typebox.Type.String(),
   controlFlags: import_typebox.Type.Integer(),
   payload: t
 });
-var TransportAckSchema = TransportMessageSchema(
-  import_typebox.Type.Object({
-    ack: import_typebox.Type.String()
-  })
-);
-var ControlMessagePayloadSchema = import_typebox.Type.Object({
+var ControlMessageAckSchema = import_typebox.Type.Object({
+  type: import_typebox.Type.Literal("ACK")
+});
+var ControlMessageCloseSchema = import_typebox.Type.Object({
   type: import_typebox.Type.Literal("CLOSE")
 });
+var PROTOCOL_VERSION = "v1";
+var ControlMessageHandshakeRequestSchema = import_typebox.Type.Object({
+  type: import_typebox.Type.Literal("HANDSHAKE_REQ"),
+  protocolVersion: import_typebox.Type.Literal(PROTOCOL_VERSION)
+});
+var ControlMessageHandshakeResponseSchema = import_typebox.Type.Object({
+  type: import_typebox.Type.Literal("HANDSHAKE_RESP"),
+  status: import_typebox.Type.Union([
+    import_typebox.Type.Object({
+      ok: import_typebox.Type.Literal(true),
+      instanceId: import_typebox.Type.String()
+    }),
+    import_typebox.Type.Object({
+      ok: import_typebox.Type.Literal(false),
+      reason: import_typebox.Type.Union([import_typebox.Type.Literal("VERSION_MISMATCH")])
+    })
+  ])
+});
+var ControlMessagePayloadSchema = import_typebox.Type.Union([
+  ControlMessageCloseSchema,
+  ControlMessageAckSchema,
+  ControlMessageHandshakeRequestSchema,
+  ControlMessageHandshakeResponseSchema
+]);
 var OpaqueTransportMessageSchema = TransportMessageSchema(
   import_typebox.Type.Unknown()
 );
-function reply(msg, response) {
+function bootResponseMessage(from, instanceId, to, ok) {
   return {
     id: (0, import_nanoid.nanoid)(),
-    streamId: msg.streamId,
+    from,
+    to,
+    seq: 0,
+    ack: 0,
+    streamId: (0, import_nanoid.nanoid)(),
     controlFlags: 0,
-    to: msg.from,
-    from: msg.to,
-    payload: response
+    payload: ok ? {
+      type: "HANDSHAKE_RESP",
+      status: {
+        ok: true,
+        instanceId
+      }
+    } : {
+      type: "HANDSHAKE_RESP",
+      status: {
+        ok: false,
+        reason: "VERSION_MISMATCH"
+      }
+    }
   };
 }
 function isAck(controlFlag) {
@@ -142,14 +134,279 @@ var EventDispatcher = class {
   }
 };
 
-// transport/transport.ts
+// transport/session.ts
+var import_nanoid2 = require("nanoid");
+var nanoid2 = (0, import_nanoid2.customAlphabet)("1234567890abcdefghijklmnopqrstuvxyz", 6);
+var unsafeId = () => nanoid2();
 var Connection = class {
-  connectedTo;
-  transport;
-  constructor(transport, connectedTo) {
-    this.connectedTo = connectedTo;
-    this.transport = transport;
+  debugId;
+  constructor() {
+    this.debugId = `conn-${unsafeId()}`;
+  }
+};
+var HEARTBEAT_INTERVAL_MS = 250;
+var HEARTBEATS_TILL_DEAD = 4;
+var SESSION_DISCONNECT_GRACE_MS = 3e3;
+var Session = class {
+  codec;
+  /**
+   * The buffer of messages that have been sent but not yet acknowledged.
+   */
+  sendBuffer = [];
+  /**
+   * The active connection associated with this session
+   */
+  connection;
+  from;
+  to;
+  /**
+   * The unique ID of this session.
+   */
+  debugId;
+  /**
+   * Number of messages we've sent along this session (excluding handshake)
+   */
+  seq = 0;
+  /**
+   * Number of unique messages we've received this session (excluding handshake)
+   */
+  ack = 0;
+  /**
+   * The grace period between when the inner connection is disconnected
+   * and when we should consider the entire session disconnected.
+   */
+  disconnectionGrace;
+  /**
+   * Number of heartbeats we've sent without a response.
+   */
+  heartbeatMisses;
+  /**
+   * The interval for sending heartbeats.
+   */
+  heartbeat;
+  constructor(codec, from, connectedTo, conn) {
+    this.debugId = `sess-${unsafeId()}`;
+    this.from = from;
+    this.to = connectedTo;
+    this.connection = conn;
+    this.codec = codec;
+    this.heartbeatMisses = 0;
+    this.heartbeat = setInterval(
+      () => this.sendHeartbeat(),
+      HEARTBEAT_INTERVAL_MS
+    );
+  }
+  /**
+   * Sends a message over the session's connection.
+   * If the connection is not ready or the message fails to send, the message can be buffered for retry unless skipped.
+   *
+   * @param msg The partial message to be sent, which will be constructed into a full message.
+   * @param skipRetry Optional. If true, the message will not be buffered for retry on failure. This should only be used for
+   * ack hearbeats, which contain information that can already be found in the other buffered messages.
+   * @returns The full transport ID of the message that was attempted to be sent.
+   */
+  send(msg, skipRetry) {
+    const fullMsg = this.constructMsg(msg);
+    log?.debug(`${this.from} -- sending ${JSON.stringify(fullMsg)}`);
+    if (this.connection) {
+      const ok = this.connection.send(this.codec.toBuffer(fullMsg));
+      if (ok)
+        return fullMsg.id;
+      log?.info(
+        `${this.from} -- failed to send ${fullMsg.id} to ${fullMsg.to}, connection (id: ${this.connection.debugId}) is probably dead`
+      );
+    } else {
+      log?.info(
+        `${this.from} -- failed to send ${fullMsg.id} to ${fullMsg.to}, connection not ready yet`
+      );
+    }
+    if (skipRetry)
+      return fullMsg.id;
+    this.addToSendBuff(fullMsg);
+    log?.info(
+      `${this.from} -- buffering msg ${fullMsg.id} until connection is healthy again`
+    );
+    return fullMsg.id;
+  }
+  sendHeartbeat() {
+    if (this.heartbeatMisses >= HEARTBEATS_TILL_DEAD && this.connection) {
+      log?.info(
+        `${this.from} -- closing connection (id: ${this.connection.debugId}) to ${this.to} due to inactivity`
+      );
+      this.halfCloseConnection();
+      return;
+    }
+    this.send(
+      {
+        streamId: "heartbeat",
+        controlFlags: 1 /* AckBit */,
+        payload: {
+          type: "ACK"
+        }
+      },
+      true
+    );
+    this.heartbeatMisses++;
+  }
+  resetBufferedMessages() {
+    this.sendBuffer = [];
+    this.seq = 0;
+    this.ack = 0;
+  }
+  sendBufferedMessages() {
+    if (!this.connection) {
+      const msg = `${this.from} -- tried sending buffered messages without a connection (if you hit this code path something is seriously wrong)`;
+      log?.error(msg);
+      throw new Error(msg);
+    }
+    for (const msg of this.sendBuffer) {
+      log?.debug(`${this.from} -- resending ${JSON.stringify(msg)}`);
+      const ok = this.connection.send(this.codec.toBuffer(msg));
+      if (!ok) {
+        const msg2 = `${this.from} -- failed to send buffered message to ${this.to} in session (id: ${this.debugId}) (if you hit this code path something is seriously wrong)`;
+        log?.error(msg2);
+        throw new Error(msg2);
+      }
+    }
+  }
+  updateBookkeeping(ack, seq) {
+    this.heartbeatMisses = 0;
+    this.sendBuffer = this.sendBuffer.filter((unacked) => unacked.seq > ack);
+    this.ack = seq + 1;
+  }
+  addToSendBuff(msg) {
+    this.sendBuffer.push(msg);
+    log?.debug(
+      `${this.from} -- send buff to ${this.to} now tracking ${this.sendBuffer.length} messages`
+    );
+  }
+  closeStaleConnection(conn) {
+    if (!this.connection || this.connection !== conn)
+      return;
+    log?.info(
+      `${this.from} -- closing old inner connection (id: ${this.connection.debugId}) from session (id: ${this.debugId}) to ${this.to}`
+    );
+    this.connection.close();
+    this.connection = void 0;
+  }
+  replaceWithNewConnection(newConn) {
+    this.closeStaleConnection(this.connection);
+    this.cancelGrace();
+    this.connection = newConn;
+  }
+  beginGrace(cb) {
+    this.disconnectionGrace = setTimeout(() => {
+      this.resetBufferedMessages();
+      clearInterval(this.heartbeat);
+      cb();
+    }, SESSION_DISCONNECT_GRACE_MS);
+  }
+  cancelGrace() {
+    clearTimeout(this.disconnectionGrace);
+  }
+  get connected() {
+    return this.connection !== void 0;
+  }
+  get nextExpectedSeq() {
+    return this.ack;
+  }
+  constructMsg(partialMsg) {
+    const msg = {
+      ...partialMsg,
+      id: unsafeId(),
+      to: this.to,
+      from: this.from,
+      seq: this.seq,
+      ack: this.ack
+    };
+    this.seq++;
+    return msg;
+  }
+  /**
+   * Closes the out-going connection but doesn't remove the listeners
+   * for incoming messages. The connection will eventually call onClose
+   * when it is ready to be cleaned up and only then will {@link connection} be set back
+   * to undefined
+   */
+  halfCloseConnection() {
+    this.connection?.close();
+  }
+  inspectSendBuffer() {
+    return this.sendBuffer;
+  }
+};
+
+// codec/json.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function uint8ArrayToBase64(uint8Array) {
+  let binary = "";
+  uint8Array.forEach((byte) => {
+    binary += String.fromCharCode(byte);
+  });
+  return btoa(binary);
+}
+function base64ToUint8Array(base64) {
+  const binaryString = atob(base64);
+  const uint8Array = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    uint8Array[i] = binaryString.charCodeAt(i);
   }
+  return uint8Array;
+}
+var NaiveJsonCodec = {
+  toBuffer: (obj) => {
+    return encoder.encode(
+      JSON.stringify(obj, function replacer(key) {
+        const val = this[key];
+        if (val instanceof Uint8Array) {
+          return { $t: uint8ArrayToBase64(val) };
+        } else {
+          return val;
+        }
+      })
+    );
+  },
+  fromBuffer: (buff) => {
+    try {
+      const parsed = JSON.parse(
+        decoder.decode(buff),
+        function reviver(_key, val) {
+          if (val?.$t) {
+            return base64ToUint8Array(val.$t);
+          } else {
+            return val;
+          }
+        }
+      );
+      if (typeof parsed === "object")
+        return parsed;
+      return null;
+    } catch {
+      return null;
+    }
+  }
+};
+
+// transport/transport.ts
+var import_nanoid3 = require("nanoid");
+
+// util/stringify.ts
+function coerceErrorString(err) {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  return `[coerced to error] ${String(err)}`;
+}
+
+// transport/transport.ts
+var DEFAULT_RECONNECT_JITTER_MAX_MS = 500;
+var DEFAULT_RECONNECT_INTERVAL_MS = 250;
+var defaultTransportOptions = {
+  retryIntervalMs: DEFAULT_RECONNECT_INTERVAL_MS,
+  retryJitterMs: DEFAULT_RECONNECT_JITTER_MAX_MS,
+  retryAttemptsMax: 5,
+  codec: NaiveJsonCodec
 };
 var Transport = class {
   /**
@@ -166,83 +423,114 @@ var Transport = class {
    */
   clientId;
   /**
-   * An array of message IDs that are waiting to be sent over the WebSocket connection.
-   * This builds up if the WebSocket is down for a period of time.
+   * The map of {@link Session}s managed by this transport.
    */
-  sendQueue;
-  /**
-   * The buffer of messages that have been sent but not yet acknowledged.
-   */
-  sendBuffer;
+  sessions;
   /**
    * The map of {@link Connection}s managed by this transport.
    */
-  connections;
+  get connections() {
+    return new Map(
+      [...this.sessions].map(([client, session]) => [client, session.connection]).filter((entry) => entry[1] !== void 0)
+    );
+  }
   /**
    * The event dispatcher for handling events of type EventTypes.
    */
   eventDispatcher;
+  /**
+   * The options for this transport.
+   */
+  options;
   /**
    * Creates a new Transport instance.
    * This should also set up {@link onConnect}, and {@link onDisconnect} listeners.
    * @param codec The codec used to encode and decode messages.
    * @param clientId The client ID of this transport.
    */
-  constructor(codec, clientId) {
+  constructor(clientId, providedOptions) {
+    this.options = { ...defaultTransportOptions, ...providedOptions };
     this.eventDispatcher = new EventDispatcher();
-    this.sendBuffer = /* @__PURE__ */ new Map();
-    this.sendQueue = /* @__PURE__ */ new Map();
-    this.connections = /* @__PURE__ */ new Map();
-    this.codec = codec;
+    this.sessions = /* @__PURE__ */ new Map();
+    this.codec = this.options.codec;
     this.clientId = clientId;
     this.state = "open";
   }
+  sessionByClientId(clientId) {
+    const session = this.sessions.get(clientId);
+    if (!session) {
+      const err = `${this.clientId} -- (invariant violation) no existing session for ${clientId}`;
+      log?.error(err);
+      throw new Error(err);
+    }
+    return session;
+  }
   /**
-   * The downstream implementation needs to call this when a new connection is established.
+   * Called when a new connection is established
+   * and we know the identity of the connected client.
    * @param conn The connection object.
    */
-  onConnect(conn) {
-    log?.info(`${this.clientId} -- new connection to ${conn.connectedTo}`);
-    this.connections.set(conn.connectedTo, conn);
+  onConnect(conn, connectedTo) {
     this.eventDispatcher.dispatchEvent("connectionStatus", {
       status: "connect",
       conn
     });
-    const outstanding = this.sendQueue.get(conn.connectedTo);
-    if (!outstanding) {
-      return;
-    }
-    for (const id of outstanding) {
-      const msg = this.sendBuffer.get(id);
-      if (!msg) {
-        log?.warn(
-          `${this.clientId} -- tried to resend a message we received an ack for`
-        );
-        continue;
-      }
-      this.send(msg);
+    const session = this.sessions.get(connectedTo);
+    if (session === void 0) {
+      const newSession = this.createSession(connectedTo, conn);
+      log?.info(
+        `${this.clientId} -- new connection (id: ${conn.debugId}) for new session (id: ${newSession.debugId}) to ${connectedTo}`
+      );
+      return newSession;
     }
-    this.sendQueue.delete(conn.connectedTo);
+    log?.info(
+      `${this.clientId} -- new connection (id: ${conn.debugId}) for existing session (id: ${session.debugId}) to ${connectedTo}`
+    );
+    session.replaceWithNewConnection(conn);
+    session.sendBufferedMessages();
+    return session;
+  }
+  createSession(connectedTo, conn) {
+    const session = new Session(
+      this.codec,
+      this.clientId,
+      connectedTo,
+      conn
+    );
+    this.sessions.set(session.to, session);
+    this.eventDispatcher.dispatchEvent("sessionStatus", {
+      status: "connect",
+      session
+    });
+    return session;
+  }
+  deleteSession(session) {
+    this.sessions.delete(session.to);
+    this.eventDispatcher.dispatchEvent("sessionStatus", {
+      status: "disconnect",
+      session
+    });
+    log?.info(
+      `${this.clientId} -- session ${session.debugId} disconnect from ${session.to}`
+    );
   }
   /**
    * The downstream implementation needs to call this when a connection is closed.
    * @param conn The connection object.
    */
-  onDisconnect(conn) {
-    log?.info(`${this.clientId} -- disconnect from ${conn.connectedTo}`);
-    conn.close();
-    this.connections.delete(conn.connectedTo);
+  onDisconnect(conn, connectedTo) {
     this.eventDispatcher.dispatchEvent("connectionStatus", {
       status: "disconnect",
       conn
     });
-  }
-  /**
-   * Handles a message received by this transport. Thin wrapper around {@link handleMsg} and {@link parseMsg}.
-   * @param msg The message to handle.
-   */
-  onMessage(msg) {
-    return this.handleMsg(this.parseMsg(msg));
+    if (!connectedTo)
+      return;
+    const session = this.sessionByClientId(connectedTo);
+    log?.info(
+      `${this.clientId} -- connection (id: ${conn.debugId}) disconnect from ${connectedTo}, ${SESSION_DISCONNECT_GRACE_MS}ms until session (id: ${session.debugId}) disconnect`
+    );
+    session.closeStaleConnection(conn);
+    session.beginGrace(() => this.deleteSession(session));
   }
   /**
    * Parses a message from a Uint8Array into a {@link OpaqueTransportMessage}.
@@ -256,13 +544,7 @@ var Transport = class {
       log?.warn(`${this.clientId} -- received malformed msg: ${decodedBuffer}`);
       return null;
     }
-    if (import_value.Value.Check(OpaqueTransportMessageSchema, parsedMsg)) {
-      return {
-        ...parsedMsg,
-        serviceName: parsedMsg.serviceName === null ? void 0 : parsedMsg.serviceName,
-        procedureName: parsedMsg.procedureName === null ? void 0 : parsedMsg.procedureName
-      };
-    } else {
+    if (!import_value.Value.Check(OpaqueTransportMessageSchema, parsedMsg)) {
       log?.warn(
         `${this.clientId} -- received invalid msg: ${JSON.stringify(
           parsedMsg
@@ -270,6 +552,11 @@ var Transport = class {
       );
       return null;
     }
+    return {
+      ...parsedMsg,
+      serviceName: parsedMsg.serviceName === null ? void 0 : parsedMsg.serviceName,
+      procedureName: parsedMsg.procedureName === null ? void 0 : parsedMsg.procedureName
+    };
   }
   /**
    * Called when a message is received by this transport.
@@ -280,21 +567,21 @@ var Transport = class {
     if (!msg) {
       return;
     }
-    if (isAck(msg.controlFlags) && import_value.Value.Check(TransportAckSchema, msg)) {
-      log?.debug(`${this.clientId} -- received ack: ${JSON.stringify(msg)}`);
-      if (this.sendBuffer.has(msg.payload.ack)) {
-        this.sendBuffer.delete(msg.payload.ack);
-      }
-    } else {
-      log?.debug(`${this.clientId} -- received msg: ${JSON.stringify(msg)}`);
+    const session = this.sessionByClientId(msg.from);
+    session.cancelGrace();
+    log?.debug(`${this.clientId} -- received msg: ${JSON.stringify(msg)}`);
+    if (msg.seq !== session.nextExpectedSeq) {
+      log?.warn(
+        `${this.clientId} -- received out-of-order msg (got: ${msg.seq}, wanted: ${session.nextExpectedSeq}), discarding: ${JSON.stringify(
+          msg
+        )}`
+      );
+      return;
+    }
+    if (!isAck(msg.controlFlags)) {
       this.eventDispatcher.dispatchEvent("message", msg);
-      if (!isAck(msg.controlFlags)) {
-        const ackMsg = reply(msg, { ack: msg.id });
-        ackMsg.controlFlags = 1 /* AckBit */;
-        ackMsg.from = this.clientId;
-        this.send(ackMsg);
-      }
     }
+    session.updateBookkeeping(msg.ack, msg.seq);
   }
   /**
    * Adds a listener to this transport.
@@ -316,9 +603,9 @@ var Transport = class {
    * Sends a message over this transport, delegating to the appropriate connection to actually
    * send the message.
    * @param msg The message to send.
-   * @returns The ID of the sent message.
+   * @returns The ID of the sent message or undefined if it wasn't sent
    */
-  send(msg) {
+  send(to, msg) {
     if (this.state === "destroyed") {
       const err = "transport is destroyed, cant send";
       log?.error(`${this.clientId} -- ` + err + `: ${JSON.stringify(msg)}`);
@@ -329,64 +616,150 @@ var Transport = class {
           msg
         )}`
       );
-      return msg.id;
+      return void 0;
     }
-    let conn = this.connections.get(msg.to);
-    if (!isAck(msg.controlFlags)) {
-      this.sendBuffer.set(msg.id, msg);
+    let session = this.sessions.get(to);
+    if (!session) {
+      session = this.createSession(to, void 0);
+      log?.info(
+        `${this.clientId} -- no session for ${to}, created a new one (id: ${session.debugId})`
+      );
     }
-    if (conn) {
-      log?.debug(`${this.clientId} -- sending ${JSON.stringify(msg)}`);
-      const ok = conn.send(this.codec.toBuffer(msg));
-      if (ok) {
-        return msg.id;
+    return session.send(msg);
+  }
+  // control helpers
+  sendCloseStream(to, streamId) {
+    return this.send(to, {
+      streamId,
+      controlFlags: 4 /* StreamClosedBit */,
+      payload: {
+        type: "CLOSE"
       }
-    }
-    log?.info(
-      `${this.clientId} -- connection to ${msg.to} not ready, attempting reconnect and queuing ${JSON.stringify(msg)}`
-    );
-    const outstanding = this.sendQueue.get(msg.to) || [];
-    outstanding.push(msg.id);
-    this.sendQueue.set(msg.to, outstanding);
-    this.createNewConnection(msg.to);
-    return msg.id;
+    });
   }
   /**
    * Default close implementation for transports. You should override this in the downstream
    * implementation if you need to do any additional cleanup and call super.close() at the end.
    * Closes the transport. Any messages sent while the transport is closed will be silently discarded.
    */
-  async close() {
-    for (const conn of this.connections.values()) {
-      conn.close();
+  close() {
+    for (const session of this.sessions.values()) {
+      session.halfCloseConnection();
     }
-    this.connections.clear();
     this.state = "closed";
-    log?.info(`${this.clientId} -- closed transport`);
+    log?.info(`${this.clientId} -- manually closed transport`);
   }
   /**
    * Default destroy implementation for transports. You should override this in the downstream
    * implementation if you need to do any additional cleanup and call super.destroy() at the end.
    * Destroys the transport. Any messages sent while the transport is destroyed will throw an error.
    */
-  async destroy() {
-    for (const conn of this.connections.values()) {
-      conn.close();
+  destroy() {
+    for (const session of this.sessions.values()) {
+      session.closeStaleConnection(session.connection);
     }
-    this.connections.clear();
     this.state = "destroyed";
-    log?.info(`${this.clientId} -- destroyed transport`);
+    log?.info(`${this.clientId} -- manually destroyed transport`);
+  }
+};
+var ServerTransport = class extends Transport {
+  /**
+   * Unique per instance of server transport.
+   * This allows us to distinguish reconnects to different
+   * server transports at the same reachable address and signal
+   * the appropriate session disconnect back to the client at the
+   * boot stage.
+   */
+  instanceId = (0, import_nanoid3.nanoid)();
+  constructor(clientId, providedOptions) {
+    super(clientId, providedOptions);
+    log?.info(
+      `${this.clientId} -- initiated server transport (instance id: ${this.instanceId}, protocol: ${PROTOCOL_VERSION})`
+    );
+  }
+  handleConnection(conn) {
+    let session = void 0;
+    const client = () => session?.to ?? "unknown";
+    const bootHandler = this.receiveWithBootSequence(
+      conn,
+      (establishedSession) => {
+        session = establishedSession;
+        conn.removeDataListener(bootHandler);
+        conn.addDataListener((data) => this.handleMsg(this.parseMsg(data)));
+      }
+    );
+    conn.addDataListener(bootHandler);
+    conn.addCloseListener(() => {
+      if (!session)
+        return;
+      log?.info(
+        `${this.clientId} -- connection (id: ${conn.debugId}) to ${client()} disconnected`
+      );
+      this.onDisconnect(conn, session.to);
+    });
+    conn.addErrorListener((err) => {
+      if (!session)
+        return;
+      log?.warn(
+        `${this.clientId} -- connection (id: ${conn.debugId}) to ${client()} got an error: ${coerceErrorString(err)}`
+      );
+    });
+  }
+  receiveWithBootSequence(conn, sessionCb) {
+    const bootHandler = (data) => {
+      const parsed = this.parseMsg(data);
+      if (!parsed)
+        return;
+      if (!import_value.Value.Check(ControlMessageHandshakeRequestSchema, parsed.payload)) {
+        const responseMsg2 = bootResponseMessage(
+          this.clientId,
+          this.instanceId,
+          parsed.from,
+          false
+        );
+        conn.send(this.codec.toBuffer(responseMsg2));
+        log?.warn(
+          `${this.clientId} -- received invalid handshake msg: ${JSON.stringify(
+            parsed
+          )}`
+        );
+        return;
+      }
+      log?.debug(
+        `${this.clientId} -- handshake from ${parsed.from} ok, responding with handshake success`
+      );
+      const responseMsg = bootResponseMessage(
+        this.clientId,
+        this.instanceId,
+        parsed.from,
+        true
+      );
+      conn.send(this.codec.toBuffer(responseMsg));
+      sessionCb(this.onConnect(conn, parsed.from));
+    };
+    return bootHandler;
   }
 };
 
 // transport/impls/ws/connection.ts
 var WebSocketConnection = class extends Connection {
   ws;
-  constructor(transport, connectedTo, ws) {
-    super(transport, connectedTo);
+  constructor(ws) {
+    super();
     this.ws = ws;
-    ws.binaryType = "arraybuffer";
-    this.ws.onmessage = (msg) => transport.onMessage(msg.data);
+    this.ws.binaryType = "arraybuffer";
+  }
+  addDataListener(cb) {
+    this.ws.onmessage = (msg) => cb(msg.data);
+  }
+  removeDataListener() {
+    this.ws.onmessage = null;
+  }
+  addCloseListener(cb) {
+    this.ws.onclose = cb;
+  }
+  addErrorListener(cb) {
+    this.ws.onerror = (err) => cb(new Error(err.message));
   }
   send(payload) {
     if (this.ws.readyState === this.ws.OPEN) {
@@ -396,53 +769,27 @@ var WebSocketConnection = class extends Connection {
       return false;
     }
   }
-  async close() {
+  close() {
     this.ws.close();
   }
 };
 
 // transport/impls/ws/server.ts
-var defaultOptions = {
-  codec: NaiveJsonCodec
-};
-var WebSocketServerTransport = class extends Transport {
+var WebSocketServerTransport = class extends ServerTransport {
   wss;
   constructor(wss, clientId, providedOptions) {
-    const options = { ...defaultOptions, ...providedOptions };
-    super(options.codec, clientId);
+    super(clientId, providedOptions);
     this.wss = wss;
-    wss.on("listening", () => {
-      log?.info(`${this.clientId} -- server is listening`);
-    });
     this.wss.on("connection", this.connectionHandler);
   }
   connectionHandler = (ws) => {
-    let conn = void 0;
-    ws.onmessage = (msg) => {
-      const parsedMsg = this.parseMsg(msg.data);
-      if (parsedMsg && !conn) {
-        conn = new WebSocketConnection(this, parsedMsg.from, ws);
-        this.onConnect(conn);
-        this.handleMsg(parsedMsg);
-      }
-    };
-    ws.onclose = () => {
-      if (conn) {
-        this.onDisconnect(conn);
-      }
-    };
-    ws.onerror = (msg) => {
-      log?.warn(
-        `${this.clientId} -- ws error from client ${conn?.connectedTo ?? "unknown"}: ${msg}`
-      );
-    };
+    const conn = new WebSocketConnection(ws);
+    log?.info(
+      `${this.clientId} -- new incoming ws connection (id: ${conn.debugId})`
+    );
+    this.handleConnection(conn);
   };
-  async createNewConnection(to) {
-    const err = `${this.clientId} -- failed to send msg to ${to}, client probably dropped`;
-    log?.warn(err);
-    return;
-  }
-  async close() {
+  close() {
     super.close();
     this.wss.off("connection", this.connectionHandler);
   }