@guren/server 0.2.0-alpha.7 → 1.0.0-rc.9

package/dist/queue/index.d.ts

@@ -0,0 +1,423 @@
+import { a5 as QueueDriver, a7 as QueuedJob, F as FailedJob, aw as WorkerOptions } from '../Application-DtWDHXr1.js';
+export { R as Job, T as JobClass, U as JobFailureHandler, V as JobHandler, W as JobOptions, a4 as QueueConfig, a6 as QueueDriverFactory, Q as QueueManager, aA as clearJobRegistry, aH as createQueueManager, aO as getJob, aQ as getQueueDriver, aR as getRegisteredJobs, aV as registerJob, a$ as setQueueDriver } from '../Application-DtWDHXr1.js';
+import { Redis } from 'ioredis';
+import 'hono';
+import '../api-token-JOif2CtG.js';
+import 'vite';
+import '../EventManager-CmIoLt7r.js';
+import '../CacheManager-BkvHEOZX.js';
+import '../MailManager-DpMvYiP9.js';
+import '../LogManager-7mxnkaPM.js';
+import '../I18nManager-Dtgzsf5n.js';
+import '../BroadcastManager-AkIWUGJo.js';
+import '../index-9_Jzj5jo.js';
+import '../app-key-CsBfRC_Q.js';
+import '../StorageManager-oZTHqaza.js';
+import '../HealthManager-DUyMIzsZ.js';
+import '../Scheduler-BstvSca7.js';
+import '../Gate-CNkBYf8m.js';
+
+/**
+ * In-memory queue driver for development and testing.
+ *
+ * @example
+ * ```ts
+ * import { MemoryDriver, setQueueDriver } from '@guren/server/queue'
+ *
+ * const driver = new MemoryDriver()
+ * setQueueDriver(driver)
+ * ```
+ */
+declare class MemoryDriver implements QueueDriver {
+    private jobs;
+    private failedJobs;
+    /**
+     * Push a job onto the queue.
+     */
+    push(job: QueuedJob): Promise<void>;
+    /**
+     * Pop the next available job from the queue.
+     */
+    pop(queue: string): Promise<QueuedJob | null>;
+    /**
+     * Release a job back onto the queue.
+     */
+    release(job: QueuedJob, delayMs?: number): Promise<void>;
+    /**
+     * Delete a job from the queue.
+     */
+    delete(jobId: string): Promise<void>;
+    /**
+     * Mark a job as failed.
+     */
+    fail(job: QueuedJob, error: Error): Promise<void>;
+    /**
+     * Get the number of jobs in a queue.
+     */
+    size(queue: string): Promise<number>;
+    /**
+     * Get failed jobs.
+     */
+    getFailedJobs(queue?: string): Promise<FailedJob[]>;
+    /**
+     * Retry a failed job.
+     */
+    retryFailedJob(jobId: string): Promise<void>;
+    /**
+     * Delete a failed job.
+     */
+    deleteFailedJob(jobId: string): Promise<void>;
+    /**
+     * Clear all jobs (for testing).
+     */
+    clear(): Promise<void>;
+    /**
+     * Get all pending jobs (for testing/debugging).
+     */
+    getPendingJobs(queue?: string): QueuedJob[];
+}
+
+/**
+ * Options for RedisDriver.
+ */
+interface RedisDriverOptions {
+    /**
+     * Key prefix for queue keys.
+     * @default 'queue:'
+     */
+    prefix?: string;
+    /**
+     * Visibility timeout in milliseconds.
+     * Jobs reserved longer than this will be released.
+     * @default 60000
+     */
+    visibilityTimeout?: number;
+}
+/**
+ * Redis-backed queue driver for production.
+ *
+ * Uses the following Redis structures:
+ * - `{prefix}{queue}:pending` - Sorted Set (score = availableAt timestamp)
+ * - `{prefix}{queue}:reserved` - Sorted Set (score = timeout timestamp)
+ * - `{prefix}{queue}:failed` - List of failed job IDs
+ * - `{prefix}job:{id}` - Hash containing job data
+ *
+ * @example
+ * ```ts
+ * import { createRedisClient } from '@guren/server/redis'
+ * import { RedisDriver, setQueueDriver } from '@guren/server/queue'
+ *
+ * const redis = createRedisClient({ url: process.env.REDIS_URL })
+ * const driver = new RedisDriver(redis)
+ * setQueueDriver(driver)
+ * ```
+ */
+declare class RedisDriver implements QueueDriver {
+    private readonly redis;
+    private readonly prefix;
+    private readonly visibilityTimeout;
+    constructor(redis: Redis, options?: RedisDriverOptions);
+    private pendingKey;
+    private reservedKey;
+    private failedKey;
+    private jobKey;
+    /**
+     * Push a job onto the queue.
+     */
+    push(job: QueuedJob): Promise<void>;
+    /**
+     * Pop the next available job from the queue.
+     */
+    pop(queue: string): Promise<QueuedJob | null>;
+    /**
+     * Release jobs that have exceeded visibility timeout.
+     */
+    private releaseTimedOutJobs;
+    /**
+     * Release a job back onto the queue.
+     */
+    release(job: QueuedJob, delayMs?: number): Promise<void>;
+    /**
+     * Delete a job from the queue.
+     */
+    delete(jobId: string): Promise<void>;
+    /**
+     * Mark a job as failed.
+     */
+    fail(job: QueuedJob, error: Error): Promise<void>;
+    /**
+     * Get the number of jobs in a queue.
+     */
+    size(queue: string): Promise<number>;
+    /**
+     * Get failed jobs.
+     */
+    getFailedJobs(queue?: string): Promise<FailedJob[]>;
+    private getFailedJobsForQueue;
+    /**
+     * Retry a failed job.
+     */
+    retryFailedJob(jobId: string): Promise<void>;
+    /**
+     * Delete a failed job.
+     */
+    deleteFailedJob(jobId: string): Promise<void>;
+    /**
+     * Clear all jobs (for testing).
+     */
+    clear(): Promise<void>;
+    /**
+     * Parse job data from Redis hash.
+     */
+    private parseJobData;
+}
+
+/**
+ * Abstracted SQS operations.
+ * Users implement this interface by wrapping their SQS client (e.g. @aws-sdk/client-sqs).
+ * This avoids a hard dependency on @aws-sdk/client-sqs in the framework.
+ */
+interface SqsAdapter {
+    /**
+     * Send a message to an SQS queue.
+     */
+    sendMessage(params: {
+        queueUrl: string;
+        messageBody: string;
+        delaySeconds: number;
+        messageGroupId?: string;
+        messageDeduplicationId?: string;
+    }): Promise<void>;
+    /**
+     * Receive a single message from an SQS queue.
+     */
+    receiveMessage(params: {
+        queueUrl: string;
+        waitTimeSeconds?: number;
+    }): Promise<{
+        body: string;
+        receiptHandle: string;
+    } | null>;
+    /**
+     * Change the visibility timeout of a message.
+     */
+    changeMessageVisibility(params: {
+        queueUrl: string;
+        receiptHandle: string;
+        visibilityTimeout: number;
+    }): Promise<void>;
+    /**
+     * Get the approximate number of messages in a queue.
+     */
+    getApproximateMessageCount(queueUrl: string): Promise<number>;
+}
+/**
+ * Options for SqsDriver.
+ */
+interface SqsDriverOptions {
+    /**
+     * SQS queue URL for the primary queue.
+     */
+    queueUrl: string;
+    /**
+     * Optional mapping of logical queue names to SQS queue URLs.
+     * If not specified, all queues use the primary `queueUrl`.
+     */
+    queueUrls?: Record<string, string>;
+    /**
+     * Message group ID for FIFO queues. If set, enables FIFO mode.
+     */
+    messageGroupId?: string;
+}
+/**
+ * Create an SqsAdapter from an @aws-sdk/client-sqs SQSClient.
+ *
+ * @example
+ * ```ts
+ * import { SQSClient } from '@aws-sdk/client-sqs'
+ * import { createSqsAdapter, SqsDriver } from '@guren/server/queue'
+ *
+ * const client = new SQSClient({ region: 'ap-northeast-1' })
+ * const adapter = createSqsAdapter(client)
+ * const driver = new SqsDriver(adapter, { queueUrl: '...' })
+ * ```
+ */
+declare function createSqsAdapter(client: {
+    send(command: unknown): Promise<unknown>;
+}): SqsAdapter;
+/**
+ * AWS SQS queue driver for serverless deployments.
+ *
+ * @example
+ * ```ts
+ * import { SQSClient } from '@aws-sdk/client-sqs'
+ * import { createSqsAdapter, SqsDriver, setQueueDriver } from '@guren/server/queue'
+ *
+ * const adapter = createSqsAdapter(new SQSClient({ region: 'ap-northeast-1' }))
+ * const driver = new SqsDriver(adapter, { queueUrl: process.env.SQS_QUEUE_URL! })
+ * setQueueDriver(driver)
+ *
+ * // Dispatch jobs as usual
+ * await SendEmailJob.dispatch({ to: 'user@example.com' })
+ * ```
+ */
+declare class SqsDriver implements QueueDriver {
+    private readonly adapter;
+    private readonly options;
+    private readonly failedJobs;
+    private readonly receiptHandles;
+    constructor(adapter: SqsAdapter, options: SqsDriverOptions);
+    push(job: QueuedJob): Promise<void>;
+    pop(queue: string): Promise<QueuedJob | null>;
+    release(job: QueuedJob, delayMs?: number): Promise<void>;
+    delete(jobId: string): Promise<void>;
+    fail(job: QueuedJob, error: Error): Promise<void>;
+    size(queue: string): Promise<number>;
+    getFailedJobs(queue?: string): Promise<FailedJob[]>;
+    retryFailedJob(jobId: string): Promise<void>;
+    deleteFailedJob(jobId: string): Promise<void>;
+    clear(): Promise<void>;
+    private resolveQueueUrl;
+}
+
+/**
+ * Worker events.
+ */
+interface WorkerEvents {
+    /**
+     * Emitted when a job is processed successfully.
+     */
+    jobProcessed?: (job: QueuedJob) => void;
+    /**
+     * Emitted when a job fails (but may retry).
+     */
+    jobFailed?: (job: QueuedJob, error: Error, willRetry: boolean) => void;
+    /**
+     * Emitted when the worker starts.
+     */
+    workerStarted?: () => void;
+    /**
+     * Emitted when the worker stops.
+     */
+    workerStopped?: () => void;
+}
+/**
+ * Queue worker that processes jobs.
+ *
+ * @example
+ * ```ts
+ * import { Worker, MemoryDriver, setQueueDriver } from '@guren/server/queue'
+ *
+ * const driver = new MemoryDriver()
+ * setQueueDriver(driver)
+ *
+ * const worker = new Worker(driver, {
+ *   queues: ['default', 'emails'],
+ *   sleep: 1000,
+ * })
+ *
+ * // Start processing
+ * await worker.start()
+ *
+ * // Stop gracefully
+ * await worker.stop()
+ * ```
+ */
+declare class Worker {
+    private readonly driver;
+    private readonly options;
+    private readonly events;
+    private running;
+    private shouldStop;
+    private processedJobs;
+    private readonly queues;
+    private readonly sleep;
+    private readonly maxJobs;
+    private readonly timeout;
+    private readonly stopWhenEmpty;
+    private currentJob;
+    constructor(driver: QueueDriver, options?: WorkerOptions, events?: WorkerEvents);
+    /**
+     * Start the worker.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the worker gracefully.
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if the worker is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Get the number of processed jobs.
+     */
+    getProcessedJobsCount(): number;
+    /**
+     * Get the next available job from the queues.
+     */
+    private getNextJob;
+    /**
+     * Process a single job.
+     */
+    private processJob;
+    /**
+     * Handle a failed job.
+     */
+    private handleFailedJob;
+    /**
+     * Execute a function with a timeout.
+     */
+    private executeWithTimeout;
+    /**
+     * Sleep for a given number of milliseconds.
+     */
+    private sleepMs;
+}
+/**
+ * Process a single job (for testing or one-off execution).
+ */
+declare function processJob(driver: QueueDriver, queue?: string): Promise<boolean>;
+
+/**
+ * Information about a failed queue job.
+ */
+interface FailedJobInfo {
+    jobName: string;
+    queue: string;
+    attempt: number;
+    maxAttempts: number;
+    willRetry: boolean;
+    error: Error;
+    failedAt: Date;
+}
+/**
+ * Handler function invoked when a job fails.
+ */
+type FailedJobHandler = (info: FailedJobInfo) => void | Promise<void>;
+/**
+ * Configurable reporter for failed queue jobs.
+ *
+ * Registered by default in QueueServiceProvider to log failures.
+ * Can be extended with custom handlers (e.g., Sentry, Slack notifications).
+ *
+ * @example
+ * ```ts
+ * const reporter = new FailedJobReporter()
+ *
+ * // Add a custom handler alongside the default logger
+ * reporter.onFailure(async (info) => {
+ *   await sendToSentry(info.error)
+ * })
+ * ```
+ */
+declare class FailedJobReporter {
+    private handlers;
+    constructor();
+    /** Add a custom handler for failed jobs. */
+    onFailure(handler: FailedJobHandler): this;
+    /** Report a job failure to all registered handlers. */
+    report(info: FailedJobInfo): Promise<void>;
+}
+
+export { FailedJob, type FailedJobHandler, type FailedJobInfo, FailedJobReporter, MemoryDriver, QueueDriver, QueuedJob, RedisDriver, type RedisDriverOptions, type SqsAdapter, SqsDriver, type SqsDriverOptions, Worker, type WorkerEvents, WorkerOptions, createSqsAdapter, processJob };