@inf-minds/jobs 0.0.1

package/src/job-manager.ts

@@ -0,0 +1,179 @@
+// ABOUTME: JobManager implementation for job CRUD operations
+// ABOUTME: Provides create, get, list, cancel, complete, and fail operations
+
+import { eq, and, desc } from 'drizzle-orm';
+import { jobs, JOB_STATUS, type Job, type JobStatus } from './schema.js';
+import type {
+  JobManager,
+  CreateJobOptions,
+  ListJobsOptions,
+  ListJobsResult,
+  DbClient,
+} from './types.js';
+
+/**
+ * Error thrown when a job operation fails.
+ */
+export class JobError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly jobId?: string
+  ) {
+    super(message);
+    this.name = 'JobError';
+  }
+}
+
+/**
+ * Creates a JobManager instance.
+ *
+ * @example
+ * import { drizzle } from 'drizzle-orm/postgres-js';
+ * import postgres from 'postgres';
+ * import { createJobManager } from '@inf-minds/jobs';
+ *
+ * const client = postgres(process.env.DATABASE_URL);
+ * const db = drizzle(client);
+ * const jobManager = createJobManager(db);
+ */
+export function createJobManager(db: DbClient): JobManager {
+  return new JobManagerImpl(db);
+}
+
+class JobManagerImpl implements JobManager {
+  constructor(private readonly db: DbClient) {}
+
+  async create<TInput = unknown>(options: CreateJobOptions<TInput>): Promise<Job> {
+    // Validate required fields
+    if (!options.type || options.type.trim() === '') {
+      throw new JobError('Job type is required', 'INVALID_TYPE');
+    }
+
+    if (!options.accountId || options.accountId.trim() === '') {
+      throw new JobError('Account ID is required', 'INVALID_ACCOUNT_ID');
+    }
+
+    const result = await this.db
+      .insert(jobs)
+      .values({
+        type: options.type,
+        accountId: options.accountId,
+        status: JOB_STATUS.PENDING,
+        input: options.input ?? null,
+        // Kernel orchestration fields
+        parentJobId: options.parentJobId ?? null,
+        nodeId: options.nodeId ?? null,
+        graphState: options.graphState ?? null,
+        artifactBasePath: options.artifactBasePath ?? null,
+      })
+      .returning();
+
+    const job = result[0];
+    if (!job) {
+      throw new JobError('Failed to create job', 'CREATE_FAILED');
+    }
+
+    return job as Job;
+  }
+
+  async get(jobId: string): Promise<Job | null> {
+    const result = await this.db
+      .select()
+      .from(jobs)
+      .where(eq(jobs.id, jobId));
+
+    return (result[0] as Job) ?? null;
+  }
+
+  async list(options: ListJobsOptions): Promise<ListJobsResult> {
+    const { accountId, type, status, limit = 50, offset = 0 } = options;
+
+    // Build where conditions
+    const conditions = [eq(jobs.accountId, accountId)];
+
+    if (type) {
+      conditions.push(eq(jobs.type, type));
+    }
+
+    if (status) {
+      conditions.push(eq(jobs.status, status));
+    }
+
+    const whereClause = conditions.length === 1 ? conditions[0]! : and(...conditions);
+
+    const result = await this.db
+      .select()
+      .from(jobs)
+      .where(whereClause)
+      .orderBy(desc(jobs.createdAt))
+      .limit(limit)
+      .offset(offset);
+
+    return {
+      jobs: result as Job[],
+    };
+  }
+
+  async cancel(jobId: string): Promise<void> {
+    const job = await this.get(jobId);
+
+    if (!job) {
+      throw new JobError('Job not found', 'NOT_FOUND', jobId);
+    }
+
+    if (!this.isCancellable(job.status as JobStatus)) {
+      throw new JobError(
+        `Cannot cancel job with status '${job.status}'`,
+        'NOT_CANCELLABLE',
+        jobId
+      );
+    }
+
+    await this.db
+      .update(jobs)
+      .set({
+        status: JOB_STATUS.CANCELLED,
+        completedAt: new Date(),
+      })
+      .where(eq(jobs.id, jobId));
+  }
+
+  async updateProgress(jobId: string, progress: number): Promise<void> {
+    const clampedProgress = Math.max(0, Math.min(1, progress));
+
+    await this.db
+      .update(jobs)
+      .set({
+        progress: clampedProgress,
+      })
+      .where(eq(jobs.id, jobId));
+  }
+
+  async complete<TOutput = unknown>(jobId: string, output?: TOutput): Promise<void> {
+    await this.db
+      .update(jobs)
+      .set({
+        status: JOB_STATUS.COMPLETED,
+        output: output ?? null,
+        progress: 1.0,
+        completedAt: new Date(),
+      })
+      .where(eq(jobs.id, jobId));
+  }
+
+  async fail(jobId: string, error: string): Promise<void> {
+    await this.db
+      .update(jobs)
+      .set({
+        status: JOB_STATUS.FAILED,
+        error,
+        completedAt: new Date(),
+      })
+      .where(eq(jobs.id, jobId));
+  }
+
+  private isCancellable(status: JobStatus): boolean {
+    return status === JOB_STATUS.PENDING || status === JOB_STATUS.RUNNING;
+  }
+}

package/src/job-runner.ts

@@ -0,0 +1,260 @@
+// ABOUTME: JobRunner implementation for direct execution model
+// ABOUTME: Orchestrates job lifecycle - create, run handler, complete/fail
+
+import { createJobContext, JobAbortedError } from './job-context.js';
+import { JOB_STATUS } from './schema.js';
+import type {
+  JobRunner,
+  JobRunnerOptions,
+  RunJobOptions,
+  RunJobResult,
+  JobHandler,
+  JobManager,
+  EventAppender,
+} from './types.js';
+import type { ArtifactManager } from './artifact-manager.js';
+import type { ArtifactMaterializer } from './artifact-materializer.js';
+import type { MaterializedArtifacts } from './job-context.js';
+
+/**
+ * Error thrown when a job cannot be found or resumed.
+ */
+export class JobRunnerError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly jobId?: string
+  ) {
+    super(message);
+    this.name = 'JobRunnerError';
+  }
+}
+
+/**
+ * Creates a JobRunner for direct execution of jobs.
+ *
+ * @example
+ * ```typescript
+ * const runner = createJobRunner({
+ *   jobManager,
+ *   eventAppender,
+ *   relayCallbackUrl: 'https://relay.example.com/callback',
+ * });
+ *
+ * const result = await runner.run(
+ *   { type: 'process-image', accountId, input: { url: '...' } },
+ *   async (ctx) => {
+ *     await ctx.log('Starting');
+ *     await ctx.progress(0.5);
+ *     return { result: 'done' };
+ *   }
+ * );
+ * ```
+ */
+export function createJobRunner(options: JobRunnerOptions): JobRunner {
+  return new JobRunnerImpl(options);
+}
+
+class JobRunnerImpl implements JobRunner {
+  private readonly jobManager: JobManager;
+  private readonly eventAppender: EventAppender;
+  private readonly relayCallbackUrl?: string;
+  private readonly fetchFn: typeof globalThis.fetch;
+  private readonly artifactManager?: ArtifactManager;
+  private readonly artifactMaterializer?: ArtifactMaterializer;
+
+  constructor(options: JobRunnerOptions) {
+    this.jobManager = options.jobManager;
+    this.eventAppender = options.eventAppender;
+    this.relayCallbackUrl = options.relayCallbackUrl;
+    this.fetchFn = options.fetch ?? globalThis.fetch;
+    this.artifactManager = options.artifactManager;
+    this.artifactMaterializer = options.artifactMaterializer;
+  }
+
+  async run<TInput = unknown, TOutput = unknown>(
+    options: RunJobOptions<TInput>,
+    handler: JobHandler<TInput, TOutput>
+  ): Promise<RunJobResult<TOutput>> {
+    // Create the job
+    const job = await this.jobManager.create({
+      type: options.type,
+      accountId: options.accountId,
+      input: options.input,
+    });
+
+    // Execute with the newly created job
+    return this.executeJob(job.id, handler, options.signal);
+  }
+
+  async resume<TInput = unknown, TOutput = unknown>(
+    jobId: string,
+    handler: JobHandler<TInput, TOutput>,
+    signal?: AbortSignal
+  ): Promise<RunJobResult<TOutput>> {
+    // Fetch existing job
+    const job = await this.jobManager.get(jobId);
+
+    if (!job) {
+      throw new JobRunnerError(
+        `Job not found: ${jobId}`,
+        'JOB_NOT_FOUND',
+        jobId
+      );
+    }
+
+    // Validate job can be resumed
+    if (job.status === JOB_STATUS.COMPLETED) {
+      throw new JobRunnerError(
+        `Job already completed: ${jobId}`,
+        'JOB_ALREADY_COMPLETED',
+        jobId
+      );
+    }
+
+    if (job.status === JOB_STATUS.CANCELLED) {
+      throw new JobRunnerError(
+        `Job was cancelled: ${jobId}`,
+        'JOB_CANCELLED',
+        jobId
+      );
+    }
+
+    if (job.status === JOB_STATUS.FAILED) {
+      throw new JobRunnerError(
+        `Job already failed: ${jobId}`,
+        'JOB_ALREADY_FAILED',
+        jobId
+      );
+    }
+
+    return this.executeJob(jobId, handler, signal);
+  }
+
+  private async executeJob<TInput = unknown, TOutput = unknown>(
+    jobId: string,
+    handler: JobHandler<TInput, TOutput>,
+    signal?: AbortSignal
+  ): Promise<RunJobResult<TOutput>> {
+    // Fetch the job (may have been just created or being resumed)
+    const job = await this.jobManager.get(jobId);
+
+    if (!job) {
+      throw new JobRunnerError(
+        `Job not found: ${jobId}`,
+        'JOB_NOT_FOUND',
+        jobId
+      );
+    }
+
+    // Create abort controller for this execution
+    const controller = new AbortController();
+
+    // Link to external signal if provided
+    if (signal) {
+      if (signal.aborted) {
+        controller.abort();
+      } else {
+        signal.addEventListener('abort', () => controller.abort(), { once: true });
+      }
+    }
+
+    // Create relay callback handler if configured
+    const onEvent = this.relayCallbackUrl
+      ? async (event: { type: string; payload: unknown; offset: string }) => {
+          try {
+            await this.fetchFn(`${this.relayCallbackUrl}/${jobId}`, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify(event),
+            });
+          } catch {
+            // Fire and forget - don't fail job on relay errors
+          }
+        }
+      : undefined;
+
+    // Materialize dependency artifacts if configured
+    let materializedArtifacts: MaterializedArtifacts | undefined;
+    if (this.artifactMaterializer) {
+      materializedArtifacts = await this.artifactMaterializer.materialize(jobId);
+    }
+
+    // Create context for handler
+    const ctx = createJobContext<TInput>({
+      job,
+      eventAppender: this.eventAppender,
+      jobManager: this.jobManager,
+      signal: controller.signal,
+      onEvent,
+      artifactManager: this.artifactManager,
+      materializedArtifacts,
+    });
+
+    try {
+      // Emit start event
+      await this.eventAppender.append({
+        jobId,
+        type: 'started',
+        payload: { timestamp: new Date().toISOString() },
+      });
+
+      // Execute handler
+      const output = await handler(ctx);
+
+      // Mark job as completed
+      await this.jobManager.complete(jobId, output);
+
+      // Emit completion event
+      await this.eventAppender.append({
+        jobId,
+        type: 'completed',
+        payload: { output, timestamp: new Date().toISOString() },
+      });
+
+      // Fetch updated job
+      const completedJob = await this.jobManager.get(jobId);
+
+      return {
+        job: completedJob ?? job,
+        output,
+      };
+    } catch (error) {
+      // Handle abort
+      if (error instanceof JobAbortedError || controller.signal.aborted) {
+        await this.jobManager.cancel(jobId);
+
+        await this.eventAppender.append({
+          jobId,
+          type: 'cancelled',
+          payload: { timestamp: new Date().toISOString() },
+        });
+
+        const cancelledJob = await this.jobManager.get(jobId);
+
+        return {
+          job: cancelledJob ?? job,
+          error: 'Job was cancelled',
+        };
+      }
+
+      // Handle other errors
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      await this.jobManager.fail(jobId, errorMessage);
+
+      await this.eventAppender.append({
+        jobId,
+        type: 'failed',
+        payload: { error: errorMessage, timestamp: new Date().toISOString() },
+      });
+
+      const failedJob = await this.jobManager.get(jobId);
+
+      return {
+        job: failedJob ?? job,
+        error: errorMessage,
+      };
+    }
+  }
+}

package/src/job-worker.ts

@@ -0,0 +1,252 @@
+// ABOUTME: JobWorkerService for receiving dispatches from the coordinator
+// ABOUTME: Handles job execution and sends callbacks through relay or direct HTTP
+
+import type { JobManager, EventAppender, JobHandler } from './types.js';
+import { createJobContext } from './job-context.js';
+
+/**
+ * Dispatch payload received from the coordinator.
+ */
+export interface DispatchPayload {
+  jobId: string;
+  type: string;
+  attempt: number;
+  input: unknown;
+  traceId: string;
+  accountId: string;
+}
+
+/**
+ * Callback payload sent back to the coordinator.
+ */
+export interface CallbackPayload {
+  attempt: number;
+  success: boolean;
+  output?: unknown;
+  error?: string;
+}
+
+/**
+ * Options for creating a JobWorker.
+ */
+export interface JobWorkerOptions {
+  /** Shared secret for authenticating dispatches */
+  authSecret: string;
+
+  /** JobManager instance for job lifecycle */
+  jobManager: JobManager;
+
+  /** EventAppender instance for event streaming */
+  eventAppender: EventAppender;
+
+  /** Map of job types to handlers */
+  handlers: Record<string, JobHandler<unknown, unknown>>;
+
+  /** Coordinator callback URL (or relay URL) */
+  coordinatorCallbackUrl: string;
+
+  /** Whether to route callbacks through relay */
+  callbackViaRelay?: boolean;
+
+  /** Relay client ID (if callbackViaRelay is true) */
+  relayClientId?: string;
+
+  /** Optional: Fetch function for callbacks (for CF Worker compatibility) */
+  fetch?: typeof globalThis.fetch;
+}
+
+/**
+ * Result of handling a dispatch request.
+ */
+export interface DispatchResult {
+  accepted: boolean;
+  error?: string;
+}
+
+/**
+ * JobWorkerService interface for receiving coordinated job dispatches.
+ */
+export interface JobWorkerService {
+  /**
+   * Verify authorization header from coordinator.
+   */
+  verifyAuth(authHeader: string | undefined): boolean;
+
+  /**
+   * Handle a dispatch request from the coordinator.
+   * Returns immediately after accepting, processes job in background.
+   */
+  handleDispatch(
+    payload: DispatchPayload,
+    waitUntil?: (promise: Promise<unknown>) => void
+  ): Promise<DispatchResult>;
+
+  /**
+   * Get registered job types.
+   */
+  getJobTypes(): string[];
+}
+
+/**
+ * Creates a JobWorkerService instance for receiving coordinated dispatches.
+ */
+export function createJobWorkerService(options: JobWorkerOptions): JobWorkerService {
+  const {
+    authSecret,
+    jobManager,
+    eventAppender,
+    handlers,
+    coordinatorCallbackUrl,
+    callbackViaRelay = false,
+    relayClientId,
+    fetch: fetchFn = globalThis.fetch,
+  } = options;
+
+  const jobTypes = Object.keys(handlers);
+
+  async function sendCallback(
+    jobId: string,
+    payload: CallbackPayload
+  ): Promise<boolean> {
+    try {
+      let url: string;
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+        'X-Internal-Auth': authSecret,
+      };
+
+      if (callbackViaRelay && relayClientId) {
+        // Route through relay
+        url = `${coordinatorCallbackUrl}/relay-callback/${relayClientId}/${jobId}`;
+        headers['X-Callback-Type'] = 'job-result';
+      } else {
+        // Direct callback to coordinator
+        url = `${coordinatorCallbackUrl}/callback/${jobId}`;
+      }
+
+      const response = await fetchFn(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(payload),
+      });
+
+      if (!response.ok) {
+        console.error(
+          `[job-worker] Callback failed: ${response.status} ${await response.text()}`
+        );
+        return false;
+      }
+
+      return true;
+    } catch (error) {
+      console.error('[job-worker] Callback error:', error);
+      return false;
+    }
+  }
+
+  async function executeJob(dispatch: DispatchPayload): Promise<void> {
+    const handler = handlers[dispatch.type];
+    if (!handler) {
+      await sendCallback(dispatch.jobId, {
+        attempt: dispatch.attempt,
+        success: false,
+        error: `No handler for job type: ${dispatch.type}`,
+      });
+      return;
+    }
+
+    // Get the job from database
+    const job = await jobManager.get(dispatch.jobId);
+    if (!job) {
+      await sendCallback(dispatch.jobId, {
+        attempt: dispatch.attempt,
+        success: false,
+        error: `Job not found: ${dispatch.jobId}`,
+      });
+      return;
+    }
+
+    // Create job context
+    const abortController = new AbortController();
+    const ctx = createJobContext({
+      job,
+      eventAppender,
+      jobManager,
+      signal: abortController.signal,
+    });
+
+    try {
+      // Execute handler
+      const output = await handler(ctx);
+
+      // Send success callback
+      await sendCallback(dispatch.jobId, {
+        attempt: dispatch.attempt,
+        success: true,
+        output,
+      });
+    } catch (error) {
+      // Send failure callback
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      await sendCallback(dispatch.jobId, {
+        attempt: dispatch.attempt,
+        success: false,
+        error: errorMessage,
+      });
+    }
+  }
+
+  return {
+    verifyAuth(authHeader: string | undefined): boolean {
+      return authHeader === authSecret;
+    },
+
+    async handleDispatch(
+      payload: DispatchPayload,
+      waitUntil?: (promise: Promise<unknown>) => void
+    ): Promise<DispatchResult> {
+      // Validate payload
+      if (!payload.jobId || !payload.type) {
+        return { accepted: false, error: 'Invalid payload: jobId and type required' };
+      }
+
+      // Check handler exists
+      const handler = handlers[payload.type];
+      if (!handler) {
+        return { accepted: false, error: `No handler for job type: ${payload.type}` };
+      }
+
+      // Execute in background
+      const execution = executeJob(payload);
+
+      if (waitUntil) {
+        // CF Workers: use waitUntil to keep worker alive
+        waitUntil(execution);
+      } else {
+        // Node.js: fire and forget (or await if needed)
+        execution.catch((err) => {
+          console.error('[job-worker] Execution error:', err);
+        });
+      }
+
+      return { accepted: true };
+    },
+
+    getJobTypes(): string[] {
+      return jobTypes;
+    },
+  };
+}
+
+/**
+ * Error thrown by JobWorker operations.
+ */
+export class JobWorkerError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string
+  ) {
+    super(message);
+    this.name = 'JobWorkerError';
+  }
+}