@fabrika/app 0.9.0-dev.12 → 0.9.0-dev.14

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 (48) hide show
  1. package/package.json +9 -9
  2. package/skill/SKILL.md +7 -4
  3. package/skill/references/app-setup.md +15 -8
  4. package/skill/references/endpoint.md +7 -1
  5. package/skill/references/errors.md +7 -6
  6. package/skill/references/jobs.md +10 -0
  7. package/skill/references/relations.md +682 -0
  8. package/skill/references/table-and-migration.md +18 -7
  9. package/skill/references/webhooks-links-connectors.md +2 -1
  10. package/src/bun.ts +10 -0
  11. package/src/contract/artifact-schema.ts +82 -1
  12. package/src/contract/build.ts +142 -12
  13. package/src/contract/compile.ts +1 -0
  14. package/src/contract/declaration.ts +4 -0
  15. package/src/contract/define.ts +12 -0
  16. package/src/contract/group.ts +10 -1
  17. package/src/contract/kit.ts +3 -1
  18. package/src/contract/platform.ts +1 -0
  19. package/src/contract/vocabulary.ts +3 -0
  20. package/src/disk-assets.ts +15 -3
  21. package/src/implement/boot.ts +59 -5
  22. package/src/implement/capability.ts +91 -6
  23. package/src/implement/dispatch.ts +334 -17
  24. package/src/implement/egress.ts +409 -9
  25. package/src/implement/implement.ts +28 -1
  26. package/src/implement/invocation.ts +10 -9
  27. package/src/implement/types.ts +15 -4
  28. package/src/implement/webhook.ts +8 -0
  29. package/src/jobs/runner.ts +7 -2
  30. package/src/source-map-path.ts +21 -0
  31. package/src/testing/caller.ts +20 -2
  32. package/src/testing/membership.ts +9 -5
  33. package/types/src/contract/declaration.d.ts +6 -0
  34. package/types/src/contract/define.d.ts +15 -0
  35. package/types/src/contract/group.d.ts +9 -1
  36. package/types/src/contract/kit.d.ts +2 -2
  37. package/types/src/contract/vocabulary.d.ts +4 -1
  38. package/types/src/implement/boot.d.ts +6 -0
  39. package/types/src/implement/capability.d.ts +14 -5
  40. package/types/src/implement/dispatch.d.ts +20 -1
  41. package/types/src/implement/egress.d.ts +36 -1
  42. package/types/src/implement/implement.d.ts +24 -1
  43. package/types/src/implement/invocation.d.ts +3 -3
  44. package/types/src/implement/types.d.ts +13 -3
  45. package/types/src/jobs/runner.d.ts +3 -0
  46. package/types/src/source-map-path.d.ts +4 -0
  47. package/types/src/testing/caller.d.ts +6 -1
  48. package/types/src/testing/membership.d.ts +1 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fabrika/app",
3
- "version": "0.9.0-dev.12",
3
+ "version": "0.9.0-dev.14",
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-dev.12",
113
- "@fabrika/auth-core": "0.9.0-dev.12",
114
- "@fabrika/db": "0.9.0-dev.12",
115
- "@fabrika/email": "0.9.0-dev.12",
116
- "@fabrika/jwks": "0.9.0-dev.12",
117
- "@fabrika/platform": "0.9.0-dev.12",
118
- "@fabrika/platform-node": "0.9.0-dev.12",
119
- "@fabrika/proxy-core": "0.9.0-dev.12",
112
+ "@fabrika/auth": "0.9.0-dev.14",
113
+ "@fabrika/auth-core": "0.9.0-dev.14",
114
+ "@fabrika/db": "0.9.0-dev.14",
115
+ "@fabrika/email": "0.9.0-dev.14",
116
+ "@fabrika/jwks": "0.9.0-dev.14",
117
+ "@fabrika/platform": "0.9.0-dev.14",
118
+ "@fabrika/platform-node": "0.9.0-dev.14",
119
+ "@fabrika/proxy-core": "0.9.0-dev.14",
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-dev.12
3
+ version: 0.9.0-dev.14
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
@@ -232,6 +232,7 @@ the access check. `references/spa.md` shows the stack.
232
232
  | e-mail (a cron job only) | `mailer: 'installation'` | `ctx.mail.send` |
233
233
  | a file from a public procedure | `file('<kind>')` input, `admission` with `bytesPerHour` | a reference the handler writes into a file column |
234
234
  | an outside HTTPS API | `egress: ['https://api.example.com']` | `fetch` to those (`https://*.<domain>`: one label) |
235
+ | any public website (a job) | `egress: 'public'` | `fetch` to public hosts, never the installation |
235
236
  | a signed link (unsubscribe) | `signs: ['<purpose>']` | `ctx.tokens.sign` |
236
237
  | a webhook binding | `binds: '<webhook>'` | `ctx.webhooks('<webhook>').bind` and `.unbind` |
237
238
  | a job run after the commit | `kicks: ['<job>']` | `ctx.kick('<job>')`, `ctx.kick('<job>', { at })` |
@@ -349,10 +350,12 @@ their errors, the caller, the components, routing, theming, screen tests), `tabl
349
350
  `ctx.url`, a mount's `compatibility`, another origin, members and labels), `tests.md` (generated tests, seeds, `testKit`, a reused scope, a caller's label, confirming a file ran),
350
351
  `errors.md` (checker findings, type errors, runtime answers), `dev.md` (the seed and the preview), `jobs.md` (which dimension `ctx.within` names, the UTC
351
352
  day, queue tables and `claim`, e-mail through `ctx.mail` with attachments and unsubscribe, the outbox and `kicks`),
352
- `files.md` and `webhooks-links-connectors.md`, all under `references/`. Two are applications of their own:
353
+ `files.md` and `webhooks-links-connectors.md`, all under `references/`. Three are applications of their own:
353
354
  `start.md`, a new application before its first table (its first test, adding the first table, installing and updating
354
- this skill), and `public-intake.md`, a public page, public procedures, a job that claims their rows, issues links and
355
- e-mails them, a link holder's files, HR's review with its history.
355
+ this skill), `public-intake.md`, a public page, public procedures, a job that claims their rows, issues links and
356
+ e-mails them, a link holder's files, HR's review with its history, and `relations.md`, access that rows of the
357
+ application grant and narrow (a relation, a role's `via`, a source table's `confers` and `assign`, a table's `when`
358
+ conditions, `readThrough`, `reveals` and `memberReveals`).
356
359
 
357
360
  ## Not built yet
358
361
 
@@ -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-dev.12",
23
- "@fabrika/db": "0.9.0-dev.12",
24
- "@fabrika/provider-zerops": "0.9.0-dev.12",
25
- "@fabrika/proxy-core": "0.9.0-dev.12",
26
- "@fabrika/ui": "0.9.0-dev.12",
22
+ "@fabrika/app": "0.9.0-dev.14",
23
+ "@fabrika/db": "0.9.0-dev.14",
24
+ "@fabrika/provider-zerops": "0.9.0-dev.14",
25
+ "@fabrika/proxy-core": "0.9.0-dev.14",
26
+ "@fabrika/ui": "0.9.0-dev.14",
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-dev.12",
34
- "@fabrika/cli": "0.9.0-dev.12",
35
- "@fabrika/platform": "0.9.0-dev.12",
33
+ "@fabrika/check": "0.9.0-dev.14",
34
+ "@fabrika/cli": "0.9.0-dev.14",
35
+ "@fabrika/platform": "0.9.0-dev.14",
36
36
  "@happy-dom/global-registrator": "^20.11.2",
37
37
  "@types/bun": "^1.4.3",
38
38
  "@types/react": "^19.0.0",
@@ -245,6 +245,13 @@ zerops:
245
245
  - bun run build:web
246
246
  ```
247
247
 
248
+ `build.base` must be a Bun that reads the committed `bun.lock`: the build installs with `--frozen-lockfile`, and an
249
+ older Bun fails it with `Unknown lockfile version`. A `bun.lock` that Bun 1.4 creates or regenerates has
250
+ `"lockfileVersion": 2`, which needs `alpine/bun@1.4`; versions 0 and 1 build on `alpine/bun@1.3`, which is also the
251
+ base without `build.base`. Raise `build.base` to `alpine/bun@1.4` rather than regenerate the lockfile with Bun 1.3, which
252
+ resolves every dependency afresh. `fabrika app build` refuses a base that cannot read the lockfile and names the one to
253
+ use.
254
+
248
255
  The platform's build runs the tests, writes the entrypoint, runs `fabrika-check` and the type check. Its init commands
249
256
  run `fabrika db migrate`, `fabrika db codegen --verify` and `fabrika db test-isolation` before the server starts: a
250
257
  version does not go live until every generated test passes. It writes every `FABRIKA_*` variable; never set one.
@@ -671,6 +671,11 @@ On Cloudflare a procedure waits for its outside call inside the object's transac
671
671
  with it (`SKILL.md`). A mutation records a row and kicks a job, which declares the `egress` and calls outside
672
672
  `ctx.transaction` (`references/jobs.md`).
673
673
 
674
+ A cron job that calls hosts nobody knows when the contract is written (the websites its operators enter: a crawler, an
675
+ auditor, a link checker) declares `egress: 'public'` instead of a list (`references/jobs.md`). Only a cron job may: a
676
+ procedure, a mutation and a webhook name their origins. Never keep `fetch` from before boot or open sockets to get past
677
+ the list; that is hidden reach.
678
+
674
679
  ## Links to your own procedures: `ctx.url`
675
680
 
676
681
  `ctx.url('<endpoint id>', { input?, query? })` builds an absolute URL of one of the application's own procedures, on
@@ -698,7 +703,8 @@ containing it, that declares `members`: a task endpoint reads its org's. A dimen
698
703
  `member.principalId` and `member.label`, never a label from the input.
699
704
  - `disabled` is a person an operator disabled in IAM: still a member, but unable to sign in. Refuse to assign one
700
705
  (`assign` in `SKILL.md`), and leave them out of a picker.
701
- - The approver sees each endpoint that reads a directory ("looks up one member of `org`"): a new one widens.
706
+ - The approver sees each endpoint that can read a directory ("can look up one member of `org`"): the first one of an
707
+ action and its callers widens; another endpoint of the same action and callers is shown as unchanged.
702
708
  - With the directory's `members.list` action (`tasks.read` here) also `ctx.members.list()`, answering
703
709
  `{ principalId, label, roles, disabled }` per member, for an assignee picker. IAM checks that action on the org
704
710
  itself too.
@@ -31,7 +31,8 @@ The refusals agents meet most, and their fix:
31
31
  | `skipped-test` | `.skip`, `.only`, `.todo` | run the test |
32
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
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`) |
34
+ | `access-view-key` | a table that names an access view has no single-column primary or unique key on its key | a `PRIMARY KEY` or `UNIQUE` on that column alone (`references/relations.md`) |
35
+ | `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`) |
35
36
  | `url-endpoint` | `ctx.url('<id>')` names no procedure of the contract | the endpoint id `<mount>.<group>.<procedure>` |
36
37
  | `cloudflare-scan` | on Cloudflare, a file kind with `scan: true` | the kind without `scan`, and no public procedure that takes its files |
37
38
  | `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 |
@@ -112,11 +113,11 @@ message. The refusal's own message names the place (`'sqlite_master' at line 2`,
112
113
  (`references/tests.md`). The codes
113
114
  you meet most:
114
115
 
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 |
116
+ | Code | Means |
117
+ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
118
+ | `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 |
119
+ | `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`, `encoded_egress`) |
120
+ | `handler_failed` | your handler threw something else; the log has no more: the Operations issue has the stack, `app dev` prints it |
120
121
 
121
122
  With an Operations DSN the same 500 is a `RequestFailed` issue in Operations. Its event also carries what your handler
122
123
  threw: the error's type, its message, its stack and its `cause` chain. Read the stack there, not in the log. A crash
@@ -144,6 +144,16 @@ 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`), read whole before `fetch` answers; a
154
+ compressed answer is refused (`encoded_egress`: the guard asks for `identity`); pass `ctx.signal`, or
155
+ `AbortSignal.any([ctx.signal, AbortSignal.timeout(8_000)])` for a shorter bound per page. The approver reviews it
156
+ closely, as reach to anywhere public. Keep the sites operators enter in a table the job reads.
147
157
  - `ctx.signal` aborts when the attempt ends (its timeout, a lost lease). Call `ctx.signal.throwIfAborted()` before
148
158
  each external effect and pass the signal to `fetch`, so a stale attempt starts nothing after its replacement.
149
159
  - A failed attempt names its failure in `kit.runJob`'s answer and the log: `handler_failed`, a framework failure