@fabrika/app 0.9.0-cloudflare.1 → 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.
- package/package.json +9 -9
- package/skill/SKILL.md +21 -17
- package/skill/references/app-setup.md +42 -11
- package/skill/references/endpoint.md +29 -22
- package/skill/references/errors.md +32 -31
- package/skill/references/jobs.md +22 -3
- package/skill/references/tests.md +29 -1
- package/src/build.ts +6 -1
- package/src/bun.ts +168 -5
- package/src/cloudflare/application.ts +546 -76
- package/src/cloudflare/bindings.ts +26 -5
- package/src/cloudflare/export.ts +621 -0
- package/src/cloudflare/import.ts +1097 -0
- package/src/cloudflare/maintenance.ts +518 -0
- package/src/cloudflare/names.ts +6 -0
- package/src/cloudflare/ops.ts +147 -18
- package/src/cloudflare/restore.ts +167 -0
- package/src/cloudflare/tracker.ts +192 -0
- package/src/cloudflare.ts +3 -2
- package/src/contract/artifact-schema.ts +13 -2
- package/src/contract/build.ts +38 -11
- package/src/contract/context.ts +26 -9
- package/src/contract/defaults.ts +22 -2
- package/src/contract/define.ts +1 -1
- package/src/contract/group.ts +10 -1
- package/src/contract/kit.ts +2 -1
- package/src/disk-assets.ts +8 -3
- package/src/files/kinds.ts +54 -24
- package/src/implement/anonymous.ts +1 -10
- package/src/implement/boot.ts +30 -12
- package/src/implement/capability.ts +3 -0
- package/src/implement/dispatch.ts +175 -37
- package/src/implement/egress.ts +367 -8
- package/src/implement/invocation.ts +60 -19
- package/src/implement/workload.ts +18 -3
- package/src/jobs/runner.ts +646 -98
- package/src/spa-fallback.ts +12 -0
- package/src/testing/endpoint-access.ts +135 -23
- package/src/testing/isolation.ts +8 -1
- package/src/testing/kit.ts +60 -0
- package/types/src/build.d.ts +1 -1
- package/types/src/bun.d.ts +34 -1
- package/types/src/cloudflare/application.d.ts +36 -5
- package/types/src/cloudflare/bindings.d.ts +6 -0
- package/types/src/cloudflare/export.d.ts +16 -0
- package/types/src/cloudflare/import.d.ts +58 -0
- package/types/src/cloudflare/maintenance.d.ts +117 -0
- package/types/src/cloudflare/names.d.ts +5 -0
- package/types/src/cloudflare/ops.d.ts +39 -4
- package/types/src/cloudflare/restore.d.ts +9 -0
- package/types/src/cloudflare/tracker.d.ts +29 -0
- package/types/src/cloudflare.d.ts +2 -1
- package/types/src/contract/artifact-schema.d.ts +2 -0
- package/types/src/contract/context.d.ts +24 -9
- package/types/src/contract/defaults.d.ts +19 -1
- package/types/src/contract/define.d.ts +1 -1
- package/types/src/contract/group.d.ts +9 -1
- package/types/src/contract/kit.d.ts +2 -2
- package/types/src/disk-assets.d.ts +4 -1
- package/types/src/files/kinds.d.ts +17 -6
- package/types/src/implement/anonymous.d.ts +0 -4
- package/types/src/implement/boot.d.ts +17 -0
- package/types/src/implement/capability.d.ts +2 -0
- package/types/src/implement/dispatch.d.ts +33 -1
- package/types/src/implement/egress.d.ts +36 -1
- package/types/src/implement/invocation.d.ts +20 -10
- package/types/src/implement/workload.d.ts +5 -0
- package/types/src/jobs/runner.d.ts +63 -2
- package/types/src/spa-fallback.d.ts +2 -0
- package/types/src/testing/endpoint-access.d.ts +25 -1
- package/types/src/testing/isolation.d.ts +1 -1
- package/types/src/testing/kit.d.ts +16 -0
|
@@ -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';
|
|
@@ -11,6 +12,7 @@ import type { BrowserConfig } from './browser-config';
|
|
|
11
12
|
import { type CapabilityMint } from './capability';
|
|
12
13
|
import type { ChallengeIssuer } from './challenge';
|
|
13
14
|
import { type ImportWire } from './connect';
|
|
15
|
+
import { type SiteEgress } from './egress';
|
|
14
16
|
import type { FailureReports } from './failures';
|
|
15
17
|
import { type HeaderPolicy } from './headers';
|
|
16
18
|
import type { ContractDatabase } from './implement';
|
|
@@ -21,6 +23,36 @@ import type { SignedTokens } from './tokens';
|
|
|
21
23
|
import type { AppUrl } from './urls';
|
|
22
24
|
import { type BindableWebhook } from './webhook';
|
|
23
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
|
+
}
|
|
24
56
|
/** SHA-256 of a proxy secret: 32 bytes whatever the secret's length, as `timingSafeEqual` needs. */
|
|
25
57
|
export declare function proxySecretDigest(secret: string): Uint8Array;
|
|
26
58
|
/** Serves the files of an SPA mount. The runtime adapter supplies it: Workers Assets, or the build output on disk. */
|
|
@@ -66,7 +98,7 @@ export type ServedEndpoint = {
|
|
|
66
98
|
/** A staged-kit site, which gets `ctx.db`; a handler `implement` bound has none. */
|
|
67
99
|
readonly site?: ServedSite;
|
|
68
100
|
/** The origins a staged-kit site's `fetch` reaches while its handler runs; absent for a handler `implement` bound. */
|
|
69
|
-
readonly egress?:
|
|
101
|
+
readonly egress?: SiteEgress;
|
|
70
102
|
/** Its buckets and time limit; without them (a generated endpoint) no bucket and the request budget. */
|
|
71
103
|
readonly admission?: ProcedureAdmission;
|
|
72
104
|
/** A POST's `query`, parsed from the URL beside the body: its schema and its shape. */
|
|
@@ -1,5 +1,40 @@
|
|
|
1
|
+
import { type DeclaredEgress } from '@fabrika/auth-core';
|
|
2
|
+
/** The addresses a host name resolves to, where the runtime exposes resolution: Bun's `node:dns`, never a Worker. */
|
|
3
|
+
export type HostResolver = (hostname: string) => Promise<readonly string[]>;
|
|
4
|
+
/** What public egress refuses beyond what a URL alone shows (`publicEgressRefusal`). */
|
|
5
|
+
export interface PublicEgressRules {
|
|
6
|
+
/** The installation's own hosts, normalized: every host a framework variable names, and `FABRIKA_EGRESS_REFUSED_HOSTS`. */
|
|
7
|
+
readonly refusedHosts: ReadonlySet<string>;
|
|
8
|
+
/** Resolves each hop's host before it is sent, so a public name of a private address is refused; `null` on Cloudflare. */
|
|
9
|
+
readonly resolve: HostResolver | null;
|
|
10
|
+
}
|
|
11
|
+
/** What one site's `fetch` reaches: its declared origins, or the rules of public egress. */
|
|
12
|
+
export type SiteEgress = readonly string[] | PublicEgressRules;
|
|
13
|
+
/**
|
|
14
|
+
* The bounds of one request under public egress, the redirects it follows included. The handler's own signal still
|
|
15
|
+
* aborts it sooner (`ctx.signal`, an `AbortSignal.timeout` of its own).
|
|
16
|
+
*/
|
|
17
|
+
export declare const PUBLIC_EGRESS_LIMITS: {
|
|
18
|
+
/** One request, its redirects and the reading of its body included: the abort also stops a body still streaming. */
|
|
19
|
+
readonly timeoutMs: 60000;
|
|
20
|
+
/** One response's body as the handler reads it; a larger one is refused, by its `Content-Length` or while it streams. */
|
|
21
|
+
readonly maxResponseBytes: number;
|
|
22
|
+
/** The redirects one request follows when its `redirect` mode is `follow`, each hop checked again. */
|
|
23
|
+
readonly maxRedirects: 10;
|
|
24
|
+
};
|
|
1
25
|
/** Runs a site's handler: every `fetch` it starts reaches only `egress`. */
|
|
2
|
-
export declare function runAsSite<T>(site: string, egress:
|
|
26
|
+
export declare function runAsSite<T>(site: string, egress: SiteEgress, work: () => Promise<T>): Promise<T>;
|
|
27
|
+
/**
|
|
28
|
+
* The egress a site runs with: its declared origins, or `rules` for `'public'`. Only a cron job's runner holds rules; a
|
|
29
|
+
* site run without them reaches nothing, though the build lets no other site declare `'public'`.
|
|
30
|
+
*/
|
|
31
|
+
export declare function siteEgress(declared: DeclaredEgress, rules: PublicEgressRules | null): SiteEgress;
|
|
32
|
+
/**
|
|
33
|
+
* The rules of public egress in one environment: the hosts its framework variables name (IAM, Operations, its own
|
|
34
|
+
* origin, the platform's receivers, the object store), the installation hosts Control hands it, and the resolver the
|
|
35
|
+
* runtime adapter supplies.
|
|
36
|
+
*/
|
|
37
|
+
export declare function publicEgressRules(framework: Readonly<Record<string, string>>, resolve: HostResolver | null): PublicEgressRules;
|
|
3
38
|
/**
|
|
4
39
|
* `facility` with each of its methods run outside any site's scope: a framework facility a handler calls, whose own
|
|
5
40
|
* requests are the platform's, not the site's.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { type ContractArtifact, type JobMailer } from '@fabrika/auth-core';
|
|
2
|
-
import { type DataAccess, type DataHandles, type FileBinding, type Session, type SqlTag } from '@fabrika/db/framework';
|
|
1
|
+
import { type ContractArtifact, type DeclaredEgress, type JobMailer } from '@fabrika/auth-core';
|
|
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';
|
|
@@ -16,8 +16,8 @@ export interface SiteDeclaration {
|
|
|
16
16
|
readonly binds: string | null;
|
|
17
17
|
/** The token purposes `ctx.tokens.sign` may sign. */
|
|
18
18
|
readonly signs: readonly string[];
|
|
19
|
-
/** The HTTPS origins the global `fetch` reaches while the site's handler runs. */
|
|
20
|
-
readonly egress:
|
|
19
|
+
/** The HTTPS origins the global `fetch` reaches while the site's handler runs, or `'public'`: every public host (a cron job). */
|
|
20
|
+
readonly egress: DeclaredEgress;
|
|
21
21
|
}
|
|
22
22
|
/** A public procedure's reach: the texts the verified signed tokens of its request carry, which name the rows it changes. */
|
|
23
23
|
export interface PublicReach {
|
|
@@ -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
|
|
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,9 +1,10 @@
|
|
|
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
|
+
import { type PublicEgressRules } from '../implement/egress';
|
|
7
8
|
import type { ContractDatabase } from '../implement/implement';
|
|
8
9
|
import type { SignedTokens } from '../implement/tokens';
|
|
9
10
|
import { type AppUrl } from '../implement/urls';
|
|
@@ -18,6 +19,11 @@ import { type CronSchedule } from './schedule';
|
|
|
18
19
|
export declare const LEASE_GRACE_MS = 60000;
|
|
19
20
|
/** How often the serving process checks every job for a crashed run and for a schedule that stopped. */
|
|
20
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;
|
|
21
27
|
/**
|
|
22
28
|
* Why a run failed. Fixed codes only: an application error's name and message may carry a secret, so neither is
|
|
23
29
|
* ever logged or returned. Only the report to Operations carries them, scrubbed (ADR-0059).
|
|
@@ -31,7 +37,7 @@ export type JobFailureCode = 'timeout' | 'lease_lost' | 'handler_failed'
|
|
|
31
37
|
| 'unauthorized'
|
|
32
38
|
/** IAM could not be asked for the job's token. */
|
|
33
39
|
| 'iam_unavailable'
|
|
34
|
-
/** The process stopped a kicked run while shutting down; the schedule runs
|
|
40
|
+
/** The process stopped a kicked run while shutting down, or the object's maintenance stopped a run; the schedule runs it again. */
|
|
35
41
|
| 'stopped'
|
|
36
42
|
/** The transport refused a message the handler did not catch; `reason` is the `EmailDeliveryError` code. */
|
|
37
43
|
| 'mail_failed';
|
|
@@ -56,6 +62,8 @@ export interface JobClock {
|
|
|
56
62
|
wait(ms: number, signal: AbortSignal): Promise<void>;
|
|
57
63
|
/** In [0, 1): the jitter of a retry's backoff. */
|
|
58
64
|
random(): number;
|
|
65
|
+
/** Epoch milliseconds: what an attempt's deadline is measured on; `Date.now()` when absent. */
|
|
66
|
+
now?(): number;
|
|
59
67
|
}
|
|
60
68
|
export interface JobRunOptions {
|
|
61
69
|
readonly clock?: JobClock;
|
|
@@ -88,6 +96,57 @@ export interface ContractJobs {
|
|
|
88
96
|
* twice its period. The serving process calls it every `JOB_CHECK_INTERVAL_MS`; it never throws.
|
|
89
97
|
*/
|
|
90
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>;
|
|
91
150
|
}
|
|
92
151
|
/** A run that cannot start: an unknown job. Its message is framework-authored. */
|
|
93
152
|
export declare class JobError extends Error {
|
|
@@ -130,6 +189,8 @@ export interface JobBindingInput {
|
|
|
130
189
|
readonly tokens?: SignedTokens;
|
|
131
190
|
/** `ctx.url`: absolute links to the application's own procedures; without it every link is refused. */
|
|
132
191
|
readonly url?: AppUrl;
|
|
192
|
+
/** The rules of public egress, which `boot` reads from the environment; without them a public job reaches nothing. */
|
|
193
|
+
readonly publicEgress?: PublicEgressRules;
|
|
133
194
|
}
|
|
134
195
|
export interface BoundJobs {
|
|
135
196
|
readonly jobs: ContractJobs;
|
|
@@ -78,6 +78,30 @@ export interface EndpointAccessKit {
|
|
|
78
78
|
*/
|
|
79
79
|
anyone(endpoint: string, input: Readonly<Record<string, unknown>>): Promise<ReachOutcome>;
|
|
80
80
|
}
|
|
81
|
+
export interface EndpointAccessOptions {
|
|
82
|
+
/**
|
|
83
|
+
* The file every case of an endpoint sends in a file field instead of the kit's sample, by endpoint id and input
|
|
84
|
+
* field: a file of the application's repository that a handler inspecting the content accepts (a valid package). Its
|
|
85
|
+
* type is the first of the field's kind that its bytes are; a file of none of them throws. `files` of the fixtures.
|
|
86
|
+
*/
|
|
87
|
+
readonly files?: Readonly<Record<string, Readonly<Record<string, URL>>>>;
|
|
88
|
+
/**
|
|
89
|
+
* The error types of the refusals (400) an endpoint's handler answers its own object with when the case's input meets
|
|
90
|
+
* no domain rule the kit can satisfy, by endpoint id: such a 400 is the handler's own answer, so the request passed
|
|
91
|
+
* the access form, and the endpoint's own case gets it as `{ status: 400 }` instead of failing; so does the other
|
|
92
|
+
* scope's request a leak case makes first. The own scope's answer of a leak case, and a global or capability case,
|
|
93
|
+
* still throw on it (an answer that holds nothing proves no isolation), so does any other 400, and an input the schema
|
|
94
|
+
* refuses (`validation`) always does. `refusals` of the fixtures.
|
|
95
|
+
*/
|
|
96
|
+
readonly refusals?: Readonly<Record<string, readonly string[]>>;
|
|
97
|
+
/**
|
|
98
|
+
* Known values for text columns of the row the endpoint addresses (the row of the table that owns its dimension), by
|
|
99
|
+
* endpoint id: the value in the own scope's row, and `<value>-other` in the other scope's, which counts among the
|
|
100
|
+
* other scope's values a leak shows. For a handler whose rule ties a column to the input or a file fixture (a package
|
|
101
|
+
* that names the skill's slug). `pins` of the fixtures.
|
|
102
|
+
*/
|
|
103
|
+
readonly pins?: Readonly<Record<string, Readonly<Record<string, string>>>>;
|
|
104
|
+
}
|
|
81
105
|
export type Grant = {
|
|
82
106
|
readonly action: string;
|
|
83
107
|
readonly scope: {
|
|
@@ -104,4 +128,4 @@ export declare const managerGrants: (artifact: Pick<ContractArtifact, "roles">,
|
|
|
104
128
|
* The endpoint access kit of `app`, whose data layer is `scoped(tables)`, over `postgres`. It boots `app` once, so the
|
|
105
129
|
* application's layer is bound here and nowhere else in the process.
|
|
106
130
|
*/
|
|
107
|
-
export declare function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract>, tables: Tables<DB, P>, postgres: TestDatabase): EndpointAccessKit;
|
|
131
|
+
export declare function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract>, tables: Tables<DB, P>, postgres: TestDatabase, options?: EndpointAccessOptions): EndpointAccessKit;
|
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
export { type DeniedOutcome, type EndpointAccessKit, endpointAccessKit, type LeakOutcome, type ReachOutcome } from './endpoint-access';
|
|
1
|
+
export { type DeniedOutcome, type EndpointAccessKit, endpointAccessKit, type EndpointAccessOptions, type LeakOutcome, type ReachOutcome, } from './endpoint-access';
|
|
2
2
|
export { type AppCaller, type AppCountOutcome, type AppIsolationKit, appPolicyIsolationKit, type ChildIsolationRow, type CountOutcome, type IsolationOutcome, type IsolationRow, type ListOutcome, type MisuseOutcome, type PolicyIsolationKit, policyIsolationKit, type ReadOutcome, } from './policy-isolation';
|
|
3
3
|
export { afterAll, describe, expect, test } from './runner';
|
|
@@ -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: {
|