/** A normal request/response result before transport encoding. */
export type StreamResponse = {
    /** Optional correlation ID for multiplexed transports. */
    id?: string;

    /** Discriminator marking this message as a route response. */
    type: 'response';

    /** HTTP-equivalent status code for the response body. */
    statusCode: number;

    /** Serialized response payload. */
    body: unknown;
};

/** An application event before a transport applies its wire encoding. */
export type StreamEvent = {
    /** Optional event or correlation ID. */
    id?: string;

    /** Application-defined event type name. */
    type: string;

    /** Serialized event payload. */
    data: unknown;
};

/** Union of every message a connection stream can emit. */
export type StreamMessage = StreamResponse | StreamEvent;

/**
 * Connection-level output channel shared by route requests and the broadcaster.
 *
 * A WebSocket connection can back many request-scoped RouteStream instances.
 * SSE and normal HTTP each create one connection stream per request.
 */
export abstract class BaseStream {
    /** Whether this connection can remain open for server events. */
    abstract readonly streaming: boolean;

    /** Whether later requests can modify this connection's subscriptions. */
    abstract readonly bidirectional: boolean;

    /**
     * Send one response or event using the transport's wire encoding.
     *
     * @param message - Neutral response or event envelope to encode.
     */
    abstract send(message: StreamMessage): Promise<void>;

    /** Close the underlying connection and notify lifecycle observers. */
    abstract close(): void;

    /**
     * Observe closure whether it occurs locally or at the remote peer.
     *
     * @param callback - Invoked once when the connection closes.
     */
    abstract onClose(callback: () => void): void;
}