@replit/river 0.205.2 → 0.207.1

package/dist/{services-036dcc97.d.ts → services-4cd29829.d.ts}

@@ -1,8 +1,627 @@
 import * as _sinclair_typebox from '@sinclair/typebox';
-import { TObject, TString, TSchema, TUnion, TLiteral, TNever, Static } from '@sinclair/typebox';
-import { C as Connection, n as ClientHandshakeOptions, t as ProcedureHandlerContext, s as ServiceContext } from './context-2c4bb66b.js';
-import { c as TransportClientId } from './message-865bba35.js';
-import { C as ClientTransport } from './client-8ab60722.js';
+import { Static, TSchema, TObject, TString, TUnion, TLiteral, TNever } from '@sinclair/typebox';
+import { Tracer, Span } from '@opentelemetry/api';
+import { c as TelemetryInfo, M as MessageMetadata, T as TransportClientId, L as Logger, O as OpaqueTransportMessage, P as ProtocolVersion, b as PartialTransportMessage, d as TransportMessage, a as Tags, H as HandshakeErrorResponseCodes, e as LogFn, f as LoggingLevel, g as HandshakeErrorCustomHandlerFatalResponseCodes } from './message-ffacb98a.js';
+import { C as Codec } from './types-3e5768ec.js';
+
+/**
+ * A connection is the actual raw underlying transport connection.
+ * It’s responsible for dispatching to/from the actual connection itself
+ * This should be instantiated as soon as the client/server has a connection
+ * It’s tied to the lifecycle of the underlying transport connection (i.e. if the WS drops, this connection should be deleted)
+ */
+declare abstract class Connection {
+    id: string;
+    telemetry?: TelemetryInfo;
+    constructor();
+    get loggingMetadata(): MessageMetadata;
+    private _dataListeners;
+    private _closeListeners;
+    private _errorListeners;
+    get dataListeners(): ((msg: Uint8Array) => void)[];
+    get closeListeners(): (() => void)[];
+    get errorListeners(): ((err: Error) => void)[];
+    onData(msg: Uint8Array): void;
+    onError(err: Error): void;
+    onClose(): void;
+    /**
+     * Handle adding a callback for when a message is received.
+     * @param msg The message that was received.
+     */
+    addDataListener(cb: (msg: Uint8Array) => void): void;
+    removeDataListener(cb: (msg: Uint8Array) => void): void;
+    /**
+     * 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: () => void): void;
+    removeCloseListener(cb: () => void): void;
+    /**
+     * 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: (err: Error) => void): void;
+    removeErrorListener(cb: (err: Error) => void): void;
+    /**
+     * Sends a message over the connection.
+     * @param msg The message to send.
+     * @returns true if the message was sent, false otherwise.
+     */
+    abstract send(msg: Uint8Array): boolean;
+    /**
+     * Closes the connection.
+     */
+    abstract close(): void;
+}
+
+declare const enum SessionState {
+    NoConnection = "NoConnection",
+    BackingOff = "BackingOff",
+    Connecting = "Connecting",
+    Handshaking = "Handshaking",
+    Connected = "Connected",
+    WaitingForHandshake = "WaitingForHandshake"
+}
+declare abstract class StateMachineState {
+    abstract readonly state: SessionState;
+    _isConsumed: boolean;
+    abstract _handleStateExit(): void;
+    abstract _handleClose(): void;
+    /**
+     * Cleanup this state machine state and mark it as consumed.
+     * After calling close, it is an error to access any properties on the state.
+     * You should never need to call this as a consumer.
+     *
+     * If you're looking to close the session from the client,
+     * use `.hardDisconnect` on the client transport.
+     */
+    close(): void;
+    constructor();
+}
+interface SessionOptions {
+    /**
+     * Frequency at which to send heartbeat acknowledgements
+     */
+    heartbeatIntervalMs: number;
+    /**
+     * Number of elapsed heartbeats without a response message before we consider
+     * the connection dead.
+     */
+    heartbeatsUntilDead: number;
+    /**
+     * Max duration that a session can be without a connection before we consider
+     * it dead. This deadline is carried between states and is used to determine
+     * when to consider the session a lost cause and delete it entirely.
+     * Generally, this should be strictly greater than the sum of
+     * {@link connectionTimeoutMs} and {@link handshakeTimeoutMs}.
+     */
+    sessionDisconnectGraceMs: number;
+    /**
+     * Connection timeout in milliseconds
+     */
+    connectionTimeoutMs: number;
+    /**
+     * Handshake timeout in milliseconds
+     */
+    handshakeTimeoutMs: number;
+    /**
+     * Whether to enable transparent session reconnects
+     */
+    enableTransparentSessionReconnects: boolean;
+    /**
+     * The codec to use for encoding/decoding messages over the wire
+     */
+    codec: Codec;
+}
+interface CommonSessionProps {
+    from: TransportClientId;
+    options: SessionOptions;
+    tracer: Tracer;
+    log: Logger | undefined;
+}
+declare abstract class CommonSession extends StateMachineState {
+    readonly from: TransportClientId;
+    readonly options: SessionOptions;
+    tracer: Tracer;
+    log?: Logger;
+    abstract get loggingMetadata(): MessageMetadata;
+    constructor({ from, options, log, tracer }: CommonSessionProps);
+    parseMsg(msg: Uint8Array): OpaqueTransportMessage | null;
+}
+type SessionId = string;
+interface IdentifiedSessionProps extends CommonSessionProps {
+    id: SessionId;
+    to: TransportClientId;
+    seq: number;
+    ack: number;
+    seqSent: number;
+    sendBuffer: Array<OpaqueTransportMessage>;
+    telemetry: TelemetryInfo;
+    protocolVersion: ProtocolVersion;
+}
+declare abstract class IdentifiedSession extends CommonSession {
+    readonly id: SessionId;
+    readonly telemetry: TelemetryInfo;
+    readonly to: TransportClientId;
+    readonly protocolVersion: ProtocolVersion;
+    /**
+     * Index of the message we will send next (excluding handshake)
+     */
+    seq: number;
+    /**
+     * Last seq we sent over the wire this session (excluding handshake) and retransmissions
+     */
+    seqSent: number;
+    /**
+     * Number of unique messages we've received this session (excluding handshake)
+     */
+    ack: number;
+    sendBuffer: Array<OpaqueTransportMessage>;
+    constructor(props: IdentifiedSessionProps);
+    get loggingMetadata(): MessageMetadata;
+    constructMsg<Payload>(partialMsg: PartialTransportMessage<Payload>): TransportMessage<Payload>;
+    nextSeq(): number;
+    send(msg: PartialTransportMessage): string;
+    _handleStateExit(): void;
+    _handleClose(): void;
+}
+interface IdentifiedSessionWithGracePeriodListeners {
+    onSessionGracePeriodElapsed: () => void;
+}
+interface IdentifiedSessionWithGracePeriodProps extends IdentifiedSessionProps {
+    graceExpiryTime: number;
+    listeners: IdentifiedSessionWithGracePeriodListeners;
+}
+declare abstract class IdentifiedSessionWithGracePeriod extends IdentifiedSession {
+    graceExpiryTime: number;
+    protected gracePeriodTimeout?: ReturnType<typeof setTimeout>;
+    listeners: IdentifiedSessionWithGracePeriodListeners;
+    constructor(props: IdentifiedSessionWithGracePeriodProps);
+    _handleStateExit(): void;
+    _handleClose(): void;
+}
+
+interface SessionConnectingListeners extends IdentifiedSessionWithGracePeriodListeners {
+    onConnectionEstablished: (conn: Connection) => void;
+    onConnectionFailed: (err: unknown) => void;
+    onConnectionTimeout: () => void;
+}
+interface SessionConnectingProps<ConnType extends Connection> extends IdentifiedSessionWithGracePeriodProps {
+    connPromise: Promise<ConnType>;
+    listeners: SessionConnectingListeners;
+}
+declare class SessionConnecting<ConnType extends Connection> extends IdentifiedSessionWithGracePeriod {
+    readonly state: SessionState.Connecting;
+    connPromise: Promise<ConnType>;
+    listeners: SessionConnectingListeners;
+    connectionTimeout?: ReturnType<typeof setTimeout>;
+    constructor(props: SessionConnectingProps<ConnType>);
+    bestEffortClose(): void;
+    _handleStateExit(): void;
+    _handleClose(): void;
+}
+
+declare class SessionNoConnection extends IdentifiedSessionWithGracePeriod {
+    readonly state: SessionState.NoConnection;
+    _handleClose(): void;
+    _handleStateExit(): void;
+}
+
+interface SessionHandshakingListeners extends IdentifiedSessionWithGracePeriodListeners {
+    onConnectionErrored: (err: unknown) => void;
+    onConnectionClosed: () => void;
+    onHandshake: (msg: OpaqueTransportMessage) => void;
+    onInvalidHandshake: (reason: string, code: Static<typeof HandshakeErrorResponseCodes>) => void;
+    onHandshakeTimeout: () => void;
+}
+interface SessionHandshakingProps<ConnType extends Connection> extends IdentifiedSessionWithGracePeriodProps {
+    conn: ConnType;
+    listeners: SessionHandshakingListeners;
+}
+declare class SessionHandshaking<ConnType extends Connection> extends IdentifiedSessionWithGracePeriod {
+    readonly state: SessionState.Handshaking;
+    conn: ConnType;
+    listeners: SessionHandshakingListeners;
+    handshakeTimeout?: ReturnType<typeof setTimeout>;
+    constructor(props: SessionHandshakingProps<ConnType>);
+    get loggingMetadata(): {
+        protocolVersion?: ProtocolVersion | undefined;
+        clientId?: string | undefined;
+        connectedTo?: string | undefined;
+        sessionId?: string | undefined;
+        connId?: string | undefined;
+        transportMessage?: Partial<OpaqueTransportMessage> | undefined;
+        validationErrors?: {
+            path: string;
+            message: string;
+        }[] | undefined;
+        tags?: Tags[] | undefined;
+        telemetry?: {
+            traceId: string;
+            spanId: string;
+        } | undefined;
+        extras?: Record<string, unknown> | undefined;
+    };
+    onHandshakeData: (msg: Uint8Array) => void;
+    sendHandshake(msg: TransportMessage): boolean;
+    _handleStateExit(): void;
+    _handleClose(): void;
+}
+
+interface SessionConnectedListeners {
+    onConnectionErrored: (err: unknown) => void;
+    onConnectionClosed: () => void;
+    onMessage: (msg: OpaqueTransportMessage) => void;
+    onInvalidMessage: (reason: string) => void;
+}
+interface SessionConnectedProps<ConnType extends Connection> extends IdentifiedSessionProps {
+    conn: ConnType;
+    listeners: SessionConnectedListeners;
+}
+declare class SessionConnected<ConnType extends Connection> extends IdentifiedSession {
+    readonly state: SessionState.Connected;
+    conn: ConnType;
+    listeners: SessionConnectedListeners;
+    private heartbeatHandle?;
+    private heartbeatMisses;
+    isActivelyHeartbeating: boolean;
+    updateBookkeeping(ack: number, seq: number): void;
+    private assertSendOrdering;
+    send(msg: PartialTransportMessage): string;
+    constructor(props: SessionConnectedProps<ConnType>);
+    get loggingMetadata(): {
+        protocolVersion?: ProtocolVersion | undefined;
+        clientId?: string | undefined;
+        connectedTo?: string | undefined;
+        sessionId?: string | undefined;
+        connId?: string | undefined;
+        transportMessage?: Partial<OpaqueTransportMessage> | undefined;
+        validationErrors?: {
+            path: string;
+            message: string;
+        }[] | undefined;
+        tags?: Tags[] | undefined;
+        telemetry?: {
+            traceId: string;
+            spanId: string;
+        } | undefined;
+        extras?: Record<string, unknown> | undefined;
+    };
+    startActiveHeartbeat(): void;
+    private sendHeartbeat;
+    closeConnection(): void;
+    onMessageData: (msg: Uint8Array) => void;
+    _handleStateExit(): void;
+    _handleClose(): void;
+}
+
+interface SessionBackingOffListeners extends IdentifiedSessionWithGracePeriodListeners {
+    onBackoffFinished: () => void;
+}
+interface SessionBackingOffProps extends IdentifiedSessionWithGracePeriodProps {
+    backoffMs: number;
+    listeners: SessionBackingOffListeners;
+}
+declare class SessionBackingOff extends IdentifiedSessionWithGracePeriod {
+    readonly state: SessionState.BackingOff;
+    listeners: SessionBackingOffListeners;
+    backoffTimeout?: ReturnType<typeof setTimeout>;
+    constructor(props: SessionBackingOffProps);
+    _handleClose(): void;
+    _handleStateExit(): void;
+}
+
+type ClientSession<ConnType extends Connection> = SessionNoConnection | SessionBackingOff | SessionConnecting<ConnType> | SessionHandshaking<ConnType> | SessionConnected<ConnType>;
+type ServerSession<ConnType extends Connection> = SessionConnected<ConnType> | SessionNoConnection;
+type Session<ConnType extends Connection> = ClientSession<ConnType> | ServerSession<ConnType>;
+
+declare const ProtocolError: {
+    readonly RetriesExceeded: "conn_retry_exceeded";
+    readonly HandshakeFailed: "handshake_failed";
+    readonly MessageOrderingViolated: "message_ordering_violated";
+    readonly InvalidMessage: "invalid_message";
+};
+type ProtocolErrorType = (typeof ProtocolError)[keyof typeof ProtocolError];
+interface EventMap {
+    message: OpaqueTransportMessage;
+    sessionStatus: {
+        status: 'created' | 'closing';
+        session: Session<Connection>;
+    } | {
+        status: 'closed';
+        session: Pick<Session<Connection>, 'id' | 'to'>;
+    };
+    sessionTransition: {
+        state: SessionState.Connected;
+        id: SessionId;
+    } | {
+        state: SessionState.Handshaking;
+        id: SessionId;
+    } | {
+        state: SessionState.Connecting;
+        id: SessionId;
+    } | {
+        state: SessionState.BackingOff;
+        id: SessionId;
+    } | {
+        state: SessionState.NoConnection;
+        id: SessionId;
+    };
+    protocolError: {
+        type: (typeof ProtocolError)['HandshakeFailed'];
+        code: Static<typeof HandshakeErrorResponseCodes>;
+        message: string;
+    } | {
+        type: Omit<ProtocolErrorType, (typeof ProtocolError)['HandshakeFailed']>;
+        message: string;
+    };
+    transportStatus: {
+        status: TransportStatus;
+    };
+}
+type EventTypes = keyof EventMap;
+type EventHandler<K extends EventTypes> = (event: EventMap[K]) => unknown;
+declare class EventDispatcher<T extends EventTypes> {
+    private eventListeners;
+    removeAllListeners(): void;
+    numberOfListeners<K extends T>(eventType: K): number;
+    addEventListener<K extends T>(eventType: K, handler: EventHandler<K>): void;
+    removeEventListener<K extends T>(eventType: K, handler: EventHandler<K>): void;
+    dispatchEvent<K extends T>(eventType: K, event: EventMap[K]): void;
+}
+
+/**
+ * Options to control the backoff and retry behavior of the client transport's connection behaviour.
+ *
+ * River implements exponential backoff with jitter to prevent flooding the server
+ * when there's an issue with connection establishment.
+ *
+ * The backoff is calculated via the following:
+ *   backOff = min(jitter + {@link baseIntervalMs} * 2 ^ budget_consumed, {@link maxBackoffMs})
+ *
+ * We use a leaky bucket rate limit with a budget of {@link attemptBudgetCapacity} reconnection attempts.
+ * Budget only starts to restore after a successful handshake at a rate of one budget per {@link budgetRestoreIntervalMs}.
+ */
+interface ConnectionRetryOptions {
+    /**
+     * The base interval to wait before retrying a connection.
+     */
+    baseIntervalMs: number;
+    /**
+     * The maximum random jitter to add to the total backoff time.
+     */
+    maxJitterMs: number;
+    /**
+     * The maximum amount of time to wait before retrying a connection.
+     * This does not include the jitter.
+     */
+    maxBackoffMs: number;
+    /**
+     * The max number of times to attempt a connection before a successful handshake.
+     * This persists across connections but starts restoring budget after a successful handshake.
+     * The restoration interval depends on {@link budgetRestoreIntervalMs}
+     */
+    attemptBudgetCapacity: number;
+    /**
+     * After a successful connection attempt, how long to wait before we restore a single budget.
+     */
+    budgetRestoreIntervalMs: number;
+}
+declare class LeakyBucketRateLimit {
+    private budgetConsumed;
+    private intervalHandle?;
+    private readonly options;
+    constructor(options: ConnectionRetryOptions);
+    getBackoffMs(): number;
+    get totalBudgetRestoreTime(): number;
+    consumeBudget(): void;
+    getBudgetConsumed(): number;
+    hasBudget(): boolean;
+    startRestoringBudget(): void;
+    private stopLeak;
+    close(): void;
+}
+
+type TransportOptions = SessionOptions;
+type ProvidedTransportOptions = Partial<TransportOptions>;
+type ClientTransportOptions = TransportOptions & ConnectionRetryOptions;
+type ProvidedClientTransportOptions = Partial<ClientTransportOptions>;
+type ServerTransportOptions = TransportOptions;
+type ProvidedServerTransportOptions = Partial<ServerTransportOptions>;
+
+/**
+ * Represents the possible states of a transport.
+ * @property {'open'} open - The transport is open and operational (note that this doesn't mean it is actively connected)
+ * @property {'closed'} closed - The transport is permanently closed and cannot be reopened.
+ */
+type TransportStatus = 'open' | 'closed';
+interface DeleteSessionOptions {
+    unhealthy: boolean;
+}
+type SessionBoundSendFn = (msg: PartialTransportMessage) => string | undefined;
+/**
+ * Transports manage the lifecycle (creation/deletion) of sessions
+ *
+ * ```plaintext
+ *            ▲
+ *  incoming  │
+ *  messages  │
+ *            ▼
+ *      ┌─────────────┐   1:N   ┌───────────┐   1:1*  ┌────────────┐
+ *      │  Transport  │ ◄─────► │  Session  │ ◄─────► │ Connection │
+ *      └─────────────┘         └───────────┘         └────────────┘
+ *            ▲                               * (may or may not be initialized yet)
+ *            │
+ *            ▼
+ *      ┌───────────┐
+ *      │ Message   │
+ *      │ Listeners │
+ *      └───────────┘
+ * ```
+ * @abstract
+ */
+declare abstract class Transport<ConnType extends Connection> {
+    /**
+     * The status of the transport.
+     */
+    private status;
+    /**
+     * The client ID of this transport.
+     */
+    clientId: TransportClientId;
+    /**
+     * The event dispatcher for handling events of type EventTypes.
+     */
+    eventDispatcher: EventDispatcher<EventTypes>;
+    /**
+     * The options for this transport.
+     */
+    protected options: TransportOptions;
+    log?: Logger;
+    tracer: Tracer;
+    sessions: Map<TransportClientId, Session<ConnType>>;
+    /**
+     * 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: TransportClientId, providedOptions?: ProvidedTransportOptions);
+    bindLogger(fn: LogFn | Logger, level?: LoggingLevel): void;
+    /**
+     * Called when a message is received by this transport.
+     * You generally shouldn't need to override this in downstream transport implementations.
+     * @param message The received message.
+     */
+    protected handleMsg(message: OpaqueTransportMessage): void;
+    /**
+     * Adds a listener to this transport.
+     * @param the type of event to listen for
+     * @param handler The message handler to add.
+     */
+    addEventListener<K extends EventTypes, T extends EventHandler<K>>(type: K, handler: T): void;
+    /**
+     * Removes a listener from this transport.
+     * @param the type of event to un-listen on
+     * @param handler The message handler to remove.
+     */
+    removeEventListener<K extends EventTypes, T extends EventHandler<K>>(type: K, handler: T): void;
+    protected protocolError(message: EventMap['protocolError']): void;
+    /**
+     * Default close implementation for transports. You should override this in the downstream
+     * implementation if you need to do any additional cleanup and call super.close() at the end.
+     * Closes the transport. Any messages sent while the transport is closed will be silently discarded.
+     */
+    close(): void;
+    getStatus(): TransportStatus;
+    protected createSession<S extends Session<ConnType>>(session: S): void;
+    protected updateSession<S extends Session<ConnType>>(session: S): void;
+    protected deleteSession(session: Session<ConnType>, options?: DeleteSessionOptions): void;
+    protected onSessionGracePeriodElapsed(session: Session<ConnType>): void;
+    protected onConnectingFailed(session: SessionConnecting<ConnType>): SessionNoConnection;
+    protected onConnClosed(session: SessionHandshaking<ConnType> | SessionConnected<ConnType>): SessionNoConnection;
+    /**
+     * Gets a send closure scoped to a specific session. Sending using the returned
+     * closure after the session has transitioned to a different state will be a noop.
+     *
+     * Session objects themselves can become stale as they transition between
+     * states. As stale sessions cannot be used again (and will throw), holding
+     * onto a session object is not recommended.
+     */
+    getSessionBoundSendFn(to: TransportClientId, sessionId: SessionId): SessionBoundSendFn;
+}
+
+type ConstructHandshake<T extends TSchema> = () => Static<T> | Promise<Static<T>>;
+type ValidateHandshake<T extends TSchema> = (metadata: Static<T>, previousParsedMetadata?: ParsedMetadata) => Static<typeof HandshakeErrorCustomHandlerFatalResponseCodes> | ParsedMetadata | Promise<Static<typeof HandshakeErrorCustomHandlerFatalResponseCodes> | ParsedMetadata>;
+interface ClientHandshakeOptions<MetadataSchema extends TSchema = TSchema> {
+    /**
+     * Schema for the metadata that the client sends to the server
+     * during the handshake.
+     */
+    schema: MetadataSchema;
+    /**
+     * Gets the {@link HandshakeRequestMetadata} to send to the server.
+     */
+    construct: ConstructHandshake<MetadataSchema>;
+}
+interface ServerHandshakeOptions<MetadataSchema extends TSchema = TSchema> {
+    /**
+     * Schema for the metadata that the server receives from the client
+     * during the handshake.
+     */
+    schema: MetadataSchema;
+    /**
+     * Parses the {@link HandshakeRequestMetadata} sent by the client, transforming
+     * it into {@link ParsedHandshakeMetadata}.
+     *
+     * May return `false` if the client should be rejected.
+     *
+     * @param metadata - The metadata sent by the client.
+     * @param session - The session that the client would be associated with.
+     * @param isReconnect - Whether the client is reconnecting to the session,
+     *                      or if this is a new session.
+     */
+    validate: ValidateHandshake<MetadataSchema>;
+}
+declare function createClientHandshakeOptions<MetadataSchema extends TSchema = TSchema>(schema: MetadataSchema, construct: ConstructHandshake<MetadataSchema>): ClientHandshakeOptions;
+declare function createServerHandshakeOptions<MetadataSchema extends TSchema = TSchema>(schema: MetadataSchema, validate: ValidateHandshake<MetadataSchema>): ServerHandshakeOptions;
+
+declare abstract class ClientTransport<ConnType extends Connection> extends Transport<ConnType> {
+    /**
+     * The options for this transport.
+     */
+    protected options: ClientTransportOptions;
+    retryBudget: LeakyBucketRateLimit;
+    /**
+     * A flag indicating whether the transport should automatically reconnect
+     * when a connection is dropped.
+     * Realistically, this should always be true for clients unless you are writing
+     * tests or a special case where you don't want to reconnect.
+     */
+    reconnectOnConnectionDrop: boolean;
+    /**
+     * Optional handshake options for this client.
+     */
+    handshakeExtensions?: ClientHandshakeOptions;
+    sessions: Map<TransportClientId, ClientSession<ConnType>>;
+    constructor(clientId: TransportClientId, providedOptions?: ProvidedClientTransportOptions);
+    extendHandshake(options: ClientHandshakeOptions): void;
+    /**
+     * Abstract method that creates a new {@link Connection} object.
+     *
+     * @param to The client ID of the node to connect to.
+     * @returns The new connection object.
+     */
+    protected abstract createNewOutgoingConnection(to: TransportClientId): Promise<ConnType>;
+    private tryReconnecting;
+    createUnconnectedSession(to: string): SessionNoConnection;
+    protected onConnectingFailed(session: SessionConnecting<ConnType>): SessionNoConnection;
+    protected onConnClosed(session: SessionHandshaking<ConnType> | SessionConnected<ConnType>): SessionNoConnection;
+    protected onConnectionEstablished(session: SessionConnecting<ConnType>, conn: ConnType): SessionHandshaking<ConnType>;
+    private rejectHandshakeResponse;
+    protected onHandshakeResponse(session: SessionHandshaking<ConnType>, msg: OpaqueTransportMessage): void;
+    /**
+     * Manually attempts to connect to a client.
+     * @param to The client ID of the node to connect to.
+     */
+    connect(to: TransportClientId): void;
+    /**
+     * Manually kills all sessions to the server (including all pending state).
+     * This is useful for when you want to close all connections to a server
+     * and don't want to wait for the grace period to elapse.
+     */
+    hardDisconnect(): void;
+    protected onBackoffFinished(session: SessionBackingOff): void;
+    private sendHandshake;
+    close(): void;
+}
 
 /**
  * {@link UNCAUGHT_ERROR_CODE} is the code that is used when an error is thrown
@@ -31,6 +650,13 @@ type BaseErrorSchemaType = TObject<{
     message: TLiteralString | TString;
     extras: TSchema;
 }>;
+/**
+ * A schema for cancel payloads sent from the client
+ */
+declare const CancelResultSchema: TObject<{
+    code: TLiteral<"CANCEL">;
+    message: TString;
+}>;
 /**
  * {@link ReaderErrorSchema} is the schema for all the built-in river errors that
  * can be emitted to a reader (request reader on the server, and response reader
@@ -248,13 +874,6 @@ declare function Err<const Err extends Static<BaseErrorSchemaType>>(error: Err):
  * Refine a {@link Result} type to its returned payload.
  */
 type ResultUnwrapOk<R> = R extends Result<infer T, infer __E> ? T : never;
-/**
- * Unwrap a {@link Result} type and return the payload if successful,
- * otherwise throws an error.
- * @param result - The result to unwrap.
- * @throws Will throw an error if the result is not ok.
- */
-declare function unwrapOrThrow<T, Err extends Static<BaseErrorSchemaType>>(result: Result<T, Err>): T;
 /**
  * Refine a {@link Result} type to its error payload.
  */
@@ -283,6 +902,101 @@ type ResponseData<RiverClient, ServiceName extends keyof RiverClient, ProcedureN
     resReadable: Readable<infer SubscriptionOutputMessage, Static<BaseErrorSchemaType>>;
 } ? SubscriptionOutputMessage : never : never : never : never;
 
+/**
+ * ServiceContext exist for the purpose of declaration merging
+ * to extend the context with additional properties.
+ *
+ * For example:
+ *
+ * ```ts
+ * declare module '@replit/river' {
+ *   interface ServiceContext {
+ *     db: Database;
+ *   }
+ * }
+ *
+ * createServer(someTransport, myServices, { extendedContext: { db: myDb } });
+ * ```
+ *
+ * Once you do this, your {@link ProcedureHandlerContext} will have `db` property on it.
+ */
+interface ServiceContext {
+}
+/**
+ * The parsed metadata schema for a service. This is the
+ * return value of the {@link ServerHandshakeOptions.validate}
+ * if the handshake extension is used.
+ *
+ * You should use declaration merging to extend this interface
+ * with the sanitized metadata.
+ *
+ * ```ts
+ * declare module '@replit/river' {
+ *   interface ParsedMetadata {
+ *     userId: number;
+ *   }
+ * }
+ * ```
+ */
+interface ParsedMetadata extends Record<string, unknown> {
+}
+/**
+ * This is passed to every procedure handler and contains various context-level
+ * information and utilities. This may be extended, see {@link ServiceContext}
+ */
+type ProcedureHandlerContext<State> = ServiceContext & {
+    /**
+     * State for this service as defined by the service definition.
+     */
+    state: State;
+    /**
+     * The span for this procedure call. You can use this to add attributes, events, and
+     * links to the span.
+     */
+    span: Span;
+    /**
+     * Metadata parsed on the server. See {@link ParsedMetadata}
+     */
+    metadata: ParsedMetadata;
+    /**
+     * The ID of the session that sent this request.
+     */
+    sessionId: SessionId;
+    /**
+     * The ID of the client that sent this request. There may be multiple sessions per client.
+     */
+    from: TransportClientId;
+    /**
+     * This is used to cancel the procedure call from the handler and notify the client that the
+     * call was cancelled.
+     *
+     * Cancelling is not the same as closing procedure calls gracefully, please refer to
+     * the river documentation to understand the difference between the two concepts.
+     */
+    cancel: (message?: string) => ErrResult<Static<typeof CancelResultSchema>>;
+    /**
+     * This signal is a standard [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+     * triggered when the procedure invocation is done. This signal tracks the invocation/request finishing
+     * for _any_ reason, for example:
+     * - client explicit cancellation
+     * - procedure handler explicit cancellation via {@link cancel}
+     * - client session disconnect
+     * - server cancellation due to client invalid payload
+     * - invocation finishes cleanly, this depends on the type of the procedure (i.e. rpc handler return, or in a stream after the client-side has closed the request writable and the server-side has closed the response writable)
+     *
+     * You can use this to pass it on to asynchronous operations (such as fetch).
+     *
+     * You may also want to explicitly register callbacks on the
+     * ['abort' event](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/abort_event)
+     * as a way to cleanup after the request is finished.
+     *
+     * Note that (per standard AbortSignals) callbacks registered _after_ the procedure invocation
+     * is done are not triggered. In such cases, you can check the "aborted" property and cleanup
+     * immediately if needed.
+     */
+    signal: AbortSignal;
+};
+
 /**
  * Brands a type to prevent it from being directly constructed.
  */
@@ -303,6 +1017,7 @@ type ValidProcType = 'rpc' | 'upload' | 'subscription' | 'stream';
  * Represents the payload type for {@link Procedure}s.
  */
 type PayloadType = TSchema;
+type Cancellable<T> = T | Static<typeof CancelResultSchema>;
 /**
  * Procedure for a single message in both directions (1:1).
  *
@@ -320,7 +1035,7 @@ interface RpcProcedure<State, RequestInit extends PayloadType, ResponseData exte
     handler(param: {
         ctx: ProcedureHandlerContext<State>;
         reqInit: Static<RequestInit>;
-    }): Promise<Result<Static<ResponseData>, Static<ResponseErr>>>;
+    }): Promise<Result<Static<ResponseData>, Cancellable<Static<ResponseErr>>>>;
 }
 /**
  * Procedure for a client-stream (potentially preceded by an initialization message),
@@ -343,7 +1058,7 @@ interface UploadProcedure<State, RequestInit extends PayloadType, RequestData ex
         ctx: ProcedureHandlerContext<State>;
         reqInit: Static<RequestInit>;
         reqReadable: Readable<Static<RequestData>, Static<typeof ReaderErrorSchema>>;
-    }): Promise<Result<Static<ResponseData>, Static<ResponseErr>>>;
+    }): Promise<Result<Static<ResponseData>, Cancellable<Static<ResponseErr>>>>;
 }
 /**
  * Procedure for a single message from client, stream from server (1:n).
@@ -362,7 +1077,7 @@ interface SubscriptionProcedure<State, RequestInit extends PayloadType, Response
     handler(param: {
         ctx: ProcedureHandlerContext<State>;
         reqInit: Static<RequestInit>;
-        resWritable: Writable<Result<Static<ResponseData>, Static<ResponseErr>>>;
+        resWritable: Writable<Result<Static<ResponseData>, Cancellable<Static<ResponseErr>>>>;
     }): Promise<void | undefined>;
 }
 /**
@@ -386,7 +1101,7 @@ interface StreamProcedure<State, RequestInit extends PayloadType, RequestData ex
         ctx: ProcedureHandlerContext<State>;
         reqInit: Static<RequestInit>;
         reqReadable: Readable<Static<RequestData>, Static<typeof ReaderErrorSchema>>;
-        resWritable: Writable<Result<Static<ResponseData>, Static<ResponseErr>>>;
+        resWritable: Writable<Result<Static<ResponseData>, Cancellable<Static<ResponseErr>>>>;
     }): Promise<void | undefined>;
 }
 /**
@@ -846,4 +1561,4 @@ declare class ServiceScaffold<State extends object> {
     }>;
 }
 
-export { AnyServiceSchemaMap as A, INVALID_REQUEST_CODE as B, CANCEL_CODE as C, ReaderErrorSchema as D, BaseErrorSchemaType as E, createClient as F, Client as G, Err as H, InstantiatedServiceSchemaMap as I, unwrapOrThrow as J, Result as K, ErrResult as L, OkResult as M, ResultUnwrapOk as N, Ok as O, ProcHandler as P, ResultUnwrapErr as Q, RpcProcedure as R, Service as S, ResponseData as T, UploadProcedure as U, ValidProcType as V, Writable as W, ReadableIterator as X, ReadableResult as Y, AnyProcedure as a, ServiceConfiguration as b, ProcInit as c, ProcRequest as d, ProcResponse as e, ProcErrors as f, ProcType as g, ServiceSchema as h, SerializedServerSchema as i, SerializedServiceSchema as j, SerializedProcedureSchema as k, serializeSchemaV1Compat as l, SerializedServerSchemaProtocolv1 as m, SerializedServiceSchemaProtocolv1 as n, SerializedProcedureSchemaProtocolv1 as o, PayloadType as p, ProcedureMap as q, SubscriptionProcedure as r, serializeSchema as s, StreamProcedure as t, Readable as u, Procedure as v, ProcedureErrorSchemaType as w, flattenErrorType as x, UNCAUGHT_ERROR_CODE as y, UNEXPECTED_DISCONNECT_CODE as z };
+export { ResultUnwrapOk as $, AnyServiceSchemaMap as A, Readable as B, ClientTransport as C, Procedure as D, ProcedureErrorSchemaType as E, flattenErrorType as F, UNCAUGHT_ERROR_CODE as G, UNEXPECTED_DISCONNECT_CODE as H, InstantiatedServiceSchemaMap as I, INVALID_REQUEST_CODE as J, CANCEL_CODE as K, ReaderErrorSchema as L, BaseErrorSchemaType as M, createClient as N, Client as O, ProvidedClientTransportOptions as P, ProcedureHandlerContext as Q, RpcProcedure as R, ServerHandshakeOptions as S, Ok as T, UploadProcedure as U, ValidProcType as V, Writable as W, Err as X, Result as Y, ErrResult as Z, OkResult as _, ProvidedServerTransportOptions as a, ResultUnwrapErr as a0, ResponseData as a1, createClientHandshakeOptions as a2, createServerHandshakeOptions as a3, ClientHandshakeOptions as a4, ReadableIterator as a5, ReadableResult as a6, Transport as a7, SessionOptions as a8, ClientTransportOptions as a9, SessionNoConnection as aa, SessionBoundSendFn as ab, CommonSession as ac, SessionState as ad, CommonSessionProps as ae, ServerTransportOptions as af, ServerSession as ag, DeleteSessionOptions as ah, TransportStatus as ai, ProvidedTransportOptions as aj, Session as ak, SessionConnecting as al, SessionHandshaking as am, SessionConnected as an, EventMap as ao, EventTypes as ap, EventHandler as aq, ProtocolError as ar, ProtocolErrorType as as, Connection as b, ParsedMetadata as c, AnyProcedure as d, ServiceContext as e, Service as f, ServiceConfiguration as g, ProcHandler as h, ProcInit as i, ProcRequest as j, ProcResponse as k, ProcErrors as l, ProcType as m, ServiceSchema as n, SerializedServerSchema as o, SerializedServiceSchema as p, SerializedProcedureSchema as q, serializeSchemaV1Compat as r, serializeSchema as s, SerializedServerSchemaProtocolv1 as t, SerializedServiceSchemaProtocolv1 as u, SerializedProcedureSchemaProtocolv1 as v, PayloadType as w, ProcedureMap as x, SubscriptionProcedure as y, StreamProcedure as z };