feat: defining base queue driver architecture

packages/contracts/src/Queue/IQueueDriver.ts

@@ -0,0 +1,36 @@
+import { IJob } from "./IJob";
+import { JobPayload } from "./Utils";
+
+/**
+ * Queue driver contract for queue backends.
+ * Methods can be sync or async (return T | Promise<T>).
+ */
+export abstract class IQueueDriver {
+  abstract push(
+    queue: string,
+    payload: JobPayload,
+    connection?: string,
+  ): string | number | void | Promise<string | number | void>;
+
+  abstract later(
+    queue: string,
+    payload: JobPayload,
+    delay: number,
+    connection?: string,
+  ): string | number | void | Promise<string | number | void>;
+
+  abstract bulk(
+    queue: string,
+    payloads: JobPayload[],
+    connection?: string,
+  ): (string | number | void)[] | Promise<(string | number | void)[]>;
+
+  abstract pop(
+    queue: string,
+    connection?: string,
+  ): IJob | null | Promise<IJob | null>;
+
+  abstract size?(queue: string, connection?: string): number | Promise<number>;
+
+  abstract clear?(queue: string, connection?: string): void | Promise<void>;
+}

packages/contracts/src/Queue/IQueueManager.ts

@@ -0,0 +1,16 @@
+import { IQueueDriver } from './IQueueDriver'
+
+/**
+ * Queue manager contract for managing drivers and connections.
+ */
+export abstract class IQueueManager {
+    abstract connection(name?: string): IQueueDriver
+
+    abstract driver(name: string): IQueueDriver
+
+    abstract extend(name: string, driver: IQueueDriver): void
+
+    abstract getDefaultConnection(): string
+
+    abstract setDefaultConnection(name: string): void
+}

packages/contracts/src/Queue/Utils.ts

@@ -1,12 +1,40 @@
+/**
+ * Serialized job data stored in the queue.
+ */
 export interface JobPayload {
-    maxTries?: number;
-    maxExceptions?: number;
-    failOnTimeout?: boolean;
-    timeout?: number;
-    retryUntil?: number;
-    job: string;
-    backoff?: number;
-    delay?: number;
-    data?: any;
-    uuid?: string;
-}
+  /** Fully qualified job handler class name. */
+  job: string;
+
+  /** Data passed to handle() method. */
+  data?: any;
+
+  /** Unique job identifier. */
+  uuid?: string;
+
+  /** Maximum number of attempts. */
+  maxTries?: number;
+
+  /** Maximum number of exception attempts. */
+  maxExceptions?: number;
+
+  /** Seconds to wait before retry (can be array for exponential backoff). */
+  backoff?: number;
+
+  /** Seconds to delay job execution. */
+  delay?: number;
+
+  /** Job timeout in seconds. */
+  timeout?: number;
+
+  /** Absolute timestamp when job should timeout. */
+  retryUntil?: number;
+
+  /** Whether to fail on timeout. */
+  failOnTimeout?: boolean;
+
+  /** Job priority (driver-specific). */
+  priority?: number;
+
+  /** Job tags (driver-specific). */
+  tags?: string[];
+}

packages/contracts/src/index.ts

@@ -33,6 +33,8 @@ export * from './Http/IServerBag'
 export * from './Http/IUploadedFile'
 export * from './Http/Utils'
 export * from './Queue/IJob'
+export * from './Queue/IQueueDriver'
+export * from './Queue/IQueueManager'
 export * from './Queue/Utils'
 export * from './Routing/IAbstractRouteCollection'
 export * from './Routing/ICallableDispatcher'