@venizia/ignis-kernel 0.2.0-9 → 0.2.1-0

package/dist/cjs/base/applications/rest.js

@@ -3,27 +3,41 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RestApplication = void 0;
 const bindings_1 = require("../../common/bindings");
 const inversion_1 = require("../../helpers/inversion");
-const rest_component_1 = require("../components/controller/rest/rest.component");
-const constants_1 = require("../controllers/common/constants");
 const zod_openapi_1 = require("@hono/zod-openapi");
 const core_1 = require("@venizia/ignis-helpers/core");
 const dev_1 = require("hono/dev");
+const body_limit_1 = require("hono/body-limit");
 const request_id_1 = require("hono/request-id");
+const rest_component_1 = require("../components/controller/rest/rest.component");
+const constants_1 = require("../controllers/common/constants");
 const app_error_middleware_1 = require("../middlewares/app-error/app-error.middleware");
+const errors_1 = require("../middlewares/common/errors");
 const not_found_middleware_1 = require("../middlewares/not-found/not-found.middleware");
 const abstract_1 = require("./abstract");
+const artifact_index_1 = require("./artifact-index");
+const boot_sequence_1 = require("./boot-sequence");
 /** Adds the `OpenAPIHono` router surface on top of `AbstractApplication` - no listening server, so this is the layer a browser Worker or gRPC-only host can extend without pulling in `Bun.serve` / `@hono/node-server`. */
 class RestApplication extends abstract_1.AbstractApplication {
     constructor(opts) {
         super(opts);
         this.registeredBindings = {};
+        this.artifactOptions = new Map();
+        // A config built from the environment can lose `path.base` at run time; the router would only fail later, inside `route()`, with a message that names nothing.
+        if (typeof this.configs.path?.base !== 'string') {
+            throw (0, core_1.getError)({
+                message: `[${opts.scope}] configs.path.base must be a string | value: ${String(this.configs.path?.base)} | an empty string mounts the application at the root`,
+            });
+        }
+        // The index signature accepts any key, so a leftover `strictPath` would compile and be ignored.
+        if (this.configs.strictPath !== undefined) {
+            throw (0, core_1.getError)({
+                message: `[${opts.scope}] configs.strictPath was removed | value: ${String(this.configs.strictPath)} | Use configs.path.isStrict`,
+            });
+        }
         this.requestIdGenerator = new core_1.RequestIdGenerator({ scope: opts.scope });
-        const honoServer = new zod_openapi_1.OpenAPIHono({
-            strict: this.configs.strictPath ?? true,
-        });
-        this.rootRouter = new zod_openapi_1.OpenAPIHono({
-            strict: this.configs.strictPath ?? true,
-        });
+        const strict = this.configs.path.isStrict ?? true;
+        const honoServer = new zod_openapi_1.OpenAPIHono({ strict });
+        this.rootRouter = new zod_openapi_1.OpenAPIHono({ strict });
         this.server = { hono: honoServer };
     }
     getRootRouter() {
@@ -57,37 +71,217 @@ class RestApplication extends abstract_1.AbstractApplication {
         });
     }
     /**
-     * The three registrations every host needs, in one place, so a server and a browser Worker cannot
-     * drift: a request id, the framework's error envelope, and a JSON 404.
-     *
-     * None is optional. Hono's own defaults answer a thrown `ApplicationError` with a generic 500 and
-     * an unrouted path with `text/plain` - a caller doing `response.json()` on that 404 gets a
-     * `SyntaxError` instead of an error envelope. And without `requestId()`, `context.get(REQUEST_ID_KEY)`
-     * is `undefined`, so `context.json` drops the one field that ties a response to a log line.
-     *
-     * Registered before `initialize()`, so an application installing its own handlers still wins.
+     * The three registrations every host needs: request id, error envelope, JSON 404 - without them a
+     * thrown `ApplicationError` is a generic 500, a 404 is `text/plain`, and no response carries a request id.
+     * Registered before `initialize()`, so an application's own handlers still win.
      */
     registerDefaultMiddlewares() {
         const server = this.getServer();
         server.use((0, request_id_1.requestId)({ generator: () => this.generateRequestId() }));
+        // Ahead of every middleware a host adds after this one, so none of them buffers a body over it.
+        const bodyLimitOptions = this.configs.middlewares?.bodyLimit;
+        this.installedBodyLimit = { options: this.toInstalledBodyLimit({ options: bodyLimitOptions }) };
+        if (bodyLimitOptions && bodyLimitOptions.enable !== false) {
+            const { maxSize, path, onError } = bodyLimitOptions;
+            if (typeof maxSize !== 'number' || !Number.isFinite(maxSize) || maxSize < 0) {
+                throw (0, core_1.getError)({
+                    message: `[registerDefaultMiddlewares] configs.middlewares.bodyLimit.maxSize must be a non-negative number of bytes | value: ${String(maxSize)}`,
+                });
+            }
+            const limiter = (0, body_limit_1.bodyLimit)({
+                maxSize,
+                onError: onError ??
+                    (() => {
+                        throw (0, core_1.getError)({
+                            error: errors_1.RequestErrors.BODY_TOO_LARGE,
+                            message: `Request body exceeds the maximum of ${maxSize} bytes`,
+                        });
+                    }),
+            });
+            if (path) {
+                server.use(path, limiter);
+            }
+            else {
+                server.use(limiter);
+            }
+        }
         server.onError(this.buildErrorMiddleware().value());
         server.notFound((0, not_found_middleware_1.notFoundHandler)({ logger: this.logger }));
     }
+    /** What a `bodyLimit` config installs: nothing when absent or disabled, else a copy, so a later in-place edit shows. */
+    toInstalledBodyLimit(opts) {
+        const { options } = opts;
+        if (!options || options.enable === false) {
+            return undefined;
+        }
+        return { ...options };
+    }
+    isSameBodyLimit(opts) {
+        const { left, right } = opts;
+        if (!left || !right) {
+            return left === right;
+        }
+        const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+        for (const key of keys) {
+            if (!Object.is(left[key], right[key])) {
+                return false;
+            }
+        }
+        return true;
+    }
     /**
-     * The artifact ordering, stated ONCE: datasources before repositories can auto-resolve them, and
-     * components before controllers because a component may contribute either.
-     *
-     * A browser Worker application inherits this and writes none of it. `BaseApplication` in
-     * `@venizia/ignis` is the one deliberate override - it interleaves phases only a server has
-     * (start-up banner, env validation, secret hydration and rotation) between these steps.
+     * `configs.middlewares` is read by `registerDefaultMiddlewares()`, which runs before `staticConfigure()`.
+     * A limit assigned in a boot hook would read back as configured while every request ran unlimited.
+     */
+    assertBodyLimitUnchanged(opts) {
+        if (!this.installedBodyLimit) {
+            return;
+        }
+        const installed = this.installedBodyLimit.options;
+        const current = this.toInstalledBodyLimit({ options: this.configs.middlewares?.bodyLimit });
+        if (this.isSameBodyLimit({ left: installed, right: current })) {
+            return;
+        }
+        throw (0, core_1.getError)({
+            message: `[${opts.step}] configs.middlewares.bodyLimit changed after registerDefaultMiddlewares() installed it | installed maxSize: ${installed?.maxSize ?? 'none'} | now maxSize: ${current?.maxSize ?? 'none'} | Pass it through the constructor config: new Application({ config: { middlewares: { bodyLimit } } })`,
+        });
+    }
+    /**
+     * The artifact order, stated once: datasources before the repositories that auto-resolve them,
+     * components before the controllers they may contribute. `BaseApplication` splices its server-only
+     * steps around these by name instead of rewriting the list.
      */
+    getBootSequence() {
+        return [
+            {
+                name: boot_sequence_1.BootSteps.STATIC_CONFIGURE,
+                run: async () => {
+                    // Declared `void`, but an override may be async; the step has always waited on it.
+                    await Promise.resolve(this.staticConfigure());
+                    this.assertBodyLimitUnchanged({ step: boot_sequence_1.BootSteps.STATIC_CONFIGURE });
+                },
+            },
+            { name: boot_sequence_1.BootSteps.REGISTER_ARTIFACTS, run: () => this.registerConfiguredArtifacts() },
+            {
+                name: boot_sequence_1.BootSteps.PRE_CONFIGURE,
+                run: async () => {
+                    await this.runApplicationHook({
+                        name: boot_sequence_1.BootSteps.PRE_CONFIGURE,
+                        hook: () => this.preConfigure(),
+                    });
+                    this.assertBodyLimitUnchanged({ step: boot_sequence_1.BootSteps.PRE_CONFIGURE });
+                },
+            },
+            {
+                name: boot_sequence_1.BootSteps.REGISTER_CONFIGURATIONS,
+                run: () => this.registerConfigurations(),
+            },
+            { name: boot_sequence_1.BootSteps.REGISTER_DATA_SOURCES, run: () => this.registerDataSources() },
+            { name: boot_sequence_1.BootSteps.REGISTER_COMPONENTS, run: () => this.registerComponents() },
+            {
+                name: boot_sequence_1.BootSteps.REGISTER_CONTRIBUTED_DATA_SOURCES,
+                run: () => this.registerContributedDataSources(),
+            },
+            { name: boot_sequence_1.BootSteps.REGISTER_CONTROLLERS, run: () => this.registerControllers() },
+            {
+                name: boot_sequence_1.BootSteps.POST_CONFIGURE,
+                run: () => this.runApplicationHook({
+                    name: boot_sequence_1.BootSteps.POST_CONFIGURE,
+                    hook: () => this.postConfigure(),
+                }),
+            },
+            { name: boot_sequence_1.BootSteps.VERIFY_BINDINGS, run: () => this.verifyBindings() },
+        ];
+    }
     async initialize() {
-        this.staticConfigure();
-        await this.preConfigure();
-        await this.registerDataSources();
-        await this.registerComponents();
-        await this.registerControllers();
-        await this.postConfigure();
+        await this.runBootSequence({ steps: this.getBootSequence() });
+    }
+    async runApplicationHook(opts) {
+        this.runningApplicationHook = opts.name;
+        try {
+            await opts.hook();
+        }
+        finally {
+            this.runningApplicationHook = undefined;
+        }
+    }
+    /**
+     * Bound keys carrying one of `tags` that nothing has resolved since the counts were last reset.
+     * The counter answers "who was read", never "who is dead" - an unread binding may be an
+     * allow-list entry or a technical floor, and only the application can tell those apart.
+     *
+     * Counting is off by default. Call `startResolutionCounting()` after `initialize()` and run the
+     * traffic that exercises the application, then read this.
+     */
+    getUnresolvedBindings(opts) {
+        if (!this.hasStartedResolutionCounting) {
+            throw (0, core_1.getError)({
+                message: `[${this.getUnresolvedBindings.name}] Resolution counting never started | Call startResolutionCounting() after initialize(), run the traffic that exercises the application, then read this - without it every binding would be reported unresolved`,
+            });
+        }
+        const tags = opts?.tags ?? [bindings_1.BindingNamespaces.SERVICE, bindings_1.BindingNamespaces.REPOSITORY];
+        const counts = this.getResolutionCounts();
+        const unresolved = [];
+        for (const tag of tags) {
+            const bindings = this.findByTag({ tag });
+            for (const binding of bindings) {
+                if (counts.has(binding.key)) {
+                    continue;
+                }
+                unresolved.push(binding.key);
+            }
+        }
+        return unresolved;
+    }
+    /** `bootChecks.binding.doVerify`: resolve every service and repository once, collect every failure, throw once with the whole list - a made-up `@inject` key or a dependency a `when` excluded then fails the boot, not the first request. */
+    verifyBindings() {
+        if (!this.configs.bootChecks?.binding?.doVerify) {
+            return;
+        }
+        const logger = this.logger.for(this.verifyBindings.name);
+        const tags = [bindings_1.BindingNamespaces.SERVICE, bindings_1.BindingNamespaces.REPOSITORY];
+        const failures = [];
+        let verified = 0;
+        for (const tag of tags) {
+            const bindings = this.findByTag({ tag });
+            for (const binding of bindings) {
+                try {
+                    this.get({ key: binding.key });
+                    verified += 1;
+                }
+                catch (error) {
+                    failures.push(`${binding.key}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+        if (failures.length > 0) {
+            throw (0, core_1.getError)({
+                message: `[${this.verifyBindings.name}] ${failures.length} binding(s) cannot be resolved | ${failures.join(' | ')}`,
+            });
+        }
+        logger.info('Every service and repository binding resolves | verified: %d', verified);
+    }
+    /** One measured log line per step, and a failure names its step before rethrowing, so a hung or failed boot is attributable without reading the sequence. */
+    async runBootSequence(opts) {
+        const { steps } = opts;
+        const logger = this.logger.for(this.initialize.name);
+        const t = performance.now();
+        const stepsEntries = steps.entries();
+        for (const [index, step] of stepsEntries) {
+            try {
+                await (0, core_1.executeWithPerformanceMeasure)({
+                    logger: this.logger,
+                    scope: this.initialize.name,
+                    description: `Boot step ${index + 1}/${steps.length} ${step.name}`,
+                    task: () => step.run(),
+                });
+            }
+            catch (error) {
+                logger.error('Boot step failed | step: %s (%d/%d) | error: %s', step.name, index + 1, steps.length, error);
+                throw error;
+            }
+        }
+        logger.info('Boot sequence complete | %d step(s) | Took: %s (ms) | %s', steps.length, performance.now() - t, steps.map(step => step.name).join(' -> '));
     }
     inspectRoutes() {
         const t = performance.now();
@@ -101,48 +295,135 @@ class RestApplication extends abstract_1.AbstractApplication {
             .for(this.inspectRoutes.name)
             .info('DONE | Inspect all application route(s) | Took: %s (ms)', performance.now() - t);
     }
-    async registerDynamicBindings(opts) {
-        const logger = this.logger.for(this.registerDynamicBindings.name);
-        const { namespace, onBeforeConfigure, onAfterConfigure } = opts;
-        if (!this.registeredBindings[namespace]) {
-            this.registeredBindings[namespace] = new Set();
-        }
-        const configured = this.registeredBindings[namespace];
+    /**
+     * `configured` is the drain's state, mutated in place: a fresh `Set` gives a one-shot complete
+     * drain (`RestComponent`); `registerDynamicBindings` passes its persistent per-namespace `Set`,
+     * which is why a second sweep touches only what the first one missed.
+     */
+    async drainByTag(opts) {
+        const { tag, configured, onEach } = opts;
         // A whole batch is drained before re-scanning: the re-scan exists only to pick up bindings a
         // `configure()` added, and asking after every single item makes boot N+1 full scans of the
         // binding map - 3.5ms at 200 controllers, against 0.04ms for this shape.
-        let bindings = this.findByTag({ tag: namespace, exclude: configured });
+        let bindings = this.findByTag({ tag, exclude: configured });
         while (bindings.length > 0) {
             for (const binding of bindings) {
                 // Within a batch a nested `configure()` may already have taken this one.
                 if (configured.has(binding.key)) {
                     continue;
                 }
+                await onEach({ binding });
+                configured.add(binding.key);
+            }
+            // Re-fetch excluding already configured - picks up dynamically added bindings
+            bindings = this.findByTag({ tag, exclude: configured });
+        }
+    }
+    async registerDynamicBindings(opts) {
+        const logger = this.logger.for(this.registerDynamicBindings.name);
+        const { namespace, onBeforeConfigure, onAfterConfigure } = opts;
+        if (!this.registeredBindings[namespace]) {
+            this.registeredBindings[namespace] = new Set();
+        }
+        const configured = this.registeredBindings[namespace];
+        await this.drainByTag({
+            tag: namespace,
+            configured,
+            onEach: async ({ binding }) => {
                 if (onBeforeConfigure) {
                     await onBeforeConfigure({ binding });
                 }
                 const instance = this.get({ key: binding.key, isOptional: false });
                 if (!instance) {
                     logger.debug('No binding instance | namespace: %s | key: %s', namespace, binding.key);
-                    configured.add(binding.key);
-                    continue;
+                    return;
+                }
+                if (typeof instance?.configure === 'function') {
+                    const options = this.artifactOptions.get(binding.key);
+                    await instance.configure(options);
                 }
-                await instance.configure();
+                // Marked before the after-hook runs, so the hook sees its own binding as configured.
                 configured.add(binding.key);
                 if (onAfterConfigure) {
                     await onAfterConfigure({ binding, instance });
                 }
-            }
-            // Re-fetch excluding already configured - picks up dynamically added bindings
-            bindings = this.findByTag({ tag: namespace, exclude: configured });
+            },
+        });
+    }
+    /** The same-key guard behind every artifact registration (`component`/`controller`/`service`/`repository`/`dataSource`). `allowOverride` defaults true to match `bind()`'s overwrite behavior; `allowOverride: false` on one registration, or `bootChecks.binding.allowOverride: false` for the whole application, opts into strict mode. */
+    assertNoBindingCollision(opts) {
+        const { key, caller } = opts;
+        const allowOverride = opts.allowOverride ?? this.configs.bootChecks?.binding?.allowOverride ?? true;
+        if (allowOverride || !this.isBound({ key })) {
+            return;
         }
+        const reason = opts.allowOverride === false
+            ? `'allowOverride: false' was set and this key collides with an existing binding | Use a distinct 'opts.binding' key, or drop 'allowOverride: false' if overriding is intentional`
+            : `'bootChecks.binding.allowOverride' is false and this key collides with an existing binding | Use a distinct 'opts.binding' key, or set 'allowOverride: true' on this registration if overriding is intentional`;
+        throw (0, core_1.getError)({
+            message: `[${caller}] Binding key already registered: '${key}' | ${reason}`,
+        });
     }
-    component(ctor, opts) {
-        return this.bind({
-            key: inversion_1.BindingKeys.build(opts?.binding ?? { namespace: bindings_1.BindingNamespaces.COMPONENT, key: ctor.name }),
-        })
-            .toClass(ctor)
-            .setScope(inversion_1.BindingScopes.SINGLETON);
+    /** Resolution order for every registration: explicit `opts` > the class's `@injectable` defaults > the derived key and the kind's default scope. `order` and `when` are `registerArtifacts`' concern, not this one. */
+    registerArtifact(opts) {
+        const { target, namespace, defaultScope, caller } = opts;
+        const declared = inversion_1.MetadataRegistry.getInstance().getArtifactMetadata({ target });
+        if (this.runningApplicationHook &&
+            this.configs.artifacts &&
+            this.configs.bootChecks?.binding?.allowManual === false) {
+            throw (0, core_1.getError)({
+                message: `[${caller}] '${target.name}' is registered by hand inside ${this.runningApplicationHook}() while 'configs.artifacts' is set and 'bootChecks.binding.allowManual' is false | Move the class into the generated index (or an explicit entry of 'configs.artifacts'), or allow manual registration`,
+            });
+        }
+        const binding = opts.opts?.binding ?? declared?.binding ?? { namespace, key: target.name };
+        bindings_1.BindingNamespaces.assertArtifactNamespace({
+            namespace: binding.namespace,
+            artifact: target.name,
+            caller,
+        });
+        const key = inversion_1.BindingKeys.build(binding);
+        // What `@inject({ target })` reads back. Only here knows the call site's `binding`, and a
+        // class registered by hand has no stereotype metadata to derive one from.
+        inversion_1.MetadataRegistry.getInstance().setBindingKey({ target, key });
+        if (opts.opts?.options !== undefined) {
+            this.artifactOptions.set(key, opts.opts.options);
+        }
+        this.assertNoBindingCollision({
+            key,
+            allowOverride: opts.opts?.allowOverride ?? declared?.allowOverride,
+            caller,
+        });
+        return this.bind({ key })
+            .toClass(target)
+            .setScope(declared?.scope ?? defaultScope);
+    }
+    configuration(target, opts) {
+        return this.registerArtifact({
+            target,
+            namespace: bindings_1.BindingNamespaces.CONFIGURATION,
+            defaultScope: inversion_1.BindingScopes.SINGLETON,
+            caller: this.configuration.name,
+            opts,
+        });
+    }
+    async registerConfigurations() {
+        await (0, core_1.executeWithPerformanceMeasure)({
+            logger: this.logger,
+            scope: this.registerConfigurations.name,
+            description: 'Register application configurations',
+            task: async () => {
+                await this.registerDynamicBindings({ namespace: bindings_1.BindingNamespaces.CONFIGURATION });
+            },
+        });
+    }
+    component(target, opts) {
+        return this.registerArtifact({
+            target,
+            namespace: bindings_1.BindingNamespaces.COMPONENT,
+            defaultScope: inversion_1.BindingScopes.SINGLETON,
+            caller: this.component.name,
+            opts,
+        });
     }
     async registerComponents() {
         await (0, core_1.executeWithPerformanceMeasure)({
@@ -150,21 +431,26 @@ class RestApplication extends abstract_1.AbstractApplication {
             scope: this.registerComponents.name,
             description: 'Register application components',
             task: async () => {
-                await this.registerDynamicBindings({
-                    namespace: bindings_1.BindingNamespaces.COMPONENT,
-                    onAfterConfigure: async () => {
-                        // Register any datasources dynamically added by this component
-                        await this.registerDynamicBindings({ namespace: bindings_1.BindingNamespaces.DATASOURCE });
-                    },
-                });
+                await this.registerDynamicBindings({ namespace: bindings_1.BindingNamespaces.COMPONENT });
             },
         });
     }
     /**
-     * Handles the REST branch only - the kernel has no notion of gRPC (it reaches `node:module` via
-     * `AbstractGrpcController`, core-only). `BaseApplication` extends this with the gRPC branch, the
-     * unsupported-transport error and the orphaned-gRPC-controller warning.
+     * Second DATASOURCE sweep, for datasources components contributed at any depth. Calls
+     * `registerDynamicBindings` directly: `this.registerDataSources()` is polymorphic and an override
+     * would run twice. Runs after every component, so a component a datasource registers is never configured.
      */
+    async registerContributedDataSources() {
+        await (0, core_1.executeWithPerformanceMeasure)({
+            logger: this.logger,
+            scope: this.registerContributedDataSources.name,
+            description: 'Register application contributed data sources',
+            task: async () => {
+                await this.registerDynamicBindings({ namespace: bindings_1.BindingNamespaces.DATASOURCE });
+            },
+        });
+    }
+    /** REST only - the kernel has no gRPC (it reaches `node:module`). `BaseApplication` adds the gRPC branch on top. */
     async registerControllers() {
         await (0, core_1.executeWithPerformanceMeasure)({
             logger: this.logger,
@@ -180,39 +466,118 @@ class RestApplication extends abstract_1.AbstractApplication {
             },
         });
     }
-    controller(ctor, opts) {
-        return this.bind({
-            key: inversion_1.BindingKeys.build(opts?.binding ?? {
-                namespace: bindings_1.BindingNamespaces.CONTROLLER,
-                key: ctor.name,
-            }),
-        }).toClass(ctor);
-    }
-    service(ctor, opts) {
-        return this.bind({
-            key: inversion_1.BindingKeys.build(opts?.binding ?? {
-                namespace: bindings_1.BindingNamespaces.SERVICE,
-                key: ctor.name,
-            }),
-        }).toClass(ctor);
-    }
-    repository(ctor, opts) {
-        return this.bind({
-            key: inversion_1.BindingKeys.build(opts?.binding ?? {
-                namespace: bindings_1.BindingNamespaces.REPOSITORY,
-                key: ctor.name,
-            }),
-        }).toClass(ctor);
-    }
-    dataSource(ctor, opts) {
-        return this.bind({
-            key: inversion_1.BindingKeys.build(opts?.binding ?? {
-                namespace: bindings_1.BindingNamespaces.DATASOURCE,
-                key: ctor.name,
-            }),
-        })
-            .toClass(ctor)
-            .setScope(inversion_1.BindingScopes.SINGLETON);
+    /** SINGLETON like `component()`: `RestComponent` mounts the one instance it resolves, so a second resolution must be that instance, not an unmounted twin. */
+    controller(target, opts) {
+        return this.registerArtifact({
+            target,
+            namespace: bindings_1.BindingNamespaces.CONTROLLER,
+            defaultScope: inversion_1.BindingScopes.SINGLETON,
+            caller: this.controller.name,
+            opts,
+        });
+    }
+    service(target, opts) {
+        return this.registerArtifact({
+            target,
+            namespace: bindings_1.BindingNamespaces.SERVICE,
+            defaultScope: inversion_1.BindingScopes.TRANSIENT,
+            caller: this.service.name,
+            opts,
+        });
+    }
+    repository(target, opts) {
+        return this.registerArtifact({
+            target,
+            namespace: bindings_1.BindingNamespaces.REPOSITORY,
+            defaultScope: inversion_1.BindingScopes.TRANSIENT,
+            caller: this.repository.name,
+            opts,
+        });
+    }
+    dataSource(target, opts) {
+        return this.registerArtifact({
+            target,
+            namespace: bindings_1.BindingNamespaces.DATASOURCE,
+            defaultScope: inversion_1.BindingScopes.SINGLETON,
+            caller: this.dataSource.name,
+            opts,
+        });
+    }
+    /** The boot step body behind `configs.artifacts`, also callable by hand: registers every kind in dependency order across the given indexes. */
+    async registerArtifacts(index) {
+        const resolved = await artifact_index_1.ArtifactIndexHelper.getInstance().resolve({
+            input: index,
+            application: this,
+        });
+        for (const target of resolved.configurations) {
+            this.configuration(target);
+            this.bindProvidedKeys({ target });
+        }
+        for (const target of resolved.dataSources) {
+            this.dataSource(target);
+        }
+        for (const target of resolved.components) {
+            this.component(target);
+            this.bindProvidedKeys({ target });
+        }
+        for (const target of resolved.repositories) {
+            this.repository(target);
+        }
+        for (const target of resolved.services) {
+            this.service(target);
+        }
+        for (const target of resolved.controllers) {
+            this.controller(target);
+        }
+    }
+    /** Registers every class a stereotype decorated, with no `configs.artifacts` entry anywhere. `when` and `order` apply exactly as they do to a declared index - which is how one process running several applications keeps them apart. */
+    async registerDiscoveredArtifacts() {
+        await this.registerArtifacts(artifact_index_1.ArtifactIndexHelper.getInstance().buildDiscoveredIndex());
+    }
+    /**
+     * The artifact boot step. `configs.discoverArtifacts` adds every decorated class in the import
+     * graph; `configs.artifacts` adds exactly what it lists. Both together register the union.
+     *
+     * An absent `artifacts` still registers nothing. Reading it as "register everything" would change
+     * what an existing application boots with, silently, and the failure would surface as ten times
+     * the bindings rather than as an error.
+     */
+    async registerConfiguredArtifacts() {
+        const inputs = [];
+        if (this.configs.discoverArtifacts) {
+            inputs.push(artifact_index_1.ArtifactIndexHelper.getInstance().buildDiscoveredIndex());
+        }
+        if (this.configs.artifacts) {
+            inputs.push(this.configs.artifacts);
+        }
+        if (inputs.length === 0) {
+            return;
+        }
+        await this.registerArtifacts(inputs);
+    }
+    /** Each `@provide` method becomes a lazy provider: the component is resolved (SINGLETON) and the method called on first `get`, so a provided value may depend on datasources or secrets that do not exist yet at registration time. */
+    bindProvidedKeys(opts) {
+        const { target } = opts;
+        const registry = inversion_1.MetadataRegistry.getInstance();
+        const provides = registry.getProvideMetadata({ target });
+        if (provides.length === 0) {
+            return;
+        }
+        const declared = registry.getArtifactMetadata({ target });
+        const defaultNamespace = declared?.type
+            ? bindings_1.ArtifactNamespaces.resolve({ type: declared.type })
+            : bindings_1.BindingNamespaces.COMPONENT;
+        const componentKey = inversion_1.BindingKeys.build(declared?.binding ?? { namespace: defaultNamespace, key: target.name });
+        for (const entry of provides) {
+            this.bind({ key: entry.key })
+                .toProvider(container => {
+                const instance = container.get({
+                    key: componentKey,
+                });
+                return instance[entry.methodName]();
+            })
+                .setScope(entry.scope ?? inversion_1.BindingScopes.SINGLETON);
+        }
     }
     async registerDataSources() {
         await (0, core_1.executeWithPerformanceMeasure)({
@@ -224,6 +589,36 @@ class RestApplication extends abstract_1.AbstractApplication {
             },
         });
     }
+    /**
+     * Closes every datasource the boot configured, so a stopped application holds no pool, socket or
+     * WASM instance. A failure, or a `close()` still pending after `dataSourceCloseTimeoutMs`, is logged
+     * and never stops the rest. A datasource configured by hand is closed by whoever configured it.
+     */
+    async closeDataSources() {
+        const keys = this.registeredBindings[bindings_1.BindingNamespaces.DATASOURCE] ?? new Set();
+        const timeoutMs = this.configs.dataSourceCloseTimeoutMs ?? 10_000;
+        const logger = this.logger.for(this.closeDataSources.name);
+        for (const key of keys) {
+            try {
+                const dataSource = this.get({ key, isOptional: true });
+                if (!dataSource?.close) {
+                    logger.debug('Nothing to close | key: %s', key);
+                    continue;
+                }
+                const closing = dataSource.close();
+                await core_1.RetryHelper.runWithTimeout({ operation: key, timeoutMs, execution: () => closing });
+            }
+            catch (error) {
+                if (core_1.RetryHelper.isRetryTimeoutError(error)) {
+                    logger.error('Close timed out | key: %s | timeoutMs: %d', key, timeoutMs);
+                    continue;
+                }
+                logger.error('Failed to close datasource | key: %s | error: %s', key, error);
+                continue;
+            }
+            logger.info('Closed datasource | key: %s', key);
+        }
+    }
 }
 exports.RestApplication = RestApplication;
 //# sourceMappingURL=rest.js.map