@replit/river 0.23.16 → 0.24.0

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

@@ -24,12 +24,193 @@ __export(server_exports, {
 });
 module.exports = __toCommonJS(server_exports);
 
-// transport/session.ts
-var import_nanoid2 = require("nanoid");
+// transport/transforms/messageFraming.ts
+var import_node_stream = require("stream");
+var Uint32LengthPrefixFraming = class extends import_node_stream.Transform {
+  receivedBuffer;
+  maxBufferSizeBytes;
+  constructor({ maxBufferSizeBytes, ...options }) {
+    super(options);
+    this.maxBufferSizeBytes = maxBufferSizeBytes;
+    this.receivedBuffer = Buffer.alloc(0);
+  }
+  _transform(chunk, _encoding, cb) {
+    if (this.receivedBuffer.byteLength + chunk.byteLength > this.maxBufferSizeBytes) {
+      const err = new Error(
+        `buffer overflow: ${this.receivedBuffer.byteLength}B > ${this.maxBufferSizeBytes}B`
+      );
+      this.emit("error", err);
+      cb(err);
+      return;
+    }
+    this.receivedBuffer = Buffer.concat([this.receivedBuffer, chunk]);
+    while (this.receivedBuffer.length > 4) {
+      const claimedMessageLength = this.receivedBuffer.readUInt32BE(0) + 4;
+      if (this.receivedBuffer.length >= claimedMessageLength) {
+        const message = this.receivedBuffer.subarray(4, claimedMessageLength);
+        this.push(message);
+        this.receivedBuffer = this.receivedBuffer.subarray(claimedMessageLength);
+      } else {
+        break;
+      }
+    }
+    cb();
+  }
+  _flush(cb) {
+    if (this.receivedBuffer.length) {
+      this.emit("error", new Error("got incomplete message while flushing"));
+    }
+    this.receivedBuffer = Buffer.alloc(0);
+    cb();
+  }
+  _destroy(error, callback) {
+    this.receivedBuffer = Buffer.alloc(0);
+    super._destroy(error, callback);
+  }
+};
+function createLengthEncodedStream(options) {
+  return new Uint32LengthPrefixFraming({
+    maxBufferSizeBytes: options?.maxBufferSizeBytes ?? 16 * 1024 * 1024
+    // 16MB
+  });
+}
+var MessageFramer = {
+  createFramedStream: createLengthEncodedStream,
+  write: (buf) => {
+    const lengthPrefix = Buffer.alloc(4);
+    lengthPrefix.writeUInt32BE(buf.length, 0);
+    return Buffer.concat([lengthPrefix, buf]);
+  }
+};
+
+// transport/id.ts
+var import_nanoid = require("nanoid");
+var alphabet = (0, import_nanoid.customAlphabet)(
+  "1234567890abcdefghijklmnopqrstuvxyzABCDEFGHIJKLMNOPQRSTUVXYZ"
+);
+var generateId = () => alphabet(12);
+
+// transport/connection.ts
+var Connection = class {
+  id;
+  telemetry;
+  constructor() {
+    this.id = `conn-${generateId()}`;
+  }
+  get loggingMetadata() {
+    const metadata = { connId: this.id };
+    const spanContext = this.telemetry?.span.spanContext();
+    if (this.telemetry?.span.isRecording() && spanContext) {
+      metadata.telemetry = {
+        traceId: spanContext.traceId,
+        spanId: spanContext.spanId
+      };
+    }
+    return metadata;
+  }
+  // can't use event emitter because we need this to work in both node + browser
+  _dataListeners = /* @__PURE__ */ new Set();
+  _closeListeners = /* @__PURE__ */ new Set();
+  _errorListeners = /* @__PURE__ */ new Set();
+  get dataListeners() {
+    return [...this._dataListeners];
+  }
+  get closeListeners() {
+    return [...this._closeListeners];
+  }
+  get errorListeners() {
+    return [...this._errorListeners];
+  }
+  /**
+   * Handle adding a callback for when a message is received.
+   * @param msg The message that was received.
+   */
+  addDataListener(cb) {
+    this._dataListeners.add(cb);
+  }
+  removeDataListener(cb) {
+    this._dataListeners.delete(cb);
+  }
+  /**
+   * Handle adding a callback for when the connection is closed.
+   * This should also be called if an error happens and after notifying all the error listeners.
+   * @param cb The callback to call when the connection is closed.
+   */
+  addCloseListener(cb) {
+    this._closeListeners.add(cb);
+  }
+  removeCloseListener(cb) {
+    this._closeListeners.delete(cb);
+  }
+  /**
+   * Handle adding a callback for when an error is received.
+   * This should only be used for this.logging errors, all cleanup
+   * should be delegated to addCloseListener.
+   *
+   * The implementer should take care such that the implemented
+   * connection will call both the close and error callbacks
+   * on an error.
+   *
+   * @param cb The callback to call when an error is received.
+   */
+  addErrorListener(cb) {
+    this._errorListeners.add(cb);
+  }
+  removeErrorListener(cb) {
+    this._errorListeners.delete(cb);
+  }
+};
+
+// transport/impls/uds/connection.ts
+var UdsConnection = class extends Connection {
+  sock;
+  input;
+  framer;
+  constructor(sock) {
+    super();
+    this.framer = MessageFramer.createFramedStream();
+    this.sock = sock;
+    this.input = sock.pipe(this.framer);
+    this.sock.on("close", () => {
+      for (const cb of this.closeListeners) {
+        cb();
+      }
+    });
+    this.sock.on("error", (err) => {
+      if (err instanceof Error && "code" in err && err.code === "EPIPE") {
+        return;
+      }
+      for (const cb of this.errorListeners) {
+        cb(err);
+      }
+    });
+    this.input.on("data", (msg) => {
+      for (const cb of this.dataListeners) {
+        cb(msg);
+      }
+    });
+    this.sock.on("end", () => {
+      this.sock.destroy();
+    });
+  }
+  send(payload) {
+    if (this.framer.destroyed || !this.sock.writable || this.sock.closed) {
+      return false;
+    }
+    this.sock.write(MessageFramer.write(payload));
+    return true;
+  }
+  close() {
+    this.sock.end();
+    this.framer.end();
+  }
+};
+
+// transport/server.ts
+var import_api3 = require("@opentelemetry/api");
 
 // transport/message.ts
 var import_typebox = require("@sinclair/typebox");
-var import_nanoid = require("nanoid");
 var TransportMessageSchema = (t) => import_typebox.Type.Object({
   id: import_typebox.Type.String(),
   from: import_typebox.Type.String(),
@@ -64,18 +245,29 @@ var ControlMessageHandshakeRequestSchema = import_typebox.Type.Object({
    * used by the server to know whether this is a new or a reestablished connection, and whether it
    * is compatible with what it already has.
    */
-  expectedSessionState: import_typebox.Type.Optional(
-    import_typebox.Type.Object({
-      /**
-       * reconnect is set to true if the client explicitly wants to reestablish an existing
-       * connection.
-       */
-      reconnect: import_typebox.Type.Boolean(),
-      nextExpectedSeq: import_typebox.Type.Integer()
-    })
-  ),
+  expectedSessionState: import_typebox.Type.Object({
+    // what the client expects the server to send next
+    nextExpectedSeq: import_typebox.Type.Integer(),
+    // TODO: remove optional once we know all servers
+    // are nextSentSeq here
+    // what the server expects the client to send next
+    nextSentSeq: import_typebox.Type.Optional(import_typebox.Type.Integer())
+  }),
   metadata: import_typebox.Type.Optional(import_typebox.Type.Unknown())
 });
+var HandshakeErrorRetriableResponseCodes = import_typebox.Type.Union([
+  import_typebox.Type.Literal("SESSION_STATE_MISMATCH")
+]);
+var HandshakeErrorFatalResponseCodes = import_typebox.Type.Union([
+  import_typebox.Type.Literal("MALFORMED_HANDSHAKE_META"),
+  import_typebox.Type.Literal("MALFORMED_HANDSHAKE"),
+  import_typebox.Type.Literal("PROTOCOL_VERSION_MISMATCH"),
+  import_typebox.Type.Literal("REJECTED_BY_CUSTOM_HANDLER")
+]);
+var HandshakeErrorResponseCodes = import_typebox.Type.Union([
+  HandshakeErrorRetriableResponseCodes,
+  HandshakeErrorFatalResponseCodes
+]);
 var ControlMessageHandshakeResponseSchema = import_typebox.Type.Object({
   type: import_typebox.Type.Literal("HANDSHAKE_RESP"),
   status: import_typebox.Type.Union([
@@ -85,7 +277,10 @@ var ControlMessageHandshakeResponseSchema = import_typebox.Type.Object({
     }),
     import_typebox.Type.Object({
       ok: import_typebox.Type.Literal(false),
-      reason: import_typebox.Type.String()
+      reason: import_typebox.Type.String(),
+      // TODO: remove optional once we know all servers
+      // are sending code here
+      code: import_typebox.Type.Optional(HandshakeErrorResponseCodes)
     })
   ])
 });
@@ -98,19 +293,18 @@ var ControlMessagePayloadSchema = import_typebox.Type.Union([
 var OpaqueTransportMessageSchema = TransportMessageSchema(
   import_typebox.Type.Unknown()
 );
-var SESSION_STATE_MISMATCH = "session state mismatch";
 function handshakeResponseMessage({
   from,
   to,
   status
 }) {
   return {
-    id: (0, import_nanoid.nanoid)(),
+    id: generateId(),
     from,
     to,
     seq: 0,
     ack: 0,
-    streamId: (0, import_nanoid.nanoid)(),
+    streamId: generateId(),
     controlFlags: 0,
     payload: {
       type: "HANDSHAKE_RESP",
@@ -122,974 +316,849 @@ function isAck(controlFlag) {
   return (controlFlag & 1 /* AckBit */) === 1 /* AckBit */;
 }
 
-// tracing/index.ts
-var import_api = require("@opentelemetry/api");
-
-// package.json
-var version = "0.23.16";
-
-// tracing/index.ts
-function createSessionTelemetryInfo(session, propagationCtx) {
-  const parentCtx = propagationCtx ? import_api.propagation.extract(import_api.context.active(), propagationCtx) : import_api.context.active();
-  const span = tracer.startSpan(
-    `session ${session.id}`,
-    {
-      attributes: {
-        component: "river",
-        "river.session.id": session.id,
-        "river.session.to": session.to,
-        "river.session.from": session.from
-      }
-    },
-    parentCtx
-  );
-  const ctx = import_api.trace.setSpan(parentCtx, span);
-  return { span, ctx };
-}
-function createConnectionTelemetryInfo(connection, info) {
-  const span = tracer.startSpan(
-    `connection ${connection.id}`,
-    {
-      attributes: {
-        component: "river",
-        "river.connection.id": connection.id
-      },
-      links: [{ context: info.span.spanContext() }]
-    },
-    info.ctx
-  );
-  const ctx = import_api.trace.setSpan(info.ctx, span);
-  return { span, ctx };
+// 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);
 }
-var tracer = import_api.trace.getTracer("river", version);
-
-// transport/session.ts
-var import_api2 = require("@opentelemetry/api");
-var nanoid2 = (0, import_nanoid2.customAlphabet)("1234567890abcdefghijklmnopqrstuvxyz", 6);
-var unsafeId = () => nanoid2();
-var Connection = class {
-  id;
-  telemetry;
-  constructor() {
-    this.id = `conn-${nanoid2(12)}`;
+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);
   }
-  get loggingMetadata() {
-    const metadata = { connId: this.id };
-    const spanContext = this.telemetry?.span.spanContext();
-    if (this.telemetry?.span.isRecording() && spanContext) {
-      metadata.telemetry = {
-        traceId: spanContext.traceId,
-        spanId: spanContext.spanId
-      };
+  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;
     }
-    return metadata;
   }
 };
-var Session = class {
-  codec;
-  options;
-  telemetry;
-  /**
-   * The buffer of messages that have been sent but not yet acknowledged.
-   */
-  sendBuffer = [];
-  /**
-   * The active connection associated with this session
-   */
-  connection;
-  /**
-   * A connection that is currently undergoing handshaking. Used to distinguish between the active
-   * connection, but still be able to close it if needed.
-   */
-  handshakingConnection;
-  from;
-  to;
-  /**
-   * The unique ID of this session.
-   */
-  id;
-  /**
-   * What the other side advertised as their session ID
-   * for this session.
-   */
-  advertisedSessionId;
-  /**
-   * Number of messages we've sent along this session (excluding handshake and acks)
-   */
-  seq = 0;
-  /**
-   * Number of unique messages we've received this session (excluding handshake and acks)
-   */
-  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;
-  log;
-  constructor(conn, from, to, options, propagationCtx) {
-    this.id = `session-${nanoid2(12)}`;
-    this.options = options;
-    this.from = from;
-    this.to = to;
-    this.connection = conn;
-    this.codec = options.codec;
-    this.heartbeatMisses = 0;
-    this.heartbeat = setInterval(
-      () => this.sendHeartbeat(),
-      options.heartbeatIntervalMs
-    );
-    this.telemetry = createSessionTelemetryInfo(this, propagationCtx);
-  }
-  bindLogger(log) {
-    this.log = log;
-  }
-  get loggingMetadata() {
-    const spanContext = this.telemetry.span.spanContext();
-    return {
-      clientId: this.from,
-      connectedTo: this.to,
-      sessionId: this.id,
-      connId: this.connection?.id,
-      telemetry: {
-        traceId: spanContext.traceId,
-        spanId: spanContext.spanId
-      }
-    };
-  }
-  /**
-   * 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 addToSendBuff Whether to add the message to the send buffer for retry.
-   * @returns The full transport ID of the message that was attempted to be sent.
-   */
-  send(msg) {
-    const fullMsg = this.constructMsg(msg);
-    this.log?.debug(`sending msg`, {
-      ...this.loggingMetadata,
-      transportMessage: fullMsg
-    });
-    if (this.connection) {
-      const ok = this.connection.send(this.codec.toBuffer(fullMsg));
-      if (ok)
-        return fullMsg.id;
-      this.log?.info(
-        `failed to send msg to ${fullMsg.to}, connection is probably dead`,
-        {
-          ...this.loggingMetadata,
-          transportMessage: fullMsg
-        }
-      );
-    } else {
-      this.log?.debug(
-        `buffering msg to ${fullMsg.to}, connection not ready yet`,
-        { ...this.loggingMetadata, transportMessage: fullMsg }
-      );
-    }
-    return fullMsg.id;
-  }
-  sendHeartbeat() {
-    const misses = this.heartbeatMisses;
-    const missDuration = misses * this.options.heartbeatIntervalMs;
-    if (misses > this.options.heartbeatsUntilDead) {
-      if (this.connection) {
-        this.log?.info(
-          `closing connection to ${this.to} due to inactivity (missed ${misses} heartbeats which is ${missDuration}ms)`,
-          this.loggingMetadata
-        );
-        this.telemetry.span.addEvent("closing connection due to inactivity");
-        this.closeStaleConnection();
-      }
+
+// transport/options.ts
+var defaultTransportOptions = {
+  heartbeatIntervalMs: 1e3,
+  heartbeatsUntilDead: 2,
+  sessionDisconnectGraceMs: 5e3,
+  connectionTimeoutMs: 2e3,
+  handshakeTimeoutMs: 1e3,
+  codec: NaiveJsonCodec
+};
+var defaultConnectionRetryOptions = {
+  baseIntervalMs: 250,
+  maxJitterMs: 200,
+  maxBackoffMs: 32e3,
+  attemptBudgetCapacity: 5,
+  budgetRestoreIntervalMs: 200
+};
+var defaultClientTransportOptions = {
+  ...defaultTransportOptions,
+  ...defaultConnectionRetryOptions
+};
+var defaultServerTransportOptions = {
+  ...defaultTransportOptions
+};
+
+// logging/log.ts
+var LoggingLevels = {
+  debug: -1,
+  info: 0,
+  warn: 1,
+  error: 2
+};
+var cleanedLogFn = (log) => {
+  return (msg, metadata) => {
+    if (!metadata?.transportMessage) {
+      log(msg, metadata);
       return;
     }
-    this.send({
-      streamId: "heartbeat",
-      controlFlags: 1 /* AckBit */,
-      payload: {
-        type: "ACK"
-      }
-    });
-    this.heartbeatMisses++;
+    const { payload, ...rest } = metadata.transportMessage;
+    metadata.transportMessage = rest;
+    log(msg, metadata);
+  };
+};
+var BaseLogger = class {
+  minLevel;
+  output;
+  constructor(output, minLevel = "info") {
+    this.minLevel = minLevel;
+    this.output = output;
   }
-  resetBufferedMessages() {
-    this.sendBuffer = [];
-    this.seq = 0;
-    this.ack = 0;
+  debug(msg, metadata) {
+    if (LoggingLevels[this.minLevel] <= LoggingLevels.debug) {
+      this.output(msg, metadata ?? {}, "debug");
+    }
   }
-  sendBufferedMessages(conn) {
-    this.log?.info(`resending ${this.sendBuffer.length} buffered messages`, {
-      ...this.loggingMetadata,
-      connId: conn.id
-    });
-    for (const msg of this.sendBuffer) {
-      this.log?.debug(`resending msg`, {
-        ...this.loggingMetadata,
-        transportMessage: msg,
-        connId: conn.id
-      });
-      const ok = conn.send(this.codec.toBuffer(msg));
-      if (!ok) {
-        const errMsg = `failed to send buffered message to ${this.to} (sus, this is a fresh connection)`;
-        conn.telemetry?.span.setStatus({
-          code: import_api2.SpanStatusCode.ERROR,
-          message: errMsg
-        });
-        this.log?.error(errMsg, {
-          ...this.loggingMetadata,
-          transportMessage: msg,
-          connId: conn.id,
-          tags: ["invariant-violation"]
-        });
-        conn.close();
-        return;
-      }
+  info(msg, metadata) {
+    if (LoggingLevels[this.minLevel] <= LoggingLevels.info) {
+      this.output(msg, metadata ?? {}, "info");
     }
   }
-  updateBookkeeping(ack, seq) {
-    if (seq + 1 < this.ack) {
-      this.log?.error(`received stale seq ${seq} + 1 < ${this.ack}`, {
-        ...this.loggingMetadata,
-        tags: ["invariant-violation"]
-      });
-      return;
+  warn(msg, metadata) {
+    if (LoggingLevels[this.minLevel] <= LoggingLevels.warn) {
+      this.output(msg, metadata ?? {}, "warn");
     }
-    this.sendBuffer = this.sendBuffer.filter((unacked) => unacked.seq >= ack);
-    this.ack = seq + 1;
   }
-  closeStaleConnection(conn) {
-    if (this.connection === void 0 || this.connection === conn)
-      return;
-    this.log?.info(
-      `closing old inner connection from session to ${this.to}`,
-      this.loggingMetadata
-    );
-    this.connection.close();
-    this.connection = void 0;
-  }
-  replaceWithNewConnection(newConn, isTransparentReconnect) {
-    this.closeStaleConnection(newConn);
-    this.cancelGrace();
-    if (isTransparentReconnect) {
-      this.sendBufferedMessages(newConn);
+  error(msg, metadata) {
+    if (LoggingLevels[this.minLevel] <= LoggingLevels.error) {
+      this.output(msg, metadata ?? {}, "error");
     }
-    this.connection = newConn;
-    this.handshakingConnection = void 0;
   }
-  replaceWithNewHandshakingConnection(newConn) {
-    this.handshakingConnection = newConn;
+};
+var createLogProxy = (log) => ({
+  debug: cleanedLogFn(log.debug.bind(log)),
+  info: cleanedLogFn(log.info.bind(log)),
+  warn: cleanedLogFn(log.warn.bind(log)),
+  error: cleanedLogFn(log.error.bind(log))
+});
+
+// transport/events.ts
+var ProtocolError = {
+  RetriesExceeded: "conn_retry_exceeded",
+  HandshakeFailed: "handshake_failed",
+  MessageOrderingViolated: "message_ordering_violated"
+};
+var EventDispatcher = class {
+  eventListeners = {};
+  removeAllListeners() {
+    this.eventListeners = {};
   }
-  beginGrace(cb) {
-    this.log?.info(
-      `starting ${this.options.sessionDisconnectGraceMs}ms grace period until session to ${this.to} is closed`,
-      this.loggingMetadata
-    );
-    this.cancelGrace();
-    this.disconnectionGrace = setTimeout(() => {
-      this.log?.info(
-        `grace period for ${this.to} elapsed`,
-        this.loggingMetadata
-      );
-      cb();
-    }, this.options.sessionDisconnectGraceMs);
+  numberOfListeners(eventType) {
+    return this.eventListeners[eventType]?.size ?? 0;
   }
-  // called on reconnect of the underlying session
-  cancelGrace() {
-    this.heartbeatMisses = 0;
-    clearTimeout(this.disconnectionGrace);
-    this.disconnectionGrace = void 0;
+  addEventListener(eventType, handler) {
+    if (!this.eventListeners[eventType]) {
+      this.eventListeners[eventType] = /* @__PURE__ */ new Set();
+    }
+    this.eventListeners[eventType]?.add(handler);
   }
-  /**
-   * Used to close the handshaking connection, if set.
-   */
-  closeHandshakingConnection(expectedHandshakingConn) {
-    if (this.handshakingConnection === void 0)
-      return;
-    if (expectedHandshakingConn !== void 0 && this.handshakingConnection === expectedHandshakingConn) {
-      return;
+  removeEventListener(eventType, handler) {
+    const handlers = this.eventListeners[eventType];
+    if (handlers) {
+      this.eventListeners[eventType]?.delete(handler);
+    }
+  }
+  dispatchEvent(eventType, event) {
+    const handlers = this.eventListeners[eventType];
+    if (handlers) {
+      const copy = [...handlers];
+      for (const handler of copy) {
+        handler(event);
+      }
     }
-    this.handshakingConnection.close();
-    this.handshakingConnection = void 0;
   }
-  // closed when we want to discard the whole session
-  // (i.e. shutdown or session disconnect)
+};
+
+// transport/sessionStateMachine/common.ts
+var import_value = require("@sinclair/typebox/value");
+var ERR_CONSUMED = `session state has been consumed and is no longer valid`;
+var StateMachineState = class {
+  /*
+   * Whether this state has been consumed
+   * and we've moved on to another state
+   */
+  _isConsumed;
   close() {
-    this.closeStaleConnection();
-    this.cancelGrace();
-    this.resetBufferedMessages();
-    clearInterval(this.heartbeat);
+    this._handleClose();
   }
-  get connected() {
-    return this.connection !== void 0;
+  constructor() {
+    this._isConsumed = false;
+    return new Proxy(this, {
+      get(target, prop) {
+        if (prop === "_isConsumed" || prop === "id" || prop === "state") {
+          return Reflect.get(target, prop);
+        }
+        if (prop === "_handleStateExit") {
+          return () => {
+            target._isConsumed = true;
+            target._handleStateExit();
+          };
+        }
+        if (prop === "_handleClose") {
+          return () => {
+            target._handleStateExit();
+            target._handleClose();
+          };
+        }
+        if (target._isConsumed) {
+          throw new Error(
+            `${ERR_CONSUMED}: getting ${prop.toString()} on consumed state`
+          );
+        }
+        return Reflect.get(target, prop);
+      },
+      set(target, prop, value) {
+        if (target._isConsumed) {
+          throw new Error(
+            `${ERR_CONSUMED}: setting ${prop.toString()} on consumed state`
+          );
+        }
+        return Reflect.set(target, prop, value);
+      }
+    });
   }
-  get nextExpectedAck() {
-    return this.seq;
+};
+var CommonSession = class extends StateMachineState {
+  from;
+  options;
+  log;
+  constructor(from, options, log) {
+    super();
+    this.from = from;
+    this.options = options;
+    this.log = log;
   }
-  get nextExpectedSeq() {
-    return this.ack;
+  parseMsg(msg) {
+    const parsedMsg = this.options.codec.fromBuffer(msg);
+    if (parsedMsg === null) {
+      const decodedBuffer = new TextDecoder().decode(Buffer.from(msg));
+      this.log?.error(
+        `received malformed msg: ${decodedBuffer}`,
+        this.loggingMetadata
+      );
+      return null;
+    }
+    if (!import_value.Value.Check(OpaqueTransportMessageSchema, parsedMsg)) {
+      this.log?.error(`received invalid msg: ${JSON.stringify(parsedMsg)}`, {
+        ...this.loggingMetadata,
+        validationErrors: [
+          ...import_value.Value.Errors(OpaqueTransportMessageSchema, parsedMsg)
+        ]
+      });
+      return null;
+    }
+    return parsedMsg;
   }
+};
+var IdentifiedSession = class extends CommonSession {
+  id;
+  telemetry;
+  to;
   /**
-   * Check that the peer's next expected seq number matches something that is in our send buffer
-   * _or_ matches our actual next seq.
+   * Index of the message we will send next (excluding handshake)
    */
-  nextExpectedSeqInRange(nextExpectedSeq) {
-    for (const msg of this.sendBuffer) {
-      if (nextExpectedSeq === msg.seq) {
-        return true;
-      }
-    }
-    return nextExpectedSeq === this.seq;
+  seq;
+  /**
+   * Number of unique messages we've received this session (excluding handshake)
+   */
+  ack;
+  sendBuffer;
+  constructor(id, from, to, seq, ack, sendBuffer, telemetry, options, log) {
+    super(from, options, log);
+    this.id = id;
+    this.to = to;
+    this.seq = seq;
+    this.ack = ack;
+    this.sendBuffer = sendBuffer;
+    this.telemetry = telemetry;
+    this.log = log;
   }
-  // This is only used in tests to make the session misbehave.
-  /* @internal */
-  advanceAckForTesting(by) {
-    this.ack += by;
+  get loggingMetadata() {
+    const spanContext = this.telemetry.span.spanContext();
+    return {
+      clientId: this.from,
+      connectedTo: this.to,
+      sessionId: this.id,
+      telemetry: {
+        traceId: spanContext.traceId,
+        spanId: spanContext.spanId
+      }
+    };
   }
   constructMsg(partialMsg) {
     const msg = {
       ...partialMsg,
-      id: unsafeId(),
+      id: generateId(),
       to: this.to,
       from: this.from,
       seq: this.seq,
       ack: this.ack
     };
     this.seq++;
-    this.sendBuffer.push(msg);
     return msg;
   }
-  inspectSendBuffer() {
-    return this.sendBuffer;
+  nextSeq() {
+    return this.sendBuffer.length > 0 ? this.sendBuffer[0].seq : this.seq;
+  }
+  send(msg) {
+    const constructedMsg = this.constructMsg(msg);
+    this.sendBuffer.push(constructedMsg);
+    return constructedMsg.id;
+  }
+  _handleStateExit() {
+  }
+  _handleClose() {
+    this.sendBuffer.length = 0;
+    this.telemetry.span.end();
   }
 };
 
-// transport/transforms/messageFraming.ts
-var import_node_stream = require("stream");
-var Uint32LengthPrefixFraming = class extends import_node_stream.Transform {
-  receivedBuffer;
-  maxBufferSizeBytes;
-  constructor({ maxBufferSizeBytes, ...options }) {
-    super(options);
-    this.maxBufferSizeBytes = maxBufferSizeBytes;
-    this.receivedBuffer = Buffer.alloc(0);
+// transport/sessionStateMachine/SessionConnecting.ts
+var SessionConnecting = class extends IdentifiedSession {
+  state = "Connecting" /* Connecting */;
+  connPromise;
+  listeners;
+  connectionTimeout;
+  constructor(connPromise, listeners, ...args) {
+    super(...args);
+    this.connPromise = connPromise;
+    this.listeners = listeners;
+    this.connectionTimeout = setTimeout(() => {
+      listeners.onConnectionTimeout();
+    }, this.options.connectionTimeoutMs);
+    connPromise.then(
+      (conn) => {
+        if (this._isConsumed)
+          return;
+        listeners.onConnectionEstablished(conn);
+      },
+      (err) => {
+        if (this._isConsumed)
+          return;
+        listeners.onConnectionFailed(err);
+      }
+    );
   }
-  _transform(chunk, _encoding, cb) {
-    if (this.receivedBuffer.byteLength + chunk.byteLength > this.maxBufferSizeBytes) {
-      const err = new Error(
-        `buffer overflow: ${this.receivedBuffer.byteLength}B > ${this.maxBufferSizeBytes}B`
-      );
-      this.emit("error", err);
-      cb(err);
-      return;
-    }
-    this.receivedBuffer = Buffer.concat([this.receivedBuffer, chunk]);
-    while (this.receivedBuffer.length > 4) {
-      const claimedMessageLength = this.receivedBuffer.readUInt32BE(0) + 4;
-      if (this.receivedBuffer.length >= claimedMessageLength) {
-        const message = this.receivedBuffer.subarray(4, claimedMessageLength);
-        this.push(message);
-        this.receivedBuffer = this.receivedBuffer.subarray(claimedMessageLength);
-      } else {
-        break;
-      }
-    }
-    cb();
-  }
-  _flush(cb) {
-    if (this.receivedBuffer.length) {
-      this.emit("error", new Error("got incomplete message while flushing"));
-    }
-    this.receivedBuffer = Buffer.alloc(0);
-    cb();
-  }
-  _destroy(error, callback) {
-    this.receivedBuffer = Buffer.alloc(0);
-    super._destroy(error, callback);
-  }
-};
-function createLengthEncodedStream(options) {
-  return new Uint32LengthPrefixFraming({
-    maxBufferSizeBytes: options?.maxBufferSizeBytes ?? 16 * 1024 * 1024
-    // 16MB
-  });
-}
-var MessageFramer = {
-  createFramedStream: createLengthEncodedStream,
-  write: (buf) => {
-    const lengthPrefix = Buffer.alloc(4);
-    lengthPrefix.writeUInt32BE(buf.length, 0);
-    return Buffer.concat([lengthPrefix, buf]);
-  }
-};
-
-// transport/impls/uds/connection.ts
-var UdsConnection = class extends Connection {
-  sock;
-  input;
-  framer;
-  constructor(sock) {
-    super();
-    this.framer = MessageFramer.createFramedStream();
-    this.sock = sock;
-    this.input = sock.pipe(this.framer);
-  }
-  addDataListener(cb) {
-    this.input.on("data", cb);
-  }
-  removeDataListener(cb) {
-    this.input.off("data", cb);
-  }
-  addCloseListener(cb) {
-    this.sock.on("close", cb);
-  }
-  addErrorListener(cb) {
-    this.sock.on("error", (err) => {
-      if (err instanceof Error && "code" in err && err.code === "EPIPE") {
-        return;
-      }
-      cb(err);
+  // close a pending connection if it resolves, ignore errors if the promise
+  // ends up rejected anyways
+  bestEffortClose() {
+    void this.connPromise.then((conn) => conn.close()).catch(() => {
     });
   }
-  send(payload) {
-    if (this.framer.destroyed || !this.sock.writable)
-      return false;
-    return this.sock.write(MessageFramer.write(payload));
+  _handleStateExit() {
+    super._handleStateExit();
+    clearTimeout(this.connectionTimeout);
+    this.connectionTimeout = void 0;
   }
-  close() {
-    this.sock.destroy();
-    this.framer.destroy();
+  _handleClose() {
+    this.bestEffortClose();
+    super._handleClose();
   }
 };
 
-// transport/server.ts
-var import_api4 = require("@opentelemetry/api");
-
-// 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);
+// transport/sessionStateMachine/SessionNoConnection.ts
+var SessionNoConnection = class extends IdentifiedSession {
+  state = "NoConnection" /* NoConnection */;
+  listeners;
+  gracePeriodTimeout;
+  constructor(listeners, ...args) {
+    super(...args);
+    this.listeners = listeners;
+    this.gracePeriodTimeout = setTimeout(() => {
+      this.listeners.onSessionGracePeriodElapsed();
+    }, this.options.sessionDisconnectGraceMs);
   }
-  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;
+  _handleClose() {
+    super._handleClose();
+  }
+  _handleStateExit() {
+    super._handleStateExit();
+    if (this.gracePeriodTimeout) {
+      clearTimeout(this.gracePeriodTimeout);
+      this.gracePeriodTimeout = void 0;
     }
   }
 };
 
-// transport/options.ts
-var defaultTransportOptions = {
-  heartbeatIntervalMs: 1e3,
-  heartbeatsUntilDead: 2,
-  sessionDisconnectGraceMs: 5e3,
-  codec: NaiveJsonCodec
-};
-var defaultConnectionRetryOptions = {
-  baseIntervalMs: 250,
-  maxJitterMs: 200,
-  maxBackoffMs: 32e3,
-  attemptBudgetCapacity: 5,
-  budgetRestoreIntervalMs: 200
-};
-var defaultClientTransportOptions = {
-  ...defaultTransportOptions,
-  ...defaultConnectionRetryOptions
-};
-var defaultServerTransportOptions = {
-  ...defaultTransportOptions
-};
+// tracing/index.ts
+var import_api = require("@opentelemetry/api");
 
-// transport/transport.ts
-var import_value = require("@sinclair/typebox/value");
+// package.json
+var version = "0.24.0";
 
-// logging/log.ts
-var LoggingLevels = {
-  debug: -1,
-  info: 0,
-  warn: 1,
-  error: 2
-};
-var cleanedLogFn = (log) => {
-  return (msg, metadata) => {
-    if (!metadata?.transportMessage) {
-      log(msg, metadata);
+// tracing/index.ts
+function createSessionTelemetryInfo(sessionId, to, from, propagationCtx) {
+  const parentCtx = propagationCtx ? import_api.propagation.extract(import_api.context.active(), propagationCtx) : import_api.context.active();
+  const span = tracer.startSpan(
+    `session ${sessionId}`,
+    {
+      attributes: {
+        component: "river",
+        "river.session.id": sessionId,
+        "river.session.to": to,
+        "river.session.from": from
+      }
+    },
+    parentCtx
+  );
+  const ctx = import_api.trace.setSpan(parentCtx, span);
+  return { span, ctx };
+}
+var tracer = import_api.trace.getTracer("river", version);
+
+// transport/sessionStateMachine/SessionWaitingForHandshake.ts
+var SessionWaitingForHandshake = class extends CommonSession {
+  state = "WaitingForHandshake" /* WaitingForHandshake */;
+  conn;
+  listeners;
+  handshakeTimeout;
+  constructor(conn, listeners, ...args) {
+    super(...args);
+    this.conn = conn;
+    this.listeners = listeners;
+    this.handshakeTimeout = setTimeout(() => {
+      listeners.onHandshakeTimeout();
+    }, this.options.handshakeTimeoutMs);
+    this.conn.addDataListener(this.onHandshakeData);
+    this.conn.addErrorListener(listeners.onConnectionErrored);
+    this.conn.addCloseListener(listeners.onConnectionClosed);
+  }
+  onHandshakeData = (msg) => {
+    const parsedMsg = this.parseMsg(msg);
+    if (parsedMsg === null) {
+      this.listeners.onInvalidHandshake("could not parse message");
       return;
     }
-    const { payload, ...rest } = metadata.transportMessage;
-    metadata.transportMessage = rest;
-    log(msg, metadata);
+    this.listeners.onHandshake(parsedMsg);
   };
-};
-var BaseLogger = class {
-  minLevel;
-  output;
-  constructor(output, minLevel = "info") {
-    this.minLevel = minLevel;
-    this.output = output;
-  }
-  debug(msg, metadata) {
-    if (LoggingLevels[this.minLevel] <= LoggingLevels.debug) {
-      this.output(msg, metadata ?? {}, "debug");
-    }
+  get loggingMetadata() {
+    return {
+      clientId: this.from,
+      connId: this.conn.id
+    };
   }
-  info(msg, metadata) {
-    if (LoggingLevels[this.minLevel] <= LoggingLevels.info) {
-      this.output(msg, metadata ?? {}, "info");
-    }
+  sendHandshake(msg) {
+    return this.conn.send(this.options.codec.toBuffer(msg));
   }
-  warn(msg, metadata) {
-    if (LoggingLevels[this.minLevel] <= LoggingLevels.warn) {
-      this.output(msg, metadata ?? {}, "warn");
-    }
+  _handleStateExit() {
+    this.conn.removeDataListener(this.onHandshakeData);
+    this.conn.removeErrorListener(this.listeners.onConnectionErrored);
+    this.conn.removeCloseListener(this.listeners.onConnectionClosed);
+    clearTimeout(this.handshakeTimeout);
+    this.handshakeTimeout = void 0;
   }
-  error(msg, metadata) {
-    if (LoggingLevels[this.minLevel] <= LoggingLevels.error) {
-      this.output(msg, metadata ?? {}, "error");
-    }
+  _handleClose() {
+    this.conn.close();
   }
 };
-var createLogProxy = (log) => ({
-  debug: cleanedLogFn(log.debug.bind(log)),
-  info: cleanedLogFn(log.info.bind(log)),
-  warn: cleanedLogFn(log.warn.bind(log)),
-  error: cleanedLogFn(log.error.bind(log))
-});
 
-// transport/events.ts
-var ProtocolError = {
-  RetriesExceeded: "conn_retry_exceeded",
-  HandshakeFailed: "handshake_failed",
-  MessageOrderingViolated: "message_ordering_violated"
-};
-var EventDispatcher = class {
-  eventListeners = {};
-  removeAllListeners() {
-    this.eventListeners = {};
-  }
-  numberOfListeners(eventType) {
-    return this.eventListeners[eventType]?.size ?? 0;
-  }
-  addEventListener(eventType, handler) {
-    if (!this.eventListeners[eventType]) {
-      this.eventListeners[eventType] = /* @__PURE__ */ new Set();
+// transport/sessionStateMachine/SessionHandshaking.ts
+var SessionHandshaking = class extends IdentifiedSession {
+  state = "Handshaking" /* Handshaking */;
+  conn;
+  listeners;
+  handshakeTimeout;
+  constructor(conn, listeners, ...args) {
+    super(...args);
+    this.conn = conn;
+    this.listeners = listeners;
+    this.handshakeTimeout = setTimeout(() => {
+      listeners.onHandshakeTimeout();
+    }, this.options.handshakeTimeoutMs);
+    this.conn.addDataListener(this.onHandshakeData);
+    this.conn.addErrorListener(listeners.onConnectionErrored);
+    this.conn.addCloseListener(listeners.onConnectionClosed);
+  }
+  onHandshakeData = (msg) => {
+    const parsedMsg = this.parseMsg(msg);
+    if (parsedMsg === null) {
+      this.listeners.onInvalidHandshake("could not parse message");
+      return;
     }
-    this.eventListeners[eventType]?.add(handler);
+    this.listeners.onHandshake(parsedMsg);
+  };
+  sendHandshake(msg) {
+    return this.conn.send(this.options.codec.toBuffer(msg));
   }
-  removeEventListener(eventType, handler) {
-    const handlers = this.eventListeners[eventType];
-    if (handlers) {
-      this.eventListeners[eventType]?.delete(handler);
-    }
+  _handleStateExit() {
+    super._handleStateExit();
+    this.conn.removeDataListener(this.onHandshakeData);
+    this.conn.removeErrorListener(this.listeners.onConnectionErrored);
+    this.conn.removeCloseListener(this.listeners.onConnectionClosed);
+    clearTimeout(this.handshakeTimeout);
   }
-  dispatchEvent(eventType, event) {
-    const handlers = this.eventListeners[eventType];
-    if (handlers) {
-      const copy = [...handlers];
-      for (const handler of copy) {
-        handler(event);
-      }
-    }
+  _handleClose() {
+    super._handleClose();
+    this.conn.close();
   }
 };
 
-// transport/transport.ts
-var import_api3 = require("@opentelemetry/api");
-var Transport = class {
-  /**
-   * The status of the transport.
-   */
-  status;
-  /**
-   * The {@link Codec} used to encode and decode messages.
-   */
-  codec;
-  /**
-   * The client ID of this transport.
-   */
-  clientId;
-  /**
-   * The map of {@link Session}s managed by this transport.
-   */
-  sessions;
-  /**
-   * The map of {@link Connection}s managed by this transport.
-   */
-  get connections() {
-    return new Map(
-      [...this.sessions].map(([client, session]) => [client, session.connection]).filter((entry) => entry[1] !== void 0)
-    );
+// transport/sessionStateMachine/SessionConnected.ts
+var import_api2 = require("@opentelemetry/api");
+var SessionConnected = class extends IdentifiedSession {
+  state = "Connected" /* Connected */;
+  conn;
+  listeners;
+  heartbeatHandle;
+  heartbeatMisses = 0;
+  get isActivelyHeartbeating() {
+    return this.heartbeatHandle !== void 0;
   }
-  /**
-   * The event dispatcher for handling events of type EventTypes.
-   */
-  eventDispatcher;
-  /**
-   * The options for this transport.
-   */
-  options;
-  log;
-  /**
-   * 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(clientId, providedOptions) {
-    this.options = { ...defaultTransportOptions, ...providedOptions };
-    this.eventDispatcher = new EventDispatcher();
-    this.sessions = /* @__PURE__ */ new Map();
-    this.codec = this.options.codec;
-    this.clientId = clientId;
-    this.status = "open";
+  updateBookkeeping(ack, seq) {
+    this.sendBuffer = this.sendBuffer.filter((unacked) => unacked.seq >= ack);
+    this.ack = seq + 1;
+    this.heartbeatMisses = 0;
   }
-  bindLogger(fn, level) {
-    if (typeof fn === "function") {
-      this.log = createLogProxy(new BaseLogger(fn, level));
-      return;
+  send(msg) {
+    const constructedMsg = this.constructMsg(msg);
+    this.sendBuffer.push(constructedMsg);
+    this.conn.send(this.options.codec.toBuffer(constructedMsg));
+    return constructedMsg.id;
+  }
+  constructor(conn, listeners, ...args) {
+    super(...args);
+    this.conn = conn;
+    this.listeners = listeners;
+    this.conn.addDataListener(this.onMessageData);
+    this.conn.addCloseListener(listeners.onConnectionClosed);
+    this.conn.addErrorListener(listeners.onConnectionErrored);
+    if (this.sendBuffer.length > 0) {
+      this.log?.debug(
+        `sending ${this.sendBuffer.length} buffered messages`,
+        this.loggingMetadata
+      );
+    }
+    for (const msg of this.sendBuffer) {
+      conn.send(this.options.codec.toBuffer(msg));
     }
-    this.log = createLogProxy(fn);
   }
-  /**
-   * Called when a new connection is established
-   * and we know the identity of the connected client.
-   * @param conn The connection object.
-   */
-  onConnect(conn, session, isTransparentReconnect) {
-    this.eventDispatcher.dispatchEvent("connectionStatus", {
-      status: "connect",
-      conn
-    });
-    conn.telemetry = createConnectionTelemetryInfo(conn, session.telemetry);
-    session.replaceWithNewConnection(conn, isTransparentReconnect);
-    this.log?.info(`connected to ${session.to}`, {
-      ...conn.loggingMetadata,
-      ...session.loggingMetadata
+  startActiveHeartbeat() {
+    this.heartbeatHandle = setInterval(() => {
+      const misses = this.heartbeatMisses;
+      const missDuration = misses * this.options.heartbeatIntervalMs;
+      if (misses >= this.options.heartbeatsUntilDead) {
+        this.log?.info(
+          `closing connection to ${this.to} due to inactivity (missed ${misses} heartbeats which is ${missDuration}ms)`,
+          this.loggingMetadata
+        );
+        this.telemetry.span.addEvent("closing connection due to inactivity");
+        this.conn.close();
+        clearInterval(this.heartbeatHandle);
+        this.heartbeatHandle = void 0;
+        return;
+      }
+      this.sendHeartbeat();
+      this.heartbeatMisses++;
+    }, this.options.heartbeatIntervalMs);
+  }
+  sendHeartbeat() {
+    this.send({
+      streamId: "heartbeat",
+      controlFlags: 1 /* AckBit */,
+      payload: {
+        type: "ACK"
+      }
     });
   }
-  createSession(to, conn, propagationCtx) {
-    const session = new Session(
-      conn,
-      this.clientId,
-      to,
-      this.options,
-      propagationCtx
-    );
-    if (this.log) {
-      session.bindLogger(this.log);
-    }
-    const currentSession = this.sessions.get(session.to);
-    if (currentSession) {
-      this.log?.warn(
-        `session ${session.id} from ${session.to} surreptitiously replacing ${currentSession.id}`,
-        {
-          ...currentSession.loggingMetadata,
+  onMessageData = (msg) => {
+    const parsedMsg = this.parseMsg(msg);
+    if (parsedMsg === null)
+      return;
+    if (parsedMsg.seq !== this.ack) {
+      if (parsedMsg.seq < this.ack) {
+        this.log?.debug(
+          `received duplicate msg (got seq: ${parsedMsg.seq}, wanted seq: ${this.ack}), discarding`,
+          {
+            ...this.loggingMetadata,
+            transportMessage: parsedMsg
+          }
+        );
+      } else {
+        const reason = `received out-of-order msg (got seq: ${parsedMsg.seq}, wanted seq: ${this.ack})`;
+        this.log?.error(reason, {
+          ...this.loggingMetadata,
+          transportMessage: parsedMsg,
           tags: ["invariant-violation"]
-        }
-      );
-      this.deleteSession({
-        session: currentSession,
-        closeHandshakingConnection: false
-      });
+        });
+        this.telemetry.span.setStatus({
+          code: import_api2.SpanStatusCode.ERROR,
+          message: reason
+        });
+        this.listeners.onInvalidMessage(reason);
+      }
+      return;
     }
-    this.sessions.set(session.to, session);
-    this.eventDispatcher.dispatchEvent("sessionStatus", {
-      status: "connect",
-      session
+    this.log?.debug(`received msg`, {
+      ...this.loggingMetadata,
+      transportMessage: parsedMsg
     });
-    return session;
-  }
-  createNewSession({
-    to,
-    conn,
-    sessionId,
-    propagationCtx
-  }) {
-    let session = this.sessions.get(to);
-    if (session !== void 0) {
-      this.log?.info(
-        `session for ${to} already exists, replacing it with a new session as requested`,
-        session.loggingMetadata
-      );
-      this.deleteSession({
-        session,
-        closeHandshakingConnection: false
-      });
-      session = void 0;
+    this.updateBookkeeping(parsedMsg.ack, parsedMsg.seq);
+    if (!isAck(parsedMsg.controlFlags)) {
+      this.listeners.onMessage(parsedMsg);
+      return;
     }
-    session = this.createSession(to, conn, propagationCtx);
-    session.advertisedSessionId = sessionId;
-    this.log?.info(`created new session for ${to}`, session.loggingMetadata);
-    return session;
-  }
-  getExistingSession({
-    to,
-    sessionId,
-    nextExpectedSeq
-  }) {
-    const session = this.sessions.get(to);
-    if (
-      // reject this request if there was no previous session to replace
-      session === void 0 || // or if both parties do not agree about the next expected sequence number
-      !session.nextExpectedSeqInRange(nextExpectedSeq) || // or if both parties do not agree on the advertised session id
-      session.advertisedSessionId !== sessionId
-    ) {
-      return false;
+    this.log?.debug(`discarding msg (ack bit set)`, {
+      ...this.loggingMetadata,
+      transportMessage: parsedMsg
+    });
+    if (!this.isActivelyHeartbeating) {
+      this.sendHeartbeat();
     }
-    this.log?.info(
-      `reused existing session for ${to}`,
-      session.loggingMetadata
-    );
-    return session;
+  };
+  _handleStateExit() {
+    super._handleStateExit();
+    this.conn.removeDataListener(this.onMessageData);
+    this.conn.removeCloseListener(this.listeners.onConnectionClosed);
+    this.conn.removeErrorListener(this.listeners.onConnectionErrored);
+    clearInterval(this.heartbeatHandle);
+    this.heartbeatHandle = void 0;
+  }
+  _handleClose() {
+    super._handleClose();
+    this.conn.close();
   }
-  getOrCreateSession({
-    to,
-    conn,
-    handshakingConn,
-    sessionId,
-    propagationCtx
-  }) {
-    let session = this.sessions.get(to);
-    const isReconnect = session !== void 0;
-    let isTransparentReconnect = isReconnect;
-    if (session?.advertisedSessionId !== void 0 && sessionId !== void 0 && session.advertisedSessionId !== sessionId) {
-      this.log?.info(
-        `session for ${to} already exists but has a different session id (expected: ${session.advertisedSessionId}, got: ${sessionId}), creating a new one`,
-        session.loggingMetadata
+};
+
+// transport/sessionStateMachine/transitions.ts
+function inheritSharedSession(session) {
+  return [
+    session.id,
+    session.from,
+    session.to,
+    session.seq,
+    session.ack,
+    session.sendBuffer,
+    session.telemetry,
+    session.options,
+    session.log
+  ];
+}
+var SessionStateGraph = {
+  entrypoints: {
+    NoConnection(to, from, listeners, options, log) {
+      const id = `session-${generateId()}`;
+      const telemetry = createSessionTelemetryInfo(id, to, from);
+      const sendBuffer = [];
+      const session = new SessionNoConnection(
+        listeners,
+        id,
+        from,
+        to,
+        0,
+        0,
+        sendBuffer,
+        telemetry,
+        options,
+        log
       );
-      this.deleteSession({
-        session,
-        closeHandshakingConnection: handshakingConn !== void 0,
-        handshakingConn
+      session.log?.info(`session ${session.id} created in NoConnection state`, {
+        ...session.loggingMetadata,
+        tags: ["state-transition"]
       });
-      isTransparentReconnect = false;
-      session = void 0;
-    }
-    if (!session) {
-      session = this.createSession(to, conn, propagationCtx);
-      this.log?.info(
-        `no session for ${to}, created a new one`,
-        session.loggingMetadata
+      return session;
+    },
+    WaitingForHandshake(from, conn, listeners, options, log) {
+      const session = new SessionWaitingForHandshake(
+        conn,
+        listeners,
+        from,
+        options,
+        log
       );
+      session.log?.info(`session created in WaitingForHandshake state`, {
+        ...session.loggingMetadata,
+        tags: ["state-transition"]
+      });
+      return session;
     }
-    if (sessionId !== void 0) {
-      session.advertisedSessionId = sessionId;
-    }
-    if (handshakingConn !== void 0) {
-      session.replaceWithNewHandshakingConnection(handshakingConn);
-    }
-    return { session, isReconnect, isTransparentReconnect };
-  }
-  deleteSession({
-    session,
-    closeHandshakingConnection,
-    handshakingConn
-  }) {
-    if (closeHandshakingConnection) {
-      session.closeHandshakingConnection(handshakingConn);
-    }
-    session.close();
-    session.telemetry.span.end();
-    const currentSession = this.sessions.get(session.to);
-    if (currentSession && currentSession.id !== session.id) {
-      this.log?.warn(
-        `session ${session.id} disconnect from ${session.to}, mismatch with ${currentSession.id}`,
+  },
+  // All of the transitions 'move'/'consume' the old session and return a new one.
+  // After a session is transitioned, any usage of the old session will throw.
+  transition: {
+    // happy path transitions
+    NoConnectionToConnecting(oldSession, connPromise, listeners) {
+      const carriedState = inheritSharedSession(oldSession);
+      oldSession._handleStateExit();
+      const session = new SessionConnecting(
+        connPromise,
+        listeners,
+        ...carriedState
+      );
+      session.log?.info(
+        `session ${session.id} transition from NoConnection to Connecting`,
         {
           ...session.loggingMetadata,
-          tags: ["invariant-violation"]
+          tags: ["state-transition"]
         }
       );
-      return;
+      return session;
+    },
+    ConnectingToHandshaking(oldSession, conn, listeners) {
+      const carriedState = inheritSharedSession(oldSession);
+      oldSession._handleStateExit();
+      const session = new SessionHandshaking(conn, listeners, ...carriedState);
+      session.log?.info(
+        `session ${session.id} transition from Connecting to Handshaking`,
+        {
+          ...session.loggingMetadata,
+          tags: ["state-transition"]
+        }
+      );
+      return session;
+    },
+    HandshakingToConnected(oldSession, listeners) {
+      const carriedState = inheritSharedSession(oldSession);
+      const conn = oldSession.conn;
+      oldSession._handleStateExit();
+      const session = new SessionConnected(conn, listeners, ...carriedState);
+      session.log?.info(
+        `session ${session.id} transition from Handshaking to Connected`,
+        {
+          ...session.loggingMetadata,
+          tags: ["state-transition"]
+        }
+      );
+      return session;
+    },
+    WaitingForHandshakeToConnected(pendingSession, oldSession, sessionId, to, propagationCtx, listeners) {
+      const conn = pendingSession.conn;
+      const { from, options } = pendingSession;
+      const carriedState = oldSession ? (
+        // old session exists, inherit state
+        inheritSharedSession(oldSession)
+      ) : (
+        // old session does not exist, create new state
+        [
+          sessionId,
+          from,
+          to,
+          0,
+          0,
+          [],
+          createSessionTelemetryInfo(sessionId, to, from, propagationCtx),
+          options,
+          pendingSession.log
+        ]
+      );
+      pendingSession._handleStateExit();
+      oldSession?._handleStateExit();
+      const session = new SessionConnected(conn, listeners, ...carriedState);
+      session.log?.info(
+        `session ${session.id} transition from WaitingForHandshake to Connected`,
+        {
+          ...session.loggingMetadata,
+          tags: ["state-transition"]
+        }
+      );
+      return session;
+    },
+    // disconnect paths
+    ConnectingToNoConnection(oldSession, listeners) {
+      const carriedState = inheritSharedSession(oldSession);
+      oldSession.bestEffortClose();
+      oldSession._handleStateExit();
+      const session = new SessionNoConnection(listeners, ...carriedState);
+      session.log?.info(
+        `session ${session.id} transition from Connecting to NoConnection`,
+        {
+          ...session.loggingMetadata,
+          tags: ["state-transition"]
+        }
+      );
+      return session;
+    },
+    HandshakingToNoConnection(oldSession, listeners) {
+      const carriedState = inheritSharedSession(oldSession);
+      oldSession.conn.close();
+      oldSession._handleStateExit();
+      const session = new SessionNoConnection(listeners, ...carriedState);
+      session.log?.info(
+        `session ${session.id} transition from Handshaking to NoConnection`,
+        {
+          ...session.loggingMetadata,
+          tags: ["state-transition"]
+        }
+      );
+      return session;
+    },
+    ConnectedToNoConnection(oldSession, listeners) {
+      const carriedState = inheritSharedSession(oldSession);
+      oldSession.conn.close();
+      oldSession._handleStateExit();
+      const session = new SessionNoConnection(listeners, ...carriedState);
+      session.log?.info(
+        `session ${session.id} transition from Connected to NoConnection`,
+        {
+          ...session.loggingMetadata,
+          tags: ["state-transition"]
+        }
+      );
+      return session;
     }
-    this.sessions.delete(session.to);
-    this.log?.info(
-      `session ${session.id} disconnect from ${session.to}`,
-      session.loggingMetadata
-    );
-    this.eventDispatcher.dispatchEvent("sessionStatus", {
-      status: "disconnect",
-      session
-    });
   }
+};
+
+// transport/transport.ts
+var Transport = class {
   /**
-   * The downstream implementation needs to call this when a connection is closed.
-   * @param conn The connection object.
-   * @param connectedTo The peer we are connected to.
+   * The status of the transport.
    */
-  onDisconnect(conn, session) {
-    if (session.connection !== void 0 && session.connection.id !== conn.id) {
-      session.telemetry.span.addEvent("onDisconnect race");
-      this.log?.warn("onDisconnect race", {
-        clientId: this.clientId,
-        ...session.loggingMetadata,
-        ...conn.loggingMetadata,
-        tags: ["invariant-violation"]
-      });
-      return;
-    }
-    conn.telemetry?.span.end();
-    this.eventDispatcher.dispatchEvent("connectionStatus", {
-      status: "disconnect",
-      conn
-    });
-    session.connection = void 0;
-    session.beginGrace(() => {
-      if (session.connection !== void 0) {
-        session.telemetry.span.addEvent("session grace period race");
-        this.log?.warn("session grace period race", {
-          clientId: this.clientId,
-          ...session.loggingMetadata,
-          ...conn.loggingMetadata,
-          tags: ["invariant-violation"]
-        });
-        return;
-      }
-      session.telemetry.span.addEvent("session grace period expired");
-      this.deleteSession({
-        session,
-        closeHandshakingConnection: true,
-        handshakingConn: conn
-      });
-    });
-  }
+  status;
   /**
-   * Parses a message from a Uint8Array into a {@link OpaqueTransportMessage}.
-   * @param msg The message to parse.
-   * @returns The parsed message, or null if the message is malformed or invalid.
+   * The client ID of this transport.
    */
-  parseMsg(msg, conn) {
-    const parsedMsg = this.codec.fromBuffer(msg);
-    if (parsedMsg === null) {
-      const decodedBuffer = new TextDecoder().decode(Buffer.from(msg));
-      this.log?.error(
-        `received malformed msg, killing conn: ${decodedBuffer}`,
-        {
-          clientId: this.clientId,
-          ...conn.loggingMetadata
-        }
-      );
-      return null;
-    }
-    if (!import_value.Value.Check(OpaqueTransportMessageSchema, parsedMsg)) {
-      this.log?.error(`received invalid msg: ${JSON.stringify(parsedMsg)}`, {
-        clientId: this.clientId,
-        ...conn.loggingMetadata,
-        validationErrors: [
-          ...import_value.Value.Errors(OpaqueTransportMessageSchema, parsedMsg)
-        ]
-      });
-      return null;
+  clientId;
+  /**
+   * The event dispatcher for handling events of type EventTypes.
+   */
+  eventDispatcher;
+  /**
+   * The options for this transport.
+   */
+  options;
+  log;
+  sessions;
+  /**
+   * Creates a new Transport instance.
+   * @param codec The codec used to encode and decode messages.
+   * @param clientId The client ID of this transport.
+   */
+  constructor(clientId, providedOptions) {
+    this.options = { ...defaultTransportOptions, ...providedOptions };
+    this.eventDispatcher = new EventDispatcher();
+    this.clientId = clientId;
+    this.status = "open";
+    this.sessions = /* @__PURE__ */ new Map();
+  }
+  bindLogger(fn, level) {
+    if (typeof fn === "function") {
+      this.log = createLogProxy(new BaseLogger(fn, level));
+      return;
     }
-    return parsedMsg;
+    this.log = createLogProxy(fn);
   }
   /**
    * Called when a message is received by this transport.
    * You generally shouldn't need to override this in downstream transport implementations.
    * @param msg The received message.
    */
-  handleMsg(msg, conn) {
+  handleMsg(msg) {
     if (this.getStatus() !== "open")
       return;
-    const session = this.sessions.get(msg.from);
-    if (!session) {
-      this.log?.error(`received message for unknown session from ${msg.from}`, {
-        clientId: this.clientId,
-        transportMessage: msg,
-        ...conn.loggingMetadata,
-        tags: ["invariant-violation"]
-      });
-      return;
-    }
-    session.cancelGrace();
-    this.log?.debug(`received msg`, {
-      clientId: this.clientId,
-      transportMessage: msg,
-      ...conn.loggingMetadata
-    });
-    if (msg.seq !== session.nextExpectedSeq) {
-      if (msg.seq < session.nextExpectedSeq) {
-        this.log?.debug(
-          `received duplicate msg (got seq: ${msg.seq}, wanted seq: ${session.nextExpectedSeq}), discarding`,
-          {
-            clientId: this.clientId,
-            transportMessage: msg,
-            ...conn.loggingMetadata
-          }
-        );
-      } else {
-        const errMsg = `received out-of-order msg (got seq: ${msg.seq}, wanted seq: ${session.nextExpectedSeq})`;
-        this.log?.error(`${errMsg}, marking connection as dead`, {
-          clientId: this.clientId,
-          transportMessage: msg,
-          ...conn.loggingMetadata,
-          tags: ["invariant-violation"]
-        });
-        this.protocolError(ProtocolError.MessageOrderingViolated, errMsg);
-        session.telemetry.span.setStatus({
-          code: import_api3.SpanStatusCode.ERROR,
-          message: "message order violated"
-        });
-        this.deleteSession({ session, closeHandshakingConnection: true });
-      }
-      return;
-    }
-    session.updateBookkeeping(msg.ack, msg.seq);
-    if (!isAck(msg.controlFlags)) {
-      this.eventDispatcher.dispatchEvent("message", msg);
-    } else {
-      this.log?.debug(`discarding msg (ack bit set)`, {
-        clientId: this.clientId,
-        transportMessage: msg,
-        ...conn.loggingMetadata
-      });
-    }
+    this.eventDispatcher.dispatchEvent("message", msg);
   }
   /**
    * Adds a listener to this transport.
@@ -1107,34 +1176,6 @@ var Transport = class {
   removeEventListener(type, handler) {
     this.eventDispatcher.removeEventListener(type, handler);
   }
-  /**
-   * 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 or undefined if it wasn't sent
-   */
-  send(to, msg) {
-    if (this.getStatus() === "closed") {
-      const err = "transport is closed, cant send";
-      this.log?.error(err, {
-        clientId: this.clientId,
-        transportMessage: msg,
-        tags: ["invariant-violation"]
-      });
-      throw new Error(err);
-    }
-    return this.getOrCreateSession({ to }).session.send(msg);
-  }
-  // control helpers
-  sendCloseStream(to, streamId) {
-    return this.send(to, {
-      streamId,
-      controlFlags: 4 /* StreamClosedBit */,
-      payload: {
-        type: "CLOSE"
-      }
-    });
-  }
   protocolError(type, message) {
     this.eventDispatcher.dispatchEvent("protocolError", { type, message });
   }
@@ -1146,7 +1187,7 @@ var Transport = class {
   close() {
     this.status = "closed";
     for (const session of this.sessions.values()) {
-      this.deleteSession({ session, closeHandshakingConnection: true });
+      this.deleteSession(session);
     }
     this.eventDispatcher.dispatchEvent("transportStatus", {
       status: this.status
@@ -1157,6 +1198,68 @@ var Transport = class {
   getStatus() {
     return this.status;
   }
+  updateSession(session) {
+    const activeSession = this.sessions.get(session.to);
+    if (activeSession && activeSession.id !== session.id) {
+      const msg = `attempt to transition active session for ${session.to} but active session (${activeSession.id}) is different from handle (${session.id})`;
+      throw new Error(msg);
+    }
+    this.sessions.set(session.to, session);
+    if (!activeSession) {
+      this.eventDispatcher.dispatchEvent("sessionStatus", {
+        status: "connect",
+        session
+      });
+    }
+    this.eventDispatcher.dispatchEvent("sessionTransition", {
+      state: session.state,
+      session
+    });
+    return session;
+  }
+  // state transitions
+  deleteSession(session) {
+    session.log?.info(`closing session ${session.id}`, session.loggingMetadata);
+    this.eventDispatcher.dispatchEvent("sessionStatus", {
+      status: "disconnect",
+      session
+    });
+    session.close();
+    this.sessions.delete(session.to);
+  }
+  // common listeners
+  onSessionGracePeriodElapsed(session) {
+    this.log?.warn(
+      `session to ${session.to} grace period elapsed, closing`,
+      session.loggingMetadata
+    );
+    this.deleteSession(session);
+  }
+  onConnectingFailed(session) {
+    const noConnectionSession = SessionStateGraph.transition.ConnectingToNoConnection(session, {
+      onSessionGracePeriodElapsed: () => {
+        this.onSessionGracePeriodElapsed(noConnectionSession);
+      }
+    });
+    return this.updateSession(noConnectionSession);
+  }
+  onConnClosed(session) {
+    let noConnectionSession;
+    if (session.state === "Handshaking" /* Handshaking */) {
+      noConnectionSession = SessionStateGraph.transition.HandshakingToNoConnection(session, {
+        onSessionGracePeriodElapsed: () => {
+          this.onSessionGracePeriodElapsed(noConnectionSession);
+        }
+      });
+    } else {
+      noConnectionSession = SessionStateGraph.transition.ConnectedToNoConnection(session, {
+        onSessionGracePeriodElapsed: () => {
+          this.onSessionGracePeriodElapsed(noConnectionSession);
+        }
+      });
+    }
+    return this.updateSession(noConnectionSession);
+  }
 };
 
 // util/stringify.ts
@@ -1181,14 +1284,14 @@ var ServerTransport = class extends Transport {
   /**
    * A map of session handshake data for each session.
    */
-  sessionHandshakeMetadata;
+  sessionHandshakeMetadata = /* @__PURE__ */ new Map();
+  pendingSessions = /* @__PURE__ */ new Set();
   constructor(clientId, providedOptions) {
     super(clientId, providedOptions);
     this.options = {
       ...defaultServerTransportOptions,
       ...providedOptions
     };
-    this.sessionHandshakeMetadata = /* @__PURE__ */ new WeakMap();
     this.log?.info(`initiated server transport`, {
       clientId: this.clientId,
       protocolVersion: PROTOCOL_VERSION
@@ -1197,6 +1300,36 @@ var ServerTransport = class extends Transport {
   extendHandshake(options) {
     this.handshakeExtensions = options;
   }
+  send(to, msg) {
+    if (this.getStatus() === "closed") {
+      const err = "transport is closed, cant send";
+      this.log?.error(err, {
+        clientId: this.clientId,
+        transportMessage: msg,
+        tags: ["invariant-violation"]
+      });
+      throw new Error(err);
+    }
+    const session = this.sessions.get(to);
+    if (!session) {
+      const err = `session to ${to} does not exist`;
+      this.log?.error(err, {
+        clientId: this.clientId,
+        transportMessage: msg,
+        tags: ["invariant-violation"]
+      });
+      throw new Error(err);
+    }
+    return session.send(msg);
+  }
+  deletePendingSession(pendingSession) {
+    pendingSession.close();
+    this.pendingSessions.delete(pendingSession);
+  }
+  deleteSession(session) {
+    this.sessionHandshakeMetadata.delete(session.to);
+    super.deleteSession(session);
+  }
   handleConnection(conn) {
     if (this.getStatus() !== "open")
       return;
@@ -1204,281 +1337,298 @@ var ServerTransport = class extends Transport {
       ...conn.loggingMetadata,
       clientId: this.clientId
     });
-    let session = void 0;
-    const client = () => session?.to ?? "unknown";
-    const handshakeTimeout = setTimeout(() => {
-      if (!session) {
-        this.log?.warn(
-          `connection to ${client()} timed out waiting for handshake, closing`,
-          {
-            ...conn.loggingMetadata,
-            clientId: this.clientId,
-            connectedTo: client()
-          }
-        );
-        conn.telemetry?.span.setStatus({
-          code: import_api4.SpanStatusCode.ERROR,
-          message: "handshake timeout"
-        });
-        conn.close();
-      }
-    }, this.options.sessionDisconnectGraceMs);
-    const buffer = [];
-    let receivedHandshakeMessage = false;
-    const handshakeHandler = (data) => {
-      if (receivedHandshakeMessage) {
-        buffer.push(data);
-        return;
-      }
-      receivedHandshakeMessage = true;
-      clearTimeout(handshakeTimeout);
-      void this.receiveHandshakeRequestMessage(data, conn).then(
-        (maybeSession) => {
-          if (!maybeSession) {
-            conn.close();
+    let receivedHandshake = false;
+    const pendingSession = SessionStateGraph.entrypoints.WaitingForHandshake(
+      this.clientId,
+      conn,
+      {
+        onConnectionClosed: () => {
+          this.log?.warn(
+            `connection from unknown closed before handshake finished`,
+            pendingSession.loggingMetadata
+          );
+          this.deletePendingSession(pendingSession);
+        },
+        onConnectionErrored: (err) => {
+          const errorString = coerceErrorString(err);
+          this.log?.warn(
+            `connection from unknown errored before handshake finished: ${errorString}`,
+            pendingSession.loggingMetadata
+          );
+          this.deletePendingSession(pendingSession);
+        },
+        onHandshakeTimeout: () => {
+          this.log?.warn(
+            `connection from unknown timed out before handshake finished`,
+            pendingSession.loggingMetadata
+          );
+          this.deletePendingSession(pendingSession);
+        },
+        onHandshake: (msg) => {
+          if (receivedHandshake) {
+            this.log?.error(
+              `received multiple handshake messages from pending session`,
+              {
+                ...pendingSession.loggingMetadata,
+                connectedTo: msg.from,
+                transportMessage: msg
+              }
+            );
+            this.deletePendingSession(pendingSession);
             return;
           }
-          session = maybeSession;
-          const dataHandler = (data2) => {
-            const parsed = this.parseMsg(data2, conn);
-            if (!parsed) {
-              conn.close();
-              return;
-            }
-            this.handleMsg(parsed, conn);
-          };
-          for (const data2 of buffer) {
-            dataHandler(data2);
-          }
-          conn.removeDataListener(handshakeHandler);
-          conn.addDataListener(dataHandler);
-          buffer.length = 0;
+          receivedHandshake = true;
+          void this.onHandshakeRequest(pendingSession, msg);
+        },
+        onInvalidHandshake: (reason) => {
+          this.log?.error(
+            `invalid handshake: ${reason}`,
+            pendingSession.loggingMetadata
+          );
+          this.deletePendingSession(pendingSession);
+          this.protocolError(ProtocolError.HandshakeFailed, reason);
         }
-      );
-    };
-    conn.addDataListener(handshakeHandler);
-    conn.addCloseListener(() => {
-      if (!session)
-        return;
-      this.log?.info(`connection to ${client()} disconnected`, {
-        ...conn.loggingMetadata,
-        clientId: this.clientId
-      });
-      this.onDisconnect(conn, session);
-    });
-    conn.addErrorListener((err) => {
-      conn.telemetry?.span.setStatus({
-        code: import_api4.SpanStatusCode.ERROR,
-        message: "connection error"
-      });
-      if (!session)
-        return;
-      this.log?.warn(
-        `connection to ${client()} got an error: ${coerceErrorString(err)}`,
-        { ...conn.loggingMetadata, clientId: this.clientId }
-      );
-    });
-  }
-  async validateHandshakeMetadata(conn, session, rawMetadata, from) {
-    let parsedMetadata = {};
-    if (this.handshakeExtensions) {
-      if (!import_value2.Value.Check(this.handshakeExtensions.schema, rawMetadata)) {
-        conn.telemetry?.span.setStatus({
-          code: import_api4.SpanStatusCode.ERROR,
-          message: "malformed handshake meta"
-        });
-        const reason = "received malformed handshake metadata";
-        const responseMsg = handshakeResponseMessage({
-          from: this.clientId,
-          to: from,
-          status: {
-            ok: false,
-            reason
-          }
-        });
-        conn.send(this.codec.toBuffer(responseMsg));
-        this.log?.warn(`received malformed handshake metadata from ${from}`, {
-          ...conn.loggingMetadata,
-          clientId: this.clientId,
-          validationErrors: [
-            ...import_value2.Value.Errors(this.handshakeExtensions.schema, rawMetadata)
-          ]
-        });
-        this.protocolError(ProtocolError.HandshakeFailed, reason);
-        return false;
-      }
-      const previousParsedMetadata = session ? this.sessionHandshakeMetadata.get(session) : void 0;
-      parsedMetadata = await this.handshakeExtensions.validate(
-        rawMetadata,
-        previousParsedMetadata
-      );
-      if (parsedMetadata === false) {
-        const reason = "rejected by handshake handler";
-        conn.telemetry?.span.setStatus({
-          code: import_api4.SpanStatusCode.ERROR,
-          message: reason
-        });
-        const responseMsg = handshakeResponseMessage({
-          from: this.clientId,
-          to: from,
-          status: {
-            ok: false,
-            reason
-          }
-        });
-        conn.send(this.codec.toBuffer(responseMsg));
-        this.log?.warn(`rejected handshake from ${from}`, {
-          ...conn.loggingMetadata,
-          clientId: this.clientId
-        });
-        this.protocolError(ProtocolError.HandshakeFailed, reason);
-        return false;
-      }
-    }
-    return parsedMetadata;
+      },
+      this.options,
+      this.log
+    );
+    this.pendingSessions.add(pendingSession);
   }
-  async receiveHandshakeRequestMessage(data, conn) {
-    const parsed = this.parseMsg(data, conn);
-    if (!parsed) {
-      conn.telemetry?.span.setStatus({
-        code: import_api4.SpanStatusCode.ERROR,
-        message: "non-transport message"
-      });
-      this.protocolError(
-        ProtocolError.HandshakeFailed,
-        "received non-transport message"
-      );
-      return false;
-    }
-    if (!import_value2.Value.Check(ControlMessageHandshakeRequestSchema, parsed.payload)) {
-      conn.telemetry?.span.setStatus({
-        code: import_api4.SpanStatusCode.ERROR,
-        message: "invalid handshake request"
-      });
-      const reason = "received invalid handshake msg";
-      const responseMsg2 = handshakeResponseMessage({
+  rejectHandshakeRequest(session, to, reason, code, metadata) {
+    session.conn.telemetry?.span.setStatus({
+      code: import_api3.SpanStatusCode.ERROR,
+      message: reason
+    });
+    this.log?.warn(reason, metadata);
+    session.sendHandshake(
+      handshakeResponseMessage({
         from: this.clientId,
-        to: parsed.from,
+        to,
         status: {
           ok: false,
+          code,
           reason
         }
-      });
-      conn.send(this.codec.toBuffer(responseMsg2));
-      this.log?.warn(reason, {
-        ...conn.loggingMetadata,
-        clientId: this.clientId,
-        // safe to this.log metadata here as we remove the payload
-        // before passing it to user-land
-        transportMessage: parsed,
-        validationErrors: [
-          ...import_value2.Value.Errors(ControlMessageHandshakeRequestSchema, parsed.payload)
-        ]
-      });
-      this.protocolError(
-        ProtocolError.HandshakeFailed,
-        "invalid handshake request"
+      })
+    );
+    this.protocolError(ProtocolError.HandshakeFailed, reason);
+    this.deletePendingSession(session);
+  }
+  async onHandshakeRequest(session, msg) {
+    if (!import_value2.Value.Check(ControlMessageHandshakeRequestSchema, msg.payload)) {
+      this.rejectHandshakeRequest(
+        session,
+        msg.from,
+        "received invalid handshake request",
+        "MALFORMED_HANDSHAKE",
+        {
+          ...session.loggingMetadata,
+          transportMessage: msg,
+          connectedTo: msg.from,
+          validationErrors: [
+            ...import_value2.Value.Errors(ControlMessageHandshakeRequestSchema, msg.payload)
+          ]
+        }
       );
-      return false;
+      return;
     }
-    const gotVersion = parsed.payload.protocolVersion;
+    const gotVersion = msg.payload.protocolVersion;
     if (gotVersion !== PROTOCOL_VERSION) {
-      conn.telemetry?.span.setStatus({
-        code: import_api4.SpanStatusCode.ERROR,
-        message: "incorrect protocol version"
-      });
-      const reason = `incorrect version (got: ${gotVersion} wanted ${PROTOCOL_VERSION})`;
-      const responseMsg2 = handshakeResponseMessage({
-        from: this.clientId,
-        to: parsed.from,
-        status: {
-          ok: false,
-          reason
+      this.rejectHandshakeRequest(
+        session,
+        msg.from,
+        `expected protocol version ${PROTOCOL_VERSION}, got ${gotVersion}`,
+        "PROTOCOL_VERSION_MISMATCH",
+        {
+          ...session.loggingMetadata,
+          connectedTo: msg.from,
+          transportMessage: msg
         }
-      });
-      conn.send(this.codec.toBuffer(responseMsg2));
-      this.log?.warn(
-        `received handshake msg with incompatible protocol version (got: ${gotVersion}, expected: ${PROTOCOL_VERSION})`,
-        { ...conn.loggingMetadata, clientId: this.clientId }
       );
-      this.protocolError(ProtocolError.HandshakeFailed, reason);
-      return false;
+      return;
     }
-    const oldSession = this.sessions.get(parsed.from);
+    let oldSession = this.sessions.get(msg.from);
     const parsedMetadata = await this.validateHandshakeMetadata(
-      conn,
+      session,
       oldSession,
-      parsed.payload.metadata,
-      parsed.from
+      msg.payload.metadata,
+      msg.from
     );
     if (parsedMetadata === false) {
-      return false;
+      return;
     }
-    let session;
-    let isTransparentReconnect;
-    if (!parsed.payload.expectedSessionState) {
-      ({ session, isTransparentReconnect } = this.getOrCreateSession({
-        to: parsed.from,
-        conn,
-        sessionId: parsed.payload.sessionId,
-        propagationCtx: parsed.tracing
-      }));
-    } else if (parsed.payload.expectedSessionState.reconnect) {
-      const existingSession = this.getExistingSession({
-        to: parsed.from,
-        sessionId: parsed.payload.sessionId,
-        nextExpectedSeq: parsed.payload.expectedSessionState.nextExpectedSeq
-      });
-      if (existingSession === false) {
-        conn.telemetry?.span.setStatus({
-          code: import_api4.SpanStatusCode.ERROR,
-          message: SESSION_STATE_MISMATCH
+    let connectCase = "new session";
+    if (oldSession && oldSession.id === msg.payload.sessionId) {
+      connectCase = "transparent reconnection";
+      const clientNextExpectedSeq = msg.payload.expectedSessionState.nextExpectedSeq;
+      const clientNextSentSeq = msg.payload.expectedSessionState.nextSentSeq ?? 0;
+      const ourNextSeq = oldSession.nextSeq();
+      const ourAck = oldSession.ack;
+      if (clientNextSentSeq > ourAck) {
+        this.rejectHandshakeRequest(
+          session,
+          msg.from,
+          `client is in the future: server wanted next message to be ${ourAck} but client would have sent ${clientNextSentSeq}`,
+          "SESSION_STATE_MISMATCH",
+          {
+            ...session.loggingMetadata,
+            connectedTo: msg.from,
+            transportMessage: msg
+          }
+        );
+        return;
+      }
+      if (ourNextSeq > clientNextExpectedSeq) {
+        this.rejectHandshakeRequest(
+          session,
+          msg.from,
+          `server is in the future: client wanted next message to be ${clientNextExpectedSeq} but server would have sent ${ourNextSeq}`,
+          "SESSION_STATE_MISMATCH",
+          {
+            ...session.loggingMetadata,
+            connectedTo: msg.from,
+            transportMessage: msg
+          }
+        );
+        return;
+      }
+      if (oldSession.state === "Connected" /* Connected */) {
+        const noConnectionSession = SessionStateGraph.transition.ConnectedToNoConnection(oldSession, {
+          onSessionGracePeriodElapsed: () => {
+            this.onSessionGracePeriodElapsed(noConnectionSession);
+          }
         });
-        const reason = SESSION_STATE_MISMATCH;
-        const responseMsg2 = handshakeResponseMessage({
-          from: this.clientId,
-          to: parsed.from,
-          status: {
-            ok: false,
-            reason
+        oldSession = noConnectionSession;
+      } else if (oldSession.state === "Handshaking" /* Handshaking */) {
+        const noConnectionSession = SessionStateGraph.transition.HandshakingToNoConnection(oldSession, {
+          onSessionGracePeriodElapsed: () => {
+            this.onSessionGracePeriodElapsed(noConnectionSession);
           }
         });
-        conn.send(this.codec.toBuffer(responseMsg2));
-        this.log?.warn(
-          `'received handshake msg with incompatible existing session state: ${parsed.payload.sessionId}`,
-          { ...conn.loggingMetadata, clientId: this.clientId }
-        );
-        this.protocolError(ProtocolError.HandshakeFailed, reason);
-        return false;
+        oldSession = noConnectionSession;
+      } else if (oldSession.state === "Connecting" /* Connecting */) {
+        const noConnectionSession = SessionStateGraph.transition.ConnectingToNoConnection(oldSession, {
+          onSessionGracePeriodElapsed: () => {
+            this.onSessionGracePeriodElapsed(noConnectionSession);
+          }
+        });
+        oldSession = noConnectionSession;
       }
-      session = existingSession;
-      isTransparentReconnect = false;
+      this.updateSession(oldSession);
+    } else if (oldSession) {
+      connectCase = "hard reconnection";
+      this.deleteSession(oldSession);
+      oldSession = void 0;
     } else {
-      const createdSession = this.createNewSession({
-        to: parsed.from,
-        conn,
-        sessionId: parsed.payload.sessionId,
-        propagationCtx: parsed.tracing
-      });
-      session = createdSession;
-      isTransparentReconnect = false;
+      connectCase = "unknown session";
+      const clientNextExpectedSeq = msg.payload.expectedSessionState.nextExpectedSeq;
+      const clientNextSentSeq = msg.payload.expectedSessionState.nextSentSeq ?? 0;
+      if (clientNextSentSeq > 0 || clientNextExpectedSeq > 0) {
+        this.rejectHandshakeRequest(
+          session,
+          msg.from,
+          `client is trying to reconnect to a session the server don't know about: ${msg.payload.sessionId}`,
+          "SESSION_STATE_MISMATCH",
+          {
+            ...session.loggingMetadata,
+            connectedTo: msg.from,
+            transportMessage: msg
+          }
+        );
+        return;
+      }
     }
-    this.sessionHandshakeMetadata.set(session, parsedMetadata);
-    this.log?.debug(
-      `handshake from ${parsed.from} ok, responding with handshake success`,
-      conn.loggingMetadata
+    const sessionId = msg.payload.sessionId;
+    this.log?.info(
+      `handshake from ${msg.from} ok (${connectCase}), responding with handshake success`,
+      {
+        ...session.loggingMetadata,
+        connectedTo: msg.from
+      }
     );
     const responseMsg = handshakeResponseMessage({
       from: this.clientId,
-      to: parsed.from,
+      to: msg.from,
       status: {
         ok: true,
-        sessionId: session.id
+        sessionId
       }
     });
-    conn.send(this.codec.toBuffer(responseMsg));
-    this.onConnect(conn, session, isTransparentReconnect);
-    return session;
+    session.sendHandshake(responseMsg);
+    const connectedSession = SessionStateGraph.transition.WaitingForHandshakeToConnected(
+      session,
+      // by this point oldSession is either no connection or we dont have an old session
+      oldSession,
+      sessionId,
+      msg.from,
+      msg.tracing,
+      {
+        onConnectionErrored: (err) => {
+          const errStr = coerceErrorString(err);
+          this.log?.warn(
+            `connection to ${connectedSession.to} errored: ${errStr}`,
+            connectedSession.loggingMetadata
+          );
+        },
+        onConnectionClosed: () => {
+          this.log?.info(
+            `connection to ${connectedSession.to} closed`,
+            connectedSession.loggingMetadata
+          );
+          this.onConnClosed(connectedSession);
+        },
+        onMessage: (msg2) => this.handleMsg(msg2),
+        onInvalidMessage: (reason) => {
+          this.protocolError(ProtocolError.MessageOrderingViolated, reason);
+          this.deleteSession(connectedSession);
+        }
+      }
+    );
+    this.sessionHandshakeMetadata.set(connectedSession.to, parsedMetadata);
+    this.updateSession(connectedSession);
+    this.pendingSessions.delete(session);
+    connectedSession.startActiveHeartbeat();
+  }
+  async validateHandshakeMetadata(handshakingSession, existingSession, rawMetadata, from) {
+    let parsedMetadata = {};
+    if (this.handshakeExtensions) {
+      if (!import_value2.Value.Check(this.handshakeExtensions.schema, rawMetadata)) {
+        this.rejectHandshakeRequest(
+          handshakingSession,
+          from,
+          "received malformed handshake metadata",
+          "MALFORMED_HANDSHAKE_META",
+          {
+            ...handshakingSession.loggingMetadata,
+            connectedTo: from,
+            validationErrors: [
+              ...import_value2.Value.Errors(this.handshakeExtensions.schema, rawMetadata)
+            ]
+          }
+        );
+        return false;
+      }
+      const previousParsedMetadata = existingSession ? this.sessionHandshakeMetadata.get(existingSession.to) : void 0;
+      parsedMetadata = await this.handshakeExtensions.validate(
+        rawMetadata,
+        previousParsedMetadata
+      );
+      if (parsedMetadata === false) {
+        this.rejectHandshakeRequest(
+          handshakingSession,
+          from,
+          "rejected by handshake handler",
+          "REJECTED_BY_CUSTOM_HANDLER",
+          {
+            ...handshakingSession.loggingMetadata,
+            connectedTo: from,
+            clientId: this.clientId
+          }
+        );
+        return false;
+      }
+    }
+    return parsedMetadata;
   }
 };