@getstrata/cli 2.2.60 → 3.0.4
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/CHANGELOG.md +24 -0
- package/package.json +3 -3
- package/src/bunChildResource.ts +281 -0
- package/src/openapi.ts +59 -48
- package/src/outboxWorker.ts +55 -53
- package/src/queueFailed.ts +60 -59
- package/src/queueWorker.ts +18 -34
- package/src/scaffold/makeFactory.ts +19 -17
- package/src/scaffold/makeListener.ts +30 -8
- package/src/scaffold/makeMigration.ts +4 -3
- package/src/scaffold/makeModel.ts +19 -20
- package/src/scaffold/makeModule.ts +1 -16
- package/src/scaffold/renderModule.ts +57 -64
- package/src/schedule.ts +15 -5
- package/src/spawnBun.ts +2 -26
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,29 @@
|
|
|
1
1
|
# @getstrata/cli changelog
|
|
2
2
|
|
|
3
|
+
## 3.0.4
|
|
4
|
+
|
|
5
|
+
Restore workspace-based npm publication and remove custom archive packing/recovery. Skip confirmed existing versions, stop on registry lookup failures, and accept successful npm uploads without requiring immediate registry visibility. Retain release quality gates, pinned npm, provenance and publication dry-runs. The v3.0.3 attempt published only @getstrata/core before its visibility check failed.
|
|
6
|
+
|
|
7
|
+
## 3.0.3
|
|
8
|
+
|
|
9
|
+
Remove the separate successful-main-CI prerequisite; the release workflow still requires its own full quality gate before publication.
|
|
10
|
+
|
|
11
|
+
Fix npm publication of local release archives by resolving paths absolutely, avoiding GitHub shorthand interpretation. Exercise archive publication dry-runs in CI and before live publication. Preserve the failed v3.0.2 tag; its first publish failed before any package was published.
|
|
12
|
+
|
|
13
|
+
## 3.0.2
|
|
14
|
+
|
|
15
|
+
Reconcile completed framework ownership and retirement documentation. Clarify the exact-commit main CI prerequisite, early-tag retry procedure, and maintainer release handoff; improve the release admission diagnostic without changing its checks.
|
|
16
|
+
|
|
17
|
+
Remove unused internal renderer/build compatibility helpers and migrate their test imports. Refresh v3 application, auth, discovery, queue, tracing and lifecycle guidance; clearly label retained 2.x qualification evidence.
|
|
18
|
+
|
|
19
|
+
## 3.0.1
|
|
20
|
+
|
|
21
|
+
Fix release archive packing for npm 12 package-keyed JSON output while retaining npm 11 compatibility. Validate archive identity and integrity, pin the publication toolchain, and exercise actual release packing in CI. The v3.0.0 tag remains unchanged; its failed workflow published no npm packages.
|
|
22
|
+
|
|
23
|
+
## 3.0.0
|
|
24
|
+
|
|
25
|
+
Breaking application-owned runtime, typed authorization and persistence, immutable starter plans, isolated adapters and authenticated queue handoffs.
|
|
26
|
+
|
|
3
27
|
## 2.2.60
|
|
4
28
|
|
|
5
29
|
- Align published core/bootstrap peers with 2.2.60. Failed-job operations receive the core persistence correction; CLI commands and replay admission/deletion ordering are unchanged.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@getstrata/cli",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "3.0.4",
|
|
4
4
|
"description": "Strata CLI: framework commands for Bun apps (dev, start, migrate, run)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -54,8 +54,8 @@
|
|
|
54
54
|
],
|
|
55
55
|
"scripts": {},
|
|
56
56
|
"peerDependencies": {
|
|
57
|
-
"@getstrata/bootstrap": "^
|
|
58
|
-
"@getstrata/core": "^
|
|
57
|
+
"@getstrata/bootstrap": "^3.0.4",
|
|
58
|
+
"@getstrata/core": "^3.0.4"
|
|
59
59
|
},
|
|
60
60
|
"publishConfig": {
|
|
61
61
|
"access": "public"
|
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
import {
|
|
2
|
+
type Application,
|
|
3
|
+
type CompletionResult,
|
|
4
|
+
createApplication,
|
|
5
|
+
type ProviderScope,
|
|
6
|
+
type StopResult,
|
|
7
|
+
} from "@getstrata/core/runtime/application";
|
|
8
|
+
import type { StrataAppConfig } from "./types.ts";
|
|
9
|
+
|
|
10
|
+
type ParentSignal = "SIGINT" | "SIGTERM";
|
|
11
|
+
|
|
12
|
+
interface NativeChild {
|
|
13
|
+
readonly exited: Promise<number>;
|
|
14
|
+
readonly exitCode: number | null;
|
|
15
|
+
kill(signal: ParentSignal): void;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
interface NativeSpawnOptions {
|
|
19
|
+
readonly cwd: string;
|
|
20
|
+
readonly env: Readonly<Record<string, string | undefined>>;
|
|
21
|
+
readonly stdin: "inherit";
|
|
22
|
+
readonly stdout: "inherit";
|
|
23
|
+
readonly stderr: "inherit";
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
type NativeSpawn = (argv: readonly string[], options: NativeSpawnOptions) => NativeChild;
|
|
27
|
+
|
|
28
|
+
interface SignalHost {
|
|
29
|
+
on(signal: ParentSignal, callback: () => void): void;
|
|
30
|
+
off(signal: ParentSignal, callback: () => void): void;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** Private native boundary for deterministic adapter tests; not a public CLI option. */
|
|
34
|
+
interface NativeHost {
|
|
35
|
+
readonly spawn?: NativeSpawn;
|
|
36
|
+
readonly signals?: SignalHost;
|
|
37
|
+
readonly shutdownTimeoutMs?: number;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
interface BunChildSupervisor {
|
|
41
|
+
readonly application: Application;
|
|
42
|
+
/** Starts once; all calls share this operation's result promise. */
|
|
43
|
+
run(): Promise<number>;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
interface PrimaryFailure {
|
|
47
|
+
/** A wrapper records presence even when the original thrown value is undefined. */
|
|
48
|
+
readonly error: unknown;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
class ChildSupervisorError extends Error {
|
|
52
|
+
/** Original delivery and owned-listener teardown faults, separate from owner diagnostics. */
|
|
53
|
+
readonly relayErrors: readonly unknown[];
|
|
54
|
+
|
|
55
|
+
constructor(
|
|
56
|
+
readonly childExitCode: number | null,
|
|
57
|
+
readonly primary: PrimaryFailure | undefined,
|
|
58
|
+
relayErrors: readonly unknown[],
|
|
59
|
+
readonly stop: StopResult,
|
|
60
|
+
readonly completion: Promise<CompletionResult>,
|
|
61
|
+
) {
|
|
62
|
+
const cause = primary
|
|
63
|
+
? primary.error
|
|
64
|
+
: relayErrors.length > 0
|
|
65
|
+
? relayErrors[0]
|
|
66
|
+
: stop.snapshot.errors[0]?.error;
|
|
67
|
+
super("Child supervision failed.", { cause });
|
|
68
|
+
this.name = "ChildSupervisorError";
|
|
69
|
+
this.relayErrors = Object.freeze([...relayErrors]);
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
type Relay = { signal: ParentSignal; callback: () => void };
|
|
74
|
+
|
|
75
|
+
function bunExecutable(): string {
|
|
76
|
+
return process.execPath.includes("bun") ? process.execPath : "bun";
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** Keep the original rejection observable without changing its value or result. */
|
|
80
|
+
function observe<T>(promise: Promise<T>): Promise<T> {
|
|
81
|
+
void promise.catch(() => {});
|
|
82
|
+
return promise;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Private CLI composition: construction has no native effects. run starts ownership.
|
|
87
|
+
* Child-only first-signal startup cancellation still waits for the already owned child;
|
|
88
|
+
* clean supervision returns its actual code. Genuine startup/work failures stay distinct.
|
|
89
|
+
*/
|
|
90
|
+
function createBunChildSupervisor(
|
|
91
|
+
app: Pick<StrataAppConfig, "root">,
|
|
92
|
+
bunArgs: readonly string[],
|
|
93
|
+
host: NativeHost = {},
|
|
94
|
+
): BunChildSupervisor {
|
|
95
|
+
const argv = Object.freeze([bunExecutable(), ...bunArgs]);
|
|
96
|
+
const options: NativeSpawnOptions = Object.freeze({
|
|
97
|
+
cwd: app.root,
|
|
98
|
+
env: Object.freeze({ ...process.env }),
|
|
99
|
+
stdin: "inherit",
|
|
100
|
+
stdout: "inherit",
|
|
101
|
+
stderr: "inherit",
|
|
102
|
+
});
|
|
103
|
+
const spawn: NativeSpawn = host.spawn ?? ((args, config) => Bun.spawn([...args], config));
|
|
104
|
+
const signals: SignalHost = host.signals ?? {
|
|
105
|
+
on: (signal, callback) => {
|
|
106
|
+
process.on(signal, callback);
|
|
107
|
+
},
|
|
108
|
+
off: (signal, callback) => {
|
|
109
|
+
process.off(signal, callback);
|
|
110
|
+
},
|
|
111
|
+
};
|
|
112
|
+
const relayErrors: unknown[] = [];
|
|
113
|
+
let child: NativeChild | undefined;
|
|
114
|
+
let exited: Promise<number> | undefined;
|
|
115
|
+
let childExitCode: number | null = null;
|
|
116
|
+
let startupSignal: AbortSignal | undefined;
|
|
117
|
+
let firstSignal: ParentSignal | undefined;
|
|
118
|
+
let running: Promise<number> | undefined;
|
|
119
|
+
let startupPrimary: PrimaryFailure | undefined;
|
|
120
|
+
|
|
121
|
+
const waitForExit = (owned: NativeChild): Promise<number> => {
|
|
122
|
+
// Reserve the observation before a native getter/thenable or reentrant callback runs.
|
|
123
|
+
exited ??= observe(
|
|
124
|
+
Promise.resolve()
|
|
125
|
+
.then(() => owned.exited)
|
|
126
|
+
.then((code) => {
|
|
127
|
+
childExitCode = code;
|
|
128
|
+
return code;
|
|
129
|
+
}),
|
|
130
|
+
);
|
|
131
|
+
return exited;
|
|
132
|
+
};
|
|
133
|
+
const removeRelays = (relays: readonly Relay[]): unknown[] => {
|
|
134
|
+
const errors: unknown[] = [];
|
|
135
|
+
for (const relay of [...relays].reverse()) {
|
|
136
|
+
try {
|
|
137
|
+
signals.off(relay.signal, relay.callback);
|
|
138
|
+
} catch (error) {
|
|
139
|
+
errors.push(error);
|
|
140
|
+
relayErrors.push(error);
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
return errors;
|
|
144
|
+
};
|
|
145
|
+
const setup = async (scope: ProviderScope): Promise<void> => {
|
|
146
|
+
startupSignal = scope.signal;
|
|
147
|
+
const owned = await scope.acquire<NativeChild>({
|
|
148
|
+
name: "cli.child",
|
|
149
|
+
open: () => {
|
|
150
|
+
try {
|
|
151
|
+
child = spawn(argv, options);
|
|
152
|
+
return { ok: true, value: child };
|
|
153
|
+
} catch (error) {
|
|
154
|
+
startupPrimary = Object.freeze({ error });
|
|
155
|
+
throw error;
|
|
156
|
+
}
|
|
157
|
+
},
|
|
158
|
+
stop: async (resource, context) => {
|
|
159
|
+
// Native status can settle before its promise observer. Drain still requires exited.
|
|
160
|
+
if (childExitCode !== null || resource.exitCode !== null) return;
|
|
161
|
+
try {
|
|
162
|
+
resource.kill(context.reason === "SIGINT" ? "SIGINT" : "SIGTERM");
|
|
163
|
+
} catch (error) {
|
|
164
|
+
// Failed delivery is a transport fault. Only actual exit can acknowledge stop.
|
|
165
|
+
relayErrors.push(error);
|
|
166
|
+
await waitForExit(resource);
|
|
167
|
+
}
|
|
168
|
+
},
|
|
169
|
+
drain: async (resource) => {
|
|
170
|
+
await waitForExit(resource);
|
|
171
|
+
},
|
|
172
|
+
close: async (resource) => {
|
|
173
|
+
await waitForExit(resource);
|
|
174
|
+
},
|
|
175
|
+
});
|
|
176
|
+
waitForExit(owned);
|
|
177
|
+
await scope.acquire<readonly Relay[]>({
|
|
178
|
+
name: "cli.child.signals",
|
|
179
|
+
open: () => {
|
|
180
|
+
const relays: Relay[] = [];
|
|
181
|
+
try {
|
|
182
|
+
for (const signal of ["SIGINT", "SIGTERM"] as const) {
|
|
183
|
+
const callback = () => {
|
|
184
|
+
if (firstSignal !== undefined) return;
|
|
185
|
+
firstSignal = signal;
|
|
186
|
+
void application.stop({ reason: signal });
|
|
187
|
+
};
|
|
188
|
+
// on() may install and then throw. Its exact remover already exists.
|
|
189
|
+
relays.push({ signal, callback });
|
|
190
|
+
signals.on(signal, callback);
|
|
191
|
+
}
|
|
192
|
+
return { ok: true, value: relays };
|
|
193
|
+
} catch (error) {
|
|
194
|
+
startupPrimary = Object.freeze({ error });
|
|
195
|
+
const cleanupErrors = removeRelays(relays);
|
|
196
|
+
return {
|
|
197
|
+
ok: false,
|
|
198
|
+
error,
|
|
199
|
+
disposition: cleanupErrors.length === 0 ? "cleaned" : "unknown",
|
|
200
|
+
cleanupErrors,
|
|
201
|
+
};
|
|
202
|
+
}
|
|
203
|
+
},
|
|
204
|
+
close: (relays) => {
|
|
205
|
+
const errors = removeRelays(relays);
|
|
206
|
+
if (errors.length > 0) throw new AggregateError(errors, "Child signal cleanup failed.");
|
|
207
|
+
},
|
|
208
|
+
});
|
|
209
|
+
};
|
|
210
|
+
const application = createApplication({
|
|
211
|
+
providers: [{ name: "cli.child-supervisor", setup }],
|
|
212
|
+
shutdownTimeoutMs: host.shutdownTimeoutMs,
|
|
213
|
+
});
|
|
214
|
+
|
|
215
|
+
const execute = async (): Promise<number> => {
|
|
216
|
+
let primary: PrimaryFailure | undefined;
|
|
217
|
+
try {
|
|
218
|
+
await application.start();
|
|
219
|
+
const owned = child;
|
|
220
|
+
if (owned) {
|
|
221
|
+
// A signal can close admission just after start settles. Observe owned work;
|
|
222
|
+
// do not try to admit a new command into an already stopping application.
|
|
223
|
+
if (application.state.phase === "ready") await application.run(() => waitForExit(owned));
|
|
224
|
+
else await waitForExit(owned);
|
|
225
|
+
}
|
|
226
|
+
} catch (error) {
|
|
227
|
+
const signalOnlyCancellation =
|
|
228
|
+
firstSignal !== undefined &&
|
|
229
|
+
startupSignal?.aborted === true &&
|
|
230
|
+
application.state.boot === "cancelled" &&
|
|
231
|
+
error === startupSignal.reason;
|
|
232
|
+
if (!signalOnlyCancellation) primary = startupPrimary ?? Object.freeze({ error });
|
|
233
|
+
}
|
|
234
|
+
if (child && childExitCode === null) {
|
|
235
|
+
// Startup may have been cancelled after acquiring a child, before app.run could
|
|
236
|
+
// be admitted. Its already-journaled native lifetime still must be observed.
|
|
237
|
+
try {
|
|
238
|
+
await waitForExit(child);
|
|
239
|
+
} catch (error) {
|
|
240
|
+
primary ??= Object.freeze({ error });
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
const stop = await application.stop({ reason: "CHILD_FINISHED" });
|
|
244
|
+
if (
|
|
245
|
+
primary === undefined &&
|
|
246
|
+
relayErrors.length === 0 &&
|
|
247
|
+
stop.successful &&
|
|
248
|
+
childExitCode !== null
|
|
249
|
+
) {
|
|
250
|
+
return childExitCode;
|
|
251
|
+
}
|
|
252
|
+
if (primary !== undefined && relayErrors.length === 0 && stop.successful) throw primary.error;
|
|
253
|
+
throw new ChildSupervisorError(
|
|
254
|
+
childExitCode,
|
|
255
|
+
primary,
|
|
256
|
+
relayErrors,
|
|
257
|
+
stop,
|
|
258
|
+
application.completion,
|
|
259
|
+
);
|
|
260
|
+
};
|
|
261
|
+
|
|
262
|
+
return Object.freeze({
|
|
263
|
+
application,
|
|
264
|
+
run(): Promise<number> {
|
|
265
|
+
running ??= observe(Promise.resolve().then(execute));
|
|
266
|
+
return running;
|
|
267
|
+
},
|
|
268
|
+
});
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
export type {
|
|
272
|
+
BunChildSupervisor,
|
|
273
|
+
NativeChild,
|
|
274
|
+
NativeHost,
|
|
275
|
+
NativeSpawn,
|
|
276
|
+
NativeSpawnOptions,
|
|
277
|
+
ParentSignal,
|
|
278
|
+
PrimaryFailure,
|
|
279
|
+
SignalHost,
|
|
280
|
+
};
|
|
281
|
+
export { bunExecutable, ChildSupervisorError, createBunChildSupervisor };
|
package/src/openapi.ts
CHANGED
|
@@ -1,8 +1,16 @@
|
|
|
1
1
|
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
|
2
2
|
import { dirname, join } from "node:path";
|
|
3
|
-
import {
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
import {
|
|
4
|
+
compileRouteMap,
|
|
5
|
+
getRouteInventory,
|
|
6
|
+
type RegisteredRoute,
|
|
7
|
+
} from "@getstrata/bootstrap/routePlan";
|
|
8
|
+
import {
|
|
9
|
+
generateOpenApiSpec,
|
|
10
|
+
type OpenApiConfig,
|
|
11
|
+
renderOpenApiDocument,
|
|
12
|
+
resolveOpenApiConfig,
|
|
13
|
+
} from "@getstrata/core/openapi/generator";
|
|
6
14
|
import { validateOpenApiSpec } from "@getstrata/core/openapi/validate";
|
|
7
15
|
import { readSpaPrefix } from "@getstrata/core/runtime/frontendMode";
|
|
8
16
|
|
|
@@ -15,7 +23,7 @@ function isSpaDocumentedPath(path: string, spaPrefix: string): boolean {
|
|
|
15
23
|
return path === "/*" || path === spaPrefix || path.startsWith(`${spaPrefix}/`);
|
|
16
24
|
}
|
|
17
25
|
|
|
18
|
-
function isWebOnlyPath(metadata: RegisteredRoute[]): boolean {
|
|
26
|
+
function isWebOnlyPath(metadata: readonly RegisteredRoute[]): boolean {
|
|
19
27
|
return (
|
|
20
28
|
metadata.some((route) => route.middleware.includes("web")) &&
|
|
21
29
|
!metadata.some((route) => route.middleware.includes("api"))
|
|
@@ -24,7 +32,7 @@ function isWebOnlyPath(metadata: RegisteredRoute[]): boolean {
|
|
|
24
32
|
|
|
25
33
|
function shouldKeepOpenApiPath(
|
|
26
34
|
path: string,
|
|
27
|
-
registered: RegisteredRoute[],
|
|
35
|
+
registered: readonly RegisteredRoute[],
|
|
28
36
|
spaPrefix: string,
|
|
29
37
|
): boolean {
|
|
30
38
|
if (isSpaDocumentedPath(path, spaPrefix)) {
|
|
@@ -35,71 +43,66 @@ function shouldKeepOpenApiPath(
|
|
|
35
43
|
return !isWebOnlyPath(metadata);
|
|
36
44
|
}
|
|
37
45
|
|
|
38
|
-
async function registerAppOpenApiRoutes(
|
|
39
|
-
|
|
46
|
+
async function registerAppOpenApiRoutes(
|
|
47
|
+
bootstrap: AppBootstrap,
|
|
48
|
+
spaPrefix = "/app",
|
|
49
|
+
): Promise<readonly RegisteredRoute[]> {
|
|
40
50
|
const { routes } = await bootstrap();
|
|
41
|
-
const registered =
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
for (const path of Object.keys(routes)) {
|
|
46
|
-
if (shouldKeepOpenApiPath(path, registered, spaPrefix)) {
|
|
47
|
-
keepPaths.add(path);
|
|
48
|
-
}
|
|
49
|
-
}
|
|
50
|
-
|
|
51
|
-
const keptRegistered = registered.filter((route) => keepPaths.has(route.path));
|
|
52
|
-
const registeredKeepPaths = new Set(keptRegistered.map((route) => route.path));
|
|
53
|
-
const unregisteredKeepers: Record<string, unknown> = {};
|
|
54
|
-
|
|
55
|
-
for (const path of keepPaths) {
|
|
56
|
-
if (!registeredKeepPaths.has(path)) {
|
|
57
|
-
unregisteredKeepers[path] = routes[path];
|
|
58
|
-
}
|
|
59
|
-
}
|
|
60
|
-
|
|
61
|
-
routeRegistry.clear();
|
|
62
|
-
for (const route of keptRegistered) {
|
|
63
|
-
routeRegistry.register(route);
|
|
64
|
-
}
|
|
65
|
-
registerOpenApiRouteMap(unregisteredKeepers, ["global", "api"]);
|
|
51
|
+
const registered = getRouteInventory(compileRouteMap(routes));
|
|
52
|
+
return Object.freeze(
|
|
53
|
+
registered.filter((route) => shouldKeepOpenApiPath(route.path, registered, spaPrefix)),
|
|
54
|
+
);
|
|
66
55
|
}
|
|
67
56
|
|
|
68
57
|
function createOpenApiCommand(
|
|
69
58
|
bootstrap: AppBootstrap,
|
|
70
|
-
operation: () => Promise<number | undefined>,
|
|
71
|
-
close
|
|
59
|
+
operation: (routes: readonly RegisteredRoute[]) => Promise<number | undefined>,
|
|
60
|
+
close: AppCleanup | undefined,
|
|
61
|
+
spaPrefix: string,
|
|
72
62
|
) {
|
|
73
63
|
return async (): Promise<void> => {
|
|
74
64
|
const exitCode = await withCommandCleanup(async () => {
|
|
75
|
-
await registerAppOpenApiRoutes(bootstrap);
|
|
76
|
-
return operation();
|
|
65
|
+
const routes = await registerAppOpenApiRoutes(bootstrap, spaPrefix);
|
|
66
|
+
return operation(routes);
|
|
77
67
|
}, close);
|
|
78
68
|
if (exitCode === 1) process.exit(1);
|
|
79
69
|
};
|
|
80
70
|
}
|
|
81
71
|
|
|
82
|
-
function createOpenApiGenerateCommand(
|
|
72
|
+
function createOpenApiGenerateCommand(
|
|
73
|
+
bootstrap: AppBootstrap,
|
|
74
|
+
close?: AppCleanup,
|
|
75
|
+
config: OpenApiConfig = resolveOpenApiConfig(process.env),
|
|
76
|
+
spaPrefix = readSpaPrefix(),
|
|
77
|
+
) {
|
|
78
|
+
config = Object.freeze({ ...config });
|
|
83
79
|
return createOpenApiCommand(
|
|
84
80
|
bootstrap,
|
|
85
|
-
async () => {
|
|
86
|
-
const spec = generateOpenApiSpec(
|
|
81
|
+
async (routes) => {
|
|
82
|
+
const spec = generateOpenApiSpec(routes, config);
|
|
87
83
|
const jsonPath = join(process.cwd(), "docs/openapi.json");
|
|
88
84
|
await mkdir(dirname(jsonPath), { recursive: true });
|
|
89
85
|
await writeFile(jsonPath, renderOpenApiDocument(spec), "utf8");
|
|
90
86
|
|
|
91
|
-
console.log(`OpenAPI spec written to ${jsonPath} (${
|
|
87
|
+
console.log(`OpenAPI spec written to ${jsonPath} (${routes.length} routes).`);
|
|
92
88
|
return undefined;
|
|
93
89
|
},
|
|
94
90
|
close,
|
|
91
|
+
spaPrefix,
|
|
95
92
|
);
|
|
96
93
|
}
|
|
97
94
|
|
|
98
|
-
function createOpenApiValidateCommand(
|
|
95
|
+
function createOpenApiValidateCommand(
|
|
96
|
+
bootstrap: AppBootstrap,
|
|
97
|
+
close?: AppCleanup,
|
|
98
|
+
config: OpenApiConfig = resolveOpenApiConfig(process.env),
|
|
99
|
+
spaPrefix = readSpaPrefix(),
|
|
100
|
+
) {
|
|
101
|
+
config = Object.freeze({ ...config });
|
|
99
102
|
return createOpenApiCommand(
|
|
100
103
|
bootstrap,
|
|
101
|
-
async () => {
|
|
102
|
-
const spec = generateOpenApiSpec(
|
|
104
|
+
async (routes) => {
|
|
105
|
+
const spec = generateOpenApiSpec(routes, config);
|
|
103
106
|
const errors = validateOpenApiSpec(spec);
|
|
104
107
|
|
|
105
108
|
if (errors.length > 0) {
|
|
@@ -110,18 +113,25 @@ function createOpenApiValidateCommand(bootstrap: AppBootstrap, close?: AppCleanu
|
|
|
110
113
|
return 1;
|
|
111
114
|
}
|
|
112
115
|
|
|
113
|
-
console.log(`OpenAPI spec valid (${
|
|
116
|
+
console.log(`OpenAPI spec valid (${routes.length} routes).`);
|
|
114
117
|
return undefined;
|
|
115
118
|
},
|
|
116
119
|
close,
|
|
120
|
+
spaPrefix,
|
|
117
121
|
);
|
|
118
122
|
}
|
|
119
123
|
|
|
120
|
-
function createOpenApiCheckCommand(
|
|
124
|
+
function createOpenApiCheckCommand(
|
|
125
|
+
bootstrap: AppBootstrap,
|
|
126
|
+
close?: AppCleanup,
|
|
127
|
+
config: OpenApiConfig = resolveOpenApiConfig(process.env),
|
|
128
|
+
spaPrefix = readSpaPrefix(),
|
|
129
|
+
) {
|
|
130
|
+
config = Object.freeze({ ...config });
|
|
121
131
|
return createOpenApiCommand(
|
|
122
132
|
bootstrap,
|
|
123
|
-
async () => {
|
|
124
|
-
const spec = generateOpenApiSpec(
|
|
133
|
+
async (routes) => {
|
|
134
|
+
const spec = generateOpenApiSpec(routes, config);
|
|
125
135
|
const errors = validateOpenApiSpec(spec);
|
|
126
136
|
|
|
127
137
|
if (errors.length > 0) {
|
|
@@ -145,10 +155,11 @@ function createOpenApiCheckCommand(bootstrap: AppBootstrap, close?: AppCleanup)
|
|
|
145
155
|
return 1;
|
|
146
156
|
}
|
|
147
157
|
|
|
148
|
-
console.log(`OpenAPI spec matches committed file (${
|
|
158
|
+
console.log(`OpenAPI spec matches committed file (${routes.length} routes).`);
|
|
149
159
|
return undefined;
|
|
150
160
|
},
|
|
151
161
|
close,
|
|
162
|
+
spaPrefix,
|
|
152
163
|
);
|
|
153
164
|
}
|
|
154
165
|
|
package/src/outboxWorker.ts
CHANGED
|
@@ -1,40 +1,51 @@
|
|
|
1
|
-
import type {
|
|
2
|
-
import {
|
|
1
|
+
import type { Application } from "@getstrata/core/contracts/application";
|
|
2
|
+
import type { OutboxWorkerTransport } from "@getstrata/core/events/outbox";
|
|
3
3
|
import {
|
|
4
4
|
installGracefulShutdownSignals,
|
|
5
5
|
LifecycleCoordinator,
|
|
6
6
|
} from "@getstrata/core/lifecycle/gracefulShutdown";
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
boot: OutboxWorkerBoot;
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
drain?: OutboxWorkerClose;
|
|
18
|
-
lifecycle?: LifecycleCoordinator;
|
|
19
|
-
};
|
|
8
|
+
interface OutboxWorkerApplication {
|
|
9
|
+
readonly application: Application;
|
|
10
|
+
readonly outboxWorker: OutboxWorkerTransport;
|
|
11
|
+
}
|
|
12
|
+
type OutboxWorkerBoot = () => OutboxWorkerApplication | Promise<OutboxWorkerApplication>;
|
|
13
|
+
interface OutboxWorkerOptions {
|
|
14
|
+
readonly boot: OutboxWorkerBoot;
|
|
15
|
+
readonly lifecycle?: LifecycleCoordinator;
|
|
16
|
+
}
|
|
20
17
|
|
|
21
18
|
async function runOutboxWorkerCommand(options: OutboxWorkerOptions): Promise<void> {
|
|
22
|
-
if (
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
19
|
+
if (
|
|
20
|
+
typeof options.boot !== "function" ||
|
|
21
|
+
["listeners", "outbox", "close", "flush", "drain"].some((key) => Object.hasOwn(options, key))
|
|
22
|
+
)
|
|
23
|
+
throw new TypeError("Outbox workers require boot() returning an application-owned transport.");
|
|
26
24
|
const lifecycle = options.lifecycle ?? new LifecycleCoordinator();
|
|
27
25
|
if (lifecycle.isShuttingDown) throw new Error("Cannot start an outbox worker during shutdown.");
|
|
28
|
-
|
|
26
|
+
let application: OutboxWorkerApplication | undefined;
|
|
29
27
|
let running: Promise<void> | undefined;
|
|
30
|
-
let booting: Promise<
|
|
28
|
+
let booting: Promise<void> | undefined;
|
|
31
29
|
let stopping = false;
|
|
32
30
|
const name = `outbox:${crypto.randomUUID()}`;
|
|
33
31
|
lifecycle.register(
|
|
34
32
|
`${name}:stop`,
|
|
35
|
-
() => {
|
|
33
|
+
async () => {
|
|
36
34
|
stopping = true;
|
|
37
|
-
|
|
35
|
+
// The signal lifecycle determines process exit status even when boot has
|
|
36
|
+
// already rejected. Retain that exact failure in every shutdown ordering.
|
|
37
|
+
await booting;
|
|
38
|
+
if (!application) return;
|
|
39
|
+
const result = await application.application.stop({ reason: "OUTBOX_SHUTDOWN" });
|
|
40
|
+
if (!result.successful) {
|
|
41
|
+
const failures = result.snapshot.errors.map((entry) => entry.error);
|
|
42
|
+
throw new AggregateError(
|
|
43
|
+
failures.length
|
|
44
|
+
? failures
|
|
45
|
+
: [new Error("Outbox application shutdown was not confirmed clean.")],
|
|
46
|
+
"Outbox application shutdown failed.",
|
|
47
|
+
);
|
|
48
|
+
}
|
|
38
49
|
},
|
|
39
50
|
"stop",
|
|
40
51
|
);
|
|
@@ -44,51 +55,42 @@ async function runOutboxWorkerCommand(options: OutboxWorkerOptions): Promise<voi
|
|
|
44
55
|
await booting?.catch(() => {});
|
|
45
56
|
await running?.catch(() => {});
|
|
46
57
|
if (running) console.log("[outbox:work] Polling stopped.");
|
|
47
|
-
await options.drain?.();
|
|
48
58
|
},
|
|
49
59
|
"drain",
|
|
50
60
|
);
|
|
51
|
-
lifecycle.register(
|
|
52
|
-
`${name}:flush`,
|
|
53
|
-
async () => {
|
|
54
|
-
await options.flush?.();
|
|
55
|
-
},
|
|
56
|
-
"flush",
|
|
57
|
-
);
|
|
58
|
-
lifecycle.register(
|
|
59
|
-
`${name}:close`,
|
|
60
|
-
async () => {
|
|
61
|
-
await options.close?.();
|
|
62
|
-
},
|
|
63
|
-
"close",
|
|
64
|
-
);
|
|
65
61
|
const uninstall = installGracefulShutdownSignals(undefined, lifecycle);
|
|
66
|
-
let failure: unknown;
|
|
67
|
-
let failed = false;
|
|
62
|
+
let failure: { error: unknown } | undefined;
|
|
68
63
|
try {
|
|
69
|
-
booting =
|
|
64
|
+
booting = (async () => {
|
|
65
|
+
application = await options.boot();
|
|
66
|
+
})();
|
|
70
67
|
await booting;
|
|
68
|
+
if (!application?.application || typeof application.application.stop !== "function")
|
|
69
|
+
throw new TypeError("Outbox boot must return its application.");
|
|
70
|
+
if (!application.outboxWorker || typeof application.outboxWorker.start !== "function")
|
|
71
|
+
throw new TypeError("Outbox boot must return its application-owned outboxWorker.");
|
|
71
72
|
if (!stopping && !lifecycle.isShuttingDown) {
|
|
72
|
-
const outbox = options.outbox ?? new SqlOutbox({ listeners: options.listeners ?? [] });
|
|
73
73
|
console.log(
|
|
74
74
|
"[outbox:work] Starting SQL outbox polling; idle until deliveries are available.",
|
|
75
75
|
);
|
|
76
|
-
running =
|
|
76
|
+
running = application.outboxWorker.start();
|
|
77
77
|
await running;
|
|
78
78
|
}
|
|
79
79
|
} catch (error) {
|
|
80
|
-
|
|
81
|
-
|
|
80
|
+
failure = { error };
|
|
81
|
+
}
|
|
82
|
+
try {
|
|
83
|
+
const result = await lifecycle.shutdown("OUTBOX_FINISHED");
|
|
84
|
+
if (!result.successful)
|
|
85
|
+
throw new AggregateError(
|
|
86
|
+
[...(failure ? [failure.error] : []), ...result.errors.map((entry) => entry.error)],
|
|
87
|
+
"Outbox startup/runtime or shutdown failed.",
|
|
88
|
+
);
|
|
89
|
+
if (failure) throw failure.error;
|
|
90
|
+
} finally {
|
|
91
|
+
uninstall();
|
|
82
92
|
}
|
|
83
|
-
const result = await lifecycle.shutdown("OUTBOX_FINISHED");
|
|
84
|
-
uninstall();
|
|
85
|
-
if (!result.successful)
|
|
86
|
-
throw new AggregateError(
|
|
87
|
-
[...(failed ? [failure] : []), ...result.errors.map((entry) => entry.error)],
|
|
88
|
-
"Outbox startup/runtime or shutdown failed.",
|
|
89
|
-
);
|
|
90
|
-
if (failed) throw failure;
|
|
91
93
|
}
|
|
92
94
|
|
|
93
|
-
export type {
|
|
95
|
+
export type { OutboxWorkerApplication, OutboxWorkerBoot, OutboxWorkerOptions };
|
|
94
96
|
export { runOutboxWorkerCommand };
|