bunqueue-client 0.1.8 → 0.2.0

package/dist/types/src/domain/types/stall.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Stall Detection Types
+ * Configuration and handling for stalled jobs
+ */
+import type { Job } from "./job.js";
+/** Stall detection configuration per queue */
+export interface StallConfig {
+    /** Enable stall detection (default: true) */
+    enabled: boolean;
+    /** Stall timeout in ms - job is stalled if no heartbeat (default: 30s) */
+    stallInterval: number;
+    /** Max stalls before moving to DLQ (default: 3) */
+    maxStalls: number;
+    /** Grace period after job start before stall detection (default: 5s) */
+    gracePeriod: number;
+}
+/** Default stall configuration */
+export declare const DEFAULT_STALL_CONFIG: StallConfig;
+/** Stall check result */
+export interface StallCheckResult {
+    /** Is the job stalled? */
+    isStalled: boolean;
+    /** Time since last heartbeat in ms */
+    stalledFor: number;
+    /** Should move to DLQ? (exceeded max stalls) */
+    shouldMoveToDlq: boolean;
+    /** Stall count after this check */
+    newStallCount: number;
+}
+/** Check if a job is stalled */
+export declare function checkStall(job: Job, config?: StallConfig, now?: number): StallCheckResult;
+/** Stalled job action */
+export declare const enum StallAction {
+    /** Retry the job */
+    Retry = "retry",
+    /** Move to DLQ */
+    MoveToDlq = "move_to_dlq",
+    /** Keep active (still within grace) */
+    Keep = "keep"
+}
+/** Determine action for stalled job */
+export declare function getStallAction(job: Job, config?: StallConfig, now?: number): StallAction;
+/** Update job heartbeat */
+export declare function updateHeartbeat(job: Job, now?: number): void;
+/** Reset stall count (after successful retry) */
+export declare function resetStallCount(job: Job): void;
+/** Increment stall count */
+export declare function incrementStallCount(job: Job): number;

package/dist/types/src/domain/types/webhook.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Webhook domain types
+ */
+/** Webhook ID type */
+export type WebhookId = string;
+/**
+ * Canonical list of webhook events the server actually triggers — single
+ * source of truth for CLI/TCP/HTTP/MCP validation. job.pushed/started/
+ * completed/failed flow through eventsManager.mapEventToWebhook; job.progress
+ * is triggered directly by updateProgress (jobManagement).
+ */
+export declare const WEBHOOK_EVENTS: readonly ["job.pushed", "job.started", "job.completed", "job.failed", "job.progress"];
+/**
+ * Webhook event types. Includes 'job.stalled' for backward compatibility with
+ * stored webhooks, but it is never emitted and not accepted on new ones.
+ */
+export type WebhookEvent = (typeof WEBHOOK_EVENTS)[number] | 'job.stalled';
+/** Webhook configuration */
+export interface Webhook {
+    id: WebhookId;
+    url: string;
+    events: WebhookEvent[];
+    queue: string | null;
+    secret: string | null;
+    createdAt: number;
+    lastTriggered: number | null;
+    successCount: number;
+    failureCount: number;
+    enabled: boolean;
+}
+/** Create a new webhook */
+export declare function createWebhook(url: string, events: string[], queue?: string, secret?: string): Webhook;
+/** Webhook payload */
+export interface WebhookPayload {
+    event: WebhookEvent;
+    timestamp: number;
+    jobId: string;
+    queue: string;
+    data?: unknown;
+    error?: string;
+    progress?: number;
+}

package/dist/types/src/domain/types/worker.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Worker domain types
+ */
+/** Worker ID type */
+export type WorkerId = string;
+/** Worker status */
+export interface Worker {
+    id: WorkerId;
+    name: string;
+    queues: string[];
+    concurrency: number;
+    hostname: string;
+    pid: number;
+    registeredAt: number;
+    lastSeen: number;
+    activeJobs: number;
+    processedJobs: number;
+    failedJobs: number;
+    currentJob: string | null;
+    /** TCP client ID that registered this worker (for cleanup on disconnect) */
+    clientId: string | null;
+}
+/** Options for creating a worker */
+export interface CreateWorkerOptions {
+    workerId?: string;
+    hostname?: string;
+    pid?: number;
+    startedAt?: number;
+    clientId?: string;
+}
+/** Create a new worker */
+export declare function createWorker(name: string, queues?: string[], concurrency?: number, opts?: CreateWorkerOptions): Worker;
+/** Job log entry */
+export interface JobLogEntry {
+    timestamp: number;
+    level: 'info' | 'warn' | 'error';
+    message: string;
+}
+/** Create log entry */
+export declare function createLogEntry(message: string, level?: 'info' | 'warn' | 'error'): JobLogEntry;

package/dist/types/src/infrastructure/backup/backupTelemetry.d.ts

@@ -0,0 +1,30 @@
+import type { BackupResult } from "./s3BackupConfig.js";
+/** Bounded, label-free backup metrics exposed to Prometheus. */
+export interface BackupMetrics {
+    enabled: boolean;
+    schedulerRunning: boolean;
+    inProgress: boolean;
+    intervalSeconds: number;
+    retention: number;
+    attemptsTotal: number;
+    successesTotal: number;
+    failuresTotal: number;
+    overlapRejectionsTotal: number;
+    consecutiveFailures: number;
+    lastSuccessTimestampSeconds: number;
+    lastFailureTimestampSeconds: number;
+    lastDurationSeconds: number;
+    lastSizeBytes: number;
+}
+export declare const EMPTY_BACKUP_METRICS: BackupMetrics;
+/** State machine for backup attempts; all transitions preserve counter conservation. */
+export declare class BackupTelemetry {
+    private readonly metrics;
+    constructor(enabled: boolean, intervalMs: number, retention: number);
+    setSchedulerRunning(running: boolean): void;
+    tryStart(): boolean;
+    succeed(result: BackupResult, durationMs: number, nowMs?: number): void;
+    fail(durationMs: number, nowMs?: number): void;
+    snapshot(): BackupMetrics;
+    private finish;
+}

package/dist/types/src/infrastructure/backup/s3BackupConfig.d.ts

@@ -0,0 +1,80 @@
+/**
+ * S3 Backup Configuration
+ * Types and configuration factory
+ */
+/** S3 Backup configuration */
+export interface S3BackupConfig {
+    /** Enable S3 backup */
+    enabled: boolean;
+    /** S3 access key ID */
+    accessKeyId: string;
+    /** S3 secret access key */
+    secretAccessKey: string;
+    /** Temporary credential session token */
+    sessionToken?: string;
+    /** S3 bucket name */
+    bucket: string;
+    /** S3 endpoint (optional, for non-AWS S3-compatible services) */
+    endpoint?: string;
+    /** Use bucket-name-in-host S3 requests */
+    virtualHostedStyle?: boolean;
+    /** S3 region (optional, default: us-east-1) */
+    region?: string;
+    /** Backup interval in milliseconds (default: 6 hours) */
+    intervalMs: number;
+    /** Number of backups to retain (default: 7) */
+    retention: number;
+    /** Prefix for backup files (default: 'backups/') */
+    prefix: string;
+    /** Path to the SQLite database file */
+    databasePath: string;
+    /** Timeout for S3 operations in milliseconds (default: 30000) */
+    timeoutMs?: number;
+}
+/** Backup result */
+export interface BackupResult {
+    success: boolean;
+    key?: string;
+    /** Uncompressed SQLite database size in bytes */
+    size?: number;
+    /** Uploaded gzip object size in bytes */
+    compressedSize?: number;
+    duration?: number;
+    error?: string;
+}
+/** Backup metadata stored in S3 */
+export interface BackupMetadata {
+    timestamp: string;
+    version: string;
+    /** Original uncompressed size in bytes */
+    size: number;
+    /** Compressed size in bytes (if compressed) */
+    compressedSize?: number;
+    checksum: string;
+    /** Whether the backup is gzip compressed */
+    compressed?: boolean;
+}
+/** Backup list item */
+export interface BackupItem {
+    key: string;
+    size: number;
+    lastModified: Date;
+}
+/** Default configuration values */
+export declare const DEFAULTS: {
+    readonly intervalMs: number;
+    readonly retention: 7;
+    readonly prefix: "backups/";
+    readonly region: "us-east-1";
+};
+/**
+ * Create configuration from environment variables
+ */
+export declare function configFromEnv(databasePath: string): S3BackupConfig;
+/**
+ * Validate configuration
+ */
+export declare function validateConfig(config: S3BackupConfig): {
+    valid: boolean;
+    errors: string[];
+};

package/dist/types/src/infrastructure/cloud/types/config.d.ts

@@ -0,0 +1,18 @@
+export interface CloudConfig {
+    readonly url: string;
+    readonly apiKey: string;
+    readonly instanceId: string;
+    readonly signingSecret: string | null;
+    readonly instanceName: string;
+    readonly intervalMs: number;
+    readonly includeJobData: boolean;
+    readonly redactFields: string[];
+    readonly eventFilter: string[];
+    readonly bufferSize: number;
+    readonly circuitBreakerThreshold: number;
+    readonly circuitBreakerResetMs: number;
+    readonly useWebSocket: boolean;
+    readonly useHttp: boolean;
+    readonly dataPath: string | null;
+    readonly remoteCommands: boolean;
+}

package/dist/types/src/infrastructure/cloud/types/event.d.ts

@@ -0,0 +1,14 @@
+export interface CloudEvent {
+    instanceId: string;
+    timestamp: number;
+    jobEvent?: {
+        eventType: string;
+        queue: string;
+        jobId: string;
+        error?: string;
+        progress?: number;
+        data?: unknown;
+        prev?: string;
+        delay?: number;
+    };
+}

package/dist/types/src/infrastructure/cloud/types/snapshot.d.ts

@@ -0,0 +1,52 @@
+import type { CloudEvent } from "./event.js";
+import type { SnapshotCollections, SnapshotConnections, SnapshotCron, SnapshotLatency, SnapshotMemory, SnapshotQueue, SnapshotRuntime, SnapshotSqliteStats, SnapshotStats, SnapshotStorage, SnapshotTaskErrors, SnapshotThroughput, SnapshotWorkers } from "./snapshotCore.js";
+import type { SnapshotActiveLock, SnapshotDlqEntry, SnapshotJob, SnapshotJobLogEntry, SnapshotStallDetail, SnapshotWorkerDetail } from "./snapshotJobs.js";
+import type { SnapshotDurationHistogram, SnapshotMcpOperation, SnapshotMcpSummary, SnapshotQueueBacklogVelocity, SnapshotQueueConfig, SnapshotQueueExtended, SnapshotQueueRetryRate, SnapshotQueueThroughput, SnapshotQueueWaitTime, SnapshotS3Backup, SnapshotTopError, SnapshotWebhook, SnapshotWorkerUtilization } from "./snapshotTelemetry.js";
+export interface CloudSnapshot {
+    instanceId: string;
+    instanceName: string;
+    version: string;
+    hostname: string;
+    pid: number;
+    startedAt: number;
+    timestamp: number;
+    sequenceId: number;
+    shutdown?: boolean;
+    stats: SnapshotStats;
+    throughput: SnapshotThroughput;
+    latency: SnapshotLatency;
+    memory: SnapshotMemory;
+    collections: SnapshotCollections;
+    queues: SnapshotQueue[];
+    workers: SnapshotWorkers;
+    crons: SnapshotCron[];
+    storage: SnapshotStorage;
+    taskErrors: SnapshotTaskErrors;
+    recentJobs: SnapshotJob[];
+    dlqEntries: SnapshotDlqEntry[];
+    workerDetails: SnapshotWorkerDetail[];
+    queueConfigs: Record<string, SnapshotQueueConfig>;
+    connections: SnapshotConnections;
+    webhooks: SnapshotWebhook[];
+    topErrors: SnapshotTopError[];
+    queueThroughput: Record<string, SnapshotQueueThroughput>;
+    durationHistogram: SnapshotDurationHistogram;
+    workerUtilization: SnapshotWorkerUtilization[];
+    sqliteStats: SnapshotSqliteStats | null;
+    runtime: SnapshotRuntime;
+    queuePriorityDistribution: Record<string, Record<number, number>>;
+    queueWaitTime: Record<string, SnapshotQueueWaitTime>;
+    queueRetryRate: Record<string, SnapshotQueueRetryRate>;
+    queueBacklogVelocity: Record<string, SnapshotQueueBacklogVelocity>;
+    stallDetails: SnapshotStallDetail[];
+    events?: CloudEvent[];
+    mcpOperations?: SnapshotMcpOperation[];
+    mcpSummary?: SnapshotMcpSummary;
+    s3Backup: SnapshotS3Backup | null;
+    jobResults: Record<string, unknown>;
+    jobLogEntries: Record<string, SnapshotJobLogEntry[]>;
+    activeLocks: SnapshotActiveLock[];
+    queueExtended: Record<string, SnapshotQueueExtended>;
+    eventSubscribers: number;
+    pendingDepChecks: number;
+}

package/dist/types/src/infrastructure/cloud/types/snapshotCore.d.ts

@@ -0,0 +1,125 @@
+export interface SnapshotStats {
+    waiting: number;
+    prioritized: number;
+    delayed: number;
+    active: number;
+    dlq: number;
+    completed: number;
+    'waiting-children': number;
+    totalPushed: string;
+    totalPulled: string;
+    totalCompleted: string;
+    totalFailed: string;
+    stalled: number;
+    paused: number;
+    uptime: number;
+    cronJobs: number;
+    cronPending: number;
+}
+export interface SnapshotThroughput {
+    pushPerSec: number;
+    pullPerSec: number;
+    completePerSec: number;
+    failPerSec: number;
+}
+export interface SnapshotLatency {
+    averages: {
+        pushMs: number;
+        pullMs: number;
+        ackMs: number;
+    };
+    percentiles: {
+        push: {
+            p50: number;
+            p95: number;
+            p99: number;
+        };
+        pull: {
+            p50: number;
+            p95: number;
+            p99: number;
+        };
+        ack: {
+            p50: number;
+            p95: number;
+            p99: number;
+        };
+    };
+}
+export interface SnapshotMemory {
+    heapUsed: number;
+    heapTotal: number;
+    rss: number;
+    external: number;
+}
+export interface SnapshotCollections {
+    jobIndex: number;
+    completedJobs: number;
+    jobResults: number;
+    jobLogs: number;
+    customIdMap: number;
+    jobLocks: number;
+    processingTotal: number;
+    queuedTotal: number;
+    temporalIndexTotal: number;
+    delayedHeapTotal: number;
+}
+export interface SnapshotQueue {
+    name: string;
+    waiting: number;
+    prioritized: number;
+    delayed: number;
+    active: number;
+    completed: number;
+    failed: number;
+    'waiting-children': number;
+    paused: boolean;
+    totalCompleted: number;
+    totalFailed: number;
+}
+export interface SnapshotWorkers {
+    total: number;
+    active: number;
+    totalProcessed: number;
+    totalFailed: number;
+    activeJobs: number;
+}
+export interface SnapshotCron {
+    name: string;
+    queue: string;
+    schedule: string | null;
+    repeatEvery: number | null;
+    nextRun: number;
+    executions: number;
+    maxLimit: number | null;
+    lastRun: number | null;
+    priority: number;
+    timezone: string | null;
+    data: unknown;
+    uniqueKey: string | null;
+    dedup: unknown;
+}
+export interface SnapshotStorage {
+    diskFull: boolean;
+    error: string | null;
+}
+export type SnapshotTaskErrors = Record<string, {
+    consecutiveFailures: number;
+    lastError?: string;
+    lastFailureAt?: number;
+}>;
+export interface SnapshotConnections {
+    tcp: number;
+    ws: number;
+    sse: number;
+}
+export interface SnapshotSqliteStats {
+    dbSizeBytes: number;
+    writeBufferPending: number;
+}
+export interface SnapshotRuntime {
+    bunVersion: string;
+    os: string;
+    arch: string;
+    cpus: number;
+}

package/dist/types/src/infrastructure/cloud/types/snapshotJobs.d.ts

@@ -0,0 +1,124 @@
+export interface SnapshotTimelineEntry {
+    state: string;
+    timestamp: number;
+    worker?: string;
+    error?: string;
+    attempt?: number;
+}
+export interface SnapshotJob {
+    id: string;
+    name: string;
+    queue: string;
+    state: string;
+    data?: unknown;
+    priority: number;
+    createdAt: number;
+    startedAt?: number;
+    completedAt?: number;
+    runAt: number;
+    failedReason?: string;
+    attempts: number;
+    maxAttempts: number;
+    backoff: number;
+    timeout?: number;
+    ttl?: number;
+    duration?: number;
+    waitTime?: number;
+    totalDuration?: number;
+    progress?: number;
+    progressMessage?: string;
+    customId?: string;
+    uniqueKey?: string;
+    tags?: string[];
+    groupId?: string;
+    parentId?: string;
+    childrenIds?: string[];
+    dependsOn?: string[];
+    childrenCompleted?: number;
+    lastHeartbeat?: number;
+    stallCount?: number;
+    stallTimeout?: number;
+    removeOnComplete?: boolean;
+    removeOnFail?: boolean;
+    lifo?: boolean;
+    backoffConfig?: unknown;
+    repeat?: unknown;
+    stackTraceLimit: number;
+    keepLogs?: number;
+    sizeLimit?: number;
+    failParentOnFailure?: boolean;
+    removeDependencyOnFailure?: boolean;
+    continueParentOnFailure?: boolean;
+    ignoreDependencyOnFailure?: boolean;
+    deduplicationTtl?: number;
+    deduplicationExtend?: boolean;
+    deduplicationReplace?: boolean;
+    debounceId?: string;
+    debounceTtl?: number;
+    timeline?: SnapshotTimelineEntry[];
+}
+export interface SnapshotDlqAttempt {
+    attempt: number;
+    startedAt: number;
+    failedAt: number;
+    reason: string;
+    error: string | null;
+    duration: number;
+}
+export interface SnapshotDlqEntry {
+    jobId: string;
+    queue: string;
+    reason: string;
+    error: string | null;
+    enteredAt: number;
+    retryCount: number;
+    lastRetryAt?: number;
+    nextRetryAt?: number;
+    expiresAt?: number;
+    jobAttempts: number;
+    jobMaxAttempts: number;
+    jobData?: unknown;
+    jobCreatedAt: number;
+    jobPriority: number;
+    attemptHistory: SnapshotDlqAttempt[];
+}
+export interface SnapshotWorkerDetail {
+    id: string;
+    name: string;
+    queues: string[];
+    concurrency: number;
+    hostname: string;
+    pid: number;
+    registeredAt: number;
+    lastSeen: number;
+    activeJobs: number;
+    processedJobs: number;
+    failedJobs: number;
+    currentJob: string | null;
+    uptime: number;
+    status: 'active' | 'idle' | 'stalled';
+    errorRate: number;
+    utilization: number;
+}
+export interface SnapshotStallDetail {
+    jobId: string;
+    queue: string;
+    workerId: string | null;
+    stalledAt: number;
+    stalledForMs: number;
+}
+export interface SnapshotJobLogEntry {
+    timestamp: number;
+    level: 'info' | 'warn' | 'error';
+    message: string;
+}
+export interface SnapshotActiveLock {
+    jobId: string;
+    owner: string;
+    token: string;
+    createdAt: number;
+    expiresAt: number;
+    lastRenewalAt: number;
+    renewalCount: number;
+    ttl: number;
+}

package/dist/types/src/infrastructure/cloud/types/snapshotTelemetry.d.ts

@@ -0,0 +1,100 @@
+export interface SnapshotQueueConfig {
+    paused: boolean;
+    rateLimit: number | null;
+    concurrencyLimit: number | null;
+    concurrencyActive: number;
+    stallConfig?: {
+        enabled: boolean;
+        stallInterval: number;
+        maxStalls: number;
+        gracePeriod: number;
+    };
+    dlqConfig?: {
+        autoRetry: boolean;
+        autoRetryInterval: number;
+        maxRetries: number;
+        maxAge: number;
+        maxEntries: number;
+    };
+}
+export interface SnapshotWebhook {
+    id: string;
+    url: string;
+    events: string[];
+    queue: string | null;
+    enabled: boolean;
+    successCount: number;
+    failureCount: number;
+    lastTriggered: number | null;
+}
+export interface SnapshotTopError {
+    message: string;
+    count: number;
+    queue: string;
+    lastSeen: number;
+}
+export interface SnapshotQueueThroughput {
+    pushPerSec: number;
+    completePerSec: number;
+    failPerSec: number;
+    errorRate: number;
+}
+export interface SnapshotDurationHistogram {
+    lt100ms: number;
+    lt1s: number;
+    lt10s: number;
+    lt60s: number;
+    gt60s: number;
+}
+export interface SnapshotWorkerUtilization {
+    id: string;
+    name: string;
+    utilization: number;
+}
+export interface SnapshotQueueWaitTime {
+    avgMs: number;
+    maxMs: number;
+    minMs: number;
+}
+export interface SnapshotQueueRetryRate {
+    retryRate: number;
+    retrying: number;
+    total: number;
+}
+export interface SnapshotQueueBacklogVelocity {
+    deltaWaiting: number;
+    deltaPerMin: number;
+    trend: 'growing' | 'shrinking' | 'stable';
+}
+export interface SnapshotMcpOperation {
+    tool: string;
+    queue: string | null;
+    timestamp: number;
+    durationMs: number;
+    success: boolean;
+    error: string | null;
+}
+export interface SnapshotMcpSummary {
+    totalInvocations: number;
+    successCount: number;
+    failureCount: number;
+    avgDurationMs: number;
+    topTools: Array<{
+        tool: string;
+        count: number;
+    }>;
+}
+export interface SnapshotS3Backup {
+    enabled: boolean;
+    bucket: string;
+    endpoint: string;
+    intervalMs: number;
+    retention: number;
+    isRunning: boolean;
+}
+export interface SnapshotQueueExtended {
+    uniqueKeys: number;
+    activeGroups: number;
+    waitingDeps: number;
+    waitingChildren: number;
+}

package/dist/types/src/infrastructure/cloud/types.d.ts

@@ -0,0 +1,3 @@
+export type { CloudConfig } from "./types/config.js";
+export type { CloudEvent } from "./types/event.js";
+export type { CloudSnapshot } from "./types/snapshot.js";

package/dist/types/src/infrastructure/persistence/batchInsert.d.ts

@@ -0,0 +1,13 @@
+import type { Database } from "../../../sdk/typescript/src/canonical-transport/bun-sqlite-types.js";
+import type { Job } from "../../domain/types/job.js";
+import type { BatchInsertResult } from "./types/batch.js";
+/** Multi-row SQLite insert manager with per-row failure isolation. */
+export declare class BatchInsertManager {
+    private readonly db;
+    private readonly cache;
+    constructor(db: Database);
+    insertJobsBatch(jobs: Job[]): BatchInsertResult;
+    private insertRowByRow;
+    private getBatchInsertStmt;
+    private insertJobsChunk;
+}