`Worker` contract

(no submodules)

abstract-metrics — abstract-metrics.ts carries the pure functions and the small accumulator used by AbstractWorker to track success/fa…
abstract — (no submodules)- local — (no submodules) - local — (no submodules)- worker — (no submodules)- abstract-metrics — abstract-metrics.ts carries the…
abstract-metrics — abstract-metrics.ts carries the pure functions and the small accumulator used by AbstractWorker to track success/fa…
abstract — (no submodules)- local — (no submodules)- local — (no submodules)- worker — (no submodules)- abstract-metrics — abstract-metrics.ts carries the pure functions and the small accumulator used by AbstractWorker to track success/fa…
abstract — (no submodules)- local — (no submodules)- local — (no submodules)- worker — (no submodules)- abstract-metrics — `abstract…
abstract-metrics — abstract-metrics.ts carries the pure functions and the small accumulator used by AbstractWorker to track success/fa…
abstract — (no submodules)- local — (no submodules)- local — (no submodules)- worker — (no submodules)- abstract-metrics — abstract-metrics.ts carries th…
abstract-metrics — abstract-metrics.ts carries the pure functions and the small accumulator used by AbstractWorker to track success/fa…
abstract — (no submodules)- local — (no submodules) - local — (no submodules)- worker — (no submodules)

Purpose

Worker is the structural interface every distribution-tier executor implements. It describes lifecycle (start, stop), task execution (executeTask), health probing (getHealth, canAcceptTask), and introspection (getInfo). Concrete workers (LocalWorker, RemoteWorker from the HTTP plugin, WorkerThreadWorker from the worker-thread plugin) extend AbstractWorker, but downstream code should program against Worker so transport choices stay swappable.

Features

id, capacity, weight, status: WorkerStatusValue, activeTasks fields kept in sync by the worker base class.
executeTask<I, O>(task, input, signal?): Promise<O> — preserves caller's <I, O> generics end-to-end.
getHealth(signal?): Promise<WorkerHealth> — pluggable health probe; the abstract base returns synthesised metrics, subclasses override with real measurements.
start(signal?), stop(force?, signal?) — idempotent lifecycle.
canAcceptTask(): boolean — used by load-balancing strategies to filter the candidate pool.
getInfo(): WorkerInfo — snapshot of identity, type, capacity, weight, status, active count, optional startedAt / lastHealthCheck / lastHealthStatus / capabilities.
WorkerStatusSchema, WorkerHealthSchema, WorkerInfoSchema — Zod schemas at every public boundary.

Usage: Basic Example

import {
    type Worker,
    WorkerStatus,
    WorkerHealthSchema,
} from "@suaveplan/queue-distribution/worker/worker";

function printWorker(worker: Worker): void {
    const info = worker.getInfo();
    console.log(`${info.type}/${info.id} — ${info.status}, ${info.activeTasks}/${info.capacity}`);
}

async function probeHealth(worker: Worker): Promise<boolean> {
    const health = await worker.getHealth();
    WorkerHealthSchema.parse(health); // validate at the boundary
    return health.isHealthy && worker.status !== WorkerStatus.UNHEALTHY;
}

Usage: Advanced Example

Workers can carry arbitrary capabilities — exposed via getInfo().capabilities — that strategies and supervisors inspect to make routing decisions.

import {
    type Worker,
    WorkerInfoSchema,
} from "@suaveplan/queue-distribution/worker/worker";

function findGpuWorkers(workers: readonly Worker[]): Worker[] {
    return workers.filter((worker) => {
        const info = WorkerInfoSchema.parse(worker.getInfo());
        return info.capabilities?.gpu === true && info.status === "ONLINE";
    });
}

API Reference

interface Worker — fields and methods above.
const WorkerStatus — frozen literal map (ONLINE / BUSY / OFFLINE / UNHEALTHY).
type WorkerStatusValue — union of the four states.
const WorkerStatusSchema: z.ZodEnum — accepts only the four states.
interface WorkerHealth — isHealthy: boolean + WorkerHealthMetrics.
interface WorkerHealthMetrics — cpu, memory, tasksFailed, tasksSucceeded, responseTime, indexed extras.
const WorkerHealthSchema: z.ZodType<WorkerHealth>.
interface WorkerInfo — identity + capacity + weight + status + active count + optional timestamps + optional health snapshot + optional capabilities map.
const WorkerInfoSchema: z.ZodType<WorkerInfo> — capacity must be a positive integer; weight non-negative; activeTasks non-negative integer.

Implementation Notes

The interface mutates the worker's status and activeTasks fields directly rather than threading them through accessors because the AbstractWorker base maintains them as the source of truth, and load-balancing strategies access them in hot paths where allocator pressure matters. getInfo() returns a fresh structural snapshot every call — callers must not mutate it. Schemas exist so transport-specific subclasses (e.g. a deserialised remote worker payload) can validate the shape they construct before publishing it to the pool.

6.4 KiB Raw Blame History

Worker contract