@opengeni/worker-bundle 0.16.29 → 0.20.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.
Files changed (188) hide show
  1. package/dist/activities/agent-run-admission.d.ts +12 -0
  2. package/dist/activities/agent-turn.d.ts +110 -19
  3. package/dist/activities/api-integrations.d.ts +21 -0
  4. package/dist/activities/browser-state-artifact-reaper.d.ts +29 -0
  5. package/dist/activities/capabilities.d.ts +6 -0
  6. package/dist/activities/codemode-dispatcher.d.ts +35 -0
  7. package/dist/activities/codemode-token-renewal.d.ts +23 -0
  8. package/dist/activities/codex-capacity.d.ts +6 -5
  9. package/dist/activities/codex-image-generation.d.ts +21 -0
  10. package/dist/activities/context-compaction.d.ts +1 -0
  11. package/dist/activities/documents.d.ts +3 -2
  12. package/dist/activities/environment.d.ts +17 -8
  13. package/dist/activities/expiring-material-renewal.d.ts +1 -1
  14. package/dist/activities/file-upload-reaper.d.ts +7 -2
  15. package/dist/activities/gateway-image-generation.d.ts +39 -0
  16. package/dist/activities/gateway-video-generation.d.ts +53 -0
  17. package/dist/activities/generated-images.d.ts +112 -0
  18. package/dist/activities/git-credential-renewal.d.ts +1 -1
  19. package/dist/activities/goals.d.ts +2 -2
  20. package/dist/activities/google-drive-changes.d.ts +99 -0
  21. package/dist/activities/image-generation-operation.d.ts +74 -0
  22. package/dist/activities/image-generation-references.d.ts +25 -0
  23. package/dist/activities/knowledge-source-sync-driver.d.ts +23 -0
  24. package/dist/activities/knowledge-source-sync.d.ts +75 -0
  25. package/dist/activities/packs.d.ts +21 -36
  26. package/dist/activities/parent-wake.d.ts +1 -1
  27. package/dist/activities/retained-screenshot-reaper.d.ts +2 -2
  28. package/dist/activities/retained-screenshots.d.ts +36 -0
  29. package/dist/activities/rig-verification.d.ts +82 -5
  30. package/dist/activities/run-credential-renewal.d.ts +1 -1
  31. package/dist/activities/run-input.d.ts +3 -1
  32. package/dist/activities/sandbox-images.d.ts +14 -0
  33. package/dist/activities/sandbox-lease.d.ts +47 -9
  34. package/dist/activities/scheduled-tasks.d.ts +2 -2
  35. package/dist/activities/session-state.d.ts +7 -5
  36. package/dist/activities/site-auth-maintenance.d.ts +27 -0
  37. package/dist/activities/streaming.d.ts +1 -1
  38. package/dist/activities/types.d.ts +87 -5
  39. package/dist/activities/video-generation-admission.d.ts +43 -0
  40. package/dist/activities/video-generation-credential.d.ts +24 -0
  41. package/dist/activities/video-generation-reconciliation.d.ts +13 -0
  42. package/dist/activities/video-media-validation.d.ts +34 -0
  43. package/dist/activities/video-output-retention.d.ts +36 -0
  44. package/dist/activities/video-reference-staging.d.ts +55 -0
  45. package/dist/activities/workflow-wake.d.ts +2 -2
  46. package/dist/activities/workspace-capture.d.ts +10 -1
  47. package/dist/activities/xai-auth.d.ts +23 -0
  48. package/dist/activities/xai-image-generation.d.ts +26 -0
  49. package/dist/activities/xai-video-generation.d.ts +18 -0
  50. package/dist/activities-control-XURE4VKN.js +7221 -0
  51. package/dist/activities-control-XURE4VKN.js.map +1 -0
  52. package/dist/activities-control.d.ts +297 -0
  53. package/dist/activities-turn-6EBXGGLS.js +16036 -0
  54. package/dist/activities-turn-6EBXGGLS.js.map +1 -0
  55. package/dist/activities-turn.d.ts +17 -0
  56. package/dist/activities.d.ts +138 -150
  57. package/dist/activity-services.d.ts +10 -0
  58. package/dist/artifact-materializer-entry.d.ts +6 -0
  59. package/dist/artifact-materializer-entry.js +2662 -0
  60. package/dist/artifact-materializer-entry.js.map +1 -0
  61. package/dist/artifact-outbox-entry.d.ts +2 -0
  62. package/dist/artifact-outbox-entry.js +681 -0
  63. package/dist/artifact-outbox-entry.js.map +1 -0
  64. package/dist/chunk-5GRJIP5H.js +3092 -0
  65. package/dist/chunk-5GRJIP5H.js.map +1 -0
  66. package/dist/chunk-GRFQTTSQ.js +448 -0
  67. package/dist/chunk-GRFQTTSQ.js.map +1 -0
  68. package/dist/chunk-TYNPCG4U.js +906 -0
  69. package/dist/chunk-TYNPCG4U.js.map +1 -0
  70. package/dist/concurrency.d.ts +108 -5
  71. package/dist/editable-artifact-hint-broker.d.ts +49 -0
  72. package/dist/editable-artifact-materializer-launcher.d.ts +49 -0
  73. package/dist/editable-artifact-materializer-service.d.ts +108 -0
  74. package/dist/editable-artifact-materializer-storage.d.ts +12 -0
  75. package/dist/editable-artifact-materializer-subprocess.d.ts +50 -0
  76. package/dist/editable-artifact-materializer.d.ts +262 -0
  77. package/dist/editable-artifact-outbox-dispatcher.d.ts +44 -0
  78. package/dist/editable-artifact-outbox-service.d.ts +70 -0
  79. package/dist/host-export.d.ts +1 -1
  80. package/dist/index.d.ts +189 -10
  81. package/dist/index.js +715 -17380
  82. package/dist/index.js.map +1 -1
  83. package/dist/memory-pressure-guard.d.ts +57 -0
  84. package/dist/model-checkpoint-memory-collector.d.ts +23 -0
  85. package/dist/model-context-contributions.d.ts +40 -0
  86. package/dist/observability-metrics.d.ts +53 -1
  87. package/dist/sandbox-reaper-contract.d.ts +40 -0
  88. package/dist/sandbox-reaper-timeout.d.ts +14 -0
  89. package/dist/sandbox-resume.d.ts +34 -7
  90. package/dist/sandbox-routing.d.ts +6 -0
  91. package/dist/worker-service-lifecycle.d.ts +6 -2
  92. package/dist/workflow-bundle.js +1094 -370
  93. package/dist/workflows/activities.d.ts +8 -2
  94. package/dist/workflows/document-index.d.ts +1 -1
  95. package/dist/workflows/knowledge-source-sync.d.ts +13 -0
  96. package/dist/workflows/rig-verification.d.ts +1 -1
  97. package/dist/workflows/sandbox-reaper.d.ts +8 -0
  98. package/dist/workflows/scheduled-tasks.d.ts +1 -1
  99. package/dist/workflows/session.d.ts +2 -2
  100. package/dist/workflows/site-auth-maintenance.d.ts +2 -0
  101. package/dist/workflows/video-generation.d.ts +10 -0
  102. package/dist/workflows/workflow-wake.d.ts +1 -1
  103. package/dist/workflows.d.ts +10 -7
  104. package/package.json +35 -15
  105. package/src/activities/agent-run-admission.ts +76 -0
  106. package/src/activities/agent-turn.ts +2600 -340
  107. package/src/activities/api-integrations.ts +138 -0
  108. package/src/activities/browser-state-artifact-reaper.ts +120 -0
  109. package/src/activities/capabilities.ts +10 -0
  110. package/src/activities/codemode-dispatcher.ts +335 -0
  111. package/src/activities/codemode-token-renewal.ts +64 -0
  112. package/src/activities/codex-capacity.ts +54 -7
  113. package/src/activities/codex-image-generation.ts +56 -0
  114. package/src/activities/context-compaction.ts +38 -3
  115. package/src/activities/documents.ts +14 -4
  116. package/src/activities/environment.ts +54 -45
  117. package/src/activities/expiring-material-renewal.ts +1 -1
  118. package/src/activities/file-upload-reaper.ts +34 -3
  119. package/src/activities/gateway-image-generation.ts +146 -0
  120. package/src/activities/gateway-video-generation.ts +298 -0
  121. package/src/activities/generated-images.ts +860 -0
  122. package/src/activities/goals.ts +8 -3
  123. package/src/activities/google-drive-changes.ts +454 -0
  124. package/src/activities/image-generation-operation.ts +333 -0
  125. package/src/activities/image-generation-references.ts +118 -0
  126. package/src/activities/knowledge-source-sync-driver.ts +27 -0
  127. package/src/activities/knowledge-source-sync.ts +2840 -0
  128. package/src/activities/mcp-credentials.ts +1 -0
  129. package/src/activities/packs.ts +75 -152
  130. package/src/activities/parent-wake.ts +13 -1
  131. package/src/activities/retained-screenshot-reaper.ts +2 -2
  132. package/src/activities/retained-screenshots.ts +453 -28
  133. package/src/activities/rig-verification.ts +554 -43
  134. package/src/activities/run-input.ts +22 -6
  135. package/src/activities/sandbox-images.ts +167 -0
  136. package/src/activities/sandbox-lease.ts +1065 -483
  137. package/src/activities/scheduled-tasks.ts +104 -74
  138. package/src/activities/session-state.ts +22 -4
  139. package/src/activities/site-auth-maintenance.ts +269 -0
  140. package/src/activities/streaming.ts +42 -3
  141. package/src/activities/types.ts +104 -5
  142. package/src/activities/video-generation-admission.ts +303 -0
  143. package/src/activities/video-generation-credential.ts +112 -0
  144. package/src/activities/video-generation-reconciliation.ts +771 -0
  145. package/src/activities/video-media-validation.ts +332 -0
  146. package/src/activities/video-output-retention.ts +314 -0
  147. package/src/activities/video-reference-staging.ts +350 -0
  148. package/src/activities/workflow-wake.ts +2 -2
  149. package/src/activities/workspace-capture.ts +44 -10
  150. package/src/activities/xai-auth.ts +122 -0
  151. package/src/activities/xai-image-generation.ts +86 -0
  152. package/src/activities/xai-video-generation.ts +69 -0
  153. package/src/activities-control.ts +58 -0
  154. package/src/activities-turn.ts +40 -0
  155. package/src/activities.ts +53 -124
  156. package/src/activity-services.ts +62 -0
  157. package/src/artifact-materializer-entry.ts +35 -0
  158. package/src/artifact-outbox-entry.ts +29 -0
  159. package/src/concurrency.ts +484 -6
  160. package/src/editable-artifact-hint-broker.ts +235 -0
  161. package/src/editable-artifact-materializer-launcher.ts +515 -0
  162. package/src/editable-artifact-materializer-service.ts +787 -0
  163. package/src/editable-artifact-materializer-storage.ts +413 -0
  164. package/src/editable-artifact-materializer-subprocess.ts +956 -0
  165. package/src/editable-artifact-materializer.ts +1289 -0
  166. package/src/editable-artifact-outbox-dispatcher.ts +244 -0
  167. package/src/editable-artifact-outbox-service.ts +438 -0
  168. package/src/index.ts +328 -72
  169. package/src/memory-pressure-guard.ts +489 -0
  170. package/src/model-checkpoint-memory-collector.ts +123 -0
  171. package/src/model-context-contributions.ts +159 -0
  172. package/src/observability-metrics.ts +297 -13
  173. package/src/sandbox-reaper-contract.ts +73 -0
  174. package/src/sandbox-reaper-timeout.ts +79 -0
  175. package/src/sandbox-resume.ts +294 -153
  176. package/src/sandbox-routing.ts +32 -24
  177. package/src/worker-service-lifecycle.ts +80 -14
  178. package/src/workflows/activities.ts +31 -0
  179. package/src/workflows/file-upload-reaper.ts +9 -1
  180. package/src/workflows/knowledge-source-sync.ts +83 -0
  181. package/src/workflows/sandbox-reaper.ts +183 -21
  182. package/src/workflows/scheduled-tasks.ts +42 -6
  183. package/src/workflows/session.ts +20 -6
  184. package/src/workflows/site-auth-maintenance.ts +14 -0
  185. package/src/workflows/video-generation.ts +36 -0
  186. package/src/workflows.ts +18 -1
  187. package/dist/activities/toolspace-token-renewal.d.ts +0 -23
  188. package/src/activities/toolspace-token-renewal.ts +0 -64
@@ -0,0 +1,244 @@
1
+ import {
2
+ EditableArtifactLiveOutboxDispatcher,
3
+ MathEditableArtifactOutboxRandom,
4
+ SystemEditableArtifactLiveClock,
5
+ SystemEditableArtifactLiveScheduler,
6
+ type EditableArtifactOutboxDispatcherOptions,
7
+ type EditableArtifactOutboxLoggerPort,
8
+ type EditableArtifactOutboxMetricsPort,
9
+ type EditableArtifactOutboxDispatcherStorePort,
10
+ type EditableArtifactLiveOutboxRecord,
11
+ } from "@opengeni/core";
12
+ import {
13
+ PostgresEditableArtifactStore,
14
+ createDb,
15
+ dbSql,
16
+ type Database,
17
+ type DbClient,
18
+ } from "@opengeni/db";
19
+
20
+ import {
21
+ connectEditableArtifactHintBroker,
22
+ type ConfirmedNatsEditableArtifactHintBroker,
23
+ type EditableArtifactHintNatsAuth,
24
+ } from "./editable-artifact-hint-broker";
25
+
26
+ export const EDITABLE_ARTIFACT_OUTBOX_DISPATCHER_DATABASE_ROLE =
27
+ "opengeni_artifact_outbox_dispatcher";
28
+ export const EDITABLE_ARTIFACT_OUTBOX_DATABASE_URL_ENV = "OPENGENI_ARTIFACT_OUTBOX_DATABASE_URL";
29
+
30
+ export type EditableArtifactOutboxWorkerOptions = Readonly<{
31
+ /** Must authenticate as the dedicated dispatcher role, never the generic app role. */
32
+ dispatcherDatabaseUrl: string;
33
+ databaseSearchPath?: string;
34
+ databasePoolSize?: number;
35
+ natsUrl: string;
36
+ natsAuth: EditableArtifactHintNatsAuth;
37
+ owner?: string;
38
+ dispatcher?: Omit<EditableArtifactOutboxDispatcherOptions, "owner">;
39
+ metrics?: EditableArtifactOutboxMetricsPort;
40
+ logger?: EditableArtifactOutboxLoggerPort;
41
+ }>;
42
+
43
+ /** Explicit lifecycle handle; hosts supervise `start()` and await `stop()` on drain. */
44
+ export class EditableArtifactOutboxWorkerRuntime {
45
+ private readonly abort = new AbortController();
46
+ private running: Promise<void> | null = null;
47
+ private closing: Promise<void> | null = null;
48
+
49
+ constructor(
50
+ readonly dispatcher: EditableArtifactLiveOutboxDispatcher,
51
+ private readonly broker: ConfirmedNatsEditableArtifactHintBroker,
52
+ private readonly database: DbClient,
53
+ ) {}
54
+
55
+ start(): Promise<void> {
56
+ if (this.closing) return Promise.reject(new Error("Artifact outbox worker is stopping"));
57
+ this.running ??= this.dispatcher.run(this.abort.signal);
58
+ return this.running;
59
+ }
60
+
61
+ drain(): boolean {
62
+ if (this.abort.signal.aborted) return false;
63
+ this.abort.abort();
64
+ return true;
65
+ }
66
+
67
+ async check(signal?: AbortSignal): Promise<void> {
68
+ if (this.abort.signal.aborted || this.closing) {
69
+ throw new Error("Artifact outbox worker is stopping");
70
+ }
71
+ await Promise.all([
72
+ assertDedicatedOutboxDispatcherDatabaseRole(this.database.db),
73
+ this.broker.check(signal),
74
+ ]);
75
+ }
76
+
77
+ stop(): Promise<void> {
78
+ if (this.closing) return this.closing;
79
+ this.closing = this.stopOnce();
80
+ return this.closing;
81
+ }
82
+
83
+ private async stopOnce(): Promise<void> {
84
+ this.drain();
85
+ const running = this.running ? await Promise.allSettled([this.running]) : [];
86
+ const cleanup = await Promise.allSettled([this.broker.close(), this.database.close()]);
87
+ const failure = [...running, ...cleanup].find(
88
+ (result): result is PromiseRejectedResult => result.status === "rejected",
89
+ );
90
+ if (failure) throw failure.reason;
91
+ }
92
+ }
93
+
94
+ /**
95
+ * Production composition. DB grants make the role a narrow capability: it can
96
+ * execute only lease-fenced dispatcher functions and cannot read artifact rows.
97
+ */
98
+ export async function createEditableArtifactOutboxWorker(
99
+ options: EditableArtifactOutboxWorkerOptions,
100
+ ): Promise<EditableArtifactOutboxWorkerRuntime> {
101
+ const dispatcherDatabaseUrl = dedicatedDispatcherDatabaseUrl(options.dispatcherDatabaseUrl);
102
+ const databasePoolSize = options.databasePoolSize ?? 2;
103
+ if (!Number.isSafeInteger(databasePoolSize) || databasePoolSize < 1 || databasePoolSize > 8) {
104
+ throw new TypeError("Artifact outbox dispatcher DB pool size must be 1-8");
105
+ }
106
+ const database = createDb(dispatcherDatabaseUrl, {
107
+ max: databasePoolSize,
108
+ ...(options.databaseSearchPath ? { searchPath: options.databaseSearchPath } : {}),
109
+ });
110
+ let broker: ConfirmedNatsEditableArtifactHintBroker;
111
+ try {
112
+ await assertDedicatedOutboxDispatcherDatabaseRole(database.db);
113
+ broker = await connectEditableArtifactHintBroker({
114
+ natsUrl: options.natsUrl,
115
+ auth: options.natsAuth,
116
+ });
117
+ } catch (error) {
118
+ await database.close();
119
+ throw error;
120
+ }
121
+ const persistence = new PostgresEditableArtifactStore(database.db);
122
+ const store = dispatcherStore(persistence);
123
+ const dispatcher = new EditableArtifactLiveOutboxDispatcher(
124
+ {
125
+ store,
126
+ broker,
127
+ clock: new SystemEditableArtifactLiveClock(),
128
+ scheduler: new SystemEditableArtifactLiveScheduler(),
129
+ random: new MathEditableArtifactOutboxRandom(),
130
+ ...(options.metrics ? { metrics: options.metrics } : {}),
131
+ ...(options.logger ? { logger: options.logger } : {}),
132
+ },
133
+ {
134
+ owner: options.owner ?? `artifact-outbox:${crypto.randomUUID()}`,
135
+ ...options.dispatcher,
136
+ },
137
+ );
138
+ return new EditableArtifactOutboxWorkerRuntime(dispatcher, broker, database);
139
+ }
140
+
141
+ /**
142
+ * Verify the database identity and its negative capability at runtime. A DSN
143
+ * username check alone is insufficient because PostgreSQL role inheritance,
144
+ * SET ROLE, or a mis-provisioned grant could otherwise widen this worker.
145
+ */
146
+ export async function assertDedicatedOutboxDispatcherDatabaseRole(db: Database): Promise<void> {
147
+ const raw = await db.execute<{
148
+ current_role: string;
149
+ session_role: string;
150
+ can_access_any_relation: boolean;
151
+ can_access_any_sequence: boolean;
152
+ }>(dbSql`
153
+ select
154
+ current_user::text as current_role,
155
+ session_user::text as session_role,
156
+ exists (
157
+ select 1
158
+ from pg_catalog.pg_class relation_row
159
+ join pg_catalog.pg_namespace namespace_row
160
+ on namespace_row.oid = relation_row.relnamespace
161
+ where namespace_row.nspname = current_schema()
162
+ and relation_row.relkind in ('r', 'p', 'v', 'm', 'f')
163
+ and (
164
+ has_table_privilege(current_user, relation_row.oid, 'SELECT')
165
+ or has_table_privilege(current_user, relation_row.oid, 'INSERT')
166
+ or has_table_privilege(current_user, relation_row.oid, 'UPDATE')
167
+ or has_table_privilege(current_user, relation_row.oid, 'DELETE')
168
+ or has_table_privilege(current_user, relation_row.oid, 'TRUNCATE')
169
+ or has_table_privilege(current_user, relation_row.oid, 'REFERENCES')
170
+ or has_table_privilege(current_user, relation_row.oid, 'TRIGGER')
171
+ or has_any_column_privilege(current_user, relation_row.oid, 'SELECT')
172
+ or has_any_column_privilege(current_user, relation_row.oid, 'INSERT')
173
+ or has_any_column_privilege(current_user, relation_row.oid, 'UPDATE')
174
+ or has_any_column_privilege(current_user, relation_row.oid, 'REFERENCES')
175
+ )
176
+ ) as can_access_any_relation,
177
+ exists (
178
+ select 1
179
+ from pg_catalog.pg_class sequence_row
180
+ join pg_catalog.pg_namespace namespace_row
181
+ on namespace_row.oid = sequence_row.relnamespace
182
+ where namespace_row.nspname = current_schema()
183
+ and sequence_row.relkind = 'S'
184
+ and (
185
+ has_sequence_privilege(current_user, sequence_row.oid, 'USAGE')
186
+ or has_sequence_privilege(current_user, sequence_row.oid, 'SELECT')
187
+ or has_sequence_privilege(current_user, sequence_row.oid, 'UPDATE')
188
+ )
189
+ ) as can_access_any_sequence
190
+ `);
191
+ const rows = Array.isArray(raw) ? raw : ((raw as unknown as { rows?: unknown[] }).rows ?? []);
192
+ const row = rows[0] as
193
+ | {
194
+ current_role?: unknown;
195
+ session_role?: unknown;
196
+ can_access_any_relation?: unknown;
197
+ can_access_any_sequence?: unknown;
198
+ }
199
+ | undefined;
200
+ if (
201
+ row?.current_role !== EDITABLE_ARTIFACT_OUTBOX_DISPATCHER_DATABASE_ROLE ||
202
+ row.session_role !== EDITABLE_ARTIFACT_OUTBOX_DISPATCHER_DATABASE_ROLE ||
203
+ row.can_access_any_relation !== false ||
204
+ row.can_access_any_sequence !== false
205
+ ) {
206
+ throw new Error("Artifact outbox dispatcher database connection has an unsafe role posture");
207
+ }
208
+ }
209
+
210
+ function dispatcherStore(
211
+ persistence: PostgresEditableArtifactStore,
212
+ ): EditableArtifactOutboxDispatcherStorePort {
213
+ return {
214
+ claimLiveOutbox: async (input) =>
215
+ (await persistence.claimLiveOutbox(
216
+ input,
217
+ )) as unknown as readonly EditableArtifactLiveOutboxRecord[],
218
+ renewLiveOutbox: async (input) => await persistence.renewLiveOutbox(input),
219
+ markLiveOutboxPublished: async (input) => await persistence.markLiveOutboxPublished(input),
220
+ retryLiveOutbox: async (input) => await persistence.retryLiveOutbox(input),
221
+ deadLetterLiveOutbox: async (input) => await persistence.deadLetterLiveOutbox(input),
222
+ };
223
+ }
224
+
225
+ export function dedicatedDispatcherDatabaseUrl(raw: string): string {
226
+ if (typeof raw !== "string" || raw.length > 8_192 || raw.trim() !== raw) {
227
+ throw new TypeError(`${EDITABLE_ARTIFACT_OUTBOX_DATABASE_URL_ENV} is malformed`);
228
+ }
229
+ let url: URL;
230
+ try {
231
+ url = new URL(raw);
232
+ } catch (cause) {
233
+ throw new TypeError(`${EDITABLE_ARTIFACT_OUTBOX_DATABASE_URL_ENV} is malformed`, { cause });
234
+ }
235
+ if (
236
+ (url.protocol !== "postgres:" && url.protocol !== "postgresql:") ||
237
+ decodeURIComponent(url.username) !== EDITABLE_ARTIFACT_OUTBOX_DISPATCHER_DATABASE_ROLE
238
+ ) {
239
+ throw new TypeError(
240
+ `${EDITABLE_ARTIFACT_OUTBOX_DATABASE_URL_ENV} must authenticate as ${EDITABLE_ARTIFACT_OUTBOX_DISPATCHER_DATABASE_ROLE}`,
241
+ );
242
+ }
243
+ return raw;
244
+ }
@@ -0,0 +1,438 @@
1
+ import {
2
+ dbSearchPath,
3
+ getSettings,
4
+ resolveNatsControlPlaneAuth,
5
+ type Settings,
6
+ } from "@opengeni/config";
7
+ import type { EditableArtifactOutboxDispatchSummary } from "@opengeni/core";
8
+ import { createObservability, type Observability } from "@opengeni/observability";
9
+
10
+ import {
11
+ EDITABLE_ARTIFACT_OUTBOX_DATABASE_URL_ENV,
12
+ EDITABLE_ARTIFACT_OUTBOX_DISPATCHER_DATABASE_ROLE,
13
+ createEditableArtifactOutboxWorker,
14
+ type EditableArtifactOutboxWorkerRuntime,
15
+ } from "./editable-artifact-outbox-dispatcher";
16
+ import type { EditableArtifactHintNatsAuth } from "./editable-artifact-hint-broker";
17
+
18
+ export type EditableArtifactOutboxServiceState =
19
+ | "starting"
20
+ | "ready"
21
+ | "draining"
22
+ | "stopped"
23
+ | "failed";
24
+
25
+ export interface EditableArtifactOutboxRuntimePort {
26
+ start(): Promise<void>;
27
+ drain(): boolean;
28
+ stop(): Promise<void>;
29
+ check(signal?: AbortSignal): Promise<void>;
30
+ readonly dispatcher: Readonly<{
31
+ dispatchOnce(): Promise<EditableArtifactOutboxDispatchSummary>;
32
+ }>;
33
+ }
34
+
35
+ export type EditableArtifactOutboxService = Readonly<{
36
+ state(): EditableArtifactOutboxServiceState;
37
+ run(): Promise<void>;
38
+ drain(reason?: string): boolean;
39
+ close(): Promise<void>;
40
+ dispatchOnce(): Promise<EditableArtifactOutboxDispatchSummary>;
41
+ fetch(request: Request): Promise<Response>;
42
+ }>;
43
+
44
+ export type CreateEditableArtifactOutboxServiceInput = Readonly<{
45
+ runtime: EditableArtifactOutboxRuntimePort;
46
+ observability: Observability;
47
+ serviceName: string;
48
+ environment: string;
49
+ deploymentRevision?: string;
50
+ readinessTimeoutMs?: number;
51
+ }>;
52
+
53
+ export type ProductionEditableArtifactOutboxServiceOptions = Readonly<{
54
+ settings: Settings;
55
+ databaseUrl: string;
56
+ declaredDatabaseRole: string;
57
+ natsUrl: string;
58
+ natsAuth: EditableArtifactHintNatsAuth;
59
+ owner: string;
60
+ databasePoolSize?: number;
61
+ batchSize?: number;
62
+ concurrency?: number;
63
+ leaseDurationMs?: number;
64
+ leaseRenewIntervalMs?: number;
65
+ pollIntervalMs?: number;
66
+ publishTimeoutMs?: number;
67
+ retryBaseMs?: number;
68
+ retryMaxMs?: number;
69
+ }>;
70
+
71
+ /** Compose the independently supervised production outbox dispatcher. */
72
+ export async function createProductionEditableArtifactOutboxService(
73
+ options: ProductionEditableArtifactOutboxServiceOptions,
74
+ ): Promise<EditableArtifactOutboxService> {
75
+ if (options.declaredDatabaseRole !== EDITABLE_ARTIFACT_OUTBOX_DISPATCHER_DATABASE_ROLE) {
76
+ throw new Error("Artifact outbox dispatcher database role declaration is invalid");
77
+ }
78
+ const observability = createObservability(options.settings, {
79
+ component: "artifact-outbox-dispatcher",
80
+ });
81
+ const databaseSearchPath = dbSearchPath(options.settings);
82
+ const runtime = await createEditableArtifactOutboxWorker({
83
+ dispatcherDatabaseUrl: options.databaseUrl,
84
+ ...(databaseSearchPath ? { databaseSearchPath } : {}),
85
+ ...(options.databasePoolSize === undefined
86
+ ? {}
87
+ : { databasePoolSize: options.databasePoolSize }),
88
+ natsUrl: options.natsUrl,
89
+ natsAuth: options.natsAuth,
90
+ owner: options.owner,
91
+ dispatcher: {
92
+ ...(options.batchSize === undefined ? {} : { batchSize: options.batchSize }),
93
+ ...(options.concurrency === undefined ? {} : { concurrency: options.concurrency }),
94
+ ...(options.leaseDurationMs === undefined
95
+ ? {}
96
+ : { leaseDurationMs: options.leaseDurationMs }),
97
+ ...(options.leaseRenewIntervalMs === undefined
98
+ ? {}
99
+ : { leaseRenewIntervalMs: options.leaseRenewIntervalMs }),
100
+ ...(options.pollIntervalMs === undefined ? {} : { pollIntervalMs: options.pollIntervalMs }),
101
+ ...(options.publishTimeoutMs === undefined
102
+ ? {}
103
+ : { publishTimeoutMs: options.publishTimeoutMs }),
104
+ ...(options.retryBaseMs === undefined ? {} : { retryBaseMs: options.retryBaseMs }),
105
+ ...(options.retryMaxMs === undefined ? {} : { retryMaxMs: options.retryMaxMs }),
106
+ },
107
+ metrics: {
108
+ increment(outcome, count = 1) {
109
+ observability.incrementCounter({
110
+ name: "opengeni_artifact_outbox_dispatch_total",
111
+ help: "Editable artifact outbox dispatch actions by closed outcome.",
112
+ labels: { outcome },
113
+ amount: count,
114
+ });
115
+ },
116
+ observePublishSeconds(outcome, seconds) {
117
+ observability.observeHistogram({
118
+ name: "opengeni_artifact_outbox_publish_seconds",
119
+ help: "Editable artifact broker publication latency by closed outcome.",
120
+ labels: { outcome },
121
+ value: seconds,
122
+ });
123
+ },
124
+ },
125
+ logger: {
126
+ warn(message, attributes) {
127
+ observability.warn(message, {
128
+ errorClass: "WorkerOperationError",
129
+ errorCode: "worker_operation_failed",
130
+ origin: "worker",
131
+ outcome: typeof attributes.code === "string" ? attributes.code : "unknown",
132
+ });
133
+ },
134
+ },
135
+ });
136
+ return createEditableArtifactOutboxService({
137
+ runtime,
138
+ observability,
139
+ serviceName: options.settings.serviceName,
140
+ environment: options.settings.environment,
141
+ deploymentRevision: options.settings.deploymentRevision,
142
+ });
143
+ }
144
+
145
+ export function createEditableArtifactOutboxService(
146
+ input: CreateEditableArtifactOutboxServiceInput,
147
+ ): EditableArtifactOutboxService {
148
+ let state: EditableArtifactOutboxServiceState = "starting";
149
+ let runPromise: Promise<void> | null = null;
150
+ let closePromise: Promise<void> | null = null;
151
+ let readinessPromise: Promise<void> | null = null;
152
+ const readinessTimeoutMs = input.readinessTimeoutMs ?? 2_000;
153
+
154
+ const ready = (): Promise<void> => {
155
+ if (readinessPromise) return readinessPromise;
156
+ const abort = new AbortController();
157
+ const check = withTimeout(input.runtime.check(abort.signal), readinessTimeoutMs, abort);
158
+ readinessPromise = check;
159
+ void check.then(
160
+ () => {
161
+ if (readinessPromise === check) readinessPromise = null;
162
+ },
163
+ () => {
164
+ if (readinessPromise === check) readinessPromise = null;
165
+ },
166
+ );
167
+ return check;
168
+ };
169
+
170
+ const run = (): Promise<void> => {
171
+ if (runPromise) return runPromise;
172
+ if (state !== "starting") {
173
+ return Promise.reject(new Error("Artifact outbox dispatcher service cannot be restarted"));
174
+ }
175
+ runPromise = (async () => {
176
+ try {
177
+ await ready();
178
+ if ((state as EditableArtifactOutboxServiceState) === "draining") {
179
+ state = "stopped";
180
+ return;
181
+ }
182
+ const running = input.runtime.start();
183
+ state = "ready";
184
+ await running;
185
+ const exitWasDraining = (state as EditableArtifactOutboxServiceState) === "draining";
186
+ state = exitWasDraining ? "stopped" : "failed";
187
+ if (!exitWasDraining) {
188
+ throw new Error("Artifact outbox dispatcher exited without a drain request");
189
+ }
190
+ } catch (error) {
191
+ const caughtState = state as EditableArtifactOutboxServiceState;
192
+ if (caughtState !== "draining" && caughtState !== "stopped") state = "failed";
193
+ throw error;
194
+ }
195
+ })();
196
+ return runPromise;
197
+ };
198
+
199
+ const drain = (_reason = "shutdown"): boolean => {
200
+ if (state === "draining" || state === "stopped" || state === "failed") return false;
201
+ state = "draining";
202
+ input.runtime.drain();
203
+ return true;
204
+ };
205
+
206
+ const close = (): Promise<void> => {
207
+ if (closePromise) return closePromise;
208
+ closePromise = (async () => {
209
+ drain("close");
210
+ if (runPromise) await runPromise.catch(() => undefined);
211
+ await input.runtime.stop();
212
+ if (state !== "failed") state = "stopped";
213
+ })();
214
+ return closePromise;
215
+ };
216
+
217
+ const fetch = async (request: Request): Promise<Response> => {
218
+ const url = new URL(request.url);
219
+ if (request.method !== "GET") {
220
+ return Response.json({ error: "method_not_allowed" }, { status: 405 });
221
+ }
222
+ if (url.pathname === "/healthz") {
223
+ const ok = state !== "failed" && state !== "stopped";
224
+ return Response.json(
225
+ {
226
+ service: input.serviceName,
227
+ component: "artifact-outbox-dispatcher",
228
+ environment: input.environment,
229
+ ...(input.deploymentRevision ? { deploymentRevision: input.deploymentRevision } : {}),
230
+ state,
231
+ ok,
232
+ },
233
+ { status: ok ? 200 : 503 },
234
+ );
235
+ }
236
+ if (url.pathname === "/readyz") {
237
+ if (state !== "ready") {
238
+ return Response.json(
239
+ {
240
+ ok: false,
241
+ state,
242
+ checks: { databaseRole: { ok: false }, nats: { ok: false } },
243
+ },
244
+ { status: 503 },
245
+ );
246
+ }
247
+ try {
248
+ await ready();
249
+ return Response.json({
250
+ ok: true,
251
+ state,
252
+ checks: { databaseRole: { ok: true }, nats: { ok: true } },
253
+ });
254
+ } catch {
255
+ return Response.json(
256
+ {
257
+ ok: false,
258
+ state,
259
+ checks: { databaseRole: { ok: false }, nats: { ok: false } },
260
+ },
261
+ { status: 503 },
262
+ );
263
+ }
264
+ }
265
+ if (url.pathname === "/metrics") {
266
+ return new Response(await input.observability.prometheusMetrics(), {
267
+ status: 200,
268
+ headers: { "content-type": "text/plain; version=0.0.4; charset=utf-8" },
269
+ });
270
+ }
271
+ return Response.json({ error: "not_found" }, { status: 404 });
272
+ };
273
+
274
+ return Object.freeze({
275
+ state: () => state,
276
+ run,
277
+ drain,
278
+ close,
279
+ dispatchOnce: async () => await input.runtime.dispatcher.dispatchOnce(),
280
+ fetch,
281
+ });
282
+ }
283
+
284
+ export type EditableArtifactOutboxSidecarEnvironment = Readonly<{
285
+ databaseUrl: string;
286
+ declaredDatabaseRole: string;
287
+ owner: string;
288
+ httpPort: number;
289
+ databasePoolSize: number;
290
+ batchSize: number;
291
+ concurrency: number;
292
+ leaseDurationMs: number;
293
+ leaseRenewIntervalMs: number;
294
+ pollIntervalMs: number;
295
+ publishTimeoutMs: number;
296
+ retryBaseMs: number;
297
+ retryMaxMs: number;
298
+ }>;
299
+
300
+ export function readEditableArtifactOutboxSidecarEnvironment(
301
+ environment: NodeJS.ProcessEnv = process.env,
302
+ ): EditableArtifactOutboxSidecarEnvironment | null {
303
+ if (environment.OPENGENI_ARTIFACT_OUTBOX_ENABLED !== "true") return null;
304
+ const declaredDatabaseRole = required(environment, "OPENGENI_ARTIFACT_OUTBOX_DATABASE_ROLE");
305
+ if (declaredDatabaseRole !== EDITABLE_ARTIFACT_OUTBOX_DISPATCHER_DATABASE_ROLE) {
306
+ throw new Error("OPENGENI_ARTIFACT_OUTBOX_DATABASE_ROLE is invalid");
307
+ }
308
+ const result = {
309
+ databaseUrl: required(environment, EDITABLE_ARTIFACT_OUTBOX_DATABASE_URL_ENV),
310
+ declaredDatabaseRole,
311
+ owner:
312
+ environment.OPENGENI_ARTIFACT_OUTBOX_OWNER?.trim() ||
313
+ `artifact-outbox-${process.pid}-${crypto.randomUUID()}`,
314
+ httpPort: integer(environment, "OPENGENI_ARTIFACT_OUTBOX_HTTP_PORT", 9466, 1, 65_535),
315
+ databasePoolSize: integer(environment, "OPENGENI_ARTIFACT_OUTBOX_DB_POOL_SIZE", 4, 1, 8),
316
+ batchSize: integer(environment, "OPENGENI_ARTIFACT_OUTBOX_BATCH_SIZE", 32, 1, 1_000),
317
+ concurrency: integer(environment, "OPENGENI_ARTIFACT_OUTBOX_CONCURRENCY", 8, 1, 128),
318
+ leaseDurationMs: integer(
319
+ environment,
320
+ "OPENGENI_ARTIFACT_OUTBOX_LEASE_MS",
321
+ 30_000,
322
+ 1_000,
323
+ 86_400_000,
324
+ ),
325
+ leaseRenewIntervalMs: integer(
326
+ environment,
327
+ "OPENGENI_ARTIFACT_OUTBOX_RENEW_MS",
328
+ 10_000,
329
+ 100,
330
+ 43_199_999,
331
+ ),
332
+ pollIntervalMs: integer(environment, "OPENGENI_ARTIFACT_OUTBOX_POLL_MS", 500, 10, 60_000),
333
+ publishTimeoutMs: integer(
334
+ environment,
335
+ "OPENGENI_ARTIFACT_OUTBOX_PUBLISH_TIMEOUT_MS",
336
+ 5_000,
337
+ 100,
338
+ 60_000,
339
+ ),
340
+ retryBaseMs: integer(environment, "OPENGENI_ARTIFACT_OUTBOX_RETRY_BASE_MS", 500, 10, 60_000),
341
+ retryMaxMs: integer(
342
+ environment,
343
+ "OPENGENI_ARTIFACT_OUTBOX_RETRY_MAX_MS",
344
+ 60_000,
345
+ 10,
346
+ 86_400_000,
347
+ ),
348
+ } as const;
349
+ if (result.leaseRenewIntervalMs >= result.leaseDurationMs) {
350
+ throw new Error("OPENGENI_ARTIFACT_OUTBOX_RENEW_MS must be less than lease duration");
351
+ }
352
+ if (result.retryBaseMs > result.retryMaxMs) {
353
+ throw new Error("OPENGENI_ARTIFACT_OUTBOX_RETRY_BASE_MS must not exceed retry max");
354
+ }
355
+ return Object.freeze(result);
356
+ }
357
+
358
+ export async function createOutboxSidecarFromEnvironment(
359
+ environment: NodeJS.ProcessEnv = process.env,
360
+ ): Promise<Readonly<{ service: EditableArtifactOutboxService; httpPort: number }> | null> {
361
+ const sidecar = readEditableArtifactOutboxSidecarEnvironment(environment);
362
+ if (!sidecar) return null;
363
+ const settings = getSettings();
364
+ const controlPlaneAuth = resolveNatsControlPlaneAuth(settings);
365
+ const natsAuth: EditableArtifactHintNatsAuth = controlPlaneAuth
366
+ ? {
367
+ kind: "user-password",
368
+ user: controlPlaneAuth.user,
369
+ pass: controlPlaneAuth.password,
370
+ }
371
+ : { kind: "anonymous" };
372
+ const service = await createProductionEditableArtifactOutboxService({
373
+ settings,
374
+ databaseUrl: sidecar.databaseUrl,
375
+ declaredDatabaseRole: sidecar.declaredDatabaseRole,
376
+ natsUrl: settings.natsUrl,
377
+ natsAuth,
378
+ owner: sidecar.owner,
379
+ databasePoolSize: sidecar.databasePoolSize,
380
+ batchSize: sidecar.batchSize,
381
+ concurrency: sidecar.concurrency,
382
+ leaseDurationMs: sidecar.leaseDurationMs,
383
+ leaseRenewIntervalMs: sidecar.leaseRenewIntervalMs,
384
+ pollIntervalMs: sidecar.pollIntervalMs,
385
+ publishTimeoutMs: sidecar.publishTimeoutMs,
386
+ retryBaseMs: sidecar.retryBaseMs,
387
+ retryMaxMs: sidecar.retryMaxMs,
388
+ });
389
+ return Object.freeze({ service, httpPort: sidecar.httpPort });
390
+ }
391
+
392
+ async function withTimeout<T>(
393
+ promise: Promise<T>,
394
+ milliseconds: number,
395
+ abort: AbortController,
396
+ ): Promise<T> {
397
+ let timer: ReturnType<typeof setTimeout> | undefined;
398
+ try {
399
+ return await Promise.race([
400
+ promise,
401
+ new Promise<never>((_resolve, reject) => {
402
+ timer = setTimeout(() => {
403
+ abort.abort();
404
+ reject(new Error("readiness check timed out"));
405
+ }, milliseconds);
406
+ }),
407
+ ]);
408
+ } finally {
409
+ if (timer) clearTimeout(timer);
410
+ }
411
+ }
412
+
413
+ function required(environment: NodeJS.ProcessEnv, name: string): string {
414
+ const value = environment[name]?.trim();
415
+ if (!value) throw new Error(`${name} is required when artifact outbox dispatch is enabled`);
416
+ return value;
417
+ }
418
+
419
+ function integer(
420
+ environment: NodeJS.ProcessEnv,
421
+ name: string,
422
+ fallback: number,
423
+ minimum: number,
424
+ maximum: number,
425
+ ): number {
426
+ const raw = environment[name];
427
+ const value = raw === undefined ? fallback : Number(raw);
428
+ if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
429
+ throw new Error(`${name} is outside its allowed range`);
430
+ }
431
+ return value;
432
+ }
433
+
434
+ // Compile-time assurance that production composition satisfies the service port.
435
+ const _runtimePort: EditableArtifactOutboxRuntimePort | undefined = undefined as
436
+ | EditableArtifactOutboxWorkerRuntime
437
+ | undefined;
438
+ void _runtimePort;