@dokebi/app 0.2.0 → 0.4.0
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 +137 -100
- package/README.md +74 -73
- package/dist/errors.d.ts +7 -0
- package/dist/errors.js +21 -0
- package/dist/index.d.ts +128 -26
- package/dist/index.js +316 -229
- package/dist/options.d.ts +16 -0
- package/dist/options.js +55 -0
- package/options.schema.json +26 -16
- package/package.json +51 -45
- package/templates/app/views/default/errors/404.ejs +7 -0
- package/templates/app/views/default/errors/error.ejs +14 -0
- package/templates/app-inertia/app.ts +3 -0
- package/templates/app-inertia/views/default/Pages/Error.vue +12 -0
- package/templates/app-inertia-ssr/app.ts +3 -0
package/README.md
CHANGED
|
@@ -1,136 +1,137 @@
|
|
|
1
|
-
# @dokebi/app 0.
|
|
1
|
+
# @dokebi/app 0.4.0
|
|
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
|
|
|
5
|
-
##
|
|
5
|
+
## Install
|
|
6
6
|
|
|
7
7
|
```sh
|
|
8
8
|
dokebi add @dokebi/app
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
|
|
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:
|
|
12
12
|
|
|
13
13
|
```sh
|
|
14
14
|
dokebi app add shop --domain a.com --domain www.a.com
|
|
15
|
-
dokebi app link shop b.com --template christmas #
|
|
15
|
+
dokebi app link shop b.com --template christmas # add a domain to an existing app
|
|
16
16
|
dokebi app unlink b.com
|
|
17
17
|
dokebi app list
|
|
18
|
-
dokebi app remove shop #
|
|
18
|
+
dokebi app remove shop # remove the domains pointing at the app first; the folder stays
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
Domain links are recorded in both dokebi.yaml and dokebi.example.yaml. When an app uses Inertia pages, WebSocket or SSE, run `dokebi add @dokebi/template-inertia`, `dokebi add @dokebi/websocket` or `dokebi add @dokebi/sse` separately.
|
|
22
22
|
|
|
23
|
-
##
|
|
23
|
+
## Folder layout
|
|
24
24
|
|
|
25
|
-
[D-0031](
|
|
25
|
+
It follows [D-0031](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0031-project-layout.md). `dokebi app add` creates the app folder.
|
|
26
26
|
|
|
27
27
|
```
|
|
28
|
-
src/apps
|
|
28
|
+
src/apps/<app>/
|
|
29
29
|
app.ts export default defineApp({ ... })
|
|
30
|
-
routes.ts
|
|
31
|
-
controllers/ defineController
|
|
32
|
-
models/
|
|
33
|
-
views/default/
|
|
34
|
-
views
|
|
35
|
-
views/app.js (Inertia
|
|
36
|
-
sockets/
|
|
37
|
-
src/shared/
|
|
30
|
+
routes.ts routes
|
|
31
|
+
controllers/ defineController tokens (this app only)
|
|
32
|
+
models/ plain code (not plugins)
|
|
33
|
+
views/default/ the default template (required). EJS apps: home.ejs; Inertia apps: Layout.vue, Pages/Home.vue
|
|
34
|
+
views/<template>/ only the files that change; missing files are looked up in default, then shared src/shared/views
|
|
35
|
+
views/app.js (Inertia apps only) Vite entry: finds per-template pages and layouts in the same order
|
|
36
|
+
sockets/ this app's WebSocket routes (defineSocket), created when needed
|
|
37
|
+
src/shared/ controllers, models, modules (dokebi-module) and views shared by several apps
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
- `dokebi app add
|
|
41
|
-
- `--ssr
|
|
42
|
-
-
|
|
40
|
+
- `dokebi app add <app> --inertia` creates an Inertia skeleton and prepares the build (`vite.config.ts`, the `build` script, Vite and Vue dev dependencies, `dist/` in `.gitignore`). Run `npm run build` afterwards.
|
|
41
|
+
- With `--ssr` ([D-0039](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0039-inertia-ssr.md)) it also creates the server entry `views/ssr.js`, `inertia.ssr: { bundle: 'dist/ssr/<app>/ssr.js' }` in app.ts and the project's `vite.ssr.config.ts`, and `build` runs both the browser and the server build (a previously generated script with only `vite build` becomes both; a script you wrote yourself is kept and reported as `BUILD_SCRIPT_KEPT`). The browser entry `views/app.js` hydrates the server-rendered page with `createSSRApp`. Layouts are chosen with the `layout` option instead of changing the page module (requests with different templates render on the server at the same time).
|
|
42
|
+
- @dokebi/template-inertia serves the build files under `/build/`. Details are in the [CLI docs](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/cli/README.md).
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
The app name is the folder name. The generated registration code (src/dokebi.generated.ts) imports `./apps/<app>/app.ts` for every app listed in `.dokebi/state.json` and passes them to this plugin as entry `{ apps: { <app>: ... } }`.
|
|
45
45
|
|
|
46
|
-
##
|
|
46
|
+
## Configuration
|
|
47
47
|
|
|
48
48
|
```yaml
|
|
49
49
|
dokebi-app:
|
|
50
50
|
domains:
|
|
51
|
-
a.com: { app: shop } # template
|
|
51
|
+
a.com: { app: shop } # no template = default
|
|
52
52
|
b.com: { app: shop, template: christmas }
|
|
53
53
|
c.com: { app: admin }
|
|
54
|
-
s.com: { app: shop, seal: true } #
|
|
55
|
-
unknownDomain: reject #
|
|
56
|
-
apps: #
|
|
57
|
-
shop: { realtime: { namespaces: [front] } } #
|
|
58
|
-
admin: { realtime: { namespaces: [admin, front] } } #
|
|
54
|
+
s.com: { app: shop, seal: true } # seal every WebSocket frame of this host (below)
|
|
55
|
+
unknownDomain: reject # default; or a key of domains (answered with those settings)
|
|
56
|
+
apps: # optional; keys are defined app names (otherwise the start fails with UNKNOWN_APP)
|
|
57
|
+
shop: { realtime: { namespaces: [front] } } # default [<app>]
|
|
58
|
+
admin: { realtime: { namespaces: [admin, front] } } # see "Realtime namespaces" below
|
|
59
59
|
```
|
|
60
60
|
|
|
61
|
-
dokebi-web `requestHost()
|
|
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/`.
|
|
62
62
|
|
|
63
63
|
## defineApp
|
|
64
64
|
|
|
65
|
-
```ts
|
|
65
|
+
```ts snippet
|
|
66
66
|
import { defineApp } from '@dokebi/app';
|
|
67
67
|
import { dependency as db } from '@dokebi/db';
|
|
68
68
|
|
|
69
69
|
export default defineApp({
|
|
70
|
-
requires: [db], //
|
|
70
|
+
requires: [db], // plugins and shared modules this app uses
|
|
71
71
|
controllers: [productController],
|
|
72
72
|
views: new URL('./views/', import.meta.url),
|
|
73
73
|
inertia: { vite: { manifest: 'dist/.vite/manifest.json', entry: 'src/apps/shop/views/app.js', base: '/build/' } },
|
|
74
|
-
modules: { '/board': board }, //
|
|
75
|
-
shared: (request, page) => ({ menu: MENU }), //
|
|
74
|
+
modules: { '/board': board }, // mounts a feature module under a prefix (D-0032)
|
|
75
|
+
shared: (request, page) => ({ menu: MENU }), // data merged into every EJS page of this app
|
|
76
76
|
routes(route, app) {
|
|
77
77
|
route.get('/', (request, reply, page) =>
|
|
78
78
|
page.view.reply(reply, 'home', app.controller(productController).list(), { layout: 'layouts/main' }),
|
|
79
79
|
);
|
|
80
80
|
},
|
|
81
|
-
sockets: (app) => [chatSocket(app)], // defineSocket(...)
|
|
82
|
-
events: (app) => [ordersStream(app)], // @dokebi/sse
|
|
81
|
+
sockets: (app) => [chatSocket(app)], // results of defineSocket(...)
|
|
82
|
+
events: (app) => [ordersStream(app)], // @dokebi/sse routes (SseRoute)
|
|
83
83
|
setup(app) {}, start(app) {}, drain(app) {},
|
|
84
84
|
});
|
|
85
85
|
```
|
|
86
86
|
|
|
87
|
-
-
|
|
88
|
-
-
|
|
89
|
-
|
|
90
|
-
-
|
|
91
|
-
-
|
|
92
|
-
-
|
|
93
|
-
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
-
|
|
102
|
-
-
|
|
103
|
-
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
-
|
|
111
|
-
|
|
112
|
-
|
|
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
|
+
- **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
|
+
- **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`.
|
|
90
|
+
- The module's `routes` are registered with this app's route constraint and the prefix; handlers get `page.module` and `page.base`.
|
|
91
|
+
- The module's `sockets` are registered under the prefix. Their tenant is `<namespace>:<tenant>`, as for app sockets.
|
|
92
|
+
- Several apps can mount the same module under different prefixes. A mounted module's API is readable with `app.get(module)` without listing it in `requires`.
|
|
93
|
+
- The prefix is `/` or `/a/b` (lower-case letters, digits, `.`, `_`, `~`, `-`).
|
|
94
|
+
- Module pages look for views in this order, so module pages render inside the app layout:
|
|
95
|
+
1. `<app>/<template>/<module>`
|
|
96
|
+
2. `<app>/default/<module>`
|
|
97
|
+
3. the module's `<template>`
|
|
98
|
+
4. the module's `default`
|
|
99
|
+
5. the app's views
|
|
100
|
+
6. shared views
|
|
101
|
+
- **`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.
|
|
102
|
+
- `get` and `getDependency` of the app context (`app`) allow only the plugins listed in `requires`. Controller factories have the same limit.
|
|
103
|
+
- 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.
|
|
104
|
+
- 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.
|
|
105
|
+
|
|
106
|
+
## Realtime namespaces (0.2.0, [D-0061](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0061-realtime-namespaces.md))
|
|
107
|
+
|
|
108
|
+
Presence lists, broadcasts and SSE publishing are divided by **namespace**, not by app. `apps.<app>.realtime.namespaces` (1 to 32, default `[<app>]`) are the spaces the app may use. Apps with the same namespace share presence, broadcasts and chat (this is not the `namespace` of the hub settings).
|
|
109
|
+
|
|
110
|
+
- **One connection = one namespace.** When a socket's or SSE route's `authenticate` returns `namespace`, the connection joins that space (it must be in the app's list), otherwise the first in the list. Outside the list: 401 and warn `NAMESPACE_FORBIDDEN`. `namespace` does not stay in the session identity.
|
|
111
|
+
- **Server code:** `app.realtime(namespace?)` gives the handle of that space (`NAMESPACE_FORBIDDEN` outside the list). A target's tenant is the authenticated tenant without the prefix; leaving it out means every tenant of the space.
|
|
112
|
+
|
|
113
|
+
```ts snippet
|
|
113
114
|
const front = app.realtime('front');
|
|
114
|
-
await front.list(); //
|
|
115
|
+
await front.list(); // connections on every server (tenant, member, rooms…)
|
|
115
116
|
await front.list({ tenant: 'shop-1', room: 'vip' });
|
|
116
|
-
await front.send({ tenant: 'shop-1', member: 'u42' }, 'chat.message', { text: '
|
|
117
|
-
await front.send({}, 'notice', { text: '
|
|
117
|
+
await front.send({ tenant: 'shop-1', member: 'u42' }, 'chat.message', { text: 'Hello' });
|
|
118
|
+
await front.send({}, 'notice', { text: 'Maintenance' }); // the whole space
|
|
118
119
|
await front.kick({ tenant: 'shop-1', member: 'u42' });
|
|
119
120
|
const stop = front.onPresence(({ tenant, joined, left }) => {});
|
|
120
121
|
await front.publish({ tenant: 'shop-1' }, 'order.changed', { id: 7 }); // @dokebi/sse
|
|
121
122
|
```
|
|
122
123
|
|
|
123
|
-
- `send
|
|
124
|
-
-
|
|
124
|
+
- `send` uses the same `{ type, data }` frame as defineSocket broadcasts, at most once (D-0057), sealed per socket for sealed sockets. Without the needed plugin it throws `REALTIME_UNAVAILABLE`.
|
|
125
|
+
- The admin app example (watching two front spaces and chatting with users) is in [AI.md](AI.md) §4 "Realtime namespaces".
|
|
125
126
|
|
|
126
|
-
##
|
|
127
|
+
## Seal hosts (0.2.0, [D-0059](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0059-seal-and-websocket-client.md) §4)
|
|
127
128
|
|
|
128
|
-
`domains.<host>.seal: true`(
|
|
129
|
+
With `domains.<host>.seal: true` (default false), app sockets connected through that host seal every frame, and the host's HTTP data (REST JSON requests and responses, the Inertia first page and visits, SSE data) is sealed too (the dokebi-web seal slot, [D-0062](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0062-http-seal.md)). Route `seal: false` and dokebi-web `sealExclude` are plain exceptions; EJS HTML stays as it is. app fills a socket's `route.seal` from the request host; the actual sealing and the static files under `/dokebi/seal/*` (browser loader, socket bundle, wasm) are the **`@dokebi/seal` plugin**'s job. This public package looks that plugin up only by name (`dokebi-seal`).
|
|
129
130
|
|
|
130
|
-
-
|
|
131
|
-
-
|
|
132
|
-
-
|
|
131
|
+
- Pages get `sealed`: `page.sealed` in handlers, `sealed` in EJS data (the app's `shared` and page data win), `sealed` in Inertia shared props. A sealed page preloads the seal loader (wasm) and connects with the seal bridge. A client given the bridge offers both `dokebi.seal` and `dokebi.plain`, so on a plain host `dokebi.plain` is picked and it runs in plain text.
|
|
132
|
+
- 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.)
|
|
133
|
+
- The rules of sealed connections (4415, 4400, hello, broadcasts) follow "Sealing per host" in the @dokebi/websocket README.
|
|
133
134
|
|
|
134
135
|
## API
|
|
135
136
|
|
|
136
|
-
`createPlugin
|
|
137
|
+
`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.
|
package/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import { DokebiError, type DokebiErrorOptions } from '@dokebi/core';
|
|
2
|
+
/** Codes of the errors this plugin throws (`AppError`, `plugin: 'dokebi-app'`). */
|
|
3
|
+
export type AppErrorCode = 'INVALID_DEFINITION' | 'INVALID_ENTRY' | 'UNKNOWN_APP' | 'SEAL_PROVIDER_MISSING' | 'VIEW_ENGINE_MISSING' | 'VIEWS_MISSING' | 'REALTIME_UNAVAILABLE' | 'NAMESPACE_FORBIDDEN' | 'INVALID_TARGET' | 'NOT_REQUIRED' | 'NOT_READY';
|
|
4
|
+
/** Errors of @dokebi/app; compare `code`, not the class (another installed copy may throw). */
|
|
5
|
+
export declare class AppError extends DokebiError<AppErrorCode> {
|
|
6
|
+
constructor(code: AppErrorCode, message: string, options?: DokebiErrorOptions);
|
|
7
|
+
}
|
package/dist/errors.js
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { DokebiError } from '@dokebi/core';
|
|
2
|
+
const FIX = {
|
|
3
|
+
INVALID_DEFINITION: 'defineApp takes requires, controllers, views (a file: URL), inertia, modules ({ "/prefix": defineModule(...) }), shared, routes, sockets, events, setup, start and drain; hooks are functions.',
|
|
4
|
+
INVALID_ENTRY: 'Pass { apps: { <name>: defineApp(...) } } (src/dokebi.generated.ts does); names match ^[a-z][a-z0-9-]{0,31}$.',
|
|
5
|
+
UNKNOWN_APP: 'Every app named in options.dokebi-app.domains.<host>.app and options.dokebi-app.apps must be defined (npx dokebi app add <name>, or remove the entry from dokebi.yaml).',
|
|
6
|
+
SEAL_PROVIDER_MISSING: 'Register the dokebi-seal plugin (npx dokebi add @dokebi/seal), or remove seal: true from options.dokebi-app.domains.',
|
|
7
|
+
VIEW_ENGINE_MISSING: 'Install the view plugin the app uses: npx dokebi add @dokebi/template-ejs (views) or npx dokebi add @dokebi/template-inertia (inertia).',
|
|
8
|
+
VIEWS_MISSING: 'Create src/apps/<app>/views/<template>/ for every template a domain selects (default/ is always needed), or drop views from defineApp.',
|
|
9
|
+
REALTIME_UNAVAILABLE: 'Install the transport the app uses: npx dokebi add @dokebi/websocket (sockets, list/send/kick/onPresence) or npx dokebi add @dokebi/sse (events, publish).',
|
|
10
|
+
NAMESPACE_FORBIDDEN: 'List the namespace in options.dokebi-app.apps.<app>.realtime.namespaces, or use one that is listed.',
|
|
11
|
+
INVALID_TARGET: 'A realtime target is { tenant?, member?, room? } with strings of 1 to 256 characters.',
|
|
12
|
+
NOT_REQUIRED: 'Add the plugin to requires of defineApp (src/apps/<app>/app.ts).',
|
|
13
|
+
NOT_READY: 'Read controllers from routes, socket handlers or start, after the app was set up.',
|
|
14
|
+
};
|
|
15
|
+
/** Errors of @dokebi/app; compare `code`, not the class (another installed copy may throw). */
|
|
16
|
+
export class AppError extends DokebiError {
|
|
17
|
+
constructor(code, message, options = {}) {
|
|
18
|
+
super(code, message, { plugin: 'dokebi-app', fix: FIX[code], ...options });
|
|
19
|
+
this.name = 'AppError';
|
|
20
|
+
}
|
|
21
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,11 +1,9 @@
|
|
|
1
1
|
import { type ControllerDefinition } from '@dokebi/controller';
|
|
2
2
|
import { type Awaitable, type Plugin, type PluginContext, type PluginDependency } from '@dokebi/core';
|
|
3
|
-
import type {
|
|
4
|
-
import type { TemplateApi } from '@dokebi/template-ejs';
|
|
5
|
-
import type { InertiaApi, InertiaScopeOptions } from '@dokebi/template-inertia';
|
|
6
|
-
import type { WebRoute } from '@dokebi/web';
|
|
7
|
-
import type { WebsocketConnectionInfo, WebsocketKickReceipt, WebsocketPeer, WebsocketReceipt, WebsocketRoute } from '@dokebi/websocket';
|
|
3
|
+
import type { WebErrorResponse, WebRoute } from '@dokebi/web';
|
|
8
4
|
import type { FastifyReply, FastifyRequest } from 'fastify';
|
|
5
|
+
export { AppError, type AppErrorCode } from './errors.js';
|
|
6
|
+
export { type AppPluginOptions, options } from './options.js';
|
|
9
7
|
/** The Fastify route constraint that selects an app by request host. */
|
|
10
8
|
export declare const APP_CONSTRAINT = "dokebiApp";
|
|
11
9
|
/** Which app answered a request, with the template and the host it came in on. */
|
|
@@ -14,6 +12,70 @@ export interface AppInfo {
|
|
|
14
12
|
readonly template: string;
|
|
15
13
|
readonly domain: string;
|
|
16
14
|
}
|
|
15
|
+
/** What `view.reply` needs of a reply (a Fastify reply has it). */
|
|
16
|
+
export interface AppViewReply {
|
|
17
|
+
type(value: string): unknown;
|
|
18
|
+
send(payload: string): unknown;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* The EJS renderer of a page, from the `ejs` view engine (@dokebi/template-ejs `TemplateApi`).
|
|
22
|
+
* Names are looked up in `<app>/<template>` → `<app>/default` → shared views.
|
|
23
|
+
*/
|
|
24
|
+
export interface AppView {
|
|
25
|
+
render(name: string, data: Readonly<Record<string, unknown>>, options?: {
|
|
26
|
+
readonly layout?: string | false;
|
|
27
|
+
}): Promise<string>;
|
|
28
|
+
/** Renders, sets text/html, sends the HTML and resolves to the same reply. */
|
|
29
|
+
reply<TReply extends AppViewReply>(reply: TReply, name: string, data: Readonly<Record<string, unknown>>, options?: {
|
|
30
|
+
readonly layout?: string | false;
|
|
31
|
+
}): Promise<TReply>;
|
|
32
|
+
/** A renderer that looks names up under each prefix in order first. */
|
|
33
|
+
scope(prefixes: readonly string[]): AppView;
|
|
34
|
+
/** True when the name resolves in this renderer's lookup order (D-0074 error views). */
|
|
35
|
+
has(name: string): boolean;
|
|
36
|
+
}
|
|
37
|
+
/** The Inertia renderer of an app, from the `inertia` view engine (@dokebi/template-inertia). */
|
|
38
|
+
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>;
|
|
43
|
+
redirect(request: FastifyRequest, reply: FastifyReply, url: string): FastifyReply;
|
|
44
|
+
location(request: FastifyRequest, reply: FastifyReply, url: string): FastifyReply;
|
|
45
|
+
/**
|
|
46
|
+
* Answers an error of this app's requests (D-0074): the validation redirect of an Inertia
|
|
47
|
+
* request, or the app's error page component. dokebi-app calls it; false when it wrote nothing.
|
|
48
|
+
*/
|
|
49
|
+
answerError(response: WebErrorResponse): Promise<boolean>;
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* Document settings of an app's Inertia pages (@dokebi/template-inertia `InertiaScopeOptions`
|
|
53
|
+
* without `shared`, which dokebi-app sets).
|
|
54
|
+
*/
|
|
55
|
+
export interface AppInertiaOptions {
|
|
56
|
+
readonly title?: string;
|
|
57
|
+
readonly rootId?: string;
|
|
58
|
+
readonly version?: string;
|
|
59
|
+
readonly scripts?: readonly string[];
|
|
60
|
+
readonly styles?: readonly string[];
|
|
61
|
+
readonly vite?: {
|
|
62
|
+
readonly manifest: string;
|
|
63
|
+
readonly entry: string;
|
|
64
|
+
readonly base?: string;
|
|
65
|
+
};
|
|
66
|
+
readonly ssr?: {
|
|
67
|
+
readonly bundle: string;
|
|
68
|
+
readonly failure?: 'fallback' | 'error';
|
|
69
|
+
readonly entry?: string;
|
|
70
|
+
} | false;
|
|
71
|
+
readonly encryptHistory?: boolean | 'sealed';
|
|
72
|
+
/**
|
|
73
|
+
* The page component of this app's error answers (D-0074), for example `Error`: rendered with
|
|
74
|
+
* `{ status, error, message, hint }` for Inertia visits and page loads. Unset: the plugin's
|
|
75
|
+
* `errorPage`; `false`: none (JSON for visits, the error views or a small page for page loads).
|
|
76
|
+
*/
|
|
77
|
+
readonly errorPage?: string | false;
|
|
78
|
+
}
|
|
17
79
|
/** What an app route handler receives besides the Fastify request and reply. */
|
|
18
80
|
export interface AppPage {
|
|
19
81
|
readonly app: AppInfo;
|
|
@@ -22,9 +84,9 @@ export interface AppPage {
|
|
|
22
84
|
/** The prefix the module is mounted at (`''` for app routes and root mounts), for links. */
|
|
23
85
|
readonly base: string;
|
|
24
86
|
/** EJS renderer scoped to `<app>/<template>` → `<app>/default` → shared views. */
|
|
25
|
-
readonly view:
|
|
87
|
+
readonly view: AppView;
|
|
26
88
|
/** Inertia renderer of this app; present when the app sets `inertia`. */
|
|
27
|
-
readonly inertia:
|
|
89
|
+
readonly inertia: AppInertia | undefined;
|
|
28
90
|
/**
|
|
29
91
|
* The request host has `seal: true` (D-0059 §4, D-0062): its sockets seal every frame and its
|
|
30
92
|
* HTTP JSON bodies, Inertia pages and SSE data are sealed, so the page should load
|
|
@@ -49,6 +111,19 @@ export interface AppRouter {
|
|
|
49
111
|
patch(url: string, handler: AppHandler, options?: Partial<AppRouteOptions>): void;
|
|
50
112
|
delete(url: string, handler: AppHandler, options?: Partial<AppRouteOptions>): void;
|
|
51
113
|
}
|
|
114
|
+
/**
|
|
115
|
+
* A realtime route of an app or module (`defineSocket` of @dokebi/websocket, an `SseRoute` of
|
|
116
|
+
* @dokebi/sse): the transport that mounts it reads the rest. `authenticate` may return
|
|
117
|
+
* `namespace`, one of the app's `realtime.namespaces` (D-0061).
|
|
118
|
+
*/
|
|
119
|
+
export interface AppRealtimeRoute {
|
|
120
|
+
readonly path: string;
|
|
121
|
+
readonly constraints?: Readonly<Record<string, unknown>>;
|
|
122
|
+
authenticate(request: FastifyRequest): Awaitable<{
|
|
123
|
+
readonly tenant: string;
|
|
124
|
+
readonly namespace?: string;
|
|
125
|
+
} | undefined>;
|
|
126
|
+
}
|
|
52
127
|
/**
|
|
53
128
|
* Whom a realtime call is about (D-0061), inside one namespace: a tenant (as `authenticate`
|
|
54
129
|
* returned it, without the namespace), or every tenant of the namespace when `tenant` is left
|
|
@@ -59,19 +134,46 @@ export interface RealtimeTarget {
|
|
|
59
134
|
readonly member?: string;
|
|
60
135
|
readonly room?: string;
|
|
61
136
|
}
|
|
137
|
+
/** A connection of the hub as presence reports it (@dokebi/websocket `WebsocketPeer`). */
|
|
138
|
+
export interface RealtimePeer {
|
|
139
|
+
readonly member: string;
|
|
140
|
+
readonly connection: string;
|
|
141
|
+
readonly ownerEpoch: string;
|
|
142
|
+
readonly clientId?: string;
|
|
143
|
+
readonly metadata: Readonly<Record<string, string>>;
|
|
144
|
+
}
|
|
62
145
|
/** A WebSocket connection of a namespace; `tenant` is without the `<namespace>:` prefix. */
|
|
63
|
-
export
|
|
146
|
+
export interface RealtimeConnection extends RealtimePeer {
|
|
147
|
+
readonly tenant: string;
|
|
148
|
+
readonly rooms: readonly string[];
|
|
149
|
+
}
|
|
64
150
|
/** Joins and leaves of one tenant of a namespace; `tenant` is without the prefix. */
|
|
65
151
|
export interface RealtimePresence {
|
|
66
152
|
readonly tenant: string;
|
|
67
|
-
readonly joined: readonly
|
|
68
|
-
readonly left: readonly
|
|
153
|
+
readonly joined: readonly RealtimePeer[];
|
|
154
|
+
readonly left: readonly RealtimePeer[];
|
|
155
|
+
}
|
|
156
|
+
/** What `send` resolves with: one hub broadcast per tenant (D-0057: matched, not confirmed). */
|
|
157
|
+
export interface RealtimeReceipt {
|
|
158
|
+
readonly ids: readonly string[];
|
|
159
|
+
readonly recipients: readonly string[];
|
|
160
|
+
}
|
|
161
|
+
/** What `kick` resolves with: one hub kick per tenant. */
|
|
162
|
+
export interface RealtimeKickReceipt {
|
|
163
|
+
readonly ids: readonly string[];
|
|
164
|
+
}
|
|
165
|
+
/** What `publish` resolves with (@dokebi/sse). */
|
|
166
|
+
export interface RealtimePublishResult {
|
|
167
|
+
/** The event id every recipient sees as `lastEventId`. */
|
|
168
|
+
readonly id: string;
|
|
169
|
+
/** Streams of this process the event was written to. */
|
|
170
|
+
readonly local: number;
|
|
69
171
|
}
|
|
70
172
|
/**
|
|
71
173
|
* One realtime namespace as app server code sees it (D-0061, `app.realtime(namespace)`): the
|
|
72
174
|
* WebSocket connections and SSE streams whose hub tenant is `<namespace>:<tenant>`, on every
|
|
73
|
-
* server. Calls fail with REALTIME_UNAVAILABLE when
|
|
74
|
-
* (@dokebi/websocket
|
|
175
|
+
* server. Calls fail with REALTIME_UNAVAILABLE when no plugin offers the transport they need
|
|
176
|
+
* (@dokebi/websocket, @dokebi/sse).
|
|
75
177
|
*/
|
|
76
178
|
export interface RealtimeHandle {
|
|
77
179
|
readonly namespace: string;
|
|
@@ -84,13 +186,13 @@ export interface RealtimeHandle {
|
|
|
84
186
|
* Sends the `{ type, data }` text frame of defineSocket broadcasts through the hub: at most
|
|
85
187
|
* once (D-0057), sealed per sealed socket. Without `tenant`: one broadcast per known tenant.
|
|
86
188
|
*/
|
|
87
|
-
send(target: RealtimeTarget, type: string, data?: unknown): Promise<
|
|
189
|
+
send(target: RealtimeTarget, type: string, data?: unknown): Promise<RealtimeReceipt>;
|
|
88
190
|
/** Closes the matching connections on every server (code 4000-4999, default 4403). */
|
|
89
|
-
kick(target: RealtimeTarget, code?: number, reason?: string): Promise<
|
|
191
|
+
kick(target: RealtimeTarget, code?: number, reason?: string): Promise<RealtimeKickReceipt>;
|
|
90
192
|
/** Joins and leaves of this namespace's tenants until the returned function is called. */
|
|
91
193
|
onPresence(listener: (change: RealtimePresence) => unknown): () => void;
|
|
92
194
|
/** Publishes one SSE event to this namespace's streams (@dokebi/sse; every process on its bus). */
|
|
93
|
-
publish(target: RealtimeTarget, event: string, data?: unknown): Promise<
|
|
195
|
+
publish(target: RealtimeTarget, event: string, data?: unknown): Promise<RealtimePublishResult>;
|
|
94
196
|
}
|
|
95
197
|
/** The view of the Application an app gets: only the plugins it lists in `requires`. */
|
|
96
198
|
export interface AppContext {
|
|
@@ -114,10 +216,10 @@ export interface AppDefinition {
|
|
|
114
216
|
readonly requires?: readonly AppRequirement[];
|
|
115
217
|
/** `defineController` tokens built with this app's context. */
|
|
116
218
|
readonly controllers?: readonly ControllerDefinition<unknown>[];
|
|
117
|
-
/** Folder with one sub-folder per template (`default/` is required). */
|
|
219
|
+
/** Folder with one sub-folder per template (`default/` is required). Needs the `ejs` engine. */
|
|
118
220
|
readonly views?: URL;
|
|
119
|
-
/** Document settings of this app's Inertia pages
|
|
120
|
-
readonly inertia?:
|
|
221
|
+
/** Document settings of this app's Inertia pages. Needs the `inertia` engine. */
|
|
222
|
+
readonly inertia?: AppInertiaOptions;
|
|
121
223
|
/**
|
|
122
224
|
* Modules (D-0032) mounted under a prefix: `{ '/board': boardModule }`. Their routes and
|
|
123
225
|
* sockets answer on this app's domains only; they need not be listed in `requires`.
|
|
@@ -132,16 +234,17 @@ export interface AppDefinition {
|
|
|
132
234
|
}): Awaitable<Record<string, unknown>>;
|
|
133
235
|
routes?(route: AppRouter, app: AppContext): Awaitable<void>;
|
|
134
236
|
/**
|
|
135
|
-
* WebSocket routes (e.g. `defineSocket`) registered for this app's domains only
|
|
136
|
-
* tenant is `<namespace>:<tenant>` (D-0061):
|
|
137
|
-
* app's `realtime.namespaces` (default the
|
|
237
|
+
* WebSocket routes (e.g. `defineSocket`) registered for this app's domains only, through the
|
|
238
|
+
* `websocket` realtime transport. Their hub tenant is `<namespace>:<tenant>` (D-0061):
|
|
239
|
+
* `authenticate` may return `namespace`, one of the app's `realtime.namespaces` (default the
|
|
240
|
+
* first); another one answers 401.
|
|
138
241
|
*/
|
|
139
|
-
sockets?(app: AppContext): Awaitable<readonly
|
|
242
|
+
sockets?(app: AppContext): Awaitable<readonly AppRealtimeRoute[]>;
|
|
140
243
|
/**
|
|
141
|
-
* Server-sent event routes (@dokebi/sse) registered for this app's domains only,
|
|
142
|
-
* same namespace and tenant rule as `sockets` (D-0061).
|
|
244
|
+
* Server-sent event routes (@dokebi/sse) registered for this app's domains only, through the
|
|
245
|
+
* `sse` realtime transport, with the same namespace and tenant rule as `sockets` (D-0061).
|
|
143
246
|
*/
|
|
144
|
-
events?(app: AppContext): Awaitable<readonly
|
|
247
|
+
events?(app: AppContext): Awaitable<readonly AppRealtimeRoute[]>;
|
|
145
248
|
setup?(app: AppContext): Awaitable<void>;
|
|
146
249
|
start?(app: AppContext): Awaitable<void>;
|
|
147
250
|
drain?(app: AppContext): Awaitable<void>;
|
|
@@ -184,4 +287,3 @@ export interface AppGroupApi {
|
|
|
184
287
|
resolve(request: FastifyRequest): AppInfo | undefined;
|
|
185
288
|
}
|
|
186
289
|
export declare const createPlugin: import("@dokebi/core").PluginFactory<AppGroupApi>;
|
|
187
|
-
export {};
|