@webiny/background-tasks-standalone 0.0.0-unstable.33e4fd9647

package/BackgroundTasksStandaloneFeature.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Background tasks for the standalone server. Register at the root container: the loop is one
+ * long-lived object for the whole process, and it needs the root's `EventDispatcher`.
+ */
+export declare const BackgroundTasksStandaloneFeature: {
+    name: string;
+    register(container: import("@webiny/di").Container): void;
+};

package/BackgroundTasksStandaloneFeature.js

@@ -0,0 +1,27 @@
+import { createFeature } from "@webiny/feature/api";
+import { BackgroundTaskEventType } from "@webiny/event-handler-core";
+import { InProcessBackgroundTasksLoop } from "./loop/InProcessBackgroundTasksLoop.js";
+import { InProcessTaskService } from "./service/InProcessTaskService.js";
+import { InProcessBackgroundTaskHandler } from "./handlers/InProcessBackgroundTaskHandler.js";
+import { KeyValueTaskClaim } from "./claim/KeyValueTaskClaim.js";
+import { KeyValueTaskRecoveries } from "./claim/KeyValueTaskRecoveries.js";
+import { TaskRecoverEventType } from "./recovery/TaskRecoverEventType.js";
+import { RecoverTasksHandler } from "./recovery/RecoverTasksHandler.js";
+import { ProcessShutdownSignal } from "./shutdown/ProcessShutdownSignal.js";
+const BackgroundTasksStandaloneFeature = createFeature({
+    name: "BackgroundTasksServer",
+    register (container) {
+        container.register(BackgroundTaskEventType);
+        container.register(InProcessBackgroundTaskHandler);
+        container.register(InProcessBackgroundTasksLoop).inSingletonScope();
+        container.register(InProcessTaskService);
+        container.register(ProcessShutdownSignal).inSingletonScope();
+        container.register(KeyValueTaskClaim);
+        container.register(KeyValueTaskRecoveries);
+        container.register(TaskRecoverEventType);
+        container.register(RecoverTasksHandler);
+    }
+});
+export { BackgroundTasksStandaloneFeature };
+
+//# sourceMappingURL=BackgroundTasksStandaloneFeature.js.map

package/BackgroundTasksStandaloneFeature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BackgroundTasksStandaloneFeature.js","sources":["../src/BackgroundTasksStandaloneFeature.ts"],"sourcesContent":["import { createFeature } from \"@webiny/feature/api\";\nimport { BackgroundTaskEventType } from \"@webiny/event-handler-core\";\nimport { InProcessBackgroundTasksLoop } from \"~/loop/InProcessBackgroundTasksLoop.js\";\nimport { InProcessTaskService } from \"~/service/InProcessTaskService.js\";\nimport { InProcessBackgroundTaskHandler } from \"~/handlers/InProcessBackgroundTaskHandler.js\";\nimport { KeyValueTaskClaim } from \"~/claim/KeyValueTaskClaim.js\";\nimport { KeyValueTaskRecoveries } from \"~/claim/KeyValueTaskRecoveries.js\";\nimport { TaskRecoverEventType } from \"~/recovery/TaskRecoverEventType.js\";\nimport { RecoverTasksHandler } from \"~/recovery/RecoverTasksHandler.js\";\nimport { ProcessShutdownSignal } from \"~/shutdown/ProcessShutdownSignal.js\";\n\n/**\n * Background tasks for the standalone server. Register at the root container: the loop is one\n * long-lived object for the whole process, and it needs the root's `EventDispatcher`.\n */\nexport const BackgroundTasksStandaloneFeature = createFeature({\n    name: \"BackgroundTasksServer\",\n    register(container) {\n        container.register(BackgroundTaskEventType);\n        container.register(InProcessBackgroundTaskHandler);\n        container.register(InProcessBackgroundTasksLoop).inSingletonScope();\n        container.register(InProcessTaskService);\n\n        /*\n         * One shutdown signal for the life of the process, shared by every request. The claims also\n         * need the process's `ProcessOwner`, which the server registers once for every feature.\n         */\n        container.register(ProcessShutdownSignal).inSingletonScope();\n        container.register(KeyValueTaskClaim);\n        container.register(KeyValueTaskRecoveries);\n\n        container.register(TaskRecoverEventType);\n        container.register(RecoverTasksHandler);\n    }\n});\n"],"names":["BackgroundTasksStandaloneFeature","createFeature","container","BackgroundTaskEventType","InProcessBackgroundTaskHandler","InProcessBackgroundTasksLoop","InProcessTaskService","ProcessShutdownSignal","KeyValueTaskClaim","KeyValueTaskRecoveries","TaskRecoverEventType","RecoverTasksHandler"],"mappings":";;;;;;;;;;AAeO,MAAMA,mCAAmCC,cAAc;IAC1D,MAAM;IACN,UAASC,SAAS;QACdA,UAAU,QAAQ,CAACC;QACnBD,UAAU,QAAQ,CAACE;QACnBF,UAAU,QAAQ,CAACG,8BAA8B,gBAAgB;QACjEH,UAAU,QAAQ,CAACI;QAMnBJ,UAAU,QAAQ,CAACK,uBAAuB,gBAAgB;QAC1DL,UAAU,QAAQ,CAACM;QACnBN,UAAU,QAAQ,CAACO;QAEnBP,UAAU,QAAQ,CAACQ;QACnBR,UAAU,QAAQ,CAACS;IACvB;AACJ"}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Webiny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# @webiny/background-tasks-standalone
+
+> [!NOTE]
+> This package is part of the [Webiny](https://www.webiny.com) monorepo.
+> It’s **included in every Webiny project by default** and is not meant to be used as a standalone package.
+
+📘 **Documentation:** [https://www.webiny.com/docs](https://www.webiny.com/docs)
+
+---
+
+_This README file is automatically generated during the publish process._

package/claim/ClaimRenewal.d.ts

@@ -0,0 +1,22 @@
+import type { TaskClaim } from "../domain/TaskClaim.js";
+interface IClaimRenewalParams {
+    claim: TaskClaim.Interface;
+    target: TaskClaim.Target;
+    onLost: () => void;
+    onError: (error: unknown) => void;
+}
+/**
+ * Keeps extending a claim while one iteration of its task runs, since an iteration can run far longer
+ * than the claim lasts. Started before the iteration and stopped after it.
+ */
+export declare class ClaimRenewal {
+    private readonly params;
+    private interval;
+    private lost;
+    constructor(params: IClaimRenewalParams);
+    isLost(): boolean;
+    start(): void;
+    stop(): void;
+    private renew;
+}
+export {};

package/claim/ClaimRenewal.js

@@ -0,0 +1,36 @@
+import { CLAIM_RENEW_EVERY_MS, CLAIM_TTL_MS } from "./constants.js";
+class ClaimRenewal {
+    constructor(params){
+        this.lost = false;
+        this.params = params;
+    }
+    isLost() {
+        return this.lost;
+    }
+    start() {
+        this.interval = setInterval(()=>{
+            this.renew();
+        }, CLAIM_RENEW_EVERY_MS);
+    }
+    stop() {
+        clearInterval(this.interval);
+        this.interval = void 0;
+    }
+    async renew() {
+        if (this.lost) return;
+        let held;
+        try {
+            held = await this.params.claim.keep(this.params.target, CLAIM_TTL_MS);
+        } catch (error) {
+            this.params.onError(error);
+            return;
+        }
+        if (held) return;
+        this.lost = true;
+        this.stop();
+        this.params.onLost();
+    }
+}
+export { ClaimRenewal };
+
+//# sourceMappingURL=ClaimRenewal.js.map

package/claim/ClaimRenewal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim/ClaimRenewal.js","sources":["../../src/claim/ClaimRenewal.ts"],"sourcesContent":["import type { TaskClaim } from \"~/domain/TaskClaim.js\";\nimport { CLAIM_RENEW_EVERY_MS } from \"./constants.js\";\nimport { CLAIM_TTL_MS } from \"./constants.js\";\n\ninterface IClaimRenewalParams {\n    claim: TaskClaim.Interface;\n    target: TaskClaim.Target;\n    // Called once, when an extension finds that this process no longer holds the claim.\n    onLost: () => void;\n    // Called for an extension that could not be written. The next one tries again.\n    onError: (error: unknown) => void;\n}\n\n/**\n * Keeps extending a claim while one iteration of its task runs, since an iteration can run far longer\n * than the claim lasts. Started before the iteration and stopped after it.\n */\nexport class ClaimRenewal {\n    private readonly params: IClaimRenewalParams;\n    private interval: ReturnType<typeof setInterval> | undefined;\n    private lost = false;\n\n    public constructor(params: IClaimRenewalParams) {\n        this.params = params;\n    }\n\n    public isLost(): boolean {\n        return this.lost;\n    }\n\n    public start(): void {\n        this.interval = setInterval(() => {\n            void this.renew();\n        }, CLAIM_RENEW_EVERY_MS);\n    }\n\n    public stop(): void {\n        clearInterval(this.interval);\n        this.interval = undefined;\n    }\n\n    /*\n     * Only an answer of `false` loses the claim. A write that fails is retried on the next tick: one\n     * slow or failed write leaves the claim with most of its time, and if they keep failing until it\n     * runs out, the next write that gets through answers `false`.\n     */\n    private async renew(): Promise<void> {\n        if (this.lost) {\n            return;\n        }\n        let held: boolean;\n        try {\n            held = await this.params.claim.keep(this.params.target, CLAIM_TTL_MS);\n        } catch (error) {\n            this.params.onError(error);\n            return;\n        }\n        if (held) {\n            return;\n        }\n        this.lost = true;\n        this.stop();\n        this.params.onLost();\n    }\n}\n"],"names":["ClaimRenewal","params","setInterval","CLAIM_RENEW_EVERY_MS","clearInterval","undefined","held","CLAIM_TTL_MS","error"],"mappings":";AAiBO,MAAMA;IAKT,YAAmBC,MAA2B,CAAE;aAFxC,IAAI,GAAG;QAGX,IAAI,CAAC,MAAM,GAAGA;IAClB;IAEO,SAAkB;QACrB,OAAO,IAAI,CAAC,IAAI;IACpB;IAEO,QAAc;QACjB,IAAI,CAAC,QAAQ,GAAGC,YAAY;YACnB,IAAI,CAAC,KAAK;QACnB,GAAGC;IACP;IAEO,OAAa;QAChBC,cAAc,IAAI,CAAC,QAAQ;QAC3B,IAAI,CAAC,QAAQ,GAAGC;IACpB;IAOA,MAAc,QAAuB;QACjC,IAAI,IAAI,CAAC,IAAI,EACT;QAEJ,IAAIC;QACJ,IAAI;YACAA,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAEC;QAC5D,EAAE,OAAOC,OAAO;YACZ,IAAI,CAAC,MAAM,CAAC,OAAO,CAACA;YACpB;QACJ;QACA,IAAIF,MACA;QAEJ,IAAI,CAAC,IAAI,GAAG;QACZ,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,MAAM,CAAC,MAAM;IACtB;AACJ"}

package/claim/KeyValueTaskClaim.d.ts

@@ -0,0 +1,19 @@
+import { GlobalKeyValueStore } from "@webiny/api-core/features/keyValueStore/index.js";
+import { TaskClaim } from "../domain/TaskClaim.js";
+import { ProcessOwner } from "@webiny/event-handler-standalone";
+/**
+ * A claim is a global key-value record whose value is the owning process. The store's conditional
+ * writes do the checking, so two processes racing for a task cannot both get it.
+ */
+declare class KeyValueTaskClaimImpl implements TaskClaim.Interface {
+    private readonly store;
+    private readonly owner;
+    constructor(store: GlobalKeyValueStore.Interface, owner: ProcessOwner.Interface);
+    take(target: TaskClaim.Target, ttlMs: number): Promise<boolean>;
+    keep(target: TaskClaim.Target, ttlMs: number): Promise<boolean>;
+    release(target: TaskClaim.Target): Promise<void>;
+}
+export declare const KeyValueTaskClaim: typeof KeyValueTaskClaimImpl & {
+    __abstraction: import("@webiny/di").Abstraction<import("~/domain/TaskClaim.js").ITaskClaim>;
+};
+export {};

package/claim/KeyValueTaskClaim.js

@@ -0,0 +1,64 @@
+import { GlobalKeyValueStore, KeyValueConditionFailedError } from "@webiny/api-core/features/keyValueStore/index.js";
+import { TaskClaim } from "../domain/TaskClaim.js";
+import { ProcessOwner } from "@webiny/event-handler-standalone";
+const CLAIM_SCOPE = "background-tasks/claims";
+const toKey = (target)=>`${target.tenant}/${target.taskId}`;
+const expiresIn = (ttlMs)=>{
+    const expiresAtMs = Date.now() + ttlMs;
+    return new Date(expiresAtMs);
+};
+const toHeld = (result)=>{
+    if (result.isOk()) return true;
+    if (result.error instanceof KeyValueConditionFailedError) return false;
+    throw result.error;
+};
+class KeyValueTaskClaimImpl {
+    constructor(store, owner){
+        this.store = store;
+        this.owner = owner;
+    }
+    async take(target, ttlMs) {
+        const key = toKey(target);
+        const expiresAt = expiresIn(ttlMs);
+        const result = await this.store.set(key, this.owner.id, {
+            scope: CLAIM_SCOPE,
+            expiresAt,
+            condition: {
+                exists: false
+            }
+        });
+        return toHeld(result);
+    }
+    async keep(target, ttlMs) {
+        const key = toKey(target);
+        const expiresAt = expiresIn(ttlMs);
+        const result = await this.store.set(key, this.owner.id, {
+            scope: CLAIM_SCOPE,
+            expiresAt,
+            condition: {
+                equals: this.owner.id
+            }
+        });
+        return toHeld(result);
+    }
+    async release(target) {
+        const key = toKey(target);
+        const result = await this.store.delete(key, {
+            scope: CLAIM_SCOPE,
+            condition: {
+                equals: this.owner.id
+            }
+        });
+        toHeld(result);
+    }
+}
+const KeyValueTaskClaim = TaskClaim.createImplementation({
+    implementation: KeyValueTaskClaimImpl,
+    dependencies: [
+        GlobalKeyValueStore,
+        ProcessOwner
+    ]
+});
+export { KeyValueTaskClaim };
+
+//# sourceMappingURL=KeyValueTaskClaim.js.map

package/claim/KeyValueTaskClaim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim/KeyValueTaskClaim.js","sources":["../../src/claim/KeyValueTaskClaim.ts"],"sourcesContent":["import type { Result } from \"@webiny/feature/api\";\nimport { GlobalKeyValueStore } from \"@webiny/api-core/features/keyValueStore/index.js\";\nimport { KeyValueConditionFailedError } from \"@webiny/api-core/features/keyValueStore/index.js\";\nimport { TaskClaim } from \"~/domain/TaskClaim.js\";\nimport { ProcessOwner } from \"@webiny/event-handler-standalone\";\n\n// Claims live apart from everyone's records, in their own scope of the global store.\nconst CLAIM_SCOPE = \"background-tasks/claims\";\n\nconst toKey = (target: TaskClaim.Target): string => {\n    return `${target.tenant}/${target.taskId}`;\n};\n\nconst expiresIn = (ttlMs: number): Date => {\n    const expiresAtMs = Date.now() + ttlMs;\n    return new Date(expiresAtMs);\n};\n\n/*\n * A write whose condition does not hold means someone else holds the claim. That is an answer, not\n * a failure, so it becomes `false`.\n */\nconst toHeld = (result: Result<void, GlobalKeyValueStore.Error>): boolean => {\n    if (result.isOk()) {\n        return true;\n    }\n    if (result.error instanceof KeyValueConditionFailedError) {\n        return false;\n    }\n    throw result.error;\n};\n\n/**\n * A claim is a global key-value record whose value is the owning process. The store's conditional\n * writes do the checking, so two processes racing for a task cannot both get it.\n */\nclass KeyValueTaskClaimImpl implements TaskClaim.Interface {\n    public constructor(\n        private readonly store: GlobalKeyValueStore.Interface,\n        private readonly owner: ProcessOwner.Interface\n    ) {}\n\n    public async take(target: TaskClaim.Target, ttlMs: number): Promise<boolean> {\n        const key = toKey(target);\n        const expiresAt = expiresIn(ttlMs);\n        const result = await this.store.set(key, this.owner.id, {\n            scope: CLAIM_SCOPE,\n            expiresAt,\n            condition: { exists: false }\n        });\n        return toHeld(result);\n    }\n\n    public async keep(target: TaskClaim.Target, ttlMs: number): Promise<boolean> {\n        const key = toKey(target);\n        const expiresAt = expiresIn(ttlMs);\n        const result = await this.store.set(key, this.owner.id, {\n            scope: CLAIM_SCOPE,\n            expiresAt,\n            condition: { equals: this.owner.id }\n        });\n        return toHeld(result);\n    }\n\n    public async release(target: TaskClaim.Target): Promise<void> {\n        const key = toKey(target);\n        const result = await this.store.delete(key, {\n            scope: CLAIM_SCOPE,\n            condition: { equals: this.owner.id }\n        });\n        // Already gone or held by someone else: either way, nothing of ours is left to release.\n        toHeld(result);\n    }\n}\n\nexport const KeyValueTaskClaim = TaskClaim.createImplementation({\n    implementation: KeyValueTaskClaimImpl,\n    dependencies: [GlobalKeyValueStore, ProcessOwner]\n});\n"],"names":["CLAIM_SCOPE","toKey","target","expiresIn","ttlMs","expiresAtMs","Date","toHeld","result","KeyValueConditionFailedError","KeyValueTaskClaimImpl","store","owner","key","expiresAt","KeyValueTaskClaim","TaskClaim","GlobalKeyValueStore","ProcessOwner"],"mappings":";;;AAOA,MAAMA,cAAc;AAEpB,MAAMC,QAAQ,CAACC,SACJ,GAAGA,OAAO,MAAM,CAAC,CAAC,EAAEA,OAAO,MAAM,EAAE;AAG9C,MAAMC,YAAY,CAACC;IACf,MAAMC,cAAcC,KAAK,GAAG,KAAKF;IACjC,OAAO,IAAIE,KAAKD;AACpB;AAMA,MAAME,SAAS,CAACC;IACZ,IAAIA,OAAO,IAAI,IACX,OAAO;IAEX,IAAIA,OAAO,KAAK,YAAYC,8BACxB,OAAO;IAEX,MAAMD,OAAO,KAAK;AACtB;AAMA,MAAME;IACF,YACqBC,KAAoC,EACpCC,KAA6B,CAChD;aAFmBD,KAAK,GAALA;aACAC,KAAK,GAALA;IAClB;IAEH,MAAa,KAAKV,MAAwB,EAAEE,KAAa,EAAoB;QACzE,MAAMS,MAAMZ,MAAMC;QAClB,MAAMY,YAAYX,UAAUC;QAC5B,MAAMI,SAAS,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAACK,KAAK,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE;YACpD,OAAOb;YACPc;YACA,WAAW;gBAAE,QAAQ;YAAM;QAC/B;QACA,OAAOP,OAAOC;IAClB;IAEA,MAAa,KAAKN,MAAwB,EAAEE,KAAa,EAAoB;QACzE,MAAMS,MAAMZ,MAAMC;QAClB,MAAMY,YAAYX,UAAUC;QAC5B,MAAMI,SAAS,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAACK,KAAK,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE;YACpD,OAAOb;YACPc;YACA,WAAW;gBAAE,QAAQ,IAAI,CAAC,KAAK,CAAC,EAAE;YAAC;QACvC;QACA,OAAOP,OAAOC;IAClB;IAEA,MAAa,QAAQN,MAAwB,EAAiB;QAC1D,MAAMW,MAAMZ,MAAMC;QAClB,MAAMM,SAAS,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAACK,KAAK;YACxC,OAAOb;YACP,WAAW;gBAAE,QAAQ,IAAI,CAAC,KAAK,CAAC,EAAE;YAAC;QACvC;QAEAO,OAAOC;IACX;AACJ;AAEO,MAAMO,oBAAoBC,UAAU,oBAAoB,CAAC;IAC5D,gBAAgBN;IAChB,cAAc;QAACO;QAAqBC;KAAa;AACrD"}

package/claim/KeyValueTaskRecoveries.d.ts

@@ -0,0 +1,16 @@
+import { GlobalKeyValueStore } from "@webiny/api-core/features/keyValueStore/index.js";
+import { TaskRecoveries } from "../domain/TaskRecoveries.js";
+import type { TaskClaim } from "../domain/TaskClaim.js";
+/**
+ * The count is read and written in two steps. That is safe only because the caller holds the
+ * task's claim, so no other process records a takeover of the same task in between.
+ */
+declare class KeyValueTaskRecoveriesImpl implements TaskRecoveries.Interface {
+    private readonly store;
+    constructor(store: GlobalKeyValueStore.Interface);
+    record(target: TaskClaim.Target, savedOn: string): Promise<number>;
+}
+export declare const KeyValueTaskRecoveries: typeof KeyValueTaskRecoveriesImpl & {
+    __abstraction: import("@webiny/di").Abstraction<import("~/domain/TaskRecoveries.js").ITaskRecoveries>;
+};
+export {};

package/claim/KeyValueTaskRecoveries.js

@@ -0,0 +1,40 @@
+import { GlobalKeyValueStore, KeyNotFoundError } from "@webiny/api-core/features/keyValueStore/index.js";
+import { TaskRecoveries } from "../domain/TaskRecoveries.js";
+const RECOVERIES_SCOPE = "background-tasks/recoveries";
+const RECOVERIES_TTL_MS = 86400000;
+const toKey = (target)=>`${target.tenant}/${target.taskId}`;
+class KeyValueTaskRecoveriesImpl {
+    constructor(store){
+        this.store = store;
+    }
+    async record(target, savedOn) {
+        const key = toKey(target);
+        const current = await this.store.get(key, {
+            scope: RECOVERIES_SCOPE
+        });
+        if (current.isFail() && !(current.error instanceof KeyNotFoundError)) throw current.error;
+        let count = 1;
+        if (current.isOk() && current.value.savedOn === savedOn) count = current.value.count + 1;
+        const record = {
+            count,
+            savedOn
+        };
+        const expiresAtMs = Date.now() + RECOVERIES_TTL_MS;
+        const expiresAt = new Date(expiresAtMs);
+        const written = await this.store.set(key, record, {
+            scope: RECOVERIES_SCOPE,
+            expiresAt
+        });
+        if (written.isFail()) throw written.error;
+        return count;
+    }
+}
+const KeyValueTaskRecoveries = TaskRecoveries.createImplementation({
+    implementation: KeyValueTaskRecoveriesImpl,
+    dependencies: [
+        GlobalKeyValueStore
+    ]
+});
+export { KeyValueTaskRecoveries };
+
+//# sourceMappingURL=KeyValueTaskRecoveries.js.map

package/claim/KeyValueTaskRecoveries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim/KeyValueTaskRecoveries.js","sources":["../../src/claim/KeyValueTaskRecoveries.ts"],"sourcesContent":["import { GlobalKeyValueStore } from \"@webiny/api-core/features/keyValueStore/index.js\";\nimport { KeyNotFoundError } from \"@webiny/api-core/features/keyValueStore/index.js\";\nimport { TaskRecoveries } from \"~/domain/TaskRecoveries.js\";\nimport type { TaskClaim } from \"~/domain/TaskClaim.js\";\n\nconst RECOVERIES_SCOPE = \"background-tasks/recoveries\";\n\n/*\n * Only clean-up: a crash loop repeats within minutes, and a task that saves starts the count over\n * anyway. A record nobody updates for a day is not worth keeping.\n */\nconst RECOVERIES_TTL_MS = 86_400_000;\n\ninterface IRecoveriesRecord {\n    count: number;\n    // When the task had last saved at the previous takeover.\n    savedOn: string;\n}\n\nconst toKey = (target: TaskClaim.Target): string => {\n    return `${target.tenant}/${target.taskId}`;\n};\n\n/**\n * The count is read and written in two steps. That is safe only because the caller holds the\n * task's claim, so no other process records a takeover of the same task in between.\n */\nclass KeyValueTaskRecoveriesImpl implements TaskRecoveries.Interface {\n    public constructor(private readonly store: GlobalKeyValueStore.Interface) {}\n\n    public async record(target: TaskClaim.Target, savedOn: string): Promise<number> {\n        const key = toKey(target);\n        const current = await this.store.get<IRecoveriesRecord>(key, { scope: RECOVERIES_SCOPE });\n        if (current.isFail() && !(current.error instanceof KeyNotFoundError)) {\n            throw current.error;\n        }\n\n        let count = 1;\n        if (current.isOk() && current.value.savedOn === savedOn) {\n            count = current.value.count + 1;\n        }\n\n        const record: IRecoveriesRecord = { count, savedOn };\n        const expiresAtMs = Date.now() + RECOVERIES_TTL_MS;\n        const expiresAt = new Date(expiresAtMs);\n        const written = await this.store.set(key, record, { scope: RECOVERIES_SCOPE, expiresAt });\n        if (written.isFail()) {\n            throw written.error;\n        }\n        return count;\n    }\n}\n\nexport const KeyValueTaskRecoveries = TaskRecoveries.createImplementation({\n    implementation: KeyValueTaskRecoveriesImpl,\n    dependencies: [GlobalKeyValueStore]\n});\n"],"names":["RECOVERIES_SCOPE","RECOVERIES_TTL_MS","toKey","target","KeyValueTaskRecoveriesImpl","store","savedOn","key","current","KeyNotFoundError","count","record","expiresAtMs","Date","expiresAt","written","KeyValueTaskRecoveries","TaskRecoveries","GlobalKeyValueStore"],"mappings":";;AAKA,MAAMA,mBAAmB;AAMzB,MAAMC,oBAAoB;AAQ1B,MAAMC,QAAQ,CAACC,SACJ,GAAGA,OAAO,MAAM,CAAC,CAAC,EAAEA,OAAO,MAAM,EAAE;AAO9C,MAAMC;IACF,YAAoCC,KAAoC,CAAE;aAAtCA,KAAK,GAALA;IAAuC;IAE3E,MAAa,OAAOF,MAAwB,EAAEG,OAAe,EAAmB;QAC5E,MAAMC,MAAML,MAAMC;QAClB,MAAMK,UAAU,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAoBD,KAAK;YAAE,OAAOP;QAAiB;QACvF,IAAIQ,QAAQ,MAAM,MAAM,CAAEA,CAAAA,QAAQ,KAAK,YAAYC,gBAAe,GAC9D,MAAMD,QAAQ,KAAK;QAGvB,IAAIE,QAAQ;QACZ,IAAIF,QAAQ,IAAI,MAAMA,QAAQ,KAAK,CAAC,OAAO,KAAKF,SAC5CI,QAAQF,QAAQ,KAAK,CAAC,KAAK,GAAG;QAGlC,MAAMG,SAA4B;YAAED;YAAOJ;QAAQ;QACnD,MAAMM,cAAcC,KAAK,GAAG,KAAKZ;QACjC,MAAMa,YAAY,IAAID,KAAKD;QAC3B,MAAMG,UAAU,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAACR,KAAKI,QAAQ;YAAE,OAAOX;YAAkBc;QAAU;QACvF,IAAIC,QAAQ,MAAM,IACd,MAAMA,QAAQ,KAAK;QAEvB,OAAOL;IACX;AACJ;AAEO,MAAMM,yBAAyBC,eAAe,oBAAoB,CAAC;IACtE,gBAAgBb;IAChB,cAAc;QAACc;KAAoB;AACvC"}

package/claim/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const CLAIM_TTL_MS = 60000;
+export declare const CLAIM_RENEW_EVERY_MS = 20000;
+export declare const RECOVER_EVERY_MS = 60000;
+export declare const RECOVER_GRACE_MS = 60000;
+export declare const MAX_RECOVERIES = 3;

package/claim/constants.js

@@ -0,0 +1,8 @@
+const CLAIM_TTL_MS = 60000;
+const CLAIM_RENEW_EVERY_MS = 20000;
+const RECOVER_EVERY_MS = 60000;
+const RECOVER_GRACE_MS = CLAIM_TTL_MS;
+const MAX_RECOVERIES = 3;
+export { CLAIM_RENEW_EVERY_MS, CLAIM_TTL_MS, MAX_RECOVERIES, RECOVER_EVERY_MS, RECOVER_GRACE_MS };
+
+//# sourceMappingURL=constants.js.map

package/claim/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim/constants.js","sources":["../../src/claim/constants.ts"],"sourcesContent":["/*\n * How long a claim lasts unless its owner extends it. A process that dies stops extending, so its\n * tasks can be taken over this long after its last extension. Shorter recovers sooner, but a process\n * that is alive and only slow (a busy event loop, a slow database) could lose a task it is running.\n */\nexport const CLAIM_TTL_MS = 60_000;\n\n// A third of the TTL, so one or two missed extensions do not lose the claim.\nexport const CLAIM_RENEW_EVERY_MS = 20_000;\n\n// How often each process looks for tasks that nobody holds.\nexport const RECOVER_EVERY_MS = 60_000;\n\n/*\n * A pending task saved this recently is left alone by recovery. It covers the moment between a\n * trigger creating a task and claiming it, when nobody holds it yet, and a claim the trigger could\n * not write, which the first iteration then takes.\n */\nexport const RECOVER_GRACE_MS = CLAIM_TTL_MS;\n\n/*\n * Takeovers of one task, with no save in between, before recovery fails it instead. A task that\n * crashes the process it runs in would otherwise be resumed on every start and take the server down\n * each time.\n */\nexport const MAX_RECOVERIES = 3;\n"],"names":["CLAIM_TTL_MS","CLAIM_RENEW_EVERY_MS","RECOVER_EVERY_MS","RECOVER_GRACE_MS","MAX_RECOVERIES"],"mappings":"AAKO,MAAMA,eAAe;AAGrB,MAAMC,uBAAuB;AAG7B,MAAMC,mBAAmB;AAOzB,MAAMC,mBAAmBH;AAOzB,MAAMI,iBAAiB"}

package/domain/BackgroundTasksLoop.d.ts

@@ -0,0 +1,31 @@
+import type { IBackgroundTaskEvent } from "@webiny/event-handler-core";
+/**
+ * Drives the background tasks of this process to completion. For each task it runs one iteration,
+ * waits as long as the iteration asks, and runs the next until the task stops asking to continue.
+ * The standalone counterpart of the Step Functions state machine that drives a task on AWS.
+ *
+ * `start` returns at once. The task runs after the request that triggered it has finished.
+ */
+export interface IBackgroundTasksLoop {
+    /** Ignored for a task already being driven, and once the process is shutting down. */
+    start(event: IBackgroundTaskEvent): void;
+    /**
+     * Stops driving tasks: running iterations are asked to save and hand their task back, and nothing
+     * new starts. Resolves once they have, or after `timeoutMs`, whichever comes first.
+     */
+    stop(timeoutMs: number): Promise<void>;
+}
+/**
+ * The status an iteration answers when another process holds the task's claim. That process drives
+ * the task, so driving it here stops without it being an error.
+ */
+export declare const CLAIMED_ELSEWHERE_STATUS = "claimed-elsewhere";
+/**
+ * The status an iteration answers when it stopped early because the process is shutting down. Its claim
+ * is released, so another process takes the task over at its next recovery sweep.
+ */
+export declare const HANDED_BACK_STATUS = "handed-back";
+export declare const BackgroundTasksLoop: import("@webiny/di").Abstraction<IBackgroundTasksLoop>;
+export declare namespace BackgroundTasksLoop {
+    type Interface = IBackgroundTasksLoop;
+}

package/domain/BackgroundTasksLoop.js

@@ -0,0 +1,7 @@
+import { createAbstraction } from "@webiny/feature/api";
+const CLAIMED_ELSEWHERE_STATUS = "claimed-elsewhere";
+const HANDED_BACK_STATUS = "handed-back";
+const BackgroundTasksLoop = createAbstraction("BackgroundTasks/BackgroundTasksLoop");
+export { BackgroundTasksLoop, CLAIMED_ELSEWHERE_STATUS, HANDED_BACK_STATUS };
+
+//# sourceMappingURL=BackgroundTasksLoop.js.map

package/domain/BackgroundTasksLoop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain/BackgroundTasksLoop.js","sources":["../../src/domain/BackgroundTasksLoop.ts"],"sourcesContent":["import { createAbstraction } from \"@webiny/feature/api\";\nimport type { IBackgroundTaskEvent } from \"@webiny/event-handler-core\";\n\n/**\n * Drives the background tasks of this process to completion. For each task it runs one iteration,\n * waits as long as the iteration asks, and runs the next until the task stops asking to continue.\n * The standalone counterpart of the Step Functions state machine that drives a task on AWS.\n *\n * `start` returns at once. The task runs after the request that triggered it has finished.\n */\nexport interface IBackgroundTasksLoop {\n    /** Ignored for a task already being driven, and once the process is shutting down. */\n    start(event: IBackgroundTaskEvent): void;\n    /**\n     * Stops driving tasks: running iterations are asked to save and hand their task back, and nothing\n     * new starts. Resolves once they have, or after `timeoutMs`, whichever comes first.\n     */\n    stop(timeoutMs: number): Promise<void>;\n}\n\n/**\n * The status an iteration answers when another process holds the task's claim. That process drives\n * the task, so driving it here stops without it being an error.\n */\nexport const CLAIMED_ELSEWHERE_STATUS = \"claimed-elsewhere\";\n\n/**\n * The status an iteration answers when it stopped early because the process is shutting down. Its claim\n * is released, so another process takes the task over at its next recovery sweep.\n */\nexport const HANDED_BACK_STATUS = \"handed-back\";\n\nexport const BackgroundTasksLoop = createAbstraction<IBackgroundTasksLoop>(\n    \"BackgroundTasks/BackgroundTasksLoop\"\n);\n\nexport namespace BackgroundTasksLoop {\n    export type Interface = IBackgroundTasksLoop;\n}\n"],"names":["CLAIMED_ELSEWHERE_STATUS","HANDED_BACK_STATUS","BackgroundTasksLoop","createAbstraction"],"mappings":";AAwBO,MAAMA,2BAA2B;AAMjC,MAAMC,qBAAqB;AAE3B,MAAMC,sBAAsBC,kBAC/B"}

package/domain/ShutdownSignal.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tells the task code that this process is shutting down, so it hands its work back instead of
+ * starting more. One for the whole process: the loop, the iterations and recovery all listen to the
+ * same one.
+ */
+export interface IShutdownSignal {
+    isShuttingDown(): boolean;
+    /** Calls `listener` once the shutdown begins. Returns a function that unsubscribes. */
+    onShutdown(listener: () => void): () => void;
+    /** Begins the shutdown. Calling it again does nothing. */
+    begin(): void;
+}
+export declare const ShutdownSignal: import("@webiny/di").Abstraction<IShutdownSignal>;
+export declare namespace ShutdownSignal {
+    type Interface = IShutdownSignal;
+}

package/domain/ShutdownSignal.js

@@ -0,0 +1,5 @@
+import { createAbstraction } from "@webiny/feature/api";
+const ShutdownSignal = createAbstraction("BackgroundTasks/ShutdownSignal");
+export { ShutdownSignal };
+
+//# sourceMappingURL=ShutdownSignal.js.map

package/domain/ShutdownSignal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain/ShutdownSignal.js","sources":["../../src/domain/ShutdownSignal.ts"],"sourcesContent":["import { createAbstraction } from \"@webiny/feature/api\";\n\n/**\n * Tells the task code that this process is shutting down, so it hands its work back instead of\n * starting more. One for the whole process: the loop, the iterations and recovery all listen to the\n * same one.\n */\nexport interface IShutdownSignal {\n    isShuttingDown(): boolean;\n    /** Calls `listener` once the shutdown begins. Returns a function that unsubscribes. */\n    onShutdown(listener: () => void): () => void;\n    /** Begins the shutdown. Calling it again does nothing. */\n    begin(): void;\n}\n\nexport const ShutdownSignal = createAbstraction<IShutdownSignal>(\"BackgroundTasks/ShutdownSignal\");\n\nexport namespace ShutdownSignal {\n    export type Interface = IShutdownSignal;\n}\n"],"names":["ShutdownSignal","createAbstraction"],"mappings":";AAeO,MAAMA,iBAAiBC,kBAAmC"}

package/domain/TaskClaim.d.ts

@@ -0,0 +1,25 @@
+export interface ITaskClaimTarget {
+    tenant: string;
+    taskId: string;
+}
+/**
+ * Which process runs a task. Every process can see every task, so before one runs a task it claims
+ * it, and only one claim can be held at a time. A claim expires unless its owner keeps extending it,
+ * which is how the tasks of a process that died become free again.
+ *
+ * Each method resolves to whether this process holds the claim afterwards. A storage failure
+ * rejects: the caller cannot tell whether it holds the claim, so it must not run the task.
+ */
+export interface ITaskClaim {
+    /** Claims the task when nobody holds it, an expired claim counting as nobody. */
+    take(target: ITaskClaimTarget, ttlMs: number): Promise<boolean>;
+    /** Extends a claim this process holds; `false` when it no longer does. */
+    keep(target: ITaskClaimTarget, ttlMs: number): Promise<boolean>;
+    /** Drops a claim this process holds, and leaves anyone else's alone. */
+    release(target: ITaskClaimTarget): Promise<void>;
+}
+export declare const TaskClaim: import("@webiny/di").Abstraction<ITaskClaim>;
+export declare namespace TaskClaim {
+    type Interface = ITaskClaim;
+    type Target = ITaskClaimTarget;
+}

package/domain/TaskClaim.js

@@ -0,0 +1,5 @@
+import { createAbstraction } from "@webiny/feature/api";
+const TaskClaim = createAbstraction("BackgroundTasks/TaskClaim");
+export { TaskClaim };
+
+//# sourceMappingURL=TaskClaim.js.map

package/domain/TaskClaim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain/TaskClaim.js","sources":["../../src/domain/TaskClaim.ts"],"sourcesContent":["import { createAbstraction } from \"@webiny/feature/api\";\n\nexport interface ITaskClaimTarget {\n    tenant: string;\n    taskId: string;\n}\n\n/**\n * Which process runs a task. Every process can see every task, so before one runs a task it claims\n * it, and only one claim can be held at a time. A claim expires unless its owner keeps extending it,\n * which is how the tasks of a process that died become free again.\n *\n * Each method resolves to whether this process holds the claim afterwards. A storage failure\n * rejects: the caller cannot tell whether it holds the claim, so it must not run the task.\n */\nexport interface ITaskClaim {\n    /** Claims the task when nobody holds it, an expired claim counting as nobody. */\n    take(target: ITaskClaimTarget, ttlMs: number): Promise<boolean>;\n    /** Extends a claim this process holds; `false` when it no longer does. */\n    keep(target: ITaskClaimTarget, ttlMs: number): Promise<boolean>;\n    /** Drops a claim this process holds, and leaves anyone else's alone. */\n    release(target: ITaskClaimTarget): Promise<void>;\n}\n\nexport const TaskClaim = createAbstraction<ITaskClaim>(\"BackgroundTasks/TaskClaim\");\n\nexport namespace TaskClaim {\n    export type Interface = ITaskClaim;\n    export type Target = ITaskClaimTarget;\n}\n"],"names":["TaskClaim","createAbstraction"],"mappings":";AAwBO,MAAMA,YAAYC,kBAA8B"}

package/domain/TaskRecoveries.d.ts

@@ -0,0 +1,18 @@
+import type { TaskClaim } from "./TaskClaim.js";
+/**
+ * Counts how often recovery has taken over a task without the task saving in between, so one that
+ * keeps dying with its process is failed instead of resumed forever. Only the holder of the task's
+ * claim records, so two processes never count the same takeover.
+ */
+export interface ITaskRecoveries {
+    /**
+     * Records one more takeover and resolves to the count, this one included. `savedOn` is when the
+     * task last saved: when it differs from the previous takeover's, the task made progress and the
+     * count starts over at 1.
+     */
+    record(target: TaskClaim.Target, savedOn: string): Promise<number>;
+}
+export declare const TaskRecoveries: import("@webiny/di").Abstraction<ITaskRecoveries>;
+export declare namespace TaskRecoveries {
+    type Interface = ITaskRecoveries;
+}

package/domain/TaskRecoveries.js

@@ -0,0 +1,5 @@
+import { createAbstraction } from "@webiny/feature/api";
+const TaskRecoveries = createAbstraction("BackgroundTasks/TaskRecoveries");
+export { TaskRecoveries };
+
+//# sourceMappingURL=TaskRecoveries.js.map

package/domain/TaskRecoveries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain/TaskRecoveries.js","sources":["../../src/domain/TaskRecoveries.ts"],"sourcesContent":["import { createAbstraction } from \"@webiny/feature/api\";\nimport type { TaskClaim } from \"./TaskClaim.js\";\n\n/**\n * Counts how often recovery has taken over a task without the task saving in between, so one that\n * keeps dying with its process is failed instead of resumed forever. Only the holder of the task's\n * claim records, so two processes never count the same takeover.\n */\nexport interface ITaskRecoveries {\n    /**\n     * Records one more takeover and resolves to the count, this one included. `savedOn` is when the\n     * task last saved: when it differs from the previous takeover's, the task made progress and the\n     * count starts over at 1.\n     */\n    record(target: TaskClaim.Target, savedOn: string): Promise<number>;\n}\n\nexport const TaskRecoveries = createAbstraction<ITaskRecoveries>(\"BackgroundTasks/TaskRecoveries\");\n\nexport namespace TaskRecoveries {\n    export type Interface = ITaskRecoveries;\n}\n"],"names":["TaskRecoveries","createAbstraction"],"mappings":";AAiBO,MAAMA,iBAAiBC,kBAAmC"}

package/handlers/InProcessBackgroundTaskHandler.d.ts

@@ -0,0 +1,37 @@
+import type { Container } from "@webiny/feature/api";
+import { BackgroundTaskEventHandler } from "@webiny/event-handler-core";
+import type { EventContext } from "@webiny/event-handler-core";
+import type { IBackgroundTaskEvent } from "@webiny/event-handler-core";
+import { RawTenantId } from "@webiny/api-core/features/requestContext/index.js";
+import { RequestTenantLoader } from "@webiny/api-core/features/requestContext/index.js";
+import { Logger } from "@webiny/api-core/features/logger/index.js";
+import { TaskClaim } from "../domain/TaskClaim.js";
+import { ShutdownSignal } from "../domain/ShutdownSignal.js";
+/**
+ * Runs one iteration of a background task in the request container the dispatcher built for it.
+ * The standalone counterpart of `BackgroundTaskLambdaHandler`: same tenant set-up and runner, with
+ * a process timer in place of the Lambda countdown.
+ *
+ * Every iteration runs under the task's claim, so only one process drives a task at a time. The
+ * first iteration takes the claim, the later ones find it still theirs.
+ *
+ * When the process starts shutting down, the running iteration's time runs out at once, so the task saves
+ * its progress and hands back control. The task is then left to another process.
+ */
+declare class InProcessBackgroundTaskHandlerImpl implements BackgroundTaskEventHandler.Interface {
+    private readonly container;
+    private readonly rawTenantId;
+    private readonly tenantLoader;
+    private readonly claim;
+    private readonly shutdown;
+    private readonly logger;
+    constructor(container: Container, rawTenantId: RawTenantId.Interface, tenantLoader: RequestTenantLoader.Interface, claim: TaskClaim.Interface, shutdown: ShutdownSignal.Interface, logger: Logger.Interface);
+    execute(eventCtx: EventContext<IBackgroundTaskEvent>): Promise<unknown>;
+    private hold;
+    private afterIteration;
+    private release;
+}
+export declare const InProcessBackgroundTaskHandler: typeof InProcessBackgroundTaskHandlerImpl & {
+    __abstraction: import("@webiny/di").Abstraction<import("@webiny/event-handler-core/features/backgroundTask/BackgroundTaskEventHandler").IBackgroundTaskEventHandler>;
+};
+export {};