@replit/river 0.215.1 → 0.216.0

package/dist/protobuf/index.d.cts

@@ -0,0 +1,488 @@
+export { ProtoCodec } from './codec.cjs';
+import { DescService, DescMethod, DescMethodUnary, MessageShape, MessageInitShape, DescMethodServerStreaming, DescMethodClientStreaming, DescMethodBiDiStreaming, DescMessage } from '@bufbuild/protobuf';
+import { C as ClientTransport } from '../client-BZUvFL6B.cjs';
+import { z as SessionId, C as Connection, n as ClientHandshakeOptions, q as ServerHandshakeOptions } from '../transport-BnU3Zb0Q.cjs';
+import { T as TransportClientId, f as HandshakeErrorCustomHandlerFatalResponseCodes, O as OpaqueTransportMessage } from '../message-CpXWqmJw.cjs';
+import { a0 as ErrorPayload, C as CANCEL_CODE, e as INVALID_REQUEST_CODE, U as UNCAUGHT_ERROR_CODE, N as UNEXPECTED_DISCONNECT_CODE, d as ErrResult, v as Result, W as Writable, q as Readable } from '../services-cwGAC2rB.cjs';
+export { E as Err, O as Ok, f as OkResult, r as ReadableBrokenError, s as ReadableResult, w as ResultUnwrapErr, x as ResultUnwrapOk } from '../services-cwGAC2rB.cjs';
+import { Span } from '@opentelemetry/api';
+import * as _sinclair_typebox from '@sinclair/typebox';
+import { Static, TSchema } from '@sinclair/typebox';
+import { S as ServerTransport } from '../server-JdnoVO11.cjs';
+import '../types-BGGvYIJM.cjs';
+import '../index-BAGGleT3.cjs';
+import '../adapter-D5X11kmP.cjs';
+
+/**
+ * Canonical RPC error codes shared by gRPC and Connect.
+ *
+ * The protobuf router uses these codes for unary rejections and streamed error
+ * messages so applications can reason about familiar transport-agnostic error
+ * categories.
+ */
+declare enum RiverErrorCode {
+    OK = "OK",
+    CANCELED = "CANCELED",
+    UNKNOWN = "UNKNOWN",
+    INVALID_ARGUMENT = "INVALID_ARGUMENT",
+    DEADLINE_EXCEEDED = "DEADLINE_EXCEEDED",
+    NOT_FOUND = "NOT_FOUND",
+    ALREADY_EXISTS = "ALREADY_EXISTS",
+    PERMISSION_DENIED = "PERMISSION_DENIED",
+    RESOURCE_EXHAUSTED = "RESOURCE_EXHAUSTED",
+    FAILED_PRECONDITION = "FAILED_PRECONDITION",
+    ABORTED = "ABORTED",
+    OUT_OF_RANGE = "OUT_OF_RANGE",
+    UNIMPLEMENTED = "UNIMPLEMENTED",
+    INTERNAL = "INTERNAL",
+    UNAVAILABLE = "UNAVAILABLE",
+    DATA_LOSS = "DATA_LOSS",
+    UNAUTHENTICATED = "UNAUTHENTICATED"
+}
+/**
+ * Protocol-level error codes surfaced by River itself rather than user
+ * handlers.
+ */
+type ProtocolErrorCode = typeof CANCEL_CODE | typeof INVALID_REQUEST_CODE | typeof UNCAUGHT_ERROR_CODE | typeof UNEXPECTED_DISCONNECT_CODE;
+/**
+ * Error codes visible from the protobuf client surface.
+ */
+type ClientErrorCode = RiverErrorCode | ProtocolErrorCode;
+/**
+ * A serialized protobuf error detail.
+ *
+ * The `typeName` identifies the protobuf message descriptor the client can use
+ * to decode `value`.
+ */
+interface RiverErrorDetail {
+    readonly typeName: string;
+    readonly value: Uint8Array;
+}
+/**
+ * A plain-object error payload used by the protobuf router.
+ *
+ * Handlers return these via `Err({ code, message, ... })`.
+ */
+interface ClientError extends ErrorPayload {
+    readonly code: ClientErrorCode;
+    readonly metadata?: Readonly<Record<string, string>>;
+    readonly details?: ReadonlyArray<RiverErrorDetail>;
+}
+/**
+ * A protocol error emitted by the River runtime.
+ */
+interface ProtocolError extends ClientError {
+    readonly code: ProtocolErrorCode;
+}
+/**
+ * Returns true when the given value matches the wire shape of a client error
+ * with a canonical RPC error code.
+ */
+declare function isRiverError(value: unknown): value is ClientError;
+/**
+ * Returns true when the given value is a protocol error.
+ */
+declare function isProtocolError(value: unknown): value is ProtocolError;
+/**
+ * Returns true when the given value is any client-visible error.
+ */
+declare function isClientError(value: unknown): value is ClientError;
+/**
+ * Returns true when the given value matches the `Err(...)` wrapper used for
+ * protobuf cancel payloads sent by the runtime or handlers.
+ */
+declare function isSerializedClientErrorResult(value: unknown): value is ErrResult<ClientError>;
+/**
+ * Returns true when the given value matches the protocol-only cancel payloads
+ * sent by clients.
+ */
+declare function isSerializedProtocolErrorResult(value: unknown): value is ErrResult<ProtocolError>;
+
+/**
+ * Context passed to protobuf handler invocations.
+ *
+ * User-provided `Context` is spread into the type so handler authors can
+ * access application dependencies directly (e.g. `ctx.db`). Per-service
+ * `State` is available via `ctx.state`.
+ */
+type ProtobufHandlerContext<Context extends object = object, State extends object = object, ParsedMetadata extends object = object> = Context & {
+    /**
+     * Per-service state created by {@link ProtoService}'s `initializeState`.
+     */
+    readonly state: State;
+    /**
+     * The span for the current procedure call.
+     */
+    readonly span: Span;
+    /**
+     * Metadata parsed during the transport handshake.
+     */
+    readonly metadata: ParsedMetadata;
+    /**
+     * The session this invocation belongs to.
+     */
+    readonly sessionId: SessionId;
+    /**
+     * The remote transport client id that initiated the invocation.
+     */
+    readonly from: TransportClientId;
+    /**
+     * The protobuf service being invoked.
+     */
+    readonly service: DescService;
+    /**
+     * The protobuf method being invoked.
+     */
+    readonly method: DescMethod;
+    /**
+     * Register cleanup work that should run once the invocation finishes.
+     */
+    readonly deferCleanup: (fn: () => void | Promise<void>) => void;
+    /**
+     * Cancel the invocation and notify the client with a protocol-level cancel
+     * error.
+     */
+    readonly cancel: (message?: string) => ErrResult<ProtocolError>;
+    /**
+     * Aborts when the invocation finishes for any reason.
+     */
+    readonly signal: AbortSignal;
+};
+
+type Awaitable<T> = T | PromiseLike<T>;
+type HandlerResult<Method extends DescMethod, Error extends ClientError = ClientError> = Result<MessageInitShape<Method['output']>, Error>;
+/**
+ * Options shared by protobuf-router client calls.
+ */
+interface CallOptions {
+    readonly signal?: AbortSignal;
+}
+/**
+ * The client-side surface for a client-streaming method.
+ */
+interface ClientStreamingCall<Method extends DescMethodClientStreaming> {
+    readonly reqWritable: Writable<MessageInitShape<Method['input']>>;
+    readonly finalize: () => Promise<Result<MessageShape<Method['output']>, ClientError>>;
+}
+/**
+ * The client-side surface for a bidi-streaming method.
+ */
+interface BiDiStreamingCall<Method extends DescMethodBiDiStreaming> {
+    readonly reqWritable: Writable<MessageInitShape<Method['input']>>;
+    readonly resReadable: Readable<MessageShape<Method['output']>, ClientError>;
+}
+/**
+ * A protobuf-router unary handler.
+ */
+type UnaryImpl<Method extends DescMethodUnary, Context extends object = object, State extends object = object, ParsedMetadata extends object = object> = (request: MessageShape<Method['input']>, ctx: ProtobufHandlerContext<Context, State, ParsedMetadata>) => Awaitable<HandlerResult<Method>>;
+/**
+ * A protobuf-router server-streaming handler.
+ */
+type ServerStreamingImpl<Method extends DescMethodServerStreaming, Context extends object = object, State extends object = object, ParsedMetadata extends object = object> = (param: {
+    readonly request: MessageShape<Method['input']>;
+    readonly ctx: ProtobufHandlerContext<Context, State, ParsedMetadata>;
+    readonly resWritable: Writable<HandlerResult<Method>>;
+}) => Awaitable<void>;
+/**
+ * A protobuf-router client-streaming handler.
+ */
+type ClientStreamingImpl<Method extends DescMethodClientStreaming, Context extends object = object, State extends object = object, ParsedMetadata extends object = object> = (param: {
+    readonly ctx: ProtobufHandlerContext<Context, State, ParsedMetadata>;
+    readonly reqReadable: Readable<MessageShape<Method['input']>, ProtocolError>;
+}) => Awaitable<HandlerResult<Method>>;
+/**
+ * A protobuf-router bidi-streaming handler.
+ */
+type BiDiStreamingImpl<Method extends DescMethodBiDiStreaming, Context extends object = object, State extends object = object, ParsedMetadata extends object = object> = (param: {
+    readonly ctx: ProtobufHandlerContext<Context, State, ParsedMetadata>;
+    readonly reqReadable: Readable<MessageShape<Method['input']>, ProtocolError>;
+    readonly resWritable: Writable<HandlerResult<Method>>;
+}) => Awaitable<void>;
+/**
+ * The handler type for an arbitrary protobuf method descriptor.
+ */
+type MethodImpl<Method extends DescMethod, Context extends object = object, State extends object = object, ParsedMetadata extends object = object> = Method extends DescMethodUnary ? UnaryImpl<Method, Context, State, ParsedMetadata> : Method extends DescMethodServerStreaming ? ServerStreamingImpl<Method, Context, State, ParsedMetadata> : Method extends DescMethodClientStreaming ? ClientStreamingImpl<Method, Context, State, ParsedMetadata> : Method extends DescMethodBiDiStreaming ? BiDiStreamingImpl<Method, Context, State, ParsedMetadata> : never;
+/**
+ * Partial implementation shape for a protobuf service.
+ *
+ * All methods are optional -- missing methods return UNIMPLEMENTED at runtime.
+ */
+type ServiceImpl<Service extends DescService, Context extends object = object, State extends object = object, ParsedMetadata extends object = object> = {
+    [MethodName in keyof Service['method']]?: MethodImpl<Service['method'][MethodName] & DescMethod, Context, State, ParsedMetadata>;
+};
+/**
+ * The client surface for an arbitrary protobuf method descriptor.
+ */
+type ClientMethod<Method extends DescMethod> = Method extends DescMethodUnary ? (request: MessageInitShape<Method['input']>, options?: CallOptions) => Promise<Result<MessageShape<Method['output']>, ClientError>> : Method extends DescMethodServerStreaming ? (request: MessageInitShape<Method['input']>, options?: CallOptions) => Readable<MessageShape<Method['output']>, ClientError> : Method extends DescMethodClientStreaming ? (options?: CallOptions) => ClientStreamingCall<Method> : Method extends DescMethodBiDiStreaming ? (options?: CallOptions) => BiDiStreamingCall<Method> : never;
+/**
+ * The generated client shape for a protobuf service descriptor.
+ */
+type Client<Service extends DescService> = {
+    [MethodName in keyof Service['method']]: Service['method'][MethodName] extends DescMethod ? ClientMethod<Service['method'][MethodName]> : never;
+};
+
+/**
+ * Options for the protobuf client.
+ */
+interface ClientOptions {
+    readonly connectOnInvoke: boolean;
+    readonly eagerlyConnect: boolean;
+}
+/**
+ * Creates a protobuf client for a single protobuf service descriptor.
+ */
+declare function createClient<Service extends DescService>(service: Service, transport: ClientTransport<Connection>, serverId: TransportClientId, providedClientOptions?: Partial<ClientOptions & {
+    handshakeOptions: ClientHandshakeOptions;
+}>): Client<Service>;
+
+/**
+ * The handshake metadata for protobuf services travels as encoded protobuf bytes
+ * over River's existing handshake extension slot.
+ */
+declare const HandshakeBytesSchema: _sinclair_typebox.TUint8Array;
+type ProtobufHandshakeFailureCode = Static<typeof HandshakeErrorCustomHandlerFatalResponseCodes>;
+type ConstructHandshake<Schema extends DescMessage> = () => MessageInitShape<Schema> | Promise<MessageInitShape<Schema>>;
+type ValidateHandshake<Schema extends DescMessage, ParsedMetadata> = (metadata: MessageShape<Schema>, previousParsedMetadata?: ParsedMetadata) => ParsedMetadata | ProtobufHandshakeFailureCode | Promise<ParsedMetadata | ProtobufHandshakeFailureCode>;
+/**
+ * Create client-side handshake options backed by a protobuf message type.
+ */
+declare function createClientHandshakeOptions<Schema extends DescMessage>(schema: Schema, construct: ConstructHandshake<Schema>): ClientHandshakeOptions<typeof HandshakeBytesSchema>;
+/**
+ * Create server-side handshake options backed by a protobuf message type.
+ */
+declare function createServerHandshakeOptions<Schema extends DescMessage, ParsedMetadata extends object = object>(schema: Schema, validate: ValidateHandshake<Schema, ParsedMetadata>): ServerHandshakeOptions<typeof HandshakeBytesSchema, ParsedMetadata>;
+
+/**
+ * An object that may implement async or sync disposal.
+ */
+type MaybeDisposable<T extends object = Record<string, unknown>> = T & {
+    [Symbol.asyncDispose]?: () => PromiseLike<void>;
+    [Symbol.dispose]?: () => void;
+};
+/**
+ * Stored registration for a single protobuf method handler.
+ */
+interface RegisteredMethod {
+    readonly service: DescService;
+    readonly method: DescMethod;
+    readonly impl: MethodImpl<DescMethod, any, any, any>;
+}
+/**
+ * An instantiated protobuf service with initialized state and a disposal hook.
+ */
+interface InstantiatedProtoService {
+    readonly descriptor: DescService;
+    readonly state: MaybeDisposable<object>;
+    readonly methods: ReadonlyMap<string, RegisteredMethod>;
+    [Symbol.asyncDispose]: () => PromiseLike<void>;
+}
+/**
+ * Type-erased interface used by the server to interact with a
+ * service definition without knowing its full generic signature.
+ */
+interface AnyProtoService {
+    readonly descriptor: DescService;
+    readonly methods: ReadonlyMap<string, RegisteredMethod>;
+    instantiate(ctx: object): InstantiatedProtoService;
+}
+interface ServiceConfiguration<Context extends object, State extends object> {
+    initializeState: (ctx: Context) => MaybeDisposable<State>;
+}
+/**
+ * A scaffold for defining a protobuf service's handlers across multiple files.
+ *
+ * @see {@link ProtoServiceSchema.scaffold}
+ */
+declare class ProtoServiceScaffold<Service extends DescService, Context extends object, State extends object, ParsedMetadata extends object> {
+    private readonly descriptor;
+    private readonly config;
+    constructor(descriptor: Service, config: ServiceConfiguration<Context, State>);
+    /**
+     * Type-check a partial set of handler implementations against this
+     * service's types. Returns the input unchanged -- this is purely a
+     * type-level helper for splitting handlers across files.
+     *
+     * @param handlers - A partial set of method implementations.
+     */
+    procedures(handlers: ServiceImpl<Service, Context, State, ParsedMetadata>): ServiceImpl<Service, Context, State, ParsedMetadata>;
+    /**
+     * Finalize the scaffold into a service definition. Provide all handlers
+     * here (or spread in handler objects from {@link procedures}).
+     *
+     * @param handlers - Method implementations (missing methods return
+     *   UNIMPLEMENTED at runtime).
+     */
+    finalize(handlers: ServiceImpl<Service, Context, State, ParsedMetadata>): {
+        readonly descriptor: Service;
+        readonly methods: ReadonlyMap<string, RegisteredMethod>;
+        /** @internal */
+        readonly initializeStateFn: ((ctx: Context) => MaybeDisposable<State>) | undefined;
+        /**
+         * Create a live service instance with initialized state.
+         *
+         * @param ctx - The user-provided context, passed to `initializeState`.
+         */
+        instantiate(ctx: Context): InstantiatedProtoService;
+    };
+}
+/**
+ * Creates a factory for defining protobuf services with typed context and
+ * metadata.
+ *
+ * This mirrors {@link createServiceSchema} from the TypeBox router. The
+ * factory binds the `Context` and `ParsedMetadata` types, then provides
+ * `.define()` and `.scaffold()` methods for creating service definitions.
+ *
+ * @example
+ * ```ts
+ * const ProtoService = createProtoService<AppContext, ParsedMetadata>();
+ *
+ * // all-in-one (stateless)
+ * const testSvc = ProtoService.define(TestService, {
+ *   echo: (req, ctx) => Ok({ text: req.text }),
+ * });
+ *
+ * // all-in-one (with state)
+ * const testSvc = ProtoService.define(
+ *   TestService,
+ *   { initializeState: (ctx) => ({ counter: 0 }) },
+ *   {
+ *     echo: (req, ctx) => {
+ *       ctx.state.counter++;
+ *       return Ok({ text: req.text });
+ *     },
+ *   },
+ * );
+ *
+ * // scaffold for file-splitting
+ * const scaffold = ProtoService.scaffold(TestService, {
+ *   initializeState: (ctx) => ({ counter: 0 }),
+ * });
+ * const echoHandlers = scaffold.procedures({
+ *   echo: (req, ctx) => Ok({ text: req.text }),
+ * });
+ * const testSvc = scaffold.finalize({
+ *   ...echoHandlers,
+ * });
+ *
+ * const server = createServer(transport, [testSvc], {
+ *   context: myAppContext,
+ * });
+ * ```
+ */
+declare function createProtoService<Context extends object = object, ParsedMetadata extends object = object>(): {
+    new <Service extends DescService, State extends object>(descriptor: Service, initializeStateFn: ((ctx: Context) => MaybeDisposable<State>) | undefined, methods: Map<string, RegisteredMethod>): {
+        readonly descriptor: Service;
+        readonly methods: ReadonlyMap<string, RegisteredMethod>;
+        /** @internal */
+        readonly initializeStateFn: ((ctx: Context) => MaybeDisposable<State>) | undefined;
+        /**
+         * Create a live service instance with initialized state.
+         *
+         * @param ctx - The user-provided context, passed to `initializeState`.
+         */
+        instantiate(ctx: Context): InstantiatedProtoService;
+    };
+    /**
+     * Define a stateless protobuf service with the given handlers.
+     *
+     * @param descriptor - The generated protobuf service descriptor.
+     * @param handlers - Method implementations (missing methods return
+     *   UNIMPLEMENTED at runtime).
+     */
+    define<S extends DescService>(descriptor: S, handlers: ServiceImpl<S, Context, object, ParsedMetadata>): {
+        readonly descriptor: S;
+        readonly methods: ReadonlyMap<string, RegisteredMethod>;
+        /** @internal */
+        readonly initializeStateFn: ((ctx: Context) => MaybeDisposable<object>) | undefined;
+        /**
+         * Create a live service instance with initialized state.
+         *
+         * @param ctx - The user-provided context, passed to `initializeState`.
+         */
+        instantiate(ctx: Context): InstantiatedProtoService;
+    };
+    /**
+     * Define a stateless protobuf service with the given handlers.
+     *
+     * @param descriptor - The generated protobuf service descriptor.
+     * @param handlers - Method implementations (missing methods return
+     *   UNIMPLEMENTED at runtime).
+     */
+    define<S_1 extends DescService, St extends object>(descriptor: S_1, config: ServiceConfiguration<Context, St>, handlers: ServiceImpl<S_1, Context, St, ParsedMetadata>): {
+        readonly descriptor: S_1;
+        readonly methods: ReadonlyMap<string, RegisteredMethod>;
+        /** @internal */
+        readonly initializeStateFn: ((ctx: Context) => MaybeDisposable<St>) | undefined;
+        /**
+         * Create a live service instance with initialized state.
+         *
+         * @param ctx - The user-provided context, passed to `initializeState`.
+         */
+        instantiate(ctx: Context): InstantiatedProtoService;
+    };
+    /**
+     * Create a scaffold for splitting handler implementations across files.
+     *
+     * @param descriptor - The generated protobuf service descriptor.
+     * @param config - Service configuration including `initializeState`.
+     */
+    scaffold<S_2 extends DescService, St_1 extends object>(descriptor: S_2, config: ServiceConfiguration<Context, St_1>): ProtoServiceScaffold<S_2, Context, St_1, ParsedMetadata>;
+};
+
+type StreamId = string;
+interface ProcStream {
+    readonly streamId: StreamId;
+    readonly from: TransportClientId;
+    readonly service: DescService;
+    readonly method: DescMethod;
+    readonly handleMsg: (msg: OpaqueTransportMessage) => void;
+    readonly handleSessionDisconnect: () => void;
+}
+/**
+ * Server instance for the protobuf router.
+ */
+interface Server {
+    readonly streams: Map<StreamId, ProcStream>;
+    close(): Promise<void>;
+}
+/**
+ * Context passed to protobuf middleware.
+ */
+type MiddlewareContext<ParsedMetadata extends object = object> = Readonly<Omit<ProtobufHandlerContext<object, object, ParsedMetadata>, 'cancel'>> & {
+    readonly streamId: StreamId;
+    readonly procedureName: string;
+    readonly serviceName: string;
+};
+/**
+ * Parameters passed to protobuf middleware.
+ */
+interface MiddlewareParam<ParsedMetadata extends object = object> {
+    readonly ctx: MiddlewareContext<ParsedMetadata>;
+    readonly reqInit: MessageShape<DescMethod['input']> | null;
+    next: () => void;
+}
+/**
+ * Middleware is a function that can inspect protobuf requests as they are
+ * received.
+ */
+type Middleware<ParsedMetadata extends object = object> = (param: MiddlewareParam<ParsedMetadata>) => void;
+/**
+ * Options for creating a protobuf server.
+ */
+interface ServerOptions<MetadataSchema extends TSchema, ParsedMetadata extends object> {
+    readonly extendedContext?: object;
+    readonly handshakeOptions?: ServerHandshakeOptions<MetadataSchema, ParsedMetadata>;
+    readonly middlewares?: Array<Middleware<ParsedMetadata>>;
+    readonly maxCancelledStreamTombstonesPerSession?: number;
+}
+/**
+ * Creates a protobuf server that listens on an existing River transport.
+ *
+ * @param transport - The server transport to listen on.
+ * @param services - Array of {@link ProtoService} definitions.
+ * @param options - Server options including context, handshake, and middleware.
+ */
+declare function createServer<MetadataSchema extends TSchema, ParsedMetadata extends object>(transport: ServerTransport<Connection, MetadataSchema, ParsedMetadata>, services: ReadonlyArray<AnyProtoService>, options?: ServerOptions<MetadataSchema, ParsedMetadata>): Server;
+
+export { type AnyProtoService, type BiDiStreamingCall, CANCEL_CODE, type CallOptions, type Client, type ClientError, type ClientErrorCode, type ClientMethod, type ClientStreamingCall, ErrResult, INVALID_REQUEST_CODE, type InstantiatedProtoService, type MaybeDisposable, type MethodImpl, type Middleware, type MiddlewareContext, type MiddlewareParam, type ClientOptions as ProtobufClientOptions, type ProtobufHandlerContext, type ServerOptions as ProtobufServerOptions, type ProtocolError, type ProtocolErrorCode, Readable, Result, RiverErrorCode, type RiverErrorDetail, type Server, type ServiceImpl, UNCAUGHT_ERROR_CODE, UNEXPECTED_DISCONNECT_CODE, Writable, createClient, createClientHandshakeOptions, createProtoService, createServer, createServerHandshakeOptions, isClientError, isProtocolError, isRiverError, isSerializedClientErrorResult, isSerializedProtocolErrorResult };