@fabrika/app 0.9.0-cloudflare.3 → 0.9.0-dev.10
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 +6 -3
- package/skill/references/app-setup.md +8 -8
- package/skill/references/dev.md +3 -1
- package/skill/references/endpoint.md +9 -9
- package/skill/references/errors.md +42 -34
- package/skill/references/files.md +4 -2
- package/skill/references/jobs.md +18 -12
- package/skill/references/table-and-migration.md +31 -4
- package/skill/references/tests.md +22 -10
- package/src/bun.ts +0 -10
- package/src/cloudflare/import.ts +3 -212
- package/src/contract/artifact-schema.ts +1 -6
- package/src/contract/build.ts +10 -33
- package/src/contract/capability-cases.ts +30 -0
- package/src/contract/containers.ts +19 -0
- package/src/contract/group.ts +1 -10
- package/src/contract/index.ts +1 -0
- package/src/contract/kit.ts +1 -2
- package/src/files/handle.ts +2 -1
- package/src/files/kinds.ts +1 -1
- package/src/implement/boot.ts +12 -30
- package/src/implement/capability.ts +1 -4
- package/src/implement/dispatch.ts +8 -5
- package/src/implement/egress.ts +8 -367
- package/src/implement/failures.ts +42 -3
- package/src/implement/faults.ts +4 -1
- package/src/implement/invocation.ts +13 -11
- package/src/implement/tokens.ts +4 -2
- package/src/implement/types.ts +22 -4
- package/src/jobs/runner.ts +32 -20
- package/src/testing/endpoint-access.ts +30 -23
- package/src/testing/index.ts +1 -1
- package/src/testing/kit.ts +6 -2
- package/src/testing/policy-isolation.ts +2 -2
- package/types/src/cloudflare/import.d.ts +1 -12
- package/types/src/contract/capability-cases.d.ts +9 -0
- package/types/src/contract/containers.d.ts +3 -0
- package/types/src/contract/group.d.ts +1 -9
- package/types/src/contract/index.d.ts +1 -0
- package/types/src/contract/kit.d.ts +2 -2
- package/types/src/files/handle.d.ts +2 -1
- package/types/src/implement/boot.d.ts +6 -9
- package/types/src/implement/capability.d.ts +1 -3
- package/types/src/implement/dispatch.d.ts +1 -2
- package/types/src/implement/egress.d.ts +1 -36
- package/types/src/implement/failures.d.ts +21 -2
- package/types/src/implement/faults.d.ts +4 -1
- package/types/src/implement/invocation.d.ts +6 -5
- package/types/src/implement/types.d.ts +25 -5
- package/types/src/jobs/runner.d.ts +14 -8
- package/types/src/testing/endpoint-access.d.ts +4 -3
- package/types/src/testing/index.d.ts +1 -1
- package/types/src/testing/kit.d.ts +6 -2
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
import type { OperationsReporter } from '../jobs/report';
|
|
2
2
|
export type RequestFailureCode = 'framework_fault' | 'unavailable' | 'capability_refused' | 'query_refused' | 'handler_status' | 'handler_failed';
|
|
3
|
+
/**
|
|
4
|
+
* Where the author's own run shows what a request's 5xx or a job attempt threw, whole, with where it happened:
|
|
5
|
+
* `fabrika app dev` sets one, and a test may pass one to the kit. No deployed application has one.
|
|
6
|
+
*/
|
|
7
|
+
export type HandlerErrorSink = (where: string, error: unknown) => void;
|
|
8
|
+
/**
|
|
9
|
+
* Hands `error` to the author's sink, if there is one. A sink that throws (a test's `expect` inside it) changes nothing
|
|
10
|
+
* of the failure it was shown: the failure is classified, logged and reported as without it.
|
|
11
|
+
*/
|
|
12
|
+
export declare function reveal(sink: HandlerErrorSink | null, where: string, error: unknown): void;
|
|
3
13
|
/** At most this many request failures per process and minute become Operations events; every one is logged. */
|
|
4
14
|
export declare const MAX_FAILURE_REPORTS_PER_MINUTE = 30;
|
|
5
15
|
/** Chosen by `instanceof` against the framework's own classes, never by `name`, which any thrown value can set. */
|
|
@@ -14,6 +24,8 @@ export declare function failureReason(error: unknown): FailureReason | null;
|
|
|
14
24
|
export interface RequestFailure {
|
|
15
25
|
/** The endpoint id the request selected, or `request` before one was selected. */
|
|
16
26
|
readonly endpoint: string;
|
|
27
|
+
/** Whether the request selected an endpoint, so `endpoint` is its id and not the fallback. */
|
|
28
|
+
readonly selected: boolean;
|
|
17
29
|
/** The proxy's `X-Request-Id`. */
|
|
18
30
|
readonly requestId: string | null;
|
|
19
31
|
readonly status: number;
|
|
@@ -25,10 +37,17 @@ export declare class MinuteBudget {
|
|
|
25
37
|
constructor(limit: number, now?: () => number);
|
|
26
38
|
admit(): boolean;
|
|
27
39
|
}
|
|
40
|
+
export interface FailureReportsOptions {
|
|
41
|
+
readonly now?: () => number;
|
|
42
|
+
readonly reveal?: HandlerErrorSink | null;
|
|
43
|
+
}
|
|
28
44
|
export declare class FailureReports {
|
|
29
45
|
#private;
|
|
30
|
-
/**
|
|
31
|
-
|
|
46
|
+
/**
|
|
47
|
+
* `reporter` is `null` without an Operations DSN: the log line is then the only record. `reveal` is `boot`'s
|
|
48
|
+
* `revealHandlerErrors`, set on the author's own run only; `now` is the budget's clock.
|
|
49
|
+
*/
|
|
50
|
+
constructor(reporter: OperationsReporter | null, options?: FailureReportsOptions);
|
|
32
51
|
/** Never rejects. The returned delivery may outlive the response; a runtime with `waitUntil` keeps it alive. */
|
|
33
52
|
record(failure: RequestFailure): Promise<void>;
|
|
34
53
|
/**
|
|
@@ -36,7 +36,10 @@ export declare const SERVER_FAULTS: {
|
|
|
36
36
|
readonly url_unbuildable: "ctx.url named no procedure of the contract, passed a parameter its HTTP shape does not read, or the environment has no public origin";
|
|
37
37
|
};
|
|
38
38
|
export type ServerFaultReason = keyof typeof SERVER_FAULTS;
|
|
39
|
-
/**
|
|
39
|
+
/**
|
|
40
|
+
* A failure the framework itself describes. Its message is for the author's own run (`revealHandlerErrors`), never the
|
|
41
|
+
* response or a log.
|
|
42
|
+
*/
|
|
40
43
|
export declare class ServerFault extends Error {
|
|
41
44
|
readonly name = "ServerFault";
|
|
42
45
|
readonly reason: ServerFaultReason;
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type ContractArtifact, type
|
|
1
|
+
import { type ContractArtifact, type JobMailer } from '@fabrika/auth-core';
|
|
2
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';
|
|
@@ -16,8 +16,8 @@ export interface SiteDeclaration {
|
|
|
16
16
|
readonly binds: string | null;
|
|
17
17
|
/** The token purposes `ctx.tokens.sign` may sign. */
|
|
18
18
|
readonly signs: readonly string[];
|
|
19
|
-
/** The HTTPS origins the global `fetch` reaches while the site's handler runs
|
|
20
|
-
readonly egress:
|
|
19
|
+
/** The HTTPS origins the global `fetch` reaches while the site's handler runs. */
|
|
20
|
+
readonly egress: readonly string[];
|
|
21
21
|
}
|
|
22
22
|
/** A public procedure's reach: the texts the verified signed tokens of its request carry, which name the rows it changes. */
|
|
23
23
|
export interface PublicReach {
|
|
@@ -106,9 +106,10 @@ export declare function siteData(handles: DataHandles, app: (action: string) =>
|
|
|
106
106
|
export declare function boundWebhookApp(webhook: string): (action: string) => never;
|
|
107
107
|
/**
|
|
108
108
|
* The handles of a job attempt, outside its fenced transaction (`'job'`, each read on its own) or inside it. `tickMs`,
|
|
109
|
-
* the job's schedule period, is a queue claim's first backoff
|
|
109
|
+
* the job's schedule period, is a queue claim's first backoff; `holds`, the actions the job holds, decide which file
|
|
110
|
+
* references of a claimed row it may open.
|
|
110
111
|
*/
|
|
111
|
-
export declare function jobHandles(frame: RequestFrame, data: DataAccess, declaration: SiteDeclaration, principal: string, kind: 'job' | 'mutation', session: () => Promise<Session>, ended: () => boolean, tickMs?: number, files?: FileBinding): DataHandles;
|
|
112
|
+
export declare function jobHandles(frame: RequestFrame, data: DataAccess, declaration: SiteDeclaration, principal: string, kind: 'job' | 'mutation', session: () => Promise<Session>, ended: () => boolean, tickMs?: number, files?: FileBinding, holds?: readonly string[]): DataHandles;
|
|
112
113
|
/** `ctx.sql` (or `member`, a job's `tx.sql`) of a site that does not declare `sql`. */
|
|
113
114
|
export declare function undeclaredSql(site: string, kind: DataKind, member?: 'ctx.sql' | 'tx.sql'): SqlTag;
|
|
114
115
|
/** `ctx.sql` of a job that declares `sql`, outside `ctx.transaction`: its statements run only in the attempt's fence. */
|
|
@@ -125,12 +125,32 @@ type LinksContext<C, Acc> = TargetOf<Acc> extends readonly [infer D extends stri
|
|
|
125
125
|
} : unknown;
|
|
126
126
|
/** What a procedure's context carries for its access form in this contract. */
|
|
127
127
|
export type ContractContext<C, Acc> = AccessContext<Acc> & MembersContext<C, Acc> & LinksContext<C, Acc>;
|
|
128
|
-
/**
|
|
129
|
-
|
|
130
|
-
|
|
128
|
+
/**
|
|
129
|
+
* The `from` fields an access form reads: its own, or under `capabilities` each `on` and `in` one's (`over` reads none).
|
|
130
|
+
* The runtime removes the same fields (`#access` and `#capabilities` in `dispatch.ts`). A widened `from` (`string`, or
|
|
131
|
+
* the union of the input's string fields an access widened to its declared constraint carries) removes every field it
|
|
132
|
+
* may name: the runtime removes one of them, and the declaration refuses such an access anyway.
|
|
133
|
+
*/
|
|
134
|
+
type FromFields<Acc> = Acc extends {
|
|
135
|
+
readonly capabilities: infer C;
|
|
131
136
|
} ? {
|
|
132
|
-
|
|
133
|
-
} :
|
|
137
|
+
[N in keyof C]: FieldRead<C[N]>;
|
|
138
|
+
}[keyof C] : FieldRead<Acc>;
|
|
139
|
+
/** The field one access form reads, for each member of a form typed as a union; `never` for a form that reads none. */
|
|
140
|
+
type FieldRead<F> = F extends {
|
|
141
|
+
readonly from: infer K extends string;
|
|
142
|
+
} ? K : never;
|
|
143
|
+
/**
|
|
144
|
+
* The input as the runtime hands it to the handler: without the `from` fields and frozen under a form that reads one and
|
|
145
|
+
* under every `capabilities` access (`Object.freeze` in `takeField` and `#capabilities`); as parsed under any other.
|
|
146
|
+
*/
|
|
147
|
+
export type HandlerInput<I, Acc> = IsAny<Acc> extends true ? InputOf<I> : Acc extends {
|
|
148
|
+
readonly capabilities: unknown;
|
|
149
|
+
} ? Without<InputOf<I>, FromFields<Acc>> : Acc extends unknown ? [FromFields<Acc>] extends [never] ? InputOf<I> : Without<InputOf<I>, FromFields<Acc>> : never;
|
|
150
|
+
/** `In` without the fields `F`, read-only: the only copy of each removed id a handler has is the checked capability. */
|
|
151
|
+
type Without<In, F> = {
|
|
152
|
+
readonly [K in keyof In as K extends F ? never : K]: In[K];
|
|
153
|
+
};
|
|
134
154
|
export type Handler<In, Ctx, O extends Schema> = (args: {
|
|
135
155
|
readonly input: In;
|
|
136
156
|
readonly ctx: Ctx;
|
|
@@ -4,7 +4,7 @@ import type { CapabilityAuthority } from '@fabrika/db/capability';
|
|
|
4
4
|
import { type DataAccess, type FrameworkTables, type LeaseFence, type Session } from '@fabrika/db/framework';
|
|
5
5
|
import { type StoredFileKinds } from '../files/kinds';
|
|
6
6
|
import { type CapabilityMint } from '../implement/capability';
|
|
7
|
-
import { type
|
|
7
|
+
import { type HandlerErrorSink } from '../implement/failures';
|
|
8
8
|
import type { ContractDatabase } from '../implement/implement';
|
|
9
9
|
import type { SignedTokens } from '../implement/tokens';
|
|
10
10
|
import { type AppUrl } from '../implement/urls';
|
|
@@ -32,7 +32,14 @@ export type JobFailureCode = 'timeout' | 'lease_lost' | 'handler_failed'
|
|
|
32
32
|
/** The data layer refused a statement or an operation tree (`QueryRefusedError`): its reason names why. */
|
|
33
33
|
| 'query_refused'
|
|
34
34
|
/** A capability or a handle was refused: forged, ended, of other work, or of another kind than the call takes. */
|
|
35
|
-
| 'capability_refused'
|
|
35
|
+
| 'capability_refused'
|
|
36
|
+
/** The framework failed the attempt (`ServerFault`): its reason names why, as a request's 500 names it. */
|
|
37
|
+
| 'framework_fault'
|
|
38
|
+
/**
|
|
39
|
+
* The framework could not reach a service it needs (a `ServerFault` with status 503), as a request's 503 names it. IAM
|
|
40
|
+
* is the exception: met inside the handler as at the attempt's start, it is `iam_unavailable` or `unauthorized`.
|
|
41
|
+
*/
|
|
42
|
+
| 'unavailable' | 'driver_failed' | 'crashed'
|
|
36
43
|
/** IAM refused the job's key: the attempt mints no capability. */
|
|
37
44
|
| 'unauthorized'
|
|
38
45
|
/** IAM could not be asked for the job's token. */
|
|
@@ -45,7 +52,10 @@ export type JobRunResult = {
|
|
|
45
52
|
readonly status: 'succeeded';
|
|
46
53
|
readonly attempts: number;
|
|
47
54
|
}
|
|
48
|
-
/**
|
|
55
|
+
/**
|
|
56
|
+
* `reason` is a framework failure's catalog key (`query_refused`, `capability_refused`, `framework_fault`,
|
|
57
|
+
* `unavailable`) or the `EmailDeliveryError` code (`mail_failed`), present only for one of those.
|
|
58
|
+
*/
|
|
49
59
|
| {
|
|
50
60
|
readonly status: 'failed';
|
|
51
61
|
readonly attempts: number;
|
|
@@ -153,8 +163,6 @@ export declare class JobError extends Error {
|
|
|
153
163
|
readonly name = "JobError";
|
|
154
164
|
}
|
|
155
165
|
export declare const systemClock: JobClock;
|
|
156
|
-
/** Where `fabrika app dev` shows what a handler threw, on the developer's own machine; nothing else sets one. */
|
|
157
|
-
export type HandlerErrorSink = (where: string, error: unknown) => void;
|
|
158
166
|
export interface JobBindingInput {
|
|
159
167
|
readonly artifact: ContractArtifact;
|
|
160
168
|
/** The handler tree `boot` binds; a job's handler is `handlers.jobs.<name>`. */
|
|
@@ -181,7 +189,7 @@ export interface JobBindingInput {
|
|
|
181
189
|
readonly capabilities: CapabilityAuthority;
|
|
182
190
|
/** Each dimension's containers, nearest first: a link's chain. */
|
|
183
191
|
readonly containers: ReadonlyMap<string, readonly string[]>;
|
|
184
|
-
/** What a job
|
|
192
|
+
/** What a job attempt threw, for the author's own run; without it the error is only its fixed code. */
|
|
185
193
|
readonly revealHandlerErrors?: HandlerErrorSink;
|
|
186
194
|
/** The transports of the jobs that declare `mailer`, which `boot` resolved. */
|
|
187
195
|
readonly mail: MailTransports;
|
|
@@ -189,8 +197,6 @@ export interface JobBindingInput {
|
|
|
189
197
|
readonly tokens?: SignedTokens;
|
|
190
198
|
/** `ctx.url`: absolute links to the application's own procedures; without it every link is refused. */
|
|
191
199
|
readonly url?: AppUrl;
|
|
192
|
-
/** The rules of public egress, which `boot` reads from the environment; without them a public job reaches nothing. */
|
|
193
|
-
readonly publicEgress?: PublicEgressRules;
|
|
194
200
|
}
|
|
195
201
|
export interface BoundJobs {
|
|
196
202
|
readonly jobs: ContractJobs;
|
|
@@ -66,9 +66,10 @@ export interface EndpointAccessKit {
|
|
|
66
66
|
global(endpoint: string, input: Readonly<Record<string, unknown>>): Promise<ReachOutcome>;
|
|
67
67
|
/**
|
|
68
68
|
* One capability of an endpoint of several, refused while every other one passes: the caller holds each other one's
|
|
69
|
-
* action in a scope of its own and addresses its object or value there
|
|
70
|
-
*
|
|
71
|
-
*
|
|
69
|
+
* action in a scope of its own and addresses its object or value there. For an `on` or `in` capability it also holds
|
|
70
|
+
* the named one's action in its own scope and addresses the other's object (404) or value (403); for `over` it holds
|
|
71
|
+
* the named action only where the others need it (403). An `over` capability without a denied case
|
|
72
|
+
* (`deniedCaseRuledOutBy`) throws. `seed` is the named one's.
|
|
72
73
|
*/
|
|
73
74
|
capability(endpoint: string, capability: string, input: Readonly<Record<string, unknown>>, seed?: Seed): Promise<DeniedOutcome>;
|
|
74
75
|
/**
|
|
@@ -2,8 +2,8 @@ export type { IamMembershipRpc } from '@fabrika/auth-core';
|
|
|
2
2
|
export { type MemoryEmail, MemoryEmailSender, type MemoryHandoff } from '@fabrika/email/memory';
|
|
3
3
|
export type { FileScanner } from '../files/scan';
|
|
4
4
|
export type { ChallengeFetch } from '../implement/challenge';
|
|
5
|
+
export type { HandlerErrorSink } from '../implement/failures';
|
|
5
6
|
export { mailKeyPrefix, type MailKeyScope, transportMailKey } from '../jobs/mail';
|
|
6
|
-
export type { HandlerErrorSink } from '../jobs/runner';
|
|
7
7
|
export type { LabelledTestCaller, LinkTestCaller, PersonTestCaller, TestCaller, TestCallerKind, TestCallerOptions, TestGrant, TestLink, TestScope, } from './caller';
|
|
8
8
|
export { passingChallenge } from './challenge';
|
|
9
9
|
export { DEV_OUTBOX_ORIGIN, type DevKit, devKit, type DevLink, type DevMail, type DevOutboxMessage, type DevOutside, type DevPersona, type DevScopeValue, type DevSeed, type DevSeedResult, } from './dev';
|
|
@@ -13,9 +13,9 @@ import { type BootOptions } from '../implement/boot';
|
|
|
13
13
|
import { type ChallengeFetch } from '../implement/challenge';
|
|
14
14
|
import { type ConnectFetch } from '../implement/connect';
|
|
15
15
|
import type { SpaAssets } from '../implement/dispatch';
|
|
16
|
+
import type { HandlerErrorSink } from '../implement/failures';
|
|
16
17
|
import type { ApplicationEnvironment, ContractImplementation } from '../implement/implement';
|
|
17
18
|
import type { MailKeyScope } from '../jobs/mail';
|
|
18
|
-
import type { HandlerErrorSink } from '../jobs/runner';
|
|
19
19
|
import type { JobRunOptions, JobRunResult } from '../jobs/runner';
|
|
20
20
|
import { type LabelledTestCaller, type LinkTestCaller, type PersonTestCaller, type TestCaller, type TestCallerOptions, type TestGrant, type TestScope } from './caller';
|
|
21
21
|
import { type KitMembership } from './membership';
|
|
@@ -60,7 +60,11 @@ export interface TestKitOptions {
|
|
|
60
60
|
readonly connect?: Readonly<Record<string, TestConnection>>;
|
|
61
61
|
/** What answers a public procedure's challenge verification in place of the provider: a stand-in for its siteverify. */
|
|
62
62
|
readonly challengeFetch?: ChallengeFetch;
|
|
63
|
-
/**
|
|
63
|
+
/**
|
|
64
|
+
* Where the author's own run shows what a request's 5xx or a job attempt threw, whole: a handler's own error, or a
|
|
65
|
+
* framework failure (a refused `ctx.sql`, a capability refusal, a `ServerFault`) whose message the log line withholds.
|
|
66
|
+
* `fabrika app dev` sets it; a test passes one to see why a call failed. Off unless passed.
|
|
67
|
+
*/
|
|
64
68
|
readonly revealHandlerErrors?: HandlerErrorSink;
|
|
65
69
|
/**
|
|
66
70
|
* The stand-in for every job's mail transport; a new `MemoryEmailSender` by default. Pass one with other capabilities
|