@cronwatch/sdk 0.3.0 → 0.3.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { S as Store, a as AlertChannel, T as TriageFn, D as Duration, J as JobOptions, b as JobDefinition, C as CheckResult, c as JobSummary, R as Run, d as JobState, A as Alert, e as AlertDraft, f as StoredJobDefinition } from './types-C1PyRjI5.cjs';
-export { g as AlertDetails, h as AlertType, B as BudgetBreach, i as Condition, E as ExpectRule, j as JobHealth, k as RunStatus, l as StoredJob, m as TriageContext } from './types-C1PyRjI5.cjs';
+import { S as Store, a as AlertChannel, T as TriageFn, D as Duration, J as JobOptions, b as JobDefinition, C as CheckResult, c as JobSummary, R as Run, d as JobState, A as Alert, e as AlertDraft, f as StoredJobDefinition } from './types-DUt2apl0.cjs';
+export { g as AlertDetails, h as AlertType, B as BudgetBreach, i as Condition, E as ExpectRule, j as JobHealth, k as RunStatus, l as StoredJob, m as TriageContext } from './types-DUt2apl0.cjs';
 
 /** What a job function receives. */
 interface JobContext {
@@ -20,9 +20,10 @@ interface RoutesOptions {
      * Required to reach anything. Send it as `Authorization: Bearer <token>`,
      * or open the dashboard once with `?token=<token>` and a cookie is set.
      * Defaults to process.env.CRONWATCH_TOKEN; an empty string counts as unset.
-     * With no token, the routes answer only requests to localhost while NODE_ENV
-     * is "development" or "test", and 503 otherwise. Pass `null` to opt out and serve them
-     * open everywhere, for example behind your own auth.
+     * With no token while NODE_ENV is "development" or "test", the routes make
+     * a random one and print a sign-in link to the server log on their first
+     * request; with no token otherwise they answer 503. Pass `null` to opt out
+     * and serve them open everywhere, for example behind your own auth.
      *
      * The check endpoint (/api/check) also accepts the client's cronSecret, so
      * a platform cron that sends `Authorization: Bearer <CRON_SECRET>` can
@@ -89,9 +90,11 @@ interface CronWatchOptions {
     /**
      * Applied to every run's output and error before it is stored, shown or
      * sent to an alert channel or triage. The default blanks values that look
-     * like secrets (password=..., URL credentials, bearer tokens, AWS, GitHub,
-     * Slack, Stripe and API key formats). Pass your own function, or false to
-     * keep output exactly as logged.
+     * like secrets (password=..., Authorization headers, URL credentials, bearer
+     * tokens, JWTs, PEM private keys, webhook URLs, AWS, GitHub, Slack, Stripe,
+     * Google and API key formats). Pass your own function, or false to keep
+     * output exactly as logged. A function that throws or returns something
+     * other than a string is reported to onError and the default is used.
      */
     redact?: ((text: string) => string) | false;
     /**
@@ -133,6 +136,7 @@ declare class CronWatch {
     private firstTick;
     private usingDefaultStore;
     private warnedNoSecret;
+    private warnedDeferredStart;
     constructor(options?: CronWatchOptions);
     /** Declare a job. Call it once, at module level, and keep the handle. */
     job(name: string, options?: JobOptions): JobHandle;
@@ -143,15 +147,32 @@ declare class CronWatch {
     definedJobs(): JobDefinition[];
     private handle;
     private warnNoSecret;
+    /** onError, for places that must carry on even when onError itself throws. */
+    private report;
     private ensureReady;
     private sync;
     /**
      * Runs `fn` after every earlier state update for the same job has settled,
      * so two runs (or a run and a check) in this process never read and write
-     * the job's state over each other. Other processes are not coordinated.
+     * the job's state over each other. Other processes are coordinated by
+     * updateState() instead.
      */
     private serial;
     private readState;
+    /**
+     * Every read-modify-write of a job's state goes through here. In turn with
+     * this process's other updates to the job (serial()), it reads the state,
+     * asks `change` for the next one, and writes it with the version one
+     * higher, only if the stored version is still the one read. When another
+     * process wrote in between, the write is refused and it starts again from
+     * a fresh read, up to STATE_ATTEMPTS times. So `change` may run more than
+     * once and must only compute: whatever it returns from the attempt that
+     * was written is the result. Nothing is written when the state is
+     * unchanged. Returns the state as stored.
+     */
+    private updateState;
+    /** A conditional write, or for a store without compareAndSetState, a plain one that always succeeds. */
+    private writeState;
     /**
      * Runs a function as a recorded run. The function always runs, whatever
      * the store is doing: store errors go to onError, and the result is the
@@ -179,8 +200,10 @@ declare class CronWatch {
      */
     check(): Promise<CheckResult>;
     private runCheck;
-    /** A job's summary and its newest runs, without alerting. */
+    /** A job's summary and its newest runs, without alerting. A job that cannot be evaluated is reported and shown as failing. */
     private snapshot;
+    /** The summary of a job whose evaluation failed, from whatever can still be read. */
+    private unevaluable;
     /** Every job the store knows about, with its health. Does not send alerts. */
     jobs(): Promise<JobSummary[]>;
     /** Every job's summary with its newest `limit` runs, read together. What the dashboard shows. */
@@ -205,20 +228,29 @@ declare class CronWatch {
     start(every?: Duration): void;
     stop(): void;
     close(): Promise<void>;
-    /** Save an evaluation's state, honouring silence, and return what should be sent. Call inside serial(). */
-    private settle;
     /**
      * Compose, triage and send each draft. The state was saved before this
-     * (settle), so a slow channel holds up nothing else; afterwards only the
-     * delivery fields are written back, onto a fresh read of the state.
+     * (updateState), so a slow channel holds up nothing else; afterwards only
+     * the delivery fields are written back, onto a fresh read of the state.
      */
     private dispatch;
-    /** Send the alerts that no channel accepted last time, once each. */
+    /**
+     * Send the alerts that no channel accepted last time, once each, oldest
+     * first. `state` is the job's state as this check left it: an alert that
+     * no longer describes it (staleAlert) is dropped instead. Retries across a
+     * check share RETRY_BUDGET_MS of wall-clock time; once it is spent the rest
+     * stay queued for the next check.
+     */
     private retryUndelivered;
-    /** Mark delivered alerts done and keep failed ones for the next check. lastAlertAt moves only on a delivery. */
+    /**
+     * Mark delivered alerts done, drop stale ones, and keep failed ones for the
+     * next check. A failed alert replaces its stored copy, so a triage made on
+     * this attempt is kept. lastAlertAt moves only on a delivery.
+     */
     private recordDelivery;
     /** Send to every channel at once. True when at least one accepted it, or there are none. */
     private deliver;
+    /** Sets alert.triage to the diagnosis, or to null when there is none, so it is tried once per alert. */
     private addTriage;
 }
 /** Writes alerts to the console. The default channel. */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as Store, a as AlertChannel, T as TriageFn, D as Duration, J as JobOptions, b as JobDefinition, C as CheckResult, c as JobSummary, R as Run, d as JobState, A as Alert, e as AlertDraft, f as StoredJobDefinition } from './types-C1PyRjI5.js';
-export { g as AlertDetails, h as AlertType, B as BudgetBreach, i as Condition, E as ExpectRule, j as JobHealth, k as RunStatus, l as StoredJob, m as TriageContext } from './types-C1PyRjI5.js';
+import { S as Store, a as AlertChannel, T as TriageFn, D as Duration, J as JobOptions, b as JobDefinition, C as CheckResult, c as JobSummary, R as Run, d as JobState, A as Alert, e as AlertDraft, f as StoredJobDefinition } from './types-DUt2apl0.js';
+export { g as AlertDetails, h as AlertType, B as BudgetBreach, i as Condition, E as ExpectRule, j as JobHealth, k as RunStatus, l as StoredJob, m as TriageContext } from './types-DUt2apl0.js';
 
 /** What a job function receives. */
 interface JobContext {
@@ -20,9 +20,10 @@ interface RoutesOptions {
      * Required to reach anything. Send it as `Authorization: Bearer <token>`,
      * or open the dashboard once with `?token=<token>` and a cookie is set.
      * Defaults to process.env.CRONWATCH_TOKEN; an empty string counts as unset.
-     * With no token, the routes answer only requests to localhost while NODE_ENV
-     * is "development" or "test", and 503 otherwise. Pass `null` to opt out and serve them
-     * open everywhere, for example behind your own auth.
+     * With no token while NODE_ENV is "development" or "test", the routes make
+     * a random one and print a sign-in link to the server log on their first
+     * request; with no token otherwise they answer 503. Pass `null` to opt out
+     * and serve them open everywhere, for example behind your own auth.
      *
      * The check endpoint (/api/check) also accepts the client's cronSecret, so
      * a platform cron that sends `Authorization: Bearer <CRON_SECRET>` can
@@ -89,9 +90,11 @@ interface CronWatchOptions {
     /**
      * Applied to every run's output and error before it is stored, shown or
      * sent to an alert channel or triage. The default blanks values that look
-     * like secrets (password=..., URL credentials, bearer tokens, AWS, GitHub,
-     * Slack, Stripe and API key formats). Pass your own function, or false to
-     * keep output exactly as logged.
+     * like secrets (password=..., Authorization headers, URL credentials, bearer
+     * tokens, JWTs, PEM private keys, webhook URLs, AWS, GitHub, Slack, Stripe,
+     * Google and API key formats). Pass your own function, or false to keep
+     * output exactly as logged. A function that throws or returns something
+     * other than a string is reported to onError and the default is used.
      */
     redact?: ((text: string) => string) | false;
     /**
@@ -133,6 +136,7 @@ declare class CronWatch {
     private firstTick;
     private usingDefaultStore;
     private warnedNoSecret;
+    private warnedDeferredStart;
     constructor(options?: CronWatchOptions);
     /** Declare a job. Call it once, at module level, and keep the handle. */
     job(name: string, options?: JobOptions): JobHandle;
@@ -143,15 +147,32 @@ declare class CronWatch {
     definedJobs(): JobDefinition[];
     private handle;
     private warnNoSecret;
+    /** onError, for places that must carry on even when onError itself throws. */
+    private report;
     private ensureReady;
     private sync;
     /**
      * Runs `fn` after every earlier state update for the same job has settled,
      * so two runs (or a run and a check) in this process never read and write
-     * the job's state over each other. Other processes are not coordinated.
+     * the job's state over each other. Other processes are coordinated by
+     * updateState() instead.
      */
     private serial;
     private readState;
+    /**
+     * Every read-modify-write of a job's state goes through here. In turn with
+     * this process's other updates to the job (serial()), it reads the state,
+     * asks `change` for the next one, and writes it with the version one
+     * higher, only if the stored version is still the one read. When another
+     * process wrote in between, the write is refused and it starts again from
+     * a fresh read, up to STATE_ATTEMPTS times. So `change` may run more than
+     * once and must only compute: whatever it returns from the attempt that
+     * was written is the result. Nothing is written when the state is
+     * unchanged. Returns the state as stored.
+     */
+    private updateState;
+    /** A conditional write, or for a store without compareAndSetState, a plain one that always succeeds. */
+    private writeState;
     /**
      * Runs a function as a recorded run. The function always runs, whatever
      * the store is doing: store errors go to onError, and the result is the
@@ -179,8 +200,10 @@ declare class CronWatch {
      */
     check(): Promise<CheckResult>;
     private runCheck;
-    /** A job's summary and its newest runs, without alerting. */
+    /** A job's summary and its newest runs, without alerting. A job that cannot be evaluated is reported and shown as failing. */
     private snapshot;
+    /** The summary of a job whose evaluation failed, from whatever can still be read. */
+    private unevaluable;
     /** Every job the store knows about, with its health. Does not send alerts. */
     jobs(): Promise<JobSummary[]>;
     /** Every job's summary with its newest `limit` runs, read together. What the dashboard shows. */
@@ -205,20 +228,29 @@ declare class CronWatch {
     start(every?: Duration): void;
     stop(): void;
     close(): Promise<void>;
-    /** Save an evaluation's state, honouring silence, and return what should be sent. Call inside serial(). */
-    private settle;
     /**
      * Compose, triage and send each draft. The state was saved before this
-     * (settle), so a slow channel holds up nothing else; afterwards only the
-     * delivery fields are written back, onto a fresh read of the state.
+     * (updateState), so a slow channel holds up nothing else; afterwards only
+     * the delivery fields are written back, onto a fresh read of the state.
      */
     private dispatch;
-    /** Send the alerts that no channel accepted last time, once each. */
+    /**
+     * Send the alerts that no channel accepted last time, once each, oldest
+     * first. `state` is the job's state as this check left it: an alert that
+     * no longer describes it (staleAlert) is dropped instead. Retries across a
+     * check share RETRY_BUDGET_MS of wall-clock time; once it is spent the rest
+     * stay queued for the next check.
+     */
     private retryUndelivered;
-    /** Mark delivered alerts done and keep failed ones for the next check. lastAlertAt moves only on a delivery. */
+    /**
+     * Mark delivered alerts done, drop stale ones, and keep failed ones for the
+     * next check. A failed alert replaces its stored copy, so a triage made on
+     * this attempt is kept. lastAlertAt moves only on a delivery.
+     */
     private recordDelivery;
     /** Send to every channel at once. True when at least one accepted it, or there are none. */
     private deliver;
+    /** Sets alert.triage to the diagnosis, or to null when there is none, so it is tried once per alert. */
     private addTriage;
 }
 /** Writes alerts to the console. The default channel. */