@mark1russell7/service 0.5.0 → 0.5.2

package/build/index.d.ts

@@ -1,8 +1,8 @@
 import { a as backoffDelay, i as backoffBand, n as DelayBand, o as backoffProblems, r as Jitter, t as Backoff } from "./backoff-B-jGWVDm.js";
 import { a as realClock, i as platformClock, n as Clock, r as PlatformClockOptions, t as Cancel } from "./clock-D-38uH_z.js";
 import { Heartbeat, HeartbeatOptions, detectionTime, heartbeat } from "./heartbeat.js";
-import { $ as heartbeatDetection, A as LifecycleEvent, B as Gate, C as ProbeAnswer, D as Outcome, E as CheckFn, F as CooperativeFloor, G as Transport, H as RepeatSignal, I as Coupling, J as Span, K as FailsBy, L as Dependency, M as Recorder, N as Check, O as Result, P as Controller, Q as failSpan, R as ExitCodes, S as HealthVerdict, T as StartOptions, U as ServiceDescription, V as Phase, W as Step, X as asDebounce, Y as Timing, Z as asWindow, _ as RequestOptions, _t as Operation, a as PhaseContext, at as ExitSignal, b as CheckVerdict, c as STAGES, ct as PROCESS_TRIGGERS, d as TransportImpl, dt as ProcessTrigger, et as recoverSpan, f as cooperativeAbortAt, ft as isExitCode, g as RequestFn, gt as Idempotency, h as RequestEvent, ht as processPortOf, i as LifecycleState, it as EXIT_SIGNALS, j as MachineName, l as ShutdownOptions, lt as ProcessHost, m as RequestEnd, mt as nodeProcess, n as HealthServer, nt as RoutePattern, o as PhaseWork, ot as ExitTrigger, p as stageRank, pt as isExitSignal, q as Poll, r as Lifecycle, rt as RouteRequest, s as RunOptions, st as HostStream, t as DependencyHandle, tt as OperationOf, u as Stage, ut as ProcessPort, v as RequestStream, vt as mayReissue, w as ProbeKind, x as Health, y as RequestWork, z as FORMAT } from "./lifecycle-DIj4YGmO.js";
-import { a as WatchdogSpec, c as Profile, d as kubernetes, f as localDev, i as Watchdog, l as daemon, n as ServiceBuilder, o as watchdog, r as service, s as PodTiming, t as ControllerBuilder, u as ephemeral } from "./builder-B_q-JeW8.js";
+import { $ as failSpan, A as LifecycleEvent, B as Gate, C as ProbeAnswer, Ct as Operation, D as Outcome, E as CheckFn, F as CooperativeFloor, G as Step, H as Phase, I as Coupling, J as Poll, K as Transport, L as Dependency, M as Recorder, N as Check, O as Result, P as Controller, Q as asWindow, R as ExitCodes, S as HealthVerdict, St as Idempotency, T as StartOptions, U as RepeatSignal, V as MessageTrigger, W as ServiceDescription, X as Timing, Y as Span, Z as asDebounce, _ as RequestOptions, _t as isExitSignal, a as PhaseContext, at as EXIT_SIGNALS, b as CheckVerdict, bt as nodeProcess, c as STAGES, ct as ExitTrigger, d as TransportImpl, dt as PROCESS_TRIGGERS, et as heartbeatDetection, f as cooperativeAbortAt, ft as ProcessHost, g as RequestFn, gt as isExitCode, h as RequestEvent, ht as embeddedProcess, i as LifecycleState, it as RouteRequest, j as MachineName, l as ShutdownOptions, lt as HostStream, m as RequestEnd, mt as ProcessTrigger, n as HealthServer, nt as OperationOf, o as PhaseWork, ot as EmbeddedProcess, p as stageRank, pt as ProcessPort, q as FailsBy, r as Lifecycle, rt as RoutePattern, s as RunOptions, st as ExitSignal, t as DependencyHandle, tt as recoverSpan, u as Stage, ut as MessageShape, v as RequestStream, vt as isMessageShape, w as ProbeKind, wt as mayReissue, x as Health, xt as processPortOf, y as RequestWork, yt as matchesMessage, z as FORMAT } from "./lifecycle-DjEpgpRk.js";
+import { a as WatchdogSpec, c as Profile, d as kubernetes, f as localDev, i as Watchdog, l as daemon, n as ServiceBuilder, o as watchdog, r as service, s as PodTiming, t as ControllerBuilder, u as ephemeral } from "./builder-BzjhWk2E.js";
 import { Extent, Quantity } from "@mark1russell7/quantity";
 import { replay } from "@mark1russell7/algebra/replay";
 import { Machine } from "@mark1russell7/algebra";
@@ -86,7 +86,8 @@ export declare const verdictOf: (rule: Rule, bind: Binding, evaluated: readonly
  * The scenario binds the symbols of the platform (preStop, grace, the probes of the kubelet,
  * propagation) and of each dependency (its failover time, the idle close of its server). Thus the
  * service gives the inequalities, and the scenario gives the values. A rule about a client
- * applies one time for each dependency.
+ * applies one time for each dependency. A rule about a consumer applies one time for each consumer
+ * and each worker.
  */
 /** A scenario gives the values of the platform and of each dependency, by the `symbol@hop` of the law. */
 interface Scenario {
@@ -103,6 +104,8 @@ interface Scenario {
   };
   /** These are the values of each dependency, by its name: failover_time@dependency, server_idle_close@server. */
   readonly dependencies?: Readonly<Record<string, Readonly<Record<string, Extent>>>> | undefined;
+  /** These are the values of the source of each consumer and worker, by its name and by the `symbol@hop` of the law: lease_duration@broker. */
+  readonly transports?: Readonly<Record<string, Readonly<Record<string, Extent>>>> | undefined;
 }
 /** A finding is the verdict of one rule for one scope: the service, or the client of a dependency. */
 interface Finding {
@@ -125,12 +128,246 @@ export declare const serviceBindings: (svc: ServiceDescription, scenario: Scenar
 /** This identifier is the rule of the findings about a field that the declaration does not give. */
 export declare const DECLARATION_RULE = "declaration";
 /**
- * This function applies each service rule to a declaration and a scenario: one time for the
- * service, and one time for each client. It also gives a finding for each necessary field that the
- * description does not give (`DECLARATION_RULE`).
+ * This function applies each service rule to a declaration and a scenario. A rule applies one time
+ * for the service, for each client, or for each consumer and worker. The function also gives a
+ * finding for each necessary field that the description does not give (`DECLARATION_RULE`).
  */
 export declare const lint: (svc: ServiceDescription, scenario: Scenario, rules: readonly Rule[]) => Finding[];
 //#endregion
+//#region src/units.d.ts
+/**
+ * A unit request names the route of each unit of work in the request tracking of the service. Then
+ * the service admits, counts, drains and cuts each unit as it does each request (`life.request`).
+ * The controller declares the route, thus its idempotency tells if a cut unit can go again.
+ */
+interface UnitRequest<U> {
+  /** This name is the controller that declares the route. */
+  readonly controller: string;
+  /** This name is the route of each unit, or a function that gives it from the unit. A route can match a route pattern. */
+  readonly route: string | ((unit: U) => string);
+  /** This function gives the detail of a unit, for the function of a route pattern. */
+  readonly detail?: ((unit: U) => unknown) | undefined;
+}
+//#endregion
+//#region src/worker.d.ts
+/**
+ * These are the knobs of a worker loop, by the names of the ordering law where the law has them.
+ * The loop has no defaults, thus each knob is necessary. A bound that nobody gives is "infinite".
+ */
+interface WorkerKnobs {
+  /**
+   * This time is the sleep of a lane, from the end of one iteration to the start of the next. A
+   * time without a bound starts the next iteration only at `wake()`.
+   */
+  readonly worker_sleep: Extent;
+  /**
+   * This time is the most that one iteration can take. At it, the loop aborts the signal of the
+   * iteration, and a throw after it is a failure. The law reads it as `unit_processing_time@consumer` (O20).
+   */
+  readonly unit_processing_time: Extent;
+  /** This time is the delay after the first failure in sequence. The delay is two times longer after each failure, with a jitter up to this time. */
+  readonly retry_base: Quantity;
+  /** This time is the most that one delay can be, before its jitter. */
+  readonly retry_cap: Quantity;
+  /** This time bounds the close: the end of the iterations after their abort, and then the teardown. */
+  readonly close_bound: Quantity;
+  /** This count (the unit `count`) is the number of lanes. Each lane does its iterations one at a time. */
+  readonly concurrency: Quantity;
+  /** The other knobs go to the declaration, for example `lease_duration@broker`. The loop does not read them. */
+  readonly [knob: string]: Extent;
+}
+/** An iteration context is what the loop gives each iteration. */
+interface IterationContext<S> {
+  /** This signal aborts at the cooperative abort of the drain, at the bound of the iteration, and at the close. */
+  readonly signal: AbortSignal;
+  /** This signal aborts when the intake stops. A long iteration can end at it in its own way. */
+  readonly intake: AbortSignal;
+  /** This value is the state that the setup gave, or undefined without a setup. */
+  readonly state: S;
+  /** This number is the lane of the iteration, from 0. */
+  readonly lane: number;
+  /** This count is the number of failures in sequence of the lane before this iteration. */
+  readonly failures: number;
+  /** This lifecycle is the lifecycle that the loop got at its start. */
+  readonly life: Lifecycle;
+}
+/** These options make a worker loop. Each function can give a promise. */
+interface WorkerLoopOptions<S> {
+  /** This function makes the state of the loop at its start, for example a connection. Its signal is the signal of the service. */
+  readonly setup?: ((signal: AbortSignal) => S | PromiseLike<S>) | undefined;
+  /**
+   * This function does one iteration. When it gives `"more"`, the next iteration of its lane starts
+   * after a zero sleep on the clock. A throw is a failure, and the lane then waits its backoff.
+   */
+  readonly iteration: (context: IterationContext<S>) => unknown;
+  /** This function releases the state at the close. It occurs each time that the setup started, with undefined after a failed setup. */
+  readonly teardown?: ((state: S | undefined) => void | PromiseLike<void>) | undefined;
+  /** This clock is the clock of the lifecycle. The sleeps, the backoffs and the bounds use it. The default is `realClock`. */
+  readonly clock?: Clock | undefined;
+  /** This function gives the random numbers of the jitter, from 0 up to 1. The default is `Math.random`. */
+  readonly random?: (() => number) | undefined;
+  /**
+   * This route puts each iteration through `life.request`: the service then admits it, counts it,
+   * drains it and can cut it. The unit of a route function is the number of the lane.
+   */
+  readonly request?: UnitRequest<number> | undefined;
+  /** This function receives each failure, with the count of failures in sequence of its lane. A refusal of the service is a failure too. */
+  readonly onError?: ((error: unknown, failures: number) => void) | undefined;
+}
+/** A worker loop is a transport of the lifecycle whose work is a loop of iterations (S6 A10). */
+interface WorkerLoop extends TransportImpl {
+  /** These knobs go to the declaration of the worker: `svc.worker(name, loop.knobs, loop)`. */
+  readonly knobs: WorkerKnobs;
+  /**
+   * This method ends the sleep of each lane at once, for example when new work is ready. It does
+   * not end a backoff. It gives false after the intake stops.
+   */
+  wake(): boolean;
+  /** This method gives the problems of the knobs in a declaration: the close bound and the bound of an iteration against the caps. */
+  problems(description: ServiceDescription): string[];
+}
+/**
+ * This function makes a worker loop as a transport (S6 A10). It has a setup, an iteration and a
+ * teardown, and each lane does its iterations one at a time.
+ * - The start does the setup. A failed setup gets its teardown, and the start throws.
+ * - The first iteration of each lane comes after the startup ends. Each sleep and each backoff is on the clock.
+ * - `stopIntake` starts no new iteration, and it ends each sleep and each backoff.
+ * - `drain` waits for each iteration in flight until the deadline, and gives it the cooperative
+ *   abort. A throw after that abort is not a failure.
+ * - `close` aborts each iteration, waits for its end, and does the teardown, all in `close_bound`.
+ */
+export declare const workerLoop: <S = undefined>(knobs: WorkerKnobs, options: WorkerLoopOptions<S>) => WorkerLoop;
+//#endregion
+//#region src/queue.d.ts
+/**
+ * These are the knobs of a queue drain, by the names of the ordering law where the law has them.
+ * The drain has no defaults, thus each knob is necessary. A bound that nobody gives is "infinite".
+ */
+interface QueueKnobs {
+  /** This time is the wait after a take that gives no job, before the next take. A time without a bound waits for `wake()`. */
+  readonly queue_poll_interval: Extent;
+  /**
+   * This time is the most that one job can take. At it, the drain aborts the signal of the job, and
+   * a throw after it is a failure. The law reads it as `unit_processing_time@consumer` (O20).
+   */
+  readonly unit_processing_time: Extent;
+  /** This time is the delay after the first failed take in sequence, or after a refusal of the service. The delay is two times longer after each one. */
+  readonly retry_base: Quantity;
+  /** This time is the most that one delay can be, before its jitter. */
+  readonly retry_cap: Quantity;
+  /** This time bounds the close: the end of the jobs after their abort, and then the close of the source. */
+  readonly close_bound: Quantity;
+  /** This count (the unit `count`) is the most jobs in flight at one time. A count without a bound takes each job that comes. */
+  readonly concurrency: Extent;
+  /** The other knobs go to the declaration, for example `lease_duration@broker`. The drain does not read them. */
+  readonly [knob: string]: Extent;
+}
+/**
+ * A job source gives the jobs of a queue drain:
+ * - A function takes the next job, or gives null when no job is ready. Its signal aborts when the intake stops.
+ * - An async iterable gives the jobs in sequence. The drain asks for the next job only when it has a free slot.
+ *   At the stop of the intake, the drain ends the iterator through `return()`.
+ */
+type JobSource<J> = ((signal: AbortSignal) => J | null | undefined | PromiseLike<J | null | undefined>) | AsyncIterable<J>;
+/**
+ * A job action is what the drain does with a job that failed:
+ * - `requeue`: the job goes back on the queue.
+ * - `reject`: the job leaves the queue without a success, for example to the dead-letter route of the queue.
+ * - `ack`: the job leaves the queue, as a poison message does.
+ */
+type JobAction = "requeue" | "reject" | "ack";
+/** A job failure is a job whose handler failed, with the count of its deliveries, 1 at the first. */
+interface JobFailure<J> {
+  readonly job: J;
+  readonly error: unknown;
+  readonly delivery: number;
+}
+/** A redelivery policy gives the action for a job that failed. The queue declares it, and it has no default (S6 A11). */
+type RedeliveryPolicy<J> = (failure: JobFailure<J>) => JobAction;
+/**
+ * A requeue cause tells why a job goes back on the queue:
+ * - `failed`: the redelivery policy sent it back after a failure.
+ * - `unstarted`: the drain took the job and did not start it, because its intake stopped or the service refused it.
+ * - `cut`: the shutdown cut the job, and its route declares that it can go again.
+ */
+type RequeueCause = "failed" | "unstarted" | "cut";
+/** A job settle is how the drain tells the queue the end of each job. Each function can give a promise. */
+interface JobSettle<J> {
+  /** This function removes the job from the queue: a success, or the action `ack`. */
+  ack(job: J): void | PromiseLike<void>;
+  /** This function puts the job back on the queue, or hands it back to the queue at the stop. */
+  requeue(job: J, cause: RequeueCause): void | PromiseLike<void>;
+  /** This function removes the job from the queue without a success: the action `reject`, or a cut job that cannot go again. */
+  reject(job: J, error: unknown): void | PromiseLike<void>;
+  /**
+   * This function gives the count of deliveries of a job from the queue, 1 at the first. The queue
+   * knows it, for example `x-delivery-count` of RabbitMQ or `ApproximateReceiveCount` of SQS. A
+   * queue in memory counts for itself. The drain has no default, because a broker gives a new object at each delivery.
+   */
+  delivery(job: J): number;
+}
+/** A job context is what the drain gives the handler of each job. */
+interface JobContext {
+  /** This signal aborts at the cooperative abort of the drain, at the bound of the job, and at the close. */
+  readonly signal: AbortSignal;
+  /** This signal aborts when the intake stops. */
+  readonly intake: AbortSignal;
+  /** This count is the delivery of the job, 1 at the first. */
+  readonly delivery: number;
+  /** This lifecycle is the lifecycle that the drain got at its start. */
+  readonly life: Lifecycle;
+}
+/** These options make a queue drain. Each function can give a promise. */
+interface QueueDrainOptions<J> {
+  readonly source: JobSource<J>;
+  /** This function does one job. A throw is a failure, and the redelivery policy then gives its action. */
+  readonly handle: (job: J, context: JobContext) => unknown;
+  readonly settle: JobSettle<J>;
+  /** This policy gives the action for each failed job. `redeliverOnce` gives the policy of S6 A11. */
+  readonly redelivery: RedeliveryPolicy<J>;
+  /** This function closes the source at the close, after the jobs end: for example, it closes a channel. */
+  readonly close?: (() => void | PromiseLike<void>) | undefined;
+  /** This clock is the clock of the lifecycle. The polls, the backoffs and the bounds use it. The default is `realClock`. */
+  readonly clock?: Clock | undefined;
+  /** This function gives the random numbers of the jitter, from 0 up to 1. The default is `Math.random`. */
+  readonly random?: (() => number) | undefined;
+  /**
+   * This route puts each job through `life.request`: the service then admits it, counts it, drains
+   * it and can cut it. The idempotency of the route tells if a cut job goes back on the queue.
+   */
+  readonly request?: UnitRequest<J> | undefined;
+  /**
+   * This function receives each failure: of a take, of a job, of a settle and of a policy. It also
+   * receives the end of a source while the intake is open. The job is undefined for a take and for that end.
+   */
+  readonly onError?: ((error: unknown, job: J | undefined) => void) | undefined;
+}
+/** A queue drain is a transport of the lifecycle whose work is the jobs of a queue (S6 A11). */
+interface QueueDrain extends TransportImpl {
+  /** These knobs go to the declaration of the consumer: `svc.consumer(name, drain.knobs, drain)`. */
+  readonly knobs: QueueKnobs;
+  /** This method ends the wait of a poll at once, for example when a job comes. It gives false after the intake stops. */
+  wake(): boolean;
+  /** This method gives the problems of the knobs in a declaration: the close bound and the bound of a job against the caps. */
+  problems(description: ServiceDescription): string[];
+}
+/**
+ * This function gives the redelivery policy of S6 A11. A poison message gets `ack`. Each other job
+ * goes back on the queue after its first failure, one time. After a later failure, `then` gives the
+ * action: the declared policy of the queue.
+ */
+export declare const redeliverOnce: <J>(then: JobAction | RedeliveryPolicy<J>, poison?: (error: unknown, job: J) => boolean) => RedeliveryPolicy<J>;
+/**
+ * This function makes a queue drain as a transport (S6 A11). One taker takes the jobs from the
+ * source while a slot is free, and each job operates in its slot.
+ * - A success gets `ack`. A failure gets the action of the redelivery policy.
+ * - `stopIntake` takes no new job, and a job that the drain took and did not start goes back (`requeue`, `unstarted`).
+ * - `drain` waits for each job in flight until the deadline, and gives it the cooperative abort.
+ * - `close` aborts each job, waits for its end, and closes the source, all in `close_bound`. A job
+ *   that does not end in the bound gets `reject`.
+ */
+export declare const queueDrain: <J>(knobs: QueueKnobs, options: QueueDrainOptions<J>) => QueueDrain;
+//#endregion
 //#region src/machines.d.ts
 /**
  * The startup gate opens one time. The lifecycle moves it from `closed` to `starting` while its
@@ -171,5 +408,5 @@ export declare const drainMachine: (description: ServiceDescription) => Machine;
 /** These are the static machines of the runtime, by the name that their events carry. */
 export declare const MACHINES: Readonly<Record<Exclude<MachineName, "drain" | "client">, Machine>>;
 //#endregion
-export { type Backoff, type Binding, type Bound, type Cancel, type Check, type CheckFn, type CheckVerdict, type Clock, type Controller, type ControllerBuilder, type CooperativeFloor, type Coupling, type DelayBand, type Dependency, type DependencyHandle, EXIT_SIGNALS, type Evaluated, type ExitCodes, type ExitSignal, type ExitTrigger, FORMAT, type FailsBy, type Finding, type Gate, type Health, type HealthServer, type HealthVerdict, type Heartbeat, type HeartbeatOptions, type HostStream, type Idempotency, type Inequality, type Jitter, type Lifecycle, type LifecycleEvent, type LifecycleState, type MachineName, type Operation, type OperationOf, type Outcome, PROCESS_TRIGGERS, type Phase, type PhaseContext, type PhaseWork, type PlatformClockOptions, type PodTiming, type Poll, type ProbeAnswer, type ProbeKind, type ProcessHost, type ProcessPort, type ProcessTrigger, type Profile, type Recorder, type RepeatSignal, type RequestEnd, type RequestEvent, type RequestFn, type RequestOptions, type RequestStream, type RequestWork, type Result, type RoutePattern, type RouteRequest, type Rule, type RunOptions, STAGES, type Scenario, type ServiceBuilder, type ServiceDescription, type ShutdownOptions, type Side, type Span, type Stage, type StartOptions, type Step, type Term, type Timing, type Transport, type TransportImpl, type Verdict, type Watchdog, type WatchdogSpec, asDebounce, asWindow, backoffBand, backoffDelay, backoffProblems, cooperativeAbortAt, daemon, detectionTime, ephemeral, failSpan, heartbeat, heartbeatDetection, isExitCode, isExitSignal, kubernetes, localDev, mayReissue, nodeProcess, platformClock, processPortOf, realClock, recoverSpan, replay, service, stageRank, watchdog };
+export { type Backoff, type Binding, type Bound, type Cancel, type Check, type CheckFn, type CheckVerdict, type Clock, type Controller, type ControllerBuilder, type CooperativeFloor, type Coupling, type DelayBand, type Dependency, type DependencyHandle, EXIT_SIGNALS, type EmbeddedProcess, type Evaluated, type ExitCodes, type ExitSignal, type ExitTrigger, FORMAT, type FailsBy, type Finding, type Gate, type Health, type HealthServer, type HealthVerdict, type Heartbeat, type HeartbeatOptions, type HostStream, type Idempotency, type Inequality, type IterationContext, type Jitter, type JobAction, type JobContext, type JobFailure, type JobSettle, type JobSource, type Lifecycle, type LifecycleEvent, type LifecycleState, type MachineName, type MessageShape, type MessageTrigger, type Operation, type OperationOf, type Outcome, PROCESS_TRIGGERS, type Phase, type PhaseContext, type PhaseWork, type PlatformClockOptions, type PodTiming, type Poll, type ProbeAnswer, type ProbeKind, type ProcessHost, type ProcessPort, type ProcessTrigger, type Profile, type QueueDrain, type QueueDrainOptions, type QueueKnobs, type Recorder, type RedeliveryPolicy, type RepeatSignal, type RequestEnd, type RequestEvent, type RequestFn, type RequestOptions, type RequestStream, type RequestWork, type RequeueCause, type Result, type RoutePattern, type RouteRequest, type Rule, type RunOptions, STAGES, type Scenario, type ServiceBuilder, type ServiceDescription, type ShutdownOptions, type Side, type Span, type Stage, type StartOptions, type Step, type Term, type Timing, type Transport, type TransportImpl, type UnitRequest, type Verdict, type Watchdog, type WatchdogSpec, type WorkerKnobs, type WorkerLoop, type WorkerLoopOptions, asDebounce, asWindow, backoffBand, backoffDelay, backoffProblems, cooperativeAbortAt, daemon, detectionTime, embeddedProcess, ephemeral, failSpan, heartbeat, heartbeatDetection, isExitCode, isExitSignal, isMessageShape, kubernetes, localDev, matchesMessage, mayReissue, nodeProcess, platformClock, processPortOf, realClock, recoverSpan, replay, service, stageRank, watchdog };
 //# sourceMappingURL=index.d.ts.map