import type { WebSocketServerLike } from '@hono/node-server';
import type { Hono } from 'hono';

/** Hono variables populated by transport-boundary middleware. */
export type AppEnv = {
    Variables: {

        /** Decoded Extended JSON request body, when present. */
        parsedBody?: unknown;

        /** Raw JSON text preserved for signature verification. */
        rawJsonBody?: string;
    };
};

/**
 * Host-facing adapter contract.
 *
 * This interface may depend on Hono because it belongs to server composition,
 * not application routing. Implementations remain unaware of route modules.
 */
export interface TransportRouter {

    /**
     * Attach wire endpoints and middleware to the shared Hono application.
     *
     * @param app - Server host application to register handlers on.
     */
    register(app: Hono<AppEnv>): Promise<void> | void;

    /** Close transport-owned long-lived connections during server shutdown. */
    stop?(): Promise<void> | void;
}

/** A transport which also supplies the WebSocket server used during upgrade. */
export interface UpgradeTransportRouter extends TransportRouter {

    /** WebSocket server instance passed to the Node HTTP listener. */
    readonly websocketServer: WebSocketServerLike;
}