meocord 4.2.0 → 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 };

package/dist/esm/core/meocord-factory.js

@@ -3,32 +3,29 @@ import { COOLDOWN_POLICY, cooldownPolicyFrom, handlerCooldowns } from './cooldow
 import { Container } from 'inversify';
 import { Client } from 'discord.js';
 import { Logger } from '../common/logger.js';
+import { warnOnce } from '../common/deprecation.js';
 import './theme-scope.js';
 import './theme-validation.js';
 import '../common/decorator.js';
 import { ExecutionContext } from '../common/execution-context.js';
-import { registerClientTranslator } from '../common/meocord-text.js';
+import '../common/errors.js';
 import { CooldownStore, MemoryCooldownStore } from '../common/cooldown-store.js';
 import 'node:crypto';
 import { getCommandMap, getMessageHandlers } from '../decorator/controller.decorator.js';
 import './scalar-types.js';
 import { processShardingEnabled, shardingRole, clientOptionsWithSharding } from '../util/sharding-mode.util.js';
 import { Translator, missingTranslatorError } from '../common/translator.js';
-import '../common/response/send-failure.js';
-import '../util/interaction.util.js';
-import '../common/response/flags.js';
-import 'path';
-import '../common/response/components.js';
-import { themeResolverClass } from './theme-resolvers.js';
+import { registerClientTranslator } from '../common/meocord-text.js';
+import '../common/response/response-state.js';
 import { isExplainedError, markExplained } from '../common/explained-error.js';
+import { themeResolverClass, ThemeCache } from './theme-resolvers.js';
 import { MeoCordApp } from './meocord.app.js';
 import { loadMeoCordConfig, compiledConfigMessage } from '../util/meocord-config-loader.util.js';
 import { bunDevelopmentValues, bunDevelopmentWarning } from '../util/inherited-env.util.js';
-import { assertBuiltForThisPlatform } from '../util/platform.util.js';
 import { isRegisterOnly } from '../util/registration-mode.util.js';
-import { injectedTokens, singletonContextError } from './guard-runner.js';
+import { recordInstanceContainers, injectedTokens, singletonContextError } from './guard-runner.js';
 import { appStages, bindGlobalStages, prepareHandlerStages, prepareThemes, bindAppPresenter } from './handler-pipeline.js';
-import { startupClasses, assertStartupClasses, lateGuardCheck } from './startup-roots.js';
+import { startupClasses, assertStartupClasses, lateGuardCheck, stageDependencies } from './startup-roots.js';
 import { markStartupChecked, assertStartupChecked } from './startup-checked.js';
 import { makeInjectable } from '../util/injectable.util.js';
 import { meocordClasses } from './meocord-classes.js';
@@ -102,8 +99,8 @@ import { isShardProcess } from '../util/shard-process.util.js';
    * The config a single process runs with. Under `meocord start --dev` without `sharding.development`,
    * process sharding falls back to running every shard in this process, so the watcher restarts one
    * process and leaves no shards behind.
-   */ static effectiveConfig(config) {
-        if (config.sharding?.mode !== 'process' || isShardProcess() || processShardingEnabled(config)) return config;
+   */ static effectiveConfig(config, shard) {
+        if (config.sharding?.mode !== 'process' || shard || processShardingEnabled(config)) return config;
         this.logger.info("sharding.mode 'process' is off in development, so every shard runs in this process; set " + 'sharding.development: true to run them in separate processes.');
         return {
             ...config,
@@ -123,7 +120,8 @@ import { isShardProcess } from '../util/shard-process.util.js';
    * @returns The application, which `start()` logs in.
    * @throws Error when the class has no `@MeoCord`, when the compiled config is missing beside the bundle or fails to
    *   load, naming the file and the reason, with what to do about it, when a provider cannot
-   *   be bound, such as one for a token MeoCord binds itself, when two handlers take one command, or two builder
+   *   be bound, such as one for a token MeoCord binds itself (a provider for `ThemeCache` or `ExecutionContext` is warned
+   *   about instead, and refused from the next major version, 5.0), when two handlers take one command, or two builder
    *   classes build one, naming both, and for any other mistake it refuses as the app loads, such as two component
    *   patterns that match the same customIds. Each check reports every error it finds, and the first is thrown,
    *   unchanged. When there are several, each is logged first, with where in the source it comes from; a lone one is
@@ -131,11 +129,14 @@ import { isShardProcess } from '../util/shard-process.util.js';
    *   shard of process sharding, the manager logs it. With `startupErrors: 'all'` in `meocord.config.ts`, the errors
    *   decorators kept are among them.
    */ static create(target) {
+        // Decided first, once, and handed to all that asks: a ShardingManager this app builds writes the variable into its
+        // own process too, which would make the manager read as a shard
+        const shard = isShardProcess(process.env);
         try {
-            return this.createApplication(target);
+            return this.createApplication(target, shard);
         } catch (error) {
             // A shard ends, so its manager restarts it, or stops every shard for a refusal, which it logs
-            if (isShardProcess()) endFailedShard(error);
+            if (shard) endFailedShard(error);
             else if (isRefusal(error) && !isExplainedError(error)) {
                 // Every startup error found together is logged, in a test too; a lone one is logged in a built application
                 if (logStartupErrors(error, (text)=>this.logger.error(text), 'the bot did not start')) markExplained(error);
@@ -147,18 +148,25 @@ import { isShardProcess } from '../util/shard-process.util.js';
             throw error;
         }
     }
-    static createApplication(target) {
-        const options = Reflect.getMetadata(META.appOptions, target);
+    static createApplication(target, shard) {
+        const appOptions = Reflect.getMetadata(META.appOptions, target);
         // With startupErrors: 'all', what the decorators kept: a built bot's every one, else the app's and its controllers'
         const declared = isBuiltApplication() ? allDeclaredErrors() : declaredErrorsOf([
             target,
-            ...options?.controllers ?? []
+            ...appOptions?.controllers ?? []
         ]);
-        if (!options) {
+        if (!appOptions) {
             // A refused @MeoCord stores no options, so its own errors say why
             collectStartupErrors(()=>declared.forEach(startupError));
             throw refuse(new Error(`${typeof target === 'function' ? target.name : String(target)}: not decorated with @MeoCord(), so there is no app to create.`));
         }
+        // A controller listed twice is one controller, as the command checks and fromApp already take it
+        const options = {
+            ...appOptions,
+            controllers: [
+                ...new Set(appOptions.controllers)
+            ]
+        };
         const meocordConfig = loadMeoCordConfig();
         if (!meocordConfig) {
             throw refuse(new Error(compiledConfigMessage()));
@@ -185,7 +193,7 @@ import { isShardProcess } from '../util/shard-process.util.js';
             ...appObservers(target)
         ];
         // A shard's manager runs the same checks, so a sharded bot warns once
-        if (!isShardProcess()) {
+        if (!shard) {
             warnUnregisteredCommands(options.controllers);
             warnInheritedRoutes(options.controllers);
             warnOverlappingPatterns(options.controllers);
@@ -200,11 +208,8 @@ import { isShardProcess } from '../util/shard-process.util.js';
         if (isRegisterOnly()) {
             return new MeoCordApp(options.controllers, new Container(), new Client(options.clientOptions), meocordConfig.discordToken);
         }
-        // Before anything is resolved: a controller or service is what first loads a native addon, and one built for another
-        // platform would otherwise fail there with a linker error. A manager checks too, before it registers or spawns.
-        assertBuiltForThisPlatform();
         // A process-sharding manager only spawns shards, so it binds, constructs and connects nothing itself.
-        if (shardingRole(meocordConfig) === 'manager') {
+        if (shardingRole(meocordConfig, shard) === 'manager') {
             return new ShardManager({
                 controllerClasses: options.controllers,
                 token: meocordConfig.discordToken,
@@ -242,7 +247,7 @@ import { isShardProcess } from '../util/shard-process.util.js';
             ], lateGuardCheck(providers, translator));
             bindGlobalStages(container, stages);
             // Bound now, so no provider stands in for it; made once the checks pass, the one Client the app logs in with
-            const clientOptions = clientOptionsWithSharding(this.effectiveConfig(meocordConfig), options.clientOptions);
+            const clientOptions = clientOptionsWithSharding(this.effectiveConfig(meocordConfig, shard), options.clientOptions);
             container.bind(Client).toDynamicValue(()=>new Client(clientOptions)).inSingletonScope();
             if (options.i18n) {
                 container.bind(Translator).toConstantValue(options.i18n);
@@ -270,6 +275,10 @@ import { isShardProcess } from '../util/shard-process.util.js';
             // After MeoCord's own tokens, which a provider may not replace, and before the app's classes, so
             // a class token that is provided is not also bound as itself
             for (const [token, provider] of providers){
+                // Bound later, or for each call, so not caught below; supported until 5.0 refuses it
+                if (token === ThemeCache || token === ExecutionContext) {
+                    warnOnce(this.logger, `${target.name}: @MeoCord({ providers }) provides ${tokenName(token)}, which MeoCord binds itself; ` + 'the next major version (5.0) refuses it. Remove the provider.');
+                }
                 if (container.isBound(token)) {
                     startupError(new Error(`${target.name}: @MeoCord({ providers }) cannot provide ${tokenName(token)}, which MeoCord binds itself.`));
                     continue;
@@ -287,6 +296,9 @@ import { isShardProcess } from '../util/shard-process.util.js';
             // Observers are services too: bound here so their lifecycle hooks run in dependency order
             const observers = appObservers(target);
             for (const observer of observers)bindDependencies(container, observer, providers);
+            // What the stages and presenter inject, bound now so a service among them is made as the bot comes online
+            const stageServices = stageDependencies(runs, providers, options.presenter);
+            for (const service of stageServices)bindDependencies(container, service, providers);
             // What follows walks what these bound, so a class refused here is not reported again as missing
             stopOnStartupErrors();
             // Providers first, then the services, the controllers and the observers, each after what it depends on. The app's
@@ -307,12 +319,19 @@ import { isShardProcess } from '../util/shard-process.util.js';
                 return isAppClassToken(token) && (!provider || isClassProvider(provider) && provider.useClass === token);
             }));
             assertProvided(container, providers, runs.classes, '@MeoCord({ providers })');
+            // With what the stages inject among them, each after what it depends on, so their hooks run as a listed service's do
+            const roots = stageServices.length > 0 ? resolutionOrder(container, providers, [
+                ...order,
+                ...stageServices
+            ], {
+                followOwnTokens: false
+            }) : order;
             // The store first, after only what it injects: it is ready before anything a call reaches, and shuts down last
             const store = options.cooldownStore;
             const lifecycle = (store ? resolutionOrder(container, providers, [
                 store,
-                ...order
-            ]) : order).map((token)=>({
+                ...roots
+            ]) : roots).map((token)=>({
                     token,
                     name: tokenName(token),
                     dependencies: tokenDependencies(container, providers, token),
@@ -352,24 +371,28 @@ import { isShardProcess } from '../util/shard-process.util.js';
             for (const cls of runs.classes){
                 Reflect.defineMetadata(META.container, container, cls);
             }
+            recordInstanceContainers(container, runs.classes);
             prepareThemes(container, appClasses);
             // Run by start() before it logs in: what may inject a provided value is resolved once every factory
             // has made its value, including those that return a promise
             const logger = this.logger;
-            const startup = async ()=>{
+            const startup = async (control)=>{
                 try {
-                    await resolveProviders(container, providers, order);
+                    await resolveProviders(container, providers, order, control);
                 } catch (error) {
                     logger.error(`${error.message}. The bot cannot start without it.`);
                     logger.debug('Provider failure:', error.cause);
                     markExplained(error);
                     throw error;
                 }
-                // The listed services are made now, so constructors that attach listeners or connect run before login
+                // The listed services are made now, so constructors that attach listeners or connect run before login; a stop
+                // meanwhile makes no more of them
                 for (const svc of options.services ?? []){
+                    if (control.stopped()) return;
                     container.get(svc);
                 }
-                if (shardingRole(meocordConfig) === 'shard' && container.get(CooldownStore) instanceof MemoryCooldownStore) {
+                if (control.stopped()) return;
+                if (shard && container.get(CooldownStore) instanceof MemoryCooldownStore) {
                     warnPerShardCooldowns(options.controllers, logger);
                 }
                 bindAppPresenter(container, target, discordClient);
@@ -377,7 +400,7 @@ import { isShardProcess } from '../util/shard-process.util.js';
                 registerClientTranslator(discordClient, options.i18n);
             };
             return new MeoCordApp(options.controllers, container, discordClient, meocordConfig.discordToken, options.activities, appClasses, meocordConfig.shutdownTimeout, startup, lifecycle, options.messages, // In development only, unless the app says otherwise
-            options.warnUnanswered ?? process.env.NODE_ENV === 'development');
+            options.warnUnanswered ?? process.env.NODE_ENV === 'development', shard);
         });
     }
 }