@dotdo/do 0.1.0

package/dist/do/hibernation.d.ts

@@ -0,0 +1,385 @@
+/**
+ * Hibernation Support for Digital Objects
+ *
+ * Implements the Cloudflare Agents SDK hibernation pattern for efficient
+ * resource usage. DOs can hibernate when idle, reducing costs by ~95%.
+ *
+ * Features:
+ * - Automatic idle detection and hibernation
+ * - WebSocket connection preservation during hibernation
+ * - Alarm-based wake-up for scheduled tasks
+ * - State persistence across hibernation cycles
+ *
+ * @example Basic hibernation
+ * ```typescript
+ * const hibernation = new HibernationManager(ctx, {
+ *   idleTimeout: 10_000, // Hibernate after 10s idle
+ * })
+ *
+ * // Touch on activity to reset idle timer
+ * hibernation.touch()
+ *
+ * // Check if hibernating
+ * if (hibernation.isHibernating()) {
+ *   // Handle wake-up
+ * }
+ * ```
+ *
+ * @example WebSocket with hibernation
+ * ```typescript
+ * // Accept WebSocket with hibernation support
+ * const response = await hibernation.acceptWebSocket(request)
+ *
+ * // WebSocket survives hibernation and reconnects automatically
+ * ```
+ *
+ * @module do/hibernation
+ */
+import type { DurableObjectState } from '@cloudflare/workers-types';
+/**
+ * Configuration for hibernation behavior
+ *
+ * @interface HibernationConfig
+ */
+export interface HibernationConfig {
+    /**
+     * Time in milliseconds before hibernating after last activity
+     * @default 10000 (10 seconds)
+     */
+    idleTimeout: number;
+    /**
+     * Maximum time in milliseconds a DO can stay hibernated
+     * After this time, the DO will be woken to check for work
+     * @default 86400000 (24 hours)
+     */
+    maxHibernationDuration: number;
+    /**
+     * Whether to preserve WebSocket connections during hibernation
+     * When true, WebSockets will hibernate and wake automatically
+     * @default true
+     */
+    preserveWebSockets: boolean;
+    /**
+     * Hook called just before hibernation
+     * Use this to clean up resources or persist state
+     */
+    onHibernate?: () => Promise<void>;
+    /**
+     * Hook called just after waking from hibernation
+     * Use this to restore state or reinitialize connections
+     */
+    onWake?: () => Promise<void>;
+}
+/**
+ * State of a hibernatable WebSocket connection
+ *
+ * @interface WebSocketState
+ */
+export interface WebSocketState {
+    /** Unique connection ID */
+    id: string;
+    /** Connection status */
+    status: 'connecting' | 'open' | 'hibernating' | 'closing' | 'closed';
+    /** Timestamp when the connection was established */
+    connectedAt: number;
+    /** Timestamp when hibernation started (if hibernating) */
+    hibernatedAt?: number;
+    /** Timestamp of last message sent or received */
+    lastMessageAt: number;
+    /** Custom data attached to this connection */
+    data?: Record<string, unknown>;
+    /** Subscriptions this connection has */
+    subscriptions: string[];
+}
+/**
+ * Alarm configuration
+ *
+ * @interface AlarmConfig
+ */
+export interface AlarmConfig {
+    /** Alarm type for handling different alarm purposes */
+    type: 'hibernation' | 'scheduled' | 'retry' | 'custom';
+    /** Scheduled time for the alarm */
+    scheduledTime: number;
+    /** Custom payload for the alarm */
+    payload?: unknown;
+}
+/**
+ * Hibernation manager for Digital Objects
+ *
+ * Manages the sleep/wake lifecycle of a DO, including:
+ * - Idle detection and automatic hibernation
+ * - WebSocket hibernation
+ * - Alarm scheduling for wake-up
+ *
+ * @class HibernationManager
+ *
+ * @example
+ * ```typescript
+ * class MyDO implements DurableObject {
+ *   private hibernation: HibernationManager
+ *
+ *   constructor(ctx: DurableObjectState) {
+ *     this.hibernation = new HibernationManager(ctx, {
+ *       idleTimeout: 30_000,
+ *       onHibernate: () => this.cleanup(),
+ *       onWake: () => this.restore()
+ *     })
+ *   }
+ *
+ *   async fetch(request: Request) {
+ *     this.hibernation.touch()
+ *     // Handle request...
+ *   }
+ * }
+ * ```
+ */
+export declare class HibernationManager {
+    private ctx;
+    /**
+     * Current hibernation state
+     */
+    private state;
+    /**
+     * Timestamp of last activity
+     */
+    private lastActivity;
+    /**
+     * Map of active WebSocket connections by ID
+     */
+    private webSockets;
+    /**
+     * WebSocket metadata storage
+     */
+    private webSocketStates;
+    /**
+     * Counter for generating unique WebSocket IDs
+     */
+    private wsIdCounter;
+    /**
+     * Configuration with defaults applied
+     */
+    private config;
+    /**
+     * Timer for idle detection (only in non-hibernating mode)
+     */
+    private idleTimer?;
+    /**
+     * Create a new HibernationManager
+     *
+     * @param ctx - Durable Object state from Cloudflare runtime
+     * @param config - Hibernation configuration options
+     */
+    constructor(ctx: DurableObjectState, config?: Partial<HibernationConfig>);
+    /**
+     * Record activity to reset the idle timer
+     *
+     * Call this method whenever the DO processes a request,
+     * message, or any other activity.
+     *
+     * @example
+     * ```typescript
+     * async fetch(request: Request) {
+     *   this.hibernation.touch()
+     *   // Process request...
+     * }
+     * ```
+     */
+    touch(): void;
+    /**
+     * Check if the DO is currently hibernating
+     *
+     * @returns True if hibernating, false if active
+     */
+    isHibernating(): boolean;
+    /**
+     * Check if the DO is idle (no recent activity)
+     *
+     * @returns True if idle for longer than idleTimeout
+     */
+    isIdle(): boolean;
+    /**
+     * Get the time since last activity in milliseconds
+     *
+     * @returns Milliseconds since last activity
+     */
+    getIdleTime(): number;
+    /**
+     * Get the current hibernation state
+     *
+     * @returns Current state ('active' or 'hibernating')
+     */
+    getState(): 'active' | 'hibernating';
+    /**
+     * Get statistics about WebSocket connections
+     *
+     * @returns WebSocket connection statistics
+     */
+    getWebSocketStats(): {
+        total: number;
+        active: number;
+        hibernating: number;
+    };
+    /**
+     * Accept a WebSocket connection with hibernation support
+     *
+     * This method upgrades the HTTP request to a WebSocket connection
+     * that supports hibernation. The connection will survive hibernation
+     * and automatically reconnect when the DO wakes.
+     *
+     * @param request - The HTTP upgrade request
+     * @param data - Optional custom data to attach to the connection
+     * @returns HTTP response with WebSocket upgrade
+     *
+     * @example
+     * ```typescript
+     * async handleWebSocket(request: Request) {
+     *   const response = await this.hibernation.acceptWebSocket(request, {
+     *     userId: '123'
+     *   })
+     *   return response
+     * }
+     * ```
+     */
+    acceptWebSocket(request: Request, data?: Record<string, unknown>): Promise<Response>;
+    /**
+     * Send a message to a specific WebSocket connection
+     *
+     * @param wsId - The WebSocket connection ID
+     * @param message - The message to send
+     * @returns True if the message was sent, false if connection not found
+     */
+    sendToWebSocket(wsId: string, message: string | ArrayBuffer): boolean;
+    /**
+     * Broadcast a message to all connected WebSockets
+     *
+     * @param message - The message to broadcast
+     * @param filter - Optional filter function to select recipients
+     * @returns Number of WebSockets that received the message
+     */
+    broadcast(message: string | ArrayBuffer, filter?: (state: WebSocketState) => boolean): number;
+    /**
+     * Get the state of a WebSocket connection
+     *
+     * @param wsId - The WebSocket connection ID
+     * @returns WebSocket state or undefined if not found
+     */
+    getWebSocketState(wsId: string): WebSocketState | undefined;
+    /**
+     * Get all WebSocket states
+     *
+     * @returns Iterator of all WebSocket states
+     */
+    getAllWebSocketStates(): IterableIterator<WebSocketState>;
+    /**
+     * Update custom data for a WebSocket connection
+     *
+     * @param wsId - The WebSocket connection ID
+     * @param data - The data to merge with existing data
+     */
+    updateWebSocketData(wsId: string, data: Record<string, unknown>): void;
+    /**
+     * Subscribe a WebSocket to a topic
+     *
+     * @param wsId - The WebSocket connection ID
+     * @param topic - The topic to subscribe to
+     */
+    subscribe(wsId: string, topic: string): void;
+    /**
+     * Unsubscribe a WebSocket from a topic
+     *
+     * @param wsId - The WebSocket connection ID
+     * @param topic - The topic to unsubscribe from
+     */
+    unsubscribe(wsId: string, topic: string): void;
+    /**
+     * Publish a message to all subscribers of a topic
+     *
+     * @param topic - The topic to publish to
+     * @param message - The message to publish
+     * @returns Number of subscribers that received the message
+     */
+    publish(topic: string, message: string | ArrayBuffer): number;
+    /**
+     * Handle WebSocket close event
+     *
+     * Called when a WebSocket connection is closed.
+     * Cleans up state and removes the connection.
+     *
+     * @param ws - The WebSocket that was closed
+     */
+    handleWebSocketClose(ws: WebSocket): void;
+    /**
+     * Handle alarm callback
+     *
+     * Called when an alarm fires. This may be for hibernation,
+     * scheduled tasks, or other purposes.
+     *
+     * @returns Promise that resolves when alarm is handled
+     */
+    handleAlarm(): Promise<void>;
+    /**
+     * Schedule an alarm at a specific time
+     *
+     * @param time - The time to trigger the alarm (Date or milliseconds)
+     * @param config - Optional alarm configuration
+     */
+    scheduleAlarm(time: Date | number, config?: Partial<AlarmConfig>): Promise<void>;
+    /**
+     * Cancel all scheduled alarms
+     */
+    cancelAlarms(): Promise<void>;
+    /**
+     * Force immediate hibernation
+     *
+     * @returns Promise that resolves when hibernation is complete
+     */
+    forceHibernate(): Promise<void>;
+    /**
+     * Force immediate wake from hibernation
+     *
+     * @returns Promise that resolves when wake is complete
+     */
+    forceWake(): Promise<void>;
+    /**
+     * Enter hibernation state
+     *
+     * @internal
+     */
+    private hibernate;
+    /**
+     * Wake from hibernation state
+     *
+     * @internal
+     */
+    private wake;
+    /**
+     * Schedule idle check via alarm
+     *
+     * @internal
+     */
+    private scheduleIdleCheck;
+    /**
+     * Generate a unique WebSocket ID
+     *
+     * @internal
+     */
+    private generateWebSocketId;
+}
+/**
+ * Create a HibernationManager instance
+ *
+ * @param ctx - Durable Object state
+ * @param config - Configuration options
+ * @returns HibernationManager instance
+ *
+ * @example
+ * ```typescript
+ * const hibernation = createHibernationManager(ctx, {
+ *   idleTimeout: 30_000
+ * })
+ * ```
+ */
+export declare function createHibernationManager(ctx: DurableObjectState, config?: Partial<HibernationConfig>): HibernationManager;
+export default HibernationManager;
+//# sourceMappingURL=hibernation.d.ts.map

package/dist/do/hibernation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hibernation.d.ts","sourceRoot":"","sources":["../../do/hibernation.ts"],"names":[],"mappings":"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"}