@fabrika/app 0.9.0-dev.1 → 0.9.0-dev.11
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 +32 -26
- package/skill/SKILL.md +46 -15
- package/skill/references/app-setup.md +43 -12
- package/skill/references/dev.md +5 -2
- package/skill/references/endpoint.md +39 -28
- package/skill/references/errors.md +50 -37
- package/skill/references/files.md +8 -4
- package/skill/references/jobs.md +39 -7
- package/skill/references/table-and-migration.md +47 -3
- package/skill/references/tests.md +73 -16
- 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 +621 -0
- package/src/cloudflare/import.ts +888 -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/capability-cases.ts +30 -0
- package/src/contract/compile.ts +1 -0
- package/src/contract/containers.ts +19 -0
- package/src/contract/context.ts +35 -9
- package/src/contract/declaration.ts +2 -0
- package/src/contract/defaults.ts +27 -4
- package/src/contract/define.ts +29 -3
- package/src/contract/index.ts +1 -0
- package/src/contract/kit.ts +4 -1
- package/src/contract/platform.ts +3 -2
- package/src/contract/vocabulary.ts +26 -8
- package/src/dev/changes.ts +5 -43
- package/src/dev/contract-digest.ts +17 -0
- package/src/dev/index.ts +1 -1
- package/src/dev/launcher.ts +197 -41
- package/src/dev/output.ts +13 -3
- package/src/dev/wire.ts +11 -1
- package/src/disk-assets.ts +8 -3
- package/src/files/archive.ts +2 -2
- package/src/files/handle.ts +2 -1
- package/src/files/job-names.ts +12 -0
- package/src/files/kinds.ts +74 -32
- 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 +84 -27
- package/src/implement/bounded.ts +21 -2
- package/src/implement/capability.ts +16 -4
- package/src/implement/dispatch.ts +423 -178
- package/src/implement/failures.ts +59 -4
- package/src/implement/faults.ts +5 -1
- package/src/implement/index.ts +1 -0
- package/src/implement/invocation.ts +62 -11
- package/src/implement/principal.ts +25 -2
- package/src/implement/terminals.ts +93 -0
- package/src/implement/tokens.ts +4 -2
- package/src/implement/types.ts +22 -4
- 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 +702 -126
- 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 +493 -202
- package/src/testing/index.ts +1 -1
- package/src/testing/isolation.ts +8 -1
- package/src/testing/kit.ts +86 -4
- package/src/testing/policy-isolation.ts +2 -2
- package/src/testing/proxy.ts +15 -10
- package/types/src/agent-skill.d.ts +29 -0
- package/types/src/build-recipe.d.ts +70 -0
- package/types/src/build.d.ts +29 -0
- package/types/src/bun.d.ts +99 -0
- package/types/src/client/caller.d.ts +19 -0
- package/types/src/client/contract.d.ts +131 -0
- package/types/src/client/error-reporting.d.ts +66 -0
- package/types/src/client/index.d.ts +4 -0
- package/types/src/client/rpc.d.ts +14 -0
- package/types/src/client/share.d.ts +2 -0
- package/types/src/client/transport.d.ts +42 -0
- 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 +47 -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 +43 -0
- package/types/src/contract/app-id.d.ts +2 -0
- package/types/src/contract/artifact-schema.d.ts +10 -0
- package/types/src/contract/attachment.d.ts +41 -0
- package/types/src/contract/build.d.ts +12 -0
- package/types/src/contract/capability-cases.d.ts +9 -0
- package/types/src/contract/compile.d.ts +11 -0
- package/types/src/contract/connect.d.ts +51 -0
- package/types/src/contract/containers.d.ts +3 -0
- package/types/src/contract/context.d.ts +525 -0
- package/types/src/contract/declaration.d.ts +307 -0
- package/types/src/contract/defaults.d.ts +228 -0
- package/types/src/contract/define.d.ts +376 -0
- package/types/src/contract/file.d.ts +44 -0
- package/types/src/contract/group.d.ts +274 -0
- package/types/src/contract/handled.d.ts +18 -0
- package/types/src/contract/index.d.ts +20 -0
- package/types/src/contract/kit.d.ts +211 -0
- package/types/src/contract/platform.d.ts +9 -0
- package/types/src/contract/problems.d.ts +14 -0
- package/types/src/contract/redirect.d.ts +25 -0
- package/types/src/contract/schema-from-shape.d.ts +10 -0
- package/types/src/contract/schema-shape.d.ts +5 -0
- package/types/src/contract/snapshot-source.d.ts +15 -0
- package/types/src/contract/token.d.ts +58 -0
- package/types/src/contract/vocabulary.d.ts +32 -0
- package/types/src/contract/webhook-binding.d.ts +24 -0
- package/types/src/contract/webhook-scheme.d.ts +23 -0
- package/types/src/dev/changes.d.ts +7 -0
- package/types/src/dev/contract-digest.d.ts +1 -0
- package/types/src/dev/index.d.ts +2 -0
- package/types/src/dev/launcher.d.ts +32 -0
- package/types/src/dev/output.d.ts +28 -0
- package/types/src/dev/wire.d.ts +126 -0
- package/types/src/disk-assets.d.ts +6 -0
- package/types/src/errors.d.ts +46 -0
- package/types/src/fetch.d.ts +7 -0
- package/types/src/files/archive.d.ts +26 -0
- package/types/src/files/clamscan.d.ts +32 -0
- package/types/src/files/handle.d.ts +107 -0
- package/types/src/files/job-names.d.ts +9 -0
- package/types/src/files/kinds.d.ts +112 -0
- package/types/src/files/scan.d.ts +78 -0
- package/types/src/files/sniff.d.ts +7 -0
- package/types/src/files/streams.d.ts +17 -0
- package/types/src/files/treatment.d.ts +18 -0
- package/types/src/from-row.d.ts +20 -0
- package/types/src/honeypot.d.ts +2 -0
- package/types/src/implement/anonymous.d.ts +24 -0
- package/types/src/implement/attachment.d.ts +14 -0
- package/types/src/implement/boot.d.ts +128 -0
- package/types/src/implement/bounded.d.ts +32 -0
- package/types/src/implement/browser-config.d.ts +19 -0
- package/types/src/implement/capability.d.ts +142 -0
- package/types/src/implement/challenge.d.ts +75 -0
- package/types/src/implement/client-address.d.ts +11 -0
- package/types/src/implement/connect.d.ts +67 -0
- package/types/src/implement/crashes.d.ts +31 -0
- package/types/src/implement/dispatch.d.ts +251 -0
- package/types/src/implement/egress.d.ts +14 -0
- package/types/src/implement/environment.d.ts +14 -0
- package/types/src/implement/failures.d.ts +58 -0
- package/types/src/implement/faults.d.ts +48 -0
- package/types/src/implement/headers.d.ts +7 -0
- package/types/src/implement/implement.d.ts +58 -0
- package/types/src/implement/index.d.ts +25 -0
- package/types/src/implement/invocation.d.ts +136 -0
- package/types/src/implement/membership.d.ts +201 -0
- package/types/src/implement/multipart.d.ts +36 -0
- package/types/src/implement/params.d.ts +7 -0
- package/types/src/implement/principal.d.ts +57 -0
- package/types/src/implement/project.d.ts +11 -0
- package/types/src/implement/public.d.ts +61 -0
- package/types/src/implement/serve.d.ts +25 -0
- package/types/src/implement/terminals.d.ts +33 -0
- package/types/src/implement/tokens.d.ts +49 -0
- package/types/src/implement/types.d.ts +263 -0
- package/types/src/implement/urls.d.ts +15 -0
- package/types/src/implement/verifiers.d.ts +19 -0
- package/types/src/implement/webhook.d.ts +55 -0
- package/types/src/implement/workload.d.ts +61 -0
- package/types/src/implement/xlsx.d.ts +6 -0
- package/types/src/index.d.ts +12 -0
- package/types/src/jobs/exception.d.ts +40 -0
- package/types/src/jobs/mail.d.ts +67 -0
- package/types/src/jobs/report.d.ts +56 -0
- package/types/src/jobs/runner.d.ts +218 -0
- package/types/src/jobs/schedule.d.ts +17 -0
- package/types/src/jobs/scrub.d.ts +12 -0
- package/types/src/jobs/types.d.ts +98 -0
- package/types/src/react/caller.d.ts +30 -0
- package/types/src/react/errors.d.ts +40 -0
- package/types/src/react/hooks.d.ts +110 -0
- package/types/src/react/index.d.ts +5 -0
- package/types/src/react/provider.d.ts +58 -0
- package/types/src/react/store.d.ts +68 -0
- package/types/src/react/testing.d.ts +28 -0
- package/types/src/react/types.d.ts +33 -0
- package/types/src/rpc/builder.d.ts +52 -0
- package/types/src/rpc/contract.d.ts +23 -0
- package/types/src/rpc/dispatcher.d.ts +11 -0
- package/types/src/rpc/types.d.ts +62 -0
- package/types/src/service/define.d.ts +42 -0
- package/types/src/service/index.d.ts +3 -0
- package/types/src/service/serve.d.ts +28 -0
- package/types/src/spa-fallback.d.ts +2 -0
- package/types/src/standard-schema.d.ts +55 -0
- package/types/src/testing/caller.d.ts +95 -0
- package/types/src/testing/challenge.d.ts +11 -0
- package/types/src/testing/dev.d.ts +97 -0
- package/types/src/testing/endpoint-access.d.ts +132 -0
- package/types/src/testing/index.d.ts +12 -0
- package/types/src/testing/isolation.d.ts +3 -0
- package/types/src/testing/kit.d.ts +207 -0
- package/types/src/testing/membership.d.ts +132 -0
- package/types/src/testing/policy-isolation.d.ts +113 -0
- package/types/src/testing/preload.d.ts +1 -0
- package/types/src/testing/proxy.d.ts +40 -0
- package/types/src/testing/runner.d.ts +8 -0
- package/types/src/testing/sample-file.d.ts +5 -0
- package/types/src/testing/status.d.ts +4 -0
- package/types/src/undumpable.d.ts +5 -0
|
@@ -8,39 +8,48 @@ architecture, and a refusal's allowed form is the one fix that passes. There is
|
|
|
8
8
|
|
|
9
9
|
The refusals agents meet most, and their fix:
|
|
10
10
|
|
|
11
|
-
| Rule
|
|
12
|
-
|
|
|
13
|
-
| `literal`
|
|
14
|
-
| `contract`
|
|
15
|
-
| `package-replacement`
|
|
16
|
-
| `generated-test-hash`
|
|
17
|
-
| `endpoint-fixture`
|
|
18
|
-
| `raw-sql`
|
|
19
|
-
| `forbidden-import`
|
|
20
|
-
| `forbidden-global`
|
|
21
|
-
| `env-read`
|
|
22
|
-
| `client-identity`
|
|
23
|
-
| `type-assertion`
|
|
24
|
-
| `sensitive-log`
|
|
25
|
-
| `migration-name`
|
|
26
|
-
| `
|
|
27
|
-
| `
|
|
28
|
-
| `
|
|
29
|
-
| `
|
|
30
|
-
| `
|
|
31
|
-
| `
|
|
32
|
-
| `
|
|
33
|
-
| `
|
|
11
|
+
| Rule | Means | Fix |
|
|
12
|
+
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
13
|
+
| `literal` | the shell (contract, vocabulary, tables, groups, schemas) holds a computed value or call | literal objects, `z.*` calls and imported literal consts; move logic into `.handle(…)` |
|
|
14
|
+
| `contract` | the contract does not compile (a reserved role, an unknown action, a wrong field) | the message names the field |
|
|
15
|
+
| `package-replacement` | `package.json` names the app under `@fabrika/*`, or a dependency is `workspace:*` | another name; a registry range such as `^0.0.4` |
|
|
16
|
+
| `generated-test-hash` | a generated test is missing, edited or stale | `bunx fabrika db test-scaffold`, and commit what it writes |
|
|
17
|
+
| `endpoint-fixture` | an endpoint's input cannot be sampled, a fixture or seed names no endpoint, a member, invitation or link field no endpoint that reads, cancels or revokes one, a file names no file field or a path outside the application, or a refusal is `validation` | a literal in `src/__tests__/endpoint-access.fixtures.ts` (`references/tests.md`) |
|
|
18
|
+
| `raw-sql` | a driver's `sql` (imported from `bun`, Kysely, `postgres`) | the handles, or `sql: 'read'` and `ctx.sql` |
|
|
19
|
+
| `forbidden-import` | a driver, an S3 client, `jose`, `node:http`, `child_process` | the handles, a file column with `ctx.files`, a connector |
|
|
20
|
+
| `forbidden-global` | `Bun.sql`, `Bun.serve`, `Bun.spawn`; `globalThis`, `window`, `self`, `global` or `Bun` in a server module | the handles; state lives in a table, not in a global; `crypto.randomUUID()` for an id |
|
|
21
|
+
| `env-read` | `process.env`, `Bun.env` | `defineDeps(build)`, which receives the application's variables |
|
|
22
|
+
| `client-identity` | an input field `userId`, `ownerId`, `createdBy`, `tenantId`, `workspaceId` | the access form's `from`, `ctx.principal.id`, or `createdBy` in the policy |
|
|
23
|
+
| `type-assertion` | `as T` (other than `as const`), `<T>x` | fix the type; `fromRow` parses a row into a schema's type |
|
|
24
|
+
| `sensitive-log` | a log of an error object, a request, headers or the environment | log a short fixed message |
|
|
25
|
+
| `migration-name` | a migration not named `YYYYMMDDHHMMSS_slug.sql` (UTC) | `bunx fabrika db new <slug>` |
|
|
26
|
+
| `migration-edited` | a migration already on the main branch, edited (even a comment), renamed or deleted | restore the file; put the change in a new migration (`bunx fabrika db new <slug>`) |
|
|
27
|
+
| `test-only-import` | `@fabrika/app/testing`, `@fabrika/app/react/testing`, `@fabrika/db/testing` or `@fabrika/db/testing-sqlite` outside a test file | import them only from `*.test.ts` or `__tests__/` |
|
|
28
|
+
| `spa-server-import` | the SPA loads a server module | the SPA imports `@fabrika/app/client`, the contract, `src/schemas.ts` and `src/shared/` |
|
|
29
|
+
| `shared-import` | a module under `src/shared/` loads a slice, `src/db/`, `@fabrika/*` or a builtin | a shared module imports `zod/v4` and other shared modules only |
|
|
30
|
+
| `tool-import` | a module outside `tools/` loads a developer's tool under `tools/` | move what both need under `src/` (`src/shared/`) and import it from the tool |
|
|
31
|
+
| `skipped-test` | `.skip`, `.only`, `.todo` | run the test |
|
|
32
|
+
| `file-column-migration` | a file column without `REFERENCES fabrika_files (id)` or without an index it leads | both, in a new migration (`references/table-and-migration.md`) |
|
|
33
|
+
| `on-conflict-index` | `insert(…, { onConflict: { columns } })` whose columns are no unique index the migrations create | a `UNIQUE` constraint or a `CREATE UNIQUE INDEX` without `WHERE` on exactly those columns |
|
|
34
|
+
| `cross-app-fetch` | a `fetch` of an absolute URL under no origin a site declares in `egress` | `egress: ['https://…']` on the site that calls it (`references/endpoint.md`) |
|
|
35
|
+
| `url-endpoint` | `ctx.url('<id>')` names no procedure of the contract | the endpoint id `<mount>.<group>.<procedure>` |
|
|
36
|
+
| `cloudflare-scan` | on Cloudflare, a file kind with `scan: true` | the kind without `scan`, and no public procedure that takes its files |
|
|
37
|
+
| `cloudflare-job-segment` | on Cloudflare, a job whose `limits.timeoutMs` exceeds one 14-minute segment | at most 14 minutes: claim a bounded batch per run, and the next run takes the rest |
|
|
38
|
+
| `cloudflare-current-timestamp` | on Cloudflare, `DEFAULT CURRENT_TIMESTAMP` in a migration: SQLite stores `YYYY-MM-DD HH:MM:SS`, which every read of the table refuses | `DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`, in a new migration |
|
|
39
|
+
| `cloudflare-framework-name` | on Cloudflare, a `fabrika_*` name in a migration, quoted or not | your own tables, and `REFERENCES fabrika_files (id)` for a file column |
|
|
40
|
+
| `migration-refused` | a migration statement Control refuses (a function, an object or a form the platform does not admit) | a new migration that does without it; a key in a SQLite backfill: the UUID expression in `table-and-migration.md` |
|
|
41
|
+
| `backup-schema` | on Cloudflare, a schema the backup cannot copy: a key back into its own table that a `CHECK` reads, or that is `NOT NULL` | a nullable key no `CHECK` names, or no such key; a new migration, before any further one deploys |
|
|
34
42
|
|
|
35
43
|
The hints:
|
|
36
44
|
|
|
37
|
-
| Hint | Means
|
|
38
|
-
| ---------------------- |
|
|
39
|
-
| `handler-location` | a `.handle(…)` outside a slice's `endpoints.ts`
|
|
40
|
-
| `data-access-location` | `ctx.db` or `ctx.sql` outside `endpoints.ts` and `queries.ts`
|
|
41
|
-
| `logic-data-access` | `logic.ts` reaches data
|
|
42
|
-
| `cross-slice-queries` | a slice loads another slice's `queries.ts`
|
|
43
|
-
| `sql-undeclared` | `ctx.sql` in a handler whose endpoint declares no `sql`
|
|
45
|
+
| Hint | Means | Fix |
|
|
46
|
+
| ---------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
|
47
|
+
| `handler-location` | a `.handle(…)` outside a slice's `endpoints.ts` | move the endpoint into `src/<slice>/endpoints.ts` |
|
|
48
|
+
| `data-access-location` | `ctx.db` or `ctx.sql` outside `endpoints.ts` and `queries.ts` | pass the handle into a function of the slice's `queries.ts` |
|
|
49
|
+
| `logic-data-access` | `logic.ts` reaches data | keep `logic.ts` pure; pass it plain values |
|
|
50
|
+
| `cross-slice-queries` | a slice loads another slice's `queries.ts` | move the function, or call that slice's endpoint |
|
|
51
|
+
| `sql-undeclared` | `ctx.sql` in a handler whose endpoint declares no `sql` | add `sql: 'read'` (or `'write'`) to that endpoint |
|
|
52
|
+
| `cloudflare-held-call` | on Cloudflare, a mutation that declares `egress` or `connect` holds the whole environment while it waits | record a row and `ctx.kick('<job>')`; the job makes the call outside `ctx.transaction` |
|
|
44
53
|
|
|
45
54
|
The first run may report only the contract's refusals: the generated-test findings appear once the contract compiles.
|
|
46
55
|
|
|
@@ -65,6 +74,7 @@ A kit error lands on the line of the mistake, in one or two lines that name the
|
|
|
65
74
|
| `'member.label' is possibly 'null'` | a nullable column or output; only `directory: 'labels'` makes it text |
|
|
66
75
|
| `admin is a role IAM defines itself for every application (reserved: admin)` | another role name |
|
|
67
76
|
| `Property 'id' does not exist on type 'Ref<…>'` | `ctx.target.value` |
|
|
77
|
+
| `Property 'taskId' does not exist on type '{ … }'` on `input` | `ctx.target.value`, or `ctx.capabilities.<name>.value` |
|
|
68
78
|
| `Property 'margin' does not exist on type 'Omit<DealsTable, "margin">'` | the column has its own read action, which this capability lacks |
|
|
69
79
|
| `Type 'Date' is not assignable to type 'string'` on a `date` column | a `YYYY-MM-DD` string |
|
|
70
80
|
| `Cannot find module '@fabrika/…'` and implicit `any`s everywhere | `bun install` (at the repository root in a monorepo) |
|
|
@@ -97,13 +107,16 @@ with its message; throw the three business errors for the application's own refu
|
|
|
97
107
|
|
|
98
108
|
A 500 answers a fixed message; the server log has one line, `fabrika: <endpoint>: <code>: <reason>: <text>`, with a
|
|
99
109
|
fixed failure code and, for a framework refusal, its reason and the reason's fixed text, never a value or your error's
|
|
100
|
-
message. The
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
|
106
|
-
|
|
|
110
|
+
message. The refusal's own message names the place (`'sqlite_master' at line 2`, the column, the function): for every
|
|
111
|
+
5xx, `fabrika app dev` prints what was thrown after that line, and a test sees it when it passes a sink to the kit
|
|
112
|
+
(`references/tests.md`). The codes
|
|
113
|
+
you meet most:
|
|
114
|
+
|
|
115
|
+
| Code | Means |
|
|
116
|
+
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
117
|
+
| `query_refused` | the data layer refused a statement or an operation: `undeclared_reach`, `sql_read_only`, `unknown_column`, `read_only`, `sql_outside_transaction`, `sql_scope`, `sql_name` …; the reason's text names the rule |
|
|
118
|
+
| `capability_refused` | a capability of another kind, dimension or action than the call takes (`wrong_capability`, `wrong_action`, `out_of_reach`), or one kept past its request (`ended`, `foreign_work`) |
|
|
119
|
+
| `handler_failed` | your handler threw something else; the log has no more: the Operations issue has the stack, `app dev` prints it |
|
|
107
120
|
|
|
108
121
|
With an Operations DSN the same 500 is a `RequestFailed` issue in Operations. Its event also carries what your handler
|
|
109
122
|
threw: the error's type, its message, its stack and its `cause` chain. Read the stack there, not in the log. A crash
|
|
@@ -76,7 +76,8 @@ task_attachments: {
|
|
|
76
76
|
cascade) or clearing a nullable column removes the reference; the framework's sweep deletes a file no column
|
|
77
77
|
references.
|
|
78
78
|
- A file column takes only a file reference: an input file (`file('<kind>')`), a `ctx.files.put` of this request, or a
|
|
79
|
-
reference this request read from a file column under that table's `read` action
|
|
79
|
+
reference this request read from a file column under that table's `read` action (or claimed with its queue row while
|
|
80
|
+
the job declares that action). A string id is refused.
|
|
80
81
|
|
|
81
82
|
```ts src/attachments/endpoints.ts
|
|
82
83
|
import { file } from '@fabrika/app/contract'
|
|
@@ -209,7 +210,8 @@ a view that maps them.
|
|
|
209
210
|
| `put(kind, bytes, { type, name? })` | stores a new file of the kind and answers its reference; it is pending until a column holds it |
|
|
210
211
|
| `open(ref, { maxBytes? })` | `{ id, name, type, size, bytes }` of a live file, read whole |
|
|
211
212
|
|
|
212
|
-
`open` takes a reference the site read from a file column under that table's `read` action
|
|
213
|
+
`open` takes a reference the site read from a file column under that table's `read` action, or a queue row a job
|
|
214
|
+
claimed while it also declares that action (`references/jobs.md`). It answers 409
|
|
213
215
|
`file_not_ready` until the scan called the file clean, 409 `file_rejected` for a rejected one, and 413 for a file over
|
|
214
216
|
`maxBytes` (the kind's by default), before any byte is read. Pass the size you hold in memory.
|
|
215
217
|
|
|
@@ -363,7 +365,8 @@ export const erase = app.cron('30 2 * * *', {
|
|
|
363
365
|
## Malware scan
|
|
364
366
|
|
|
365
367
|
`scan: true` on a kind holds every file of it `quarantined` until ClamAV answers clean; on Zerops the platform
|
|
366
|
-
installs ClamAV and runs the scan job.
|
|
368
|
+
installs ClamAV and runs the scan job. No scanner runs on Cloudflare: the deploy and the boot refuse a kind with
|
|
369
|
+
`scan: true` there, and so a public procedure with a file field. A file answer is 409 `file_not_ready` until then and 409 `file_rejected` once
|
|
367
370
|
the file is `rejected`; a list shows each file's `status`, so show it rather than a broken link. In a test, the scan runs with
|
|
368
371
|
`kit.runJob(FILE_SCAN_JOB)` and a `scanner` passed to `testKit` (`references/tests.md`); the generated tests pass their
|
|
369
372
|
own seeded files.
|
|
@@ -401,7 +404,8 @@ the transaction that deletes the row. The file is never copied; the sweep delete
|
|
|
401
404
|
## Storage
|
|
402
405
|
|
|
403
406
|
On Zerops, declare one `object-storage` service in `fabrika.config.ts`; the platform writes `FABRIKA_APP_STORAGE_*`
|
|
404
|
-
from it. Never read those variables, build a storage URL or import an S3 client.
|
|
407
|
+
from it. Never read those variables, build a storage URL or import an S3 client. On Cloudflare the platform binds the
|
|
408
|
+
environment's R2 bucket itself; declare nothing.
|
|
405
409
|
|
|
406
410
|
```text
|
|
407
411
|
// in the services of fabrika.config.ts
|
package/skill/references/jobs.md
CHANGED
|
@@ -4,8 +4,8 @@ Background work is a cron job: `app.cron(schedule, { actions })` with its `.hand
|
|
|
4
4
|
`endpoints.ts` of the slice whose data it works on, mounted under `jobs` in the contract. There are no timers, loops,
|
|
5
5
|
`setInterval` or self-scheduled work, and no `ctx.jobs.enqueue`: work for later is a row that a run picks up, usually
|
|
6
6
|
from a queue table with `claim` (below). A mutation, a webhook or another job that declares `kicks: ['<job>']` and
|
|
7
|
-
calls `ctx.kick('<job>')` starts a run within seconds of its commit (the outbox below)
|
|
8
|
-
that run leaves.
|
|
7
|
+
calls `ctx.kick('<job>')` starts a run within seconds of its commit (the outbox below), and `ctx.kick('<job>', { at })`
|
|
8
|
+
starts one at `at`; the schedule picks up whatever that run leaves.
|
|
9
9
|
|
|
10
10
|
```ts src/overdue/endpoints.ts
|
|
11
11
|
import { app } from '../app-kit'
|
|
@@ -118,7 +118,7 @@ export const contract = app.contract((c) => ({
|
|
|
118
118
|
one, since no zone is a day further ahead.
|
|
119
119
|
- **Reads run outside the transaction; every write runs inside `ctx.transaction((tx) => …)`**, through `tx.db`, fenced
|
|
120
120
|
by the attempt's lease. A write outside it is a type error that names `tx.db`.
|
|
121
|
-
- An attempt that fails or outlives `limits.timeoutMs` (default
|
|
121
|
+
- An attempt that fails or outlives `limits.timeoutMs` (default 14 minutes, at most a day; at most 14 minutes on Cloudflare) is retried up to `retries` times, so every write is
|
|
122
122
|
idempotent. **Re-read each row under its lock before you write it:** `tx.db.on(ref).getForUpdate()` inside the
|
|
123
123
|
transaction, decide again on what it answers with the list's whole filter (`isOverdue`), and write with its
|
|
124
124
|
`version`. The listed row is already old: someone
|
|
@@ -146,9 +146,9 @@ export const contract = app.contract((c) => ({
|
|
|
146
146
|
builds an absolute link to one of the application's procedures, for an e-mail.
|
|
147
147
|
- `ctx.signal` aborts when the attempt ends (its timeout, a lost lease). Call `ctx.signal.throwIfAborted()` before
|
|
148
148
|
each external effect and pass the signal to `fetch`, so a stale attempt starts nothing after its replacement.
|
|
149
|
-
- A failed attempt names its failure in `kit.runJob`'s answer and the log: `handler_failed`, a framework
|
|
150
|
-
with its reason (`query_refused: undeclared_reach`, `capability_refused: undeclared_action
|
|
151
|
-
or `mail_failed` with the transport's code (`mail_failed: provider_rejected`).
|
|
149
|
+
- A failed attempt names its failure in `kit.runJob`'s answer and the log: `handler_failed`, a framework failure
|
|
150
|
+
with its reason (`query_refused: undeclared_reach`, `capability_refused: undeclared_action`,
|
|
151
|
+
`framework_fault: url_unbuildable`; `references/errors.md`), or `mail_failed` with the transport's code (`mail_failed: provider_rejected`).
|
|
152
152
|
|
|
153
153
|
## E-mail: `mailer` and `ctx.mail`
|
|
154
154
|
|
|
@@ -177,7 +177,14 @@ that says so): it records an outbox row and kicks the job (below). `references/p
|
|
|
177
177
|
(RFC 8058), so a mailbox offers one-click unsubscribe. The URL is a public procedure of your own with a signed token
|
|
178
178
|
(`ctx.url('api.mail.unsubscribe', { query: { t: ctx.tokens.sign('unsubscribe', claims, { days: 400 }) } })`,
|
|
179
179
|
`references/endpoint.md`). There are no free headers. A transport without the header refuses the message.
|
|
180
|
-
-
|
|
180
|
+
- `broadcast: true` marks one message of a send to many recipients (a newsletter, an announcement to every student),
|
|
181
|
+
as opposed to mail a recipient's own action triggers (a sign-in link, a confirmation). Providers keep the two apart
|
|
182
|
+
and pause an account whose transactional channel carries broadcast mail, so mark every message of a bulk send. It
|
|
183
|
+
needs `unsubscribe`. A transport without `ctx.mail.capabilities.broadcast` refuses it as `invalid_message`. Under
|
|
184
|
+
`mailer: 'installation'` the capability is true even where the installation's provider sends none; the first
|
|
185
|
+
message then fails `invalid_message`, so stop a bulk send at its first refusal instead of failing every row.
|
|
186
|
+
- The idempotency key covers the attachments, the unsubscribe URL and `broadcast`: a repeated key with other content
|
|
187
|
+
is refused.
|
|
181
188
|
- `idempotencyKey` is 1 to 200 visible ASCII characters, unique per message in the application environment, and
|
|
182
189
|
derived from the outbox row (`intake-link-<link id>`), never random. `ctx.mail` puts a prefix of the installation
|
|
183
190
|
and the environment in front of it, so no other application on the same provider account shares it.
|
|
@@ -213,15 +220,32 @@ for (const row of await ctx.db.app('mail.send').outbox.claim({ limit: 50 })) {
|
|
|
213
220
|
has come and whose attempts are below `maxAttempts` (10 by default), `for update skip locked`. It adds one attempt
|
|
214
221
|
and moves `<due>` by the backoff: the job's schedule period (60 s without one), doubled per attempt, at most 30
|
|
215
222
|
days. Each row answers its columns, its new `version` and `ref`.
|
|
223
|
+
- `where` takes the conditions of a `list` (`references/endpoint.md`), a null test included: `[['result', 'is', null]]`
|
|
224
|
+
claims only the rows without a result.
|
|
216
225
|
- Claim through the capability you read the table with: `ctx.db.app('<action>').<table>` for an application table,
|
|
217
226
|
`ctx.db.over(ctx.within('<action>', '<dimension>')).<table>` for a scoped one. The action is the table's `update`
|
|
218
227
|
action. `claim` runs only in a job and never inside `ctx.transaction`.
|
|
228
|
+
- A claimed row's file column is a reference the job opens (`ctx.files.open`) only when the job also declares the
|
|
229
|
+
table's `read` action. With only the update action it carries the metadata, and `open` refuses it. A column with
|
|
230
|
+
its own read action is in the claim's answer only when that action is the claim's own, and is then readable.
|
|
231
|
+
|
|
232
|
+
```text
|
|
233
|
+
// uploads: read 'uploads.read', update 'uploads.process', files: { file: 'documents' }
|
|
234
|
+
app.cron('*/5 * * * *', { actions: ['uploads.read', 'uploads.process'] }).handle(async ({ ctx }) => {
|
|
235
|
+
for (const row of await ctx.db.app('uploads.process').uploads.claim({ limit: 5 })) {
|
|
236
|
+
const document = await ctx.files.open(row.file)
|
|
237
|
+
…
|
|
238
|
+
}
|
|
239
|
+
})
|
|
240
|
+
```
|
|
219
241
|
- Finish each row in its own transaction through `tx.db.on(row.ref)`: `.update(values, { expectVersion, done: true })`
|
|
220
242
|
writes and clears `<due>`; `.remove({ expectVersion })` deletes the row (the table's delete action);
|
|
221
243
|
`.requeue({ at? })` makes it due again at `at` (now by default) with no attempts, for a dead row or a reminder moved
|
|
222
244
|
later.
|
|
223
245
|
- A failure or a crash leaves the row as the claim left it, due again after the backoff; nothing retries at once.
|
|
224
246
|
Attempts count claims, so claim only what the run will reach.
|
|
247
|
+
- A claim that leased rows runs the job again when the same claim would next find one (its `where`, its scope, below
|
|
248
|
+
`maxAttempts`), no sooner than a second later; a claim that took its full `limit` runs it again at once.
|
|
225
249
|
- A row past `maxAttempts` stays in the table, no longer due, for the application to show or requeue.
|
|
226
250
|
- One recipe covers an outbox, a per-record reminder (`<due>` is the reminder time) and asynchronous work: a mutation
|
|
227
251
|
inserts a request row and kicks; the job claims it, renders, puts the result into a file column with
|
|
@@ -237,9 +261,17 @@ row, in its own transaction: a public procedure's row (`registrations`), an outb
|
|
|
237
261
|
transaction committed, the job runs within seconds, under its own key, and the answer does not wait for it. A thrown
|
|
238
262
|
handler, a refused answer and a failed commit kick nothing. Kicks coalesce: at most one run is active and one pending,
|
|
239
263
|
however many calls arrive. A kick carries nothing; the job reads its rows, and its schedule stays the recovery.
|
|
264
|
+
The kick is written in the site's transaction, so a crash right after the commit still runs the job.
|
|
240
265
|
`kicks` names cron jobs of the contract, as literals (`r.mutation({ …, kicks: ['testMails'] })`); a mutation, a
|
|
241
266
|
webhook and a job declare it, and the kick edges never form a cycle.
|
|
242
267
|
|
|
268
|
+
**A kick for later.** `ctx.kick('<job>', { at })`, with `at` a `Date`, runs the job at that time instead of after the
|
|
269
|
+
commit: a reminder, a retry the application times itself. Kicks of one job in the same second are one; kicks at
|
|
270
|
+
different times stay apart, and a run takes only those already due. The second argument is the time and nothing else;
|
|
271
|
+
what to do stays in the job's rows (`where <due> <= now()`, or a queue table's `<due>`). On Cloudflare the object's
|
|
272
|
+
alarm runs it within seconds of `at`; on Bun the serving process that wrote it runs it at `at`, and another process
|
|
273
|
+
finds it within a minute.
|
|
274
|
+
|
|
243
275
|
The rules of the job:
|
|
244
276
|
|
|
245
277
|
- **Bounded batches.** Each run takes at most a fixed number of records (`order by received_at, id limit 50`), oldest
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# references/table-and-migration.md — the vocabulary, migrations and table policies
|
|
2
2
|
|
|
3
|
-
The order is fixed: the vocabulary, then the migration, then `fabrika db migrate` and `fabrika db codegen
|
|
4
|
-
table policies, which take the generated `columns`.
|
|
3
|
+
The order is fixed: the vocabulary, then the migration, then `fabrika db migrate` and `fabrika db codegen` (on
|
|
4
|
+
Cloudflare `codegen` only), then the table policies, which take the generated `columns`.
|
|
5
5
|
|
|
6
6
|
## The vocabulary
|
|
7
7
|
|
|
@@ -147,7 +147,21 @@ INSERT INTO priorities (code, label, rank) VALUES ('low', 'Low', 1), ('normal',
|
|
|
147
147
|
- A column with a fixed set of values is an `ENUM` type, not a `CHECK` on text: the generated tests fill text columns
|
|
148
148
|
with markers, which a `CHECK` refuses.
|
|
149
149
|
- Codegen types: `date` is a `YYYY-MM-DD` string; `timestamptz` reads a `Date` and takes a `Date` or a strict ISO 8601 string with `Z` or an offset;
|
|
150
|
-
`int8` and `numeric` are strings; an enum is its literal union.
|
|
150
|
+
`int8` and `numeric` are strings; an enum is its literal union. `bytea`, arrays and domains are refused.
|
|
151
|
+
- A column of JSON is `jsonb` (`json` is refused: it keeps whitespace and duplicate keys). It reads as `unknown`: parse it
|
|
152
|
+
with a zod schema in the handler, never trust its shape. A write takes a JSON value (plain objects and arrays, strings,
|
|
153
|
+
finite numbers, booleans; a `Date`, a `Map` or a class instance is refused), and `null` is SQL NULL. Type a value you
|
|
154
|
+
write with a `type` alias or a zod-inferred type: an `interface` has no index signature, so it is not a
|
|
155
|
+
`JsonColumnValue`. Postgres reorders an object's keys; compare values, not their `JSON.stringify` text. A `where`,
|
|
156
|
+
`orderBy` or aggregate never names a JSON column: read a path of it with `ctx.sql` (`details ->> 'kind'`), and write
|
|
157
|
+
one there as `${JSON.stringify(value)}`.
|
|
158
|
+
- A generated column (`GENERATED ALWAYS AS (…) STORED`) of any type codegen does not type (a `tsvector` for full-text
|
|
159
|
+
search, a `json`, an array, a range) is left out of the generated types instead: every `fabrika db codegen` run,
|
|
160
|
+
`--verify` too, prints `<table>.<column> (<type>, generated) is left out`, and `schema.generated.ts` has a comment
|
|
161
|
+
where the column would stand. No `ctx.db` handle reads or writes it, a policy cannot name it, and only `ctx.sql`
|
|
162
|
+
reaches it. An identity column and a generated column of a type codegen does type are never left out. A left-out
|
|
163
|
+
column in the primary key, a unique key or a foreign key is refused, and so is a table whose every column would be
|
|
164
|
+
left out.
|
|
151
165
|
- Plain SQL of the application's own schema only. Refused: another schema (`public.`, `app_…`), any `fabrika_*`
|
|
152
166
|
object (a file column references `fabrika_files (id)`, `references/files.md`), `GRANT`, roles, `CREATE EXTENSION`, `COPY`,
|
|
153
167
|
`SET`, transaction control, `SECURITY DEFINER`, a domain, `serial` and sequences (use `GENERATED ALWAYS AS IDENTITY`),
|
|
@@ -155,6 +169,36 @@ INSERT INTO priorities (code, label, rank) VALUES ('low', 'Low', 1), ('normal',
|
|
|
155
169
|
- Never edit, rename or delete a committed migration; add a new one. Change a schema by expand, switch, contract, and
|
|
156
170
|
ask before you drop or rename anything.
|
|
157
171
|
|
|
172
|
+
## On Cloudflare: SQLite migrations
|
|
173
|
+
|
|
174
|
+
An application on Cloudflare (its `fabrika.config.ts` imports `defineApp` from `@fabrika/provider-cloudflare`) writes
|
|
175
|
+
its migrations in SQLite. Its Durable Object applies them when it boots, each file once in name order, in a transaction
|
|
176
|
+
of its own, so there is no `fabrika db migrate`; `fabrika db codegen` applies them to an in-memory database and needs
|
|
177
|
+
no URL. The rules above for keys, chains, composite foreign keys, `version` and `created_by` hold unchanged, and the
|
|
178
|
+
database enforces foreign keys.
|
|
179
|
+
|
|
180
|
+
- The declared types codegen reads: `TEXT` (a UUID too), `INTEGER`, `REAL`, `BLOB`; `BOOLEAN`, stored as 0 or 1 and
|
|
181
|
+
read as a boolean; `TIMESTAMP`, stored as UTC ISO text and read as a `Date`; `DATE`, `YYYY-MM-DD` text; `JSONB`,
|
|
182
|
+
stored as JSON text and handled as Postgres's `jsonb` above (`JSON` is refused). Any other declared type is refused.
|
|
183
|
+
A generated column of another declared type (`JSON`) is left out as on Postgres; one with no declared type is
|
|
184
|
+
refused, so declare it. A `STRICT` table admits only `INTEGER`, `REAL`, `TEXT` and `BLOB`, so a table with a
|
|
185
|
+
`BOOLEAN`, `TIMESTAMP`, `DATE` or `JSONB` column is not `STRICT`. `ctx.sql` reads a `JSONB` column as its text, or
|
|
186
|
+
as a number when the value is one; parse the text with `JSON.parse`.
|
|
187
|
+
- SQLite has no `ENUM`: a column with a fixed set of values is `TEXT` with `CHECK (<column> IN ('a', 'b'))`. The
|
|
188
|
+
generated tests write its first value.
|
|
189
|
+
- No transaction control (`BEGIN`, `COMMIT`, `SAVEPOINT`) and no Postgres syntax (`timestamptz`, `::` casts,
|
|
190
|
+
`GENERATED ALWAYS AS IDENTITY`, `CREATE TYPE`).
|
|
191
|
+
- SQLite has no `gen_random_uuid()`. A backfill that inserts rows gives each one a key with this expression, a UUID v4
|
|
192
|
+
that `z.uuid()` accepts (`hex(randomblob(16))` alone is not one). It is random, not time-ordered like the UUIDv7 an
|
|
193
|
+
insert of the data layer stamps, so nothing may depend on the order of these keys.
|
|
194
|
+
|
|
195
|
+
```sql
|
|
196
|
+
INSERT INTO deal_tags (id, deal_id, tag)
|
|
197
|
+
SELECT lower(hex(randomblob(4)) || '-' || hex(randomblob(2)) || '-4' || substr(hex(randomblob(2)), 2) || '-'
|
|
198
|
+
|| substr('89ab', 1 + (random() & 3), 1) || substr(hex(randomblob(2)), 2) || '-' || hex(randomblob(6))), id, label
|
|
199
|
+
FROM deals WHERE label IS NOT NULL;
|
|
200
|
+
```
|
|
201
|
+
|
|
158
202
|
## Database code is a declared deviation
|
|
159
203
|
|
|
160
204
|
A function, trigger, view, rule, policy or `DO` block in a migration is allowed. The migration file declares it, and
|
|
@@ -10,9 +10,11 @@ longer writes. Commit them; never edit, format or import them (`generated-test-h
|
|
|
10
10
|
every `on` and `over` endpoint, and every `in` endpoint that declares `sql`, answers nothing of another scope; a
|
|
11
11
|
caller with only an endpoint's write action, plus what IAM requires of it (below), reaches its own object (200). An
|
|
12
12
|
`app` or `creates` endpoint refuses a holder of its action in one scope only (403) and answers a global holder. An
|
|
13
|
-
endpoint of several `capabilities` adds a denied case per capability
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
endpoint of several `capabilities` adds a denied case per capability (none for an `over` one whose action another one
|
|
14
|
+
needs on its dimension, a container of it or a dimension inside it, which gets a `// Not checked:` line instead). A
|
|
15
|
+
public procedure answers anyone without a credential, or, behind a challenge, refuses a caller without a solved one.
|
|
16
|
+
A file input is sent as a generated file of its kind, or as the file the fixtures name (`files`, below); a `GET`
|
|
17
|
+
procedure's input goes in its URL.
|
|
16
18
|
- Their kit stands in for IAM, as `testKit` does (below): it creates a scope, assigns or invites a member and issues a
|
|
17
19
|
link under IAM's rules for the caller's grants. A repeated invitation answers the open one, `resend` restarts its
|
|
18
20
|
7 days, and an organization's address is refused for an external role (`internal_mailbox`). So the caller of an endpoint with the dimension's `members.manage`
|
|
@@ -41,6 +43,11 @@ export const members = { 'api.tasks.assign': ['assignee'] }
|
|
|
41
43
|
`{ 'api.integrations.connectGithub': { orgId: 'acme', account: 'installation:1' } }`. The checker names each missing one,
|
|
42
44
|
and one of an endpoint that does not exist (`endpoint-fixture`). The access form's `from` field is
|
|
43
45
|
replaced by the seeded scope.
|
|
46
|
+
- A `from` field that admits a fixed set of values (`z.enum(['eu', 'us', 'apac'])`, a literal or a union of them) gets
|
|
47
|
+
two of them, one per scope: an enum's first two in sorted order, a union's first two as written. A row the table that owns the dimension already holds
|
|
48
|
+
under that key (a migration wrote the regions) is used as it is; a row the case inserts is removed once it is over.
|
|
49
|
+
Such a stored row takes no `seeds` or `pins`, and a field of one value cannot be asked from two scopes: both fail the
|
|
50
|
+
case.
|
|
44
51
|
- `members['<endpoint id>']` lists the input fields that name a picked person the handler checks with
|
|
45
52
|
`ctx.members.get` (`assign`'s `assignee`). The generated cases send a real member of the object's org there; without
|
|
46
53
|
it they send a sample, the handler answers 400, and the case fails.
|
|
@@ -53,21 +60,57 @@ export const members = { 'api.tasks.assign': ['assignee'] }
|
|
|
53
60
|
endpoint's dimension in both scopes: `close` answers 409 for an open task, so the seed makes it `doing`. A seed
|
|
54
61
|
sets neither a column that places the row nor a text column that holds a marker; a text column a CHECK lists the
|
|
55
62
|
values of, and a foreign key, it may set.
|
|
56
|
-
- `rows['<endpoint id>']` names the input fields that address a row
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
table of the table that owns it, or a table it contains
|
|
60
|
-
(`endpoint-fixture`).
|
|
61
|
-
|
|
63
|
+
- `rows['<endpoint id>']` names the input fields that address a row in the endpoint's scope, with that row's table:
|
|
64
|
+
`export const rows = { 'api.tasks.editComment': { commentId: 'task_comments' } }`. The generated cases seed one row
|
|
65
|
+
of the table in each scope and send its key there. Under `on` and `in` the table lies directly in the object or
|
|
66
|
+
target (a child table of the table that owns it, or a table it contains), and a table owns the dimension; under
|
|
67
|
+
`over` the dimension lists the table. The checker refuses anything else (`endpoint-fixture`). An endpoint with
|
|
68
|
+
`capabilities` names the capability whose scope the row lies in: `'api.tasks.copyToTask#from': { id:
|
|
69
|
+
'task_attachments' }`. Without it they send a sample, the handler finds no row (404), and the case fails.
|
|
70
|
+
- `appRows['<endpoint id>']` gives the rows of application tables (`scope: { app }`) that the endpoint's handler reads
|
|
71
|
+
for the caller's own scope, by table, with the columns they need: `export const appRows = { 'portal.guide': { guides:
|
|
72
|
+
{ active: true } } }`. Each of its leak and own-object cases seeds one row of each before it asks and removes them
|
|
73
|
+
once it is over, with every row that refers to them (a download the handler logged), so a handler that reads the
|
|
74
|
+
newest guide answers 200 instead of 404, and no other endpoint's case finds the row. A foreign key from one given row
|
|
75
|
+
to another holds that row's key. A text column may be given; the key, the version, the creator and a file column may
|
|
76
|
+
not (a file column holds a live, scanned file). Only application tables, and only for an endpoint with a leak or an
|
|
77
|
+
own-object case: the checker refuses a table in a scope, which `rows` and `seeds` address (`endpoint-fixture`).
|
|
78
|
+
- `files['<endpoint id>']` names, by file field, a file of the repository that every case of the endpoint sends there
|
|
79
|
+
instead of the generated one, a path from the application's root:
|
|
80
|
+
`export const files = { 'api.skills.publish': { package: 'src/__tests__/fixtures/skill.zip' } }`. Give one when the
|
|
81
|
+
handler inspects the content (a package it unpacks, a document it parses) and answers 400 to the generated file, which
|
|
82
|
+
has only the leading bytes of its type. Commit the file; keep it small and free of real data. The kit sends it with the
|
|
83
|
+
first type of the field's kind its bytes are, and a file it cannot read, or of none of those types, fails the case. The
|
|
84
|
+
checker refuses a field that holds no file and a path that leaves the application, starts with `.` or has characters
|
|
85
|
+
other than letters, digits, `_`, `-`, `.` and `/` (`endpoint-fixture`).
|
|
86
|
+
- `pins['<endpoint id>']` gives text columns of the row the endpoint addresses (the row of the table that owns its
|
|
87
|
+
dimension) a known value instead of the seed's marker: `export const pins = { 'api.skills.publish': { slug:
|
|
88
|
+
'published-skill' } }`, when the handler ties the column to the input or to the file in `files` (a package whose
|
|
89
|
+
`SKILL.md` names the skill's slug). The own scope's row holds the value, the other scope's `<value>-other`, which a
|
|
90
|
+
leak case still looks for in the own scope's answer. A pin of a column that places the row, or of no text column,
|
|
91
|
+
fails the case; the checker refuses one of an endpoint without an addressed row (`endpoint-fixture`).
|
|
92
|
+
- `refusals['<endpoint id>']` lists the error types of the 400s the endpoint's handler answers with when its rule ties
|
|
93
|
+
the row to the input and the scope is the other one: `export const refusals = { 'api.skills.publish':
|
|
94
|
+
['skill_frontmatter'] }`, beside the pin above. A leak case asks from the other scope first, whose pinned value the
|
|
95
|
+
package does not name; that request may answer one of them. The own case passes on 200 or one of them, and the
|
|
96
|
+
denial cases still expect 404 or 403. The answer a leak case checks, the own scope's, still fails on it, because an
|
|
97
|
+
answer that holds nothing proves no isolation: pin the row and give the file so that the own scope succeeds. Any
|
|
98
|
+
other 400 fails the case, and the checker refuses `validation`, an input the schema refuses (`endpoint-fixture`).
|
|
62
99
|
- The endpoint id is `<mount>.<group>.<endpoint>` (`api.tasks.close`).
|
|
63
100
|
- The seed of the tests fills every text column with a marker and every other required column with a sample of its
|
|
64
|
-
type: an enum's first label, `1`, `false`, today. A column
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
101
|
+
type: an enum's first label, `1`, `false`, today. A number column that a `UNIQUE` index or the primary key covers
|
|
102
|
+
gets the next number above the largest among the rows that share the index's other columns with it instead (`1`
|
|
103
|
+
under a fresh parent, `2` for the insert case beside the seeded row; the whole column for a one-column index), so
|
|
104
|
+
the row collides with no row of the table. A column with a `DEFAULT` keeps it (`status` is `open`). A column a
|
|
105
|
+
`CHECK` names gets the first value of an `IN (…)` list, or `null` where it is nullable. A foreign key outside the
|
|
106
|
+
containment chain is `null` where it is nullable, and otherwise references an existing or a seeded row of a
|
|
107
|
+
reference or application table. What the seed cannot satisfy (another `CHECK` on a required text column, a unique
|
|
108
|
+
number column whose type holds no larger number, a `UNIQUE` index whose sampled values another row holds, such as a
|
|
109
|
+
date, an enum or a boolean unique on its own, a required key to a dimension or child table outside the chain) fails
|
|
110
|
+
the test with a `SeedLimitError` that names the constraint: a limit of the generator, not a bug of the handler. The
|
|
111
|
+
numbering reads only a `UNIQUE` index of plain columns with no `WHERE`. A collision the seed does not write itself (a
|
|
112
|
+
non-number column unique within the parent, which the insert case's row shares with the seeded one) answers 500 in
|
|
113
|
+
the insert case. Keep the column as the domain needs it, and ask the human when the limit blocks the tests.
|
|
71
114
|
- A generated case's input is a sample of the schema: no optional field, `null` for a nullable one, an enum's first
|
|
72
115
|
value, the shortest string its bounds admit (`'x'`), the smallest number, `false`, a fixed value for a format
|
|
73
116
|
(`uuid`, `email`, `iso.date`). When that input meets a precondition (`close` of an `open` task is 409), seed the
|
|
@@ -196,6 +239,9 @@ if (postgres !== null) {
|
|
|
196
239
|
`<label> skipped: set FABRIKA_TEST_POSTGRES_URL to run the Postgres-backed tests`, and the file registers no test.
|
|
197
240
|
A skip proves nothing. To confirm a file ran, run it alone (`bun test --isolate src/tasks`) and check that the pass
|
|
198
241
|
count is its number of tests, or set `FABRIKA_TEST_POSTGRES_REQUIRED=1`: a missing URL then fails the file.
|
|
242
|
+
- On Cloudflare import `testDatabase` from `@fabrika/db/testing-sqlite` instead, with the same options: it migrates a
|
|
243
|
+
fresh in-memory SQLite database as the Durable Object does, needs no URL and never answers `null`. The generated tests
|
|
244
|
+
already use it.
|
|
199
245
|
- `statusOf(call)` answers 200 when the call resolves and the status of the application's refusal otherwise; any other
|
|
200
246
|
failure (no answer, a bug in the test) is rethrown. Import it beside `testKit`; do not write your own.
|
|
201
247
|
- `kit.testCaller(grants, { kind })` makes a caller: a grant is a role or an action, in one scope or global. A
|
|
@@ -281,6 +327,10 @@ if (postgres !== null) {
|
|
|
281
327
|
- `testKit(app, { membership })` replaces the stand-in with your own `IamMembershipRpc`; that kit accepts no
|
|
282
328
|
invitation. `@fabrika/app/testing` exports the types of the options: `IamMembershipRpc` (`membership`),
|
|
283
329
|
`ChallengeFetch` (`challengeFetch`) and `FileScanner` (`scanner`). Import them from there, beside `testKit`.
|
|
330
|
+
- A 5xx or a failed `kit.runJob` names only its code and reason. To see what was thrown (your handler's error, or a
|
|
331
|
+
refusal's own message: a refused `ctx.sql` names its line, a refused column its name), pass a sink while you debug:
|
|
332
|
+
`testKit(app, { database: postgres.database, revealHandlerErrors: (where, error) => console.error(where, error) })`
|
|
333
|
+
(`HandlerErrorSink`). It is off unless passed.
|
|
284
334
|
- `kit.testCaller(grants, { disabled: true })` is a person an operator disabled: the directory lists and finds them
|
|
285
335
|
with `disabled: true`, so an assignment of them answers your handler's 400, and their own requests are refused (401 for
|
|
286
336
|
a session, 403 for a key).
|
|
@@ -290,6 +340,13 @@ if (postgres !== null) {
|
|
|
290
340
|
- A mutation that kicks (`kicks`, `ctx.kick`) starts its job in the background of the call. `kit.drain()` waits for
|
|
291
341
|
those runs, and `kit.runJob` first waits for them; every generated access case drains before it answers. The kicked
|
|
292
342
|
run may start at once, so arm a fault before the call, never between the call and the run.
|
|
343
|
+
- `await kit.runDueJobs({ within: 3 * 3600000 })` runs every job with a wake due now or within `within` milliseconds
|
|
344
|
+
(0 by default) once, as the Cloudflare object's alarm runs it: a cron job's next fire, a kick, a failed run's retry.
|
|
345
|
+
It answers `[{ job, result }]` for the runs it started, and first waits for the kicked runs. Without it the kit fires
|
|
346
|
+
no wake: a cron job runs only through `runJob` or `runDueJobs`. Only the wakes move, never the clock: a handler's
|
|
347
|
+
`new Date()` and a queue row's due time stay real, so a row due later is not claimed early. A second call does not run
|
|
348
|
+
a cron fire the first one ran early. A failed run of a job with `retries` is due again after its backoff, at most a
|
|
349
|
+
second for the first retry, so `runDueJobs({ within: 2000 })` runs it. It needs the application's data layer.
|
|
293
350
|
- `kit.mail` is the stand-in for every job's mail transport (`MemoryEmailSender` of `@fabrika/app/testing`), so a test
|
|
294
351
|
needs no mail variable. `kit.mail.accepted` is what reached the inbox, once per key, and `kit.mail.handoffs` every
|
|
295
352
|
send with its `answer`. `refuse(code?)`, `unavailable()`, `unreachable()`, `loseAnswers(n)` and `during(hook)`
|
|
@@ -89,7 +89,7 @@ export const integrations = app.group({ callers: ['human'] }, (r) => ({
|
|
|
89
89
|
that binds it takes an `app` capability: `access: { action, app: true }`, `binds`, and
|
|
90
90
|
`ctx.webhooks('<webhook>').bind(ctx.app, account)`.
|
|
91
91
|
- `limits: { maxBytes?, timeoutMs? }`: the body is 1 MiB by default and at most 48 MiB; the handler runs 10 s by
|
|
92
|
-
default, at most 60 s. A webhook may declare `kicks`, `signs`, `egress`, `sql` and `unscoped`, and `ctx.files.put`
|
|
92
|
+
default, at most 60 s (25 s on Cloudflare). A webhook may declare `kicks`, `signs`, `egress`, `sql` and `unscoped`, and `ctx.files.put`
|
|
93
93
|
stores a file a provider sends (an inbound e-mail's attachment) for a file column: raise `limits.maxBytes` to the
|
|
94
94
|
mail you accept.
|
|
95
95
|
- Not covered: a provider that validates its URL with a `GET`, or that needs a custom answer body.
|