import type { Engine } from '../../core/engine.ts';
import { type PrometheusExporter } from '../../observability/metrics.ts';
import type { WorkerRegistry } from '../../worker/registry.ts';
import type { AuthContext } from '../authentication.ts';
import type { DiscoveryInfo } from '../discovery-info.ts';
import type { FleetEventFeed } from '../fleet-event-feed.ts';
import { type OpenApiSecuritySchemeName } from '../openapi.ts';
import { type OperationRegistry, type PipelineTrace } from '../operation-catalog.ts';
import type { OperationFault } from '../operation-fault.ts';
import type { WorkflowStreamConnectionAcquirer } from '../operations/workflow-events-sse.ts';
import type { Principal } from '../principal.ts';
import { type UnknownRestBinding } from '../rest-bindings.ts';
import type { TaskQueue } from '../task-queue.ts';
import type { WorkflowEventFeed } from '../workflow-event-feed.ts';
import type { DirectRouteHandlerName } from './route-matching.ts';
import { type LiveEventStreamContext } from './sse-route-dispatch.ts';
/**
 * Options bag passed to `handleRequest` by the HTTP server wrapper.
 *
 * Injects the resolved authentication context, custom metrics exporters, and
 * an optional override for the operation registry and REST bindings. Omit
 * `operationRegistry` and `restBindings` together to use the live defaults,
 * optionally bound to the supplied worker registry and task queue.
 *
 * @example
 * ```ts
 * import { type HandlerOptions } from '@lostgradient/weft/server/handler';
 *
 * const options: HandlerOptions = {
 *   authContext: { method: 'public' },
 * };
 * void options;
 * ```
 */
export interface HandlerOptions {
    /**
     * Optional authenticated caller context injected by the HTTP server
     * wrapper. See `AuthContext` in `authentication.ts` for field documentation.
     */
    authContext?: AuthContext;
    /**
     * Optional {@link PrometheusExporter} used to produce the body of
     * `/v1/metrics`. This is the plug point for projects that source metrics
     * from the OpenTelemetry SDK (e.g. via `@opentelemetry/exporter-prometheus`).
     */
    prometheusExporter?: PrometheusExporter;
    /** Live worker state used by worker and task-diagnostics operations. */
    workerRegistry?: WorkerRegistry;
    /** Live task-queue state used by queue and task-diagnostics operations. */
    taskQueue?: TaskQueue;
    /**
     * Operation registry for pipeline dispatch. Must be supplied together
     * with `restBindings` — a caller that overrides one but not the other
     * gets a mismatched configuration (custom bindings referencing a live
     * registry they weren't built against), which `handleRequest` rejects
     * at request time. Omit both to use the live defaults.
     */
    operationRegistry?: OperationRegistry;
    /**
     * REST bindings. A request whose method+path matches a binding routes
     * through the `executeOperation` pipeline. Must be supplied together
     * with `operationRegistry`. Omit both to use the live defaults.
     */
    restBindings?: ReadonlyArray<UnknownRestBinding>;
    /** OpenAPI security schemes supported by the live server configuration. */
    supportedAuthenticationSchemes?: ReadonlySet<OpenApiSecuritySchemeName>;
    /**
     * Operator-supplied metadata applied uniformly to all three discovery
     * documents (`/openapi.json`, `/openrpc.json`, `/asyncapi.json`).
     */
    discoveryInfo?: DiscoveryInfo;
    /**
     * Optional explicit public origin used when emitting absolute URLs in
     * discovery routes such as `/.well-known/api-catalog` and
     * `/.well-known/mcp.json`. Recommended in production to avoid trusting
     * attacker-controlled `Host` / `X-Forwarded-Proto` headers. Takes precedence
     * over `trustedHosts`.
     */
    publicOrigin?: string;
    /**
     * Optional allowlist of `Host` values that are trusted as the source of
     * absolute service-desc URLs in discovery routes such as
     * `/.well-known/api-catalog` and `/.well-known/mcp.json`. The route derives
     * the origin from the incoming request and rejects (421
     * Misdirected Request) if the resolved Host is not in this list.
     *
     * Either `publicOrigin` OR `trustedHosts` must be configured in
     * production deployments — without one, the route returns 503 because
     * `Bun.serve()` trusts the Host header in `request.url` and an attacker
     * can otherwise poison the discovery URLs.
     */
    trustedHosts?: ReadonlyArray<string>;
    /** Maximum REST operation request body size in bytes. Defaults to 1 MB. */
    maxRequestBodyBytes?: number;
    /** Event feed used by live workflow SSE routes. */
    workflowEventFeed?: WorkflowEventFeed;
    /** Fleet feed used by live fleet SSE routes. */
    fleetEventFeed?: Pick<FleetEventFeed, 'subscribe'>;
    /** Shared per-workflow long-lived stream connection limiter. */
    acquireWorkflowStreamConnection?: WorkflowStreamConnectionAcquirer;
    /**
     * Optional pipeline-trace observer. **Internal test seam** used by the
     * dispatch-audit suite to prove every transport drives the full
     * `executeOperation` pipeline. Production callers should not set this
     * — the parameter has no other effect on dispatch behavior.
     *
     * @internal
     */
    pipelineTrace?: PipelineTrace;
}
export type RouteExecutionContext = {
    request: Request;
    engine: Engine;
    options: HandlerOptions | undefined;
};
export type RouteExecutor = (context: RouteExecutionContext) => Promise<Response>;
export declare const DIRECT_ROUTE_EXECUTORS: Record<DirectRouteHandlerName, RouteExecutor>;
export declare function dispatchViaExecuteOperation(request: Request, engine: Engine, binding: UnknownRestBinding, pathParams: Record<string, string>, registry: OperationRegistry, principal: Principal, pipelineTrace?: PipelineTrace, maxRequestBodyBytes?: number, supportedAuthenticationSchemes?: ReadonlySet<OpenApiSecuritySchemeName>, liveEventStreamContext?: LiveEventStreamContext): Promise<Response>;
/**
 * Type guard that returns true if the value structurally resembles an
 * {@link OperationFault} (carries `code`, `message`, and `data` properties).
 *
 * Used by error handlers to decide whether a thrown value can be mapped to a
 * structured operation fault response, vs. needing to be wrapped in a generic
 * 500.
 *
 * @example Catch an unknown error and surface as a fault when it qualifies
 * ```ts
 * import { isOperationFaultLike } from '@lostgradient/weft/server/handler';
 *
 * try {
 *   // operation handler runs here
 * } catch (error) {
 *   if (isOperationFaultLike(error)) {
 *     // structured fault — pass through
 *   } else {
 *     // unknown — wrap as 500
 *   }
 * }
 * ```
 */
export declare function isOperationFaultLike(value: unknown): value is OperationFault;
export declare function defaultOperationRegistry(options?: Pick<HandlerOptions, 'workerRegistry' | 'taskQueue'>): OperationRegistry;
export declare function defaultRestBindings(): ReadonlyArray<UnknownRestBinding>;