@fabrika/app 0.9.0-cloudflare.2 → 0.9.0-cloudflare.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/package.json +9 -9
  2. package/skill/SKILL.md +20 -18
  3. package/skill/references/app-setup.md +29 -16
  4. package/skill/references/endpoint.md +24 -22
  5. package/skill/references/errors.md +3 -2
  6. package/skill/references/jobs.md +13 -3
  7. package/skill/references/tests.md +7 -0
  8. package/src/bun.ts +159 -6
  9. package/src/cloudflare/application.ts +543 -73
  10. package/src/cloudflare/export.ts +621 -0
  11. package/src/cloudflare/import.ts +1097 -0
  12. package/src/cloudflare/maintenance.ts +518 -0
  13. package/src/cloudflare/ops.ts +147 -18
  14. package/src/cloudflare/restore.ts +167 -0
  15. package/src/cloudflare/tracker.ts +192 -0
  16. package/src/cloudflare.ts +3 -2
  17. package/src/contract/artifact-schema.ts +7 -1
  18. package/src/contract/build.ts +6 -2
  19. package/src/contract/context.ts +26 -9
  20. package/src/contract/defaults.ts +22 -2
  21. package/src/contract/define.ts +1 -1
  22. package/src/contract/group.ts +1 -1
  23. package/src/files/kinds.ts +54 -24
  24. package/src/implement/anonymous.ts +1 -10
  25. package/src/implement/boot.ts +21 -9
  26. package/src/implement/dispatch.ts +171 -33
  27. package/src/implement/egress.ts +34 -8
  28. package/src/implement/invocation.ts +50 -10
  29. package/src/implement/workload.ts +18 -3
  30. package/src/jobs/runner.ts +639 -96
  31. package/src/testing/kit.ts +60 -0
  32. package/types/src/bun.d.ts +34 -1
  33. package/types/src/cloudflare/application.d.ts +36 -5
  34. package/types/src/cloudflare/export.d.ts +16 -0
  35. package/types/src/cloudflare/import.d.ts +58 -0
  36. package/types/src/cloudflare/maintenance.d.ts +117 -0
  37. package/types/src/cloudflare/ops.d.ts +39 -4
  38. package/types/src/cloudflare/restore.d.ts +9 -0
  39. package/types/src/cloudflare/tracker.d.ts +29 -0
  40. package/types/src/cloudflare.d.ts +2 -1
  41. package/types/src/contract/artifact-schema.d.ts +2 -0
  42. package/types/src/contract/context.d.ts +24 -9
  43. package/types/src/contract/defaults.d.ts +19 -1
  44. package/types/src/contract/define.d.ts +1 -1
  45. package/types/src/contract/group.d.ts +1 -1
  46. package/types/src/files/kinds.d.ts +17 -6
  47. package/types/src/implement/anonymous.d.ts +0 -4
  48. package/types/src/implement/boot.d.ts +11 -0
  49. package/types/src/implement/dispatch.d.ts +31 -0
  50. package/types/src/implement/invocation.d.ts +17 -7
  51. package/types/src/implement/workload.d.ts +5 -0
  52. package/types/src/jobs/runner.d.ts +60 -2
  53. package/types/src/testing/kit.d.ts +16 -0
@@ -78,7 +78,7 @@ export interface EgressField {
78
78
  }
79
79
  /**
80
80
  * A cron job's `egress`: its exact HTTPS origins, or `'public'`, every public host over HTTPS or HTTP on its default
81
- * port, for a job that calls the websites its operators name (ADR-0070). The guard refuses IP addresses, local and
81
+ * port, for a job that calls the websites its operators name (ADR-0071). The guard refuses IP addresses, local and
82
82
  * internal names and the installation's own hosts, checks each redirect, and bounds each request's time and body.
83
83
  */
84
84
  export interface JobEgressField {
@@ -11,6 +11,11 @@ export { FILE_SWEEP_JOB, FILE_SWEEP_SCHEDULE } from './job-names';
11
11
  export declare const FILE_SWEEP_TIMEOUT_MS: number;
12
12
  /** How long a staged file waits for its first reference before the sweep may delete it. */
13
13
  export declare const FILE_PENDING_GRACE_MS: number;
14
+ /**
15
+ * How long a removed file's object outlives its row on Cloudflare, so the rows of a restored backup still find their
16
+ * files: the 30 days backups are kept, which never exceeds this window.
17
+ */
18
+ export declare const FILE_TOMBSTONE_RETENTION_MS: number;
14
19
  /** One file part of a multipart body, as the multipart reader hands it over. */
15
20
  export interface FilePart {
16
21
  readonly filename: string | null;
@@ -46,7 +51,7 @@ interface Kind {
46
51
  }
47
52
  export declare class StoredFileKinds {
48
53
  #private;
49
- constructor(kinds: readonly Kind[], store: FileObjectStore, files: StoredFiles, columns: readonly FileColumnRef[]);
54
+ constructor(kinds: readonly Kind[], store: FileObjectStore, files: StoredFiles, columns: readonly FileColumnRef[], retentionMs: number);
50
55
  /** Whether the contract declares kind `name`. */
51
56
  has(name: string): boolean;
52
57
  /** Whether any kind scans, so the scan job runs. */
@@ -72,9 +77,14 @@ export declare class StoredFileKinds {
72
77
  /** The answer of a procedure whose output is a file: the file the handler returned, streamed. */
73
78
  download(work: FileWork, endpoint: string, kind: string, reference: unknown): Promise<FileDownload>;
74
79
  /**
75
- * The sweep: it finishes deletions a crash interrupted, adopts the migrated files a declared column references, then
76
- * deletes, batch by batch, every file past the grace that no declared column references: its row and the record of
77
- * its object in one transaction (the foreign key keeps a referenced one), then the object, then the record.
80
+ * Cancels the tombstones of `objectKeys`, so their objects stay: a restore cancels every key its restored rows
81
+ * reference. Once it resolves, no deletion of this sweep is in flight. Answers how many it cancelled.
82
+ */
83
+ cancelDeletions(objectKeys: readonly string[]): Promise<number>;
84
+ /**
85
+ * The sweep: it adopts the migrated files a declared column references, then removes, batch by batch, every file past
86
+ * the grace that no declared column references: its row and the record of its object in one transaction (the foreign
87
+ * key keeps a referenced one). Last it claims each recorded object past the retention window, then deletes it.
78
88
  */
79
89
  sweep(signal: AbortSignal): Promise<void>;
80
90
  /** One scan pass over the quarantined files of every scanning kind: the scan job's part for kinds. */
@@ -96,6 +106,7 @@ export declare function storedFilesHandle(kinds: StoredFileKinds | null, work: F
96
106
  };
97
107
  /**
98
108
  * The file kinds of `artifact`, or `null` when it declares none. Every reason a kind cannot be served goes into
99
- * `problems`, so `boot` refuses to start rather than take a file it cannot check.
109
+ * `problems`, so `boot` refuses to start rather than take a file it cannot check. A removed file's object outlives its
110
+ * row by `retentionMs`.
100
111
  */
101
- export declare function storedFileKinds(artifact: ContractArtifact, database: ImplementationDatabase | null, store: FileObjectStore | undefined, problems: string[]): StoredFileKinds | null;
112
+ export declare function storedFileKinds(artifact: ContractArtifact, database: ImplementationDatabase | null, store: FileObjectStore | undefined, problems: string[], retentionMs: number): StoredFileKinds | null;
@@ -1,8 +1,4 @@
1
1
  import { HttpError } from '../errors';
2
- /** The slowest body a procedure waits for, in bytes per second: its deadline is `maxBytes` at this rate, 30 s at least. */
3
- export declare const BODY_RATE_FLOOR: number;
4
- /** How long a body of at most `maxBytes` may take to arrive. */
5
- export declare function bodyDeadlineMs(maxBytes: number): number;
6
2
  /**
7
3
  * The body as bytes, read until `maxBytes`; a longer one stops the read and is a 413. A body whose stream fails before
8
4
  * its end (the client closed the connection) is the sender's 400 `aborted`, never a failure of the application.
@@ -1,5 +1,6 @@
1
1
  import { type IamMembershipRpc, type IamTerminalRpc, type Jwks } from '@fabrika/auth-core';
2
2
  import type { Database } from '@fabrika/db';
3
+ import { type Session } from '@fabrika/db/framework';
3
4
  import type { EmailProviderRegistry } from '@fabrika/email';
4
5
  import type { FileObjectStore } from '@fabrika/platform';
5
6
  import type { RequestExecutionContext } from '../fetch';
@@ -33,6 +34,11 @@ export interface BootOptions {
33
34
  readonly requireProxySecret?: boolean;
34
35
  /** The object storage of the stored files, which the Bun adapter opens. Without it, a contract with file kinds does not boot. */
35
36
  readonly files?: FileObjectStore;
37
+ /**
38
+ * How long a removed file's object outlives its row, so a restored backup's rows find their files:
39
+ * `FILE_TOMBSTONE_RETENTION_MS` on Cloudflare. Zero when omitted, as on Bun.
40
+ */
41
+ readonly fileRetentionMs?: number;
36
42
  /**
37
43
  * The malware scanner of the scan job of `scan: true` file kinds, which the Bun adapter supplies to a job run
38
44
  * (`clamscanScanner`). Without it the scan job leaves every quarantined file quarantined and reports.
@@ -102,6 +108,11 @@ export interface BootOptions {
102
108
  * then `null`.
103
109
  */
104
110
  readonly clientAddress?: 'vouched';
111
+ /**
112
+ * Runs in the transaction of every change of a job's wakes or lease (`DataLayerRuntime.projectWakes`): the Cloudflare
113
+ * object arms its alarm there. Bun supplies none.
114
+ */
115
+ readonly projectWakes?: (transaction: Session) => Promise<void>;
105
116
  }
106
117
  export interface ContractApp {
107
118
  /** `exec` keeps a failure's report to Operations alive past the response (a Worker's `waitUntil`). */
@@ -1,5 +1,6 @@
1
1
  import type { IamMembership } from '@fabrika/auth';
2
2
  import { type CompiledEndpointTable, type CredentialedEndpoint, type EndpointRow, type ExportDescription, type IamTerminalRpc, type SchemaShape, type ScopeBinding, type WebhookScheme } from '@fabrika/auth-core';
3
+ import { DatabaseError } from '@fabrika/db';
3
4
  import { type CapabilityAuthority } from '@fabrika/db/capability';
4
5
  import type { DataAccess, FrameworkTables } from '@fabrika/db/framework';
5
6
  import type { DataKind } from '@fabrika/db/tables';
@@ -22,6 +23,36 @@ import type { SignedTokens } from './tokens';
22
23
  import type { AppUrl } from './urls';
23
24
  import { type BindableWebhook } from './webhook';
24
25
  import type { WorkloadCredential } from './workload';
26
+ /** The classes of invocation an object's maintenance barrier admits per mode, counts and drains (ADR-0069 §3). */
27
+ export type InvocationKind = 'read' | 'write' | 'webhook' | 'kick' | 'job' | 'framework-job';
28
+ /** One admitted invocation, counted until it settles. */
29
+ export interface InvocationAdmission {
30
+ /** Aborts when a drain stops the invocation. */
31
+ readonly signal: AbortSignal;
32
+ /** Counts `work` the invocation handed on until it settles, past the invocation's own end. */
33
+ track(work: Promise<unknown>): void;
34
+ /** Ends the invocation's own count; called once it settled. */
35
+ release(): void;
36
+ }
37
+ /** What a Cloudflare object's barrier puts around each of its events; `null` refuses an invocation. */
38
+ export interface InvocationGate {
39
+ admit(kind: InvocationKind): InvocationAdmission | null;
40
+ }
41
+ /** Runs `work` with `gate` admitting every invocation it starts, the background work it hands on included. */
42
+ export declare function runGated<T>(gate: InvocationGate, work: () => T): T;
43
+ /** Admits an invocation of `kind` at the current event's gate; outside an object every invocation is admitted, uncounted. */
44
+ export declare function admitInvocation(kind: InvocationKind): InvocationAdmission | null;
45
+ /** The answer while maintenance refuses an invocation: 503 with `Retry-After`, the fixed body of every 503. */
46
+ export declare function maintenanceRefusal(): Response;
47
+ /**
48
+ * A write the object's write fence refused: the invocation was admitted before a restrictive transition (ADR-0069 §3).
49
+ * A `DatabaseError`, so `@fabrika/db` passes it through its normalization of statement and commit failures unchanged;
50
+ * its fixed text names no statement or value. Dispatch answers it as `maintenanceRefusal()`.
51
+ */
52
+ export declare class MaintenanceFenceError extends DatabaseError {
53
+ name: string;
54
+ constructor();
55
+ }
25
56
  /** SHA-256 of a proxy secret: 32 bytes whatever the secret's length, as `timingSafeEqual` needs. */
26
57
  export declare function proxySecretDigest(secret: string): Uint8Array;
27
58
  /** Serves the files of an SPA mount. The runtime adapter supplies it: Workers Assets, or the build output on disk. */
@@ -1,5 +1,5 @@
1
1
  import { type ContractArtifact, type DeclaredEgress, type JobMailer } from '@fabrika/auth-core';
2
- import { type DataAccess, type DataHandles, type FileBinding, type Session, type SqlTag } from '@fabrika/db/framework';
2
+ import { type DataAccess, type DataHandles, type FileBinding, type NewWake, type Session, type SqlTag } from '@fabrika/db/framework';
3
3
  import type { DataKind, UnscopedMode } from '@fabrika/db/tables';
4
4
  import type { SqlMode } from '../contract/context';
5
5
  import { type RequestFrame } from './capability';
@@ -115,11 +115,21 @@ export declare function undeclaredSql(site: string, kind: DataKind, member?: 'ct
115
115
  export declare function jobSqlOutsideTransaction(job: string): SqlTag;
116
116
  /** `tx.sql` of a job site that declares it: its statements run in the attempt's fenced transaction. */
117
117
  export declare function jobSql(frame: RequestFrame, data: DataAccess, mode: SqlMode, session: Session, ended: () => boolean): SqlTag;
118
+ /** The kicks of one invocation, as `ctx.kick` recorded them. */
119
+ export interface KickRecorder {
120
+ readonly kick: (job: string, options?: unknown) => void;
121
+ /** The jobs kicked without `at`, each once: what the dispatcher starts after the commit. */
122
+ readonly kicked: () => readonly string[];
123
+ /** Whether the invocation kicked anything, now or for later. */
124
+ readonly recorded: () => boolean;
125
+ /**
126
+ * Every kick's wake, one per job and due second (`kick:<job>:<due second>`); a kick without `at` is due at `now`. The
127
+ * site writes them in its transaction, so a rollback leaves none.
128
+ */
129
+ readonly wakes: (now: Date) => readonly NewWake[];
130
+ }
118
131
  /**
119
- * `ctx.kick` of one invocation: it names only a declared job, and records it; the dispatcher sends each recorded job once,
120
- * after the commit, and nothing on a rollback.
132
+ * `ctx.kick` of one invocation: it names only a declared job, and records it; the site writes each kick's wake in its
133
+ * transaction, and the dispatcher starts each job kicked without `at` once, after the commit, and nothing on a rollback.
121
134
  */
122
- export declare function kickRecorder(site: string, declared: readonly string[]): {
123
- readonly kick: (job: string) => void;
124
- readonly kicked: () => readonly string[];
125
- };
135
+ export declare function kickRecorder(site: string, declared: readonly string[]): KickRecorder;
@@ -42,6 +42,11 @@ export declare class WorkloadCredential {
42
42
  #private;
43
43
  constructor(options: WorkloadCredentialOptions);
44
44
  authority(): Promise<WorkloadAuthority>;
45
+ /**
46
+ * The caller stopped waiting for `pending`, an answer of `authority()` (its attempt timed out or was stopped): the
47
+ * next call exchanges afresh instead of waiting on an exchange that may never answer.
48
+ */
49
+ abandon(pending: Promise<WorkloadAuthority>): void;
45
50
  }
46
51
  /** The key a workload's credential is found under: `job:<name>`, `webhook:<name>`, `public:<endpoint id>`. */
47
52
  export declare function workloadSite(kind: WorkloadKindOf, name: string): string;
@@ -1,7 +1,7 @@
1
1
  import type { IamMembership } from '@fabrika/auth';
2
2
  import { type ContractArtifact } from '@fabrika/auth-core';
3
3
  import type { CapabilityAuthority } from '@fabrika/db/capability';
4
- import { type DataAccess, type FrameworkTables } from '@fabrika/db/framework';
4
+ import { type DataAccess, type FrameworkTables, type LeaseFence, type Session } from '@fabrika/db/framework';
5
5
  import { type StoredFileKinds } from '../files/kinds';
6
6
  import { type CapabilityMint } from '../implement/capability';
7
7
  import { type PublicEgressRules } from '../implement/egress';
@@ -19,6 +19,11 @@ import { type CronSchedule } from './schedule';
19
19
  export declare const LEASE_GRACE_MS = 60000;
20
20
  /** How often the serving process checks every job for a crashed run and for a schedule that stopped. */
21
21
  export declare const JOB_CHECK_INTERVAL_MS = 60000;
22
+ /**
23
+ * A run the Cloudflare alarm started has one segment (`CLOUDFLARE_MAX_JOB_SEGMENT_MS`): its attempt ends this much
24
+ * before the segment, at most a tenth of it, so the finish runs inside the segment too.
25
+ */
26
+ export declare const SEGMENT_FINISH_RESERVE_MS = 30000;
22
27
  /**
23
28
  * Why a run failed. Fixed codes only: an application error's name and message may carry a secret, so neither is
24
29
  * ever logged or returned. Only the report to Operations carries them, scrubbed (ADR-0059).
@@ -32,7 +37,7 @@ export type JobFailureCode = 'timeout' | 'lease_lost' | 'handler_failed'
32
37
  | 'unauthorized'
33
38
  /** IAM could not be asked for the job's token. */
34
39
  | 'iam_unavailable'
35
- /** The process stopped a kicked run while shutting down; the schedule runs the job again. */
40
+ /** The process stopped a kicked run while shutting down, or the object's maintenance stopped a run; the schedule runs it again. */
36
41
  | 'stopped'
37
42
  /** The transport refused a message the handler did not catch; `reason` is the `EmailDeliveryError` code. */
38
43
  | 'mail_failed';
@@ -57,6 +62,8 @@ export interface JobClock {
57
62
  wait(ms: number, signal: AbortSignal): Promise<void>;
58
63
  /** In [0, 1): the jitter of a retry's backoff. */
59
64
  random(): number;
65
+ /** Epoch milliseconds: what an attempt's deadline is measured on; `Date.now()` when absent. */
66
+ now?(): number;
60
67
  }
61
68
  export interface JobRunOptions {
62
69
  readonly clock?: JobClock;
@@ -89,6 +96,57 @@ export interface ContractJobs {
89
96
  * twice its period. The serving process calls it every `JOB_CHECK_INTERVAL_MS`; it never throws.
90
97
  */
91
98
  check(options?: Pick<JobRunOptions, 'reporter'>): Promise<void>;
99
+ /**
100
+ * The serving process's wake timer on Bun, where crontab runs the schedule: reaps a crashed holder of every job and
101
+ * kicks each contract job with a due wake through the kick path, handing each kick to `track` until it ended. Answers
102
+ * how long until a wake is due next on the database's clock (0 while one still is), `null` when none is pending. The
103
+ * first call deletes the wakes of jobs the contract no longer declares.
104
+ */
105
+ wake(track: (kick: Promise<void>) => void): Promise<number | null>;
106
+ /** What the Cloudflare object's alarm drives the jobs through; `null` without `@fabrika/db`. */
107
+ readonly scheduler: JobScheduler | null;
108
+ }
109
+ /** What the scheduler's `take` did for one job in the alarm's transaction. */
110
+ export interface TakenLease {
111
+ /** The lease a run of the job now holds, for `run`; `null` when nothing was due or another run holds it. */
112
+ readonly fence: LeaseFence | null;
113
+ /** Whether a crashed holder's lease was freed: `crashed` reports it once the transaction committed. */
114
+ readonly reaped: boolean;
115
+ }
116
+ /**
117
+ * The jobs as the Cloudflare object's alarm drives them (ADR-0065 §5): over the wakes and leases of the object's
118
+ * storage, every time on the database's clock. The object holds the transactions and arms the alarm.
119
+ */
120
+ export interface JobScheduler {
121
+ /** Every job bound to run, the framework's included. */
122
+ readonly jobs: readonly string[];
123
+ /**
124
+ * Startup repair: reaps and reports every crashed run, of a job the contract no longer declares too; registers every
125
+ * job and surveils it (as `check`), deletes the wakes of jobs the contract no longer declares and the cron wakes of a
126
+ * changed expression, and keeps one cron wake per job at its next fire; an overdue one stays, so missed runs coalesce
127
+ * into one. `false` when the object's barrier admits no job.
128
+ */
129
+ repair(options?: Pick<JobRunOptions, 'reporter'>): Promise<boolean>;
130
+ /** The jobs the contract no longer declares whose lease a crashed run still holds: `take` reaps them. */
131
+ orphans(): Promise<readonly string[]>;
132
+ /** How long until every wake due within `withinMs` of the database's clock is due; 0 when none is early. */
133
+ earlyBy(withinMs: number): Promise<number>;
134
+ /**
135
+ * Reaps a crashed holder of `job`'s lease, then, when one of its wakes is due, takes the lease, or sets the pending
136
+ * flag for the run holding it; of a job no longer declared (an orphan), only reaps. Statements only, for the caller's
137
+ * one transaction.
138
+ */
139
+ take(job: string): Promise<TakenLease>;
140
+ /** Runs `job` under the lease `take` took. A failed run retries the wakes it owns durably. */
141
+ run(job: string, fence: LeaseFence, options?: JobRunOptions): Promise<JobRunResult>;
142
+ /** Reports the crashed run `take` reaped. */
143
+ crashed(job: string, options?: Pick<JobRunOptions, 'reporter'>): Promise<void>;
144
+ /** When the scheduler wakes next: `JobWakes.next`, read in `using` when given. */
145
+ next(using?: Session): Promise<Date | null>;
146
+ /** How far the next wake is from the database's now, in milliseconds: `JobWakes.untilNext`, read in `using` when given. */
147
+ untilNext(using?: Session): Promise<number | null>;
148
+ /** Reports a failure of the scheduler itself: the alarm's or the repair's. Never rejects. */
149
+ failed(step: 'alarm' | 'repair', error: unknown): Promise<void>;
92
150
  }
93
151
  /** A run that cannot start: an unknown job. Its message is framework-authored. */
94
152
  export declare class JobError extends Error {
@@ -126,6 +126,17 @@ export interface TestKit<C extends AnyContract> {
126
126
  runJob(name: JobName<C> | typeof FILE_SCAN_JOB | typeof FILE_SWEEP_JOB, options?: JobRunOptions): Promise<JobRunResult>;
127
127
  /** Waits for the work requests left running: the runs a site's `ctx.kick` sent, a failure's report. */
128
128
  drain(): Promise<void>;
129
+ /**
130
+ * Runs every job with a wake due now or within `within` ms (0 by default) once, as the Cloudflare object's alarm
131
+ * runs it: the startup repair first (each job's cron wake at its next fire), then each wake ahead moved to now, then
132
+ * each due job under its lease, a failed run's retry moved to its backoff. It first waits for the runs a site's
133
+ * `ctx.kick` sent. Nothing else fires on its own. Handlers keep real time: only the wakes move, never the clock, so
134
+ * a run again schedules its cron fire from now, and a later call skips a cron fire this kit already ran early. Needs
135
+ * the application's data layer.
136
+ */
137
+ runDueJobs(options?: {
138
+ readonly within?: number;
139
+ }): Promise<readonly DueJobRun[]>;
129
140
  /**
130
141
  * The stand-in for every job's transport: what reached it (`accepted`, `handoffs`) and its faults (`refuse`,
131
142
  * `unavailable`, `unreachable`, `loseAnswers`, `during`, `heal`). Each message carries the transport key,
@@ -148,6 +159,11 @@ export interface TestKit<C extends AnyContract> {
148
159
  */
149
160
  solveChallenge(procedure: object): Promise<string>;
150
161
  }
162
+ /** A job `runDueJobs` ran, and its run's result. */
163
+ export interface DueJobRun {
164
+ readonly job: string;
165
+ readonly result: JobRunResult;
166
+ }
151
167
  /** The names of the contract's cron jobs. */
152
168
  export type JobName<C> = C extends {
153
169
  readonly surface: {