Skip to content

Commit 7f048de

Browse files
committed
docs: say what comes after a green test, for the layout that exists
The two feature READMEs stop at the test command, so the step after a green test is a guess: nothing says the feature reaches a real stack through `fun up --k8s`, that registration reads the same `handler.json` the test reads, or that an unregistered method's only symptom arrives later as `No service URL for ...`. Adds a Next section to both, and a page paragraph: a page is a lane rather than a UI framework, and a feature serving a site puts those methods in a second nested manifest (`handlers/pages/handler.json`, `"type": "node-page"`) that the platform builds as its own image — `route` and `accessChannels` being per method, as `features/checkout` shows across all three lanes. Docs only; placeholder tokens untouched.
1 parent 2666f4b commit 7f048de

2 files changed

Lines changed: 88 additions & 0 deletions

File tree

typescript/gql/README.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,3 +61,47 @@ pgpm docker start --image docker.io/constructiveio/postgres-plus:18
6161
eval "$(pgpm env)"
6262
pnpm --filter "@constructive-functions/feature-____name____" test
6363
```
64+
65+
## Next
66+
67+
The test above is the loop: it clones a seeded template database, needs no
68+
cluster, and is the only thing you need while writing the handler. When you want
69+
this feature on a real stack, from the root of the checkout it lives in:
70+
71+
```bash
72+
pnpm fun up --k8s # brings the platform up and registers every feature here
73+
```
74+
75+
Registration reads `handlers/handler.json` — the same file the test reads — so a
76+
manifest-only change needs no rebuild:
77+
78+
```bash
79+
pnpm fun register --apply # write the declaration; --dry-run prints the SQL
80+
```
81+
82+
A registration failure aborts the bring-up rather than being reported as
83+
skipped, which it once was: an unregistered method has no symptom of its own
84+
until something calls it and gets
85+
`No service URL for "____name____:____method____"`.
86+
87+
### If this is a page
88+
89+
A page method is `accessChannels: ["page"]` plus a `route`, and that is the whole
90+
of it: no framework, no build step, no `pages/` directory — the handler answers
91+
with the status, headers and body the browser gets.
92+
93+
A feature that serves a *site* rather than one route puts those methods in a
94+
second manifest nested beside this one, because a page container and a JSON
95+
container are two images:
96+
97+
```
98+
handlers/handler.json the sync/job methods "type": "node-multi-method"
99+
handlers/pages/handler.json the routes a browser lands on "type": "node-page"
100+
```
101+
102+
The nested manifest declares its own `image`, and the platform generates and
103+
builds it as one. `features/auth` in constructive-functions is the reference —
104+
one page image serving four landings, each redirecting with the tenant's session
105+
cookie. Note that `route` and `accessChannels` are per **method**, not per
106+
feature: `features/checkout` serves `checkout:session` at `/session` over `sync`
107+
and `checkout:callback` at `/callback` as a page, from one feature.

typescript/sql/README.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,3 +73,47 @@ pgpm docker start --image docker.io/constructiveio/postgres-plus:18
7373
eval "$(pgpm env)"
7474
pnpm --filter "@constructive-functions/feature-____name____" test
7575
```
76+
77+
## Next
78+
79+
The test above is the loop: it clones a seeded template database, needs no
80+
cluster, and is the only thing you need while writing the handler. When you want
81+
this feature on a real stack, from the root of the checkout it lives in:
82+
83+
```bash
84+
pnpm fun up --k8s # brings the platform up and registers every feature here
85+
```
86+
87+
Registration reads `handlers/handler.json` — the same file the test reads — so a
88+
manifest-only change needs no rebuild:
89+
90+
```bash
91+
pnpm fun register --apply # write the declaration; --dry-run prints the SQL
92+
```
93+
94+
A registration failure aborts the bring-up rather than being reported as
95+
skipped, which it once was: an unregistered method has no symptom of its own
96+
until something calls it and gets
97+
`No service URL for "____name____:____method____"`.
98+
99+
### If this is a page
100+
101+
A page method is `accessChannels: ["page"]` plus a `route`, and that is the whole
102+
of it: no framework, no build step, no `pages/` directory — the handler answers
103+
with the status, headers and body the browser gets.
104+
105+
A feature that serves a *site* rather than one route puts those methods in a
106+
second manifest nested beside this one, because a page container and a JSON
107+
container are two images:
108+
109+
```
110+
handlers/handler.json the sync/job methods "type": "node-multi-method"
111+
handlers/pages/handler.json the routes a browser lands on "type": "node-page"
112+
```
113+
114+
The nested manifest declares its own `image`, and the platform generates and
115+
builds it as one. `features/auth` in constructive-functions is the reference —
116+
one page image serving four landings, each redirecting with the tenant's session
117+
cookie. Note that `route` and `accessChannels` are per **method**, not per
118+
feature: `features/checkout` serves `checkout:session` at `/session` over `sync`
119+
and `checkout:callback` at `/callback` as a page, from one feature.

0 commit comments

Comments
 (0)