@rexezuge/runtime 1.0.8 → 1.1.0

package/dist/index.d.ts

@@ -21,4 +21,6 @@ export { createLogger, isLogLevel, resolveLogLevel } from './logger';
 export type { LogLevel, Logger } from './logger';
 export { KvCache, KV_DOMAINS, buildKvKey, clampTtl, digest128 } from './kv';
 export type { KvDomainDef, KvDomainName, KvNamespaceLike } from './kv';
+export { AbstractScheduledTask, TaskRegistry } from './scheduled';
+export type { ApplicationRunHandle, ScheduledTaskEnv, TaskLogger, TaskRunRecorder, TaskRunSummary } from './scheduled';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACtF,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,YAAY,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AACzG,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACzF,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAC5E,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACtF,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,YAAY,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AACzG,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACzF,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAC5E,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -14,4 +14,5 @@ export { AbstractQueueWorker } from './base/AbstractQueueWorker';
 export { AbstractWorkflowWorker } from './base/AbstractWorkflowWorker';
 export { createLogger, isLogLevel, resolveLogLevel } from './logger';
 export { KvCache, KV_DOMAINS, buildKvKey, clampTtl, digest128 } from './kv';
+export { AbstractScheduledTask, TaskRegistry } from './scheduled';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAE3E,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAEvE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAErE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC","sourcesContent":["/**\n * `@rexezuge/runtime` — the platform foundation layer: DI, configuration,\n * worker bases, logger, KV cache. Zero dependencies (the one platform import\n * is type-only, resolved through each consumer's generated wrangler types).\n */\n\nexport { Container } from './di/Container';\nexport type { Factory, Token } from './di/Container';\nexport { asScopedContext, getRequestScope, setRequestScope } from './di/RequestScope';\nexport type { ScopedContext } from './di/RequestScope';\nexport { AppConfiguration } from './config/AppConfiguration';\nexport { EnvParser } from './config/EnvParser';\nexport { DEFAULT_SITE_URL } from './config/ConfigurationDefaults';\nexport { AbstractEntrypointWorker } from './base/AbstractEntrypointWorker';\nexport type { WorkerExecutionContext, WorkerScheduledController } from './base/AbstractEntrypointWorker';\nexport { AbstractDurableObjectWorker } from './base/AbstractDurableObjectWorker';\nexport { AbstractQueueWorker } from './base/AbstractQueueWorker';\nexport type { WorkerMessageBatch } from './base/AbstractQueueWorker';\nexport { AbstractWorkflowWorker } from './base/AbstractWorkflowWorker';\nexport type { WorkflowEventLike, WorkflowStepLike } from './base/AbstractWorkflowWorker';\nexport { createLogger, isLogLevel, resolveLogLevel } from './logger';\nexport type { LogLevel, Logger } from './logger';\nexport { KvCache, KV_DOMAINS, buildKvKey, clampTtl, digest128 } from './kv';\nexport type { KvDomainDef, KvDomainName, KvNamespaceLike } from './kv';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAE3E,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAEvE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAErE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAE5E,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC","sourcesContent":["/**\n * `@rexezuge/runtime` — the platform foundation layer: DI, configuration,\n * worker bases, logger, KV cache. Zero dependencies (the one platform import\n * is type-only, resolved through each consumer's generated wrangler types).\n */\n\nexport { Container } from './di/Container';\nexport type { Factory, Token } from './di/Container';\nexport { asScopedContext, getRequestScope, setRequestScope } from './di/RequestScope';\nexport type { ScopedContext } from './di/RequestScope';\nexport { AppConfiguration } from './config/AppConfiguration';\nexport { EnvParser } from './config/EnvParser';\nexport { DEFAULT_SITE_URL } from './config/ConfigurationDefaults';\nexport { AbstractEntrypointWorker } from './base/AbstractEntrypointWorker';\nexport type { WorkerExecutionContext, WorkerScheduledController } from './base/AbstractEntrypointWorker';\nexport { AbstractDurableObjectWorker } from './base/AbstractDurableObjectWorker';\nexport { AbstractQueueWorker } from './base/AbstractQueueWorker';\nexport type { WorkerMessageBatch } from './base/AbstractQueueWorker';\nexport { AbstractWorkflowWorker } from './base/AbstractWorkflowWorker';\nexport type { WorkflowEventLike, WorkflowStepLike } from './base/AbstractWorkflowWorker';\nexport { createLogger, isLogLevel, resolveLogLevel } from './logger';\nexport type { LogLevel, Logger } from './logger';\nexport { KvCache, KV_DOMAINS, buildKvKey, clampTtl, digest128 } from './kv';\nexport type { KvDomainDef, KvDomainName, KvNamespaceLike } from './kv';\nexport { AbstractScheduledTask, TaskRegistry } from './scheduled';\nexport type { ApplicationRunHandle, ScheduledTaskEnv, TaskLogger, TaskRunRecorder, TaskRunSummary } from './scheduled';\n"]}

package/dist/scheduled/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The scheduled-task Template Method, and the run-record port it records through.
+ *
+ * Converged from `apps/background/src/scheduled/{IScheduledTask,TaskRegistry}.ts`
+ * in seven repos, where the copies range from 13 lines (CalDAV-Bridge) to 103
+ * (Mail-Otter). Mail-Otter's was the one that had solved the defects the others
+ * carried, so this is that one.
+ *
+ * ## What the smaller copies were missing
+ *
+ * - **Run bookkeeping.** A task that fails silently leaves an operator with a
+ *   cron that appears to run and never does. `runId` here is the record that
+ *   says which.
+ * - **A failure that is recorded as a failure.** The template's `catch` writes
+ *   `failRun`, so the task-runs table shows the reason rather than a row that
+ *   stopped at `running`.
+ * - **A test seam.** `createRunRecorder` is a Factory Method so a suite
+ *   substitutes a double without a D1 binding.
+ *
+ * ## Why the recorder is a port and not a DAO
+ *
+ * `runtime` is the DI and platform layer and has no `d1` dependency — that
+ * would invert the package graph. The port is four methods; the consumer binds
+ * its `BackgroundTaskRunDAO` at the composition root.
+ */
+/** The summary a task reports when it finishes. */
+interface TaskRunSummary {
+    itemsProcessed: number;
+    itemsFailed: number;
+    summary?: string;
+    details?: unknown;
+}
+/**
+ * Where run records go.
+ *
+ * Implemented by each repo's `BackgroundTaskRunDAO`; supplied as a factory so a
+ * task can be constructed before the binding is known.
+ */
+interface TaskRunRecorder {
+    startRun(fields: {
+        taskType: string;
+        applicationId?: string;
+    }): Promise<string>;
+    succeedRun(runId: string, result: TaskRunSummary): Promise<void>;
+    failRun(runId: string, errorMessage: string, partial?: Partial<TaskRunSummary>): Promise<void>;
+    skipRun(runId: string, reason?: string): Promise<void>;
+}
+/**
+ * A handle to one run's completion.
+ *
+ * Every method swallows its own recording failure and logs a warning. A task
+ * whose work succeeded must not be reported as failed because the bookkeeping
+ * write did not land — that is the same class of defect as a status read that
+ * writes.
+ */
+interface ApplicationRunHandle {
+    succeed(result: TaskRunSummary): Promise<void>;
+    fail(errorMessage: string, partial?: Partial<TaskRunSummary>): Promise<void>;
+    skip(reason?: string): Promise<void>;
+}
+/** The minimum a task needs from `env`: a D1 binding, when the repo has one. */
+interface ScheduledTaskEnv {
+    DB?: unknown;
+}
+/**
+ * The cron event, structurally.
+ *
+ * Declared here rather than taken from `@cloudflare/workers-types`: this package
+ * stays typecheckable with no platform types installed, the same trade
+ * `AbstractEntrypointWorker` makes. A consumer's real `ScheduledController`
+ * satisfies it.
+ */
+interface ScheduledControllerLike {
+    cron: string;
+    scheduledTime: number;
+    noRetry(): void;
+}
+/** The execution context, structurally. See {@link ScheduledControllerLike}. */
+interface ExecutionContextLike {
+    waitUntil(promise: Promise<unknown>): void;
+    passThroughOnException(): void;
+}
+type TaskLogger = (level: 'warn' | 'error', message: string) => void;
+/**
+ * The base every scheduled task extends.
+ *
+ * Subclasses implement {@link handleScheduledTask} and, when they want their
+ * runs recorded, override {@link getTaskType}.
+ */
+declare abstract class AbstractScheduledTask<TEnv extends ScheduledTaskEnv = ScheduledTaskEnv> {
+    /**
+     * The task type recorded against each run, or `null` to opt out.
+     *
+     * Opting **in** rather than out is deliberate: a task that never reports is
+     * invisible, and invisibility is the failure mode worth avoiding by default.
+     * A per-application task should leave this `null` and use
+     * {@link createApplicationRun} instead, so it does not produce a redundant
+     * global record beside its per-application ones.
+     */
+    protected getTaskType(): string | null;
+    /** Factory Method for the recorder. Override in tests. */
+    protected createRunRecorder(): TaskRunRecorder | null;
+    /** Override to route this task's failures somewhere other than the console. */
+    protected logger(): TaskLogger;
+    /**
+     * The entry point the platform calls.
+     *
+     * Owns the try/catch so a task cannot forget it: a scheduled task that throws
+     * uncaught is retried by the platform with no record of why.
+     */
+    handle(event: ScheduledControllerLike, env: TEnv, ctx: ExecutionContextLike): Promise<void>;
+    /**
+     * Open a per-application run record.
+     *
+     * Call inside a loop over applications, so the operator sees which one failed
+     * rather than a single row for the whole cron.
+     */
+    protected createApplicationRun(taskType: string, applicationId: string): Promise<ApplicationRunHandle | null>;
+    /**
+     * The task's work.
+     *
+     * Returns a summary to be recorded, or nothing for a task whose runs are not
+     * tracked.
+     */
+    protected abstract handleScheduledTask(event: ScheduledControllerLike, env: TEnv, ctx: ExecutionContextLike): Promise<TaskRunSummary | void>;
+}
+/**
+ * The phase registry.
+ *
+ * Two phases, run in order, each internally parallel. The split is what keeps
+ * one slow task from delaying the pruning that has to run behind it — and it is
+ * why this is a table rather than a list: adding a task at index 0 cannot
+ * silently reclassify every task after it.
+ */
+declare class TaskRegistry {
+    private readonly byPhase;
+    register(phase: number, task: AbstractScheduledTask): this;
+    /** Every task in a phase, in registration order. */
+    tasksForPhase(phase: number): readonly AbstractScheduledTask[];
+    /** The phases that have at least one task, ascending. */
+    phases(): readonly number[];
+}
+export { AbstractScheduledTask, TaskRegistry };
+export type { ApplicationRunHandle, ScheduledTaskEnv, TaskLogger, TaskRunRecorder, TaskRunSummary };
+//# sourceMappingURL=index.d.ts.map

package/dist/scheduled/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scheduled/index.ts"],"names":[],"mappings":"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"}

package/dist/scheduled/index.js

@@ -0,0 +1,151 @@
+/**
+ * The scheduled-task Template Method, and the run-record port it records through.
+ *
+ * Converged from `apps/background/src/scheduled/{IScheduledTask,TaskRegistry}.ts`
+ * in seven repos, where the copies range from 13 lines (CalDAV-Bridge) to 103
+ * (Mail-Otter). Mail-Otter's was the one that had solved the defects the others
+ * carried, so this is that one.
+ *
+ * ## What the smaller copies were missing
+ *
+ * - **Run bookkeeping.** A task that fails silently leaves an operator with a
+ *   cron that appears to run and never does. `runId` here is the record that
+ *   says which.
+ * - **A failure that is recorded as a failure.** The template's `catch` writes
+ *   `failRun`, so the task-runs table shows the reason rather than a row that
+ *   stopped at `running`.
+ * - **A test seam.** `createRunRecorder` is a Factory Method so a suite
+ *   substitutes a double without a D1 binding.
+ *
+ * ## Why the recorder is a port and not a DAO
+ *
+ * `runtime` is the DI and platform layer and has no `d1` dependency — that
+ * would invert the package graph. The port is four methods; the consumer binds
+ * its `BackgroundTaskRunDAO` at the composition root.
+ */
+const consoleLogger = (level, message) => {
+    if (level === 'warn')
+        console.warn(message);
+    else
+        console.error(message);
+};
+/**
+ * The base every scheduled task extends.
+ *
+ * Subclasses implement {@link handleScheduledTask} and, when they want their
+ * runs recorded, override {@link getTaskType}.
+ */
+class AbstractScheduledTask {
+    /**
+     * The task type recorded against each run, or `null` to opt out.
+     *
+     * Opting **in** rather than out is deliberate: a task that never reports is
+     * invisible, and invisibility is the failure mode worth avoiding by default.
+     * A per-application task should leave this `null` and use
+     * {@link createApplicationRun} instead, so it does not produce a redundant
+     * global record beside its per-application ones.
+     */
+    getTaskType() {
+        return null;
+    }
+    /** Factory Method for the recorder. Override in tests. */
+    createRunRecorder() {
+        return null;
+    }
+    /** Override to route this task's failures somewhere other than the console. */
+    logger() {
+        return consoleLogger;
+    }
+    /**
+     * The entry point the platform calls.
+     *
+     * Owns the try/catch so a task cannot forget it: a scheduled task that throws
+     * uncaught is retried by the platform with no record of why.
+     */
+    async handle(event, env, ctx) {
+        const taskType = this.getTaskType();
+        const recorder = taskType === null ? null : this.createRunRecorder();
+        let runId;
+        if (recorder && taskType !== null) {
+            runId = await recorder.startRun({ taskType }).catch((error) => {
+                // Losing the record must not lose the run.
+                this.logger()('warn', `[${this.constructor.name}] failed to start task run record`);
+                void error;
+                return undefined;
+            });
+        }
+        try {
+            const result = await this.handleScheduledTask(event, env, ctx);
+            if (recorder && runId) {
+                await recorder.succeedRun(runId, result ?? { itemsProcessed: 0, itemsFailed: 0 }).catch(() => {
+                    this.logger()('warn', `[${this.constructor.name}] failed to mark task run succeeded`);
+                });
+            }
+        }
+        catch (error) {
+            this.logger()('error', `[${this.constructor.name}] uncaught error`);
+            if (recorder && runId) {
+                const message = error instanceof Error ? error.message : String(error);
+                await recorder.failRun(runId, message).catch(() => {
+                    this.logger()('warn', `[${this.constructor.name}] failed to mark task run failed`);
+                });
+            }
+        }
+    }
+    /**
+     * Open a per-application run record.
+     *
+     * Call inside a loop over applications, so the operator sees which one failed
+     * rather than a single row for the whole cron.
+     */
+    async createApplicationRun(taskType, applicationId) {
+        const recorder = this.createRunRecorder();
+        if (!recorder)
+            return null;
+        const runId = await recorder.startRun({ taskType, applicationId });
+        const warn = (op) => () => {
+            this.logger()('warn', `[${this.constructor.name}] failed to mark application run ${op}`);
+        };
+        return {
+            succeed: (result) => recorder
+                .succeedRun(runId, result)
+                .catch(warn('succeeded'))
+                .then(() => undefined),
+            fail: (errorMessage, partial) => recorder
+                .failRun(runId, errorMessage, partial)
+                .catch(warn('failed'))
+                .then(() => undefined),
+            skip: (reason) => recorder
+                .skipRun(runId, reason)
+                .catch(warn('skipped'))
+                .then(() => undefined),
+        };
+    }
+}
+/**
+ * The phase registry.
+ *
+ * Two phases, run in order, each internally parallel. The split is what keeps
+ * one slow task from delaying the pruning that has to run behind it — and it is
+ * why this is a table rather than a list: adding a task at index 0 cannot
+ * silently reclassify every task after it.
+ */
+class TaskRegistry {
+    byPhase = new Map();
+    register(phase, task) {
+        const existing = this.byPhase.get(phase) ?? [];
+        existing.push(task);
+        this.byPhase.set(phase, existing);
+        return this;
+    }
+    /** Every task in a phase, in registration order. */
+    tasksForPhase(phase) {
+        return this.byPhase.get(phase) ?? [];
+    }
+    /** The phases that have at least one task, ascending. */
+    phases() {
+        return [...this.byPhase.keys()].sort((left, right) => left - right);
+    }
+}
+export { AbstractScheduledTask, TaskRegistry };
+//# sourceMappingURL=index.js.map

package/dist/scheduled/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scheduled/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The scheduled-task Template Method, and the run-record port it records through.\n *\n * Converged from `apps/background/src/scheduled/{IScheduledTask,TaskRegistry}.ts`\n * in seven repos, where the copies range from 13 lines (CalDAV-Bridge) to 103\n * (Mail-Otter). Mail-Otter's was the one that had solved the defects the others\n * carried, so this is that one.\n *\n * ## What the smaller copies were missing\n *\n * - **Run bookkeeping.** A task that fails silently leaves an operator with a\n *   cron that appears to run and never does. `runId` here is the record that\n *   says which.\n * - **A failure that is recorded as a failure.** The template's `catch` writes\n *   `failRun`, so the task-runs table shows the reason rather than a row that\n *   stopped at `running`.\n * - **A test seam.** `createRunRecorder` is a Factory Method so a suite\n *   substitutes a double without a D1 binding.\n *\n * ## Why the recorder is a port and not a DAO\n *\n * `runtime` is the DI and platform layer and has no `d1` dependency — that\n * would invert the package graph. The port is four methods; the consumer binds\n * its `BackgroundTaskRunDAO` at the composition root.\n */\n\n/** The summary a task reports when it finishes. */\ninterface TaskRunSummary {\n  itemsProcessed: number;\n  itemsFailed: number;\n  summary?: string;\n  details?: unknown;\n}\n\n/**\n * Where run records go.\n *\n * Implemented by each repo's `BackgroundTaskRunDAO`; supplied as a factory so a\n * task can be constructed before the binding is known.\n */\ninterface TaskRunRecorder {\n  startRun(fields: { taskType: string; applicationId?: string }): Promise<string>;\n  succeedRun(runId: string, result: TaskRunSummary): Promise<void>;\n  failRun(runId: string, errorMessage: string, partial?: Partial<TaskRunSummary>): Promise<void>;\n  skipRun(runId: string, reason?: string): Promise<void>;\n}\n\n/**\n * A handle to one run's completion.\n *\n * Every method swallows its own recording failure and logs a warning. A task\n * whose work succeeded must not be reported as failed because the bookkeeping\n * write did not land — that is the same class of defect as a status read that\n * writes.\n */\ninterface ApplicationRunHandle {\n  succeed(result: TaskRunSummary): Promise<void>;\n  fail(errorMessage: string, partial?: Partial<TaskRunSummary>): Promise<void>;\n  skip(reason?: string): Promise<void>;\n}\n\n/** The minimum a task needs from `env`: a D1 binding, when the repo has one. */\ninterface ScheduledTaskEnv {\n  DB?: unknown;\n}\n\n/**\n * The cron event, structurally.\n *\n * Declared here rather than taken from `@cloudflare/workers-types`: this package\n * stays typecheckable with no platform types installed, the same trade\n * `AbstractEntrypointWorker` makes. A consumer's real `ScheduledController`\n * satisfies it.\n */\ninterface ScheduledControllerLike {\n  cron: string;\n  scheduledTime: number;\n  noRetry(): void;\n}\n\n/** The execution context, structurally. See {@link ScheduledControllerLike}. */\ninterface ExecutionContextLike {\n  waitUntil(promise: Promise<unknown>): void;\n  passThroughOnException(): void;\n}\n\ntype TaskLogger = (level: 'warn' | 'error', message: string) => void;\n\nconst consoleLogger: TaskLogger = (level, message) => {\n  if (level === 'warn') console.warn(message);\n  else console.error(message);\n};\n\n/**\n * The base every scheduled task extends.\n *\n * Subclasses implement {@link handleScheduledTask} and, when they want their\n * runs recorded, override {@link getTaskType}.\n */\nabstract class AbstractScheduledTask<TEnv extends ScheduledTaskEnv = ScheduledTaskEnv> {\n  /**\n   * The task type recorded against each run, or `null` to opt out.\n   *\n   * Opting **in** rather than out is deliberate: a task that never reports is\n   * invisible, and invisibility is the failure mode worth avoiding by default.\n   * A per-application task should leave this `null` and use\n   * {@link createApplicationRun} instead, so it does not produce a redundant\n   * global record beside its per-application ones.\n   */\n  protected getTaskType(): string | null {\n    return null;\n  }\n\n  /** Factory Method for the recorder. Override in tests. */\n  protected createRunRecorder(): TaskRunRecorder | null {\n    return null;\n  }\n\n  /** Override to route this task's failures somewhere other than the console. */\n  protected logger(): TaskLogger {\n    return consoleLogger;\n  }\n\n  /**\n   * The entry point the platform calls.\n   *\n   * Owns the try/catch so a task cannot forget it: a scheduled task that throws\n   * uncaught is retried by the platform with no record of why.\n   */\n  public async handle(event: ScheduledControllerLike, env: TEnv, ctx: ExecutionContextLike): Promise<void> {\n    const taskType = this.getTaskType();\n    const recorder = taskType === null ? null : this.createRunRecorder();\n\n    let runId: string | undefined;\n    if (recorder && taskType !== null) {\n      runId = await recorder.startRun({ taskType }).catch((error: unknown) => {\n        // Losing the record must not lose the run.\n        this.logger()('warn', `[${this.constructor.name}] failed to start task run record`);\n        void error;\n        return undefined;\n      });\n    }\n\n    try {\n      const result = await this.handleScheduledTask(event, env, ctx);\n      if (recorder && runId) {\n        await recorder.succeedRun(runId, result ?? { itemsProcessed: 0, itemsFailed: 0 }).catch(() => {\n          this.logger()('warn', `[${this.constructor.name}] failed to mark task run succeeded`);\n        });\n      }\n    } catch (error: unknown) {\n      this.logger()('error', `[${this.constructor.name}] uncaught error`);\n      if (recorder && runId) {\n        const message = error instanceof Error ? error.message : String(error);\n        await recorder.failRun(runId, message).catch(() => {\n          this.logger()('warn', `[${this.constructor.name}] failed to mark task run failed`);\n        });\n      }\n    }\n  }\n\n  /**\n   * Open a per-application run record.\n   *\n   * Call inside a loop over applications, so the operator sees which one failed\n   * rather than a single row for the whole cron.\n   */\n  protected async createApplicationRun(taskType: string, applicationId: string): Promise<ApplicationRunHandle | null> {\n    const recorder = this.createRunRecorder();\n    if (!recorder) return null;\n    const runId = await recorder.startRun({ taskType, applicationId });\n\n    const warn = (op: string) => (): void => {\n      this.logger()('warn', `[${this.constructor.name}] failed to mark application run ${op}`);\n    };\n\n    return {\n      succeed: (result: TaskRunSummary): Promise<void> =>\n        recorder\n          .succeedRun(runId, result)\n          .catch(warn('succeeded'))\n          .then(() => undefined),\n      fail: (errorMessage: string, partial?: Partial<TaskRunSummary>): Promise<void> =>\n        recorder\n          .failRun(runId, errorMessage, partial)\n          .catch(warn('failed'))\n          .then(() => undefined),\n      skip: (reason?: string): Promise<void> =>\n        recorder\n          .skipRun(runId, reason)\n          .catch(warn('skipped'))\n          .then(() => undefined),\n    };\n  }\n\n  /**\n   * The task's work.\n   *\n   * Returns a summary to be recorded, or nothing for a task whose runs are not\n   * tracked.\n   */\n  protected abstract handleScheduledTask(\n    event: ScheduledControllerLike,\n    env: TEnv,\n    ctx: ExecutionContextLike,\n  ): Promise<TaskRunSummary | void>;\n}\n\n/**\n * The phase registry.\n *\n * Two phases, run in order, each internally parallel. The split is what keeps\n * one slow task from delaying the pruning that has to run behind it — and it is\n * why this is a table rather than a list: adding a task at index 0 cannot\n * silently reclassify every task after it.\n */\nclass TaskRegistry {\n  private readonly byPhase = new Map<number, AbstractScheduledTask[]>();\n\n  public register(phase: number, task: AbstractScheduledTask): this {\n    const existing = this.byPhase.get(phase) ?? [];\n    existing.push(task);\n    this.byPhase.set(phase, existing);\n    return this;\n  }\n\n  /** Every task in a phase, in registration order. */\n  public tasksForPhase(phase: number): readonly AbstractScheduledTask[] {\n    return this.byPhase.get(phase) ?? [];\n  }\n\n  /** The phases that have at least one task, ascending. */\n  public phases(): readonly number[] {\n    return [...this.byPhase.keys()].sort((left, right) => left - right);\n  }\n}\n\nexport { AbstractScheduledTask, TaskRegistry };\nexport type { ApplicationRunHandle, ScheduledTaskEnv, TaskLogger, TaskRunRecorder, TaskRunSummary };\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rexezuge/runtime",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "private": false,
   "license": "MIT",
   "repository": {