@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.
Files changed (54) hide show
  1. package/package.json +9 -9
  2. package/skill/SKILL.md +6 -3
  3. package/skill/references/app-setup.md +8 -8
  4. package/skill/references/dev.md +3 -1
  5. package/skill/references/endpoint.md +9 -9
  6. package/skill/references/errors.md +42 -34
  7. package/skill/references/files.md +4 -2
  8. package/skill/references/jobs.md +18 -12
  9. package/skill/references/table-and-migration.md +31 -4
  10. package/skill/references/tests.md +22 -10
  11. package/src/bun.ts +0 -10
  12. package/src/cloudflare/import.ts +3 -212
  13. package/src/contract/artifact-schema.ts +1 -6
  14. package/src/contract/build.ts +10 -33
  15. package/src/contract/capability-cases.ts +30 -0
  16. package/src/contract/containers.ts +19 -0
  17. package/src/contract/group.ts +1 -10
  18. package/src/contract/index.ts +1 -0
  19. package/src/contract/kit.ts +1 -2
  20. package/src/files/handle.ts +2 -1
  21. package/src/files/kinds.ts +1 -1
  22. package/src/implement/boot.ts +12 -30
  23. package/src/implement/capability.ts +1 -4
  24. package/src/implement/dispatch.ts +8 -5
  25. package/src/implement/egress.ts +8 -367
  26. package/src/implement/failures.ts +42 -3
  27. package/src/implement/faults.ts +4 -1
  28. package/src/implement/invocation.ts +13 -11
  29. package/src/implement/tokens.ts +4 -2
  30. package/src/implement/types.ts +22 -4
  31. package/src/jobs/runner.ts +32 -20
  32. package/src/testing/endpoint-access.ts +30 -23
  33. package/src/testing/index.ts +1 -1
  34. package/src/testing/kit.ts +6 -2
  35. package/src/testing/policy-isolation.ts +2 -2
  36. package/types/src/cloudflare/import.d.ts +1 -12
  37. package/types/src/contract/capability-cases.d.ts +9 -0
  38. package/types/src/contract/containers.d.ts +3 -0
  39. package/types/src/contract/group.d.ts +1 -9
  40. package/types/src/contract/index.d.ts +1 -0
  41. package/types/src/contract/kit.d.ts +2 -2
  42. package/types/src/files/handle.d.ts +2 -1
  43. package/types/src/implement/boot.d.ts +6 -9
  44. package/types/src/implement/capability.d.ts +1 -3
  45. package/types/src/implement/dispatch.d.ts +1 -2
  46. package/types/src/implement/egress.d.ts +1 -36
  47. package/types/src/implement/failures.d.ts +21 -2
  48. package/types/src/implement/faults.d.ts +4 -1
  49. package/types/src/implement/invocation.d.ts +6 -5
  50. package/types/src/implement/types.d.ts +25 -5
  51. package/types/src/jobs/runner.d.ts +14 -8
  52. package/types/src/testing/endpoint-access.d.ts +4 -3
  53. package/types/src/testing/index.d.ts +1 -1
  54. 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
- /** `reporter` is `null` without an Operations DSN: the log line is then the only record. */
31
- constructor(reporter: OperationsReporter | null, now?: () => number);
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
- /** A failure the framework itself describes. Its message is for the author's own run, never the response or a log. */
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 DeclaredEgress, type JobMailer } from '@fabrika/auth-core';
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, or `'public'`: every public host (a cron job). */
20
- readonly egress: DeclaredEgress;
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
- /** The input without the `from` field: the only copy of that id a handler has is the checked capability. */
129
- export type HandlerInput<I, Acc> = Acc extends {
130
- readonly from: infer F extends string;
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
- readonly [K in keyof InputOf<I> as K extends F ? never : K]: InputOf<I>[K];
133
- } : InputOf<I>;
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 PublicEgressRules } from '../implement/egress';
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' | 'driver_failed' | 'crashed'
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
- /** `reason` is a framework refusal's catalog key (`query_refused`, `capability_refused`), present only for one. */
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's handler threw, for `fabrika app dev`; without it the error is only its fixed code. */
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 (or, for `over`, holds the action globally).
70
- * For an `on` or `in` capability it also holds the named one's action in its own scope and addresses the other's
71
- * object (404) or value (403); for `over` it holds the named action nowhere (403). `seed` is the named one's.
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
- /** What a job's handler threw, shown on the developer's own machine: `fabrika app dev` sets it, a test need not. */
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