meocord 4.1.2 → 4.2.1

package/dist/esm/core/lifecycle-hooks.js

@@ -1,4 +1,6 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { storeOperationsSettled } from './cooldown-runner.js';
+import { RunningCalls } from './running-calls.js';
 
 /** The entry of a unit whose instance is `instance`. */ function lifecycleEntry(unit, instance) {
     return {
@@ -11,11 +13,45 @@ import { storeOperationsSettled } from './cooldown-runner.js';
         }
     };
 }
+/**
+ * The ready hooks' pass, which shutdown waits for before it reads which units to shut down, so a unit whose `onReady`
+ * finishes meanwhile is shut down too. An `onReady` still running that asks the app to stop is not waited for; a timer
+ * or callback an `onReady` that has settled left behind excuses nothing.
+ */ class ReadyPass {
+    /** Runs `pass`, the ready hooks, as the pass shutdown waits for. */ run(pass) {
+        return this.passes.run('onReady', pass);
+    }
+    /** Excuses the pass when this runs within the `onReady` in progress, as one that stops the app does. */ excuseCurrent() {
+        if (this.current && this.hooks.getStore() === this.current) this.passes.excuseCurrent();
+    }
+    /** Settles once the pass has, unless excused. */ settled() {
+        return this.passes.settled();
+    }
+    /** The unit whose `onReady` a wait would still wait for, if any. */ running() {
+        return this.passes.running().length > 0 ? [
+            this.unit ?? 'a unit'
+        ] : [];
+    }
+    constructor(){
+        this.passes = new RunningCalls();
+        /** The `onReady` each async context belongs to. */ this.hooks = new AsyncLocalStorage();
+        /** Runs a unit's `onReady` as the one in progress. */ this.runOnReady = async (unit, run)=>{
+            const hook = {};
+            this.current = hook;
+            this.unit = unit.name;
+            try {
+                await this.hooks.run(hook, run);
+            } finally{
+                if (this.current === hook) this.current = undefined;
+            }
+        };
+    }
+}
 /**
  * Resolves each unit and runs its `onReady` one at a time, in the units' dependency order. A failure is
  * reported and the next unit still runs. Each unit whose `onReady` settled, or that has none, is pushed
  * to `entries` as it finishes, so a shutdown that starts meanwhile closes exactly those.
- */ async function runReadyHooks(container, units, client, info, entries, report, { stopped = ()=>false, slowAfterMs, settled } = {}) {
+ */ async function runReadyHooks(container, units, client, info, entries, report, { stopped = ()=>false, slowAfterMs, settled, runOnReady } = {}) {
     const failed = new Set();
     // For each unit, the failed units it depends on, directly or through another dependency
     const failedUpstream = new Map();
@@ -23,6 +59,9 @@ import { storeOperationsSettled } from './cooldown-runner.js';
             unit.token,
             unit
         ]));
+    // The token each instance was first reached by: one instance two tokens reach, an alias or one value provided twice,
+    // runs its hooks once
+    const firstToken = new Map();
     for (const unit of units){
         if (stopped()) break;
         const upstream = new Set();
@@ -41,9 +80,17 @@ import { storeOperationsSettled } from './cooldown-runner.js';
             settled?.(unit);
             continue;
         }
+        const first = firstToken.get(instance);
+        if (first !== undefined) {
+            // Failed or not as the token that ran its hooks did, for what depends on this one
+            if (failed.has(first)) failed.add(unit.token);
+            settled?.(unit);
+            continue;
+        }
+        firstToken.set(instance, unit.token);
         const entry = lifecycleEntry(unit, instance);
-        // Only a unit whose onReady has settled, or that has none, is shut down: a stop mid-ready skips
-        // the one still starting, and those not reached yet
+        // Only a unit whose onReady has settled, or that has none, is shut down: a stop mid-ready waits for the one still
+        // starting, within its time, and skips those not reached yet
         if (typeof instance.onReady !== 'function') {
             entries.push(entry);
             settled?.(unit);
@@ -54,7 +101,8 @@ import { storeOperationsSettled } from './cooldown-runner.js';
         ]);
         const slow = slowAfterMs !== undefined && report.slow ? setTimeout(()=>report.slow(unit), slowAfterMs) : undefined;
         try {
-            await instance.onReady(client, info);
+            const onReady = ()=>instance.onReady(client, info);
+            await (runOnReady ? runOnReady(unit, onReady) : onReady());
         } catch (error) {
             failed.add(unit.token);
             report.hookFailed(unit, error);
@@ -67,12 +115,14 @@ import { storeOperationsSettled } from './cooldown-runner.js';
 }
 /**
  * Runs the entries' `onShutdown` hooks one at a time, in reverse, so a unit stops before those it
- * depends on. A failure is reported and the next hook still runs.
- */ async function runShutdownHooks(entries, hookFailed) {
+ * depends on. A failure is reported and the next hook still runs. An instance already in `ran` is not shut down again,
+ * so one that two entries reach stops once.
+ */ async function runShutdownHooks(entries, hookFailed, ran = new Set()) {
     for (const { name, instance } of [
         ...entries
     ].reverse()){
-        if (typeof instance.onShutdown !== 'function') continue;
+        if (typeof instance.onShutdown !== 'function' || ran.has(instance)) continue;
+        ran.add(instance);
         try {
             await instance.onShutdown();
         } catch (error) {
@@ -80,54 +130,91 @@ import { storeOperationsSettled } from './cooldown-runner.js';
         }
     }
 }
-/**
- * Shuts down the entries there are when it begins, as a bot and a testing module both do. When the cooldown store, or
- * anything it injects directly or through another, has an `onShutdown`, the calls under way finish first, then the
- * store operations they started, so the store's last writes and releases still reach it. The other hooks then run in
- * reverse dependency order, and the store and what it injects last. The whole sequence is waited for at most
- * `timeoutMs`.
- */ async function runShutdownSequence(container, entries, { drainCalls, timeoutMs, hookFailed, warn }) {
-    // A unit whose onReady settles while the calls drain was still starting when shutdown began, so it is not shut down
-    entries = [
-        ...entries
-    ];
-    const byToken = new Map(entries.map((entry)=>[
-            entry.token,
-            entry
-        ]));
-    // The store and everything it reaches through what it injects
-    const storeSide = new Set();
-    const reach = (entry)=>{
-        if (!entry || storeSide.has(entry)) return;
-        storeSide.add(entry);
-        for (const dependency of entry.dependencies)reach(byToken.get(dependency));
-    };
-    for (const entry of entries)if (entry.cooldownStore) reach(entry);
-    const needsStore = [
-        ...storeSide
-    ].some((entry)=>typeof entry.instance.onShutdown === 'function');
-    const sequence = (async ()=>{
-        if (needsStore) {
-            await drainCalls();
-            await storeOperationsSettled(container);
-        }
-        // Nothing on the store's side injects anything outside it, so running it last keeps the reverse dependency order
-        await runShutdownHooks(entries.filter((entry)=>!storeSide.has(entry)), hookFailed);
-        await runShutdownHooks(entries.filter((entry)=>storeSide.has(entry)), hookFailed);
-    })();
+/** The part of `timeoutMs` the drain leaves for the hooks: a quarter, at least 1 s, and never more than half. */ function hooksReserveMs(timeoutMs) {
+    return Math.min(Math.max(timeoutMs / 4, 1000), timeoutMs / 2);
+}
+/** A timer whose promise resolves with `value` after `ms`, and `cancel` to clear it. */ function after(ms, value) {
     let timer;
-    const timedOut = new Promise((resolve)=>{
-        timer = setTimeout(()=>resolve('timeout'), timeoutMs);
+    const promise = new Promise((resolve)=>{
+        timer = setTimeout(()=>resolve(value), ms);
     });
+    return {
+        promise,
+        cancel: ()=>clearTimeout(timer)
+    };
+}
+/**
+ * Shuts down the entries there are once an `onReady` in progress has settled, as a bot and a testing module both do.
+ * The calls under way finish first, on every shutdown with `drainAlways`, and otherwise when the cooldown store, or
+ * anything it injects directly or through another, has an `onShutdown`; then the store operations they started, so the
+ * store's last writes and releases still reach it. The other hooks then run in reverse dependency order, and the store
+ * and what it injects last.
+ *
+ * The whole sequence is waited for at most `timeoutMs`. The wait for the `onReady` and the drain stop early enough to
+ * leave the hooks {@link hooksReserveMs}, with a warning naming what still runs, and the hooks run in the time left.
+ */ async function runShutdownSequence(container, readEntries, { drainCalls, drainAlways = false, runningCalls, readyPass, timeoutMs, hookFailed, warn }) {
+    const whole = after(timeoutMs, 'timeout');
+    const reserve = hooksReserveMs(timeoutMs);
+    const drainEnds = after(timeoutMs - reserve, false);
+    // At once on a shutdown that always drains, so no call starts while an onReady finishes
+    let draining = drainAlways ? drainCalls().then(()=>true) : undefined;
     try {
+        const readying = readyPass?.running() ?? [];
+        if (readying.length > 0 && !await Promise.race([
+            readyPass.settled().then(()=>true),
+            drainEnds.promise
+        ])) {
+            warn(`onReady in ${readying.join(', ')} is still running after ${timeoutMs - reserve} ms; shutting down without waiting for it.`);
+        }
+        // Read once the onReady in progress has settled, so its unit is among them
+        const entries = [
+            ...readEntries()
+        ];
+        const byToken = new Map(entries.map((entry)=>[
+                entry.token,
+                entry
+            ]));
+        // The store and everything it reaches through what it injects
+        const storeSide = new Set();
+        const reach = (entry)=>{
+            if (!entry || storeSide.has(entry)) return;
+            storeSide.add(entry);
+            for (const dependency of entry.dependencies)reach(byToken.get(dependency));
+        };
+        for (const entry of entries)if (entry.cooldownStore) reach(entry);
+        const needsStore = [
+            ...storeSide
+        ].some((entry)=>typeof entry.instance.onShutdown === 'function');
+        let drained = true;
+        if (needsStore) draining ?? (draining = drainCalls().then(()=>true));
+        if (draining) {
+            drained = await Promise.race([
+                draining,
+                drainEnds.promise
+            ]);
+            if (!drained) {
+                const running = runningCalls?.() ?? [];
+                warn(`Calls still running after ${timeoutMs - reserve} ms${running.length > 0 ? `: ${running.join(', ')}` : ''}; ` + `running the onShutdown hooks in the ${reserve} ms left.`);
+            }
+        }
+        drainEnds.cancel();
+        const sequence = (async ()=>{
+            // Only after the calls settled: a call still running may never let its store operations settle
+            if (needsStore && drained) await storeOperationsSettled(container);
+            // Nothing on the store's side injects anything outside it, so running it last keeps the reverse dependency order
+            const ran = new Set();
+            await runShutdownHooks(entries.filter((entry)=>!storeSide.has(entry)), hookFailed, ran);
+            await runShutdownHooks(entries.filter((entry)=>storeSide.has(entry)), hookFailed, ran);
+        })();
         if (await Promise.race([
             sequence,
-            timedOut
+            whole.promise
         ]) === 'timeout') {
             warn(`onShutdown hooks did not finish within ${timeoutMs} ms; shutting down anyway.`);
         }
     } finally{
-        clearTimeout(timer);
+        drainEnds.cancel();
+        whole.cancel();
     }
 }
 /** Settles once every promise in `calls` has, those added while waiting included. */ async function callsSettled(calls) {
@@ -136,4 +223,4 @@ import { storeOperationsSettled } from './cooldown-runner.js';
     ]);
 }
 
-export { callsSettled, lifecycleEntry, runReadyHooks, runShutdownHooks, runShutdownSequence };
+export { ReadyPass, callsSettled, hooksReserveMs, lifecycleEntry, runReadyHooks, runShutdownHooks, runShutdownSequence };