@getstrata/core 3.1.5 → 3.1.7

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 CHANGED
@@ -1,5 +1,13 @@
1
1
  # @getstrata/core changelog
2
2
 
3
+ ## 3.1.7
4
+
5
+ Fix graceful shutdown for admitted queue jobs
6
+
7
+ ## 3.1.6
8
+
9
+ fix: drain admitted request bookkeeping during shutdown
10
+
3
11
  ## 3.1.5
4
12
 
5
13
  Fix published class-model type exports so inferred fields and strict model/repository contracts remain intact in installed applications.
@@ -114,6 +114,9 @@ type ExecutionEnvelope = ExecutionEnvelopeFields & ({
114
114
  readonly kind: "job";
115
115
  readonly actor: ExecutionActor;
116
116
  });
117
+ interface ExecutionOptions {
118
+ readonly drainOnStop?: boolean;
119
+ }
117
120
  type ExecutionContext = ExecutionEnvelope & {
118
121
  readonly applicationId: string;
119
122
  readonly executionId: string;
@@ -152,6 +155,6 @@ interface Application {
152
155
  /** Stable, never rejecting; remains pending while owned operations are actually still running. */
153
156
  readonly completion: Promise<CompletionResult>;
154
157
  run<T>(work: (scope: CommandScope) => T | Promise<T>): Promise<T>;
155
- run<T>(envelope: ExecutionEnvelope, work: (scope: CommandScope) => T | Promise<T>): Promise<T>;
158
+ run<T>(envelope: ExecutionEnvelope, work: (scope: CommandScope) => T | Promise<T>, options?: ExecutionOptions): Promise<T>;
156
159
  }
157
- export type { Application, ApplicationConfig, ApplicationConfigValue, ApplicationDefinition, ApplicationDiagnostic, ApplicationPhase, ApplicationSnapshot, BootDisposition, CleanupContext, CleanupDisposition, CommandScope, CompletionResult, ExecutionActor, ExecutionContext, ExecutionEnvelope, ExecutionTaskOutcome, OpenOutcome, ProviderDefinition, ProviderScope, ResourcePhase, ResourceSpec, StopResult, TransportDefinition, };
160
+ export type { Application, ApplicationConfig, ApplicationConfigValue, ApplicationDefinition, ApplicationDiagnostic, ApplicationPhase, ApplicationSnapshot, BootDisposition, CleanupContext, CleanupDisposition, CommandScope, CompletionResult, ExecutionActor, ExecutionContext, ExecutionEnvelope, ExecutionOptions, ExecutionTaskOutcome, OpenOutcome, ProviderDefinition, ProviderScope, ResourcePhase, ResourceSpec, StopResult, TransportDefinition, };
@@ -1,11 +1,11 @@
1
1
  import type { DatabaseSession, TransactionSession } from "../database/session";
2
- import type { ExecutionEnvelope } from "./application";
2
+ import type { ExecutionEnvelope, ExecutionOptions } from "./application";
3
3
  export type SelectedSession = DatabaseSession | TransactionSession;
4
4
  export interface ExecutionPersistence {
5
5
  readonly database: DatabaseSession;
6
6
  readonly policy: ScopedPolicy;
7
7
  }
8
- export type PersistenceInvocation = <T>(envelope: ExecutionEnvelope, work: (ports: ExecutionPersistence) => T | Promise<T>) => Promise<T>;
8
+ export type PersistenceInvocation = <T>(envelope: ExecutionEnvelope, work: (ports: ExecutionPersistence) => T | Promise<T>, options?: ExecutionOptions) => Promise<T>;
9
9
  export type EstablishedDatabasePolicy = Readonly<{
10
10
  kind: "tenant";
11
11
  tenantId: number;
@@ -1,5 +1,5 @@
1
1
  import { type QueueHandoff } from "@getstrata/core/queue/queueHandoff";
2
- import type { ExecutionEnvelope } from "../contracts/application";
2
+ import type { ExecutionEnvelope, ExecutionOptions } from "../contracts/application";
3
3
  import type { DatabaseSession } from "../database/session";
4
4
  import type FailedJobService from "./failedJobService";
5
5
  import type { JobContext } from "./index";
@@ -8,7 +8,7 @@ import type { QueueJobEnvelope } from "./jobRunner";
8
8
  type QueueInvocation = <T>(envelope: ExecutionEnvelope, work: (ports: {
9
9
  readonly database: DatabaseSession;
10
10
  readonly policy?: import("../contracts/persistence").ScopedPolicy;
11
- }) => T | Promise<T>) => Promise<T>;
11
+ }) => T | Promise<T>, options?: ExecutionOptions) => Promise<T>;
12
12
  type FailureInput = Parameters<FailedJobService["recordFailure"]>[0];
13
13
  interface QueueServices extends Pick<FailedJobService, "recordFailure" | "listRecent" | "retry" | "delete" | "flush"> {
14
14
  runAttempt(envelope: QueueJobEnvelope, context: JobContext, work: (context: JobContext) => Promise<void>): Promise<void>;
@@ -1,9 +1,11 @@
1
1
  import type { ExecutionContext, ExecutionEnvelope } from "../contracts/application";
2
+ declare function readDrainOnStop(options: unknown): boolean;
2
3
  /** Validation and copying perform no timer, listener, container or factory effects. */
3
4
  declare function normalizeExecutionEnvelope(input: unknown): ExecutionEnvelope;
4
5
  declare function ownExecutionContext(envelope: ExecutionEnvelope, applicationId: string, appSignal: AbortSignal): {
5
6
  context: ExecutionContext;
6
7
  dispose: () => void;
7
8
  check: () => void;
9
+ admit(drainSignal: AbortSignal): void;
8
10
  };
9
- export { normalizeExecutionEnvelope, ownExecutionContext };
11
+ export { normalizeExecutionEnvelope, ownExecutionContext, readDrainOnStop };
@@ -317,7 +317,7 @@ function createQueueServices(config) {
317
317
  policy,
318
318
  actor: envelope.actor,
319
319
  tenant: envelope.tenant
320
- }));
320
+ }), { drainOnStop: true });
321
321
  }
322
322
  });
323
323
  }
@@ -314,7 +314,7 @@ function createQueueServices(config) {
314
314
  policy,
315
315
  actor: envelope.actor,
316
316
  tenant: envelope.tenant
317
- }));
317
+ }), { drainOnStop: true });
318
318
  }
319
319
  });
320
320
  }
@@ -92,6 +92,14 @@ function record(input, keys) {
92
92
  }
93
93
  return result;
94
94
  }
95
+ function readDrainOnStop(options) {
96
+ if (options === undefined)
97
+ return false;
98
+ const { drainOnStop } = record(options, ["drainOnStop"]);
99
+ if (drainOnStop !== undefined && typeof drainOnStop !== "boolean")
100
+ throw new TypeError("Execution drainOnStop must be boolean.");
101
+ return drainOnStop === true;
102
+ }
95
103
  function metadata(value) {
96
104
  if (value === null || typeof value !== "object" || Array.isArray(value)) {
97
105
  throw new TypeError("Execution metadata must be a plain record.");
@@ -178,8 +186,10 @@ function ownExecutionContext(envelope, applicationId, appSignal) {
178
186
  const subscribe = (signal) => {
179
187
  const listener = () => cancel(signal);
180
188
  addListener.call(signal, "abort", listener);
181
- subscriptions.push({ signal, listener });
189
+ const subscription = { signal, listener };
190
+ subscriptions.push(subscription);
182
191
  cancel(signal);
192
+ return subscription;
183
193
  };
184
194
  const dispose = () => {
185
195
  disposed = true;
@@ -191,7 +201,7 @@ function ownExecutionContext(envelope, applicationId, appSignal) {
191
201
  try {
192
202
  if (envelope.signal !== undefined)
193
203
  subscribe(envelope.signal);
194
- subscribe(appSignal);
204
+ const admission = subscribe(appSignal);
195
205
  const deadline = envelope.deadlineAtMs;
196
206
  const refreshDeadline = () => {
197
207
  if (disposed || controller.signal.aborted || deadline === undefined)
@@ -222,7 +232,18 @@ function ownExecutionContext(envelope, applicationId, appSignal) {
222
232
  executionId,
223
233
  signal: controller.signal
224
234
  });
225
- return { context, dispose, check };
235
+ return {
236
+ context,
237
+ dispose,
238
+ check,
239
+ admit(drainSignal) {
240
+ check();
241
+ subscribe(drainSignal);
242
+ check();
243
+ removeListener.call(admission.signal, "abort", admission.listener);
244
+ subscriptions.splice(subscriptions.indexOf(admission), 1);
245
+ }
246
+ };
226
247
  } catch (error) {
227
248
  dispose();
228
249
  throw error;
@@ -80,7 +80,7 @@ function createQueueServices(config) {
80
80
  policy,
81
81
  actor: envelope.actor,
82
82
  tenant: envelope.tenant
83
- }));
83
+ }), { drainOnStop: true });
84
84
  }
85
85
  });
86
86
  }
@@ -314,7 +314,7 @@ function createQueueServices(config) {
314
314
  policy,
315
315
  actor: envelope.actor,
316
316
  tenant: envelope.tenant
317
- }));
317
+ }), { drainOnStop: true });
318
318
  }
319
319
  });
320
320
  }
@@ -101,6 +101,14 @@ function record(input, keys) {
101
101
  }
102
102
  return result;
103
103
  }
104
+ function readDrainOnStop(options) {
105
+ if (options === undefined)
106
+ return false;
107
+ const { drainOnStop } = record(options, ["drainOnStop"]);
108
+ if (drainOnStop !== undefined && typeof drainOnStop !== "boolean")
109
+ throw new TypeError("Execution drainOnStop must be boolean.");
110
+ return drainOnStop === true;
111
+ }
104
112
  function metadata(value) {
105
113
  if (value === null || typeof value !== "object" || Array.isArray(value)) {
106
114
  throw new TypeError("Execution metadata must be a plain record.");
@@ -187,8 +195,10 @@ function ownExecutionContext(envelope, applicationId, appSignal) {
187
195
  const subscribe = (signal) => {
188
196
  const listener = () => cancel(signal);
189
197
  addListener.call(signal, "abort", listener);
190
- subscriptions.push({ signal, listener });
198
+ const subscription = { signal, listener };
199
+ subscriptions.push(subscription);
191
200
  cancel(signal);
201
+ return subscription;
192
202
  };
193
203
  const dispose = () => {
194
204
  disposed = true;
@@ -200,7 +210,7 @@ function ownExecutionContext(envelope, applicationId, appSignal) {
200
210
  try {
201
211
  if (envelope.signal !== undefined)
202
212
  subscribe(envelope.signal);
203
- subscribe(appSignal);
213
+ const admission = subscribe(appSignal);
204
214
  const deadline = envelope.deadlineAtMs;
205
215
  const refreshDeadline = () => {
206
216
  if (disposed || controller.signal.aborted || deadline === undefined)
@@ -231,7 +241,18 @@ function ownExecutionContext(envelope, applicationId, appSignal) {
231
241
  executionId,
232
242
  signal: controller.signal
233
243
  });
234
- return { context, dispose, check };
244
+ return {
245
+ context,
246
+ dispose,
247
+ check,
248
+ admit(drainSignal) {
249
+ check();
250
+ subscribe(drainSignal);
251
+ check();
252
+ removeListener.call(admission.signal, "abort", admission.listener);
253
+ subscriptions.splice(subscriptions.indexOf(admission), 1);
254
+ }
255
+ };
235
256
  } catch (error) {
236
257
  dispose();
237
258
  throw error;
@@ -1219,19 +1240,21 @@ class OwnedApplication {
1219
1240
  stop(options = {}) {
1220
1241
  return this.taskStorage.run(undefined, () => this.beginStop(options.reason ?? "shutdown", this.definition.shutdownTimeoutMs));
1221
1242
  }
1222
- run(input, callback) {
1243
+ run(input, callback, options) {
1223
1244
  return this.taskStorage.run(undefined, () => {
1224
1245
  if (this.phase !== "ready") {
1225
1246
  return observed2(Promise.reject(new ApplicationStateError("APPLICATION_NOT_READY", this.id)));
1226
1247
  }
1227
1248
  let envelope;
1228
1249
  let work;
1250
+ let drainOnStop;
1229
1251
  try {
1230
1252
  const candidate = typeof input === "function" && callback === undefined ? input : callback;
1231
1253
  if (typeof candidate !== "function")
1232
1254
  throw new TypeError("Execution callback must be a function.");
1233
1255
  work = candidate;
1234
1256
  envelope = normalizeExecutionEnvelope(typeof input === "function" && callback === undefined ? { kind: "command" } : input);
1257
+ drainOnStop = readDrainOnStop(options) || envelope.kind === "request";
1235
1258
  if (this.phase !== "ready" || this.cancellation.signal.aborted) {
1236
1259
  throw new ApplicationStateError("APPLICATION_NOT_READY", this.id);
1237
1260
  }
@@ -1242,11 +1265,11 @@ class OwnedApplication {
1242
1265
  observed2(result.promise);
1243
1266
  this.commands.add(result.promise);
1244
1267
  result.promise.then(() => this.commandSettled(result.promise), () => this.commandSettled(result.promise));
1245
- this.execute(envelope, work).then(result.resolve, result.reject);
1268
+ this.execute(envelope, work, drainOnStop).then(result.resolve, result.reject);
1246
1269
  return result.promise;
1247
1270
  });
1248
1271
  }
1249
- async execute(envelope, work) {
1272
+ async execute(envelope, work, drainOnStop) {
1250
1273
  const owner = ownExecutionContext(envelope, this.id, this.cancellation.signal);
1251
1274
  try {
1252
1275
  const { context } = owner;
@@ -1319,7 +1342,11 @@ class OwnedApplication {
1319
1342
  finalize: () => this.taskStorage.run(undefined, () => this.journal.finalizeGroup(group, cleanupContext))
1320
1343
  });
1321
1344
  };
1322
- const callbacks = initialization.ok ? await settleExecutionTasks(work, owner.check, (body, spawn, resources, dispatch) => {
1345
+ const callbacks = initialization.ok ? await settleExecutionTasks((scope) => {
1346
+ if (drainOnStop)
1347
+ owner.admit(this.cleanupCancellation.signal);
1348
+ return work(scope);
1349
+ }, owner.check, (body, spawn, resources, dispatch) => {
1323
1350
  const lease = { active: true };
1324
1351
  const frame = Object.freeze({
1325
1352
  application: this,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@getstrata/core",
3
- "version": "3.1.5",
3
+ "version": "3.1.7",
4
4
  "description": "Laravel-inspired framework for Bun and TypeScript: models, authentication, queues, mail, and storage.",
5
5
  "type": "module",
6
6
  "license": "MIT",