@replit/river 0.23.18 → 0.24.0

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

@@ -25,11 +25,19 @@ __export(client_exports, {
 module.exports = __toCommonJS(client_exports);
 
 // transport/client.ts
-var import_api4 = require("@opentelemetry/api");
+var import_api3 = require("@opentelemetry/api");
 
 // transport/message.ts
 var import_typebox = require("@sinclair/typebox");
+
+// transport/id.ts
 var import_nanoid = require("nanoid");
+var alphabet = (0, import_nanoid.customAlphabet)(
+  "1234567890abcdefghijklmnopqrstuvxyzABCDEFGHIJKLMNOPQRSTUVXYZ"
+);
+var generateId = () => alphabet(12);
+
+// transport/message.ts
 var TransportMessageSchema = (t) => import_typebox.Type.Object({
   id: import_typebox.Type.String(),
   from: import_typebox.Type.String(),
@@ -64,18 +72,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 +104,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)
     })
   ])
 });
@@ -107,12 +129,12 @@ function handshakeRequestMessage({
   tracing
 }) {
   return {
-    id: (0, import_nanoid.nanoid)(),
+    id: generateId(),
     from,
     to,
     seq: 0,
     ack: 0,
-    streamId: (0, import_nanoid.nanoid)(),
+    streamId: generateId(),
     controlFlags: 0,
     tracing,
     payload: {
@@ -124,7 +146,6 @@ function handshakeRequestMessage({
     }
   };
 }
-var SESSION_STATE_MISMATCH = "session state mismatch";
 function isAck(controlFlag) {
   return (controlFlag & 1 /* AckBit */) === 1 /* AckBit */;
 }
@@ -186,7 +207,8 @@ var defaultTransportOptions = {
   heartbeatIntervalMs: 1e3,
   heartbeatsUntilDead: 2,
   sessionDisconnectGraceMs: 5e3,
-  handshakeTimeoutMs: 5e3,
+  connectionTimeoutMs: 2e3,
+  handshakeTimeoutMs: 1e3,
   codec: NaiveJsonCodec
 };
 var defaultConnectionRetryOptions = {
@@ -275,9 +297,6 @@ var LeakyBucketRateLimit = class {
   }
 };
 
-// transport/transport.ts
-var import_value = require("@sinclair/typebox/value");
-
 // logging/log.ts
 var LoggingLevels = {
   debug: -1,
@@ -368,14 +387,222 @@ var EventDispatcher = class {
   }
 };
 
-// transport/session.ts
-var import_nanoid2 = require("nanoid");
+// 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._handleClose();
+  }
+  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);
+      }
+    });
+  }
+};
+var CommonSession = class extends StateMachineState {
+  from;
+  options;
+  log;
+  constructor(from, options, log) {
+    super();
+    this.from = from;
+    this.options = options;
+    this.log = log;
+  }
+  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;
+  /**
+   * Index of the message we will send next (excluding handshake)
+   */
+  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;
+  }
+  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: generateId(),
+      to: this.to,
+      from: this.from,
+      seq: this.seq,
+      ack: this.ack
+    };
+    this.seq++;
+    return msg;
+  }
+  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/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);
+      }
+    );
+  }
+  // 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(() => {
+    });
+  }
+  _handleStateExit() {
+    super._handleStateExit();
+    clearTimeout(this.connectionTimeout);
+    this.connectionTimeout = void 0;
+  }
+  _handleClose() {
+    this.bestEffortClose();
+    super._handleClose();
+  }
+};
+
+// 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);
+  }
+  _handleClose() {
+    super._handleClose();
+  }
+  _handleStateExit() {
+    super._handleStateExit();
+    if (this.gracePeriodTimeout) {
+      clearTimeout(this.gracePeriodTimeout);
+      this.gracePeriodTimeout = void 0;
+    }
+  }
+};
 
 // tracing/index.ts
 var import_api = require("@opentelemetry/api");
 
 // package.json
-var version = "0.23.18";
+var version = "0.24.0";
 
 // tracing/index.ts
 function getPropagationContext(ctx) {
@@ -386,16 +613,16 @@ function getPropagationContext(ctx) {
   import_api.propagation.inject(ctx, tracing);
   return tracing;
 }
-function createSessionTelemetryInfo(session, propagationCtx) {
+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 ${session.id}`,
+    `session ${sessionId}`,
     {
       attributes: {
         component: "river",
-        "river.session.id": session.id,
-        "river.session.to": session.to,
-        "river.session.from": session.from
+        "river.session.id": sessionId,
+        "river.session.to": to,
+        "river.session.from": from
       }
     },
     parentCtx
@@ -403,173 +630,155 @@ function createSessionTelemetryInfo(session, propagationCtx) {
   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 };
-}
 var tracer = import_api.trace.getTracer("river", version);
 var tracing_default = tracer;
 
-// 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)}`;
+// 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);
   }
-  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
-      };
+  onHandshakeData = (msg) => {
+    const parsedMsg = this.parseMsg(msg);
+    if (parsedMsg === null) {
+      this.listeners.onInvalidHandshake("could not parse message");
+      return;
     }
-    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;
-  }
+    this.listeners.onHandshake(parsedMsg);
+  };
   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
-      }
+      connId: this.conn.id
     };
   }
-  /**
-   * 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.
-   */
+  sendHandshake(msg) {
+    return this.conn.send(this.options.codec.toBuffer(msg));
+  }
+  _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;
+  }
+  _handleClose() {
+    this.conn.close();
+  }
+};
+
+// 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.listeners.onHandshake(parsedMsg);
+  };
+  sendHandshake(msg) {
+    return this.conn.send(this.options.codec.toBuffer(msg));
+  }
+  _handleStateExit() {
+    super._handleStateExit();
+    this.conn.removeDataListener(this.onHandshakeData);
+    this.conn.removeErrorListener(this.listeners.onConnectionErrored);
+    this.conn.removeCloseListener(this.listeners.onConnectionClosed);
+    clearTimeout(this.handshakeTimeout);
+  }
+  _handleClose() {
+    super._handleClose();
+    this.conn.close();
+  }
+};
+
+// 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;
+  }
+  updateBookkeeping(ack, seq) {
+    this.sendBuffer = this.sendBuffer.filter((unacked) => unacked.seq >= ack);
+    this.ack = seq + 1;
+    this.heartbeatMisses = 0;
+  }
   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 {
+    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(
-        `buffering msg to ${fullMsg.to}, connection not ready yet`,
-        { ...this.loggingMetadata, transportMessage: fullMsg }
+        `sending ${this.sendBuffer.length} buffered messages`,
+        this.loggingMetadata
       );
     }
-    return fullMsg.id;
+    for (const msg of this.sendBuffer) {
+      conn.send(this.options.codec.toBuffer(msg));
+    }
   }
-  sendHeartbeat() {
-    const misses = this.heartbeatMisses;
-    const missDuration = misses * this.options.heartbeatIntervalMs;
-    if (misses > this.options.heartbeatsUntilDead) {
-      if (this.connection) {
+  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.closeStaleConnection();
+        this.conn.close();
+        clearInterval(this.heartbeatHandle);
+        this.heartbeatHandle = void 0;
+        return;
       }
-      return;
-    }
+      this.sendHeartbeat();
+      this.heartbeatMisses++;
+    }, this.options.heartbeatIntervalMs);
+  }
+  sendHeartbeat() {
     this.send({
       streamId: "heartbeat",
       controlFlags: 1 /* AckBit */,
@@ -577,186 +786,255 @@ var Session = class {
         type: "ACK"
       }
     });
-    this.heartbeatMisses++;
-  }
-  resetBufferedMessages() {
-    this.sendBuffer = [];
-    this.seq = 0;
-    this.ack = 0;
   }
-  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, {
+  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: msg,
-          connId: conn.id,
+          transportMessage: parsedMsg,
           tags: ["invariant-violation"]
         });
-        conn.close();
-        return;
+        this.telemetry.span.setStatus({
+          code: import_api2.SpanStatusCode.ERROR,
+          message: reason
+        });
+        this.listeners.onInvalidMessage(reason);
       }
+      return;
     }
-  }
-  updateBookkeeping(ack, seq) {
-    if (seq + 1 < this.ack) {
-      this.log?.error(`received stale seq ${seq} + 1 < ${this.ack}`, {
-        ...this.loggingMetadata,
-        tags: ["invariant-violation"]
-      });
+    this.log?.debug(`received msg`, {
+      ...this.loggingMetadata,
+      transportMessage: parsedMsg
+    });
+    this.updateBookkeeping(parsedMsg.ack, parsedMsg.seq);
+    if (!isAck(parsedMsg.controlFlags)) {
+      this.listeners.onMessage(parsedMsg);
       return;
     }
-    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);
+    this.log?.debug(`discarding msg (ack bit set)`, {
+      ...this.loggingMetadata,
+      transportMessage: parsedMsg
+    });
+    if (!this.isActivelyHeartbeating) {
+      this.sendHeartbeat();
     }
-    this.connection = newConn;
-    this.handshakingConnection = void 0;
-  }
-  replaceWithNewHandshakingConnection(newConn) {
-    this.handshakingConnection = newConn;
+  };
+  _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();
   }
-  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
+};
+
+// 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
       );
-      cb();
-    }, this.options.sessionDisconnectGraceMs);
-  }
-  // called on reconnect of the underlying session
-  cancelGrace() {
-    this.heartbeatMisses = 0;
-    clearTimeout(this.disconnectionGrace);
-    this.disconnectionGrace = void 0;
-  }
-  /**
-   * Used to close the handshaking connection, if set.
-   */
-  closeHandshakingConnection(expectedHandshakingConn) {
-    if (this.handshakingConnection === void 0)
-      return;
-    if (expectedHandshakingConn !== void 0 && this.handshakingConnection === expectedHandshakingConn) {
-      return;
+      session.log?.info(`session ${session.id} created in NoConnection state`, {
+        ...session.loggingMetadata,
+        tags: ["state-transition"]
+      });
+      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;
     }
-    this.handshakingConnection.close();
-    this.handshakingConnection = void 0;
-  }
-  // closed when we want to discard the whole session
-  // (i.e. shutdown or session disconnect)
-  close() {
-    this.closeStaleConnection();
-    this.cancelGrace();
-    this.resetBufferedMessages();
-    clearInterval(this.heartbeat);
-  }
-  get connected() {
-    return this.connection !== void 0;
-  }
-  get nextExpectedAck() {
-    return this.seq;
-  }
-  get nextExpectedSeq() {
-    return this.ack;
-  }
-  /**
-   * Check that the peer's next expected seq number matches something that is in our send buffer
-   * _or_ matches our actual next seq.
-   */
-  nextExpectedSeqInRange(nextExpectedSeq) {
-    for (const msg of this.sendBuffer) {
-      if (nextExpectedSeq === msg.seq) {
-        return true;
-      }
+  },
+  // 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: ["state-transition"]
+        }
+      );
+      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;
     }
-    return nextExpectedSeq === this.seq;
-  }
-  // This is only used in tests to make the session misbehave.
-  /* @internal */
-  advanceAckForTesting(by) {
-    this.ack += by;
-  }
-  constructMsg(partialMsg) {
-    const msg = {
-      ...partialMsg,
-      id: unsafeId(),
-      to: this.to,
-      from: this.from,
-      seq: this.seq,
-      ack: this.ack
-    };
-    this.seq++;
-    this.sendBuffer.push(msg);
-    return msg;
-  }
-  inspectSendBuffer() {
-    return this.sendBuffer;
   }
 };
 
 // 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)
-    );
-  }
   /**
    * The event dispatcher for handling events of type EventTypes.
    */
@@ -766,19 +1044,18 @@ var Transport = class {
    */
   options;
   log;
+  sessions;
   /**
    * 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";
+    this.sessions = /* @__PURE__ */ new Map();
   }
   bindLogger(fn, level) {
     if (typeof fn === "function") {
@@ -787,299 +1064,15 @@ var Transport = class {
     }
     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
-    });
-  }
-  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,
-          tags: ["invariant-violation"]
-        }
-      );
-      this.deleteSession({
-        session: currentSession,
-        closeHandshakingConnection: false
-      });
-    }
-    this.sessions.set(session.to, session);
-    this.eventDispatcher.dispatchEvent("sessionStatus", {
-      status: "connect",
-      session
-    });
-    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;
-    }
-    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?.info(
-      `reused existing session for ${to}`,
-      session.loggingMetadata
-    );
-    return session;
-  }
-  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
-      );
-      this.deleteSession({
-        session,
-        closeHandshakingConnection: handshakingConn !== void 0,
-        handshakingConn
-      });
-      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
-      );
-    }
-    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}`,
-        {
-          ...session.loggingMetadata,
-          tags: ["invariant-violation"]
-        }
-      );
-      return;
-    }
-    this.sessions.delete(session.to);
-    this.log?.info(
-      `session ${session.id} disconnect from ${session.to}`,
-      session.loggingMetadata
-    );
-    this.eventDispatcher.dispatchEvent("sessionStatus", {
-      status: "disconnect",
-      session
-    });
-  }
-  /**
-   * 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.
-   */
-  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
-      });
-    });
-  }
-  /**
-   * 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.
-   */
-  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;
-    }
-    return parsedMsg;
-  }
   /**
    * 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.
@@ -1097,34 +1090,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 });
   }
@@ -1136,7 +1101,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
@@ -1147,6 +1112,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
@@ -1164,10 +1191,6 @@ var ClientTransport = class extends Transport {
    * The options for this transport.
    */
   options;
-  /**
-   * The map of reconnect promises for each client ID.
-   */
-  inflightConnectionPromises;
   retryBudget;
   /**
    * A flag indicating whether the transport should automatically reconnect
@@ -1186,352 +1209,278 @@ var ClientTransport = class extends Transport {
       ...defaultClientTransportOptions,
       ...providedOptions
     };
-    this.inflightConnectionPromises = /* @__PURE__ */ new Map();
     this.retryBudget = new LeakyBucketRateLimit(this.options);
   }
   extendHandshake(options) {
     this.handshakeExtensions = options;
   }
-  handleConnection(conn, to) {
-    if (this.getStatus() !== "open")
-      return;
-    let session = void 0;
-    const handshakeTimeout = setTimeout(() => {
-      if (session)
-        return;
-      this.log?.warn(
-        `connection to ${to} timed out waiting for handshake, closing`,
-        { ...conn.loggingMetadata, clientId: this.clientId, connectedTo: to }
-      );
-      conn.close();
-    }, this.options.handshakeTimeoutMs);
-    const handshakeHandler = (data) => {
-      const maybeSession = this.receiveHandshakeResponseMessage(data, conn);
-      clearTimeout(handshakeTimeout);
-      if (!maybeSession) {
-        conn.close();
-        return;
-      } else {
-        session = maybeSession;
-      }
-      conn.removeDataListener(handshakeHandler);
-      conn.addDataListener((data2) => {
-        const parsed = this.parseMsg(data2, conn);
-        if (!parsed) {
-          conn.telemetry?.span.setStatus({
-            code: import_api4.SpanStatusCode.ERROR,
-            message: "message parse failure"
-          });
-          conn.close();
-          return;
-        }
-        this.handleMsg(parsed, conn);
+  tryReconnecting(to) {
+    if (this.reconnectOnConnectionDrop && this.getStatus() === "open") {
+      this.connect(to);
+    }
+  }
+  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"]
       });
-    };
-    conn.addDataListener(handshakeHandler);
-    conn.addCloseListener(() => {
-      if (session) {
-        this.onDisconnect(conn, session);
-      }
-      const willReconnect = this.reconnectOnConnectionDrop && this.getStatus() === "open";
-      this.log?.info(
-        `connection to ${to} disconnected` + (willReconnect ? ", reconnecting" : ""),
-        {
-          ...conn.loggingMetadata,
-          ...session?.loggingMetadata,
-          clientId: this.clientId,
-          connectedTo: to
+      throw new Error(err);
+    }
+    let session = this.sessions.get(to);
+    if (!session) {
+      session = this.createUnconnectedSession(to);
+    }
+    return session.send(msg);
+  }
+  createUnconnectedSession(to) {
+    const session = SessionStateGraph.entrypoints.NoConnection(
+      to,
+      this.clientId,
+      {
+        onSessionGracePeriodElapsed: () => {
+          this.onSessionGracePeriodElapsed(session);
         }
-      );
-      this.inflightConnectionPromises.delete(to);
-      if (this.reconnectOnConnectionDrop) {
-        void this.connect(to);
+      },
+      this.options,
+      this.log
+    );
+    this.updateSession(session);
+    return session;
+  }
+  // listeners
+  onConnectingFailed(session) {
+    const noConnectionSession = super.onConnectingFailed(session);
+    this.tryReconnecting(noConnectionSession.to);
+    return noConnectionSession;
+  }
+  onConnClosed(session) {
+    const noConnectionSession = super.onConnClosed(session);
+    this.tryReconnecting(noConnectionSession.to);
+    return noConnectionSession;
+  }
+  onConnectionEstablished(session, conn) {
+    const handshakingSession = SessionStateGraph.transition.ConnectingToHandshaking(session, conn, {
+      onConnectionErrored: (err) => {
+        const errStr = coerceErrorString(err);
+        this.log?.error(
+          `connection to ${handshakingSession.to} errored during handshake: ${errStr}`,
+          handshakingSession.loggingMetadata
+        );
+      },
+      onConnectionClosed: () => {
+        this.log?.warn(
+          `connection to ${handshakingSession.to} closed during handshake`,
+          handshakingSession.loggingMetadata
+        );
+        this.onConnClosed(handshakingSession);
+      },
+      onHandshake: (msg) => {
+        this.onHandshakeResponse(handshakingSession, msg);
+      },
+      onInvalidHandshake: (reason) => {
+        this.log?.error(
+          `invalid handshake: ${reason}`,
+          handshakingSession.loggingMetadata
+        );
+        this.deleteSession(session);
+        this.protocolError(ProtocolError.HandshakeFailed, reason);
+      },
+      onHandshakeTimeout: () => {
+        this.log?.error(
+          `connection to ${handshakingSession.to} timed out during handshake`,
+          handshakingSession.loggingMetadata
+        );
+        this.onConnClosed(handshakingSession);
       }
     });
-    conn.addErrorListener((err) => {
-      conn.telemetry?.span.setStatus({
-        code: import_api4.SpanStatusCode.ERROR,
-        message: "connection error"
-      });
-      this.log?.warn(
-        `error in connection to ${to}: ${coerceErrorString(err)}`,
-        {
-          ...conn.loggingMetadata,
-          ...session?.loggingMetadata,
-          clientId: this.clientId,
-          connectedTo: to
-        }
-      );
+    this.updateSession(handshakingSession);
+    void this.sendHandshake(handshakingSession);
+    return handshakingSession;
+  }
+  rejectHandshakeResponse(session, reason, metadata) {
+    session.conn.telemetry?.span.setStatus({
+      code: import_api3.SpanStatusCode.ERROR,
+      message: reason
     });
+    this.log?.warn(reason, metadata);
+    this.deleteSession(session);
   }
-  receiveHandshakeResponseMessage(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(ControlMessageHandshakeResponseSchema, parsed.payload)) {
-      conn.telemetry?.span.setStatus({
-        code: import_api4.SpanStatusCode.ERROR,
-        message: "invalid handshake response"
-      });
-      this.log?.warn(`received invalid handshake resp`, {
-        ...conn.loggingMetadata,
-        clientId: this.clientId,
-        connectedTo: parsed.from,
-        transportMessage: parsed,
+  onHandshakeResponse(session, msg) {
+    if (!import_value2.Value.Check(ControlMessageHandshakeResponseSchema, msg.payload)) {
+      const reason = `received invalid handshake response`;
+      this.rejectHandshakeResponse(session, reason, {
+        ...session.loggingMetadata,
+        transportMessage: msg,
         validationErrors: [
-          ...import_value2.Value.Errors(
-            ControlMessageHandshakeResponseSchema,
-            parsed.payload
-          )
+          ...import_value2.Value.Errors(ControlMessageHandshakeResponseSchema, msg.payload)
         ]
       });
-      this.protocolError(
-        ProtocolError.HandshakeFailed,
-        "invalid handshake resp"
-      );
-      return false;
+      return;
     }
-    const previousSession = this.sessions.get(parsed.from);
-    if (!parsed.payload.status.ok) {
-      if (parsed.payload.status.reason === SESSION_STATE_MISMATCH) {
-        if (previousSession) {
-          this.deleteSession({
-            session: previousSession,
-            closeHandshakingConnection: true
-          });
-        }
-        conn.telemetry?.span.setStatus({
-          code: import_api4.SpanStatusCode.ERROR,
-          message: parsed.payload.status.reason
-        });
+    if (!msg.payload.status.ok) {
+      const retriable = msg.payload.status.code ? import_value2.Value.Check(
+        HandshakeErrorRetriableResponseCodes,
+        msg.payload.status.code
+      ) : false;
+      const reason = `handshake failed: ${msg.payload.status.reason}`;
+      this.rejectHandshakeResponse(session, reason, {
+        ...session.loggingMetadata,
+        transportMessage: msg
+      });
+      if (retriable) {
+        this.tryReconnecting(session.to);
       } else {
-        conn.telemetry?.span.setStatus({
-          code: import_api4.SpanStatusCode.ERROR,
-          message: "handshake rejected"
-        });
+        this.deleteSession(session);
+        this.protocolError(ProtocolError.HandshakeFailed, reason);
       }
-      this.log?.warn(
-        `received handshake rejection: ${parsed.payload.status.reason}`,
-        {
-          ...conn.loggingMetadata,
-          clientId: this.clientId,
-          connectedTo: parsed.from,
-          transportMessage: parsed
-        }
-      );
-      this.protocolError(
-        ProtocolError.HandshakeFailed,
-        parsed.payload.status.reason
-      );
-      return false;
+      return;
     }
-    if (previousSession?.advertisedSessionId && previousSession.advertisedSessionId !== parsed.payload.status.sessionId) {
-      this.deleteSession({
-        session: previousSession,
-        closeHandshakingConnection: true
-      });
-      conn.telemetry?.span.setStatus({
-        code: import_api4.SpanStatusCode.ERROR,
-        message: "session id mismatch"
-      });
-      this.log?.warn(`handshake from ${parsed.from} session id mismatch`, {
-        ...conn.loggingMetadata,
-        clientId: this.clientId,
-        connectedTo: parsed.from,
-        transportMessage: parsed
+    if (msg.payload.status.sessionId !== session.id) {
+      const reason = `session id mismatch: expected ${session.id}, got ${msg.payload.status.sessionId}`;
+      this.rejectHandshakeResponse(session, reason, {
+        ...session.loggingMetadata,
+        transportMessage: msg
       });
-      this.protocolError(ProtocolError.HandshakeFailed, "session id mismatch");
-      return false;
+      return;
     }
-    this.log?.debug(`handshake from ${parsed.from} ok`, {
-      ...conn.loggingMetadata,
-      clientId: this.clientId,
-      connectedTo: parsed.from,
-      transportMessage: parsed
+    this.log?.info(`handshake from ${msg.from} ok`, {
+      ...session.loggingMetadata,
+      transportMessage: msg
     });
-    const { session, isTransparentReconnect } = this.getOrCreateSession({
-      to: parsed.from,
-      conn,
-      sessionId: parsed.payload.status.sessionId
+    const connectedSession = SessionStateGraph.transition.HandshakingToConnected(session, {
+      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.deleteSession(connectedSession);
+        this.protocolError(ProtocolError.MessageOrderingViolated, reason);
+      }
     });
-    this.onConnect(conn, session, isTransparentReconnect);
-    this.retryBudget.startRestoringBudget(session.to);
-    return session;
+    this.updateSession(connectedSession);
+    this.retryBudget.startRestoringBudget(connectedSession.to);
   }
   /**
    * Manually attempts to connect to a client.
    * @param to The client ID of the node to connect to.
    */
-  async connect(to) {
-    if (this.connections.has(to)) {
-      this.log?.info(`already connected to ${to}, skipping connect attempt`, {
-        clientId: this.clientId,
-        connectedTo: to
-      });
+  connect(to) {
+    let session = this.sessions.get(to);
+    session ??= this.createUnconnectedSession(to);
+    if (session.state !== "NoConnection" /* NoConnection */) {
+      this.log?.debug(
+        `session to ${to} has state ${session.state}, skipping connect attempt`,
+        session.loggingMetadata
+      );
       return;
     }
-    const canProceedWithConnection = () => this.getStatus() === "open";
-    if (!canProceedWithConnection()) {
+    if (this.getStatus() !== "open") {
       this.log?.info(
         `transport state is no longer open, cancelling attempt to connect to ${to}`,
-        { clientId: this.clientId, connectedTo: to }
+        session.loggingMetadata
       );
       return;
     }
-    let reconnectPromise = this.inflightConnectionPromises.get(to);
-    if (!reconnectPromise) {
-      if (!this.retryBudget.hasBudget(to)) {
-        const budgetConsumed = this.retryBudget.getBudgetConsumed(to);
-        const errMsg = `tried to connect to ${to} but retry budget exceeded (more than ${budgetConsumed} attempts in the last ${this.retryBudget.totalBudgetRestoreTime}ms)`;
-        this.log?.error(errMsg, { clientId: this.clientId, connectedTo: to });
-        this.protocolError(ProtocolError.RetriesExceeded, errMsg);
-        return;
-      }
-      let sleep = Promise.resolve();
-      const backoffMs = this.retryBudget.getBackoffMs(to);
-      if (backoffMs > 0) {
-        sleep = new Promise((resolve) => setTimeout(resolve, backoffMs));
-      }
-      this.log?.info(
-        `attempting connection to ${to} (${backoffMs}ms backoff)`,
-        {
-          clientId: this.clientId,
-          connectedTo: to
-        }
-      );
-      this.retryBudget.consumeBudget(to);
-      reconnectPromise = tracing_default.startActiveSpan("connect", async (span) => {
-        try {
-          span.addEvent("backoff", { backoffMs });
-          await sleep;
-          if (!canProceedWithConnection()) {
-            throw new Error("transport state is no longer open");
-          }
-          span.addEvent("connecting");
-          const conn = await this.createNewOutgoingConnection(to);
-          if (!canProceedWithConnection()) {
-            this.log?.info(
-              `transport state is no longer open, closing pre-handshake connection to ${to}`,
-              {
-                ...conn.loggingMetadata,
-                clientId: this.clientId,
-                connectedTo: to
-              }
-            );
-            conn.close();
-            throw new Error("transport state is no longer open");
-          }
-          span.addEvent("sending handshake");
-          const ok = await this.sendHandshake(to, conn);
-          if (!ok) {
-            conn.close();
-            throw new Error("failed to send handshake");
-          }
-          return conn;
-        } catch (err) {
-          const errStr = coerceErrorString(err);
-          span.recordException(errStr);
-          span.setStatus({ code: import_api4.SpanStatusCode.ERROR });
-          throw err;
-        } finally {
-          span.end();
-        }
-      });
-      this.inflightConnectionPromises.set(to, reconnectPromise);
-    } else {
-      this.log?.info(
-        `attempting connection to ${to} (reusing previous attempt)`,
-        {
-          clientId: this.clientId,
-          connectedTo: to
-        }
-      );
+    if (!this.retryBudget.hasBudget(to)) {
+      const budgetConsumed = this.retryBudget.getBudgetConsumed(to);
+      const errMsg = `tried to connect to ${to} but retry budget exceeded (more than ${budgetConsumed} attempts in the last ${this.retryBudget.totalBudgetRestoreTime}ms)`;
+      this.log?.error(errMsg, session.loggingMetadata);
+      this.protocolError(ProtocolError.RetriesExceeded, errMsg);
+      return;
     }
-    try {
-      await reconnectPromise;
-    } catch (error) {
-      this.inflightConnectionPromises.delete(to);
-      const errStr = coerceErrorString(error);
-      if (!this.reconnectOnConnectionDrop || !canProceedWithConnection()) {
-        this.log?.warn(`connection to ${to} failed (${errStr})`, {
-          clientId: this.clientId,
-          connectedTo: to
-        });
-      } else {
-        this.log?.warn(`connection to ${to} failed (${errStr}), retrying`, {
-          clientId: this.clientId,
-          connectedTo: to
-        });
-        await this.connect(to);
-      }
+    let sleep = Promise.resolve();
+    const backoffMs = this.retryBudget.getBackoffMs(to);
+    if (backoffMs > 0) {
+      sleep = new Promise((resolve) => setTimeout(resolve, backoffMs));
     }
-  }
-  deleteSession({
-    session,
-    closeHandshakingConnection,
-    handshakingConn
-  }) {
-    this.inflightConnectionPromises.delete(session.to);
-    super.deleteSession({
-      session,
-      closeHandshakingConnection,
-      handshakingConn
+    this.log?.info(
+      `attempting connection to ${to} (${backoffMs}ms backoff)`,
+      session.loggingMetadata
+    );
+    this.retryBudget.consumeBudget(to);
+    const reconnectPromise = tracing_default.startActiveSpan("connect", async (span) => {
+      try {
+        span.addEvent("backoff", { backoffMs });
+        await sleep;
+        if (this.getStatus() !== "open") {
+          throw new Error("transport state is no longer open");
+        }
+        span.addEvent("connecting");
+        return await this.createNewOutgoingConnection(to);
+      } catch (err) {
+        const errStr = coerceErrorString(err);
+        span.recordException(errStr);
+        span.setStatus({ code: import_api3.SpanStatusCode.ERROR });
+        throw err;
+      } finally {
+        span.end();
+      }
     });
+    const connectingSession = SessionStateGraph.transition.NoConnectionToConnecting(
+      session,
+      reconnectPromise,
+      {
+        onConnectionEstablished: (conn) => {
+          this.log?.debug(
+            `connection to ${connectingSession.to} established`,
+            connectingSession.loggingMetadata
+          );
+          this.onConnectionEstablished(connectingSession, conn);
+        },
+        onConnectionFailed: (error) => {
+          const errStr = coerceErrorString(error);
+          this.log?.error(
+            `error connecting to ${connectingSession.to}: ${errStr}`,
+            connectingSession.loggingMetadata
+          );
+          this.onConnectingFailed(connectingSession);
+        },
+        onConnectionTimeout: () => {
+          this.log?.error(
+            `connection to ${connectingSession.to} timed out`,
+            connectingSession.loggingMetadata
+          );
+          this.onConnectingFailed(connectingSession);
+        }
+      }
+    );
+    this.updateSession(connectingSession);
   }
-  async sendHandshake(to, conn) {
+  async sendHandshake(session) {
     let metadata = void 0;
     if (this.handshakeExtensions) {
       metadata = await this.handshakeExtensions.construct();
-      if (!import_value2.Value.Check(this.handshakeExtensions.schema, metadata)) {
-        this.log?.error(`constructed handshake metadata did not match schema`, {
-          ...conn.loggingMetadata,
-          clientId: this.clientId,
-          connectedTo: to,
-          validationErrors: [
-            ...import_value2.Value.Errors(this.handshakeExtensions.schema, metadata)
-          ],
-          tags: ["invariant-violation"]
-        });
-        this.protocolError(
-          ProtocolError.HandshakeFailed,
-          "handshake metadata did not match schema"
-        );
-        conn.telemetry?.span.setStatus({
-          code: import_api4.SpanStatusCode.ERROR,
-          message: "handshake meta mismatch"
-        });
-        return false;
-      }
     }
-    const { session } = this.getOrCreateSession({ to, handshakingConn: conn });
     const requestMsg = handshakeRequestMessage({
       from: this.clientId,
-      to,
+      to: session.to,
       sessionId: session.id,
       expectedSessionState: {
-        reconnect: session.advertisedSessionId !== void 0,
-        nextExpectedSeq: session.nextExpectedSeq
+        nextExpectedSeq: session.ack,
+        nextSentSeq: session.nextSeq()
       },
       metadata,
       tracing: getPropagationContext(session.telemetry.ctx)
     });
-    this.log?.debug(`sending handshake request to ${to}`, {
-      ...conn.loggingMetadata,
-      clientId: this.clientId,
-      connectedTo: to,
+    this.log?.debug(`sending handshake request to ${session.to}`, {
+      ...session.loggingMetadata,
       transportMessage: requestMsg
     });
-    conn.send(this.codec.toBuffer(requestMsg));
-    return true;
+    session.sendHandshake(requestMsg);
   }
   close() {
     this.retryBudget.close();
@@ -1539,10 +1488,79 @@ var ClientTransport = class extends Transport {
   }
 };
 
+// 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/ws/connection.ts
 var WebSocketConnection = class extends Connection {
-  errorCb = null;
-  closeCb = null;
   ws;
   constructor(ws) {
     super();
@@ -1553,29 +1571,23 @@ var WebSocketConnection = class extends Connection {
       didError = true;
     };
     this.ws.onclose = ({ code, reason }) => {
-      if (didError && this.errorCb) {
-        this.errorCb(
-          new Error(
-            `websocket closed with code and reason: ${code} - ${reason}`
-          )
+      if (didError) {
+        const err = new Error(
+          `websocket closed with code and reason: ${code} - ${reason}`
         );
+        for (const cb of this.errorListeners) {
+          cb(err);
+        }
       }
-      if (this.closeCb) {
-        this.closeCb();
+      for (const cb of this.closeListeners) {
+        cb();
+      }
+    };
+    this.ws.onmessage = (msg) => {
+      for (const cb of this.dataListeners) {
+        cb(msg.data);
       }
     };
-  }
-  addDataListener(cb) {
-    this.ws.onmessage = (msg) => cb(msg.data);
-  }
-  removeDataListener() {
-    this.ws.onmessage = null;
-  }
-  addCloseListener(cb) {
-    this.closeCb = cb;
-  }
-  addErrorListener(cb) {
-    this.errorCb = cb;
   }
   send(payload) {
     if (this.ws.readyState !== this.ws.OPEN) {
@@ -1636,7 +1648,6 @@ var WebSocketClientTransport = class extends ClientTransport {
       clientId: this.clientId,
       connectedTo: to
     });
-    this.handleConnection(conn, to);
     return conn;
   }
 };