/**
 * Backend WebSocket transport — manages server-side WebSocket connections
 * with session tracking and revocation support.
 *
 * @module
 */
import type { WSContext } from 'hono/ws';
import { type Uuid } from '@fuzdev/fuz_util/id.js';
import type { JsonrpcMessageFromServerToClient, JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
import { type Transport, type TransportSendOptions } from './transports.js';
/**
 * Auth identity attached to a single WebSocket connection.
 *
 * One record per connection. `token_hash` is set for cookie-session
 * connections, `api_token_id` for bearer (`api_token`) connections, and
 * both are null for daemon-token connections (reachable only via
 * `BackendWebsocketTransport.close_sockets_for_account`).
 */
export interface ConnectionIdentity {
    /** Blake3 session token hash, or null for non-session credentials. */
    token_hash: string | null;
    /** Authenticated account id. Always set. */
    account_id: Uuid;
    /** `api_token.id` for bearer-authenticated connections, else null. */
    api_token_id: string | null;
}
/**
 * Structural capability for transports that can broadcast with a
 * per-connection ACL predicate. Named separately from `Transport` so the
 * broadcast API can feature-detect without importing a concrete class.
 *
 * `ConnectionIdentity` is the auth-gated identity shape used today. When a
 * second implementation (e.g. SSE backend transport) lands with a
 * different identity, consider parameterizing on `TIdentity`.
 */
export interface FilterableBroadcastTransport extends Transport {
    broadcast_filtered: (message: JsonrpcMessageFromServerToClient, predicate: (identity: ConnectionIdentity) => boolean) => number;
}
/** Type guard for `FilterableBroadcastTransport`. */
export declare const is_filterable_broadcast_transport: (transport: Transport) => transport is FilterableBroadcastTransport;
export declare class BackendWebsocketTransport implements FilterableBroadcastTransport {
    #private;
    readonly transport_name: "backend_websocket_rpc";
    /**
     * Add a new WebSocket connection with auth info.
     * Session connections pass a token hash for targeted revocation.
     * Bearer token connections (`api_token`) pass the `api_token.id` so the
     * socket can be closed when that specific token is revoked without
     * tearing down the account's other sockets. Daemon-token connections
     * pass `null` for both — they're only reachable via
     * `close_sockets_for_account`.
     *
     * @returns the freshly assigned `connection_id` (branded `Uuid`)
     * @mutates this - inserts into `#connections`, `#connection_ids`, and
     *   `#connection_identities`
     */
    add_connection(ws: WSContext, token_hash: string | null, account_id: Uuid, api_token_id?: string | null): Uuid;
    /**
     * Remove a WebSocket connection and its auth tracking data.
     * Idempotent — safe to call after revocation has already cleaned up.
     *
     * @mutates this - deletes the connection's entries from `#connections`,
     *   `#connection_ids`, and `#connection_identities`
     */
    remove_connection(ws: WSContext): void;
    /**
     * Close all sockets associated with a specific session token hash.
     *
     * @returns the number of sockets closed
     * @mutates this - removes matching connections from internal maps and
     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
     */
    close_sockets_for_session(token_hash: string): number;
    /**
     * Close all sockets associated with a specific account.
     *
     * @returns the number of sockets closed
     * @mutates this - removes matching connections from internal maps and
     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
     */
    close_sockets_for_account(account_id: Uuid): number;
    /**
     * Close all sockets associated with a specific API token.
     *
     * Used on `token_revoke` audit events so revoking one token doesn't
     * tear down the account's session-authenticated sockets or other
     * tokens' sockets.
     *
     * @returns the number of sockets closed
     * @mutates this - removes matching connections from internal maps and
     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
     */
    close_sockets_for_token(api_token_id: string): number;
    send(message: JsonrpcRequest, options?: TransportSendOptions): Promise<JsonrpcResponseOrError>;
    send(message: JsonrpcNotification, options?: TransportSendOptions): Promise<JsonrpcErrorResponse | null>;
    /**
     * Broadcast to connections whose identity satisfies a predicate.
     *
     * Used by the broadcast API when a consumer supplies a subscription ACL hook
     * (e.g. zap's `zap_run_created` only reaches the account that owns the run).
     * When no ACL is needed, callers should prefer `send(message)` / `#broadcast`
     * to skip the per-connection predicate overhead.
     *
     * @returns the number of sockets the message was sent to
     */
    broadcast_filtered(message: JsonrpcMessageFromServerToClient, predicate: (identity: ConnectionIdentity) => boolean): number;
    /**
     * Send a message to every socket bound to a specific account.
     *
     * Targeted per-account fan-out for any flow where the delivery target
     * is a single known account. Prefer this over `broadcast_filtered` when
     * the filter is exactly "this account_id"; reach for `broadcast_filtered`
     * when the ACL is an arbitrary predicate over `ConnectionIdentity`.
     *
     * Mirrors `close_sockets_for_account` on the send side: every connection
     * for the account (session, bearer, and daemon-token) receives the
     * message.
     *
     * @returns the number of sockets the message was sent to
     */
    send_to_account(account_id: Uuid, message: JsonrpcMessageFromServerToClient): number;
    is_ready(): boolean;
    /**
     * Number of currently tracked WebSocket connections.
     *
     * Read-only counter intended for telemetry, logging, and tests.
     * Counts every entry in the connection map — including connections
     * that have been closed by the peer but not yet removed by the WS
     * adapter's `onClose` callback.
     */
    get_connection_count(): number;
}
//# sourceMappingURL=transports_ws_backend.d.ts.map