@happyvertical/smrt-jobs 0.30.0

package/dist/smrt-job-event.d.ts

@@ -0,0 +1,54 @@
+import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
+export type SmrtJobEventType = 'status' | 'progress' | 'log' | 'error' | string;
+export type SmrtJobEventLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface SmrtJobEventData {
+    tenantId?: string | null;
+    jobId: string;
+    type?: SmrtJobEventType;
+    level?: SmrtJobEventLevel;
+    stage?: string | null;
+    progress?: number | null;
+    message?: string;
+    data?: Record<string, unknown>;
+    createdAt?: Date;
+}
+export interface JobEventCursor {
+    createdAt: string | Date;
+    id: string;
+}
+export interface ListJobEventsOptions {
+    tenantId?: string | null;
+    limit?: number;
+    since?: string | Date;
+    afterId?: string;
+    cursor?: string | JobEventCursor;
+}
+export declare class SmrtJobEvent extends SmrtObject {
+    tenantId: string | null | undefined;
+    jobId: string;
+    type: SmrtJobEventType;
+    level: SmrtJobEventLevel;
+    stage: string | null;
+    progress: number | null;
+    message: string;
+    data: Record<string, unknown>;
+    createdAt: Date;
+    toCursor(): string;
+}
+export declare class SmrtJobEventCollection extends SmrtCollection<SmrtJobEvent> {
+    static readonly _itemClass: typeof SmrtJobEvent;
+    initialize(): Promise<this>;
+    append(input: SmrtJobEventData): Promise<SmrtJobEvent>;
+    listByJob(jobId: string, options?: ListJobEventsOptions): Promise<SmrtJobEvent[]>;
+    listSinceCursor(options?: ListJobEventsOptions & {
+        jobId?: string;
+    }): Promise<SmrtJobEvent[]>;
+    latestProgressByJobIds(jobIds: string[], options?: {
+        tenantId?: string | null;
+    }): Promise<Map<string, SmrtJobEvent>>;
+    private addTenantPredicate;
+    private createdAtComparableExpression;
+    private resolveCursorCreatedAt;
+}
+export default SmrtJobEvent;
+//# sourceMappingURL=smrt-job-event.d.ts.map

package/dist/smrt-job-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smrt-job-event.d.ts","sourceRoot":"","sources":["../src/smrt-job-event.ts"],"names":[],"mappings":"AAEA,OAAO,wBAAwB,CAAC;AAEhC,OAAO,EAIL,cAAc,EACd,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAOlC,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,UAAU,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC;AAEhF,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEpE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC;CAClC;AAkBD,qBAoBa,YAAa,SAAQ,UAAU;IAE1C,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAa;IAGhD,KAAK,EAAE,MAAM,CAAM;IAGnB,IAAI,EAAE,gBAAgB,CAAS;IAG/B,KAAK,EAAE,iBAAiB,CAAU;IAGlC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAQ;IAG5B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAG/B,OAAO,EAAE,MAAM,CAAM;IAGrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM;IAGnC,SAAS,EAAE,IAAI,CAAc;IAE7B,QAAQ,IAAI,MAAM;CAOnB;AAwDD,qBAAa,sBAAuB,SAAQ,cAAc,CAAC,YAAY,CAAC;IACtE,MAAM,CAAC,QAAQ,CAAC,UAAU,sBAAgB;IAE3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMpC,MAAM,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;IActD,SAAS,CACb,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,YAAY,EAAE,CAAC;IAOpB,eAAe,CACnB,OAAO,GAAE,oBAAoB,GAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GACtD,OAAO,CAAC,YAAY,EAAE,CAAC;IA2CpB,sBAAsB,CAC1B,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAO,GACzC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAwCrC,OAAO,CAAC,kBAAkB;IAwB1B,OAAO,CAAC,6BAA6B;YAQvB,sBAAsB;CA6BrC;AAED,eAAe,YAAY,CAAC"}

package/dist/smrt-job.d.ts

@@ -0,0 +1,215 @@
+import { RetryStrategyConfig } from '@happyvertical/jobs';
+import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
+/**
+ * Job status type
+ */
+export type JobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Timeout behavior type
+ */
+export type TimeoutBehavior = 'fail' | 'kill' | 'warn';
+/**
+ * Persistent job record stored in the `_smrt_jobs` system table.
+ *
+ * @remarks
+ * Each SmrtJob represents a deferred method call on a SmrtObject. The TaskRunner polls for
+ * pending jobs, resolves the target class via ObjectRegistry, and invokes the method. Jobs
+ * track status (`pending -> running -> completed/failed/cancelled`), retry attempts with
+ * configurable strategies, worker heartbeats for stale-job detection, and optional result pointers.
+ * Priority ordering is `higher = sooner`; the default timeout is 5 minutes (300000ms).
+ */
+export declare class SmrtJob extends SmrtObject {
+    /** Tenant context captured for this job, if any */
+    tenantId: string | null | undefined;
+    /** Queue name for the job */
+    queue: string;
+    /** Type of object to invoke method on */
+    objectType: string;
+    /** ID of the specific object (null for static methods) */
+    objectId: string | null;
+    /** Method name to invoke */
+    method: string;
+    /** Arguments to pass to the method (JSON) */
+    args: Record<string, unknown>;
+    /** When to run the job */
+    runAt: Date;
+    /** Priority (higher = sooner) */
+    priority: number;
+    /** Current status */
+    status: JobStatus;
+    /** Number of execution attempts */
+    attempts: number;
+    /** Maximum retry attempts */
+    maxAttempts: number;
+    /** Timeout in milliseconds */
+    timeout: number;
+    /** What to do on timeout */
+    timeoutBehavior: TimeoutBehavior;
+    /** When execution started */
+    startedAt: Date | null;
+    /** When execution completed */
+    completedAt: Date | null;
+    /** Last error message */
+    lastError: string | null;
+    /** Pointer to where result is stored */
+    resultPointer: string | null;
+    /** Retry strategy configuration */
+    retryStrategy: RetryStrategyConfig;
+    /** ID of the worker processing this job */
+    workerId: string | null;
+    /** Last heartbeat from the worker */
+    workerHeartbeat: Date | null;
+    /**
+     * Capture ambient tenant context when a job is saved inside withTenant().
+     *
+     * Scheduled jobs can also set this explicitly from their owning schedule.
+     */
+    save(): Promise<this>;
+    /**
+     * Mark the job for retry
+     */
+    retry(): Promise<void>;
+    /**
+     * Cancel the job
+     */
+    cancel(): Promise<void>;
+    /**
+     * Get a human-readable description of the job
+     */
+    getDescription(): string;
+}
+/**
+ * Job data type (for create operations)
+ */
+export interface SmrtJobData {
+    tenantId?: string | null;
+    queue?: string;
+    objectType: string;
+    objectId?: string | null;
+    method: string;
+    args?: Record<string, unknown>;
+    runAt?: Date;
+    priority?: number;
+    maxAttempts?: number;
+    timeout?: number;
+    timeoutBehavior?: TimeoutBehavior;
+    retryStrategy?: RetryStrategyConfig;
+}
+/**
+ * Options controlling a centralized {@link SmrtJobCollection.enqueueJob} call.
+ */
+export interface EnqueueJobOptions {
+    /**
+     * Per-tenant in-flight cap. Defaults to {@link DEFAULT_TENANT_JOB_CAP}.
+     * `0`/negative disables the cap (trusted internal callers). Global
+     * (no-context / null tenant) jobs are always exempt.
+     */
+    tenantJobCap?: number;
+}
+/**
+ * Options for listReady
+ */
+export interface ListReadyOptions {
+    limit?: number;
+    queues?: string[];
+}
+/**
+ * Options for atomically claiming ready jobs.
+ */
+export interface ClaimReadyOptions extends ListReadyOptions {
+    workerId: string;
+    now?: Date;
+}
+/**
+ * Collection for managing SmrtJob objects
+ */
+export declare class SmrtJobCollection extends SmrtCollection<SmrtJob> {
+    static readonly _itemClass: typeof SmrtJob;
+    initialize(): Promise<this>;
+    /**
+     * List jobs by status
+     */
+    listByStatus(status: JobStatus | JobStatus[], options?: {
+        limit?: number;
+        queue?: string;
+    }): Promise<SmrtJob[]>;
+    /**
+     * List pending jobs ready to run
+     */
+    listReady(options?: {
+        limit?: number;
+        queues?: string[];
+    }): Promise<SmrtJob[]>;
+    /**
+     * Atomically claim pending jobs ready to run for a worker.
+     *
+     * The claim is performed as one conditional UPDATE so concurrent workers
+     * cannot receive the same pending row. PostgreSQL additionally skips rows
+     * locked by other workers instead of waiting behind them.
+     */
+    claimReady(options: ClaimReadyOptions): Promise<SmrtJob[]>;
+    /**
+     * Count non-terminal (pending/running) jobs owned by a tenant.
+     *
+     * Used to enforce the per-tenant creation cap so one tenant cannot exhaust
+     * the shared worker pool (S5 audit #1402). Reads `_smrt_jobs` directly so it
+     * works regardless of ambient tenant context.
+     *
+     * @param tenantId - Tenant to count for. `null` counts global (NULL-tenant)
+     *   jobs.
+     */
+    countInFlightForTenant(tenantId: string | null): Promise<number>;
+    /**
+     * The single creation path for queued jobs.
+     *
+     * Centralizes the two creation-time security guards from the S5 audit (#1402)
+     * so every enqueue — the fluent {@link "./job-builder".JobBuilder} *and* the
+     * ScheduleRunner's cron-triggered jobs — goes through one place:
+     *
+     * 1. `maxAttempts` is clamped to {@link MAX_JOB_RETRIES} so a misconfigured
+     *    caller cannot pin a worker on a poison job indefinitely.
+     * 2. A per-tenant in-flight cap bounds how many non-terminal jobs one tenant
+     *    may hold, so one tenant cannot exhaust the shared worker pool
+     *    (cross-tenant denial of service). The cap applies to the row's effective
+     *    tenant (explicit `data.tenantId` or, when absent, the ambient context);
+     *    global (null-tenant) jobs are exempt.
+     *
+     * Atomicity note (best-effort soft cap, by design): the cap is a
+     * count-then-insert, NOT a hard transactional invariant. It is intentionally
+     * left non-atomic. A plain transaction would not help — under the adapters'
+     * default isolation two concurrent same-tenant enqueues would each read the
+     * same COUNT and both insert, so serializing them would require either a
+     * per-tenant lock row (`SELECT ... FOR UPDATE`) or SERIALIZABLE-isolation
+     * retry loops. That cross-process locking is fragile (lock-row contention,
+     * adapter-specific isolation behavior, the `transaction` adapter method being
+     * optional) and out of proportion to the threat: this cap is defense in depth
+     * against runaway/accidental creation exhausting the shared worker pool, not a
+     * billing/quota boundary. So under truly simultaneous enqueues a tenant may
+     * momentarily overshoot by the number of in-flight creators; the bound still
+     * prevents unbounded growth and closes the prior ScheduleRunner bypass. If a
+     * hard guarantee is ever needed, enforce it with a DB CHECK/trigger or a
+     * dedicated counter row, not an application-level lock.
+     */
+    enqueueJob(data: SmrtJobData, options?: EnqueueJobOptions): Promise<SmrtJob>;
+    /**
+     * Get job statistics
+     */
+    stats(queue?: string): Promise<{
+        pending: number;
+        running: number;
+        completed: number;
+        failed: number;
+        cancelled: number;
+    }>;
+    /**
+     * Cleanup old completed/failed jobs
+     */
+    cleanup(options: {
+        completedBefore?: Date;
+        failedBefore?: Date;
+        cancelledBefore?: Date;
+        limit?: number;
+    }): Promise<number>;
+}
+export default SmrtJob;
+//# sourceMappingURL=smrt-job.d.ts.map

package/dist/smrt-job.d.ts.map

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