flowingts 0.0.0 → 0.19.0

package/dist/core/streaming/sse.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Server-Sent Events (F-13). Fica fora do `Context`, que só delega: o modelo da requisição não carrega a
+ * lógica de cada forma de envio.
+ */
+import type { Context } from '../context.ts';
+/** Um evento de Server-Sent Events (F-13). `data` em objeto vira JSON; strings com várias linhas são divididas. */
+export interface SseEvent {
+    data: unknown;
+    event?: string;
+    id?: string;
+    /** Sugestão de espera para o navegador reconectar, em ms. */
+    retry?: number;
+}
+/** Conexão SSE aberta por `ctx.sse()`. */
+export interface SseStream {
+    send(event: SseEvent | string): void;
+    /** Comentário (`: texto`), ignorado pelo navegador; útil como keep-alive. */
+    comment(text: string): void;
+    /** Encerra a resposta. */
+    close(): void;
+    /** Chamado quando a conexão termina: o cliente desconectou, `close()` ou encerramento do app. */
+    onClose(listener: () => void): void;
+    readonly closed: boolean;
+    /** `Last-Event-ID` enviado pelo navegador ao reconectar. */
+    readonly lastEventId: string | undefined;
+}
+export interface SseOptions {
+    /** Comentário periódico para proxies não derrubarem a conexão ociosa. Padrão: 15000 ms; `0` desliga. */
+    heartbeatMs?: number;
+    /** `retry:` enviado na abertura. */
+    retry?: number;
+}
+/** Abre a conexão SSE de `ctx`. `markStreaming` marca a resposta como stream (estado privado do `Context`). */
+export declare function openSse(ctx: Context, opts: SseOptions, markStreaming: () => void): SseStream;
+//# sourceMappingURL=sse.d.ts.map

package/dist/core/streaming/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../../src/core/streaming/sse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,mHAAmH;AACnH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0CAA0C;AAC1C,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAC;IACrC,6EAA6E;IAC7E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,0BAA0B;IAC1B,KAAK,IAAI,IAAI,CAAC;IACd,iGAAiG;IACjG,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED,MAAM,WAAW,UAAU;IACzB,wGAAwG;IACxG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAoCD,+GAA+G;AAC/G,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,IAAI,GAAG,SAAS,CAqE5F"}

package/dist/core/streaming/sse.js

@@ -0,0 +1,121 @@
+/**
+ * Campos de uma linha SSE não podem ter quebra de linha (seria injeção de evento); `id` também não pode
+ * ter U+0000, que faz o navegador ignorar o campo.
+ */
+const sseField = (name, value) => {
+    if (/[\r\n]/.test(value))
+        throw new Error(`[flowing] ctx.sse(): "${name}" cannot contain line breaks.`);
+    if (name === 'id' && value.includes('\0'))
+        throw new Error('[flowing] ctx.sse(): "id" cannot contain U+0000.');
+    return `${name}: ${value}\n`;
+};
+/** Maior intervalo dos timers do Node; acima disso, ele usa 1 ms (heartbeat contínuo). */
+const MAX_TIMER_MS = 2_147_483_647;
+/** `retry` e `heartbeatMs`: inteiro não negativo, como o protocolo exige, e dentro do limite dos timers. */
+const nonNegativeInt = (name, value) => {
+    if (!Number.isInteger(value) || value < 0 || value > MAX_TIMER_MS) {
+        throw new Error(`[flowing] ctx.sse(): "${name}" must be an integer between 0 and ${MAX_TIMER_MS} (got ${value}).`);
+    }
+    return value;
+};
+/** `data` do evento: strings como estão; o resto em JSON. Valor que não vira JSON gera erro claro, sem escrever nada. */
+function sseData(data) {
+    if (typeof data === 'string')
+        return data;
+    let text;
+    try {
+        text = JSON.stringify(data);
+    }
+    catch (err) {
+        throw new Error(`[flowing] ctx.sse(): "data" is not JSON-serializable (${err.message}).`, { cause: err });
+    }
+    if (text === undefined)
+        throw new Error(`[flowing] ctx.sse(): "data" of type ${typeof data} is not JSON-serializable.`);
+    return text;
+}
+/** Abre a conexão SSE de `ctx`. `markStreaming` marca a resposta como stream (estado privado do `Context`). */
+export function openSse(ctx, opts, markStreaming) {
+    if (ctx.sent)
+        throw new Error('[flowing] ctx.sse(): the response was already sent.');
+    // Valida antes de abrir a resposta: um erro aqui ainda vira um 500 normal.
+    const heartbeatMs = nonNegativeInt('heartbeatMs', opts.heartbeatMs ?? 15_000);
+    if (opts.retry !== undefined)
+        nonNegativeInt('retry', opts.retry);
+    const res = ctx.res;
+    markStreaming();
+    res.statusCode = 200;
+    res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
+    res.setHeader('Cache-Control', 'no-cache, no-transform');
+    res.setHeader('X-Accel-Buffering', 'no');
+    res.removeHeader('Content-Length');
+    res.flushHeaders();
+    const listeners = [];
+    let closed = false;
+    const finish = () => {
+        if (closed)
+            return;
+        closed = true;
+        clearInterval(heartbeat);
+        for (const l of listeners.splice(0)) {
+            try {
+                l();
+            }
+            catch (err) {
+                ctx.log.error({ err }, 'sse onClose listener failed');
+            }
+        }
+    };
+    const write = (chunk) => {
+        if (!closed && !res.writableEnded)
+            res.write(chunk);
+    };
+    const heartbeat = setInterval(() => write(': ping\n\n'), heartbeatMs || 2 ** 31 - 1);
+    heartbeat.unref();
+    if (!heartbeatMs)
+        clearInterval(heartbeat);
+    res.once('close', finish);
+    const signal = ctx.signal;
+    signal.addEventListener('abort', () => stream.close(), { once: true });
+    if (opts.retry !== undefined)
+        write(`retry: ${opts.retry}\n\n`);
+    const stream = {
+        send: (event) => {
+            const e = typeof event === 'string' ? { data: event } : event;
+            let out = '';
+            if (e.event !== undefined)
+                out += sseField('event', e.event);
+            if (e.id !== undefined)
+                out += sseField('id', e.id);
+            if (e.retry !== undefined)
+                out += `retry: ${nonNegativeInt('retry', e.retry)}\n`;
+            if (e.data === undefined)
+                throw new Error('[flowing] ctx.sse(): "data" is required; use "" for an empty event.');
+            const text = sseData(e.data);
+            for (const line of text.split(/\r\n|\r|\n/))
+                out += `data: ${line}\n`;
+            write(`${out}\n`);
+        },
+        comment: (text) => write(`: ${text.replace(/[\r\n]+/g, ' ')}\n\n`),
+        close: () => {
+            if (!res.writableEnded)
+                res.end();
+            finish();
+        },
+        onClose: (listener) => {
+            if (closed)
+                listener();
+            else
+                listeners.push(listener);
+        },
+        get closed() {
+            return closed;
+        },
+        lastEventId: ctx.get('last-event-id'),
+    };
+    // O cliente pode ter desconectado antes do `ctx.sse()` (num `await` anterior): o 'close' e o 'abort' já
+    // passaram, e os listeners acima nunca rodariam. Encerra já, limpando o heartbeat e chamando `onClose`.
+    if (signal.aborted)
+        stream.close();
+    return stream;
+}
+//# sourceMappingURL=sse.js.map

package/dist/core/streaming/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../../src/core/streaming/sse.ts"],"names":[],"mappings":"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"}

package/dist/core/symbols.d.ts

@@ -0,0 +1,28 @@
+/** Símbolos internos do core. Ficam num módulo próprio para quem os usa não depender do `Context` em tempo de execução. */
+/** @internal Envio cru, sem pipeline: usado pelo próprio pipeline, por erros e por 404/405. */
+export declare const kRawSend: unique symbol;
+/** @internal Cancela o `ctx.signal` (encerramento do app) (F-13). */
+export declare const kAbort: unique symbol;
+/** @internal Envio de arquivo em andamento, que o app aguarda mesmo sem `await` no handler (F-13). */
+export declare const kPendingSend: unique symbol;
+/** @internal Liga o contexto aos schemas de resposta da rota, antes do handler (F-32). */
+export declare const kBindResponse: unique symbol;
+/** @internal A cadeia global chegou ao roteamento (o último middleware chamou `next()`). */
+export declare const kRouted: unique symbol;
+/** @internal A rota que atendeu a requisição (`ctx.route`, F-38). */
+export declare const kRoute: unique symbol;
+/** @internal O erro tratado pelo pipeline de erros, para o `onResponse` (F-38). */
+export declare const kError: unique symbol;
+/** @internal Em que etapa a requisição está, para a fase do `onError` (F-38). */
+export declare const kPhase: unique symbol;
+/** @internal Estado do `telemetry` de uma requisição (F-38). */
+export declare const kTelemetry: unique symbol;
+/** @internal Instante em que os headers da resposta saíram, para o `ttfbMs` (F-38). */
+export declare const kHeadersAt: unique symbol;
+/** @internal Hooks com escopo da rota, guardados no `RouteInfo` de cada host (F-43). */
+export declare const kHooks: unique symbol;
+/** @internal O motor dos contratos do app (`contracts`, F-27), lido pelo pipeline de resposta. */
+export declare const kContracts: unique symbol;
+/** @internal Arquivos recebidos de um upload (F-46), lidos por `ctx.file()`/`ctx.files()`. */
+export declare const kFiles: unique symbol;
+//# sourceMappingURL=symbols.d.ts.map

package/dist/core/symbols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbols.d.ts","sourceRoot":"","sources":["../../src/core/symbols.ts"],"names":[],"mappings":"AAAA,2HAA2H;AAE3H,+FAA+F;AAC/F,eAAO,MAAM,QAAQ,eAA4B,CAAC;AAClD,qEAAqE;AACrE,eAAO,MAAM,MAAM,eAA0B,CAAC;AAC9C,sGAAsG;AACtG,eAAO,MAAM,YAAY,eAAgC,CAAC;AAC1D,0FAA0F;AAC1F,eAAO,MAAM,aAAa,eAAiC,CAAC;AAC5D,4FAA4F;AAC5F,eAAO,MAAM,OAAO,eAA2B,CAAC;AAChD,qEAAqE;AACrE,eAAO,MAAM,MAAM,eAA0B,CAAC;AAC9C,mFAAmF;AACnF,eAAO,MAAM,MAAM,eAA0B,CAAC;AAC9C,iFAAiF;AACjF,eAAO,MAAM,MAAM,eAA0B,CAAC;AAC9C,gEAAgE;AAChE,eAAO,MAAM,UAAU,eAA8B,CAAC;AACtD,uFAAuF;AACvF,eAAO,MAAM,UAAU,eAA8B,CAAC;AACtD,wFAAwF;AACxF,eAAO,MAAM,MAAM,eAA0B,CAAC;AAC9C,kGAAkG;AAClG,eAAO,MAAM,UAAU,eAA8B,CAAC;AACtD,8FAA8F;AAC9F,eAAO,MAAM,MAAM,eAA0B,CAAC"}

package/dist/core/symbols.js

@@ -0,0 +1,28 @@
+/** Símbolos internos do core. Ficam num módulo próprio para quem os usa não depender do `Context` em tempo de execução. */
+/** @internal Envio cru, sem pipeline: usado pelo próprio pipeline, por erros e por 404/405. */
+export const kRawSend = Symbol('flowing.rawSend');
+/** @internal Cancela o `ctx.signal` (encerramento do app) (F-13). */
+export const kAbort = Symbol('flowing.abort');
+/** @internal Envio de arquivo em andamento, que o app aguarda mesmo sem `await` no handler (F-13). */
+export const kPendingSend = Symbol('flowing.pendingSend');
+/** @internal Liga o contexto aos schemas de resposta da rota, antes do handler (F-32). */
+export const kBindResponse = Symbol('flowing.bindResponse');
+/** @internal A cadeia global chegou ao roteamento (o último middleware chamou `next()`). */
+export const kRouted = Symbol('flowing.routed');
+/** @internal A rota que atendeu a requisição (`ctx.route`, F-38). */
+export const kRoute = Symbol('flowing.route');
+/** @internal O erro tratado pelo pipeline de erros, para o `onResponse` (F-38). */
+export const kError = Symbol('flowing.error');
+/** @internal Em que etapa a requisição está, para a fase do `onError` (F-38). */
+export const kPhase = Symbol('flowing.phase');
+/** @internal Estado do `telemetry` de uma requisição (F-38). */
+export const kTelemetry = Symbol('flowing.telemetry');
+/** @internal Instante em que os headers da resposta saíram, para o `ttfbMs` (F-38). */
+export const kHeadersAt = Symbol('flowing.headersAt');
+/** @internal Hooks com escopo da rota, guardados no `RouteInfo` de cada host (F-43). */
+export const kHooks = Symbol('flowing.hooks');
+/** @internal O motor dos contratos do app (`contracts`, F-27), lido pelo pipeline de resposta. */
+export const kContracts = Symbol('flowing.contracts');
+/** @internal Arquivos recebidos de um upload (F-46), lidos por `ctx.file()`/`ctx.files()`. */
+export const kFiles = Symbol('flowing.files');
+//# sourceMappingURL=symbols.js.map

package/dist/core/symbols.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbols.js","sourceRoot":"","sources":["../../src/core/symbols.ts"],"names":[],"mappings":"AAAA,2HAA2H;AAE3H,+FAA+F;AAC/F,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAClD,qEAAqE;AACrE,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;AAC9C,sGAAsG;AACtG,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;AAC1D,0FAA0F;AAC1F,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAC5D,4FAA4F;AAC5F,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAChD,qEAAqE;AACrE,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;AAC9C,mFAAmF;AACnF,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;AAC9C,iFAAiF;AACjF,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;AAC9C,gEAAgE;AAChE,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;AACtD,uFAAuF;AACvF,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;AACtD,wFAAwF;AACxF,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;AAC9C,kGAAkG;AAClG,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;AACtD,8FAA8F;AAC9F,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC"}

package/dist/core/telemetry.d.ts

@@ -0,0 +1,83 @@
+/**
+ * OpenTelemetry nativo por injeção (F-38): `createApp({ telemetry: otel })`, com o `@opentelemetry/api` que a
+ * aplicação já usa. O core não importa o pacote nem prende uma versão: só os tipos estruturais abaixo, o
+ * mesmo modelo do `logger: pino()`.
+ *
+ * Com um span ativo (a auto-instrumentação HTTP do SDK já criou o span SERVER), o FlowingTS **enriquece** esse
+ * span, sem duplicar: nome `GET /users/:id`, `http.route` e as exceções com a fase. Esse span é encerrado pela
+ * própria auto-instrumentação, dentro do `res.end()`, então o enriquecimento acontece no roteamento e no
+ * tratamento de erro, antes da resposta. Sem span ativo, o FlowingTS cria o span SERVER, a partir do
+ * `traceparent` recebido, e o encerra no fim da requisição.
+ */
+import type { ResponseInfo } from './app/options.ts';
+import type { ErrorPhase } from './abort.ts';
+import type { Context } from './context.ts';
+import type { RouteInfo } from './route-table.ts';
+type Attributes = Record<string, string | number | boolean>;
+/** O subconjunto de um `Span` do OpenTelemetry que o FlowingTS usa. */
+export interface TelemetrySpan {
+    setAttribute(key: string, value: string | number | boolean): unknown;
+    updateName(name: string): unknown;
+    recordException(exception: unknown): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    addEvent?(name: string, attributes?: Attributes): unknown;
+    end(): void;
+    spanContext(): {
+        traceId: string;
+        spanId: string;
+    };
+}
+interface TelemetryInstrument {
+    record?(value: number, attributes?: Attributes): void;
+    add?(value: number, attributes?: Attributes): void;
+}
+/** O subconjunto do `@opentelemetry/api` que o FlowingTS usa. Passe o módulo inteiro: `import * as otel`. */
+export interface TelemetryApi {
+    trace: {
+        getActiveSpan(): TelemetrySpan | undefined;
+        getTracer(name: string, version?: string): {
+            startSpan(name: string, options?: object, context?: unknown): TelemetrySpan;
+        };
+        setSpan(context: unknown, span: TelemetrySpan): unknown;
+    };
+    context: {
+        active(): unknown;
+        with<T>(context: unknown, fn: () => T): T;
+    };
+    propagation: {
+        extract(context: unknown, carrier: unknown): unknown;
+    };
+    metrics?: {
+        getMeter(name: string, version?: string): {
+            createHistogram(name: string, options?: object): TelemetryInstrument;
+            createUpDownCounter(name: string, options?: object): TelemetryInstrument;
+            createCounter(name: string, options?: object): TelemetryInstrument;
+        };
+    };
+    SpanKind: {
+        SERVER: number;
+    };
+    SpanStatusCode: {
+        ERROR: number;
+    };
+}
+/** Os pontos do pipeline em que o `telemetry` age; chamados pelo request-handler. */
+export interface Telemetry {
+    onRequest(ctx: Context): void;
+    onRoute(ctx: Context, route: RouteInfo): void;
+    onError(ctx: Context, err: unknown, phase: ErrorPhase): void;
+    onResponse(ctx: Context, info: ResponseInfo): void;
+    /** Roda o pipeline dentro do contexto do span criado pelo FlowingTS (spans do usuário viram filhos). */
+    run<T>(ctx: Context, fn: () => T): T;
+    /** `traceId`/`spanId` do span da requisição, para o `ctx.log`. */
+    spanIds(ctx: Context): {
+        traceId: string;
+        spanId: string;
+    } | undefined;
+}
+export declare function createTelemetry(api: TelemetryApi, version?: string | undefined): Telemetry;
+export {};
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/core/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/core/telemetry.ts"],"names":[],"mappings":"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"}

package/dist/core/telemetry.js

@@ -0,0 +1,96 @@
+import { createRequire } from 'node:module';
+import { kTelemetry } from './symbols.js';
+/** O estado deste módulo no `ctx`; o campo é `unknown` no `Context`, para ele não depender do telemetry. */
+const state = (ctx) => ctx[kTelemetry];
+/** Versão do FlowingTS, para o nome do tracer e do meter. Lida só quando o `telemetry` é usado. */
+function packageVersion() {
+    try {
+        return createRequire(import.meta.url)('../../package.json').version;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createTelemetry(api, version = packageVersion()) {
+    const tracer = api.trace.getTracer('flowingts', version);
+    const meter = api.metrics?.getMeter('flowingts', version);
+    const duration = meter?.createHistogram('http.server.request.duration', {
+        unit: 's',
+        description: 'Duração das requisições HTTP (sem streams).',
+    });
+    const streamDuration = meter?.createHistogram('flowing.stream.duration', {
+        unit: 's',
+        description: 'Duração das respostas em stream (SSE, NDJSON, arquivos).',
+    });
+    const active = meter?.createUpDownCounter('http.server.active_requests', { unit: '{request}' });
+    const aborted = meter?.createCounter('flowing.request.aborted', { unit: '{request}' });
+    return {
+        onRequest(ctx) {
+            const current = api.trace.getActiveSpan();
+            let telemetry;
+            if (current) {
+                telemetry = { span: current, owned: false, activeAttrs: { 'http.request.method': ctx.method } };
+            }
+            else {
+                const parent = api.propagation.extract(api.context.active(), ctx.req.headers);
+                const span = tracer.startSpan(ctx.method, { kind: api.SpanKind.SERVER, attributes: { 'http.request.method': ctx.method, 'url.path': ctx.path } }, parent);
+                telemetry = { span, owned: true, context: api.trace.setSpan(parent, span), activeAttrs: { 'http.request.method': ctx.method } };
+            }
+            ctx[kTelemetry] = telemetry;
+            active?.add?.(1, telemetry.activeAttrs);
+        },
+        onRoute(ctx, route) {
+            const t = state(ctx);
+            if (!t)
+                return;
+            t.span.updateName(`${ctx.method} ${route.path}`);
+            t.span.setAttribute('http.route', route.path);
+        },
+        onError(ctx, err, phase) {
+            const t = state(ctx);
+            if (!t)
+                return;
+            t.span.recordException(err);
+            t.span.addEvent?.('flowing.error', { 'flowing.error.phase': phase });
+        },
+        onResponse(ctx, info) {
+            const t = state(ctx);
+            if (!t)
+                return;
+            const attrs = { 'http.request.method': ctx.method, 'http.response.status_code': info.status };
+            if (info.route)
+                attrs['http.route'] = info.route.path;
+            // A regra do virtual host, não o hostname do cliente: mantém baixa a cardinalidade.
+            if (info.route?.host)
+                attrs['server.address'] = info.route.host;
+            if (info.status >= 500)
+                attrs['error.type'] = String(info.status);
+            if (info.abortReason)
+                attrs['flowing.abort.reason'] = info.abortReason;
+            active?.add?.(-1, t.activeAttrs);
+            if (info.abortReason)
+                aborted?.add?.(1, { 'flowing.abort.reason': info.abortReason });
+            (info.streaming ? streamDuration : duration)?.record?.(info.ms / 1000, attrs);
+            // O span da auto-instrumentação já foi encerrado por ela; só o criado aqui recebe o fim.
+            if (!t.owned)
+                return;
+            for (const [k, v] of Object.entries(attrs))
+                t.span.setAttribute(k, v);
+            t.span.setAttribute('flowing.outcome', info.outcome);
+            if (info.ttfbMs !== undefined)
+                t.span.setAttribute('flowing.ttfb_ms', info.ttfbMs);
+            // Convenções semânticas: só 5xx marca o span SERVER como erro; um 4xx é resposta normal.
+            if (info.status >= 500)
+                t.span.setStatus({ code: api.SpanStatusCode.ERROR });
+            t.span.end();
+        },
+        run(ctx, fn) {
+            const t = state(ctx);
+            return t?.context === undefined ? fn() : api.context.with(t.context, fn);
+        },
+        spanIds(ctx) {
+            return state(ctx)?.span.spanContext();
+        },
+    };
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/core/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/core/telemetry.ts"],"names":[],"mappings":"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"}

package/dist/core/uploads/receive.d.ts

@@ -0,0 +1,63 @@
+import type { Context } from '../context.ts';
+import type { ContentDetector, FileRule, FileRules, Size, UploadedFile, UploadsOptions } from './types.ts';
+/** `'5mb'` → 5242880. Erro de configuração aparece no registro da rota. */
+export declare function parseSize(size: Size, where: string): number;
+/**
+ * Detectores de conteúdo (F-46):
+ * - `detectors.magicBytes()`: o padrão, sem dependências (centenas de assinaturas; documentos do Office só como ZIP).
+ * - `detectors.fileType(fileTypeFromBuffer)`: o `file-type`, instalado pela aplicação, para conferências mais completas
+ *   (abre o ZIP para confirmar `.docx`, `.xlsx`, `.pptx`).
+ */
+export declare const detectors: {
+    magicBytes: () => ContentDetector;
+    fileType: (fileTypeFromBuffer: (buffer: Uint8Array) => Promise<{
+        mime: string;
+    } | undefined>) => ContentDetector;
+};
+/** Limites globais resolvidos, em bytes e contagens. */
+export interface UploadLimits {
+    readonly fileSize: number;
+    readonly files: number;
+    readonly fields: number;
+    readonly fieldSize: number;
+    readonly parts: number;
+}
+export interface UploadSettings {
+    readonly limits: UploadLimits;
+    readonly tempDir: string;
+    readonly detect: ContentDetector;
+}
+export declare function uploadSettings(opts?: UploadsOptions): UploadSettings;
+/** As regras de um campo, resolvidas no registro da rota. */
+interface CompiledRule {
+    readonly required: boolean;
+    readonly maxSize: number;
+    readonly maxCount: number;
+    readonly types: readonly string[] | undefined;
+    readonly verify: FileRule['verify'];
+}
+/** O plano de upload de uma rota, montado no registro (nada por requisição). */
+export interface UploadPlan {
+    readonly rules: ReadonlyMap<string, CompiledRule>;
+    readonly settings: UploadSettings;
+    /** O maior tamanho permitido entre os campos: o limite de leitura do busboy. */
+    readonly largest: number;
+}
+/**
+ * Resolve o `files` do contrato. Uma rota que tenta ampliar um limite global falha aqui, no registro, em vez de ser
+ * ignorada em silêncio.
+ */
+export declare function uploadPlan(files: FileRules, settings: UploadSettings, where: string): UploadPlan;
+/** O que a recepção deixa no `ctx`: os campos de texto (o body) e os arquivos por nome de campo. */
+export interface Received {
+    readonly fields: Record<string, string | string[]>;
+    readonly files: ReadonlyMap<string, readonly UploadedFile[]>;
+}
+/**
+ * Lê um `multipart/form-data` (F-46). Os arquivos vão para temporários com nome gerado, apagados quando a resposta
+ * termina (sucesso, erro ou cancelamento). Limites, tipos, conteúdo e obrigatórios são conferidos aqui, antes do
+ * handler; os campos de texto são validados depois pelo contrato `body`.
+ */
+export declare function receiveUploads(ctx: Context, plan: UploadPlan): Promise<Received>;
+export {};
+//# sourceMappingURL=receive.d.ts.map

package/dist/core/uploads/receive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receive.d.ts","sourceRoot":"","sources":["../../../src/core/uploads/receive.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAY,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAOrH,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK3D;AAKD;;;;;GAKG;AACH,eAAO,MAAM,SAAS;IACpB,UAAU,QAAM,eAAe;IAC/B,QAAQ,uBACe,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,KAAG,eAAe;CAKvG,CAAC;AAEF,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;CAClC;AAED,wBAAgB,cAAc,CAAC,IAAI,GAAE,cAAmB,GAAG,cAAc,CAaxE;AAED,6DAA6D;AAC7D,UAAU,YAAY;IACpB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;CACrC;AAED,gFAAgF;AAChF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAkBhG;AA2CD,oGAAoG;AACpG,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC,CAAC;CAC9D;AAID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CA8IhF"}