@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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fabrika/app",
3
- "version": "0.9.0-cloudflare.3",
3
+ "version": "0.9.0-dev.10",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -109,14 +109,14 @@
109
109
  "test": "bun test --path-ignore-patterns='src/react/**' && bun test --isolate src/react"
110
110
  },
111
111
  "dependencies": {
112
- "@fabrika/auth": "0.9.0-cloudflare.3",
113
- "@fabrika/auth-core": "0.9.0-cloudflare.3",
114
- "@fabrika/db": "0.9.0-cloudflare.3",
115
- "@fabrika/email": "0.9.0-cloudflare.3",
116
- "@fabrika/jwks": "0.9.0-cloudflare.3",
117
- "@fabrika/platform": "0.9.0-cloudflare.3",
118
- "@fabrika/platform-node": "0.9.0-cloudflare.3",
119
- "@fabrika/proxy-core": "0.9.0-cloudflare.3",
112
+ "@fabrika/auth": "0.9.0-dev.10",
113
+ "@fabrika/auth-core": "0.9.0-dev.10",
114
+ "@fabrika/db": "0.9.0-dev.10",
115
+ "@fabrika/email": "0.9.0-dev.10",
116
+ "@fabrika/jwks": "0.9.0-dev.10",
117
+ "@fabrika/platform": "0.9.0-dev.10",
118
+ "@fabrika/platform-node": "0.9.0-dev.10",
119
+ "@fabrika/proxy-core": "0.9.0-dev.10",
120
120
  "altcha-lib": "2.6.0",
121
121
  "jose": "^5.9.0"
122
122
  },
package/skill/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: fabrika-app
3
- version: 0.9.0-cloudflare.3
3
+ version: 0.9.0-dev.10
4
4
  description: >
5
5
  How to write and change a Fabrika application: src/vocabulary.ts, db/migrations/, src/db/tables.ts, the
6
6
  slices' endpoints.ts with their handlers, fabrika.contract.ts, jobs, files, webhooks, share links, connectors
@@ -30,6 +30,7 @@ below. When it does not reach far enough, declare the step off it. A declared st
30
30
  | `fabrika.contract.ts` | `app.contract((c) => ({ api: c.rpc('/api', { … }), … }))`: mounts the groups |
31
31
  | `src/app.ts` | `export default serve(contract, { database: scoped(tables) })` and nothing else |
32
32
  | `web/` | the SPA: React over `@fabrika/app/react` and `@fabrika/ui`, never a server module |
33
+ | `tools/` | a developer's tools, such as a command line; the application never loads them |
33
34
 
34
35
  ## The paved road
35
36
 
@@ -231,7 +232,6 @@ the access check. `references/spa.md` shows the stack.
231
232
  | e-mail (a cron job only) | `mailer: 'installation'` | `ctx.mail.send` |
232
233
  | a file from a public procedure | `file('<kind>')` input, `admission` with `bytesPerHour` | a reference the handler writes into a file column |
233
234
  | an outside HTTPS API | `egress: ['https://api.example.com']` | `fetch` to exactly those origins |
234
- | any public website (a job) | `egress: 'public'` | `fetch` to public hosts, never the installation |
235
235
  | a signed link (unsubscribe) | `signs: ['<purpose>']` | `ctx.tokens.sign` |
236
236
  | a webhook binding | `binds: '<webhook>'` | `ctx.webhooks('<webhook>').bind` and `.unbind` |
237
237
  | a job run after the commit | `kicks: ['<job>']` | `ctx.kick('<job>')`, `ctx.kick('<job>', { at })` |
@@ -257,7 +257,10 @@ Which promise the types, the checker, boot, the runtime or the approver keeps, a
257
257
  - An endpoint never sends e-mail; it has no `ctx.mail`. It records an outbox row, declares `kicks: ['<job>']` and calls `ctx.kick('<job>')`, which
258
258
  starts that job once its transaction committed. The job declares `mailer` and sends with `ctx.mail`, under a key
259
259
  derived from the row, and sends again only where `ctx.mail.mayRetry(error)` allows it (`references/jobs.md`).
260
- - No `as` (except `as const`), `any`, `@ts-ignore`, `@ts-expect-error`, `process.env` or `Bun.env`.
260
+ - No `as` (except `as const`), `any`, `@ts-ignore`, `@ts-expect-error`, `process.env` or `Bun.env`. A developer's tool
261
+ under `tools/` (a command line that calls a deployed environment with a service key) may read the environment and
262
+ spawn a process; it still has no `as`, `any` or key literal, the application never imports it, and `tools/` holds
263
+ no `package.json`. Its tests run in the platform build, so they test its logic, without a keychain or a network.
261
264
  - Never log an error object, a request, headers or the environment.
262
265
  - Never edit a generated file (`src/db/schema.generated.ts`, the generated tests, `fabrika/entry.generated.ts`,
263
266
  `fabrika/migrations.generated.ts`, `fabrika/connect/`) or a committed migration. Regenerate the file; write a new migration.
@@ -19,20 +19,20 @@ the SPA is added with it.
19
19
  "test": "bun test --isolate"
20
20
  },
21
21
  "dependencies": {
22
- "@fabrika/app": "0.9.0-cloudflare.3",
23
- "@fabrika/db": "0.9.0-cloudflare.3",
24
- "@fabrika/provider-zerops": "0.9.0-cloudflare.3",
25
- "@fabrika/proxy-core": "0.9.0-cloudflare.3",
26
- "@fabrika/ui": "0.9.0-cloudflare.3",
22
+ "@fabrika/app": "0.9.0-dev.10",
23
+ "@fabrika/db": "0.9.0-dev.10",
24
+ "@fabrika/provider-zerops": "0.9.0-dev.10",
25
+ "@fabrika/proxy-core": "0.9.0-dev.10",
26
+ "@fabrika/ui": "0.9.0-dev.10",
27
27
  "kysely": "0.29.6",
28
28
  "react": "^19.0.0",
29
29
  "react-dom": "^19.0.0",
30
30
  "zod": "^3.25.76"
31
31
  },
32
32
  "devDependencies": {
33
- "@fabrika/check": "0.9.0-cloudflare.3",
34
- "@fabrika/cli": "0.9.0-cloudflare.3",
35
- "@fabrika/platform": "0.9.0-cloudflare.3",
33
+ "@fabrika/check": "0.9.0-dev.10",
34
+ "@fabrika/cli": "0.9.0-dev.10",
35
+ "@fabrika/platform": "0.9.0-dev.10",
36
36
  "@happy-dom/global-registrator": "^20.11.2",
37
37
  "@types/bun": "^1.4.3",
38
38
  "@types/react": "^19.0.0",
@@ -53,7 +53,9 @@ export default seed
53
53
  - Check every call the seed makes: an endpoint that refuses answers a status, and the seed goes on without its data.
54
54
  Throw when one does: a seed that throws stops `app dev` and prints its error with the stack.
55
55
  - `dev.runJob('<job>')` runs a cron job from the seed (`app dev` runs none on its schedule). A job's `ctx.links` works:
56
- the stand-in IAM takes the job's own key. What a job's handler throws is printed with its stack, here only.
56
+ the stand-in IAM takes the job's own key. What a request's 5xx or a job attempt threw is printed with its stack, here
57
+ only, after the log line that names its code and reason: your handler's own error, or a framework refusal with its
58
+ own message (a refused `ctx.sql` names its line).
57
59
 
58
60
  ## Outside the application
59
61
 
@@ -144,7 +144,11 @@ copyToTask: r.mutation({
144
144
  (`on` 404, `in` and `over` 403).
145
145
  - The handler binds each with `ctx.db.on(…)`, `ctx.db.in(…)` or `ctx.db.over(…)`. It has no `ctx.target`,
146
146
  `ctx.within`, `ctx.db.app`, `ctx.members` or `ctx.links`.
147
- - The generated tests add a denied case per capability. A join or a lock over many rows still needs `sql`.
147
+ - The `from` fields are gone from `input`, as under a single `on` or `in`: `input.toTaskId` is a type error. Each id
148
+ is its capability's value, `ctx.capabilities.to.value`.
149
+ - The generated tests add a denied case per capability, except an `over` one whose action another one needs on its
150
+ dimension, a container of it or a dimension inside it: every caller that passes that one is answered the list. Two
151
+ capabilities may share an action. A join or a lock over many rows still needs `sql`.
148
152
 
149
153
  ### The methods of each handle
150
154
 
@@ -188,9 +192,10 @@ picker of the org a new project goes into; an `'all'` caller types the org inste
188
192
  - `list({ where, orderBy, limit, after })` answers `{ items, next }`: a keyset page of at most `limit` rows (50 by
189
193
  default, 500 at most). Pass `next` back as `after`; it is `null` on the last page.
190
194
  - `where` is AND of `[column, operator, value]`: `=`, `<>`, `<`, `<=`, `>`, `>=`, `in` and `not in` (a list),
191
- `like`, `ilike`, `not like`, `not ilike`, `contains`. Optional filters are conditional spreads, each tuple
195
+ `like`, `ilike`, `not like`, `not ilike`, `contains`, and `is` and `is not` with `null` on a nullable column
196
+ (`['processed_at', 'is', null]`). Optional filters are conditional spreads, each tuple
192
197
  `as const` (`list` in `SKILL.md`): `...(input.status === undefined ? [] : [['status', '=', input.status] as const])`.
193
- There is no `is null` and no OR: write that in `ctx.sql`.
198
+ There is no OR: write that in `ctx.sql`. `count` and a queue table's `claim` (`references/jobs.md`) take the same `where`.
194
199
  - `orderBy` is `[[column, 'asc' | 'desc']]`; the key is added last as the tiebreak.
195
200
  - `count({ where })` answers a number. `aggregate({ groupBy, count, sum, min, max })` takes lists of column names
196
201
  and answers one row per group: the `groupBy` columns, `count` as a string (Postgres `bigint`), and `sum_<column>`,
@@ -420,7 +425,7 @@ export const workloadRows = (
420
425
 
421
426
  ## Raw SQL: `sql: 'read'`
422
427
 
423
- Raw SQL is legitimate for a join, a report, an `OR` or `IS NULL` filter, or a bulk write. Declare it on the endpoint;
428
+ Raw SQL is legitimate for a join, a report, an `OR` filter, or a bulk write. Declare it on the endpoint;
424
429
  `ctx.sql` exists only there. It runs on Postgres and, on Cloudflare, on SQLite (the rules of each are below).
425
430
 
426
431
  ```ts src/reports/endpoints.ts
@@ -658,11 +663,6 @@ On Cloudflare a procedure waits for its outside call inside the object's transac
658
663
  with it (`SKILL.md`). A mutation records a row and kicks a job, which declares the `egress` and calls outside
659
664
  `ctx.transaction` (`references/jobs.md`).
660
665
 
661
- A cron job that calls hosts nobody knows when the contract is written (the websites its operators enter: a crawler, an
662
- auditor, a link checker) declares `egress: 'public'` instead of a list (`references/jobs.md`). Only a cron job may: a
663
- procedure, a mutation and a webhook name their origins. Never keep `fetch` from before boot or open sockets to get past
664
- the list; that is hidden reach.
665
-
666
666
  ## Links to your own procedures: `ctx.url`
667
667
 
668
668
  `ctx.url('<endpoint id>', { input?, query? })` builds an absolute URL of one of the application's own procedures, on
@@ -8,33 +8,37 @@ 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 | 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
- | `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__/` |
27
- | `spa-server-import` | the SPA loads a server module | the SPA imports `@fabrika/app/client`, the contract, `src/schemas.ts` and `src/shared/` |
28
- | `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 |
29
- | `skipped-test` | `.skip`, `.only`, `.todo` | run the test |
30
- | `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`) |
31
- | `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 |
32
- | `cross-app-fetch` | a `fetch` of an absolute URL under no origin a site declares in `egress`, or one a job's `egress: 'public'` refuses (an IP address, `localhost`) | `egress: ['https://…']` on the site that calls it (`references/endpoint.md`) |
33
- | `url-endpoint` | `ctx.url('<id>')` names no procedure of the contract | the endpoint id `<mount>.<group>.<procedure>` |
34
- | `cloudflare-scan` | on Cloudflare, a file kind with `scan: true` | the kind without `scan`, and no public procedure that takes its files |
35
- | `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 |
36
- | `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 |
37
- | `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 |
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 |
38
42
 
39
43
  The hints:
40
44
 
@@ -70,6 +74,7 @@ A kit error lands on the line of the mistake, in one or two lines that name the
70
74
  | `'member.label' is possibly 'null'` | a nullable column or output; only `directory: 'labels'` makes it text |
71
75
  | `admin is a role IAM defines itself for every application (reserved: admin)` | another role name |
72
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` |
73
78
  | `Property 'margin' does not exist on type 'Omit<DealsTable, "margin">'` | the column has its own read action, which this capability lacks |
74
79
  | `Type 'Date' is not assignable to type 'string'` on a `date` column | a `YYYY-MM-DD` string |
75
80
  | `Cannot find module '@fabrika/…'` and implicit `any`s everywhere | `bun install` (at the repository root in a monorepo) |
@@ -102,13 +107,16 @@ with its message; throw the three business errors for the application's own refu
102
107
 
103
108
  A 500 answers a fixed message; the server log has one line, `fabrika: <endpoint>: <code>: <reason>: <text>`, with a
104
109
  fixed failure code and, for a framework refusal, its reason and the reason's fixed text, never a value or your error's
105
- message. The codes you meet most:
106
-
107
- | Code | Means |
108
- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
109
- | `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 |
110
- | `capability_refused` | a capability of another kind, dimension or action than the call takes (`wrong_capability`, `wrong_action`, `out_of_reach`), one kept past its request (`ended`, `foreign_work`), or a `fetch` its `egress` refuses (`undeclared_egress`, `refused_egress`, `oversized_egress`) |
111
- | `handler_failed` | your handler threw something else; the log has no more: the Operations issue has the stack, or test the handler |
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 |
112
120
 
113
121
  With an Operations DSN the same 500 is a `RequestFailed` issue in Operations. Its event also carries what your handler
114
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. A string id is refused.
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. It answers 409
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
 
@@ -144,20 +144,11 @@ export const contract = app.contract((c) => ({
144
144
  - A job may also declare `kicks` (another job; the edges never form a cycle), `signs` (`ctx.tokens.sign`),
145
145
  `egress` (the HTTPS origins its `fetch` calls) and `issues` (`references/endpoint.md`). `ctx.url('<endpoint id>', …)`
146
146
  builds an absolute link to one of the application's procedures, for an e-mail.
147
- - A job that calls the websites its operators enter (a crawler, an auditor) declares `egress: 'public'`:
148
- `app.cron('*/5 * * * *', { actions: ['sites.read'], egress: 'public' })`. Its `fetch` reaches any public host over
149
- HTTPS or HTTP on the default port. It is refused (`capability_refused: refused_egress`) for an IP address, a name of
150
- one label (`localhost`, an internal service), a name under `.local`, `.internal`, `.workers.dev`, `.zerops.app` and similar, a port,
151
- the installation's own hosts (IAM, Control, Operations, every application's domain) and, on Bun (Zerops), a name
152
- that resolves to a private address. Every redirect is checked again: `redirect: 'manual'` gets the redirect, the default
153
- follows at most 10. A request has 60 s, a response body at most 16 MiB (`oversized_egress`); pass `ctx.signal`, or
154
- `AbortSignal.any([ctx.signal, AbortSignal.timeout(8_000)])` for a shorter bound per page. The approver reviews it
155
- closely, as reach to anywhere public. Keep the sites operators enter in a table the job reads.
156
147
  - `ctx.signal` aborts when the attempt ends (its timeout, a lost lease). Call `ctx.signal.throwIfAborted()` before
157
148
  each external effect and pass the signal to `fetch`, so a stale attempt starts nothing after its replacement.
158
- - A failed attempt names its failure in `kit.runJob`'s answer and the log: `handler_failed`, a framework refusal
159
- with its reason (`query_refused: undeclared_reach`, `capability_refused: undeclared_action`; `references/errors.md`),
160
- 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`).
161
152
 
162
153
  ## E-mail: `mailer` and `ctx.mail`
163
154
 
@@ -229,9 +220,24 @@ for (const row of await ctx.db.app('mail.send').outbox.claim({ limit: 50 })) {
229
220
  has come and whose attempts are below `maxAttempts` (10 by default), `for update skip locked`. It adds one attempt
230
221
  and moves `<due>` by the backoff: the job's schedule period (60 s without one), doubled per attempt, at most 30
231
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.
232
225
  - Claim through the capability you read the table with: `ctx.db.app('<action>').<table>` for an application table,
233
226
  `ctx.db.over(ctx.within('<action>', '<dimension>')).<table>` for a scoped one. The action is the table's `update`
234
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
+ ```
235
241
  - Finish each row in its own transaction through `tx.db.on(row.ref)`: `.update(values, { expectVersion, done: true })`
236
242
  writes and clears `<due>`; `.remove({ expectVersion })` deletes the row (the table's delete action);
237
243
  `.requeue({ at? })` makes it due again at `at` (now by default) with no attempts, for a dead row or a reminder moved
@@ -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. JSON, `bytea`, arrays and domains are refused.
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`),
@@ -164,13 +178,26 @@ no URL. The rules above for keys, chains, composite foreign keys, `version` and
164
178
  database enforces foreign keys.
165
179
 
166
180
  - The declared types codegen reads: `TEXT` (a UUID too), `INTEGER`, `REAL`, `BLOB`; `BOOLEAN`, stored as 0 or 1 and
167
- read as a boolean; `TIMESTAMP`, stored as UTC ISO text and read as a `Date`; `DATE`, `YYYY-MM-DD` text. Any other
168
- declared type is refused. A `STRICT` table admits only `INTEGER`, `REAL`, `TEXT` and `BLOB`, so a table with a
169
- `BOOLEAN`, `TIMESTAMP` or `DATE` column is not `STRICT`.
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`.
170
187
  - SQLite has no `ENUM`: a column with a fixed set of values is `TEXT` with `CHECK (<column> IN ('a', 'b'))`. The
171
188
  generated tests write its first value.
172
189
  - No transaction control (`BEGIN`, `COMMIT`, `SAVEPOINT`) and no Postgres syntax (`timestamptz`, `::` casts,
173
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
+ ```
174
201
 
175
202
  ## Database code is a declared deviation
176
203
 
@@ -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. A public procedure answers anyone without a
14
- credential, or, behind a challenge, refuses a caller without a solved one. A file input is sent as a generated file
15
- of its kind, or as the file the fixtures name (`files`, below); a `GET` procedure's input goes in its URL.
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`
@@ -90,13 +92,19 @@ export const members = { 'api.tasks.assign': ['assignee'] }
90
92
  other 400 fails the case, and the checker refuses `validation`, an input the schema refuses (`endpoint-fixture`).
91
93
  - The endpoint id is `<mount>.<group>.<endpoint>` (`api.tasks.close`).
92
94
  - The seed of the tests fills every text column with a marker and every other required column with a sample of its
93
- type: an enum's first label, `1`, `false`, today. A column with a `DEFAULT` keeps it (`status` is `open`). A column
94
- a `CHECK` names gets the first value of an `IN (…)` list, or `null` where it is nullable. A foreign key outside
95
- the containment chain is `null` where it is nullable, and otherwise references an existing or a seeded row of a
96
- reference or application table. What the seed cannot satisfy (another `CHECK` on a required text column, a required
97
- key to a dimension or child table outside the chain) fails the test with a `SeedLimitError` that names the
98
- constraint: a limit of the generator, not a bug of the handler. Keep the column as the domain needs it, and ask the
99
- human when the limit blocks the tests.
95
+ type: an enum's first label, `1`, `false`, today. A number column that a `UNIQUE` index or the primary key covers
96
+ gets the next number above the largest among the rows that share the index's other columns with it instead (`1`
97
+ under a fresh parent, `2` for the insert case beside the seeded row; the whole column for a one-column index), so
98
+ the row collides with no row of the table. A column with a `DEFAULT` keeps it (`status` is `open`). A column a
99
+ `CHECK` names gets the first value of an `IN (…)` list, or `null` where it is nullable. A foreign key outside the
100
+ containment chain is `null` where it is nullable, and otherwise references an existing or a seeded row of a
101
+ reference or application table. What the seed cannot satisfy (another `CHECK` on a required text column, a unique
102
+ number column whose type holds no larger number, a `UNIQUE` index whose sampled values another row holds, such as a
103
+ date, an enum or a boolean unique on its own, a required key to a dimension or child table outside the chain) fails
104
+ the test with a `SeedLimitError` that names the constraint: a limit of the generator, not a bug of the handler. The
105
+ numbering reads only a `UNIQUE` index of plain columns with no `WHERE`. A collision the seed does not write itself (a
106
+ non-number column unique within the parent, which the insert case's row shares with the seeded one) answers 500 in
107
+ the insert case. Keep the column as the domain needs it, and ask the human when the limit blocks the tests.
100
108
  - A generated case's input is a sample of the schema: no optional field, `null` for a nullable one, an enum's first
101
109
  value, the shortest string its bounds admit (`'x'`), the smallest number, `false`, a fixed value for a format
102
110
  (`uuid`, `email`, `iso.date`). When that input meets a precondition (`close` of an `open` task is 409), seed the
@@ -313,6 +321,10 @@ if (postgres !== null) {
313
321
  - `testKit(app, { membership })` replaces the stand-in with your own `IamMembershipRpc`; that kit accepts no
314
322
  invitation. `@fabrika/app/testing` exports the types of the options: `IamMembershipRpc` (`membership`),
315
323
  `ChallengeFetch` (`challengeFetch`) and `FileScanner` (`scanner`). Import them from there, beside `testKit`.
324
+ - A 5xx or a failed `kit.runJob` names only its code and reason. To see what was thrown (your handler's error, or a
325
+ refusal's own message: a refused `ctx.sql` names its line, a refused column its name), pass a sink while you debug:
326
+ `testKit(app, { database: postgres.database, revealHandlerErrors: (where, error) => console.error(where, error) })`
327
+ (`HandlerErrorSink`). It is off unless passed.
316
328
  - `kit.testCaller(grants, { disabled: true })` is a person an operator disabled: the directory lists and finds them
317
329
  with `disabled: true`, so an assignment of them answers your handler's 400, and their own requests are refused (401 for
318
330
  a session, 403 for a key).
package/src/bun.ts CHANGED
@@ -14,7 +14,6 @@ import { directoryEmailProvider } from '@fabrika/email/directory'
14
14
  import { parseJwks } from '@fabrika/jwks'
15
15
  import type { FileObjectStore } from '@fabrika/platform'
16
16
  import { applicationRuntimeUrl, S3BlobStore } from '@fabrika/platform-node'
17
- import { lookup } from 'node:dns/promises'
18
17
  import { diskAssets } from './disk-assets.js'
19
18
  import type { FetchService, RequestExecutionContext } from './fetch.js'
20
19
  import { clamscanScanner } from './files/clamscan.js'
@@ -551,7 +550,6 @@ async function startContractServer(
551
550
  membership,
552
551
  terminals,
553
552
  workloadTokens,
554
- resolveHost,
555
553
  requireProxySecret: true,
556
554
  localEmailProviders: LOCAL_EMAIL_PROVIDERS,
557
555
  connections: databaseConnections(environment.framework[DATABASE_CONNECTIONS]) ?? DEFAULT_DATABASE_CONNECTIONS,
@@ -587,13 +585,6 @@ async function startContractServer(
587
585
  return { port: server.port ?? port, stop }
588
586
  }
589
587
 
590
- /**
591
- * Every address `hostname` resolves to, as the operating system's resolver answers Bun's own `fetch`: a cron job's public
592
- * egress refuses a hop whose name resolves to any private one (ADR-0071).
593
- */
594
- const resolveHost = async (hostname: string): Promise<readonly string[]> =>
595
- (await lookup(hostname, { all: true, verbatim: true })).map((entry) => entry.address)
596
-
597
588
  /** The application module at `path`, imported when the loader runs; its default export must be what `serve` returned. */
598
589
  export function implementationAt(path: string): ImplementationLoader {
599
590
  return async () => {
@@ -640,7 +631,6 @@ export async function runContractJob(
640
631
  membership,
641
632
  terminals,
642
633
  workloadTokens,
643
- resolveHost,
644
634
  requireProxySecret: true,
645
635
  localEmailProviders: LOCAL_EMAIL_PROVIDERS,
646
636
  // ClamAV on PATH, as the provider's build installs it for a `scan: true` file kind; missing, the scan fails closed.