@dokebi/module 0.1.1 → 0.1.3
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 +8 -5
- package/README.md +4 -3
- package/dist/index.d.ts +22 -0
- package/dist/index.js +36 -7
- package/package.json +7 -7
package/AI.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# AI 작업 안내 — @dokebi/module 0.1.
|
|
1
|
+
# AI 작업 안내 — @dokebi/module 0.1.3
|
|
2
2
|
|
|
3
3
|
모듈은 **기능 하나의 업무 단위**다(D-0032). 컨트롤러·모델·뷰·라우트·소켓을 한 폴더에 담고, 앱이 접두사로 붙인다. 웹이 없는 업무(Job handler, 이벤트 구독, 공통 API)도 모듈로 만든다. Node >=24.0.0, core ^0.2.0. 세부는 [README](README.md)다.
|
|
4
4
|
|
|
@@ -41,7 +41,8 @@ export default defineModule({
|
|
|
41
41
|
);
|
|
42
42
|
route.post('/', async (request, reply, page) => { /* ... */ });
|
|
43
43
|
},
|
|
44
|
-
sockets: (module) => [boardSocket(module)], // defineSocket 결과. tenant는
|
|
44
|
+
sockets: (module) => [boardSocket(module)], // defineSocket 결과. tenant는 <네임스페이스>:<tenant>
|
|
45
|
+
events: (module) => [boardStream(module)], // (0.1.3) @dokebi/sse 라우트(SseRoute). 소켓과 같은 규칙
|
|
45
46
|
setup(module) { return { count: () => module.controller(postsController).count() }; }, // 다른 쪽이 받는 API
|
|
46
47
|
start(module) {}, drain(module) {},
|
|
47
48
|
});
|
|
@@ -54,7 +55,8 @@ export default defineModule({
|
|
|
54
55
|
|
|
55
56
|
## 3. 앱에 붙이기와 공통 API
|
|
56
57
|
|
|
57
|
-
- 앱: `defineApp({ modules: { '/board': board } })`.
|
|
58
|
+
- 앱: `defineApp({ modules: { '/board': board } })`. 라우트·소켓·SSE 라우트는 **그 앱의 도메인과 접두사에서만** 응답한다. 같은 모듈을 여러 앱이 다른 접두사로 붙일 수 있다.
|
|
59
|
+
- 소켓·SSE 라우트(`events`, 0.1.3)의 허브 tenant는 붙인 앱의 규칙을 따른다([D-0061](../../docs/decisions/D-0061-realtime-namespaces.md)): `<네임스페이스>:<인증 tenant>`이고, `authenticate`가 `namespace`를 돌려주면 붙인 앱의 `realtime.namespaces` 안이어야 한다(아니면 401). 모듈 문맥에는 `realtime` 핸들이 없다. 발행은 @dokebi/sse `publish({ tenantPrefix: '<네임스페이스>:' }, …)`나 앱의 `app.realtime(ns).publish`로 한다. `events`는 @dokebi/app 0.2.0 이상이 붙인다(0.1.x 앱은 이 필드를 읽지 않아 스트림이 생기지 않는다).
|
|
58
60
|
- 모든 도메인에서 응답해야 하는 API(예: `/api/*`)는 `routes`가 아니라 `setup`에서 `@dokebi/router`(`mount`)나 web으로 직접 등록한다.
|
|
59
61
|
- 다른 모듈·플러그인이 이 모듈의 API를 쓰려면 `requires`에 이 모듈을 넣고 `get(모듈)` 하면 `setup`의 반환값을 받는다.
|
|
60
62
|
|
|
@@ -74,12 +76,13 @@ export default defineModule({
|
|
|
74
76
|
- `createPlugin({ app, entry: { modules } })`: 여러 모듈을 의존성 그래프로 묶는다. API는 `{ names }`. `defineModule`이 만든 것만 받고 중복은 `INVALID_PLUGIN_INPUT`.
|
|
75
77
|
- 훅: setup(라우트 등록·API 반환) → start → drain(새 유입 차단, 진행 업무 대기) → defer 정리. drain은 의존 역순(이 모듈에 의존하는 모듈이 먼저), 무관한 모듈은 동시에.
|
|
76
78
|
- 모듈 인스턴스는 Application 하나에만 쓴다. 실행 중 자동 검색·동적 import·hot reload는 없다.
|
|
79
|
+
- debug 로그(D-0047): `Modules registered`(묶음)·`Module set up`(requires·컨트롤러 수·views 접두사·routes·sockets·events 유무·ms)·`Module start finished`·`Module drain finished`. `views/default/`가 없거나 읽을 수 없으면 시작 실패이고 원래 파일 오류는 `cause`에 남는다.
|
|
77
80
|
|
|
78
81
|
## 6. 주의 사항
|
|
79
82
|
|
|
80
83
|
- 모듈은 앱에 의존하지 않는다(앱 이름으로 분기하지 않는다). 앱별 차이는 `page.app`과 앱의 화면 덮어쓰기로 처리한다.
|
|
81
84
|
- `moduleMount`·`MODULE_MOUNT`는 @dokebi/app이 쓰는 내부 연결이다. 앱 코드에서 쓰지 않는다.
|
|
82
|
-
-
|
|
85
|
+
- 소켓·SSE 라우트 타입은 모양으로만 정해져 있어 쓰지 않는 프로젝트는 @dokebi/websocket·@dokebi/sse가 필요 없다. 쓰면 그 패키지를 add한다(없으면 앱 시작 실패: `has sockets; add @dokebi/websocket`, `has event streams; add @dokebi/sse`).
|
|
83
86
|
- 응답 종료·연결 끊김을 업무 완료로 보지 않는다. 요청 밖으로 떼어 낸 작업은 모듈 `drain`에서 기다린다.
|
|
84
87
|
|
|
85
|
-
근거: `examples/26-scaffold`(생성·붙이기·덮어쓰기 반복), `examples/25-playground`(기능 모듈
|
|
88
|
+
근거: `examples/26-scaffold`(생성·붙이기·덮어쓰기 반복), `examples/25-playground`(기능 모듈 여덟 개, sse 모듈이 `events`로 앱마다 `/api/sse/events`를 붙임), `examples/22-web/main.ts`(코드 조합), D-0022·D-0032.
|
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# @dokebi/module 0.1.
|
|
1
|
+
# @dokebi/module 0.1.2
|
|
2
2
|
|
|
3
3
|
Node >=24.0.0, core ^0.2.0의 선택 패키지다(npm 공개). 모듈은 **기능 하나의 MVC 업무 단위**다([D-0022](../../docs/decisions/D-0022-plugin-boundaries-and-db.md), [D-0032](../../docs/decisions/D-0032-feature-modules.md)). 컨트롤러·모델·뷰·라우트·소켓을 한 폴더에 담고, 앱이 접두사로 붙인다. HTTP 전용 묶음이 아니어서 웹 없는 업무(Job 처리, 이벤트 구독)도 모듈로 만든다.
|
|
4
4
|
|
|
@@ -28,7 +28,8 @@ export default defineModule({
|
|
|
28
28
|
route.get('/', (request, reply, page) =>
|
|
29
29
|
page.view.reply(reply, 'index', module.controller(postsController).list(page)));
|
|
30
30
|
},
|
|
31
|
-
sockets: (module) => [boardSocket(module)], // 앱마다 접두사 아래 등록, tenant는
|
|
31
|
+
sockets: (module) => [boardSocket(module)], // 앱마다 접두사 아래 등록, tenant는 <네임스페이스>:<tenant>
|
|
32
|
+
events: (module) => [boardStream(module)], // (0.1.3) SSE 라우트(@dokebi/sse). 소켓과 같은 규칙
|
|
32
33
|
setup(module) { return api; }, // 선택. 반환값이 이 모듈을 requires한 쪽이 받는 API
|
|
33
34
|
start(module) {}, drain(module) {},
|
|
34
35
|
});
|
|
@@ -53,7 +54,7 @@ export default defineModule({
|
|
|
53
54
|
|
|
54
55
|
그래서 앱은 모듈 화면의 파일 하나만 바꿀 수 있다. 예: `src/apps/<앱>/views/christmas/<모듈>/heading.ejs`.
|
|
55
56
|
- **Inertia 앱:** 모듈이 `page.inertia.render(request, reply, '컴포넌트', props)`로 props를 낸다. Vue 페이지는 앱이 `views/<템플릿>/Pages/`에 둔다.
|
|
56
|
-
-
|
|
57
|
+
- **소켓·SSE:** `sockets`·`events`(0.1.3)의 반환 타입은 모양(`ModuleSocketRoute`·`ModuleEventRoute`)으로만 정한다. 그래서 쓰지 않는 프로젝트는 @dokebi/websocket·@dokebi/sse가 없어도 된다. 붙인 앱이 자기 네임스페이스 규칙으로 등록한다([D-0061](../../docs/decisions/D-0061-realtime-namespaces.md)): tenant는 `<네임스페이스>:<인증 tenant>`, 인증의 `namespace`는 그 앱의 목록 안이어야 한다.
|
|
57
58
|
- **`moduleMount(plugin)`·`MODULE_MOUNT`:** 앱 플러그인이 붙이기 정보를 읽는 길이다. 앱 코드에서 쓸 일은 없다.
|
|
58
59
|
|
|
59
60
|
## 묶음 플러그인
|
package/dist/index.d.ts
CHANGED
|
@@ -49,10 +49,28 @@ export interface ModuleRouter {
|
|
|
49
49
|
* shape so projects whose modules have no sockets need not install @dokebi/websocket.
|
|
50
50
|
*/
|
|
51
51
|
export interface ModuleSocketRoute {
|
|
52
|
+
readonly path: string;
|
|
53
|
+
readonly constraints?: Readonly<Record<string, unknown>>;
|
|
54
|
+
/**
|
|
55
|
+
* `namespace` (D-0061): one of the mounting app's `realtime.namespaces` (default its first);
|
|
56
|
+
* @dokebi/app prefixes the tenant with it and answers 401 for another one.
|
|
57
|
+
*/
|
|
58
|
+
authenticate(request: FastifyRequest): Awaitable<{
|
|
59
|
+
readonly tenant: string;
|
|
60
|
+
readonly namespace?: string;
|
|
61
|
+
} | undefined>;
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* A server-sent event route of a module (0.1.3), as @dokebi/sse `SseRoute`. Typed by shape so
|
|
65
|
+
* projects whose modules have no event streams need not install @dokebi/sse. @dokebi/app mounts
|
|
66
|
+
* it like a module socket: under the prefix, on the app's domains, with the app's namespace rule.
|
|
67
|
+
*/
|
|
68
|
+
export interface ModuleEventRoute {
|
|
52
69
|
readonly path: string;
|
|
53
70
|
readonly constraints?: Readonly<Record<string, unknown>>;
|
|
54
71
|
authenticate(request: FastifyRequest): Awaitable<{
|
|
55
72
|
readonly tenant: string;
|
|
73
|
+
readonly namespace?: string;
|
|
56
74
|
} | undefined>;
|
|
57
75
|
}
|
|
58
76
|
export interface ModuleDefinition<T> {
|
|
@@ -68,6 +86,8 @@ export interface ModuleDefinition<T> {
|
|
|
68
86
|
routes?(route: ModuleRouter, module: ModuleContext): Awaitable<void>;
|
|
69
87
|
/** WebSocket routes registered by every app that mounts this module, under its prefix. */
|
|
70
88
|
sockets?(module: ModuleContext): Awaitable<readonly ModuleSocketRoute[]>;
|
|
89
|
+
/** SSE routes (@dokebi/sse) registered by every app that mounts this module, under its prefix. */
|
|
90
|
+
events?(module: ModuleContext): Awaitable<readonly ModuleEventRoute[]>;
|
|
71
91
|
/** Optional; the result is the API of this module for plugins and modules that require it. */
|
|
72
92
|
setup?(module: ModuleContext): Awaitable<T>;
|
|
73
93
|
start?(module: ModuleContext): Awaitable<void>;
|
|
@@ -83,6 +103,8 @@ export interface ModuleMount {
|
|
|
83
103
|
readonly views: string | undefined;
|
|
84
104
|
readonly routes: ModuleDefinition<unknown>['routes'];
|
|
85
105
|
readonly sockets: ModuleDefinition<unknown>['sockets'];
|
|
106
|
+
/** SSE routes (0.1.3); undefined for a module without them (and in older module packages). */
|
|
107
|
+
readonly events: ModuleDefinition<unknown>['events'];
|
|
86
108
|
/** The module context; available once the module has been set up. */
|
|
87
109
|
context(): ModuleContext;
|
|
88
110
|
}
|
package/dist/index.js
CHANGED
|
@@ -12,6 +12,7 @@ const DEFINITION_KEYS = new Set([
|
|
|
12
12
|
'views',
|
|
13
13
|
'routes',
|
|
14
14
|
'sockets',
|
|
15
|
+
'events',
|
|
15
16
|
'setup',
|
|
16
17
|
'start',
|
|
17
18
|
'drain',
|
|
@@ -73,7 +74,7 @@ export function defineModule(definition) {
|
|
|
73
74
|
(definition.controllers !== undefined && !Array.isArray(definition.controllers)) ||
|
|
74
75
|
(definition.views !== undefined &&
|
|
75
76
|
(!(definition.views instanceof URL) || definition.views.protocol !== 'file:')) ||
|
|
76
|
-
['routes', 'sockets', 'setup', 'start', 'drain'].some((hook) => definition[hook] !== undefined && typeof definition[hook] !== 'function'))
|
|
77
|
+
['routes', 'sockets', 'events', 'setup', 'start', 'drain'].some((hook) => definition[hook] !== undefined && typeof definition[hook] !== 'function'))
|
|
77
78
|
throw new TypeError('Invalid module definition');
|
|
78
79
|
const { name, views } = definition;
|
|
79
80
|
const dependencies = (definition.requires ?? []).map(requirement);
|
|
@@ -88,7 +89,14 @@ export function defineModule(definition) {
|
|
|
88
89
|
let controllers;
|
|
89
90
|
let current;
|
|
90
91
|
const prefix = `module.${name}`;
|
|
91
|
-
const hook = (key) =>
|
|
92
|
+
const hook = (key) => async (context) => {
|
|
93
|
+
const begin = performance.now();
|
|
94
|
+
await definition[key]?.(current ?? moduleContext(context, name, declared, () => controllers));
|
|
95
|
+
context.logger.log('debug', `Module ${key} finished`, {
|
|
96
|
+
module: name,
|
|
97
|
+
ms: Math.round(performance.now() - begin),
|
|
98
|
+
});
|
|
99
|
+
};
|
|
92
100
|
const plugin = {
|
|
93
101
|
metadata: Object.freeze({
|
|
94
102
|
name: 'dokebi-module.' + name,
|
|
@@ -101,17 +109,36 @@ export function defineModule(definition) {
|
|
|
101
109
|
throw new Error('Create one module instance per Application');
|
|
102
110
|
started = true;
|
|
103
111
|
current = moduleContext(context, name, declared, () => controllers);
|
|
112
|
+
const begin = performance.now();
|
|
104
113
|
if (definition.controllers?.length) {
|
|
105
114
|
const { createControllers } = await import('@dokebi/controller');
|
|
106
115
|
controllers = await createControllers(current, definition.controllers);
|
|
107
116
|
}
|
|
108
117
|
if (views) {
|
|
109
118
|
const folder = fileURLToPath(new URL('default/', views));
|
|
110
|
-
|
|
111
|
-
|
|
119
|
+
// A missing folder and an unreadable one both stop setup; the stat error is the cause.
|
|
120
|
+
let failure;
|
|
121
|
+
const info = await stat(folder).catch((cause) => {
|
|
122
|
+
failure = cause;
|
|
123
|
+
return undefined;
|
|
124
|
+
});
|
|
125
|
+
if (!info?.isDirectory())
|
|
126
|
+
throw new Error(`Module ${name} has no views/default/ folder`, failure === undefined ? undefined : { cause: failure });
|
|
112
127
|
await context.getDependency(templates ?? ejs).addDirectory(views, prefix);
|
|
113
128
|
}
|
|
114
|
-
|
|
129
|
+
const api = (await definition.setup?.(current));
|
|
130
|
+
context.logger.log('debug', 'Module set up', {
|
|
131
|
+
module: name,
|
|
132
|
+
version,
|
|
133
|
+
requires: dependencies.map((dependency) => dependency.name),
|
|
134
|
+
controllers: definition.controllers?.length ?? 0,
|
|
135
|
+
views: views ? prefix : false,
|
|
136
|
+
routes: Boolean(definition.routes),
|
|
137
|
+
sockets: Boolean(definition.sockets),
|
|
138
|
+
events: Boolean(definition.events),
|
|
139
|
+
ms: Math.round(performance.now() - begin),
|
|
140
|
+
});
|
|
141
|
+
return api;
|
|
115
142
|
},
|
|
116
143
|
...(definition.start ? { start: hook('start') } : {}),
|
|
117
144
|
...(definition.drain ? { drain: hook('drain') } : {}),
|
|
@@ -121,6 +148,7 @@ export function defineModule(definition) {
|
|
|
121
148
|
views: views ? prefix : undefined,
|
|
122
149
|
routes: definition.routes?.bind(definition),
|
|
123
150
|
sockets: definition.sockets?.bind(definition),
|
|
151
|
+
events: definition.events?.bind(definition),
|
|
124
152
|
context: () => {
|
|
125
153
|
if (!current)
|
|
126
154
|
throw new Error(`Module ${name} is not set up yet`);
|
|
@@ -183,13 +211,14 @@ class ModuleGroupRuntime {
|
|
|
183
211
|
constructor(names) {
|
|
184
212
|
this.names = names;
|
|
185
213
|
}
|
|
186
|
-
setup() {
|
|
214
|
+
setup(context) {
|
|
215
|
+
context.logger.log('debug', 'Modules registered', { modules: this.names });
|
|
187
216
|
return Object.freeze({ names: this.names });
|
|
188
217
|
}
|
|
189
218
|
}
|
|
190
219
|
export const createPlugin = definePlugin({
|
|
191
220
|
name: 'dokebi-module',
|
|
192
|
-
version: '0.1.
|
|
221
|
+
version: '0.1.3',
|
|
193
222
|
core: '^0.2.0',
|
|
194
223
|
options: parseOptions,
|
|
195
224
|
entry: parseEntry,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dokebi/module",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -32,8 +32,8 @@
|
|
|
32
32
|
"@dokebi/controller": "^0.1.0",
|
|
33
33
|
"@dokebi/core": "^0.2.0",
|
|
34
34
|
"@dokebi/template-ejs": "^0.1.0",
|
|
35
|
-
"@dokebi/template-inertia": "^0.1.0",
|
|
36
|
-
"@dokebi/web": "^0.1.0",
|
|
35
|
+
"@dokebi/template-inertia": "^0.1.0 || ^0.2.0",
|
|
36
|
+
"@dokebi/web": "^0.1.0 || ^0.2.0",
|
|
37
37
|
"fastify": "^5.12.7"
|
|
38
38
|
},
|
|
39
39
|
"dokebi": {
|
|
@@ -67,10 +67,10 @@
|
|
|
67
67
|
}
|
|
68
68
|
},
|
|
69
69
|
"devDependencies": {
|
|
70
|
-
"@dokebi/controller": "0.1.
|
|
71
|
-
"@dokebi/template-ejs": "0.1.
|
|
72
|
-
"@dokebi/template-inertia": "0.
|
|
73
|
-
"@dokebi/web": "0.
|
|
70
|
+
"@dokebi/controller": "0.1.2",
|
|
71
|
+
"@dokebi/template-ejs": "0.1.2",
|
|
72
|
+
"@dokebi/template-inertia": "0.2.0",
|
|
73
|
+
"@dokebi/web": "0.2.0"
|
|
74
74
|
},
|
|
75
75
|
"publishConfig": {
|
|
76
76
|
"access": "public",
|