sashiko 0.12.2 → 0.13.0

package/dist/core/app.js

@@ -1,88 +1,63 @@
-import { randomBytes, randomUUID } from 'node:crypto';
-import http from 'node:http';
-import https from 'node:https';
-import { compileTls } from '../server/tls.js';
-import { performance } from 'node:perf_hooks';
+import '../shims/symbol-metadata.js';
 import { childScope, joinPrefix, compileAutoRoutes, compileManualRoute, createGroup, ROOT_SCOPE, } from './compiler.js';
-import { RouteGroupScope } from './mounted-group.js';
-import { MountedGroup } from './mounted-group.js';
-import { compose } from './compose.js';
-import { Context, kAbort, kBindResponse, kPendingSend, kRawSend } from './context.js';
+import { MountedGroup, RouteGroupScope } from './mounted-group.js';
 import { staticHandler } from '../server/static.js';
-import { joinPaths } from '../utils/path.js';
-import { docsPage, generateOpenAPI } from '../openapi/generate.js';
+import { canonicalPath, joinPaths } from '../utils/path.js';
+import { generateOpenAPI } from '../openapi/generate.js';
 import { compileHealth } from './health.js';
-import '../shims/symbol-metadata.js';
-import { bodyParser } from './body-parser.js';
-import { assertSchemas, validateRequest } from './request-validation.js';
-import { problem, sendError, sendProblem, sendResult } from './response.js';
-import { RouteTable } from './route-table.js';
-import { canonicalPath } from '../utils/path.js';
 import { mediaType } from '../utils/content-type.js';
-import { compileHostMatcher, hostRank, hostReachability, NO_HOST_RANK } from '../utils/origin-match.js';
+import { compileHostMatcher } from '../utils/origin-match.js';
 import { inject } from './inject.js';
 import { guardsMiddleware } from './guard.js';
-import { shutdownCoordinator } from './shutdown.js';
 import { consoleLogger, silentLogger } from './logger.js';
 import { buildSecurityHeaders } from '../middlewares/security-headers.js';
-/** Registrar num grupo cujo callback já terminou é erro: o registro estaria fora da transação do grupo. */
+import { FrameworkRoutes } from './registry/framework-routes.js';
+import { RouteRegistry } from './registry/registry.js';
+import { RequestHandler } from './runtime/request-handler.js';
+import { ServerLifecycle } from './runtime/server.js';
 function assertOpen(scope) {
     if (scope.token && !scope.token.open) {
         throw new Error('[sashiko] app.group(): this group has already finished; register its routes inside the callback, synchronously.');
     }
 }
 const isThenable = (v) => (typeof v === 'object' || typeof v === 'function') && v !== null && typeof v.then === 'function';
-const SAFE_REQUEST_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+/**
+ * O app. É uma fachada (Facade) sobre o registro de rotas, as rotas do próprio framework (health, OpenAPI),
+ * o servidor e o pipeline da requisição: a API pública fica aqui, e o trabalho fica nesses componentes.
+ */
 export class SashikoApp {
-    middlewares = [];
-    router = new RouteTable();
-    errorHandlers = [];
-    onSendHooks = [];
-    onResponseHooks = [];
-    onCloseHooks = [];
-    routes = [];
-    /** Registros pendentes de um `group()` em andamento (duas fases). */
-    pending;
-    warnedHosts = new Set();
-    draining = false;
-    healthConfig;
-    openapiConfig;
-    closeHooksPending = true;
-    applySecurityHeaders;
-    opts;
-    allowedHosts;
-    serializers;
-    server;
-    tlsState;
-    /** Respostas em andamento, para o encerramento gracioso não travar em conexões keep-alive. */
-    inflight = new Set();
-    /** Contexto de cada resposta em andamento, para o shutdown encerrar os streams (F-13). */
-    contexts = new WeakMap();
-    closing;
-    /** Logger do app (F-06). Use para logs fora de uma requisição. */
     log;
+    core;
+    registry;
+    framework;
+    runtime;
+    requests;
     constructor(opts = {}) {
-        this.opts = opts;
-        // Compilado na criação: uma regra inválida falha aqui, e não na primeira requisição.
-        this.allowedHosts = opts.allowedHosts ? compileHostMatcher(opts.allowedHosts) : undefined;
-        this.serializers = new Map(Object.entries(opts.serializers ?? {}).map(([type, fn]) => [mediaType(type), fn]));
         this.log = opts.logger === false ? silentLogger : (opts.logger ?? consoleLogger());
-        const sd = opts.shutdown || {};
-        Object.assign(this.shutdownTarget, {
+        this.core = {
+            opts,
             log: this.log,
-            signals: sd.signals ?? ['SIGINT', 'SIGTERM'],
-            exitOnShutdown: sd.exit ?? true,
-        });
-        if (opts.securityHeaders !== false)
-            this.applySecurityHeaders = buildSecurityHeaders(opts.securityHeaders);
-        this.use(bodyParser(opts.bodyLimit ?? 1024 * 1024, opts.protoPoisoning));
+            middlewares: [],
+            errorHandlers: [],
+            onSendHooks: [],
+            onResponseHooks: [],
+            onCloseHooks: [],
+            // Compilados na criação: uma regra inválida falha aqui, e não na primeira requisição.
+            allowedHosts: opts.allowedHosts ? compileHostMatcher(opts.allowedHosts) : undefined,
+            serializers: new Map(Object.entries(opts.serializers ?? {}).map(([type, fn]) => [mediaType(type), fn])),
+            applySecurityHeaders: opts.securityHeaders !== false ? buildSecurityHeaders(opts.securityHeaders) : undefined,
+        };
+        this.registry = new RouteRegistry(this.core, () => this.framework.reservedPaths(), () => this.framework.openapi?.cache.clear());
+        this.framework = new FrameworkRoutes(this.core, this.registry);
+        this.runtime = new ServerLifecycle(this.core, () => this.callback());
+        this.requests = new RequestHandler(this.core, this.registry, this.framework, this.runtime);
     }
     use(mw) {
-        this.middlewares.push(mw);
+        this.core.middlewares.push(mw);
         return this;
     }
     onError(h) {
-        this.errorHandlers.push(h);
+        this.core.errorHandlers.push(h);
         return this;
     }
     /**
@@ -91,7 +66,7 @@ export class SashikoApp {
      * novos. Se lançar, o erro é logado e a resposta original é enviada (F-04).
      */
     onSend(hook) {
-        this.onSendHooks.push(hook);
+        this.core.onSendHooks.push(hook);
         return this;
     }
     /**
@@ -99,7 +74,7 @@ export class SashikoApp {
      * auditoria. Pode ser assíncrono; erros são só logados (F-04).
      */
     onResponse(hook) {
-        this.onResponseHooks.push(hook);
+        this.core.onResponseHooks.push(hook);
         return this;
     }
     /**
@@ -107,7 +82,7 @@ export class SashikoApp {
      * e antes do `shutdown.onShutdown`. Erros são logados e fazem o `close()` rejeitar ao final (F-04).
      */
     onClose(hook) {
-        this.onCloseHooks.push(hook);
+        this.core.onCloseHooks.push(hook);
         return this;
     }
     mount(ref, options = {}) {
@@ -135,10 +110,10 @@ export class SashikoApp {
         // Registro em duas fases: o que o callback registrar fica pendente e só é efetivado se ele terminar
         // de forma síncrona e sem erro. Grupos aninhados entram no lote do grupo mais externo; se um aninhado
         // falhar (mesmo com o erro capturado pelo externo), só a parte dele é descartada.
-        const outermost = this.pending === undefined;
+        const outermost = this.registry.pending === undefined;
         if (outermost)
-            this.pending = [];
-        const mark = this.pending.length;
+            this.registry.pending = [];
+        const mark = this.registry.pending.length;
         try {
             const result = define(new RouteGroupScope(this, scope));
             if (isThenable(result)) {
@@ -148,16 +123,16 @@ export class SashikoApp {
                 throw new Error('[sashiko] app.group(): the callback must be synchronous; do async work before registering routes.');
             }
             if (outermost)
-                this.commit(this.pending);
+                this.registry.commit(this.registry.pending);
         }
         catch (err) {
-            this.pending.length = mark;
+            this.registry.pending.length = mark;
             throw err;
         }
         finally {
             scope.token.open = false;
             if (outermost)
-                this.pending = undefined;
+                this.registry.pending = undefined;
         }
     }
     /**
@@ -195,16 +170,16 @@ export class SashikoApp {
         const routes = [route(joinPaths(base, '*'))];
         if (base !== '/')
             routes.push(route(base));
-        this.stage(`static('${prefix}')`, routes);
+        this.registry.stage(`static('${prefix}')`, routes);
     }
     /** @internal */
     mountIn(scope, ref, options = {}) {
         assertOpen(scope);
         const group = createGroup(ref, options, scope);
-        this.stage(group.name, compileAutoRoutes(group));
+        this.registry.stage(group.name, compileAutoRoutes(group));
         return new MountedGroup(this, group, (g, method, path, select, opts) => {
             assertOpen(scope);
-            this.stage(g.name, [compileManualRoute(g, method, path, select, opts)]);
+            this.registry.stage(g.name, [compileManualRoute(g, method, path, select, opts)]);
         }, scope);
     }
     /**
@@ -217,11 +192,11 @@ export class SashikoApp {
         const docs = opts.docs === true ? '/docs' : opts.docs || false;
         if (docs && canonicalPath(docs) === canonicalPath(path))
             throw new Error(`[sashiko] openapi(): "docs" and "path" cannot both be "${path}".`);
-        this.assertFreePaths('app.openapi()', docs ? [canonicalPath(path), canonicalPath(docs)] : [canonicalPath(path)], 'openapi');
+        this.framework.assertFreePaths('app.openapi()', docs ? [canonicalPath(path), canonicalPath(docs)] : [canonicalPath(path)], 'openapi');
         const pipeline = [...(opts.middlewares ?? [])];
         if (opts.guards?.length)
             pipeline.push(guardsMiddleware(opts.guards));
-        this.openapiConfig = { opts, path, docs, pipeline, cache: new Map() };
+        this.framework.openapi = { opts, path, docs, pipeline, cache: new Map() };
         return this;
     }
     /**
@@ -235,467 +210,45 @@ export class SashikoApp {
      */
     health(opts = {}) {
         const config = compileHealth(opts, this.log);
-        this.assertFreePaths('app.health()', config.paths, 'health');
-        this.healthConfig = config;
+        this.framework.assertFreePaths('app.health()', config.paths, 'health');
+        this.framework.health = config;
         return this;
     }
-    /** Paths servidos pelo próprio app (`health()`, `openapi()`), que encobririam uma rota GET do usuário. */
-    reservedPaths(except) {
-        const out = new Map();
-        if (except !== 'health')
-            for (const p of this.healthConfig?.paths ?? [])
-                out.set(p, 'app.health()');
-        const cfg = this.openapiConfig;
-        if (cfg && except !== 'openapi') {
-            out.set(canonicalPath(cfg.path), 'app.openapi()');
-            if (cfg.docs)
-                out.set(canonicalPath(cfg.docs), 'app.openapi({ docs })');
-        }
-        return out;
-    }
-    /** Um path do framework não pode coincidir com uma rota GET/HEAD registrada nem com outro do framework. */
-    assertFreePaths(where, paths, kind) {
-        // `health()`/`openapi()` configuram o app, não o grupo: dentro de um `group()` em andamento, a
-        // configuração sobreviveria a um grupo desfeito e não enxergaria as rotas ainda pendentes.
-        if (this.pending !== undefined) {
-            throw new Error(`[sashiko] ${where}: cannot be called inside an app.group() callback; call it on the app, outside the group.`);
-        }
-        const reserved = this.reservedPaths(kind);
-        for (const path of paths) {
-            const other = reserved.get(path);
-            if (other)
-                throw new Error(`[sashiko] ${where}: path "${path}" is already used by ${other}.`);
-            const route = this.routes.find((r) => (r.method === 'GET' || r.method === 'HEAD') && canonicalPath(r.path) === path);
-            if (route) {
-                throw new Error(`[sashiko] ${where}: path "${path}" would shadow ${route.owner}.${route.handlerName} (GET ${route.path}); choose another path.`);
-            }
-        }
-    }
     /**
      * Documento OpenAPI 3.1 das rotas registradas até agora, para gravar em arquivo ou testar (F-16).
      * Com virtual hosts, é por host (F-35): `{ host: 'api.exemplo.com' }` traz as rotas desse host e as sem
      * host; sem `host`, só as sem host. Domínios diferentes nunca se misturam num mesmo documento.
      */
-    openapiDocument(opts = this.openapiConfig?.opts ?? {}) {
-        return generateOpenAPI(this.routesFor(opts.host?.toLowerCase()), opts, !this.opts.formatError);
-    }
-    /**
-     * Rotas que o roteador **executaria** num host (F-35): para cada método e path, só a vencedora pela mesma
-     * prioridade do roteador (exato → curinga mais específico → RegExp → sem host). Assim o OpenAPI documenta
-     * exatamente o handler que responde. Sem `hostname`, só as rotas sem host.
-     */
-    routesFor(hostname) {
-        const best = new Map();
-        for (const [seq, route] of this.routes.entries()) {
-            let rank = route.hosts.length === 0 ? NO_HOST_RANK : -1;
-            if (rank === -1 && hostname !== undefined) {
-                for (const h of route.hosts) {
-                    if (!h.test(hostname))
-                        continue;
-                    // Desempate pela ordem de registro, a mesma que o roteador usa em cada path.
-                    const r = hostRank(h, seq);
-                    if (rank === -1 || r < rank)
-                        rank = r;
-                }
-            }
-            if (rank === -1)
-                continue;
-            const key = `${route.method} ${canonicalPath(route.path)}`;
-            const current = best.get(key);
-            if (!current || rank < current.rank)
-                best.set(key, { route, rank });
-        }
-        return this.routes.filter((r) => best.get(`${r.method} ${canonicalPath(r.path)}`)?.route === r);
-    }
-    /** Se a requisição é para `/openapi.json` ou `/docs` (quando ligados), responde e devolve `true`. */
-    async serveOpenAPI(ctx) {
-        const cfg = this.openapiConfig;
-        if (!cfg || (ctx.method !== 'GET' && ctx.method !== 'HEAD'))
-            return false;
-        const path = canonicalPath(ctx.path);
-        const isSpec = path === canonicalPath(cfg.path);
-        if (!isSpec && !(cfg.docs && path === canonicalPath(cfg.docs)))
-            return false;
-        await compose(ctx, [
-            ...cfg.pipeline,
-            () => {
-                if (isSpec) {
-                    // Um documento por conjunto de rotas visíveis no host da requisição (F-35); a chave não usa o
-                    // hostname em si, então hosts arbitrários não fazem o cache crescer.
-                    const visible = this.routesFor(ctx.hostname.toLowerCase());
-                    const key = visible.map((r) => this.routes.indexOf(r)).join(',');
-                    let doc = cfg.cache.get(key);
-                    if (doc === undefined) {
-                        doc = JSON.stringify(generateOpenAPI(visible, cfg.opts, !this.opts.formatError));
-                        cfg.cache.set(key, doc);
-                    }
-                    ctx[kRawSend](doc, 'application/json; charset=utf-8');
-                    return;
-                }
-                const nonce = randomBytes(16).toString('base64');
-                const { html, csp } = docsPage(cfg.path, cfg.opts.info?.title ?? 'API', nonce);
-                ctx.res.setHeader('Content-Security-Policy', csp);
-                ctx.res.setHeader('Cache-Control', 'no-store');
-                ctx[kRawSend](html, 'text/html; charset=utf-8');
-            },
-        ]);
-        return true;
-    }
-    /**
-     * Primeira fase: valida as rotas (schemas obrigatórios, hosts alcançáveis, conflitos com o roteador e
-     * dentro do próprio lote). Dentro de um `group()`, acumula; fora, efetiva na hora.
-     */
-    stage(owner, routes) {
-        const batch = this.pending ?? [];
-        // Checkpoint: dentro de um group(), um mount() que falha no meio não deixa parte dele no lote,
-        // mesmo que o callback capture o erro e siga em frente.
-        const mark = batch.length;
-        try {
-            for (const route of routes) {
-                // Rotas internas (static) não têm schema por natureza: o requireSchemas vale para as da aplicação.
-                if (this.opts.requireSchemas && !route.internal)
-                    assertSchemas(owner, route);
-                if (route.method === 'GET' || route.method === 'HEAD') {
-                    const reservedBy = this.reservedPaths().get(canonicalPath(route.path));
-                    if (reservedBy) {
-                        throw new Error(`[sashiko] app.mount(${owner}): GET ${route.path} is served by ${reservedBy} and would never be reached; choose another path.`);
-                    }
-                }
-                this.checkReachableHosts(owner, route);
-                for (const host of route.hosts.length > 0 ? route.hosts.map((h) => h.key) : [undefined]) {
-                    const taken = this.router.has(route.method, route.path, host) ||
-                        batch.some((p) => p.route.method === route.method && canonicalPath(p.route.path) === canonicalPath(route.path) && p.hosts.includes(host));
-                    if (taken) {
-                        const where = host ? ` on host ${host}` : '';
-                        throw new Error(`[sashiko] app.mount(${owner}): ${route.method} ${route.path}${where} is already registered. ` +
-                            `Use a different "prefix" or "host" to mount the same class twice.`);
-                    }
-                }
-                batch.push({ owner, route, hosts: route.hosts.length > 0 ? route.hosts.map((h) => h.key) : [undefined] });
-            }
-        }
-        catch (err) {
-            batch.length = mark;
-            throw err;
-        }
-        if (this.pending === undefined)
-            this.commit(batch);
-    }
-    /**
-     * Segunda fase: registra o lote no roteador. Se algo ainda falhar (um conflito que o `has()` não prevê),
-     * desfaz o que já entrou, e nenhuma rota do lote fica registrada.
-     */
-    commit(batch) {
-        const done = [];
-        try {
-            for (const { owner, route, hosts } of batch) {
-                for (const host of hosts) {
-                    try {
-                        this.router.on(route.method, route.path, route, host);
-                    }
-                    catch (err) {
-                        throw new Error(`[sashiko] app.mount(${owner}): ${route.method} ${route.path} conflicts with a registered route.`, {
-                            cause: err,
-                        });
-                    }
-                    done.push({ method: route.method, path: route.path, host });
-                }
-            }
-        }
-        catch (err) {
-            for (const r of done.reverse())
-                this.router.off(r.method, r.path, r.host);
-            throw err;
-        }
-        for (const { route } of batch)
-            this.routes.push(route);
-        if (this.openapiConfig && batch.length > 0)
-            this.openapiConfig.cache.clear();
-    }
-    /**
-     * Um host de rota sem interseção com o `allowedHosts` nunca seria alcançado: o app responde 400 antes do
-     * roteamento (F-35). Comprovado: erro (ou aviso, com `unreachableHosts: 'warn'`). Sem como provar
-     * (RegExp em algum dos lados): aviso.
-     */
-    checkReachableHosts(owner, route) {
-        const mode = this.opts.unreachableHosts ?? 'error';
-        const allowed = this.opts.allowedHosts;
-        if (mode === 'off' || !allowed)
-            return;
-        for (const host of route.hosts) {
-            const verdict = hostReachability(host, allowed);
-            if (verdict === 'yes')
-                continue;
-            const where = `app.mount(${owner}): ${route.method} ${route.path} uses host ${host.label}`;
-            if (verdict === 'no' && mode === 'error') {
-                throw new Error(`[sashiko] ${where}, which no allowedHosts rule accepts; the route is unreachable. Add it to allowedHosts, or set unreachableHosts: 'warn'.`);
-            }
-            const key = `${owner} ${host.key}`;
-            if (this.warnedHosts.has(key))
-                continue;
-            this.warnedHosts.add(key);
-            this.log.warn({ host: host.label }, verdict === 'no'
-                ? `[sashiko] ${where}, which no allowedHosts rule accepts; the route is unreachable.`
-                : `[sashiko] ${where}; could not verify it against allowedHosts (RegExp).`);
-        }
+    openapiDocument(opts = this.framework.openapi?.opts ?? {}) {
+        return generateOpenAPI(this.registry.routesFor(opts.host?.toLowerCase()), opts, !this.core.opts.formatError);
     }
-    async handle(ctx) {
-        // Antes de tudo, para valer inclusive em erros, 404 e preflight (S-04).
-        this.applySecurityHeaders?.(ctx.res);
-        try {
-            // Healthchecks antes dos middlewares globais: sondas do load balancer não têm credenciais.
-            if (this.healthConfig && (await this.healthConfig.serve(ctx, this.draining || this.closing !== undefined)))
-                return;
-            await compose(ctx, this.middlewares);
-            if (ctx.sent || (await this.serveOpenAPI(ctx)))
-                return;
-            // F-35: hosts não diferenciam maiúsculas; as regras já são compiladas em minúsculas.
-            const hostname = ctx.hostname.toLowerCase();
-            const match = this.router.find(ctx.method, ctx.path, hostname);
-            if (!match) {
-                const allowed = this.router.allowedMethods(ctx.path, hostname);
-                if (allowed.length > 0) {
-                    ctx.res.setHeader('Allow', allowed.join(', '));
-                    // F-08: OPTIONS automático para qualquer path com rotas.
-                    if (ctx.method === 'OPTIONS')
-                        return void ctx.status(204).res.end();
-                    return void sendProblem(ctx, problem(405, undefined, { code: 'METHOD_NOT_ALLOWED', details: { allowed } }), this.opts.formatError);
-                }
-                return void sendProblem(ctx, problem(404, undefined, { code: 'NOT_FOUND' }), this.opts.formatError);
-            }
-            ctx.params = match.params;
-            // F-01: middlewares → guards → validação → handler. Guards antes da validação, para que
-            // quem não tem acesso receba 401/403 e não um 400 que revele a estrutura esperada.
-            const route = match;
-            const pipeline = [...route.middlewares];
-            if (route.guards.length > 0)
-                pipeline.push(guardsMiddleware(route.guards));
-            pipeline.push(async () => {
-                validateRequest(ctx, route.schemas);
-                // F-32: a partir daqui, ctx.json/send/text passam pelo mesmo pipeline do `return`.
-                ctx[kBindResponse](route.schemas.response, this.serializers);
-                const result = await route.handler(ctx);
-                if (ctx[kPendingSend])
-                    await ctx[kPendingSend];
-                if (!ctx.sent)
-                    sendResult(ctx, route.schemas.response, result, this.serializers);
-            });
-            await compose(ctx, pipeline);
-        }
-        catch (err) {
-            await this.runErrorHandlers(err, ctx);
-        }
-    }
-    /**
-     * Executa os `onError` do usuário. Se um deles lançar, o erro é logado e seguimos
-     * para a resposta padrão com o erro **original** — nunca deixamos a Promise rejeitar (B-08).
-     */
-    async runErrorHandlers(err, ctx) {
-        for (const h of this.errorHandlers) {
-            try {
-                await h(err, ctx);
-            }
-            catch (handlerErr) {
-                ctx.log.error({ err: handlerErr, method: ctx.method, path: ctx.path }, 'onError handler failed');
-                break;
-            }
-            if (ctx.res.writableEnded)
-                return;
-        }
-        sendError(ctx, err, this.opts.formatError);
+    /** Executa o pipeline completo para um contexto já criado. */
+    handle(ctx) {
+        return this.requests.handle(ctx);
     }
     /**
      * Listener `(req, res)` do app, para usar com qualquer servidor do Node:
      * `https.createServer(opts, app.callback())`, `http2` em modo compat, testes etc. (F-09).
      */
     callback() {
-        const rid = this.opts.requestId ?? {};
-        const header = rid.header === false ? undefined : (rid.header ?? 'x-request-id').toLowerCase();
-        const trust = rid.trustIncoming ?? true;
-        const generate = rid.generate ?? (() => randomUUID());
-        return (req, res) => {
-            const started = performance.now();
-            this.inflight.add(res);
-            if (this.closing)
-                res.setHeader('Connection', 'close');
-            res.once('close', () => {
-                this.inflight.delete(res);
-                // Durante o close(), cada resposta concluída libera as conexões que ficaram ociosas.
-                this.closing?.closeIdleConnections();
-            });
-            const incoming = header ? req.headers[header] : undefined;
-            const id = trust && typeof incoming === 'string' && SAFE_REQUEST_ID.test(incoming) ? incoming : generate();
-            if (header)
-                res.setHeader(header, id);
-            // Última barreira (B-08): nada que aconteça numa requisição pode virar unhandledRejection.
-            const fail = (err) => {
-                this.log.error({ err, reqId: id, method: req.method, url: req.url }, 'unhandled error while handling request');
-                if (!res.headersSent)
-                    res.statusCode = 500;
-                if (!res.writableEnded)
-                    res.end();
-            };
-            try {
-                const ctx = new Context(req, res, {
-                    queryMaxKeys: this.opts.queryMaxKeys,
-                    id,
-                    logger: this.log,
-                    trustProxy: this.opts.trustProxy,
-                    onSend: this.onSendHooks,
-                });
-                this.contexts.set(res, ctx);
-                // S-09: Host ausente, malformado ou fora da lista permitida → 400, antes de qualquer middleware.
-                // Exceção: healthchecks aceitam qualquer host válido, porque sondas chegam com o IP do pod.
-                const healthProbe = this.healthConfig?.bypassesHostCheck(ctx.method, ctx.path) ?? false;
-                if (!ctx.host || (this.allowedHosts && !healthProbe && !this.allowedHosts(ctx.hostname, ctx.host))) {
-                    this.applySecurityHeaders?.(res);
-                    sendProblem(ctx, problem(400, 'Invalid Host header', { code: 'INVALID_HOST' }), this.opts.formatError);
-                    return;
-                }
-                if (this.opts.logRequests || this.onResponseHooks.length > 0) {
-                    res.once('finish', () => {
-                        const ms = Math.round((performance.now() - started) * 100) / 100;
-                        if (this.opts.logRequests) {
-                            ctx.log.info({ method: ctx.method, path: ctx.path, status: res.statusCode, ms }, 'request completed');
-                        }
-                        for (const hook of this.onResponseHooks) {
-                            Promise.resolve()
-                                .then(() => hook(ctx, { status: res.statusCode, ms }))
-                                .catch((err) => ctx.log.error({ err }, 'onResponse hook failed'));
-                        }
-                    });
-                }
-                this.handle(ctx).catch(fail);
-            }
-            catch (err) {
-                fail(err);
-            }
-        };
+        return this.requests.callback();
     }
-    async listen(options = {}) {
-        if (this.server)
-            throw new Error('[sashiko] app is already listening; call app.close() first.');
-        const { port = 3000, host = '127.0.0.1', tls } = typeof options === 'number' ? { port: options } : options;
-        let server;
-        if (tls) {
-            const sni = { current: { find: () => undefined } };
-            const compiled = compileTls(tls, sni);
-            server = https.createServer(compiled.options, this.callback());
-            this.tlsState = { sni };
-        }
-        else {
-            server = http.createServer(this.callback());
-            this.tlsState = undefined;
-        }
-        const t = this.opts.timeouts ?? {};
-        server.requestTimeout = t.requestTimeout ?? 30_000;
-        server.headersTimeout = Math.min(t.headersTimeout ?? 10_000, server.requestTimeout || Infinity);
-        server.keepAliveTimeout = t.keepAliveTimeout ?? 5_000;
-        await new Promise((resolve, reject) => {
-            server.once('error', reject);
-            server.listen(port, host, () => {
-                server.off('error', reject);
-                resolve();
-            });
-        });
-        this.server = server;
-        this.closeHooksPending = true;
-        this.draining = false;
-        if (this.opts.shutdown !== false)
-            shutdownCoordinator.register(this.shutdownTarget);
-        return server;
+    listen(options = {}) {
+        return this.runtime.listen(options);
     }
     /**
      * Troca os certificados sem reiniciar nem derrubar conexões (renovação, ACME externo). Conexões novas
      * usam os novos; as abertas seguem com os antigos. Um certificado inválido lança erro e mantém os atuais.
      */
     reloadTLS(tls) {
-        const server = this.server;
-        if (!server || !this.tlsState || !(server instanceof https.Server)) {
-            throw new Error('[sashiko] reloadTLS(): the app is not listening with { tls }.');
-        }
-        const next = { current: this.tlsState.sni.current };
-        const compiled = compileTls(tls, next); // valida tudo antes de trocar
-        if (compiled.main)
-            server.setSecureContext(compiled.main);
-        this.tlsState.sni.current = next.current;
+        this.runtime.reloadTLS(tls);
     }
-    /** Ponte entre este app e o coordenador de sinais (F-07). */
-    shutdownTarget = {
-        log: undefined, // definido no construtor
-        signals: [],
-        exitOnShutdown: true,
-        shutdown: async (signal) => {
-            const opts = this.opts.shutdown || {};
-            try {
-                this.draining = true;
-                if (opts.drainDelayMs) {
-                    this.log.info({ signal, drainDelayMs: opts.drainDelayMs }, 'draining before shutdown');
-                    await new Promise((r) => setTimeout(r, opts.drainDelayMs));
-                }
-                await this.close(opts.timeoutMs ?? 10_000);
-                await opts.onShutdown?.(signal);
-                return true;
-            }
-            catch (err) {
-                this.log.error({ err, signal }, 'error during graceful shutdown');
-                return false;
-            }
-        },
-    };
     /**
      * Para de aceitar conexões, encerra as ociosas e espera as requisições em andamento terminarem.
      * Depois de `graceMs`, força o fechamento das restantes.
      */
-    async close(graceMs = 10_000) {
-        const server = this.server;
-        if (!server)
-            return this.runCloseHooks();
-        this.server = undefined;
-        this.closing = server;
-        // Respostas que ainda não enviaram headers avisam o cliente para não reusar a conexão.
-        for (const res of this.inflight)
-            if (!res.headersSent)
-                res.setHeader('Connection', 'close');
-        // Streams longos (SSE, NDJSON) não terminam sozinhos: o `ctx.signal` é cancelado para eles fecharem
-        // já, em vez de segurar o encerramento até o prazo. Requisições comuns seguem até terminar.
-        for (const res of this.inflight) {
-            const ctx = this.contexts.get(res);
-            if (ctx?.streamingResponse)
-                ctx[kAbort]('server shutting down');
-        }
-        const force = setTimeout(() => server.closeAllConnections(), graceMs);
-        force.unref();
-        try {
-            await new Promise((resolve, reject) => {
-                server.close((err) => (err ? reject(err) : resolve()));
-                server.closeIdleConnections();
-            });
-        }
-        finally {
-            clearTimeout(force);
-            this.closing = undefined;
-            shutdownCoordinator.unregister(this.shutdownTarget);
-        }
-        await this.runCloseHooks();
-    }
-    /** `onClose` uma vez por ciclo (até o próximo `listen`); todos rodam mesmo se algum falhar (F-04). */
-    async runCloseHooks() {
-        if (!this.closeHooksPending)
-            return;
-        this.closeHooksPending = false;
-        const errors = [];
-        for (const hook of this.onCloseHooks) {
-            try {
-                await hook();
-            }
-            catch (err) {
-                errors.push(err);
-                this.log.error({ err }, 'onClose hook failed');
-            }
-        }
-        if (errors.length > 0)
-            throw new AggregateError(errors, `[sashiko] ${errors.length} onClose hook(s) failed`);
+    close(graceMs = 10_000) {
+        return this.runtime.close(graceMs);
     }
     /** Executa uma requisição em memória, sem rede. Ideal para testes (F-09). */
     inject(opts) {