@orpc/experimental-durable-iterator 0.0.0-next.012cf1e

package/dist/durable-object/index.d.mts

@@ -0,0 +1,290 @@
+import { RPCHandlerOptions } from '@orpc/server/websocket';
+import { DurableObject } from 'cloudflare:workers';
+import { b as DurableIteratorTokenPayload, a as DurableIteratorObjectDef, D as DurableIteratorObject$1 } from '../shared/experimental-durable-iterator.DQjHfIr1.mjs';
+import { StandardRPCJsonSerializerOptions } from '@orpc/client/standard';
+import { Interceptor } from '@orpc/shared';
+export { withEventMeta } from '@orpc/server';
+import '@orpc/client';
+import 'valibot';
+
+interface DurableIteratorWebsocketInternal {
+    /**
+     * Access the original websocket instance
+     *
+     * @warning Be careful when using original because you can accidentally modifying internal state.
+     */
+    original: WebSocket;
+    /**
+     * Serialize the websocket id
+     *
+     * @warning this method should be called when client established connection
+     */
+    serializeId(id: string): void;
+    /**
+     * Deserialize the websocket id
+     *
+     * @warning this method assumes that the id is already set when client established connection
+     */
+    deserializeId(): string;
+    /**
+     * Serialize the token payload usually when client connected
+     *
+     * @warning this method should be called when client established connection or when token payload is updated
+     */
+    serializeTokenPayload(payload: DurableIteratorTokenPayload): void;
+    /**
+     * Deserialize the payload attached when client connected
+     *
+     * @warning this method assumes that the token payload is already set when client established connection
+     */
+    deserializeTokenPayload(): DurableIteratorTokenPayload;
+    /**
+     * Serialize the hibernation id used for publishing events to the client
+     */
+    serializeHibernationId(id: string): void;
+    /**
+     * Deserialize the hibernation id used for publishing events to the client
+     */
+    deserializeHibernationId(): string | undefined;
+    /**
+     * Close the websocket connection if expired
+     *
+     * @warning this method assumes that the token payload is already set when client established connection
+     */
+    closeIfExpired(): void;
+}
+interface DurableIteratorWebsocket extends WebSocket {
+    /**
+     * Durable Event internal apis
+     */
+    ['~orpc']: DurableIteratorWebsocketInternal;
+}
+/**
+ * Create a Durable Iterator WebSocket from a regular WebSocket
+ *
+ * @info The websocket automatically closes if expired before sending data
+ */
+declare function toDurableIteratorWebsocket(original: WebSocket): DurableIteratorWebsocket;
+
+interface DurableIteratorObjectStateInternal {
+    /**
+     * The original DurableObjectState
+     *
+     * @warning Be careful when using original because you can accidentally modifying internal state.
+     */
+    original: DurableObjectState;
+}
+interface DurableIteratorObjectState<TProps> extends DurableObjectState<TProps> {
+    /**
+     * DurableIteratorObjectState internal apis
+     */
+    '~orpc': DurableIteratorObjectStateInternal;
+    /**
+     * Get all WebSockets connected to this Durable Object
+     * And convert them to DurableIteratorWebsocket to avoid accidentally modifying internal state
+     */
+    'getWebSockets'(...args: Parameters<DurableObjectState['getWebSockets']>): DurableIteratorWebsocket[];
+}
+declare function toDurableIteratorObjectState<TProps>(original: DurableObjectState<TProps>): DurableIteratorObjectState<TProps>;
+
+interface EventResumeStorageOptions extends StandardRPCJsonSerializerOptions {
+    /**
+     * How long (in seconds) to retain events for reconnection replay.
+     *
+     * When a client reconnects, stored events within this window can be replayed
+     * to ensure no data is lost. Outside this window, missed events are dropped.
+     *
+     * @remarks
+     * - Use infinite values to disable
+     * - Note that for performance, expired event cleanup is deferred. This means
+     *  expired events may remain in storage for a short period beyond their
+     *  retention time.
+     *
+     * @default NaN (disabled)
+     */
+    resumeRetentionSeconds?: number;
+    /**
+     * Prefix for the resume storage table schema.
+     * This is used to avoid naming conflicts with other tables in the same Durable Object.
+     *
+     * @default 'orpc:durable-iterator:resume:'
+     */
+    resumeSchemaPrefix?: string;
+}
+interface ResumeEventFilter {
+    /** Only websockets with these tags will receive the event */
+    tags?: readonly string[];
+    /** Only websockets that are in this list will receive the event */
+    targets?: readonly DurableIteratorWebsocket[];
+    /** Websockets that are in this list will not receive the event */
+    exclude?: readonly DurableIteratorWebsocket[];
+}
+declare class EventResumeStorage<T extends object> {
+    private readonly durableState;
+    private readonly serializer;
+    private readonly retentionSeconds;
+    private readonly schemaPrefix;
+    get isEnabled(): boolean;
+    constructor(durableState: DurableObjectState, options?: EventResumeStorageOptions);
+    /**
+     * Store an payload for resume capability.
+     *
+     * @returns The updated meta of the stored payload
+     */
+    store(payload: T, resumeFilter: ResumeEventFilter): T;
+    /**
+     * Get events after lastEventId for a specific websocket
+     */
+    get(websocket: DurableIteratorWebsocket, lastEventId: string): T[];
+    private initSchema;
+    private resetSchema;
+    private lastCleanupTime;
+    private cleanupExpiredEvents;
+    private serializeEventPayload;
+    private deserializeEventPayload;
+    private withEventId;
+}
+
+type DurableIteratorObjectRouterContext = {
+    object: DurableObject<any, any>;
+    resumeStorage: EventResumeStorage<any>;
+    websocket: DurableIteratorWebsocket;
+    options: DurableIteratorObjectHandlerOptions;
+};
+interface PublishEventOptions {
+    /**
+     * Deliver the event only to websockets that have the specified tags.
+     */
+    tags?: readonly string[];
+    /**
+     * Restrict the event to a specific set of websockets.
+     *
+     * Accept a list of websockets or a filter function.
+     *
+     * Use this when security is important — only the listed websockets
+     * will ever receive the event. Newly connected websockets are not
+     * included unless explicitly added here.
+     */
+    targets?: readonly WebSocket[] | ((ws: DurableIteratorWebsocket) => boolean);
+    /**
+     * Exclude certain websockets from receiving the event.
+     *
+     * Accept a list of websockets or a filter function.
+     *
+     * Use this when broadcasting widely but skipping a few clients
+     * (e.g., the sender). Newly connected websockets may still receive
+     * the event if not listed here, so this is less strict than `targets`.
+     */
+    exclude?: readonly WebSocket[] | ((ws: DurableIteratorWebsocket) => boolean);
+}
+interface DurableIteratorObjectHandlerOptions extends RPCHandlerOptions<DurableIteratorObjectRouterContext>, EventResumeStorageOptions {
+    /**
+     * The signing key to use verify the token.
+     */
+    signingKey: string;
+    /**
+     * Called after a client successfully subscribes to the main iterator.
+     * You can start sending events to the client here.
+     *
+     * @param websocket Corresponding WebSocket connection.
+     * @param lastEventId Can be `undefined` if this is the first connection (not a resumed session).
+     */
+    onSubscribed?: (websocket: DurableIteratorWebsocket, lastEventId: string | undefined) => void;
+}
+declare class DurableIteratorObjectHandler<T extends object, TProps> implements DurableIteratorObjectDef<T> {
+    private readonly object;
+    private readonly options;
+    '~eventPayloadType'?: {
+        type: T;
+    };
+    private readonly handler;
+    private readonly resumeStorage;
+    /**
+     * Proxied, ensure you don't accidentally change internal state, and auto close if expired websockets before .send is called
+     */
+    ctx: DurableIteratorObjectState<TProps>;
+    constructor(ctx: DurableObjectState<TProps>, object: DurableObject<any, TProps>, options: DurableIteratorObjectHandlerOptions);
+    /**
+     * Publish an event to a set of clients.
+     */
+    publishEvent(payload: T, options?: PublishEventOptions): void;
+    /**
+     * This method is called when a HTTP request is received for upgrading to a WebSocket connection.
+     * Should mapping with corresponding `fetch` inside durable object
+     */
+    fetch(request: Request): Promise<Response>;
+    /**
+     * This method is called when a WebSocket message is received.
+     * Should mapping with corresponding `webSocketMessage` inside durable object
+     */
+    webSocketMessage(websocket_: WebSocket, message: string | ArrayBuffer): Promise<void>;
+    /**
+     * This method is called when a WebSocket connection is closed.
+     * Should mapping with corresponding `webSocketClose` inside durable object
+     */
+    webSocketClose(ws_: WebSocket, _code: number, _reason: string, _wasClean: boolean): void | Promise<void>;
+}
+
+declare class DurableIteratorObject<T extends object, TEnv = Cloudflare.Env, TProps = {}> extends DurableObject<TEnv, TProps> implements DurableIteratorObject$1<T> {
+    '~orpc': DurableIteratorObjectHandler<T, TProps>;
+    /**
+     * Proxied, ensure you don't accidentally change internal state, and auto close if expired websockets before .send is called
+     */
+    protected ctx: DurableIteratorObjectState<TProps>;
+    constructor(ctx: DurableObjectState<TProps>, env: TEnv, options: DurableIteratorObjectHandlerOptions);
+    /**
+     * Publish an event to clients
+     */
+    publishEvent(payload: T, options?: PublishEventOptions): void;
+    /**
+     * Upgrades websocket connection
+     *
+     * @info You can safety intercept non-upgrade requests
+     * @warning No verification is done here, you should verify the token payload before calling this method.
+     */
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Handle WebSocket messages
+     *
+     * @warning Use `toDurableIteratorWebsocket` to proxy the WebSocket when interacting
+     *          to avoid accidentally modifying internal state, and auto close if expired before .send is called
+     */
+    webSocketMessage(websocket: WebSocket, message: string | ArrayBuffer): Promise<void>;
+    /**
+     * Handle WebSocket close event
+     *
+     * @warning Use `toDurableIteratorWebsocket` to proxy the WebSocket when interacting
+     *          to avoid accidentally modifying internal state, and auto close if expired before .send is called
+     */
+    webSocketClose(websocket: WebSocket, code: number, reason: string, wasClean: boolean): void | Promise<void>;
+}
+
+interface UpgradeDurableIteratorRequestOptions {
+    /**
+     * The signing key used to verify the token
+     */
+    signingKey: string;
+    /**
+     * The durable object namespace
+     */
+    namespace: DurableObjectNamespace<any>;
+    /**
+     * The options to use when getting the durable object stub
+     */
+    namespaceGetOptions?: DurableObjectNamespaceGetDurableObjectOptions;
+    /**
+     * intercept upgrade process
+     */
+    interceptors?: Interceptor<{
+        payload: DurableIteratorTokenPayload;
+    }, Promise<Response>>[];
+}
+/**
+ * Verifies and upgrades a durable iterator request.
+ *
+ * @info Verify token before forwarding to durable object to prevent DDoS attacks
+ */
+declare function upgradeDurableIteratorRequest(request: Request, options: UpgradeDurableIteratorRequestOptions): Promise<Response>;
+
+export { DurableIteratorObject, DurableIteratorObjectHandler, EventResumeStorage, toDurableIteratorObjectState, toDurableIteratorWebsocket, upgradeDurableIteratorRequest };
+export type { DurableIteratorObjectHandlerOptions, DurableIteratorObjectState, DurableIteratorObjectStateInternal, DurableIteratorWebsocket, DurableIteratorWebsocketInternal, EventResumeStorageOptions, PublishEventOptions, ResumeEventFilter, UpgradeDurableIteratorRequestOptions };

package/dist/durable-object/index.d.ts

@@ -0,0 +1,290 @@
+import { RPCHandlerOptions } from '@orpc/server/websocket';
+import { DurableObject } from 'cloudflare:workers';
+import { b as DurableIteratorTokenPayload, a as DurableIteratorObjectDef, D as DurableIteratorObject$1 } from '../shared/experimental-durable-iterator.DQjHfIr1.js';
+import { StandardRPCJsonSerializerOptions } from '@orpc/client/standard';
+import { Interceptor } from '@orpc/shared';
+export { withEventMeta } from '@orpc/server';
+import '@orpc/client';
+import 'valibot';
+
+interface DurableIteratorWebsocketInternal {
+    /**
+     * Access the original websocket instance
+     *
+     * @warning Be careful when using original because you can accidentally modifying internal state.
+     */
+    original: WebSocket;
+    /**
+     * Serialize the websocket id
+     *
+     * @warning this method should be called when client established connection
+     */
+    serializeId(id: string): void;
+    /**
+     * Deserialize the websocket id
+     *
+     * @warning this method assumes that the id is already set when client established connection
+     */
+    deserializeId(): string;
+    /**
+     * Serialize the token payload usually when client connected
+     *
+     * @warning this method should be called when client established connection or when token payload is updated
+     */
+    serializeTokenPayload(payload: DurableIteratorTokenPayload): void;
+    /**
+     * Deserialize the payload attached when client connected
+     *
+     * @warning this method assumes that the token payload is already set when client established connection
+     */
+    deserializeTokenPayload(): DurableIteratorTokenPayload;
+    /**
+     * Serialize the hibernation id used for publishing events to the client
+     */
+    serializeHibernationId(id: string): void;
+    /**
+     * Deserialize the hibernation id used for publishing events to the client
+     */
+    deserializeHibernationId(): string | undefined;
+    /**
+     * Close the websocket connection if expired
+     *
+     * @warning this method assumes that the token payload is already set when client established connection
+     */
+    closeIfExpired(): void;
+}
+interface DurableIteratorWebsocket extends WebSocket {
+    /**
+     * Durable Event internal apis
+     */
+    ['~orpc']: DurableIteratorWebsocketInternal;
+}
+/**
+ * Create a Durable Iterator WebSocket from a regular WebSocket
+ *
+ * @info The websocket automatically closes if expired before sending data
+ */
+declare function toDurableIteratorWebsocket(original: WebSocket): DurableIteratorWebsocket;
+
+interface DurableIteratorObjectStateInternal {
+    /**
+     * The original DurableObjectState
+     *
+     * @warning Be careful when using original because you can accidentally modifying internal state.
+     */
+    original: DurableObjectState;
+}
+interface DurableIteratorObjectState<TProps> extends DurableObjectState<TProps> {
+    /**
+     * DurableIteratorObjectState internal apis
+     */
+    '~orpc': DurableIteratorObjectStateInternal;
+    /**
+     * Get all WebSockets connected to this Durable Object
+     * And convert them to DurableIteratorWebsocket to avoid accidentally modifying internal state
+     */
+    'getWebSockets'(...args: Parameters<DurableObjectState['getWebSockets']>): DurableIteratorWebsocket[];
+}
+declare function toDurableIteratorObjectState<TProps>(original: DurableObjectState<TProps>): DurableIteratorObjectState<TProps>;
+
+interface EventResumeStorageOptions extends StandardRPCJsonSerializerOptions {
+    /**
+     * How long (in seconds) to retain events for reconnection replay.
+     *
+     * When a client reconnects, stored events within this window can be replayed
+     * to ensure no data is lost. Outside this window, missed events are dropped.
+     *
+     * @remarks
+     * - Use infinite values to disable
+     * - Note that for performance, expired event cleanup is deferred. This means
+     *  expired events may remain in storage for a short period beyond their
+     *  retention time.
+     *
+     * @default NaN (disabled)
+     */
+    resumeRetentionSeconds?: number;
+    /**
+     * Prefix for the resume storage table schema.
+     * This is used to avoid naming conflicts with other tables in the same Durable Object.
+     *
+     * @default 'orpc:durable-iterator:resume:'
+     */
+    resumeSchemaPrefix?: string;
+}
+interface ResumeEventFilter {
+    /** Only websockets with these tags will receive the event */
+    tags?: readonly string[];
+    /** Only websockets that are in this list will receive the event */
+    targets?: readonly DurableIteratorWebsocket[];
+    /** Websockets that are in this list will not receive the event */
+    exclude?: readonly DurableIteratorWebsocket[];
+}
+declare class EventResumeStorage<T extends object> {
+    private readonly durableState;
+    private readonly serializer;
+    private readonly retentionSeconds;
+    private readonly schemaPrefix;
+    get isEnabled(): boolean;
+    constructor(durableState: DurableObjectState, options?: EventResumeStorageOptions);
+    /**
+     * Store an payload for resume capability.
+     *
+     * @returns The updated meta of the stored payload
+     */
+    store(payload: T, resumeFilter: ResumeEventFilter): T;
+    /**
+     * Get events after lastEventId for a specific websocket
+     */
+    get(websocket: DurableIteratorWebsocket, lastEventId: string): T[];
+    private initSchema;
+    private resetSchema;
+    private lastCleanupTime;
+    private cleanupExpiredEvents;
+    private serializeEventPayload;
+    private deserializeEventPayload;
+    private withEventId;
+}
+
+type DurableIteratorObjectRouterContext = {
+    object: DurableObject<any, any>;
+    resumeStorage: EventResumeStorage<any>;
+    websocket: DurableIteratorWebsocket;
+    options: DurableIteratorObjectHandlerOptions;
+};
+interface PublishEventOptions {
+    /**
+     * Deliver the event only to websockets that have the specified tags.
+     */
+    tags?: readonly string[];
+    /**
+     * Restrict the event to a specific set of websockets.
+     *
+     * Accept a list of websockets or a filter function.
+     *
+     * Use this when security is important — only the listed websockets
+     * will ever receive the event. Newly connected websockets are not
+     * included unless explicitly added here.
+     */
+    targets?: readonly WebSocket[] | ((ws: DurableIteratorWebsocket) => boolean);
+    /**
+     * Exclude certain websockets from receiving the event.
+     *
+     * Accept a list of websockets or a filter function.
+     *
+     * Use this when broadcasting widely but skipping a few clients
+     * (e.g., the sender). Newly connected websockets may still receive
+     * the event if not listed here, so this is less strict than `targets`.
+     */
+    exclude?: readonly WebSocket[] | ((ws: DurableIteratorWebsocket) => boolean);
+}
+interface DurableIteratorObjectHandlerOptions extends RPCHandlerOptions<DurableIteratorObjectRouterContext>, EventResumeStorageOptions {
+    /**
+     * The signing key to use verify the token.
+     */
+    signingKey: string;
+    /**
+     * Called after a client successfully subscribes to the main iterator.
+     * You can start sending events to the client here.
+     *
+     * @param websocket Corresponding WebSocket connection.
+     * @param lastEventId Can be `undefined` if this is the first connection (not a resumed session).
+     */
+    onSubscribed?: (websocket: DurableIteratorWebsocket, lastEventId: string | undefined) => void;
+}
+declare class DurableIteratorObjectHandler<T extends object, TProps> implements DurableIteratorObjectDef<T> {
+    private readonly object;
+    private readonly options;
+    '~eventPayloadType'?: {
+        type: T;
+    };
+    private readonly handler;
+    private readonly resumeStorage;
+    /**
+     * Proxied, ensure you don't accidentally change internal state, and auto close if expired websockets before .send is called
+     */
+    ctx: DurableIteratorObjectState<TProps>;
+    constructor(ctx: DurableObjectState<TProps>, object: DurableObject<any, TProps>, options: DurableIteratorObjectHandlerOptions);
+    /**
+     * Publish an event to a set of clients.
+     */
+    publishEvent(payload: T, options?: PublishEventOptions): void;
+    /**
+     * This method is called when a HTTP request is received for upgrading to a WebSocket connection.
+     * Should mapping with corresponding `fetch` inside durable object
+     */
+    fetch(request: Request): Promise<Response>;
+    /**
+     * This method is called when a WebSocket message is received.
+     * Should mapping with corresponding `webSocketMessage` inside durable object
+     */
+    webSocketMessage(websocket_: WebSocket, message: string | ArrayBuffer): Promise<void>;
+    /**
+     * This method is called when a WebSocket connection is closed.
+     * Should mapping with corresponding `webSocketClose` inside durable object
+     */
+    webSocketClose(ws_: WebSocket, _code: number, _reason: string, _wasClean: boolean): void | Promise<void>;
+}
+
+declare class DurableIteratorObject<T extends object, TEnv = Cloudflare.Env, TProps = {}> extends DurableObject<TEnv, TProps> implements DurableIteratorObject$1<T> {
+    '~orpc': DurableIteratorObjectHandler<T, TProps>;
+    /**
+     * Proxied, ensure you don't accidentally change internal state, and auto close if expired websockets before .send is called
+     */
+    protected ctx: DurableIteratorObjectState<TProps>;
+    constructor(ctx: DurableObjectState<TProps>, env: TEnv, options: DurableIteratorObjectHandlerOptions);
+    /**
+     * Publish an event to clients
+     */
+    publishEvent(payload: T, options?: PublishEventOptions): void;
+    /**
+     * Upgrades websocket connection
+     *
+     * @info You can safety intercept non-upgrade requests
+     * @warning No verification is done here, you should verify the token payload before calling this method.
+     */
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Handle WebSocket messages
+     *
+     * @warning Use `toDurableIteratorWebsocket` to proxy the WebSocket when interacting
+     *          to avoid accidentally modifying internal state, and auto close if expired before .send is called
+     */
+    webSocketMessage(websocket: WebSocket, message: string | ArrayBuffer): Promise<void>;
+    /**
+     * Handle WebSocket close event
+     *
+     * @warning Use `toDurableIteratorWebsocket` to proxy the WebSocket when interacting
+     *          to avoid accidentally modifying internal state, and auto close if expired before .send is called
+     */
+    webSocketClose(websocket: WebSocket, code: number, reason: string, wasClean: boolean): void | Promise<void>;
+}
+
+interface UpgradeDurableIteratorRequestOptions {
+    /**
+     * The signing key used to verify the token
+     */
+    signingKey: string;
+    /**
+     * The durable object namespace
+     */
+    namespace: DurableObjectNamespace<any>;
+    /**
+     * The options to use when getting the durable object stub
+     */
+    namespaceGetOptions?: DurableObjectNamespaceGetDurableObjectOptions;
+    /**
+     * intercept upgrade process
+     */
+    interceptors?: Interceptor<{
+        payload: DurableIteratorTokenPayload;
+    }, Promise<Response>>[];
+}
+/**
+ * Verifies and upgrades a durable iterator request.
+ *
+ * @info Verify token before forwarding to durable object to prevent DDoS attacks
+ */
+declare function upgradeDurableIteratorRequest(request: Request, options: UpgradeDurableIteratorRequestOptions): Promise<Response>;
+
+export { DurableIteratorObject, DurableIteratorObjectHandler, EventResumeStorage, toDurableIteratorObjectState, toDurableIteratorWebsocket, upgradeDurableIteratorRequest };
+export type { DurableIteratorObjectHandlerOptions, DurableIteratorObjectState, DurableIteratorObjectStateInternal, DurableIteratorWebsocket, DurableIteratorWebsocketInternal, EventResumeStorageOptions, PublishEventOptions, ResumeEventFilter, UpgradeDurableIteratorRequestOptions };