@dotdo/postgres 0.1.0

package/src/config/storage.ts

@@ -0,0 +1,204 @@
+/**
+ * Storage Configuration Constants
+ *
+ * Centralized constants for the tiered storage system (HOT/WARM/COLD).
+ * These values control promotion/demotion thresholds, TTLs, page sizes,
+ * and circuit breaker behavior.
+ *
+ * ## Storage Tier Architecture
+ *
+ * ```
+ * +-----------+     +-----------+     +-----------+
+ * |    HOT    | --> |   WARM    | --> |   COLD    |
+ * | (Cache)   |     | (DO/SQLite)|    |   (R2)    |
+ * +-----------+     +-----------+     +-----------+
+ *  - FREE           - Persistent     - Durable
+ *  - Ephemeral      - Sync access    - Async
+ *  - Fastest        - Limited size   - Unlimited
+ * ```
+ *
+ * @module config/storage
+ */
+
+// =============================================================================
+// Page Size Configuration
+// =============================================================================
+
+/**
+ * Default page size for storage operations (8KB).
+ *
+ * Matches the standard PostgreSQL page size and PGLite default.
+ * All tiered storage operations work with pages of this size.
+ */
+export const DEFAULT_PAGE_SIZE = 8192
+
+/**
+ * Default chunk size for DOVFS blob storage (2MB).
+ *
+ * Durable Object storage blobs are chunked at this size.
+ * Balances between:
+ * - Too small: Many chunks, high metadata overhead
+ * - Too large: Slow reads, memory pressure
+ */
+export const DEFAULT_CHUNK_SIZE = 2 * 1024 * 1024
+
+// =============================================================================
+// Promotion Thresholds
+// =============================================================================
+
+/**
+ * Default access count before promoting from COLD to WARM tier (3).
+ *
+ * Prevents unnecessary promotion of rarely accessed data.
+ * Three accesses within the promotion window indicates the data
+ * is likely to be accessed again.
+ */
+export const DEFAULT_COLD_TO_WARM_THRESHOLD = 3
+
+/**
+ * Default access count before promoting from WARM to HOT tier (5).
+ *
+ * Higher than cold-to-warm to ensure only frequently accessed data
+ * gets cached in the ephemeral HOT tier. This prevents cache churn.
+ */
+export const DEFAULT_WARM_TO_HOT_THRESHOLD = 5
+
+/**
+ * Default promotion threshold used by tiered-vfs.ts (3).
+ *
+ * Generic promotion threshold for tier upgrades.
+ */
+export const DEFAULT_PROMOTION_THRESHOLD = 3
+
+/**
+ * Default time window for promotion consideration (60 seconds).
+ *
+ * Accesses must occur within this window to count toward promotion.
+ * Prevents old access patterns from triggering promotion.
+ */
+export const DEFAULT_PROMOTION_WINDOW_MS = 60000
+
+// =============================================================================
+// Tier TTLs (Time to Live)
+// =============================================================================
+
+/**
+ * Default TTL for HOT tier entries (5 minutes).
+ *
+ * Cache entries not accessed within this time are demoted to WARM.
+ * Shorter TTL keeps the cache fresh and prevents stale data.
+ */
+export const DEFAULT_HOT_TTL_MS = 300000
+
+/**
+ * Default TTL for WARM tier entries (1 hour).
+ *
+ * DO storage entries not accessed within this time are demoted to COLD.
+ * Longer TTL because WARM storage is persistent and cheaper than HOT.
+ */
+export const DEFAULT_WARM_TTL_MS = 3600000
+
+// =============================================================================
+// Tier Capacity Limits
+// =============================================================================
+
+/**
+ * Default maximum number of pages in HOT tier (1000).
+ *
+ * Limits cache memory usage in Workers environment.
+ * At 8KB per page, this allows ~8MB of cached data.
+ */
+export const DEFAULT_MAX_HOT_PAGES = 1000
+
+/**
+ * Default prefix for DO storage keys.
+ *
+ * Namespaces page data to avoid collisions with other DO data
+ * like metadata, migration state, etc.
+ */
+export const DEFAULT_DO_PREFIX = 'page:'
+
+// =============================================================================
+// Index Eviction Configuration
+// =============================================================================
+
+/**
+ * Default number of entries to evict when index bounds are exceeded (10).
+ *
+ * Batch eviction amortizes overhead across multiple entries.
+ * Larger batches are more efficient but may cause latency spikes.
+ */
+export const DEFAULT_INDEX_EVICTION_BATCH_SIZE = 10
+
+// =============================================================================
+// Circuit Breaker Configuration
+// =============================================================================
+
+/**
+ * Default number of consecutive failures before opening circuit (3).
+ *
+ * Prevents cascading failures by temporarily disabling failing tiers.
+ * Three failures provides confidence that the issue is persistent.
+ */
+export const DEFAULT_CIRCUIT_BREAKER_FAILURE_THRESHOLD = 3
+
+/**
+ * Default time before attempting to close an open circuit (30 seconds).
+ *
+ * Allows the failing tier to recover before retrying operations.
+ * After this timeout, the circuit enters half-open state.
+ */
+export const DEFAULT_CIRCUIT_BREAKER_RESET_TIMEOUT_MS = 30000
+
+/**
+ * Default failure threshold for tiered-vfs.ts circuit breaker (3).
+ */
+export const DEFAULT_FAILURE_THRESHOLD = 3
+
+/**
+ * Default recovery time before tier is considered healthy again (30 seconds).
+ */
+export const DEFAULT_RECOVERY_TIME_MS = 30000
+
+/**
+ * Maximum number of failures to track in history (100).
+ *
+ * Limits memory usage for failure tracking while providing
+ * enough history for trend analysis.
+ */
+export const DEFAULT_MAX_FAILURE_HISTORY = 100
+
+// =============================================================================
+// R2 Overflow Configuration
+// =============================================================================
+
+/**
+ * Minimum chunk size for R2 multi-part uploads (1MB).
+ *
+ * R2 requires chunks to be at least 5MB for multi-part uploads,
+ * but for overflow operations we use 1MB as the minimum.
+ */
+export const R2_MIN_CHUNK_SIZE = 1 * 1024 * 1024
+
+/**
+ * Maximum chunk size for R2 multi-part uploads (10MB).
+ *
+ * Larger chunks reduce the number of API calls but increase
+ * memory pressure during uploads.
+ */
+export const R2_MAX_CHUNK_SIZE = 10 * 1024 * 1024
+
+/**
+ * Target number of chunks for R2 uploads (6).
+ *
+ * Used to calculate optimal chunk size based on file size.
+ */
+export const R2_TARGET_CHUNK_COUNT = 6
+
+/**
+ * Maximum parallel R2 operations (4).
+ *
+ * Limits concurrent uploads/downloads to prevent overwhelming
+ * the R2 API and memory pressure.
+ */
+export const R2_MAX_PARALLEL_OPERATIONS = 4

package/src/config/streaming.ts

@@ -0,0 +1,147 @@
+/**
+ * Streaming Configuration Constants
+ *
+ * Centralized constants for query streaming and memory-bounded streams.
+ * These values control buffer sizes, water marks for backpressure, and
+ * batch sizes for cursor-based query streaming.
+ *
+ * ## Water Mark System
+ *
+ * The streaming system uses a dual water mark approach to prevent thrashing:
+ *
+ * ```
+ * Memory
+ *   ^
+ *   |  memoryLimit -------- Hard limit (throws OOM)
+ *   |
+ *   |  highWaterMark ------ Pause point
+ *   |       |
+ *   |       v  (paused zone)
+ *   |  lowWaterMark ------- Resume point
+ *   |       |
+ *   |       v  (normal zone)
+ *   +-------------------------> Time
+ * ```
+ *
+ * @module config/streaming
+ */
+
+// =============================================================================
+// Memory Limits for Streaming
+// =============================================================================
+
+/**
+ * Default memory limit for streaming operations (50MB).
+ *
+ * This is the hard limit that triggers StreamingOOMError when exceeded.
+ * Set lower than Worker limit to leave room for other operations.
+ *
+ * Calculation:
+ * - 128MB Worker limit
+ * - ~55MB PGLite baseline
+ * - ~23MB buffer for other operations
+ * = ~50MB available for streaming
+ */
+export const DEFAULT_STREAMING_MEMORY_LIMIT = 50 * 1024 * 1024
+
+// =============================================================================
+// Water Marks for Backpressure
+// =============================================================================
+
+/**
+ * Default high water mark for streaming backpressure (10MB).
+ *
+ * When buffered data exceeds this threshold, the stream pauses the producer
+ * and waits for the consumer to catch up. This prevents unbounded memory growth.
+ *
+ * Set at 20% of memory limit to provide early warning without being too aggressive.
+ */
+export const DEFAULT_HIGH_WATER_MARK = 10 * 1024 * 1024
+
+/**
+ * Default low water mark for streaming resume (5MB).
+ *
+ * When buffered data drops below this threshold after being paused,
+ * the stream resumes producing. The gap between high and low marks
+ * prevents rapid pause/resume oscillation (thrashing).
+ *
+ * Set at 10% of memory limit (50% of high water mark).
+ */
+export const DEFAULT_LOW_WATER_MARK = 5 * 1024 * 1024
+
+// =============================================================================
+// Query Streaming Configuration
+// =============================================================================
+
+/**
+ * Default number of rows per cursor fetch batch (100).
+ *
+ * Balance between:
+ * - Too small: High overhead from many FETCH calls
+ * - Too large: Memory spikes, poor backpressure responsiveness
+ *
+ * 100 rows is a good default for typical row sizes (1-10KB).
+ * Adjust based on actual row sizes in your workload.
+ */
+export const DEFAULT_BATCH_SIZE = 100
+
+/**
+ * Default cursor name prefix for streaming queries.
+ *
+ * Combined with a unique suffix (timestamp or counter) to create
+ * cursor names like 'pglite_cursor_1234567890'.
+ */
+export const DEFAULT_CURSOR_PREFIX = 'pglite_cursor'
+
+// =============================================================================
+// Row Size Estimation
+// =============================================================================
+
+/**
+ * Fallback row size estimate when serialization fails (1KB).
+ *
+ * Used by estimateRowsMemory() when JSON.stringify() fails due to
+ * circular references or other issues.
+ */
+export const FALLBACK_ROW_SIZE_BYTES = 1024
+
+// =============================================================================
+// Buffer Pool Configuration (from buffer-pool.ts)
+// =============================================================================
+
+/**
+ * Base memory overhead per JavaScript object (64 bytes).
+ *
+ * Includes object header, hidden class pointer, and other V8 internals.
+ * Used for accurate memory tracking in buffer pools.
+ */
+export const OBJECT_BASE_OVERHEAD = 64
+
+/**
+ * Bytes per character in JavaScript strings (2 bytes).
+ *
+ * JavaScript uses UTF-16 encoding, so each character takes 2 bytes.
+ * Used for string memory estimation.
+ */
+export const BYTES_PER_CHAR = 2
+
+/**
+ * String header overhead in bytes (24 bytes).
+ *
+ * V8 string objects have a header with length, hash, and encoding info.
+ */
+export const STRING_HEADER_OVERHEAD = 24
+
+/**
+ * Base overhead for JavaScript arrays (24 bytes).
+ *
+ * Includes array length and pointer to backing store.
+ */
+export const ARRAY_BASE_OVERHEAD = 24
+
+/**
+ * Per-element overhead in JavaScript arrays (8 bytes).
+ *
+ * Each array element is a tagged pointer (8 bytes on 64-bit).
+ */
+export const ARRAY_ELEMENT_OVERHEAD = 8

package/src/config/timeouts.ts

@@ -0,0 +1,221 @@
+/**
+ * Timeout Configuration Constants
+ *
+ * Centralized timeout values used throughout the postgres package.
+ * These constants define standard wait times for various operations
+ * including monitoring, recovery, connection, and shutdown.
+ *
+ * ## Timeout Categories
+ *
+ * - **Check Intervals**: How often to poll for state changes
+ * - **Grace Periods**: Time allowed for operations to complete
+ * - **Connection Timeouts**: Maximum wait for network operations
+ * - **Recovery Timeouts**: Time before retrying after failures
+ *
+ * @module config/timeouts
+ */
+
+// =============================================================================
+// Memory Pressure Monitoring Intervals
+// =============================================================================
+
+/**
+ * Default interval for memory pressure checks (5 seconds).
+ *
+ * How often the MemoryPressureManager samples heap usage and
+ * evaluates pressure thresholds. Lower values provide faster
+ * response but use more CPU.
+ */
+export const DEFAULT_CHECK_INTERVAL_MS = 5000
+
+/**
+ * Minimum interval between GC hint triggers (5 seconds).
+ *
+ * Prevents GC thrashing by rate-limiting garbage collection hints.
+ * Allows the runtime to stabilize between collections.
+ */
+export const DEFAULT_GC_HINT_MIN_INTERVAL_MS = 5000
+
+/**
+ * Default interval for memory pressure recovery hysteresis (2 seconds).
+ *
+ * Time to wait at normal pressure before considering recovery complete.
+ * Prevents oscillation when pressure hovers near thresholds.
+ */
+export const DEFAULT_RECOVERY_HYSTERESIS_MS = 2000
+
+/**
+ * Default interval between recovery steps (1 second).
+ *
+ * When gradually re-enabling features after recovery, this controls
+ * how long to wait between enabling each feature.
+ */
+export const DEFAULT_RECOVERY_STEP_INTERVAL_MS = 1000
+
+/**
+ * Default time at elevated pressure before alert (5 seconds).
+ *
+ * Triggers sustained pressure callback when pressure level remains
+ * elevated for this duration. Helps distinguish transient spikes
+ * from persistent memory issues.
+ */
+export const DEFAULT_SUSTAINED_PRESSURE_THRESHOLD_MS = 5000
+
+// =============================================================================
+// Query Management Timeouts
+// =============================================================================
+
+/**
+ * Default timeout for paused queries (30 seconds).
+ *
+ * Maximum time a query can be paused due to memory pressure before
+ * being cancelled with a timeout error. Prevents indefinite waiting.
+ */
+export const DEFAULT_QUERY_PAUSE_TIMEOUT_MS = 30000
+
+/**
+ * Default request timeout for tenant router (30 seconds).
+ *
+ * Maximum time to wait for a routed request to complete before
+ * returning a timeout error to the client.
+ */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30000
+
+// =============================================================================
+// Shutdown Manager Timeouts
+// =============================================================================
+
+/**
+ * Default grace period before forced shutdown (30 seconds).
+ *
+ * Allows in-flight queries to complete before termination.
+ * After this period, any remaining queries are forcibly cancelled.
+ */
+export const DEFAULT_GRACE_PERIOD_MS = 30000
+
+/**
+ * Default interval for checking if queries have drained (100ms).
+ *
+ * Frequent checks ensure responsive shutdown when queries complete.
+ * Lower values provide faster shutdown at the cost of more CPU.
+ */
+export const DEFAULT_DRAIN_CHECK_INTERVAL_MS = 100
+
+/**
+ * Default timeout for PGlite close operation (5 seconds).
+ *
+ * Prevents shutdown from hanging if PGlite fails to close cleanly.
+ * After this timeout, shutdown proceeds anyway.
+ */
+export const DEFAULT_CLOSE_TIMEOUT_MS = 5000
+
+// =============================================================================
+// WebSocket/SSE Transport Timeouts
+// =============================================================================
+
+/**
+ * Default WebSocket connect timeout (5 seconds).
+ *
+ * Maximum time to wait for WebSocket handshake to complete.
+ */
+export const DEFAULT_WS_CONNECT_TIMEOUT_MS = 5000
+
+/**
+ * Default WebSocket ping interval (30 seconds).
+ *
+ * How often to send ping frames to keep the connection alive
+ * and detect stale connections.
+ */
+export const DEFAULT_WS_PING_INTERVAL_MS = 30000
+
+/**
+ * Default SSE connect timeout (10 seconds).
+ *
+ * Maximum time to wait for SSE connection to establish.
+ * Longer than WebSocket because SSE is often used over HTTP/1.1.
+ */
+export const DEFAULT_SSE_CONNECT_TIMEOUT_MS = 10000
+
+/**
+ * Default SSE retry delay (3 seconds).
+ *
+ * Time to wait before attempting to reconnect after SSE connection drops.
+ */
+export const DEFAULT_SSE_RETRY_MS = 3000
+
+/**
+ * Default SSE heartbeat interval (30 seconds).
+ *
+ * How often to send comment heartbeats to keep the connection alive.
+ */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000
+
+// =============================================================================
+// Circuit Breaker Timeouts
+// =============================================================================
+
+/**
+ * Default circuit breaker reset timeout (30 seconds).
+ *
+ * Time before an open circuit transitions to half-open state.
+ * Already exported from storage.ts as DEFAULT_CIRCUIT_BREAKER_RESET_TIMEOUT_MS.
+ * Re-exported here for convenience in timeout-focused imports.
+ */
+export { DEFAULT_CIRCUIT_BREAKER_RESET_TIMEOUT_MS } from './storage'
+
+// =============================================================================
+// Migration Timeouts
+// =============================================================================
+
+/**
+ * Default migration lock timeout (5 seconds).
+ *
+ * Maximum time to wait for migration advisory lock.
+ * Prevents deadlocks when multiple instances try to migrate.
+ */
+export const DEFAULT_MIGRATION_LOCK_TIMEOUT_MS = 5000
+
+/**
+ * Default migration execution timeout (30 seconds).
+ *
+ * Maximum time for a single migration to complete.
+ * Long-running migrations should be broken into smaller steps.
+ */
+export const DEFAULT_MIGRATION_TIMEOUT_MS = 30000
+
+// =============================================================================
+// Rate Limiting Timeouts
+// =============================================================================
+
+/**
+ * Default rate limit window (60 seconds).
+ *
+ * Duration over which rate limit counters are tracked.
+ */
+export const DEFAULT_RATE_LIMIT_WINDOW_MS = 60000
+
+/**
+ * Default rate limit cleanup interval (5 minutes).
+ *
+ * How often to purge expired rate limit entries.
+ */
+export const DEFAULT_RATE_LIMIT_CLEANUP_INTERVAL_MS = 300000
+
+// =============================================================================
+// Listener Limits (Not timeouts, but related capacity limits)
+// =============================================================================
+
+/**
+ * Default maximum number of event listeners.
+ *
+ * Prevents memory leaks from uncleaned listener registrations.
+ * Applies to shutdown events, memory pressure events, etc.
+ */
+export const DEFAULT_MAX_LISTENERS = 100
+
+/**
+ * Threshold percentage for listener count warning (80%).
+ *
+ * Warns when listener count reaches this percentage of max.
+ */
+export const LISTENER_WARNING_THRESHOLD = 0.8