@dokebi/app 0.4.2 → 0.4.6
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/AI.md +46 -17
- package/README.md +21 -5
- package/dist/describe.d.ts +37 -0
- package/dist/describe.js +79 -0
- package/dist/index.d.ts +108 -11
- package/dist/index.js +315 -65
- package/package.json +17 -6
- package/templates/app/controllers/home.ts +7 -3
- package/templates/app/models/site.ts +4 -4
- package/templates/app/services/site.ts +7 -0
- package/templates/app-inertia/controllers/home.ts +7 -3
- package/templates/app-inertia/models/site.ts +4 -4
- package/templates/app-inertia/services/site.ts +7 -0
- package/templates/app-inertia/views/app.js +20 -6
- package/templates/app-inertia/views/default/Layout.vue +21 -1
- package/templates/app-inertia/views/default/Pages/Error.vue +2 -2
- package/templates/app-inertia/views/default/Pages/Home.vue +3 -2
- package/templates/app-inertia-ssr/views/ssr.js +3 -0
- package/templates/inertia-build/build.json +5 -2
- package/templates/inertia-build/page.d.ts +21 -0
- package/templates/inertia-build/tsconfig.vue.json +9 -0
- package/templates/inertia-build/typecheck-vue.mjs +14 -0
- package/templates/inertia-build/vite.config.ts +27 -4
- package/templates/inertia-build/vite.ssr.config.ts +16 -6
package/AI.md
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
# AI guide — @dokebi/app
|
|
1
|
+
# AI guide — @dokebi/app
|
|
2
2
|
|
|
3
|
-
A plugin for several apps in one project that **picks the app and template by request domain** (D-0030). One app is one folder `src/apps/<app>/`, defined with `defineApp`. Node >=24.0.0, core ^0.4.0, web ^0.4.
|
|
3
|
+
A plugin for several apps in one project that **picks the app and template by request domain** (D-0030). One app is one folder `src/apps/<app>/`, defined with `defineApp`. Node >=24.0.0, core ^0.4.0, web ^0.4.3; @dokebi/session optional (0.4.1: a refused HTML form goes back to its page, §4). The human-oriented description is the [README](README.md).
|
|
4
4
|
|
|
5
5
|
## 1. Install and what it creates
|
|
6
6
|
|
|
7
7
|
```sh
|
|
8
|
-
npx dokebi add @dokebi/app # installs web, controller and template-ejs too; first app src/apps/main, localhost → main
|
|
8
|
+
npx dokebi add @dokebi/app # installs web, controller and template-ejs too; first app src/apps/main, main.<project>.localhost → main
|
|
9
9
|
npx dokebi app add shop --domain a.com --domain www.a.com
|
|
10
10
|
npx dokebi app add admin --inertia [--ssr] --domain admin.a.com # a Vue app (+ server rendering)
|
|
11
11
|
npx dokebi app link shop b.com --template christmas
|
|
@@ -28,12 +28,14 @@ src/apps/<app>/
|
|
|
28
28
|
app.ts export default defineApp({ ... })
|
|
29
29
|
routes.ts routes
|
|
30
30
|
controllers/ this app's defineController tokens
|
|
31
|
-
|
|
31
|
+
services/ data and workflows through models
|
|
32
|
+
models/ persistence and pure data computations
|
|
32
33
|
views/default/ the default template (required). EJS: home.ejs / Inertia: Layout.vue, Pages/**/*.vue (subfolders work: `Posts/Show` is Pages/Posts/Show.vue)
|
|
33
34
|
views/<template>/errors/404.ejs, errors/error.ejs (EJS, optional) error pages for browser pages (D-0074)
|
|
34
35
|
views/<template>/Pages/Error.vue (Inertia, with inertia.errorPage) the error page component
|
|
35
36
|
views/<template>/ only the files that change
|
|
36
37
|
views/app.js (Inertia) browser entry views/ssr.js (--ssr) server entry
|
|
38
|
+
public/ (EJS) the app's browser files: CSS, images, fonts, browser scripts → /assets/<path> (needs @dokebi/static)
|
|
37
39
|
sockets/ (optional) defineSocket
|
|
38
40
|
```
|
|
39
41
|
|
|
@@ -51,7 +53,7 @@ Do not put features several apps share into an app; make a feature module (`npx
|
|
|
51
53
|
| `apps` | `{ <app>: { realtime?: { namespaces } } }` | none | per-app settings. **Keys must be defined app names** (otherwise the start fails with `UNKNOWN_APP`) |
|
|
52
54
|
| `apps.<app>.realtime.namespaces` | 1 to 32 names (`^[a-z][a-z0-9-]{0,31}$`, no duplicates) | `[<app>]` | this app's realtime spaces (§4 realtime namespaces, D-0061) |
|
|
53
55
|
|
|
54
|
-
The host is dokebi-web's `requestHost()` (`X-Forwarded-Host` with trustProxy) without the port, in lower case, compared **exactly**. There are no wildcards or path prefixes. Behind a proxy, put the proxy addresses into dokebi-web `trustProxy`.
|
|
56
|
+
The host is dokebi-web's `requestHost()` (`X-Forwarded-Host` with trustProxy; behind a tunnel or reverse proxy set `trustProxy`, @dokebi/web AI.md §2.6) without the port and a trailing dot (`a.com.` is `a.com`), in lower case, compared **exactly**. `unknownDomain` answers only a Host that is a host name, an IP address or empty; any other Host header (`a.com/x`, `user@a.com`, markup) is refused like an unknown host, so it never reaches `page.app.domain`. There are no wildcards or path prefixes. Behind a proxy, put the proxy addresses into dokebi-web `trustProxy`.
|
|
55
57
|
|
|
56
58
|
## 4. defineApp
|
|
57
59
|
|
|
@@ -69,8 +71,9 @@ export default defineApp({
|
|
|
69
71
|
modules: { '/board': board }, // mounts the module's routes, sockets and views on this app's domains
|
|
70
72
|
shared: (request, page) => ({ menu: MENU }), // merged under every EJS page's data (page values win)
|
|
71
73
|
routes(route, app) {
|
|
74
|
+
const products = app.controller(productController); // at the top: an unlisted controller fails the start
|
|
72
75
|
route.get('/', async (request, reply, page) =>
|
|
73
|
-
page.view.reply(reply, 'home', { items: await
|
|
76
|
+
page.view.reply(reply, 'home', { items: await products.list() }, { layout: 'layouts/main' }),
|
|
74
77
|
);
|
|
75
78
|
},
|
|
76
79
|
sockets: (app) => [chatSocket(app)],
|
|
@@ -81,11 +84,12 @@ export default defineApp({
|
|
|
81
84
|
|
|
82
85
|
- `route`: `get`, `post`, `put`, `patch`, `delete(url, handler, options?)` and `route(options)`. Handlers are `(request, reply, page)`. Options are `WebRoute` options without `handler` and `constraints` (so `seal` works).
|
|
83
86
|
- `page`: `{ app: { name, template, domain }, module, base, view, inertia, sealed }`. In app routes `module` is undefined and `base` is `''`.
|
|
84
|
-
- `view`: the EJS renderer. Lookup order `<app>/<template>` → `<app>/default` → `src/shared/views` (layouts and `$include` too). Every page's data also has `errors`, `old` and `flash` (0.4.1, below), always objects.
|
|
85
|
-
- `inertia`: an Inertia renderer with the app's document settings (when the app has `inertia`). It adds `app` (`{ name, template, domain }`) and `sealed` to the shared props.
|
|
87
|
+
- `view`: the EJS renderer. Lookup order `<app>/<template>` → `<app>/default` → `src/shared/views` (layouts and `$include` too). Every page's data also has `errors`, `old` and `flash` (0.4.1, below), `seal` (`{ head }`, D-0092, §4 seal hosts), always objects, and what plugins contribute to `dokebi-web:view-data` (D-0076 §5, for example `data.csrf` of a CSRF plugin): after `sealed` and the flash, before the app's `shared` and the page data (those win). Error views get it too. Two plugins with one key, or a plugin key `sealed`/`seal`/`errors`/`old`/`flash`, refuse the setup (`VIEW_DATA_CONFLICT`).
|
|
88
|
+
- `inertia`: an Inertia renderer with the app's document settings (when the app has `inertia`). It adds `app` (`{ name, template, domain }`) and `sealed` to the shared props; `src/infra/inertia/page.d.ts`, which `dokebi app add --inertia` writes once, types them for the Vue type check of `npm run typecheck` (`vue-tsc`).
|
|
86
89
|
- `sealed`: whether the request host has `seal: true`. EJS data gets it as `sealed` too (the app's `shared` and the page data win).
|
|
87
|
-
-
|
|
88
|
-
- `
|
|
90
|
+
- **Controllers are read at the top of `routes()`**, which runs after they are created: a controller missing from `controllers` then fails the start with `UNKNOWN_CONTROLLER` naming it. Read inside a handler (`() => app.controller(x)`), the same mistake is a 500 on the first request of that route.
|
|
91
|
+
- `app` (AppContext): `name`, `logger`, `signal`, `get`, `getDependency`, `getOptionalDependency`, `controller`, `defer`, `realtime(namespace?)` (§4 realtime namespaces). **Reading something not in `requires` is an error** (`NOT_REQUIRED`: `App <app> does not list <plugin> in requires`). Controller factories have the same limit. When several apps require the same plugin, dokebi-app declares it once to core with the semver AND of every distinct range (`^1.0.0` and `^1.2.0` give `>=1.0.0 <2.0.0-0 >=1.2.0 <2.0.0-0`; `||` alternatives are combined pair by pair), satisfied by exactly the versions every app's own range admits: a prerelease provider is accepted only when each app's range admits that prerelease (`>=1.0.0 <2.0.0` never admits `1.1.0-beta.2`, whatever another app allows), required when any app requires it, with the first factory (`create`) given. Ranges that cannot meet (`^1.0.0` and `^2.0.0`) are refused at `createPlugin` with `DEPENDENCY_CONFLICT` naming both apps.
|
|
92
|
+
- `inertia.ssr: { bundle: 'dist/ssr/<app>/ssr.js', timeoutMs? }` renders the first HTML on the server (D-0039, see the template-inertia AI.md); `timeoutMs` (default 5000) bounds one render, past it `SSR_TIMEOUT` goes through `failure` (D-0107).
|
|
89
93
|
- `inertia.errorPage: 'Error'` renders that page component for the error answers of this app's Inertia visits and page loads (D-0074; `false` turns off a plugin-level default). The `app add --inertia` skeleton sets it and creates `views/default/Pages/Error.vue`.
|
|
90
94
|
|
|
91
95
|
### Errors on an app's hosts (D-0074)
|
|
@@ -93,8 +97,8 @@ export default defineApp({
|
|
|
93
97
|
Every error answer on an app's host — a thrown error, a refused schema, an unknown route (404) — goes through this app first (a dokebi-web error responder):
|
|
94
98
|
|
|
95
99
|
1. **Inertia** (`inertia` set): the app's scope answers an Inertia validation error with the redirect back (`errors` in the session flash, template-inertia §3.3) and other errors with `inertia.errorPage` when set.
|
|
96
|
-
2. **HTML form back** (0.4.1, D-0074 addendum 1): an HTML form post (body `application/x-www-form-urlencoded` or `multipart/form-data`, answered with HTML — not `fetch`, XHR, Bearer, JSON or Inertia) refused with 422 `VALIDATION_FAILED` (a route schema or `validationError()`) goes **back to its page** when the request has a session (@dokebi/session registered) and a `Referer` of the same host: `errors` (`{ field: message }`) and `old` (the body's top-level values without password-like fields such as `password`, `token`, `secret`, `api_key`, `card`, `cvc`, `otp`, `pin`; nothing when larger than 8 KB) are flashed and the answer is **303 to the Referer** (its path and query). Without a session, or with a missing or foreign Referer (0.4.2: also one whose path reads as another host, such as `//other.host/…`), it is the 422 error view below (no redirect, so no loop).
|
|
97
|
-
3. **EJS error views** (an HTML answer: a browser navigation or an HTML form post): `errors/<status>` (for example `errors/404.ejs`), else `errors/error`, looked up like any page (`<app>/<template>` → `<app>/default` → `src/shared/views`, so a shared `errors/404.ejs` serves every app), with the app's `shared` data and the default layout. Data: `{ status, title ('404 Not Found'), error, message, hint, fields ([{ field, message }], empty unless 422), errors ({ field: message } of a 422), old (the refused form's input, 422 only), fix, stack }` — `fix` and `stack` (5xx) only outside production, otherwise null. An `errors/422.ejs` can therefore show the form again without a session (`<%- await data.$include('posts/form') %>` with the same `data.errors`/`data.old`).
|
|
100
|
+
2. **HTML form back** (0.4.1, D-0074 addendum 1): an HTML form post (body `application/x-www-form-urlencoded` or `multipart/form-data`, answered with HTML — not `fetch`, XHR, Bearer, JSON or Inertia) refused with 422 `VALIDATION_FAILED` (a route schema or `validationError()`) goes **back to its page** when the request has a session (@dokebi/session registered) and a `Referer` of the same host: `errors` (`{ field: message }`) and `old` (the body's top-level values without password-like fields such as `password`, `token`, `secret`, `api_key`, `card`, `cvc`, `otp`, `pin`; nothing when larger than 8 KB) are flashed and the answer is **303 to the Referer** (its path and query). Without a session, or with a missing or foreign Referer (0.4.2: also one whose path reads as another host, such as `//other.host/…`), it is the 422 error view below (no redirect, so no loop). **Any other 4xx can ask for the same redirect** (0.4.3, D-0076 §2.5): an error whose `data.formErrors` is a `{ field: message }` record of strings (thrown by a plugin or a handler, for example `throw new DokebiError('EXPIRED', '…', { plugin: 'blog', status: 409, data: { formErrors: { _form: 'Someone else changed this post.' } } })`) goes back exactly like a 422, with those errors; `_form` is the key of an error about the whole form (`data.errors._form`). @dokebi/csrf uses it for an expired token (`errors._form`, never for a cross-origin post). A 5xx never goes back.
|
|
101
|
+
3. **EJS error views** (an HTML answer: a browser navigation or an HTML form post): `errors/<status>` (for example `errors/404.ejs`), else `errors/error`, looked up like any page (`<app>/<template>` → `<app>/default` → `src/shared/views`, so a shared `errors/404.ejs` serves every app), with the app's `shared` data and the default layout (a **503** view gets neither `shared` nor the plugins' view data such as `data.csrf` or `data.auth`: they may read the store, database or Redis that just failed, [D-0102](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0102-dev-hosts-and-redis-overload.md); write `errors/503.ejs`/`errors/error.ejs` so they render without them, e.g. `data.csrf?.field`). Data: `{ status, title ('404 Not Found'), error, message, hint, fields ([{ field, message }], empty unless 422), errors ({ field: message } of a 422, or `data.formErrors` of another 4xx), old (the refused form's input, 422 only), fix, stack }` — `fix` and `stack` (5xx) only outside production, otherwise null. An `errors/422.ejs` can therefore show the form again without a session (`<%- await data.$include('posts/form') %>` with the same `data.errors`/`data.old`).
|
|
98
102
|
4. Otherwise dokebi-web's own answer: JSON for scripts (Inertia, `fetch`, XHR, Bearer, JSON bodies), a small HTML page for browser pages.
|
|
99
103
|
|
|
100
104
|
JSON clients never get a view, and are never redirected. A view that fails to render (a missing data field, a broken include) falls back to web's page and logs `error` `Web error responder failed` (`WEB_ERROR_RESPONDER_FAILED`, once per route and interval). Refuse input in handlers with `throw validationError({ name: 'Already taken' })` from @dokebi/web (422, the same answer as a refused schema). Debug: `App error view rendered` (app, template, view, status), `App form validation redirect` (app, method, route, fields, old count, target path), `App form validation answered with the error view` (app, reason `no-session` or `no-way-back`, method, route).
|
|
@@ -147,8 +151,20 @@ HTML forms need `dokebi-web.formBody: true` (urlencoded bodies). The flow needs
|
|
|
147
151
|
### Routing and WebSocket
|
|
148
152
|
|
|
149
153
|
- App routes are registered with the Fastify constraint `dokebiApp` (`APP_CONSTRAINT`), so several apps can own the same path. Routes without the constraint (health checks, `@dokebi/router` APIs) answer on every domain.
|
|
154
|
+
- **Routes of other plugins bound to apps (D-0132).** dokebi-app gives dokebi-web its routing (`web.appRouting`: the constraint, the app names, the domain map and the `unknownDomain` app), so any route with `app: '<app>'` or `app: [...]` (dokebi-web AI.md §2.1) — and every plugin option `<plugin>.app` built on it — gets this same constraint at boot. Such a route answers on exactly the hosts an app route of those apps answers on (domains, dev hosts `<app>.<project>.localhost`, a trusted forwarded host, the `unknownDomain` fallback) and every other host gets the 404 of an unknown route there (this app's 404 page, or JSON `NOT_FOUND`). A bound route at the same method and path as a route of the same app fails the start (`ROUTE_APP_CONFLICT`). In dokebi.yaml:
|
|
155
|
+
|
|
156
|
+
```yaml
|
|
157
|
+
dokebi-app:
|
|
158
|
+
domains:
|
|
159
|
+
studio.example.com: { app: studio }
|
|
160
|
+
mcp.example.com: { app: mcp } # an app with no routes of its own is fine
|
|
161
|
+
api.example.com: { app: api }
|
|
162
|
+
dokebi-oauth: { issuer: https://studio.example.com, app: studio, resources: { mcp: { uri: https://mcp.example.com/mcp, app: mcp } } }
|
|
163
|
+
dokebi-mcp: { app: mcp }
|
|
164
|
+
```
|
|
150
165
|
- App sockets use the same constraint. The hub tenant is `<namespace>:<tenant>` (the default namespace is the app name, so without settings it is `<app>:<tenant>`), and the session's `identity.tenant` holds that value. Messages use the `{ type, data, id? }` shape of `defineSocket`.
|
|
151
166
|
- App `events` (SSE, @dokebi/sse) attach with the same constraint and tenant rule (`stream.tenant` is `<namespace>:<tenant>`). Without @dokebi/sse the start fails with `App <app> has event streams; add @dokebi/sse`. The `events` of a mounted module attach under the module prefix with the same rule (`Module <module> (app <app>) has event streams; add @dokebi/sse`).
|
|
167
|
+
- Route ids (D-0140): sockets and event streams take `config: { id }` like app routes (`route.get('/', handler, { config: { id: 'home' } })`), for example `defineSocket({ path: '/ws', config: { id: 'chat' }, … })` and `{ path: '/api/live', config: { id: 'live' }, authenticate }`. `dokebi describe` lists every one as `routes[].id`, dokebi-web's route hooks and `request.routeOptions.config.id` see them (an audit log keyed by route id covers 401 and 403 refusals of sockets and streams too), and the refusal logs carry `routeId` (the warn `NAMESPACE_FORBIDDEN` as well). The id is checked at start like a web route id (`INVALID_ROUTE_CONFIG`), and one id used twice in an app, by its routes, sockets, event streams or those of its modules, fails the start with `DUPLICATE_ROUTE_ID` (dokebi-web's check per app constraint). A module mounted in two apps keeps its ids in each. `config` of a socket or stream takes only `id` (`INVALID_ROUTE` otherwise).
|
|
152
168
|
|
|
153
169
|
### Realtime namespaces (0.2.0, [D-0061](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0061-realtime-namespaces.md))
|
|
154
170
|
|
|
@@ -170,7 +186,7 @@ dokebi-app:
|
|
|
170
186
|
- **The server-side handle** `app.realtime(namespace?)` (`RealtimeHandle`; the first namespace when left out; outside the list it throws `NAMESPACE_FORBIDDEN` at once). The tenant of a target `{ tenant?, member?, room? }` is the authenticated tenant without the prefix. **Leaving out tenant means every tenant of that namespace**.
|
|
171
187
|
- `list(filter?)` → connections (`tenant` (no prefix), `member`, `connection`, `ownerEpoch`, `clientId?`, `rooms`, `metadata`). With a tenant it asks the hub (the whole cluster; failures carry the hub's code); without one it reads the presence this server received (every server, possibly slightly late; an empty list before start).
|
|
172
188
|
- `send(target, type, data?)` → the same `{ type, data }` text frame as defineSocket broadcasts, through the hub (at most once; sealed per sealed socket). Receipt `{ ids, recipients }`. Without a tenant, one broadcast per tenant.
|
|
173
|
-
- `kick(target, code?, reason?)` → closes those connections on every server (4000–4999, default 4403).
|
|
189
|
+
- `kick(target, code?, reason?)` → closes those connections on every server (4000–4999, default 4403). A kick that rejects with `OUTCOME_UNKNOWN` (just after a hub leader failover, a server not yet reconnected) may have left some open and is not kept: when it must take effect (removing a member), call it again until it resolves (@dokebi/websocket AI.md).
|
|
174
190
|
- `onPresence(listener)` → joins and leaves of that space's tenants (`{ tenant, joined, left }`, tenant without prefix). Call the returned function to stop. A listener that throws or rejects is logged by websocket as error `PRESENCE_LISTENER_FAILED`.
|
|
175
191
|
- `publish(target, event, data?)` → @dokebi/sse publishing (that space's streams; every process when there is a bus). Without a tenant, every process writes to its own streams whose tenant has the prefix.
|
|
176
192
|
- When the needed transport is missing it throws `REALTIME_UNAVAILABLE` (list, send, kick and onPresence need the `websocket` transport = @dokebi/websocket; publish needs the `sse` transport = @dokebi/sse).
|
|
@@ -255,11 +271,12 @@ dokebi-app:
|
|
|
255
271
|
- app fills an app socket's `route.seal` from the request host (only when at least one of that app's hosts is sealed; a route's own `seal` is kept on plain hosts too). The **`@dokebi/seal` plugin** (`dokebi-seal`) owns the algorithm and the static files under `/dokebi/seal/*`. This public package only looks it up by name.
|
|
256
272
|
- Pages: when `sealed` is true, load `/dokebi/seal/seal.mjs` and `socket.mjs`, call `initSeal()`, then `connectChannel({ path, seal: sealBridge })`. (Passing the bridge always is fine: the client offers both `dokebi.seal` and `dokebi.plain`, and a plain host picks `dokebi.plain` and runs in plain text. `sealed` decides whether to fetch the wasm early.) Connecting to a seal host without a bridge closes with 4415 (no reconnect); an unopenable frame closes with 4400. Details are in @dokebi/websocket AI.md §4a and the @dokebi/seal README.
|
|
257
273
|
- Same app = same hub tenant, so a broadcast sent on a seal host reaches plain-host sockets in plain text and sealed sockets sealed.
|
|
258
|
-
- **HTTP (D-0062)**: when sealed domains exist, app registers `sealRequests(is the host sealed)` with dokebi-web. Every HTTP request to such a host (app routes or `/api/*` routes a module put directly on web) gets sealed JSON responses, 415 for plain JSON bodies, a sealed Inertia first page and sealed SSE data. An app route with `seal: false` (`route.post('/hook', handler, { seal: false })`) stays plain (webhooks, server to server), as does dokebi-web `sealExclude`. EJS HTML stays as it is
|
|
274
|
+
- **HTTP (D-0062)**: when sealed domains exist, app registers `sealRequests(is the host sealed)` with dokebi-web. Every HTTP request to such a host (app routes or `/api/*` routes a module put directly on web) gets sealed JSON responses, 415 for plain JSON bodies, a sealed Inertia first page and sealed SSE data. An app route with `seal: false` (`route.post('/hook', handler, { seal: false })`) stays plain (webhooks, server to server), as does dokebi-web `sealExclude`. EJS HTML stays as it is (page navigations and their error pages, D-0092 §1).
|
|
275
|
+
- **EJS forms on seal hosts (D-0092)**: every EJS page and error view gets **`data.seal`**: `{ head }`, on a seal host the HTML of an import map (`@dokebi/seal/http` → `/dokebi/seal/http.mjs`, `@dokebi/seal/forms` → `/dokebi/seal/forms.mjs`) and the module script of `/dokebi/seal/forms.mjs`, on a plain host `''`. Write **`<%- data.seal.head %>`** in the `<head>` of the layout, before other module scripts (the shared layout of `npx dokebi add @dokebi/template-ejs` does). The forms module sends every POST form sealed with `x-dokebi-form: 1`: handlers read the urlencoded shape as usual (`dokebi-web.formBody: true`), a 422 (or `data.formErrors`) goes back with `errors` and `old` like any HTML form, other errors render the error views, and REST calls of the page use `sealedFetch` (`@dokebi/seal/http`, the same module instance). **Do not give form routes `seal: false`**: that was the old workaround and leaves the form body plain. A form posted without the module (no JavaScript) gets the HTML 415 page `This page needs its seal script to send forms`. `seal` is a reserved view data key. Example: `examples/45-ejs-seal`. Inertia scopes of apps on sealed domains get `sealed: true`; with SSR only public pages (`page.inertia.render(…, { public: true })`, 0.4.6, D-0195) are server rendered there, plain, and every other page stays sealed (template-inertia AI.md §3.5). The scope's `app` and `sealed` props go in as `publicShared` (the same for every visitor), so a public page's SSR knows `app.template`; `AppInertia.render` takes `public` and `head` (`AppInertiaRenderOptions`). Browser: `sealInertia`, `sealedFetch` and `currentSealBridge` of `@dokebi/seal/http` (the CLI template `views/app.js` imports `@dokebi/seal/http` and calls `sealInertia(http)` on sealed pages and on public pages of a seal host (`meta[name="dokebi-seal"][content="host"]`); `dokebiInertia()` of the generated `vite.config.ts`, from `@dokebi/template-inertia/vite`, makes every import of `@dokebi/seal/http` load the served `/dokebi/seal/http.mjs`, so pages import `sealedFetch` statically and share that seal).
|
|
259
276
|
|
|
260
277
|
## 5. API
|
|
261
278
|
|
|
262
|
-
The API of `createPlugin` is `{ names, resolve(request) }` (`AppGroupApi`). `resolve` returns the request's `{ name, template, domain }` or undefined for an unknown host. Also exported: `APP_CONSTRAINT`, `hostOf(request)` (the Host header without the port, ignoring proxies), `withoutPort(host)`, `options` (the `defineOptions` declaration) and the types (`AppDefinition`, `AppContext`, `AppPage`, `RealtimeHandle`, …). Use `resolve` to decide the app.
|
|
279
|
+
The API of `createPlugin` is `{ names, resolve(request), seal(request) }` (`AppGroupApi`). `seal(request)` is the `data.seal` of an EJS page for the request's host (`{ head }`, `''` on a plain host), for a page rendered outside an app route, such as the consent page of @dokebi/oauth (its form is then sealed like the app's). In its setup dokebi-app also registers the routing of bound routes with dokebi-web (`web.appRouting`, D-0132), before its own routes, and the app of each host (`web.requestApps`, D-0181), so other plugins ask `web.appOf(request)` without depending on dokebi-app — dokebi-i18n translates each app's requests with its layer (`src/apps/<app>/locales/`, @dokebi/i18n AI.md). `resolve` returns the request's `{ name, template, domain }` or undefined for an unknown host. Also exported: `APP_CONSTRAINT`, `hostOf(request)` (the Host header without the port, or the `:authority` of an HTTP/2 request, which wins when both are sent, as in dokebi-web `requestHost`; ignoring proxies), `withoutPort(host)`, `options` (the `defineOptions` declaration) and the types (`AppDefinition`, `AppContext`, `AppPage`, `RealtimeHandle`, …). Use `resolve` to decide the app.
|
|
263
280
|
|
|
264
281
|
## 6. Errors and what is refused at start
|
|
265
282
|
|
|
@@ -268,8 +285,8 @@ The API of `createPlugin` is `{ names, resolve(request) }` (`AppGroupApi`). `res
|
|
|
268
285
|
|
|
269
286
|
| Code | When |
|
|
270
287
|
|---|---|
|
|
271
|
-
| `INVALID_DEFINITION` | unknown fields or bad values in `defineApp`, a bad module prefix, a module not made with `defineModule`, a bad requires item |
|
|
272
|
-
| `DEPENDENCY_CONFLICT` | at `createPlugin`: two apps (or an app and dokebi-app) require one plugin with version ranges no
|
|
288
|
+
| `INVALID_DEFINITION` | unknown fields or bad values in `defineApp`, a bad module prefix, a module not made with `defineModule`, a bad requires item; or a route bound to several apps on a router whose constraint store is not the bit-mask store of find-my-way 9 (D-0132; it never happens with the supported Fastify) |
|
|
289
|
+
| `DEPENDENCY_CONFLICT` | at `createPlugin`: two apps (or an app and dokebi-app) require one plugin with version ranges no version satisfies together (each range's prerelease rule included); the message names both apps and ranges, `details.needs` lists every requirement |
|
|
273
290
|
| `INVALID_ENTRY` | the entry is not `{ apps: { <name>: defineApp(...) } }` (the cause of `INVALID_PLUGIN_INPUT`) |
|
|
274
291
|
| `UNKNOWN_APP` | a domain pointing at an undefined app, or `apps.<app>` naming an undefined app |
|
|
275
292
|
| `SEAL_PROVIDER_MISSING` | a `seal: true` domain exists but the `dokebi-seal` plugin does not (even without sockets) |
|
|
@@ -291,6 +308,7 @@ Debug logs (D-0047): `App domains configured` (domain → app/template, `(sealed
|
|
|
291
308
|
|
|
292
309
|
- Do not branch on the Host header in code. Keep domain → app/template in dokebi.yaml only; handlers read `page.app`.
|
|
293
310
|
- Do not delete `views/default/`. Template folders hold only the files that change.
|
|
311
|
+
- **Browser files** (R1 measurement, user instruction 2026-10-28): an app's style sheets, images, fonts and browser scripts live in `src/apps/<app>/public/`, never in `views/` and never behind a route that reads them by hand. With `@dokebi/static` registered (`npx dokebi add @dokebi/static`), dokebi-app serves that folder at **`/assets/<path>`** on the app's own hosts (a mount bound to the app, id `static.app<name>`: `ETag`, 304, `Range`, `no-cache` by default, no listing, never outside the folder, public under `dokebi-auth.default: required`), so a layout links `/assets/site.css`. Without `@dokebi/static` a `public/` folder is not served and the start warns `APP_PUBLIC_UNSERVED` with that fix; `dokebi check` warns `asset-in-views` for a browser file left in the views of an EJS app. An Inertia app imports its styles and images through Vite from `views/`.
|
|
294
312
|
- Apps do not import each other. Shared code goes into `src/shared/` (models, views) or a module.
|
|
295
313
|
- Do not edit the generated registration code or `.dokebi/state.json`. Change apps and domains with `dokebi app` commands (they are recorded in dokebi.example.yaml too).
|
|
296
314
|
- An Inertia app without its build files fails to start. Run `npm run build` first.
|
|
@@ -299,3 +317,14 @@ Debug logs (D-0047): `App domains configured` (domain → app/template, `(sealed
|
|
|
299
317
|
## 8. References
|
|
300
318
|
|
|
301
319
|
`examples/25-playground` (vue, ejs and admin apps; domains and templates; modules; sockets; namespaces: admin watches the vue and ejs users, chats and publishes SSE), `examples/26-scaffold` (repeated checks of CLI generation), D-0030, D-0031, D-0032, D-0039, D-0059 (seal hosts — the playground's `sealed.localhost`; real server and Chromium checks are @dokebi/seal's `seal:test` and `seal:browser-check`), D-0061, D-0062.
|
|
320
|
+
|
|
321
|
+
## Service composition
|
|
322
|
+
|
|
323
|
+
Use Controller -> Service -> Model for application data. Controllers handle HTTP input/output;
|
|
324
|
+
services provide data and coordinate workflows through models; models own persistence.
|
|
325
|
+
Generated app/module starters include this chain. Keep services free of request/reply and
|
|
326
|
+
rendering objects, and reuse them from jobs. Compose dependencies once during setup.
|
|
327
|
+
App-specific services belong in `src/apps/<app>/services`, cross-app services in
|
|
328
|
+
`src/shared/services`, and module services in `src/shared/modules/<module>/services`.
|
|
329
|
+
Shared services must not import app-specific code. These are ordinary application classes,
|
|
330
|
+
not a new framework plugin or service registry. Existing projects are not moved automatically.
|
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# @dokebi/app 0.4.
|
|
1
|
+
# @dokebi/app 0.4.4
|
|
2
2
|
|
|
3
3
|
An optional plugin for several apps in one project that picks the app and template by request domain. An optional package for Node >=24.0.0 and core ^0.4.0 (public on npm). The design is [D-0030](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0030-multi-app-and-domains.md).
|
|
4
4
|
|
|
@@ -8,7 +8,7 @@ An optional plugin for several apps in one project that picks the app and templa
|
|
|
8
8
|
dokebi add @dokebi/app
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
The required plugins dokebi-web, dokebi-controller and dokebi-template-ejs are installed in the same change (result `autoInstalled`), and the first app `src/apps/main` and `domains: { localhost: { app: main } }` are created. template-ejs comes along at install time because the first app is an EJS skeleton. At run time app collects view engines (`ejs`, `inertia`) and realtime transports (`websocket`, `sse`) by name from @dokebi/web's contribution points and never imports those packages (D-0063 §5). Errors are `AppError` (`VIEW_ENGINE_MISSING`, `REALTIME_UNAVAILABLE` and so on, [AI.md](AI.md) §6). To add more apps:
|
|
11
|
+
The required plugins dokebi-web, dokebi-controller and dokebi-template-ejs are installed in the same change (result `autoInstalled`), and the first app `src/apps/main` and `domains: { main.<project>.localhost: { app: main } }` are created (the project's own development host, from the package.json name or the folder name: two projects on one machine never share its cookies; `dokebi app link main <host>` adds another). template-ejs comes along at install time because the first app is an EJS skeleton. At run time app collects view engines (`ejs`, `inertia`) and realtime transports (`websocket`, `sse`) by name from @dokebi/web's contribution points and never imports those packages (D-0063 §5). Errors are `AppError` (`VIEW_ENGINE_MISSING`, `REALTIME_UNAVAILABLE` and so on, [AI.md](AI.md) §6). To add more apps:
|
|
12
12
|
|
|
13
13
|
```sh
|
|
14
14
|
dokebi app add shop --domain a.com --domain www.a.com
|
|
@@ -58,7 +58,7 @@ dokebi-app:
|
|
|
58
58
|
admin: { realtime: { namespaces: [admin, front] } } # see "Realtime namespaces" below
|
|
59
59
|
```
|
|
60
60
|
|
|
61
|
-
The host from dokebi-web's `requestHost()` (`X-Forwarded-Host` from a trusted proxy) is compared exactly, without the port and in lower case. Behind a proxy, list the proxy addresses in dokebi-web `trustProxy`. There are no wildcards or path prefixes yet. The start refuses unknown apps, missing template folders and a missing `views/default/`.
|
|
61
|
+
The host from dokebi-web's `requestHost()` (`X-Forwarded-Host` from a trusted proxy) is compared exactly, without the port and a trailing dot (`a.com.` is `a.com`) and in lower case. `unknownDomain` answers only a Host that is a host name, an IP address or empty; any other Host header (`a.com/x`, `user@a.com`, markup) is refused like an unknown host. Behind a proxy, list the proxy addresses in dokebi-web `trustProxy`. There are no wildcards or path prefixes yet. The start refuses unknown apps, missing template folders and a missing `views/default/`.
|
|
62
62
|
|
|
63
63
|
## defineApp
|
|
64
64
|
|
|
@@ -86,7 +86,7 @@ export default defineApp({
|
|
|
86
86
|
|
|
87
87
|
- A handler's `page` is `{ app: { name, template, domain }, module, base, view, inertia, sealed }`. In app routes `module` is undefined and `base` is `''`. `view` is an EJS renderer that looks in `<app>/<template>` → `<app>/default` → shared src/shared/views; layouts and `$include` follow the same order. `inertia` uses the app's document settings (Vite entry and so on) and adds `app` to the shared props.
|
|
88
88
|
- **Error pages ([D-0074](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0074-error-responses.md)):** errors on an app's hosts (unknown routes included) go through the app first. An Inertia app answers Inertia validation errors with the redirect back (`errors`) and other errors with `inertia.errorPage` (for example `Error`); for a browser page an EJS app renders `views/<template>/errors/<status>.ejs`, else `errors/error.ejs` (same lookup as pages, with `status`, `title`, `error`, `message`, `hint`, `fields`), else @dokebi/web's small page. JSON clients always get JSON. The `app add` skeletons include `errors/404.ejs` and `errors/error.ejs` (EJS) or `Pages/Error.vue` with `errorPage: 'Error'` (Inertia). Refuse input with `throw validationError({ name: 'Already taken' })` from @dokebi/web.
|
|
89
|
-
- **HTML forms come back (0.4.1, D-0074 addendum 1):** with [@dokebi/session](https://git.nyx-zone.com/dokebi/framework/-/blob/main/plugins/dokebi-session/README.md) registered, an HTML form post refused with 422 `VALIDATION_FAILED` flashes `errors` and `old` (without password-like fields) and answers 303 to the `Referer` of the same host, and every EJS page gets `data.errors`, `data.old` and `data.flash` (always objects, the flash read once per request), so the form shows `<%= data.old.title ?? '' %>` and `data.errors.title`. Without a session, or without a same-host Referer, the refused form gets `errors/422.ejs` (else `errors/error.ejs`) with `fields`, `errors` and `old`. A Referer whose path reads as another host (`//other.host/…`) is no way back (0.4.2). Scripts (`fetch`, XHR, Bearer, JSON, Inertia) keep their JSON. Needs @dokebi/web ^0.4.
|
|
89
|
+
- **HTML forms come back (0.4.1, D-0074 addendum 1):** with [@dokebi/session](https://git.nyx-zone.com/dokebi/framework/-/blob/main/plugins/dokebi-session/README.md) registered, an HTML form post refused with 422 `VALIDATION_FAILED` flashes `errors` and `old` (without password-like fields) and answers 303 to the `Referer` of the same host, and every EJS page gets `data.errors`, `data.old` and `data.flash` (always objects, the flash read once per request), so the form shows `<%= data.old.title ?? '' %>` and `data.errors.title`. Without a session, or without a same-host Referer, the refused form gets `errors/422.ejs` (else `errors/error.ejs`) with `fields`, `errors` and `old`. A Referer whose path reads as another host (`//other.host/…`) is no way back (0.4.2). Another 4xx whose `data.formErrors` is a `{ field: message }` record goes back the same way (0.4.3, D-0076 §2.5; `_form` is the whole-form key, which @dokebi/csrf uses for an expired token). Scripts (`fetch`, XHR, Bearer, JSON, Inertia) keep their JSON. Needs @dokebi/web ^0.4.3.
|
|
90
90
|
- **Mounting modules ([D-0032](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0032-feature-modules.md)):** `modules: { '/prefix': module }`, where the module was made with `defineModule`.
|
|
91
91
|
- The module's `routes` are registered with this app's route constraint and the prefix; handlers get `page.module` and `page.base`.
|
|
92
92
|
- The module's `sockets` are registered under the prefix. Their tenant is `<namespace>:<tenant>`, as for app sockets.
|
|
@@ -101,9 +101,10 @@ export default defineApp({
|
|
|
101
101
|
6. shared views
|
|
102
102
|
- **`shared(request, { app })`:** merged under the data of every EJS page this app renders (app routes and module routes). On overlapping keys the page data wins. Put app data the layout needs, such as the menu or the user, here. It corresponds to Inertia's shared props.
|
|
103
103
|
- `get` and `getDependency` of the app context (`app`) allow only the plugins listed in `requires`. Controller factories have the same limit.
|
|
104
|
-
- A plugin several apps require is checked against every app's version range (
|
|
104
|
+
- A plugin several apps require is checked against every app's version range (core gets their semver AND, which keeps each range's prerelease rule); ranges that cannot meet stop `createPlugin` with `DEPENDENCY_CONFLICT`, naming both apps.
|
|
105
105
|
- App routes are registered with a Fastify route constraint (`dokebiApp`), so several apps can own the same path. Shared routes without the constraint (health checks, module APIs) answer on every domain.
|
|
106
106
|
- The app's WebSocket routes (`sockets`) and SSE routes (`events`, @dokebi/sse) use the same constraint. The hub tenant is `<namespace>:<tenant>` and the default namespace is the app name, so without settings it stays `<app>:<tenant>`, one per app. The session's `identity.tenant` and `stream.tenant` hold this value.
|
|
107
|
+
- Sockets and SSE routes take a route id like app routes (D-0140): `config: { id: 'chat' }` on `defineSocket` or the `SseRoute`. `dokebi describe` lists it, dokebi-web's route hooks and the refusal logs (`routeId`) see it, and an id used twice in one app (routes, sockets, streams and those of its modules together) fails the start with `DUPLICATE_ROUTE_ID`.
|
|
107
108
|
|
|
108
109
|
## Realtime namespaces (0.2.0, [D-0061](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0061-realtime-namespaces.md))
|
|
109
110
|
|
|
@@ -134,6 +135,21 @@ With `domains.<host>.seal: true` (default false), app sockets connected through
|
|
|
134
135
|
- Refused at start (fail closed): a `seal: true` domain without the `dokebi-seal` plugin is `SEAL_PROVIDER_MISSING`. An app on a sealed domain that has sockets with @dokebi/websocket older than 0.3 gets the same code. (The warn `SEAL_WITHOUT_SOCKETS` for sealed apps without sockets was removed by D-0062: HTTP is sealed too.)
|
|
135
136
|
- The rules of sealed connections (4415, 4400, hello, broadcasts) follow "Sealing per host" in the @dokebi/websocket README.
|
|
136
137
|
|
|
138
|
+
## Plugin routes on an app's hosts (D-0132)
|
|
139
|
+
|
|
140
|
+
Routes that other plugins add on dokebi-web answer on every host unless they are bound to apps. dokebi-app gives web its domain map, so a route with `app` and any plugin option `<plugin>.app` (`dokebi-mcp.app: mcp`, `dokebi-oauth.app: studio`, `dokebi-oauth.resources.<id>.app`) answers on exactly that app's hosts, dev hosts and `unknownDomain` included; other hosts get the app's 404 like an unknown route. See [examples/53-app-hosts](https://git.nyx-zone.com/dokebi/framework/-/blob/main/examples/53-app-hosts/README.md).
|
|
141
|
+
|
|
137
142
|
## API
|
|
138
143
|
|
|
139
144
|
`createPlugin` returns the API `{ names, resolve(request) }`. `resolve` returns the request's app, template and domain, or undefined for an unknown Host. `APP_CONSTRAINT` (`'dokebiApp'`), `hostOf(request)` and `withoutPort(host)` are public too.
|
|
145
|
+
|
|
146
|
+
## Service composition
|
|
147
|
+
|
|
148
|
+
Use Controller -> Service -> Model for application data. Controllers handle HTTP input/output;
|
|
149
|
+
services provide data and coordinate workflows through models; models own persistence.
|
|
150
|
+
Generated app/module starters include this chain. Keep services free of request/reply and
|
|
151
|
+
rendering objects, and reuse them from jobs. Compose dependencies once during setup.
|
|
152
|
+
App-specific services belong in `src/apps/<app>/services`, cross-app services in
|
|
153
|
+
`src/shared/services`, and module services in `src/shared/modules/<module>/services`.
|
|
154
|
+
Shared services must not import app-specific code. These are ordinary application classes,
|
|
155
|
+
not a new framework plugin or service registry. Existing projects are not moved automatically.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { type Describer } from '@dokebi/core';
|
|
2
|
+
/**
|
|
3
|
+
* The `core:describe` point of @dokebi/core 0.4.2, declared here by name (its identity) so this
|
|
4
|
+
* package keeps working with older cores, which never describe.
|
|
5
|
+
*/
|
|
6
|
+
export declare const describePoint: import("@dokebi/core").ContributionPoint<Describer>;
|
|
7
|
+
/** One app as `dokebi describe` shows it. */
|
|
8
|
+
export interface DescribedApp {
|
|
9
|
+
readonly name: string;
|
|
10
|
+
/** `ejs` (views/*.ejs), `inertia` (views/<template>/Pages), or null without views. */
|
|
11
|
+
readonly engine: 'ejs' | 'inertia' | null;
|
|
12
|
+
/** The views folder, relative to the working directory. */
|
|
13
|
+
readonly views: string | null;
|
|
14
|
+
/** Template folders found under views (`default` first). */
|
|
15
|
+
readonly templates: readonly string[];
|
|
16
|
+
readonly modules: readonly {
|
|
17
|
+
readonly prefix: string;
|
|
18
|
+
readonly module: string;
|
|
19
|
+
}[];
|
|
20
|
+
readonly requires: readonly string[];
|
|
21
|
+
readonly namespaces: readonly string[];
|
|
22
|
+
}
|
|
23
|
+
/** One page: an EJS view or an Inertia page component. */
|
|
24
|
+
export interface DescribedPage {
|
|
25
|
+
readonly app: string;
|
|
26
|
+
readonly engine: 'ejs' | 'inertia';
|
|
27
|
+
readonly template: string;
|
|
28
|
+
/** EJS: the view name (`home`, `errors/404`); Inertia: the component (`Posts/Index`). */
|
|
29
|
+
readonly name: string;
|
|
30
|
+
readonly file: string;
|
|
31
|
+
}
|
|
32
|
+
/** The app's templates and pages, read from its views folder. */
|
|
33
|
+
export declare function appPages(name: string, views: URL | undefined, inertia: boolean): Promise<{
|
|
34
|
+
templates: string[];
|
|
35
|
+
pages: DescribedPage[];
|
|
36
|
+
folder: string | null;
|
|
37
|
+
}>;
|
package/dist/describe.js
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
// Describe mode (D-0077 B): the apps, their domains and their pages as data, for
|
|
2
|
+
// `dokebi describe --json`. Only used when `context.runtime.describing` is true.
|
|
3
|
+
import { readdir } from 'node:fs/promises';
|
|
4
|
+
import { join, relative, sep } from 'node:path';
|
|
5
|
+
import { fileURLToPath } from 'node:url';
|
|
6
|
+
import { definePoint } from '@dokebi/core';
|
|
7
|
+
/**
|
|
8
|
+
* The `core:describe` point of @dokebi/core 0.4.2, declared here by name (its identity) so this
|
|
9
|
+
* package keeps working with older cores, which never describe.
|
|
10
|
+
*/
|
|
11
|
+
export const describePoint = definePoint('core:describe');
|
|
12
|
+
const MAX_FILES = 2000;
|
|
13
|
+
const MAX_DEPTH = 8;
|
|
14
|
+
const INERTIA_FILE = /\.(vue|jsx|tsx|svelte|js|ts)$/;
|
|
15
|
+
/** Files under `folder`, relative to it with `/`, sorted; bounded. */
|
|
16
|
+
async function files(folder) {
|
|
17
|
+
const found = [];
|
|
18
|
+
const walk = async (directory, depth) => {
|
|
19
|
+
if (depth > MAX_DEPTH || found.length >= MAX_FILES)
|
|
20
|
+
return;
|
|
21
|
+
const entries = await readdir(directory, { withFileTypes: true });
|
|
22
|
+
entries.sort((a, b) => a.name.localeCompare(b.name));
|
|
23
|
+
for (const entry of entries) {
|
|
24
|
+
if (found.length >= MAX_FILES)
|
|
25
|
+
return;
|
|
26
|
+
if (entry.name.startsWith('.') || entry.name === 'node_modules')
|
|
27
|
+
continue;
|
|
28
|
+
const path = join(directory, entry.name);
|
|
29
|
+
if (entry.isDirectory())
|
|
30
|
+
await walk(path, depth + 1);
|
|
31
|
+
else if (entry.isFile())
|
|
32
|
+
found.push(relative(folder, path).split(sep).join('/'));
|
|
33
|
+
}
|
|
34
|
+
};
|
|
35
|
+
await walk(folder, 0);
|
|
36
|
+
return found;
|
|
37
|
+
}
|
|
38
|
+
const display = (path) => {
|
|
39
|
+
const shown = relative(process.cwd(), path).split(sep).join('/');
|
|
40
|
+
return shown.startsWith('..') ? path.split(sep).join('/') : shown;
|
|
41
|
+
};
|
|
42
|
+
/** The app's templates and pages, read from its views folder. */
|
|
43
|
+
export async function appPages(name, views, inertia) {
|
|
44
|
+
if (!views)
|
|
45
|
+
return { templates: [], pages: [], folder: null };
|
|
46
|
+
const folder = fileURLToPath(views).replace(/[\\/]+$/, '');
|
|
47
|
+
const list = await files(folder);
|
|
48
|
+
const templates = new Set();
|
|
49
|
+
const pages = [];
|
|
50
|
+
for (const file of list) {
|
|
51
|
+
const slash = file.indexOf('/');
|
|
52
|
+
if (slash < 1)
|
|
53
|
+
continue;
|
|
54
|
+
const template = file.slice(0, slash);
|
|
55
|
+
const rest = file.slice(slash + 1);
|
|
56
|
+
templates.add(template);
|
|
57
|
+
if (inertia) {
|
|
58
|
+
if (!rest.startsWith('Pages/') || !INERTIA_FILE.test(rest))
|
|
59
|
+
continue;
|
|
60
|
+
pages.push({
|
|
61
|
+
app: name,
|
|
62
|
+
engine: 'inertia',
|
|
63
|
+
template,
|
|
64
|
+
name: rest.slice('Pages/'.length).replace(INERTIA_FILE, ''),
|
|
65
|
+
file: display(join(folder, file)),
|
|
66
|
+
});
|
|
67
|
+
}
|
|
68
|
+
else if (rest.endsWith('.ejs'))
|
|
69
|
+
pages.push({
|
|
70
|
+
app: name,
|
|
71
|
+
engine: 'ejs',
|
|
72
|
+
template,
|
|
73
|
+
name: rest.slice(0, -'.ejs'.length),
|
|
74
|
+
file: display(join(folder, file)),
|
|
75
|
+
});
|
|
76
|
+
}
|
|
77
|
+
const ordered = [...templates].sort((a, b) => a === 'default' ? -1 : b === 'default' ? 1 : a.localeCompare(b));
|
|
78
|
+
return { templates: ordered, pages, folder: display(folder) };
|
|
79
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -35,11 +35,42 @@ export interface AppView {
|
|
|
35
35
|
has(name: string): boolean;
|
|
36
36
|
}
|
|
37
37
|
/** The Inertia renderer of an app, from the `inertia` view engine (@dokebi/template-inertia). */
|
|
38
|
+
/**
|
|
39
|
+
* The render options of an app's Inertia page (@dokebi/template-inertia `InertiaRenderOptions`;
|
|
40
|
+
* `public` and `head` need template-inertia 0.4.6, D-0195).
|
|
41
|
+
*/
|
|
42
|
+
export interface AppInertiaRenderOptions {
|
|
43
|
+
readonly encryptHistory?: boolean;
|
|
44
|
+
readonly clearHistory?: boolean;
|
|
45
|
+
/**
|
|
46
|
+
* A public page: its first HTML is the same for every visitor (no auth, csrf or flash in it;
|
|
47
|
+
* they come right after it through a visit), server rendered on a seal host too when the app
|
|
48
|
+
* has `ssr`. `cacheControl` replaces `no-store` for that HTML.
|
|
49
|
+
*/
|
|
50
|
+
readonly public?: boolean | {
|
|
51
|
+
readonly cacheControl?: string;
|
|
52
|
+
};
|
|
53
|
+
/** Head tags of the first HTML: title, description, canonical, robots, alternates, meta. */
|
|
54
|
+
readonly head?: {
|
|
55
|
+
readonly title?: string;
|
|
56
|
+
readonly description?: string;
|
|
57
|
+
readonly canonical?: string;
|
|
58
|
+
readonly robots?: string;
|
|
59
|
+
readonly alternates?: readonly {
|
|
60
|
+
readonly hreflang: string;
|
|
61
|
+
readonly href: string;
|
|
62
|
+
}[];
|
|
63
|
+
readonly meta?: readonly ({
|
|
64
|
+
readonly name: string;
|
|
65
|
+
readonly content: string;
|
|
66
|
+
} | {
|
|
67
|
+
readonly property: string;
|
|
68
|
+
readonly content: string;
|
|
69
|
+
})[];
|
|
70
|
+
};
|
|
71
|
+
}
|
|
38
72
|
export interface AppInertia {
|
|
39
|
-
render(request: FastifyRequest, reply: FastifyReply, component: string, props?: Readonly<Record<string, unknown>>, options?:
|
|
40
|
-
readonly encryptHistory?: boolean;
|
|
41
|
-
readonly clearHistory?: boolean;
|
|
42
|
-
}): Promise<FastifyReply>;
|
|
73
|
+
render(request: FastifyRequest, reply: FastifyReply, component: string, props?: Readonly<Record<string, unknown>>, options?: AppInertiaRenderOptions): Promise<FastifyReply>;
|
|
43
74
|
redirect(request: FastifyRequest, reply: FastifyReply, url: string): FastifyReply;
|
|
44
75
|
location(request: FastifyRequest, reply: FastifyReply, url: string): FastifyReply;
|
|
45
76
|
/**
|
|
@@ -67,6 +98,11 @@ export interface AppInertiaOptions {
|
|
|
67
98
|
readonly bundle: string;
|
|
68
99
|
readonly failure?: 'fallback' | 'error';
|
|
69
100
|
readonly entry?: string;
|
|
101
|
+
/**
|
|
102
|
+
* How long one render(page) may take, in ms (1 to 600000, default 5000); past it the
|
|
103
|
+
* render fails with SSR_TIMEOUT and `failure` decides (template-inertia, D-0107 §4).
|
|
104
|
+
*/
|
|
105
|
+
readonly timeoutMs?: number;
|
|
70
106
|
} | false;
|
|
71
107
|
readonly encryptHistory?: boolean | 'sealed';
|
|
72
108
|
/**
|
|
@@ -75,6 +111,24 @@ export interface AppInertiaOptions {
|
|
|
75
111
|
* `errorPage`; `false`: none (JSON for visits, the error views or a small page for page loads).
|
|
76
112
|
*/
|
|
77
113
|
readonly errorPage?: string | false;
|
|
114
|
+
/**
|
|
115
|
+
* The text in the root of this app's first HTML while it loads (template-inertia
|
|
116
|
+
* `bootFallback`): `{ enabled?, timeoutMs?, messages?, stylesheet? }`, or `false` for an empty
|
|
117
|
+
* root. Unset: the plugin's.
|
|
118
|
+
*/
|
|
119
|
+
readonly bootFallback?: {
|
|
120
|
+
readonly enabled?: boolean;
|
|
121
|
+
/** A local stylesheet with the app's own look of the box (`/assets/boot.css`). */
|
|
122
|
+
readonly stylesheet?: string;
|
|
123
|
+
/** A local image above the spinner (`/assets/logo.svg`). */
|
|
124
|
+
readonly logo?: string;
|
|
125
|
+
readonly timeoutMs?: number;
|
|
126
|
+
readonly messages?: Readonly<Record<string, {
|
|
127
|
+
readonly loading?: string;
|
|
128
|
+
readonly failed?: string;
|
|
129
|
+
readonly reload?: string;
|
|
130
|
+
}>>;
|
|
131
|
+
} | false;
|
|
78
132
|
}
|
|
79
133
|
/** What an app route handler receives besides the Fastify request and reply. */
|
|
80
134
|
export interface AppPage {
|
|
@@ -91,7 +145,7 @@ export interface AppPage {
|
|
|
91
145
|
* The request host has `seal: true` (D-0059 §4, D-0062): its sockets seal every frame and its
|
|
92
146
|
* HTTP JSON bodies, Inertia pages and SSE data are sealed, so the page should load
|
|
93
147
|
* `/dokebi/seal/*` and use the seal bridge. Also in EJS data and the Inertia shared props as
|
|
94
|
-
* `sealed`. EJS HTML itself stays plain.
|
|
148
|
+
* `sealed`. EJS HTML itself stays plain; its forms are sealed by the module in `data.seal.head`.
|
|
95
149
|
*/
|
|
96
150
|
readonly sealed: boolean;
|
|
97
151
|
}
|
|
@@ -118,6 +172,14 @@ export interface AppRouter {
|
|
|
118
172
|
*/
|
|
119
173
|
export interface AppRealtimeRoute {
|
|
120
174
|
readonly path: string;
|
|
175
|
+
/**
|
|
176
|
+
* `{ id }` (D-0140): the route id, as `config.id` of an app route. The transport hands it to
|
|
177
|
+
* dokebi-web, so describe lists it, route hooks see it and an id used twice in the app (by any
|
|
178
|
+
* route, socket or event stream of it or its modules) fails the start (DUPLICATE_ROUTE_ID).
|
|
179
|
+
*/
|
|
180
|
+
readonly config?: {
|
|
181
|
+
readonly id?: string;
|
|
182
|
+
};
|
|
121
183
|
readonly constraints?: Readonly<Record<string, unknown>>;
|
|
122
184
|
authenticate(request: FastifyRequest): Awaitable<{
|
|
123
185
|
readonly tenant: string;
|
|
@@ -191,8 +253,15 @@ export interface RealtimeHandle {
|
|
|
191
253
|
kick(target: RealtimeTarget, code?: number, reason?: string): Promise<RealtimeKickReceipt>;
|
|
192
254
|
/** Joins and leaves of this namespace's tenants until the returned function is called. */
|
|
193
255
|
onPresence(listener: (change: RealtimePresence) => unknown): () => void;
|
|
194
|
-
/**
|
|
195
|
-
|
|
256
|
+
/**
|
|
257
|
+
* Publishes one SSE event to this namespace's streams (@dokebi/sse; every process on its bus).
|
|
258
|
+
* `options.id` is the event id the client sends back as `Last-Event-ID` (your own durable
|
|
259
|
+
* order, such as a message sequence, so any server can resume from it); left out, the plugin
|
|
260
|
+
* numbers the event in this process.
|
|
261
|
+
*/
|
|
262
|
+
publish(target: RealtimeTarget, event: string, data?: unknown, options?: {
|
|
263
|
+
readonly id?: string;
|
|
264
|
+
}): Promise<RealtimePublishResult>;
|
|
196
265
|
}
|
|
197
266
|
/** The view of the Application an app gets: only the plugins it lists in `requires`. */
|
|
198
267
|
export interface AppContext {
|
|
@@ -275,9 +344,23 @@ export interface AppOptions {
|
|
|
275
344
|
export interface AppEntry {
|
|
276
345
|
readonly apps: Readonly<Record<string, AppDefinition>>;
|
|
277
346
|
}
|
|
347
|
+
/** `data.seal` of an EJS page (D-0092 §1.5): what a layout writes in its `<head>`. */
|
|
348
|
+
export interface AppSealViewData {
|
|
349
|
+
/**
|
|
350
|
+
* HTML for the `<head>` of a page on a seal host: an import map naming `@dokebi/seal/http`
|
|
351
|
+
* and `@dokebi/seal/forms` (the files the seal plugin serves) and the forms module, which sends
|
|
352
|
+
* the page's POST forms sealed. An empty string on a plain host. Write it unescaped, before any
|
|
353
|
+
* other module script: `<%- data.seal.head %>`.
|
|
354
|
+
*/
|
|
355
|
+
readonly head: string;
|
|
356
|
+
}
|
|
278
357
|
/** A host without its port, lower case; IPv6 literals keep their brackets. */
|
|
279
358
|
export declare function withoutPort(host: string): string;
|
|
280
|
-
/**
|
|
359
|
+
/**
|
|
360
|
+
* The Host header without port, or an HTTP/2 request's `:authority`, which stands for it, usually
|
|
361
|
+
* comes without a Host and wins when both are there (RFC 9113 §8.3.1; dokebi-web `requestHost`
|
|
362
|
+
* reads them in this order). Apps use `requestHost`, which honours trustProxy.
|
|
363
|
+
*/
|
|
281
364
|
export declare function hostOf(request: {
|
|
282
365
|
headers: Record<string, string | string[] | undefined>;
|
|
283
366
|
}): string;
|
|
@@ -285,12 +368,26 @@ export interface AppGroupApi {
|
|
|
285
368
|
readonly names: readonly string[];
|
|
286
369
|
/** The app, template and domain for a request; undefined for an unknown host. */
|
|
287
370
|
resolve(request: FastifyRequest): AppInfo | undefined;
|
|
371
|
+
/**
|
|
372
|
+
* `data.seal` of an EJS page for the request's host, for a page rendered outside an app route
|
|
373
|
+
* (the consent page of @dokebi/oauth, R6 Claude T3): its forms are then sealed like the app's.
|
|
374
|
+
*/
|
|
375
|
+
seal(request: FastifyRequest): AppSealViewData;
|
|
288
376
|
}
|
|
289
377
|
export declare const createPlugin: import("@dokebi/core").PluginFactory<AppGroupApi>;
|
|
290
378
|
/**
|
|
291
|
-
* The semver AND of two ranges, `||` included: every pair of alternatives
|
|
292
|
-
* unsatisfiable pairs left out. Joining whole ranges with a space is wrong
|
|
293
|
-
* (`^1 || ^2` and `^2` would read as `^1 || (^2 ^2)` and accept 1.x; ISSUE-0006 recheck).
|
|
379
|
+
* The semver AND of two ranges, `||` included: every pair of alternatives (comparator sets)
|
|
380
|
+
* joined with a space, unsatisfiable pairs left out. Joining whole ranges with a space is wrong
|
|
381
|
+
* for `||` (`^1 || ^2` and `^2` would read as `^1 || (^2 ^2)` and accept 1.x; ISSUE-0006 recheck).
|
|
294
382
|
* An empty string: no version satisfies both.
|
|
383
|
+
*
|
|
384
|
+
* Joining two sets must also keep each side's prerelease rule (ISSUE-0006 recheck R03): semver
|
|
385
|
+
* admits a prerelease only when a comparator of its set carries a prerelease of the same
|
|
386
|
+
* major.minor.patch, so a joined set would let one side's `>=1.1.0-beta.1` admit `1.1.0-beta.2`
|
|
387
|
+
* for a side (`>=1.0.0 <2.0.0`) that refuses it. A prerelease comparator whose major.minor.patch
|
|
388
|
+
* is not carried by both sides is therefore written as its release form (`>=X-p` and `>X-p` as
|
|
389
|
+
* `>=X`, `<X-p` and `<=X-p` as `<X`, `=X-p` as no version): the same answer for every version
|
|
390
|
+
* outside X, and no prerelease of X is admitted any more. The result is satisfied by exactly the
|
|
391
|
+
* versions that satisfy both `a` and `b` (default semver options, as core checks).
|
|
295
392
|
*/
|
|
296
393
|
export declare function andRanges(a: string, b: string): string;
|