@smthrs/triggers 0.0.0-stage → 1.0.0-rc.3

package/dist/cjs/Scheduler.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Durable, Clock-driven trigger scheduling.
+ *
+ * @see packages/smithers/agent/triggers/docs/api.md
+ *
+ * @since 0.1.0
+ */
+import * as Control from "@smthrs/control/Control";
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as Scope from "effect/Scope";
+import { TriggerError } from "./TriggerError.ts";
+import { TriggerStore } from "./TriggerStore.ts";
+/**
+ * Arguments used to launch one scheduled flow.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface StartInput {
+    readonly flowId: string;
+    readonly input: unknown;
+    readonly idempotencyKey: string;
+}
+/**
+ * What the runtime says about one scheduled run.
+ *
+ * `active` keeps the monitor polling. `completed` is the only state recorded as
+ * a completed occurrence; `failed`, `cancelled`, and `missing` (the runtime has
+ * no record of the run) are recorded as `failed` with the state in the error.
+ *
+ * @category models
+ * @since 1.0.0-rc.1
+ */
+export type RunState = "active" | "completed" | "failed" | "cancelled" | "missing";
+/**
+ * Runtime operations required by the scheduler.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface RunnerService {
+    readonly start: (input: StartInput) => Effect.Effect<string, TriggerError>;
+    readonly inspect: (runId: string) => Effect.Effect<RunState, TriggerError>;
+    readonly cancel: (runId: string) => Effect.Effect<void, TriggerError>;
+}
+declare const Runner_base: Context.ServiceClass<Runner, "flows/triggers/Scheduler/Runner", RunnerService>;
+/**
+ * Injectable scheduled-run launcher.
+ *
+ * Constructed with {@link makeRunner}, {@link makeNoopRunner}, or
+ * {@link layerNoopRunner}; the tag itself carries no constructors, so there is
+ * one spelling of each and the module's own `make`/`makeNoop` can only mean
+ * the scheduler.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class Runner extends Runner_base {
+}
+/**
+ * Constructs a scheduled-run launcher.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeRunner: (implementation: RunnerService) => RunnerService;
+/**
+ * Constructs a launcher that returns the idempotency key as a terminal run.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeNoopRunner: (overrides?: Partial<RunnerService>) => RunnerService;
+/**
+ * Provides the terminal no-op launcher.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoopRunner: (overrides?: Partial<RunnerService>) => Layer.Layer<Runner>;
+/**
+ * How many times a parked plan is re-offered before the launch is abandoned.
+ *
+ * The delay doubles from one second, so the eighth attempt lands a little over
+ * two minutes in. A plan nobody approves used to be re-offered once a second
+ * for the life of the scope while the launch reservation behind it expired.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const parkedAttempts = 8;
+/**
+ * Runner layer backed by the authoritative Control plan/run/list/cancel API.
+ *
+ * A parked plan waits for approval and retries the same idempotent run request
+ * a bounded number of times; this adapter never approves it or reconstructs an
+ * execution envelope.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerControlRunner: Layer.Layer<Runner, never, Control.Control>;
+/**
+ * Scheduler timing configuration.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+    readonly pollInterval?: Duration.Input | undefined;
+    readonly runPollInterval?: Duration.Input | undefined;
+    /**
+     * How many triggers one tick processes at the same time. Defaults to
+     * {@link defaultConcurrency}. A tick never waits for a launch: the claim is
+     * durable and the launch runs on its own fiber.
+     */
+    readonly concurrency?: number | undefined;
+    /**
+     * How long one `Runner.start` may take before the launch is abandoned with
+     * `runner_timeout`. Defaults to four minutes: above the Control adapter's
+     * bounded parked-approval retries and below the five-minute reservation
+     * lease, so an abandoned launch still owns its reservation and re-arms the
+     * occurrence itself. The next tick retries it under the same idempotency
+     * key. A deadline above the lease is allowed; a start that answers after
+     * its lease is reconciled as a late launch.
+     */
+    readonly startTimeout?: Duration.Input | undefined;
+    /**
+     * How long one `Runner.inspect` may take. Defaults to thirty seconds. A
+     * timeout is an inspection failure: the monitor retries and then detaches,
+     * retaining the durable owner.
+     */
+    readonly inspectTimeout?: Duration.Input | undefined;
+    /**
+     * How long one `Runner.cancel` may take. Defaults to thirty seconds. A
+     * timeout fails the supersede, which restores the prior run as active and
+     * queues the replacement.
+     */
+    readonly cancelTimeout?: Duration.Input | undefined;
+    /**
+     * The name this scheduler records its heartbeat under, so a listing can say
+     * which host last polled the store. Defaults to {@link defaultHost}.
+     */
+    readonly host?: string | undefined;
+    /**
+     * How long settled fire ledger rows are kept. Defaults to
+     * {@link defaultFireRetention}. A tick deletes older settled rows through
+     * `TriggerStore.pruneFires` at most once an hour; a failed prune is logged
+     * and the tick goes on.
+     */
+    readonly fireRetention?: Duration.Input | undefined;
+}
+/**
+ * The heartbeat host name a scheduler records under when its options name
+ * none.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultHost = "local";
+/**
+ * How many triggers one tick processes at the same time when its options name
+ * no `concurrency`.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultConcurrency = 4;
+/**
+ * How long settled fire ledger rows are kept when the options name no
+ * `fireRetention`: thirty days.
+ *
+ * @category constants
+ * @since 1.0.0-rc.1
+ */
+export declare const defaultFireRetention: Duration.Duration;
+/**
+ * Histogram boundaries, in milliseconds, of `smithers.triggers.tick_duration_ms`
+ * and `smithers.triggers.launch_duration_ms`.
+ *
+ * @category constants
+ * @since 1.0.0-rc.1
+ */
+export declare const durationBoundaries: ReadonlyArray<number>;
+/**
+ * Scheduler operations.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    readonly runOnce: Effect.Effect<void, TriggerError>;
+}
+declare const Scheduler_base: Context.ServiceClass<Scheduler, "flows/triggers/Scheduler", Service>;
+/**
+ * The live trigger scheduler.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class Scheduler extends Scheduler_base {
+}
+/** Stable Control request identity for one manual or scheduled occurrence.
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const idempotencyKey: (triggerId: string, occurrence: number) => string;
+/**
+ * Constructs a scheduler service in the current Scope.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: (options?: Options) => Effect.Effect<Service, TriggerError, Runner | Scope.Scope | TriggerStore>;
+/**
+ * Constructs a scheduler that performs no work.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeNoop: () => Service;
+/**
+ * Scoped scheduler layer. Its supervisor sleeps only through the Effect Clock,
+ * so scope closure interrupts the poll loop and detaches every run monitor.
+ * Detaching is all it does: the runs themselves are durable and keep going,
+ * and the next incarnation re-attaches to them from the store.
+ *
+ * The loop recovers from the whole cause rather than the typed error alone. A
+ * defect raised anywhere under a tick, which `Effect.catch` by contract leaves
+ * alone, would otherwise kill this fiber and stop every trigger in the process
+ * with nothing written down.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: (options?: Options) => Layer.Layer<Scheduler, TriggerError, Runner | TriggerStore>;
+/**
+ * Provides an inert scheduler without allocating a supervisor fiber.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: Layer.Layer<Scheduler>;
+export {};
+//# sourceMappingURL=Scheduler.d.ts.map

package/dist/cjs/Scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scheduler.d.ts","sourceRoot":"","sources":["../../src/Scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,OAAO,MAAM,yBAAyB,CAAA;AAIlD,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAKrC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAI1C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAML,YAAY,EACb,MAAM,mBAAmB,CAAA;AAE1B;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAA;AAElF;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IAC1E,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAA;IAC1E,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;CACtE;;AAED;;;;;;;;;;GAUG;AACH,qBAAa,MAAO,SAAQ,WAA2E;CAAG;AAE1G;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,gBAAgB,aAAa,KAAG,aAA0C,CAAA;AAErG;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,YAAW,OAAO,CAAC,aAAa,CAAM,KAAG,aAMpE,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAC1B,YAAW,OAAO,CAAC,aAAa,CAAM,KACrC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAqD,CAAA;AAkE1E;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,IAAI,CAAA;AA4C/B;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAgD1E,CAAA;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;IAClD,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;IACrD;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzC;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;IAClD;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;IACpD;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;IACnD;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;CACpD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,UAAU,CAAA;AAElC;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,QAA4B,CAAA;AAIxE;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,MAAM,CAA6C,CAAA;AAmClG;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;CACpD;;AAED;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,cAAiE;CAAG;AAEnG;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,WAAW,MAAM,EAAE,YAAY,MAAM,KAAG,MACjB,CAAA;AA8BtD;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GACf,UAAS,OAAY,KACpB,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,KAAK,CAAC,KAAK,GAAG,YAAY,CA8mBvE,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,QAAO,OAAiD,CAAA;AAE7E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK,GAChB,UAAS,OAAY,KACpB,KAAK,CAAC,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,YAAY,CAoB1D,CAAA;AAEH;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,SAAS,CAAwC,CAAA"}