@fabrika/app 0.9.0-dev.4 → 0.9.0-dev.5
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 +41 -14
- package/skill/references/app-setup.md +43 -12
- package/skill/references/dev.md +2 -1
- package/skill/references/endpoint.md +30 -24
- package/skill/references/errors.md +40 -35
- package/skill/references/files.md +4 -2
- package/skill/references/jobs.md +21 -4
- package/skill/references/table-and-migration.md +19 -2
- package/skill/references/tests.md +40 -1
- package/skill/references/webhooks-links-connectors.md +1 -1
- package/src/build-recipe.ts +198 -0
- package/src/build.ts +60 -4
- package/src/bun.ts +181 -13
- package/src/cloudflare/application.ts +822 -0
- package/src/cloudflare/bindings.ts +159 -0
- package/src/cloudflare/export.ts +641 -0
- package/src/cloudflare/import.ts +1021 -0
- package/src/cloudflare/maintenance.ts +518 -0
- package/src/cloudflare/names.ts +16 -0
- package/src/cloudflare/ops.ts +375 -0
- package/src/cloudflare/r2-files.ts +172 -0
- package/src/cloudflare/restore.ts +167 -0
- package/src/cloudflare/tracker.ts +192 -0
- package/src/cloudflare.ts +100 -146
- package/src/contract/app-id.ts +5 -0
- package/src/contract/artifact-schema.ts +9 -1
- package/src/contract/build.ts +40 -2
- package/src/contract/compile.ts +1 -0
- package/src/contract/context.ts +35 -9
- package/src/contract/declaration.ts +2 -0
- package/src/contract/defaults.ts +22 -2
- package/src/contract/define.ts +29 -3
- package/src/contract/kit.ts +4 -1
- package/src/contract/platform.ts +3 -2
- package/src/contract/vocabulary.ts +26 -8
- package/src/dev/launcher.ts +50 -4
- package/src/disk-assets.ts +8 -3
- package/src/files/archive.ts +2 -2
- package/src/files/job-names.ts +12 -0
- package/src/files/kinds.ts +73 -31
- package/src/files/scan.ts +3 -4
- package/src/files/streams.ts +3 -1
- package/src/implement/anonymous.ts +12 -11
- package/src/implement/boot.ts +75 -6
- package/src/implement/bounded.ts +21 -2
- package/src/implement/capability.ts +15 -3
- package/src/implement/dispatch.ts +419 -177
- package/src/implement/failures.ts +17 -1
- package/src/implement/faults.ts +1 -0
- package/src/implement/index.ts +1 -0
- package/src/implement/invocation.ts +58 -10
- package/src/implement/principal.ts +25 -2
- package/src/implement/terminals.ts +93 -0
- package/src/implement/workload.ts +42 -16
- package/src/jobs/mail.ts +8 -0
- package/src/jobs/report.ts +5 -1
- package/src/jobs/runner.ts +672 -113
- package/src/jobs/schedule.ts +7 -1
- package/src/jobs/scrub.ts +14 -1
- package/src/jobs/types.ts +6 -0
- package/src/spa-fallback.ts +12 -0
- package/src/testing/endpoint-access.ts +307 -152
- package/src/testing/isolation.ts +8 -1
- package/src/testing/kit.ts +80 -2
- package/src/testing/proxy.ts +15 -10
- package/types/src/build-recipe.d.ts +70 -0
- package/types/src/build.d.ts +19 -1
- package/types/src/bun.d.ts +34 -1
- package/types/src/cloudflare/application.d.ts +73 -0
- package/types/src/cloudflare/bindings.d.ts +33 -0
- package/types/src/cloudflare/export.d.ts +16 -0
- package/types/src/cloudflare/import.d.ts +51 -0
- package/types/src/cloudflare/maintenance.d.ts +117 -0
- package/types/src/cloudflare/names.d.ts +11 -0
- package/types/src/cloudflare/ops.d.ts +81 -0
- package/types/src/cloudflare/r2-files.d.ts +9 -0
- package/types/src/cloudflare/restore.d.ts +9 -0
- package/types/src/cloudflare/tracker.d.ts +29 -0
- package/types/src/cloudflare.d.ts +12 -18
- package/types/src/contract/app-id.d.ts +2 -0
- package/types/src/contract/artifact-schema.d.ts +2 -0
- package/types/src/contract/context.d.ts +35 -11
- package/types/src/contract/declaration.d.ts +4 -0
- package/types/src/contract/defaults.d.ts +19 -1
- package/types/src/contract/define.d.ts +20 -3
- package/types/src/contract/kit.d.ts +2 -1
- package/types/src/contract/platform.d.ts +2 -2
- package/types/src/contract/vocabulary.d.ts +9 -7
- package/types/src/disk-assets.d.ts +4 -1
- package/types/src/files/job-names.d.ts +9 -0
- package/types/src/files/kinds.d.ts +21 -14
- package/types/src/files/scan.d.ts +1 -3
- package/types/src/implement/anonymous.d.ts +2 -4
- package/types/src/implement/boot.d.ts +17 -1
- package/types/src/implement/bounded.d.ts +11 -1
- package/types/src/implement/capability.d.ts +4 -2
- package/types/src/implement/dispatch.d.ts +34 -1
- package/types/src/implement/failures.d.ts +5 -0
- package/types/src/implement/faults.d.ts +1 -0
- package/types/src/implement/index.d.ts +1 -0
- package/types/src/implement/invocation.d.ts +22 -7
- package/types/src/implement/principal.d.ts +6 -1
- package/types/src/implement/terminals.d.ts +33 -0
- package/types/src/implement/workload.d.ts +5 -0
- package/types/src/jobs/runner.d.ts +66 -2
- package/types/src/jobs/schedule.d.ts +2 -0
- package/types/src/jobs/types.d.ts +6 -0
- package/types/src/spa-fallback.d.ts +2 -0
- package/types/src/testing/endpoint-access.d.ts +37 -5
- package/types/src/testing/isolation.d.ts +1 -1
- package/types/src/testing/kit.d.ts +22 -1
- package/types/src/testing/proxy.d.ts +4 -4
|
@@ -7,16 +7,15 @@ import type { OperationsReporter } from '../jobs/report';
|
|
|
7
7
|
import type { OpenedFile } from './handle';
|
|
8
8
|
import { type FileScanner } from './scan';
|
|
9
9
|
import { FileDownload } from './treatment';
|
|
10
|
-
|
|
11
|
-
* The framework's sweep job: hourly, it deletes the files no declared column references and the pending ones past the
|
|
12
|
-
* grace, so none waits for the next request. A reserved name with `-`, which no `c.cron` name can take;
|
|
13
|
-
* `@fabrika/provider-zerops` writes it into the crontab on this schedule (`ZEROPS_FILE_SWEEP_JOB`).
|
|
14
|
-
*/
|
|
15
|
-
export declare const FILE_SWEEP_JOB = "fabrika-file-sweep";
|
|
16
|
-
export declare const FILE_SWEEP_SCHEDULE = "41 * * * *";
|
|
10
|
+
export { FILE_SWEEP_JOB, FILE_SWEEP_SCHEDULE } from './job-names';
|
|
17
11
|
export declare const FILE_SWEEP_TIMEOUT_MS: number;
|
|
18
12
|
/** How long a staged file waits for its first reference before the sweep may delete it. */
|
|
19
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;
|
|
20
19
|
/** One file part of a multipart body, as the multipart reader hands it over. */
|
|
21
20
|
export interface FilePart {
|
|
22
21
|
readonly filename: string | null;
|
|
@@ -41,7 +40,10 @@ export declare class FileWork {
|
|
|
41
40
|
readonly request: string;
|
|
42
41
|
constructor(holder: object, request: string);
|
|
43
42
|
staged(id: string): void;
|
|
43
|
+
/** The work wrote the object of a file it staged, under a key no other file has. */
|
|
44
|
+
wrote(id: string, objectKey: string): void;
|
|
44
45
|
get stagedIds(): readonly string[];
|
|
46
|
+
writtenKey(id: string): string | null;
|
|
45
47
|
}
|
|
46
48
|
interface Kind {
|
|
47
49
|
readonly name: string;
|
|
@@ -49,7 +51,7 @@ interface Kind {
|
|
|
49
51
|
}
|
|
50
52
|
export declare class StoredFileKinds {
|
|
51
53
|
#private;
|
|
52
|
-
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);
|
|
53
55
|
/** Whether the contract declares kind `name`. */
|
|
54
56
|
has(name: string): boolean;
|
|
55
57
|
/** Whether any kind scans, so the scan job runs. */
|
|
@@ -75,9 +77,14 @@ export declare class StoredFileKinds {
|
|
|
75
77
|
/** The answer of a procedure whose output is a file: the file the handler returned, streamed. */
|
|
76
78
|
download(work: FileWork, endpoint: string, kind: string, reference: unknown): Promise<FileDownload>;
|
|
77
79
|
/**
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
|
|
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.
|
|
81
88
|
*/
|
|
82
89
|
sweep(signal: AbortSignal): Promise<void>;
|
|
83
90
|
/** One scan pass over the quarantined files of every scanning kind: the scan job's part for kinds. */
|
|
@@ -99,7 +106,7 @@ export declare function storedFilesHandle(kinds: StoredFileKinds | null, work: F
|
|
|
99
106
|
};
|
|
100
107
|
/**
|
|
101
108
|
* The file kinds of `artifact`, or `null` when it declares none. Every reason a kind cannot be served goes into
|
|
102
|
-
* `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`.
|
|
103
111
|
*/
|
|
104
|
-
export declare function storedFileKinds(artifact: ContractArtifact, database: ImplementationDatabase | null, store: FileObjectStore | undefined, problems: string[]): StoredFileKinds | null;
|
|
105
|
-
export {};
|
|
112
|
+
export declare function storedFileKinds(artifact: ContractArtifact, database: ImplementationDatabase | null, store: FileObjectStore | undefined, problems: string[], retentionMs: number): StoredFileKinds | null;
|
|
@@ -1,9 +1,7 @@
|
|
|
1
1
|
import type { QuarantinedStoredFile } from '@fabrika/db/framework';
|
|
2
2
|
import type { FileObjectStore } from '@fabrika/platform';
|
|
3
3
|
import type { OperationsReporter } from '../jobs/report';
|
|
4
|
-
|
|
5
|
-
export declare const FILE_SCAN_JOB = "fabrika-file-scan";
|
|
6
|
-
export declare const FILE_SCAN_SCHEDULE = "* * * * *";
|
|
4
|
+
export { FILE_SCAN_JOB, FILE_SCAN_SCHEDULE } from './job-names';
|
|
7
5
|
export declare const SCAN_LIMITS: {
|
|
8
6
|
/** One pass scans at most this many files, and at most `batchBytes` of them; the next pass takes the rest. */
|
|
9
7
|
readonly batchFiles: 20;
|
|
@@ -1,13 +1,11 @@
|
|
|
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.
|
|
9
5
|
*/
|
|
10
6
|
export declare function readBoundedBody(request: Request, maxBytes: number, deadline?: AbortSignal): Promise<Uint8Array<ArrayBuffer>>;
|
|
7
|
+
/** `readBoundedBody` within the deadline `maxBytes` derives; the deadline ends with the read. */
|
|
8
|
+
export declare function readBodyInTime(request: Request, maxBytes: number): Promise<Uint8Array<ArrayBuffer>>;
|
|
11
9
|
/** What a request answers whose body did not arrive whole: nobody reads it, and no failure is reported. */
|
|
12
10
|
export declare function abortedBody(): HttpError;
|
|
13
11
|
/**
|
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
import { type IamMembershipRpc, type Jwks } from '@fabrika/auth-core';
|
|
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';
|
|
@@ -32,6 +33,11 @@ export interface BootOptions {
|
|
|
32
33
|
readonly requireProxySecret?: boolean;
|
|
33
34
|
/** The object storage of the stored files, which the Bun adapter opens. Without it, a contract with file kinds does not boot. */
|
|
34
35
|
readonly files?: FileObjectStore;
|
|
36
|
+
/**
|
|
37
|
+
* How long a removed file's object outlives its row, so a restored backup's rows find their files:
|
|
38
|
+
* `FILE_TOMBSTONE_RETENTION_MS` on Cloudflare. Zero when omitted, as on Bun.
|
|
39
|
+
*/
|
|
40
|
+
readonly fileRetentionMs?: number;
|
|
35
41
|
/**
|
|
36
42
|
* The malware scanner of the scan job of `scan: true` file kinds, which the Bun adapter supplies to a job run
|
|
37
43
|
* (`clamscanScanner`). Without it the scan job leaves every quarantined file quarantined and reports.
|
|
@@ -42,6 +48,11 @@ export interface BootOptions {
|
|
|
42
48
|
* creates scopes, manages members or issues share links does not boot.
|
|
43
49
|
*/
|
|
44
50
|
readonly membership?: IamMembershipRpc;
|
|
51
|
+
/**
|
|
52
|
+
* IAM's identification operations at a terminal (ADR-0067): the IAM binding on Cloudflare, `HttpIamTerminals`
|
|
53
|
+
* elsewhere. Without it, a contract that declares a terminal does not boot.
|
|
54
|
+
*/
|
|
55
|
+
readonly terminals?: IamTerminalRpc;
|
|
45
56
|
/**
|
|
46
57
|
* Cloudflare service bindings to the owners' proxy Workers, by binding name (`FABRIKA_CONNECT_<IMPORT>`). An import
|
|
47
58
|
* without one calls its owner with `fetch`.
|
|
@@ -91,6 +102,11 @@ export interface BootOptions {
|
|
|
91
102
|
* then `null`.
|
|
92
103
|
*/
|
|
93
104
|
readonly clientAddress?: 'vouched';
|
|
105
|
+
/**
|
|
106
|
+
* Runs in the transaction of every change of a job's wakes or lease (`DataLayerRuntime.projectWakes`): the Cloudflare
|
|
107
|
+
* object arms its alarm there. Bun supplies none.
|
|
108
|
+
*/
|
|
109
|
+
readonly projectWakes?: (transaction: Session) => Promise<void>;
|
|
94
110
|
}
|
|
95
111
|
export interface ContractApp {
|
|
96
112
|
/** `exec` keeps a failure's report to Operations alive past the response (a Worker's `waitUntil`). */
|
|
@@ -4,8 +4,18 @@
|
|
|
4
4
|
* both runtimes stop a handler at the same point.
|
|
5
5
|
*/
|
|
6
6
|
export declare const REQUEST_BUDGET_MS = 10000;
|
|
7
|
+
/** A signal that aborts once its time passed, and a `clear` its work calls when it settles. */
|
|
8
|
+
export interface Deadline {
|
|
9
|
+
readonly signal: AbortSignal;
|
|
10
|
+
clear(): void;
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* Aborts like `AbortSignal.timeout(ms)`, or when `parent` aborts. Its timer is cleared by `clear`, which every caller
|
|
14
|
+
* runs in `finally`: workerd counts a pending timer as work, so an uncleared one keeps a Durable Object awake.
|
|
15
|
+
*/
|
|
16
|
+
export declare function deadline(ms: number, parent?: AbortSignal): Deadline;
|
|
7
17
|
/** A handler's `ctx.signal`: aborted when the client leaves (`request.signal`) or once `budgetMs` passed. */
|
|
8
|
-
export declare function handlerSignal(request: Request, budgetMs?: number):
|
|
18
|
+
export declare function handlerSignal(request: Request, budgetMs?: number): Deadline;
|
|
9
19
|
export interface BoundedRead {
|
|
10
20
|
readonly maxBytes: number;
|
|
11
21
|
/** `Content-Length`, when the sender declared one: a larger value is refused before anything is read. */
|
|
@@ -82,13 +82,15 @@ export declare class Within<D extends string, A extends string> implements Withi
|
|
|
82
82
|
readonly dimension: D;
|
|
83
83
|
readonly action: A;
|
|
84
84
|
};
|
|
85
|
-
constructor(token: typeof MINT, issuer: object, frame: RequestFrame, dimension: D, action: A, principal: string, values: readonly string[] | 'all', containers: readonly ContainerGrant[]);
|
|
85
|
+
constructor(token: typeof MINT, issuer: object, frame: RequestFrame, dimension: D, action: A, principal: string, values: readonly string[] | 'all', containers: readonly ContainerGrant[], contained: readonly ContainerGrant[]);
|
|
86
86
|
get dimension(): D;
|
|
87
87
|
get action(): A;
|
|
88
88
|
/** The values of this dimension itself. */
|
|
89
89
|
get values(): readonly string[] | 'all';
|
|
90
90
|
/** The containers in which the caller also holds the action: `organization → [o1]` for a workspace list. */
|
|
91
91
|
get containers(): readonly ContainerGrant[];
|
|
92
|
+
/** The dimensions inside this one in which the caller holds the action: `note → [n1]` for a workspace list. */
|
|
93
|
+
get contained(): readonly ContainerGrant[];
|
|
92
94
|
}
|
|
93
95
|
/**
|
|
94
96
|
* One action held as a global grant, in one request: what an `app` endpoint's `ctx.db.app` is built from. The proxy
|
|
@@ -123,7 +125,7 @@ export declare class RowRef<T extends string, A extends string> implements RowRe
|
|
|
123
125
|
/** Makes the capabilities one authority accepts; a runtime's is held by the `boot` call that made it alone. */
|
|
124
126
|
export interface CapabilityMint {
|
|
125
127
|
ref<D extends string, A extends string>(frame: RequestFrame, dimension: D, action: A, principal: string, id: string, chain: ReadonlyMap<string, string>): Ref<D, A>;
|
|
126
|
-
within<D extends string, A extends string>(frame: RequestFrame, dimension: D, action: A, principal: string, values: readonly string[] | 'all', containers?: readonly ContainerGrant[]): Within<D, A>;
|
|
128
|
+
within<D extends string, A extends string>(frame: RequestFrame, dimension: D, action: A, principal: string, values: readonly string[] | 'all', containers?: readonly ContainerGrant[], contained?: readonly ContainerGrant[]): Within<D, A>;
|
|
127
129
|
app<A extends string>(frame: RequestFrame, action: A, principal: string): AppCapability<A>;
|
|
128
130
|
}
|
|
129
131
|
/** A mint and the one authority that accepts what it mints. */
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { IamMembership } from '@fabrika/auth';
|
|
2
|
-
import { type CompiledEndpointTable, type CredentialedEndpoint, type EndpointRow, type ExportDescription, type SchemaShape, type ScopeBinding, type WebhookScheme } from '@fabrika/auth-core';
|
|
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';
|
|
@@ -21,6 +22,36 @@ import type { SignedTokens } from './tokens';
|
|
|
21
22
|
import type { AppUrl } from './urls';
|
|
22
23
|
import { type BindableWebhook } from './webhook';
|
|
23
24
|
import type { WorkloadCredential } from './workload';
|
|
25
|
+
/** The classes of invocation an object's maintenance barrier admits per mode, counts and drains (ADR-0069 §3). */
|
|
26
|
+
export type InvocationKind = 'read' | 'write' | 'webhook' | 'kick' | 'job' | 'framework-job';
|
|
27
|
+
/** One admitted invocation, counted until it settles. */
|
|
28
|
+
export interface InvocationAdmission {
|
|
29
|
+
/** Aborts when a drain stops the invocation. */
|
|
30
|
+
readonly signal: AbortSignal;
|
|
31
|
+
/** Counts `work` the invocation handed on until it settles, past the invocation's own end. */
|
|
32
|
+
track(work: Promise<unknown>): void;
|
|
33
|
+
/** Ends the invocation's own count; called once it settled. */
|
|
34
|
+
release(): void;
|
|
35
|
+
}
|
|
36
|
+
/** What a Cloudflare object's barrier puts around each of its events; `null` refuses an invocation. */
|
|
37
|
+
export interface InvocationGate {
|
|
38
|
+
admit(kind: InvocationKind): InvocationAdmission | null;
|
|
39
|
+
}
|
|
40
|
+
/** Runs `work` with `gate` admitting every invocation it starts, the background work it hands on included. */
|
|
41
|
+
export declare function runGated<T>(gate: InvocationGate, work: () => T): T;
|
|
42
|
+
/** Admits an invocation of `kind` at the current event's gate; outside an object every invocation is admitted, uncounted. */
|
|
43
|
+
export declare function admitInvocation(kind: InvocationKind): InvocationAdmission | null;
|
|
44
|
+
/** The answer while maintenance refuses an invocation: 503 with `Retry-After`, the fixed body of every 503. */
|
|
45
|
+
export declare function maintenanceRefusal(): Response;
|
|
46
|
+
/**
|
|
47
|
+
* A write the object's write fence refused: the invocation was admitted before a restrictive transition (ADR-0069 §3).
|
|
48
|
+
* A `DatabaseError`, so `@fabrika/db` passes it through its normalization of statement and commit failures unchanged;
|
|
49
|
+
* its fixed text names no statement or value. Dispatch answers it as `maintenanceRefusal()`.
|
|
50
|
+
*/
|
|
51
|
+
export declare class MaintenanceFenceError extends DatabaseError {
|
|
52
|
+
name: string;
|
|
53
|
+
constructor();
|
|
54
|
+
}
|
|
24
55
|
/** SHA-256 of a proxy secret: 32 bytes whatever the secret's length, as `timingSafeEqual` needs. */
|
|
25
56
|
export declare function proxySecretDigest(secret: string): Uint8Array;
|
|
26
57
|
/** Serves the files of an SPA mount. The runtime adapter supplies it: Workers Assets, or the build output on disk. */
|
|
@@ -176,6 +207,8 @@ export interface RuntimeParts {
|
|
|
176
207
|
readonly assets: SpaAssets | null;
|
|
177
208
|
/** IAM's membership operations; `boot` refuses a contract that needs them when the adapter supplies none. */
|
|
178
209
|
readonly membership: IamMembership | null;
|
|
210
|
+
/** IAM's identification operations, where the contract declares a terminal; `boot` refuses one without them. */
|
|
211
|
+
readonly terminals: IamTerminalRpc | null;
|
|
179
212
|
/** The framework's own writes (admission buckets, webhook tables); `boot` refuses a webhook or a bucket without them. */
|
|
180
213
|
readonly framework: FrameworkTables | null;
|
|
181
214
|
/** This runtime's capability mint, which `boot` alone holds, and the authority its stores are bound to. */
|
|
@@ -31,4 +31,9 @@ export declare class FailureReports {
|
|
|
31
31
|
constructor(reporter: OperationsReporter | null, now?: () => number);
|
|
32
32
|
/** Never rejects. The returned delivery may outlive the response; a runtime with `waitUntil` keeps it alive. */
|
|
33
33
|
record(failure: RequestFailure): Promise<void>;
|
|
34
|
+
/**
|
|
35
|
+
* A writing invocation that held its object's transaction past `@fabrika/db`'s report threshold, which already
|
|
36
|
+
* logged it. Never rejects; the delivery may outlive the response like a failure's.
|
|
37
|
+
*/
|
|
38
|
+
held(endpoint: string, heldMs: number): Promise<void>;
|
|
34
39
|
}
|
|
@@ -16,6 +16,7 @@ export declare const SERVER_FAULTS: {
|
|
|
16
16
|
readonly webhook_unverifiable: "a webhook verifies a signature over its public URL (Twilio), and the environment has no FABRIKA_APP_ORIGIN";
|
|
17
17
|
readonly webhook_claim_lost: "a delivery's claim expired and another copy of the delivery took it over before this one committed; nothing it wrote is kept";
|
|
18
18
|
readonly workload_unauthorized: "the workload's key or token does not carry the authority its declaration needs";
|
|
19
|
+
readonly terminal_refused: "IAM refused the application's own credential for an identification at a terminal";
|
|
19
20
|
readonly request_cancelled: "the request was cancelled or outlived its budget before its transaction committed; nothing it wrote is kept";
|
|
20
21
|
readonly file_object_missing: "a file's object is missing from storage";
|
|
21
22
|
readonly file_object_mismatch: "a file's object has another size than its row records";
|
|
@@ -19,6 +19,7 @@ export { isContractImplementation } from './implement';
|
|
|
19
19
|
export type { ApplicationDirectory, ApplicationMember, ApplicationMemberPage, ApplicationMemberRole, AssignedMember, DirectoryMember, IssuedLink, LinkIssuing, Member, MemberDirectory, MemberList, MemberLookup, MemberManagement, MemberTarget, } from './membership';
|
|
20
20
|
export type { AppPrincipal, LinkHolder, Principal, PrincipalOf, PublicPrincipal, ServicePrincipal, UserPrincipal } from './principal';
|
|
21
21
|
export { type AppDeps, defineDeps, serve, type ServeOptions } from './serve';
|
|
22
|
+
export type { AssertedIdentity, OpenIdentification, TerminalIdentification } from './terminals';
|
|
22
23
|
export type { AccessContext, ConnectCall, ConnectContext, ConnectSnapshots, ContractContext, ExactHandlers, Handler, HandlerInput, HandlersOf, RequestClient, RequestContext, WebhookHandler, } from './types';
|
|
23
24
|
export type { WebhookDelivery, WebhookPrincipal } from './webhook';
|
|
24
25
|
export { issuerWorkloadTokens, type WorkloadTokenSource } from './workload';
|
|
@@ -1,5 +1,5 @@
|
|
|
1
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';
|
|
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';
|
|
@@ -75,6 +75,11 @@ export declare class Invocation {
|
|
|
75
75
|
readonly check: () => void;
|
|
76
76
|
readonly session: () => Promise<Session>;
|
|
77
77
|
};
|
|
78
|
+
/**
|
|
79
|
+
* Runs `work`, from the handler to `commit`, in this invocation's transaction. On SQLite it encloses `work`, and a
|
|
80
|
+
* hold past `@fabrika/db`'s report threshold reaches `held`, logged under `site`.
|
|
81
|
+
*/
|
|
82
|
+
enclose<T>(work: () => Promise<T>, site: string, held: (heldMs: number) => void): Promise<T>;
|
|
78
83
|
/** Commits; a request the caller abandoned meanwhile rolls back instead. */
|
|
79
84
|
commit(signal: AbortSignal | null): Promise<void>;
|
|
80
85
|
rollback(): Promise<void>;
|
|
@@ -110,11 +115,21 @@ export declare function undeclaredSql(site: string, kind: DataKind, member?: 'ct
|
|
|
110
115
|
export declare function jobSqlOutsideTransaction(job: string): SqlTag;
|
|
111
116
|
/** `tx.sql` of a job site that declares it: its statements run in the attempt's fenced transaction. */
|
|
112
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
|
+
}
|
|
113
131
|
/**
|
|
114
|
-
* `ctx.kick` of one invocation: it names only a declared job, and records it; the
|
|
115
|
-
* 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.
|
|
116
134
|
*/
|
|
117
|
-
export declare function kickRecorder(site: string, declared: readonly string[]):
|
|
118
|
-
readonly kick: (job: string) => void;
|
|
119
|
-
readonly kicked: () => readonly string[];
|
|
120
|
-
};
|
|
135
|
+
export declare function kickRecorder(site: string, declared: readonly string[]): KickRecorder;
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type AccessTokenClaims, type Caller, type PermissionEntry } from '@fabrika/auth-core';
|
|
1
|
+
import { type AccessTokenClaims, type Caller, type PermissionEntry, type TerminalTokenClaims } from '@fabrika/auth-core';
|
|
2
2
|
import type { PageCaller } from '../client/caller';
|
|
3
3
|
/** A person: the IAM session, or a `px_` key bound to a user principal. */
|
|
4
4
|
export interface UserPrincipal {
|
|
@@ -8,6 +8,11 @@ export interface UserPrincipal {
|
|
|
8
8
|
readonly label: string;
|
|
9
9
|
/** The mailbox IAM recorded for the person, lower-cased: the one to mail, not proof of possession. Only a person has one. */
|
|
10
10
|
readonly email: string;
|
|
11
|
+
/**
|
|
12
|
+
* The enrolled terminal the person signed in on, when an application asserted them there (ADR-0067); absent for every
|
|
13
|
+
* other sign-in. Information for the handler: what the session may do is in its permissions already.
|
|
14
|
+
*/
|
|
15
|
+
readonly terminal?: TerminalTokenClaims;
|
|
11
16
|
}
|
|
12
17
|
/** A machine: a `px_` key bound to a service principal. */
|
|
13
18
|
export interface ServicePrincipal {
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { IamTerminalRpc, IdentificationTerminal, MembershipCaller } from '@fabrika/auth-core';
|
|
2
|
+
/** An open identification: the terminal it was opened on and when it expires (unix seconds). */
|
|
3
|
+
export interface OpenIdentification {
|
|
4
|
+
readonly terminal: IdentificationTerminal;
|
|
5
|
+
readonly expiresAt: number;
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* IAM's answer to an assertion: the URL the browser goes to next, or why IAM refused. `not_found` is an identification
|
|
9
|
+
* that is unknown, expired, used, cancelled or no longer open to this application; `invalid_principal` a principal
|
|
10
|
+
* that cannot sign in on a terminal (unknown, disabled, not a person, or external).
|
|
11
|
+
*/
|
|
12
|
+
export type AssertedIdentity = {
|
|
13
|
+
readonly ok: true;
|
|
14
|
+
readonly completionUrl: string;
|
|
15
|
+
} | {
|
|
16
|
+
readonly ok: false;
|
|
17
|
+
readonly reason: 'not_found' | 'invalid_principal';
|
|
18
|
+
};
|
|
19
|
+
/** `ctx.terminals` of an application that declares `terminal: { identify }`. */
|
|
20
|
+
export interface TerminalIdentification {
|
|
21
|
+
/** The open identification `id` (the page's `identification` query parameter), or null when there is none. */
|
|
22
|
+
inspect(id: string): Promise<OpenIdentification | null>;
|
|
23
|
+
/**
|
|
24
|
+
* The application's word that `principalId` stands at the identification's terminal. IAM uses the identification up
|
|
25
|
+
* and, on `ok`, the handler sends the browser to `completionUrl`: IAM signs the person in there, and only on the
|
|
26
|
+
* terminal's own browser.
|
|
27
|
+
*/
|
|
28
|
+
assert(id: string, principalId: string): Promise<AssertedIdentity>;
|
|
29
|
+
/** Ends an identification the person abandoned; one that is no longer open is already ended. */
|
|
30
|
+
cancel(id: string): Promise<void>;
|
|
31
|
+
}
|
|
32
|
+
/** `ctx.terminals` for one request: every call carries the request's credential and correlation id. */
|
|
33
|
+
export declare function terminalIdentification(rpc: IamTerminalRpc, caller: MembershipCaller): TerminalIdentification;
|
|
@@ -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 { ContractDatabase } from '../implement/implement';
|
|
@@ -10,6 +10,7 @@ import { type AppUrl } from '../implement/urls';
|
|
|
10
10
|
import { type WorkloadCredential } from '../implement/workload';
|
|
11
11
|
import { type MailTransports } from './mail';
|
|
12
12
|
import type { OperationsReporter } from './report';
|
|
13
|
+
import { type CronSchedule } from './schedule';
|
|
13
14
|
/**
|
|
14
15
|
* The lease outlives an attempt's deadline by this much: the runner renews or finishes a timed-out attempt's lease,
|
|
15
16
|
* and no other run takes it over meanwhile. The attempt's writes stop at its deadline regardless.
|
|
@@ -17,6 +18,11 @@ import type { OperationsReporter } from './report';
|
|
|
17
18
|
export declare const LEASE_GRACE_MS = 60000;
|
|
18
19
|
/** How often the serving process checks every job for a crashed run and for a schedule that stopped. */
|
|
19
20
|
export declare const JOB_CHECK_INTERVAL_MS = 60000;
|
|
21
|
+
/**
|
|
22
|
+
* A run the Cloudflare alarm started has one segment (`CLOUDFLARE_MAX_JOB_SEGMENT_MS`): its attempt ends this much
|
|
23
|
+
* before the segment, at most a tenth of it, so the finish runs inside the segment too.
|
|
24
|
+
*/
|
|
25
|
+
export declare const SEGMENT_FINISH_RESERVE_MS = 30000;
|
|
20
26
|
/**
|
|
21
27
|
* Why a run failed. Fixed codes only: an application error's name and message may carry a secret, so neither is
|
|
22
28
|
* ever logged or returned. Only the report to Operations carries them, scrubbed (ADR-0059).
|
|
@@ -30,7 +36,7 @@ export type JobFailureCode = 'timeout' | 'lease_lost' | 'handler_failed'
|
|
|
30
36
|
| 'unauthorized'
|
|
31
37
|
/** IAM could not be asked for the job's token. */
|
|
32
38
|
| 'iam_unavailable'
|
|
33
|
-
/** The process stopped a kicked run while shutting down; the schedule runs
|
|
39
|
+
/** The process stopped a kicked run while shutting down, or the object's maintenance stopped a run; the schedule runs it again. */
|
|
34
40
|
| 'stopped'
|
|
35
41
|
/** The transport refused a message the handler did not catch; `reason` is the `EmailDeliveryError` code. */
|
|
36
42
|
| 'mail_failed';
|
|
@@ -55,6 +61,8 @@ export interface JobClock {
|
|
|
55
61
|
wait(ms: number, signal: AbortSignal): Promise<void>;
|
|
56
62
|
/** In [0, 1): the jitter of a retry's backoff. */
|
|
57
63
|
random(): number;
|
|
64
|
+
/** Epoch milliseconds: what an attempt's deadline is measured on; `Date.now()` when absent. */
|
|
65
|
+
now?(): number;
|
|
58
66
|
}
|
|
59
67
|
export interface JobRunOptions {
|
|
60
68
|
readonly clock?: JobClock;
|
|
@@ -76,12 +84,68 @@ export interface FrameworkJob {
|
|
|
76
84
|
export interface ContractJobs {
|
|
77
85
|
/** The contract's `c.cron` jobs; `run` also takes the name of a framework job the contract needs. */
|
|
78
86
|
readonly names: readonly string[];
|
|
87
|
+
/** Every job bound to run, the framework's included, with its schedule: what a minute tick runs when due. */
|
|
88
|
+
readonly scheduled: readonly {
|
|
89
|
+
readonly name: string;
|
|
90
|
+
readonly schedule: CronSchedule;
|
|
91
|
+
}[];
|
|
79
92
|
run(name: string, options?: JobRunOptions): Promise<JobRunResult>;
|
|
80
93
|
/**
|
|
81
94
|
* Registers every job (its first-seen time), reports a run that crashed and a job that has not succeeded within
|
|
82
95
|
* twice its period. The serving process calls it every `JOB_CHECK_INTERVAL_MS`; it never throws.
|
|
83
96
|
*/
|
|
84
97
|
check(options?: Pick<JobRunOptions, 'reporter'>): Promise<void>;
|
|
98
|
+
/**
|
|
99
|
+
* The serving process's wake timer on Bun, where crontab runs the schedule: reaps a crashed holder of every job and
|
|
100
|
+
* kicks each contract job with a due wake through the kick path, handing each kick to `track` until it ended. Answers
|
|
101
|
+
* how long until a wake is due next on the database's clock (0 while one still is), `null` when none is pending. The
|
|
102
|
+
* first call deletes the wakes of jobs the contract no longer declares.
|
|
103
|
+
*/
|
|
104
|
+
wake(track: (kick: Promise<void>) => void): Promise<number | null>;
|
|
105
|
+
/** What the Cloudflare object's alarm drives the jobs through; `null` without `@fabrika/db`. */
|
|
106
|
+
readonly scheduler: JobScheduler | null;
|
|
107
|
+
}
|
|
108
|
+
/** What the scheduler's `take` did for one job in the alarm's transaction. */
|
|
109
|
+
export interface TakenLease {
|
|
110
|
+
/** The lease a run of the job now holds, for `run`; `null` when nothing was due or another run holds it. */
|
|
111
|
+
readonly fence: LeaseFence | null;
|
|
112
|
+
/** Whether a crashed holder's lease was freed: `crashed` reports it once the transaction committed. */
|
|
113
|
+
readonly reaped: boolean;
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* The jobs as the Cloudflare object's alarm drives them (ADR-0065 §5): over the wakes and leases of the object's
|
|
117
|
+
* storage, every time on the database's clock. The object holds the transactions and arms the alarm.
|
|
118
|
+
*/
|
|
119
|
+
export interface JobScheduler {
|
|
120
|
+
/** Every job bound to run, the framework's included. */
|
|
121
|
+
readonly jobs: readonly string[];
|
|
122
|
+
/**
|
|
123
|
+
* Startup repair: reaps and reports every crashed run, of a job the contract no longer declares too; registers every
|
|
124
|
+
* job and surveils it (as `check`), deletes the wakes of jobs the contract no longer declares and the cron wakes of a
|
|
125
|
+
* changed expression, and keeps one cron wake per job at its next fire; an overdue one stays, so missed runs coalesce
|
|
126
|
+
* into one. `false` when the object's barrier admits no job.
|
|
127
|
+
*/
|
|
128
|
+
repair(options?: Pick<JobRunOptions, 'reporter'>): Promise<boolean>;
|
|
129
|
+
/** The jobs the contract no longer declares whose lease a crashed run still holds: `take` reaps them. */
|
|
130
|
+
orphans(): Promise<readonly string[]>;
|
|
131
|
+
/** How long until every wake due within `withinMs` of the database's clock is due; 0 when none is early. */
|
|
132
|
+
earlyBy(withinMs: number): Promise<number>;
|
|
133
|
+
/**
|
|
134
|
+
* Reaps a crashed holder of `job`'s lease, then, when one of its wakes is due, takes the lease, or sets the pending
|
|
135
|
+
* flag for the run holding it; of a job no longer declared (an orphan), only reaps. Statements only, for the caller's
|
|
136
|
+
* one transaction.
|
|
137
|
+
*/
|
|
138
|
+
take(job: string): Promise<TakenLease>;
|
|
139
|
+
/** Runs `job` under the lease `take` took. A failed run retries the wakes it owns durably. */
|
|
140
|
+
run(job: string, fence: LeaseFence, options?: JobRunOptions): Promise<JobRunResult>;
|
|
141
|
+
/** Reports the crashed run `take` reaped. */
|
|
142
|
+
crashed(job: string, options?: Pick<JobRunOptions, 'reporter'>): Promise<void>;
|
|
143
|
+
/** When the scheduler wakes next: `JobWakes.next`, read in `using` when given. */
|
|
144
|
+
next(using?: Session): Promise<Date | null>;
|
|
145
|
+
/** How far the next wake is from the database's now, in milliseconds: `JobWakes.untilNext`, read in `using` when given. */
|
|
146
|
+
untilNext(using?: Session): Promise<number | null>;
|
|
147
|
+
/** Reports a failure of the scheduler itself: the alarm's or the repair's. Never rejects. */
|
|
148
|
+
failed(step: 'alarm' | 'repair', error: unknown): Promise<void>;
|
|
85
149
|
}
|
|
86
150
|
/** A run that cannot start: an unknown job. Its message is framework-authored. */
|
|
87
151
|
export declare class JobError extends Error {
|
|
@@ -9,6 +9,8 @@ export interface CronSchedule {
|
|
|
9
9
|
}
|
|
10
10
|
/** The schedule of a five-field expression, or `null` when it is not one this runner reads. */
|
|
11
11
|
export declare function parseCron(expression: string): CronSchedule | null;
|
|
12
|
+
/** Whether the schedule is due in the UTC minute that holds `at`: what a Worker's minute tick runs (ADR-0065). */
|
|
13
|
+
export declare function isDueAt(schedule: CronSchedule, at: Date): boolean;
|
|
12
14
|
/** The latest `count` due minutes at or before `at`, newest first; fewer when the schedule is that rare. */
|
|
13
15
|
export declare function previousDue(schedule: CronSchedule, at: Date, count: number): Date[];
|
|
14
16
|
/** The time between the two latest due minutes at or before `at`, or `null` when there are not two in the window. */
|
|
@@ -50,6 +50,12 @@ export interface AppMailMessage {
|
|
|
50
50
|
readonly unsubscribe?: {
|
|
51
51
|
readonly url: string;
|
|
52
52
|
};
|
|
53
|
+
/**
|
|
54
|
+
* One message of a send to many recipients (a newsletter, an announcement), not a reply to what the recipient did.
|
|
55
|
+
* The transport sends it on the provider's channel for broadcast mail, which keeps it apart from sign-in links and
|
|
56
|
+
* receipts. It needs `unsubscribe`. A transport without `capabilities.broadcast` refuses it as `invalid_message`.
|
|
57
|
+
*/
|
|
58
|
+
readonly broadcast?: boolean;
|
|
53
59
|
/**
|
|
54
60
|
* Files the message carries: references this attempt holds and may read, as `ctx.files.open` takes them. Only a
|
|
55
61
|
* `live` file is sent; the bytes of all of them together stay within the transport's `maxAttachmentBytes`, and a
|
|
@@ -28,6 +28,12 @@ export type ReachOutcome = {
|
|
|
28
28
|
};
|
|
29
29
|
/** Column → value of the row of the table that owns the endpoint's dimension, in both scopes: the author's seed. */
|
|
30
30
|
export type Seed = Readonly<Record<string, SampleValue>>;
|
|
31
|
+
/**
|
|
32
|
+
* Table → column → value: one row of each application table the handler reads for the caller's own scope, seeded
|
|
33
|
+
* before a leak or an own case asks and removed once it is over, with every row that refers to it, so no other case
|
|
34
|
+
* finds it. Both scopes may see it, so its values are never counted as the other scope's.
|
|
35
|
+
*/
|
|
36
|
+
export type AppRows = Readonly<Record<string, Seed>>;
|
|
31
37
|
export interface EndpointAccessKit {
|
|
32
38
|
/**
|
|
33
39
|
* A caller holding the endpoint's action in one scope names an object (`on`) or a scope value (`in`) of another;
|
|
@@ -36,16 +42,18 @@ export interface EndpointAccessKit {
|
|
|
36
42
|
denied(endpoint: string, input: Readonly<Record<string, unknown>>, seed?: Seed): Promise<DeniedOutcome>;
|
|
37
43
|
/**
|
|
38
44
|
* A caller of the other scope asks first, then a caller of one scope asks for its own object (`on`), its list
|
|
39
|
-
* (`over`) or, for every table that lies in the dimension, its scope value (`in`).
|
|
45
|
+
* (`over`) or, for every table that lies in the dimension, its scope value (`in`). `appRows` are seeded first, as
|
|
46
|
+
* for `own`.
|
|
40
47
|
*/
|
|
41
|
-
leaked(endpoint: string, input: Readonly<Record<string, unknown>>, seed?: Seed): Promise<LeakOutcome>;
|
|
48
|
+
leaked(endpoint: string, input: Readonly<Record<string, unknown>>, seed?: Seed, appRows?: AppRows): Promise<LeakOutcome>;
|
|
42
49
|
/**
|
|
43
50
|
* A caller that holds only the endpoint's action asks for its own object: a person or a script in its scope, or, on
|
|
44
51
|
* a link mount, the holder of a link bound to the object. A write action reads its own target. Where IAM requires more
|
|
45
52
|
* of the caller, it holds that too: a member manager an assigning role and the assigned role's actions, a link's
|
|
46
|
-
* issuer the actions the link grants.
|
|
53
|
+
* issuer the actions the link grants. `appRows` are the rows of application tables its handler reads (the guide a link
|
|
54
|
+
* holder downloads), each seeded first.
|
|
47
55
|
*/
|
|
48
|
-
own(endpoint: string, input: Readonly<Record<string, unknown>>, seed?: Seed): Promise<DeniedOutcome>;
|
|
56
|
+
own(endpoint: string, input: Readonly<Record<string, unknown>>, seed?: Seed, appRows?: AppRows): Promise<DeniedOutcome>;
|
|
49
57
|
/**
|
|
50
58
|
* An `app` or a `creates` endpoint asked by a caller who holds its action in one value of a dimension only, never
|
|
51
59
|
* globally: refused (403), by the proxy for `app` and by IAM for `creates`, since both need a global grant.
|
|
@@ -70,6 +78,30 @@ export interface EndpointAccessKit {
|
|
|
70
78
|
*/
|
|
71
79
|
anyone(endpoint: string, input: Readonly<Record<string, unknown>>): Promise<ReachOutcome>;
|
|
72
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
|
+
}
|
|
73
105
|
export type Grant = {
|
|
74
106
|
readonly action: string;
|
|
75
107
|
readonly scope: {
|
|
@@ -96,4 +128,4 @@ export declare const managerGrants: (artifact: Pick<ContractArtifact, "roles">,
|
|
|
96
128
|
* The endpoint access kit of `app`, whose data layer is `scoped(tables)`, over `postgres`. It boots `app` once, so the
|
|
97
129
|
* application's layer is bound here and nowhere else in the process.
|
|
98
130
|
*/
|
|
99
|
-
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';
|