@rikalabs/akter 0.1.0-alpha.0

package/dist/policies/job.js

@@ -0,0 +1,60 @@
+import { Duration } from "effect";
+/** Retries after a job's first failed attempt when its binding names none. */
+const DEFAULT_RETRIES = 3;
+/** An attempt that runs longer is abandoned and counts as an unknown outcome. */
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_BACKOFF = { baseMs: 1000, maxMs: 256_000 };
+const PROGRESS_EVERY_MS = { default: 250, min: 50, max: 60_000 };
+const TIMER = { min: 1, max: 2_147_483_647, label: "1 millisecond to 2147483647 milliseconds" };
+/** Job timings are timer durations: 1 ms to 2^31 − 1 ms unless `bounds` narrows them. */
+const millis = (path, duration, bounds = TIMER) => {
+    const value = Duration.toMillis(Duration.fromInputUnsafe(duration));
+    if (!Number.isFinite(value) || value < bounds.min || value > bounds.max)
+        throw new Error(`${path} must be a duration from ${bounds.label}`);
+    return Math.floor(value);
+};
+/**
+ * Resolves one declared job's binding, throwing on a route that is not one of
+ * `commands`, a `concurrency.perActor` outside 1..64, `retry.times` outside
+ * 0..100, a duration outside its bounds, or a backoff whose max is below its
+ * base. `path` names the binding in those messages.
+ */
+export const resolveJobPolicy = ({ path, declared, commands, }) => {
+    for (const route of [declared?.onSuccess, declared?.onDeadLetter, declared?.onCancelled])
+        if (route !== undefined && !commands.includes(route))
+            throw new Error(`${path} routes must name a command of this actor`);
+    const perActor = declared?.concurrency?.perActor;
+    if (declared?.concurrency !== undefined &&
+        (perActor === undefined || !Number.isInteger(perActor) || perActor < 1 || perActor > 64))
+        throw new Error(`${path}.concurrency.perActor must be an integer from 1 to 64`);
+    const times = declared?.retry?.times ?? DEFAULT_RETRIES;
+    if (!Number.isInteger(times) || times < 0 || times > 100)
+        throw new Error(`${path}.retry.times must be an integer from 0 to 100`);
+    const backoff = declared?.retry?.backoff;
+    const resolved = {
+        attempts: 1 + times,
+        timeoutMs: declared?.timeout === undefined
+            ? DEFAULT_TIMEOUT_MS
+            : millis(`${path}.timeout`, declared.timeout),
+        backoff: backoff === undefined
+            ? DEFAULT_BACKOFF
+            : {
+                baseMs: millis(`${path}.retry.backoff.base`, backoff.base),
+                maxMs: millis(`${path}.retry.backoff.max`, backoff.max),
+            },
+        progressEveryMs: declared?.progressEvery === undefined
+            ? PROGRESS_EVERY_MS.default
+            : millis(`${path}.progressEvery`, declared.progressEvery, {
+                min: PROGRESS_EVERY_MS.min,
+                max: PROGRESS_EVERY_MS.max,
+                label: "50 milliseconds to 1 minute",
+            }),
+        perActor,
+        onSuccess: declared?.onSuccess,
+        onDeadLetter: declared?.onDeadLetter,
+        onCancelled: declared?.onCancelled,
+    };
+    if (resolved.backoff.maxMs < resolved.backoff.baseMs)
+        throw new Error(`${path}.retry.backoff.max must be at least its base`);
+    return Object.freeze(resolved);
+};

package/dist/policies/schedules.d.ts

@@ -0,0 +1,33 @@
+import { Effect, Schema } from "effect";
+import type { AnyCommand } from "../members/command.ts";
+/** One `schedules` entry: its tick's timer key, when it ticks, and its zero-input target. */
+export interface CronEntry {
+    readonly key: string;
+    /** The first scheduled instant strictly after `afterMs`. */
+    readonly next: (afterMs: number) => number;
+    readonly command: string;
+    /** Encodes the target's empty input, as an intent carries it. */
+    readonly payload: Effect.Effect<string>;
+}
+/** The commands a `schedules` entry may target: those whose payload is `Schema.Void`. */
+export type ScheduleTarget<Command extends AnyCommand> = AnyCommand extends Command ? AnyCommand : Extract<Command, {
+    readonly payload: Schema.Void;
+}>;
+/** An actor type's cron entries and how late a tick may still fire. */
+export interface CronSchedule {
+    readonly entries: ReadonlyArray<CronEntry>;
+    readonly skipMs: number;
+}
+/**
+ * Parses `schedules`. A key is a five- or six-field Effect `Cron.parse`
+ * expression evaluated in UTC, the same with a `CRON_TZ=<IANA zone> ` prefix
+ * evaluated in that zone, or `@every <duration>`. Whitespace is normalized and
+ * the timer key names the zone, so one expression in two zones is two entries.
+ * Two declarations with one timer key, an unparsable expression, an unknown
+ * zone, a bad interval, or a target that is not a zero-input command of this
+ * actor throw.
+ */
+export declare const resolveSchedules: ({ declared, commands, }: {
+    readonly declared: Readonly<Record<string, AnyCommand>> | undefined;
+    readonly commands: ReadonlyArray<AnyCommand>;
+}) => ReadonlyArray<CronEntry>;

package/dist/policies/schedules.js

@@ -0,0 +1,131 @@
+import { Cron, DateTime, Duration, Effect, Option, Result, Schema, SchemaAST } from "effect";
+import { CRON_PREFIX } from "../runtime/cron/key.js";
+const emptyPayload = (command) => Schema.encodeEffect(Schema.fromJsonString(Schema.toCodecJson(Schema.Struct({ value: command.payload }))))({ value: undefined }).pipe(Effect.orDie);
+const ZONE_PREFIX = /^CRON_TZ=(\S+)\s+(.*)$/;
+const EVERY_PREFIX = /^@every(?:\s+(.*))?$/;
+const DAY_MS = 86_400_000;
+/**
+ * A declaration's timer key and the first scheduled instant strictly after a
+ * time. Offset zones such as `+05:00` are rejected as unknown: they have no
+ * daylight saving, so a UTC expression says the same thing. Cron fields are
+ * parsed in UTC and `nextInZone` maps the wall-clock times to instants.
+ */
+const scheduleOf = (declaration) => {
+    const normalized = declaration.trim().replace(/\s+/g, " ");
+    const zoned = ZONE_PREFIX.exec(normalized);
+    const zone = zoned?.[1] ?? "UTC";
+    const expression = zoned?.[2] ?? normalized;
+    const every = EVERY_PREFIX.exec(expression);
+    if (every !== null) {
+        if (zoned !== null)
+            throw new Error(`schedules "${declaration}": an interval takes no time zone`);
+        const length = Duration.fromInput((every[1] ?? ""));
+        const millis = Option.isSome(length) ? Duration.toMillis(length.value) : Number.NaN;
+        if (!Number.isSafeInteger(millis) || millis < 1000)
+            throw new Error(`schedules "${declaration}" needs an interval of whole milliseconds, at least 1 second`);
+        return { key: `${CRON_PREFIX}@every ${millis}ms`, next: nextEvery(millis) };
+    }
+    if (/^[+-]/.test(zone) || Option.isNone(DateTime.zoneMakeNamed(zone)))
+        throw new Error(`schedules "${declaration}" names an unknown time zone "${zone}"`);
+    const parsed = Cron.parse(expression, "UTC");
+    if (Result.isFailure(parsed))
+        throw new Error(`schedules "${declaration}" does not parse: ${parsed.failure.message}`);
+    return {
+        key: `${CRON_PREFIX}${zone} ${canonicalOf(parsed.success)}`,
+        next: nextInZone(zone, parsed.success),
+    };
+};
+/**
+ * Parses `schedules`. A key is a five- or six-field Effect `Cron.parse`
+ * expression evaluated in UTC, the same with a `CRON_TZ=<IANA zone> ` prefix
+ * evaluated in that zone, or `@every <duration>`. Whitespace is normalized and
+ * the timer key names the zone, so one expression in two zones is two entries.
+ * Two declarations with one timer key, an unparsable expression, an unknown
+ * zone, a bad interval, or a target that is not a zero-input command of this
+ * actor throw.
+ */
+export const resolveSchedules = ({ declared, commands, }) => {
+    const entries = [];
+    const declarations = new Map();
+    for (const [declaration, command] of Object.entries(declared ?? {})) {
+        const { key, next } = scheduleOf(declaration);
+        if (!commands.includes(command))
+            throw new Error(`schedules "${declaration}" must name a command of this actor`);
+        if (!SchemaAST.isVoid(command.payload.ast))
+            throw new Error(`schedules "${declaration}" must name a command without input`);
+        const duplicate = declarations.get(key);
+        if (duplicate !== undefined)
+            throw new Error(`schedules "${declaration}" repeats the schedule of "${duplicate}"`);
+        declarations.set(key, declaration);
+        entries.push({
+            key,
+            next,
+            command: command.tag,
+            payload: emptyPayload(command),
+        });
+    }
+    return entries;
+};
+const field = (values, size) => values.size === 0 || values.size === size ? "*" : [...values].join(",");
+/** One spelling per parsed schedule, so equivalent expressions share a timer key. */
+const canonicalOf = (cron) => {
+    const seconds = [...cron.seconds];
+    const fields = [
+        field(cron.minutes, 60),
+        field(cron.hours, 24),
+        cron.days.size === 0 ? "*" : [...cron.days].join(","),
+        field(cron.months, 12),
+        cron.weekdays.size === 0 ? "*" : [...cron.weekdays].join(","),
+    ];
+    return (seconds.length === 1 && seconds[0] === 0 ? fields : [field(cron.seconds, 60), ...fields]).join(" ");
+};
+/** Interval ticks fall on whole multiples of the interval since the Unix epoch. */
+const nextEvery = (millis) => (afterMs) => (Math.floor(afterMs / millis) + 1) * millis;
+const offsetAt = (zone, ms) => DateTime.zonedOffset(DateTime.makeZonedUnsafe(ms, { timeZone: zone }));
+/**
+ * The earliest instant whose wall clock in `zone` shows `wall` (a wall-clock
+ * time written as UTC milliseconds), or, when a spring-forward gap skips
+ * `wall`, the first instant after that gap. Offsets a day either side bound
+ * the candidates, since no zone changes its offset twice within two days. A
+ * larger offset gives an earlier instant, so candidates are tried larger
+ * offset first and a repeated time resolves to its first occurrence; a gap is
+ * resolved by bisecting for the first instant whose wall clock reaches `wall`.
+ */
+const instantOf = (zone, wall) => {
+    const before = offsetAt(zone, wall - DAY_MS);
+    const after = offsetAt(zone, wall + DAY_MS);
+    for (const offset of before >= after ? [before, after] : [after, before]) {
+        if (offsetAt(zone, wall - offset) === offset)
+            return wall - offset;
+    }
+    let low = wall - Math.max(before, after);
+    let high = wall - Math.min(before, after);
+    while (high - low > 1) {
+        const middle = Math.floor((low + high) / 2);
+        if (middle + offsetAt(zone, middle) >= wall)
+            high = middle;
+        else
+            low = middle;
+    }
+    return high;
+};
+/**
+ * The first scheduled instant after `afterMs`: a matching wall-clock time at
+ * its first occurrence, or the first instant after a gap that skips one. A
+ * repeated time's second occurrence is never scheduled, however late the tick
+ * is rewritten, so it cannot fire twice.
+ */
+const nextInZone = (zone, cron) => {
+    if (zone === "UTC")
+        return (afterMs) => Cron.next(cron, afterMs).getTime();
+    const named = DateTime.zoneMakeNamedUnsafe(zone);
+    return (afterMs) => {
+        let wall = afterMs + offsetAt(named, afterMs);
+        for (;;) {
+            wall = Cron.next(cron, wall).getTime();
+            const instant = instantOf(named, wall);
+            if (instant > afterMs)
+                return instant;
+        }
+    };
+};

package/dist/protocol/frames.d.ts

@@ -0,0 +1,66 @@
+import { Schema } from "effect";
+/** The WebSocket subprotocol a connection upgrade must offer; it versions the envelope below. */
+export declare const SUBPROTOCOL = "akter.v1";
+/**
+ * Messages a client sends on a connection's socket. Member frames travel only
+ * inside `frame`, so an application frame can never be read as control.
+ */
+export declare const ClientWireMessage: Schema.Union<readonly [Schema.Struct<{
+    readonly t: Schema.Literal<"hello">;
+    readonly authorization: Schema.optional<Schema.String>;
+    readonly params: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>, Schema.Struct<{
+    readonly t: Schema.Literal<"frame">;
+    readonly frame: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, Schema.Struct<{
+    readonly t: Schema.Literal<"resyncDone">;
+    readonly through: Schema.optional<Schema.String>;
+}>, Schema.Struct<{
+    readonly t: Schema.Literal<"reauthenticate">;
+    readonly authorization: Schema.String;
+}>]>;
+/** A message a client sends on a connection's socket. */
+export type ClientWireMessage = typeof ClientWireMessage.Type;
+/**
+ * Messages a server sends on a connection's socket. Times are milliseconds
+ * since the epoch, except `deadline`, which is how long the client has to
+ * answer `resync`. `progress` is a job executor's progress apart from member frames:
+ * display-only, lossy, never replayed, and without cursors.
+ */
+export declare const ServerWireMessage: Schema.Union<readonly [Schema.Struct<{
+    readonly t: Schema.Literal<"open">;
+    readonly connectionId: Schema.String;
+    readonly baseline: Schema.optional<Schema.String>;
+    readonly reauthenticateBy: Schema.optional<Schema.Finite>;
+}>, Schema.Struct<{
+    readonly t: Schema.Literal<"frame">;
+    readonly frame: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly cursor: Schema.optional<Schema.String>;
+    readonly event: Schema.optional<Schema.String>;
+}>, Schema.Struct<{
+    readonly t: Schema.Literal<"resync">;
+    readonly after: Schema.optional<Schema.String>;
+    readonly reason: Schema.Literal<"OwnerLost">;
+    readonly deadline: Schema.Finite;
+}>, Schema.Struct<{
+    readonly t: Schema.Literal<"resyncReplayed">;
+    readonly through: Schema.optional<Schema.String>;
+}>, Schema.Struct<{
+    readonly t: Schema.Literal<"progress">;
+    readonly job: Schema.String;
+    readonly jobId: Schema.String;
+    readonly attempt: Schema.Finite;
+    readonly seq: Schema.Finite;
+    readonly frame: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, Schema.Struct<{
+    readonly t: Schema.Literal<"reauthenticate">;
+    readonly by: Schema.Finite;
+}>, Schema.Struct<{
+    readonly t: Schema.Literal<"reauthenticated">;
+    readonly by: Schema.optional<Schema.Finite>;
+}>, Schema.Struct<{
+    readonly t: Schema.Literal<"end">;
+    readonly error: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>]>;
+/** A message a server sends on a connection's socket. */
+export type ServerWireMessage = typeof ServerWireMessage.Type;

package/dist/protocol/frames.js

@@ -0,0 +1,55 @@
+import { Schema } from "effect";
+/** The WebSocket subprotocol a connection upgrade must offer; it versions the envelope below. */
+export const SUBPROTOCOL = "akter.v1";
+/**
+ * Messages a client sends on a connection's socket. Member frames travel only
+ * inside `frame`, so an application frame can never be read as control.
+ */
+export const ClientWireMessage = Schema.Union([
+    Schema.Struct({
+        t: Schema.Literal("hello"),
+        authorization: Schema.optional(Schema.String),
+        params: Schema.optional(Schema.Json),
+    }),
+    Schema.Struct({ t: Schema.Literal("frame"), frame: Schema.Json }),
+    Schema.Struct({ t: Schema.Literal("resyncDone"), through: Schema.optional(Schema.String) }),
+    Schema.Struct({ t: Schema.Literal("reauthenticate"), authorization: Schema.String }),
+]);
+/**
+ * Messages a server sends on a connection's socket. Times are milliseconds
+ * since the epoch, except `deadline`, which is how long the client has to
+ * answer `resync`. `progress` is a job executor's progress apart from member frames:
+ * display-only, lossy, never replayed, and without cursors.
+ */
+export const ServerWireMessage = Schema.Union([
+    Schema.Struct({
+        t: Schema.Literal("open"),
+        connectionId: Schema.String,
+        baseline: Schema.optional(Schema.String),
+        reauthenticateBy: Schema.optional(Schema.Finite),
+    }),
+    Schema.Struct({
+        t: Schema.Literal("frame"),
+        frame: Schema.Json,
+        cursor: Schema.optional(Schema.String),
+        event: Schema.optional(Schema.String),
+    }),
+    Schema.Struct({
+        t: Schema.Literal("resync"),
+        after: Schema.optional(Schema.String),
+        reason: Schema.Literal("OwnerLost"),
+        deadline: Schema.Finite,
+    }),
+    Schema.Struct({ t: Schema.Literal("resyncReplayed"), through: Schema.optional(Schema.String) }),
+    Schema.Struct({
+        t: Schema.Literal("progress"),
+        job: Schema.String,
+        jobId: Schema.String,
+        attempt: Schema.Finite,
+        seq: Schema.Finite,
+        frame: Schema.Json,
+    }),
+    Schema.Struct({ t: Schema.Literal("reauthenticate"), by: Schema.Finite }),
+    Schema.Struct({ t: Schema.Literal("reauthenticated"), by: Schema.optional(Schema.Finite) }),
+    Schema.Struct({ t: Schema.Literal("end"), error: Schema.optional(Schema.Json) }),
+]);