@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
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import { type OpsDumpSchema, type OpsImportRequest } from '@fabrika/auth-core';
|
|
2
|
+
import type { SqliteStorage } from '@fabrika/db/sqlite';
|
|
3
|
+
import { type SqliteMigrationBundle } from '@fabrika/db/sqlite-migrate';
|
|
4
|
+
import type { MaintenanceBarrier } from './maintenance.js';
|
|
5
|
+
import type { OpsTarget } from './ops.js';
|
|
6
|
+
/**
|
|
7
|
+
* One step of loading a dump into a fresh object (ADR-0070); `serving` is the object of ordinary traffic. A runtime
|
|
8
|
+
* whose storage has no synchronous KV or `deleteAll` does not serve the operation.
|
|
9
|
+
*/
|
|
10
|
+
export declare function serveImport(target: OpsTarget, barrier: MaintenanceBarrier, step: OpsImportRequest, serving: string): Promise<Response>;
|
|
11
|
+
/** workerd's synchronous KV storage of a SQLite-backed object: it lives in the same database, so it commits with a transaction. */
|
|
12
|
+
export interface ImportKv {
|
|
13
|
+
get(key: string): unknown;
|
|
14
|
+
put(key: string, value: unknown): void;
|
|
15
|
+
delete(key: string): boolean;
|
|
16
|
+
}
|
|
17
|
+
/** What the importer needs of the object's storage; a SQLite-backed `DurableObjectStorage` fits it. */
|
|
18
|
+
export interface ImportStorage extends SqliteStorage {
|
|
19
|
+
readonly kv: ImportKv;
|
|
20
|
+
/** Wipes the object's database, its KV storage and its alarm. */
|
|
21
|
+
deleteAll(): Promise<void>;
|
|
22
|
+
}
|
|
23
|
+
/** The object an import step loads into. */
|
|
24
|
+
export interface ImportTarget {
|
|
25
|
+
readonly storage: ImportStorage;
|
|
26
|
+
/** The environment's bucket (the `FABRIKA_FILES` R2 binding), where the backup lies. */
|
|
27
|
+
readonly bucket: unknown;
|
|
28
|
+
/** The release's migration bundles in the order the object applies them: the framework's, then the application's. */
|
|
29
|
+
readonly migrations: readonly SqliteMigrationBundle[];
|
|
30
|
+
/** The object of ordinary traffic (`FABRIKA_APPLICATION_OBJECT`), which `discard` never wipes. */
|
|
31
|
+
readonly serving: string;
|
|
32
|
+
}
|
|
33
|
+
/** The KV key of the import marker. Invariant: an object that holds it never boots and never leaves `inspect`. */
|
|
34
|
+
export declare const IMPORT_MARKER_KEY = "fabrika:import";
|
|
35
|
+
/** Whether the object holds an import marker, so it must neither boot nor leave `inspect`. */
|
|
36
|
+
export declare function importInProgress(storage: {
|
|
37
|
+
readonly kv: ImportKv;
|
|
38
|
+
}): boolean;
|
|
39
|
+
/**
|
|
40
|
+
* One step of loading the consistent backup `step.source` into the fresh object `target` (ADR-0070 §6), in the
|
|
41
|
+
* barrier's turn: ADR-0069's stale refusal unless `step.generation` is the published one, then `serving_object` on the
|
|
42
|
+
* object of ordinary traffic, then `wrong_mode` unless `inspect`. The turn is held across the step's R2 reads, so the
|
|
43
|
+
* generation and mode it was admitted under still hold when it commits.
|
|
44
|
+
*/
|
|
45
|
+
export declare function importStep(target: ImportTarget, barrier: MaintenanceBarrier, step: OpsImportRequest): Promise<Response>;
|
|
46
|
+
/**
|
|
47
|
+
* The schema `planOpsDump` reads, from the PRAGMAs workerd admits, of every table a dump holds. An `INITIALLY DEFERRED`
|
|
48
|
+
* clause is read from the table's SQL outside its quotes and comments, and marks every foreign key of its table; the
|
|
49
|
+
* names a `CHECK` reads come from the same SQL (`checkNamesOf`).
|
|
50
|
+
*/
|
|
51
|
+
export declare function describeDumpSchema(storage: SqliteStorage): OpsDumpSchema;
|
|
52
|
+
/**
|
|
53
|
+
* The names the `CHECK` clauses of a table's `sql` read: every word and quoted identifier between a `CHECK` keyword's
|
|
54
|
+
* parentheses, ASCII-lowercase, keywords and numbers included, so it lists at least every column a `CHECK` reads. A
|
|
55
|
+
* string literal and a comment name nothing; a double-quoted string, which SQLite may read as either, counts as a name.
|
|
56
|
+
* `null` when the text does not scan (an unclosed quote, comment or parenthesis), which counts as naming every column.
|
|
57
|
+
*/
|
|
58
|
+
export declare function checkNamesOf(sql: string): string[] | null;
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
import { type OpsMaintenance, type OpsMode, type OpsPublishedState, type OpsStateAck } from '@fabrika/auth-core';
|
|
2
|
+
import type { InvocationAdmission, InvocationGate, InvocationKind } from '../implement/dispatch.js';
|
|
3
|
+
export declare const DRAIN_BOUND_MS: number;
|
|
4
|
+
/** The state R2 holds, and its version: the etag a conditional put names. */
|
|
5
|
+
export interface StoredMaintenance {
|
|
6
|
+
readonly state: OpsPublishedState;
|
|
7
|
+
readonly version: string;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Since which generation the object has written nothing, as of the published generation `generation`: kept only while
|
|
11
|
+
* it is `read-only`, `closed` or `inspect`.
|
|
12
|
+
*/
|
|
13
|
+
export interface FrozenRecord {
|
|
14
|
+
readonly generation: number;
|
|
15
|
+
readonly since: number;
|
|
16
|
+
}
|
|
17
|
+
/** The object's durable copy of its maintenance state. */
|
|
18
|
+
export interface MaintenanceStore {
|
|
19
|
+
/** `null` only for a definite not-found; every other failure throws, and is never read as absence. */
|
|
20
|
+
read(): Promise<StoredMaintenance | null>;
|
|
21
|
+
/** Puts `state` if R2 still holds `version` (`null`: holds nothing); the new version, or `null` when the condition failed. */
|
|
22
|
+
put(state: OpsPublishedState, version: string | null): Promise<string | null>;
|
|
23
|
+
/** The frozen record, `null` when none is stored. A store without these keeps the record in memory only. */
|
|
24
|
+
readFrozen?(): Promise<FrozenRecord | null>;
|
|
25
|
+
putFrozen?(record: FrozenRecord): Promise<void>;
|
|
26
|
+
}
|
|
27
|
+
/** `__fabrika/ops/<object>.json` in the environment's bucket (`bucket`, an R2 binding). */
|
|
28
|
+
export declare function r2MaintenanceStore(bucket: unknown, object: string): MaintenanceStore;
|
|
29
|
+
export type TransitionResult = {
|
|
30
|
+
readonly kind: 'acknowledged';
|
|
31
|
+
readonly ack: OpsStateAck;
|
|
32
|
+
}
|
|
33
|
+
/** The 409: what R2 holds as far as the object knows, `null` before the first publication. */
|
|
34
|
+
| {
|
|
35
|
+
readonly kind: 'stale';
|
|
36
|
+
readonly published: OpsPublishedState | null;
|
|
37
|
+
}
|
|
38
|
+
/** R2 could not be read or written: the call fails and Control retries. */
|
|
39
|
+
| {
|
|
40
|
+
readonly kind: 'failed';
|
|
41
|
+
}
|
|
42
|
+
/** The caller's `frozen` held the object in `inspect`: nothing changed. */
|
|
43
|
+
| {
|
|
44
|
+
readonly kind: 'frozen';
|
|
45
|
+
};
|
|
46
|
+
export type MigrateResult<T> = {
|
|
47
|
+
readonly kind: 'migrated';
|
|
48
|
+
readonly value: T;
|
|
49
|
+
} | {
|
|
50
|
+
readonly kind: 'stale';
|
|
51
|
+
readonly published: OpsPublishedState | null;
|
|
52
|
+
};
|
|
53
|
+
/** What a step run in the barrier's turn answers, and what keeps the turn past the answer (`null`: nothing). */
|
|
54
|
+
export interface TurnStep<T> {
|
|
55
|
+
readonly value: T;
|
|
56
|
+
readonly holdUntil: Promise<void> | null;
|
|
57
|
+
}
|
|
58
|
+
export type StepResult<T> = {
|
|
59
|
+
readonly kind: 'ran';
|
|
60
|
+
readonly value: T;
|
|
61
|
+
} | {
|
|
62
|
+
readonly kind: 'stale';
|
|
63
|
+
readonly published: OpsPublishedState | null;
|
|
64
|
+
};
|
|
65
|
+
export interface BarrierOptions {
|
|
66
|
+
/** The drain's bound; `DRAIN_BOUND_MS` by default. */
|
|
67
|
+
readonly drainBoundMs?: number;
|
|
68
|
+
}
|
|
69
|
+
export declare class MaintenanceBarrier {
|
|
70
|
+
#private;
|
|
71
|
+
private constructor();
|
|
72
|
+
/** The cold start: an absent state is `open`; a failed read rejects, and the caller retries on its next request. */
|
|
73
|
+
static load(store: MaintenanceStore, options?: BarrierOptions): Promise<MaintenanceBarrier>;
|
|
74
|
+
get mode(): OpsMode;
|
|
75
|
+
view(): OpsMaintenance;
|
|
76
|
+
/** What R2 holds as far as this instance knows, `null` before the first publication: what a stale refusal names. */
|
|
77
|
+
get published(): OpsPublishedState | null;
|
|
78
|
+
/**
|
|
79
|
+
* The generation at which the object entered its current stretch of `read-only`, `closed` and `inspect`, or at which a
|
|
80
|
+
* data step last wrote within it; `null` outside such a stretch. A consistent dump is one state while it holds.
|
|
81
|
+
*/
|
|
82
|
+
get frozenSince(): number | null;
|
|
83
|
+
/**
|
|
84
|
+
* Called in a data step's turn before the step writes while the object writes nothing else (an import step, a
|
|
85
|
+
* restore's `arm`): the stretch starts again at the current generation, durably before the write. A failed put rejects.
|
|
86
|
+
*/
|
|
87
|
+
restrictedWrite(): Promise<void>;
|
|
88
|
+
/** The scope of one invocation, admitted now: the generation and mode it captures, which its writes are fenced on. */
|
|
89
|
+
event(): BarrierEvent;
|
|
90
|
+
/** Whether a write of an invocation admitted at `generation` in `mode` may commit now. */
|
|
91
|
+
writable(generation: number | null, mode: OpsMode): boolean;
|
|
92
|
+
/** Admits an invocation of `kind` captured at `generation`, or `null` when the mode refuses it or a transition followed. */
|
|
93
|
+
admit(kind: InvocationKind, generation: number | null): InvocationAdmission | null;
|
|
94
|
+
/**
|
|
95
|
+
* `POST /__fabrika/ops/state`: the transition of ADR-0069 §3, acknowledged once published and drained. `frozen` is
|
|
96
|
+
* asked in the turn, after every data step before it: while it holds, no transition leaves `inspect`.
|
|
97
|
+
*/
|
|
98
|
+
transition(requested: OpsPublishedState, frozen?: () => boolean): Promise<TransitionResult>;
|
|
99
|
+
/**
|
|
100
|
+
* `POST /__fabrika/ops/migrate`: `work` runs only under the published generation, in a mode that may migrate, and no
|
|
101
|
+
* transition runs meanwhile.
|
|
102
|
+
*/
|
|
103
|
+
migrate<T>(generation: number, work: () => Promise<T>): Promise<MigrateResult<T>>;
|
|
104
|
+
/**
|
|
105
|
+
* A data step of Control's (ADR-0070): `work` runs in the barrier's turn, only under the published `generation`, with
|
|
106
|
+
* the mode it is in. No transition runs until `work` settles, nor, when it answers one, until `holdUntil` settles.
|
|
107
|
+
*/
|
|
108
|
+
step<T>(generation: number, work: (mode: OpsMode) => Promise<TurnStep<T>>): Promise<StepResult<T>>;
|
|
109
|
+
}
|
|
110
|
+
/** One invocation's view of the barrier: the gate that admits and counts its work, and its write fence. */
|
|
111
|
+
export declare class BarrierEvent implements InvocationGate {
|
|
112
|
+
#private;
|
|
113
|
+
constructor(barrier: MaintenanceBarrier, generation: number | null, mode: OpsMode);
|
|
114
|
+
admit(kind: InvocationKind): InvocationAdmission | null;
|
|
115
|
+
/** Whether this invocation may commit a write now: still `open`, at the generation it was admitted under. */
|
|
116
|
+
writable(): boolean;
|
|
117
|
+
}
|
|
@@ -4,3 +4,8 @@ export declare const CLOUDFLARE_APPLICATION_CLASS = "FabrikaApplication";
|
|
|
4
4
|
export declare const CLOUDFLARE_APPLICATION_BINDING = "FABRIKA_APPLICATION";
|
|
5
5
|
/** The R2 bucket binding of the environment's stored files. */
|
|
6
6
|
export declare const CLOUDFLARE_FILES_BINDING = "FABRIKA_FILES";
|
|
7
|
+
/**
|
|
8
|
+
* The Workers Assets binding the SPA and link mounts serve their files from. Its directory mirrors the request paths:
|
|
9
|
+
* the mount `/admin` serves `<directory>/admin/…`, the root mount `<directory>/…`.
|
|
10
|
+
*/
|
|
11
|
+
export declare const CLOUDFLARE_ASSETS_BINDING = "ASSETS";
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { type ApplicationObjects, type OpsBootFailureContent, type OpsOperation } from '@fabrika/auth-core';
|
|
2
|
-
import type { SqliteCursor, SqliteValue } from '@fabrika/db/sqlite';
|
|
3
|
-
|
|
2
|
+
import type { SqliteCursor, SqliteStorage, SqliteValue } from '@fabrika/db/sqlite';
|
|
3
|
+
import type { SqliteMigrationBundle } from '@fabrika/db/sqlite-migrate';
|
|
4
|
+
import type { MaintenanceBarrier } from './maintenance.js';
|
|
5
|
+
/** What the view reads of the object's storage; workerd's `DurableObjectStorage` has every optional member. */
|
|
4
6
|
export interface OpsStorage {
|
|
5
7
|
readonly sql: {
|
|
6
8
|
exec(query: string, ...bindings: SqliteValue[]): SqliteCursor;
|
|
@@ -9,6 +11,27 @@ export interface OpsStorage {
|
|
|
9
11
|
};
|
|
10
12
|
/** The bun:sqlite test double has no alarm. */
|
|
11
13
|
getAlarm?(): Promise<number | null>;
|
|
14
|
+
/** The object's KV storage, which point-in-time recovery rewinds with its SQLite; the bun:sqlite double has none. */
|
|
15
|
+
get?(key: string): Promise<unknown>;
|
|
16
|
+
put?(key: string, value: unknown): Promise<void>;
|
|
17
|
+
/** The synchronous KV of a SQLite-backed object, in the same database; the bun:sqlite test double has none. */
|
|
18
|
+
readonly kv?: {
|
|
19
|
+
get(key: string): unknown;
|
|
20
|
+
put(key: string, value: unknown): void;
|
|
21
|
+
delete(key: string): boolean;
|
|
22
|
+
};
|
|
23
|
+
/** Wipes the object's database, its KV and its alarm; the bun:sqlite test double has none. */
|
|
24
|
+
deleteAll?(): Promise<void>;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* The object's point-in-time recovery: workerd's storage bookmarks and the abort that resets the object. `null` where the
|
|
28
|
+
* storage has none (the bun:sqlite double, a runtime without PITR).
|
|
29
|
+
*/
|
|
30
|
+
export interface OpsRecovery {
|
|
31
|
+
getCurrentBookmark(): Promise<string>;
|
|
32
|
+
getBookmarkForTime(time: number): Promise<string>;
|
|
33
|
+
onNextSessionRestoreBookmark(bookmark: string): Promise<string>;
|
|
34
|
+
abort(reason: string): void;
|
|
12
35
|
}
|
|
13
36
|
/** `X-Fabrika-Endpoint` of the composed ops row, the only value an ops request may carry (ADR-0022 rule 3). */
|
|
14
37
|
export declare const OPS_ENDPOINT: string;
|
|
@@ -21,16 +44,28 @@ export interface OpsAccess {
|
|
|
21
44
|
export declare function opsAccess(env: Readonly<Record<string, unknown>>): OpsAccess | null;
|
|
22
45
|
/** What an ops request reads of the object it reached. */
|
|
23
46
|
export interface OpsTarget {
|
|
24
|
-
readonly storage: OpsStorage;
|
|
47
|
+
readonly storage: OpsStorage & SqliteStorage;
|
|
48
|
+
/** The environment's bucket (the `FABRIKA_FILES` R2 binding), where dumps and the maintenance state live. */
|
|
49
|
+
readonly bucket: unknown;
|
|
50
|
+
readonly recovery: OpsRecovery | null;
|
|
51
|
+
/** The digest of the contract this release was deployed with (`FABRIKA_CONTRACT_DIGEST`); a dump's manifest records it. */
|
|
52
|
+
readonly contractDigest: string | null;
|
|
53
|
+
/** The release's migration bundles in the order the object applies them: the framework's, then the application's. */
|
|
54
|
+
readonly migrations: readonly SqliteMigrationBundle[];
|
|
25
55
|
/**
|
|
26
56
|
* The instance's last failed boot, the application's error text included. Asked only after authentication: it
|
|
27
57
|
* waits for a boot under way and never starts one.
|
|
28
58
|
*/
|
|
29
59
|
bootFailure(): Promise<OpsBootFailureContent | null>;
|
|
60
|
+
/** The barrier of the object named `object`, read from R2 on a cold start; rejects while R2 cannot be read. */
|
|
61
|
+
maintenance(object: string): Promise<MaintenanceBarrier>;
|
|
62
|
+
/** Runs the pending migrations and boots the application; `false` when the boot failed. */
|
|
63
|
+
migrate(): Promise<boolean>;
|
|
30
64
|
}
|
|
31
65
|
/**
|
|
32
66
|
* Answers an ops request the Worker forwarded with the proxy secret, which the object checked before. Authentication
|
|
33
|
-
* runs first; an unknown operation, a malformed body and an object name the list lacks are refused after it.
|
|
67
|
+
* runs first; an unknown operation, a malformed body and an object name the list lacks are refused after it. Every
|
|
68
|
+
* operation needs the barrier, so while R2 cannot be read each answers 503.
|
|
34
69
|
*/
|
|
35
70
|
export declare function serveOps(request: Request, access: OpsAccess | null, target: OpsTarget): Promise<Response>;
|
|
36
71
|
/** The object an ops request names, read with its operation's strict parser; `null` for a body that does not parse. */
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { type OpsRestoreRequest } from '@fabrika/auth-core';
|
|
2
|
+
import type { MaintenanceBarrier } from './maintenance.js';
|
|
3
|
+
import type { OpsTarget } from './ops.js';
|
|
4
|
+
/**
|
|
5
|
+
* One step of the original object's point-in-time restore (ADR-0070 §9 step 6). `prepare` and `arm` run in the
|
|
6
|
+
* barrier's turn, only under the published generation, on an object that is not the one ordinary traffic reaches
|
|
7
|
+
* (`serving`), while it is `inspect`; `verify` writes nothing and runs in any mode.
|
|
8
|
+
*/
|
|
9
|
+
export declare function serveRestore(target: OpsTarget, barrier: MaintenanceBarrier, step: OpsRestoreRequest, serving: boolean): Promise<Response>;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { type OpsTimersRequest, type OpsTimersView } from '@fabrika/auth-core';
|
|
2
|
+
import { type Scrubber } from '../jobs/scrub.js';
|
|
3
|
+
/** The global timers the tracker wraps while it is on; `globalThis` fits it. */
|
|
4
|
+
export interface TimerScope {
|
|
5
|
+
setTimeout(handler: unknown, delay?: unknown, ...args: unknown[]): unknown;
|
|
6
|
+
setInterval(handler: unknown, delay?: unknown, ...args: unknown[]): unknown;
|
|
7
|
+
clearTimeout(id?: unknown): void;
|
|
8
|
+
clearInterval(id?: unknown): void;
|
|
9
|
+
}
|
|
10
|
+
export interface TimerTracker {
|
|
11
|
+
/** Switches tracking on (wrapping the scope's timers) or off (restoring them and forgetting every record). */
|
|
12
|
+
track(on: boolean): void;
|
|
13
|
+
/**
|
|
14
|
+
* While tracking is on, records `promise` until it settles and answers a chain that settles as it does, rejection
|
|
15
|
+
* included, so the caller hands the chain to `waitUntil` and an unhandled rejection stays unhandled. Off, `promise`.
|
|
16
|
+
*/
|
|
17
|
+
pending<T>(promise: Promise<T>): Promise<T>;
|
|
18
|
+
/** The live records, oldest first, at most `OPS_TIMERS_CAP` of them. */
|
|
19
|
+
view(): OpsTimersView;
|
|
20
|
+
}
|
|
21
|
+
/** A tracker over `scope`'s timers, off until `track(true)`; each stack is scrubbed by `scrubber`. */
|
|
22
|
+
export declare function timerTracker(scope: TimerScope, now: () => number, scrubber: Scrubber): TimerTracker;
|
|
23
|
+
/**
|
|
24
|
+
* Records a promise an object hands to `waitUntil` while the tracker is on. Hand the answer, not `promise`, to
|
|
25
|
+
* `waitUntil`: it rejects as `promise` does, so an unhandled rejection still reaches the crash reporting.
|
|
26
|
+
*/
|
|
27
|
+
export declare function trackPending<T>(promise: Promise<T>): Promise<T>;
|
|
28
|
+
/** The isolate's live timers and `waitUntil` promises; `track` switches the isolate's tracker on or off first. */
|
|
29
|
+
export declare function serveTimers(request: OpsTimersRequest): Response;
|
|
@@ -35,7 +35,8 @@ export interface ContractWorker {
|
|
|
35
35
|
/**
|
|
36
36
|
* The Worker module of a contract application, called only by the generated entrypoint, which also exports
|
|
37
37
|
* `FabrikaApplication`. The application runs in the environment's Durable Object (ADR-0065): `fetch` forwards every
|
|
38
|
-
* request to it with the proxy secret, the proxy's own headers unchanged, and `scheduled` forwards the
|
|
38
|
+
* request to it with the proxy secret, the proxy's own headers unchanged, and `scheduled` forwards the repair tick: the
|
|
39
|
+
* object's alarm runs the jobs, and the tick repairs its wakes and arms an alarm nothing armed yet.
|
|
39
40
|
* An ops request goes to the object its body names instead (ADR-0069). The object captures the environment, imports
|
|
40
41
|
* the application and boots it.
|
|
41
42
|
*/
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { type ContractArtifact, type OutputShape, type SchemaShape } from '@fabrika/auth-core';
|
|
2
2
|
import { z } from 'zod/v4';
|
|
3
|
+
/** A file's object key starts with its kind: the framework keeps its own objects in the files bucket under this prefix. */
|
|
4
|
+
export declare const RESERVED_FILE_KIND_PREFIX = "__fabrika";
|
|
3
5
|
/** A `SchemaShape` read back as JSON. */
|
|
4
6
|
export declare const schemaShapeSchema: z.ZodType<SchemaShape>;
|
|
5
7
|
export declare const outputShapeSchema: z.ZodType<OutputShape>;
|
|
@@ -91,14 +91,24 @@ export type SqlValue = string | number | boolean | bigint | Date | null | readon
|
|
|
91
91
|
export interface SqlTag<Ix extends AnyDbIndex = AnyDbIndex, M extends SqlMode = SqlMode> {
|
|
92
92
|
<Row extends Schema>(row: Row): (text: TemplateStringsArray, ...values: readonly (SqlValue | SqlScope)[]) => Promise<z.output<Row>[]>;
|
|
93
93
|
/**
|
|
94
|
-
* The capability's whole predicate on `table
|
|
95
|
-
*
|
|
96
|
-
* `
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
-
*
|
|
94
|
+
* The capability's whole predicate on `table`: the object's key and every link of its chain for a `Ref`, what
|
|
95
|
+
* `ctx.db.within` matches for a `Within`, every row for `ctx.app`. Interpolated as
|
|
96
|
+
* `where ${ctx.sql.scope(ctx.target, 'tasks', { alias: 't' })}`, its values are bound parameters. `alias` is the
|
|
97
|
+
* table's name in the statement (the table's own by default). `use` states what the statement does with the table:
|
|
98
|
+
* `'read'` (the default) needs an action the table reads with, `'update'` or `'delete'` (a `'write'` site only) that
|
|
99
|
+
* operation's action, checked when the fragment is built. The statement is not read for where the fragment stands:
|
|
100
|
+
* using it as stated is the author's and the approver's to check. A table the capability reaches for no use of this
|
|
101
|
+
* site is a type error here.
|
|
100
102
|
*/
|
|
101
|
-
scope<C extends Ref<string, string> | Within<string, string> | AppCapability<string>, T extends FragmentTable<Ix, C, M>>(capability: C, table: T,
|
|
103
|
+
scope<C extends Ref<string, string> | Within<string, string> | AppCapability<string>, T extends FragmentTable<Ix, C, M>>(capability: C, table: T, options?: SqlScopeOptions): SqlScope;
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* The third argument of `ctx.sql.scope`: the table's alias in the statement, and what the statement does with it. A
|
|
107
|
+
* `'read'` site's `ctx.sql` is refused `'update'` and `'delete'` at run time; a `'write'` site's stays assignable to it.
|
|
108
|
+
*/
|
|
109
|
+
export interface SqlScopeOptions {
|
|
110
|
+
readonly alias?: string;
|
|
111
|
+
readonly use?: 'read' | 'update' | 'delete';
|
|
102
112
|
}
|
|
103
113
|
declare const sqlScope: unique symbol;
|
|
104
114
|
/** What `ctx.sql.scope(…)` builds: only the framework makes one, and only its own tag takes it. */
|
|
@@ -369,13 +379,18 @@ export type PublicContext<K extends KitTypes, Kind extends DataKind, Acts extend
|
|
|
369
379
|
} & NoMail;
|
|
370
380
|
/**
|
|
371
381
|
* `ctx.kick('<job>')` of a site that declares `kicks`: the job runs in the background after the site's transaction
|
|
372
|
-
* committed, once however often it is kicked, and not at all on a rollback.
|
|
382
|
+
* committed, once however often it is kicked, and not at all on a rollback. `ctx.kick('<job>', { at })` runs it at `at`
|
|
383
|
+
* instead. Either way the kick is a durable wake written in the site's transaction, and it carries nothing.
|
|
373
384
|
*/
|
|
374
385
|
export type KickContext<Ks> = [Ks] extends [never] ? {
|
|
375
386
|
readonly kick: Unavailable<"declare kicks: ['<cron job>'] on this site to kick a job after its commit">;
|
|
376
387
|
} : Ks extends readonly (infer N extends string)[] ? {
|
|
377
|
-
kick(job: N): void;
|
|
388
|
+
kick(job: N, options?: KickOptions): void;
|
|
378
389
|
} : never;
|
|
390
|
+
/** When a kicked job runs: at `at`, a `Date`; without options, as soon as the site committed. */
|
|
391
|
+
export interface KickOptions {
|
|
392
|
+
readonly at: Date;
|
|
393
|
+
}
|
|
379
394
|
/** `ctx.tokens.sign('<purpose>', claims, { days })` of a site that declares `signs`: a token of one of those purposes. */
|
|
380
395
|
export type TokensContext<K extends KitTypes, Sg> = [Sg] extends [never] ? {
|
|
381
396
|
readonly tokens: Unavailable<"declare signs: ['<token purpose>'] on this site to sign its tokens">;
|
|
@@ -22,6 +22,16 @@ export declare const PROCEDURE_LIMITS: {
|
|
|
22
22
|
/** The headers of one part of a multipart body, at most. */
|
|
23
23
|
readonly maxPartHeaderBytes: number;
|
|
24
24
|
};
|
|
25
|
+
/**
|
|
26
|
+
* The slowest body a procedure or a webhook waits for: its deadline is `maxBytes` at `bytesPerSecond`, `minMs` at least.
|
|
27
|
+
* The handler's own `timeoutMs` starts after the last byte, so the approval diff names both.
|
|
28
|
+
*/
|
|
29
|
+
export declare const BODY_DEADLINE: {
|
|
30
|
+
readonly bytesPerSecond: number;
|
|
31
|
+
readonly minMs: 30000;
|
|
32
|
+
};
|
|
33
|
+
/** How long a body of at most `maxBytes` may take to arrive. */
|
|
34
|
+
export declare function bodyDeadlineMs(maxBytes: number): number;
|
|
25
35
|
/**
|
|
26
36
|
* A procedure with file fields is `multipart/form-data`: its JSON input travels in the first part, named `input`, and
|
|
27
37
|
* each file in a part named after its field. A field of several files sends one part per file, under its name.
|
|
@@ -37,7 +47,15 @@ export declare const WEBHOOK_LIMITS: {
|
|
|
37
47
|
readonly maxMaxBytes: number;
|
|
38
48
|
readonly timeoutMs: 10000;
|
|
39
49
|
};
|
|
40
|
-
/**
|
|
50
|
+
/**
|
|
51
|
+
* The longest job segment on Cloudflare: setup, one attempt and its finish. A framework policy inside the 15 minutes
|
|
52
|
+
* `waitUntil` keeps an object alive, not a platform guarantee; longer work chunks through claims.
|
|
53
|
+
*/
|
|
54
|
+
export declare const CLOUDFLARE_MAX_JOB_SEGMENT_MS: number;
|
|
55
|
+
/**
|
|
56
|
+
* A job attempt's time limit (`limits.timeoutMs`) and its ceiling, which keeps a lease and a timer within a day. The
|
|
57
|
+
* default is one Cloudflare segment, so a job that declares no limit deploys on either provider.
|
|
58
|
+
*/
|
|
41
59
|
export declare const JOB_LIMITS: {
|
|
42
60
|
readonly timeoutMs: number;
|
|
43
61
|
readonly maxTimeoutMs: number;
|
|
@@ -5,7 +5,7 @@ import type { TokenPurposes } from './token';
|
|
|
5
5
|
export type Path = `/${string}`;
|
|
6
6
|
/** Whether `value` is written as a `Path`; what `buildArtifact` refuses of one is a separate check. */
|
|
7
7
|
export declare function isPath(value: string): value is Path;
|
|
8
|
-
/** A job attempt's time limit:
|
|
8
|
+
/** A job attempt's time limit: 14 minutes by default, at most a day. A job reads no body, so it has no `maxBytes`. */
|
|
9
9
|
export interface JobLimitsOption {
|
|
10
10
|
readonly timeoutMs?: number;
|
|
11
11
|
}
|
|
@@ -74,7 +74,15 @@ export type SignsField<Sg, Purposes extends string> = {
|
|
|
74
74
|
* `fetch` refuses any other while the site runs; a public procedure declares none.
|
|
75
75
|
*/
|
|
76
76
|
export interface EgressField {
|
|
77
|
-
readonly egress?: readonly `https://${string}`[]
|
|
77
|
+
readonly egress?: readonly `https://${string}`[] | Unavailable<"egress: 'public' is a cron job's only: record a row and kick a job that declares it">;
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
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-0071). The guard refuses IP addresses, local and
|
|
82
|
+
* internal names and the installation's own hosts, checks each redirect, and bounds each request's time and body.
|
|
83
|
+
*/
|
|
84
|
+
export interface JobEgressField {
|
|
85
|
+
readonly egress?: readonly `https://${string}`[] | 'public';
|
|
78
86
|
}
|
|
79
87
|
/** Each purpose `signs` names is one of `defineApp`'s `tokens`. */
|
|
80
88
|
type KnownPurposes<Sg, Purposes extends string> = Sg extends readonly (infer P extends string)[] ? [Exclude<P, Purposes>] extends [never] ? LiteralList<Sg> : Unavailable<`signs names ${ListOf<Exclude<P, Purposes>>}, which defineApp's tokens do not declare`> : unknown;
|
|
@@ -4,7 +4,7 @@ import type { z } from 'zod/v4';
|
|
|
4
4
|
import type { Declared, JobKitContext, KickContext, KitImports, KitTypes, NoTablesIndex, SqlMode, TokensContext, WebhookKitContext } from './context';
|
|
5
5
|
import { type ExportAccessDeclaration, type ImportDeclaration, type LinkAccessDeclaration, type ProcedureType } from './declaration';
|
|
6
6
|
import { type Contract, type CreatableDimension, type CronJob, type Export, type InputSchema, type JobLimitsOption, type Kit, type LinkMount, type NotLoose, type Path, type ProcedureTree, type RpcMount, type Schema, type Surface, type WebhookMount } from './define';
|
|
7
|
-
import type { DeclaredFields, EgressField, Endpoint, ExportKit, Group, GroupBuild, GroupInput, GroupKit, KicksField, LimitsOption, LinkGroupKit, ListOf, PendingIn, SignsField } from './group';
|
|
7
|
+
import type { DeclaredFields, EgressField, Endpoint, ExportKit, Group, GroupBuild, GroupInput, GroupKit, JobEgressField, KicksField, LimitsOption, LinkGroupKit, ListOf, PendingIn, SignsField } from './group';
|
|
8
8
|
import type { TokenPurposes } from './token';
|
|
9
9
|
import type { AnyAppVocabulary, AppVocabulary } from './vocabulary';
|
|
10
10
|
/** Fields a builder sets itself: an options object that carries one does not type-check. */
|
|
@@ -31,7 +31,7 @@ export type CronOptions<Acts, S, U, Is, Ix extends AnyDbIndex, M = never, Ks = n
|
|
|
31
31
|
readonly actions: Acts;
|
|
32
32
|
readonly limits?: JobLimitsOption;
|
|
33
33
|
readonly retries?: number;
|
|
34
|
-
} & DeclaredFields<S, U, never, Is, Ix> & MailerField<M> & KicksField<Ks> & SignsField<Sg, Purposes> &
|
|
34
|
+
} & DeclaredFields<S, U, never, Is, Ix> & MailerField<M> & KicksField<Ks> & SignsField<Sg, Purposes> & JobEgressField;
|
|
35
35
|
/** The mail transport a job reaches, inferred from its optional field and then required, like a declared field. */
|
|
36
36
|
type MailerField<M> = {
|
|
37
37
|
/** `'installation'`: the installation's mail transport; `'own'`: the application's own. */
|
|
@@ -1,3 +1,6 @@
|
|
|
1
1
|
import type { SpaAssets } from './implement/dispatch.js';
|
|
2
|
-
/**
|
|
2
|
+
/**
|
|
3
|
+
* Serves each SPA mount from its build directory under `root`; a page route that names no file gets the SPA's
|
|
4
|
+
* `index.html` (`isPageRoute`), and a missing asset is 404.
|
|
5
|
+
*/
|
|
3
6
|
export declare function diskAssets(root: string): SpaAssets;
|
|
@@ -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
|
-
*
|
|
76
|
-
*
|
|
77
|
-
|
|
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';
|
|
@@ -9,6 +10,7 @@ import { type ContractJobs, type HandlerErrorSink } from '../jobs/runner';
|
|
|
9
10
|
import type { ChallengeFetch, ChallengeWork } from './challenge';
|
|
10
11
|
import { type ConnectFetch } from './connect';
|
|
11
12
|
import { type SpaAssets } from './dispatch';
|
|
13
|
+
import { type HostResolver } from './egress';
|
|
12
14
|
import type { CapturedEnvironment } from './environment';
|
|
13
15
|
import type { ContractImplementation } from './implement';
|
|
14
16
|
import { type WorkloadTokenSource } from './workload';
|
|
@@ -32,6 +34,11 @@ export interface BootOptions {
|
|
|
32
34
|
readonly requireProxySecret?: boolean;
|
|
33
35
|
/** The object storage of the stored files, which the Bun adapter opens. Without it, a contract with file kinds does not boot. */
|
|
34
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;
|
|
35
42
|
/**
|
|
36
43
|
* The malware scanner of the scan job of `scan: true` file kinds, which the Bun adapter supplies to a job run
|
|
37
44
|
* (`clamscanScanner`). Without it the scan job leaves every quarantined file quarantined and reports.
|
|
@@ -57,6 +64,11 @@ export interface BootOptions {
|
|
|
57
64
|
* with a job or a webhook does not boot.
|
|
58
65
|
*/
|
|
59
66
|
readonly workloadTokens?: WorkloadTokenSource;
|
|
67
|
+
/**
|
|
68
|
+
* Resolves a host name to its addresses, which the Bun adapter supplies (`node:dns`): a cron job's public egress then
|
|
69
|
+
* refuses a public name of a private address before each hop. A Worker exposes no resolution and passes none.
|
|
70
|
+
*/
|
|
71
|
+
readonly resolveHost?: HostResolver;
|
|
60
72
|
/** What posts a report to Operations' ingest; `fetch` by default. */
|
|
61
73
|
readonly operationsFetch?: (request: Request) => Promise<Response>;
|
|
62
74
|
/** What asks a public procedure's challenge provider to verify a token; `fetch` by default. */
|
|
@@ -96,6 +108,11 @@ export interface BootOptions {
|
|
|
96
108
|
* then `null`.
|
|
97
109
|
*/
|
|
98
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>;
|
|
99
116
|
}
|
|
100
117
|
export interface ContractApp {
|
|
101
118
|
/** `exec` keeps a failure's report to Operations alive past the response (a Worker's `waitUntil`). */
|
|
@@ -11,6 +11,8 @@ export declare const CAPABILITY_REFUSALS: {
|
|
|
11
11
|
readonly undeclared_binding: "the site named a webhook it does not declare in binds";
|
|
12
12
|
readonly undeclared_signs: "the site signed a token of a purpose it does not declare in signs, or for longer than the purpose allows";
|
|
13
13
|
readonly undeclared_egress: "the site called an origin it does not declare in egress";
|
|
14
|
+
readonly refused_egress: "the site's public egress refused the host: an IP address, a local or internal name, a non-default port, a host of this installation, or a name that resolves to a private address";
|
|
15
|
+
readonly oversized_egress: "a response to the site's public egress was larger than it reads";
|
|
14
16
|
readonly wrong_binding: "a webhook binding was handed a capability of another kind or dimension than the webhook is bound to";
|
|
15
17
|
readonly missing_id: "the job named an object without an id";
|
|
16
18
|
readonly wrong_capability: "an operation was handed a capability of another dimension or action than it needs";
|