@sourceregistry/node-ovsdb/dist/index.d.ts

TypeScript OVSDB client for Node.js

import { Socket } from 'node:net';
import { EventEmitter } from 'node:events';
import { Duplex } from 'node:stream';
import { TLSSocket, ConnectionOptions as TlsConnectionOptions } from 'node:tls';
import { AbortOperation, AssertOperation, CommentOperation, CommitOperation, DatabaseOperation, DatabaseSchema, DatabaseTableMap, DeleteOperation, InsertOperation, JsonObject, JsonValue, ListDbsResult, LockedNotification, MutateOperation, MonitorCondRequest, MonitorCondSinceResult, MonitorRequest, OperationResult, OperationResults, OvsdbError, OvsdbNotification, OvsdbValue, SelectOperation, StolenNotification, TableUpdates, TableUpdates2, Update2Notification, Update3Notification, UpdateNotification, UpdateOperation, WaitOperation } from './types';
/**
 * A socket-compatible stream used by the client transport.
 */
export type OvsdbStream = Duplex | Socket | TLSSocket;
/**
 * Supported connection modes for the OVSDB transport.
 */
export type OvsdbTransportKind = "unix" | "tcp" | "tls";
/**
 * Resolved Unix socket transport settings.
 */
export interface OvsdbUnixConnectionOptions {
    transport: "unix";
    socketPath: string;
}
/**
 * Resolved TCP transport settings.
 */
export interface OvsdbTcpConnectionOptions {
    transport: "tcp";
    host: string;
    port: number;
}
/**
 * Resolved TLS transport settings.
 */
export interface OvsdbTlsTransportOptions {
    transport: "tls";
    host: string;
    port: number;
    tlsOptions: TlsConnectionOptions;
}
/**
 * Fully resolved transport settings used by the client.
 */
export type OvsdbResolvedConnectionOptions = OvsdbUnixConnectionOptions | OvsdbTcpConnectionOptions | OvsdbTlsTransportOptions;
/**
 * Typed events emitted by {@link OVSDBClient}.
 */
export interface OvsdbClientEvents<TDatabase extends DatabaseTableMap = DatabaseTableMap> {
    connect: [];
    close: [];
    notification: [OvsdbNotification<TDatabase>];
    update: [UpdateNotification<TDatabase>];
    update2: [Update2Notification<TDatabase>];
    update3: [Update3Notification<TDatabase>];
    locked: [LockedNotification];
    stolen: [StolenNotification];
    protocolError: [Error, unknown];
    transportError: [Error];
}
/**
 * Options for configuring an {@link OVSDBClient}.
 */
export interface OvsdbClientOptions {
    /**
     * Path to the OVSDB Unix domain socket.
     *
     * @defaultValue `"/var/run/openvswitch/db.sock"`
     */
    socketPath?: string;
    /**
     * Hostname for TCP or TLS connections.
     *
     * When set, the client uses a network socket instead of a Unix socket.
     */
    host?: string;
    /**
     * Port for TCP or TLS connections.
     *
     * @defaultValue `6640`
     */
    port?: number;
    /**
     * Enables TLS for network connections.
     *
     * @defaultValue `false`
     */
    tls?: boolean;
    /**
     * Extra TLS connection options forwarded to `node:tls`.
     *
     * These options are only used when `tls` is enabled.
     */
    tlsOptions?: TlsConnectionOptions;
    /**
     * Request and connection timeout in milliseconds.
     *
     * @defaultValue `5000`
     */
    timeout?: number;
    /**
     * Optional stream factory used for testing or custom transports.
     * When set, the client skips the socket path existence check.
     */
    connectionFactory?: (options: OvsdbResolvedConnectionOptions) => OvsdbStream;
}
/**
 * JSON-RPC transport error returned by the OVSDB server.
 */
export declare class OvsdbRpcError extends Error {
    /**
     * The error payload returned by the server.
     */
    readonly response: OvsdbError;
    /**
     * Creates a new RPC error wrapper.
     */
    constructor(response: OvsdbError);
}
/**
 * Raised when a message does not match the expected JSON-RPC envelope.
 */
export declare class OvsdbProtocolError extends Error {
    /**
     * The raw payload that failed validation.
     */
    readonly payload: unknown;
    /**
     * Creates a new protocol error wrapper.
     */
    constructor(message: string, payload: unknown);
}
/**
 * Raised when an OVSDB transaction response contains an operation-level error.
 */
export declare class OvsdbTransactionError<TDatabase extends DatabaseTableMap = DatabaseTableMap> extends Error {
    /**
     * Zero-based index of the failed operation in the submitted transaction.
     */
    readonly operationIndex: number;
    /**
     * Operation that produced the error.
     */
    readonly operation: DatabaseOperation<TDatabase>;
    /**
     * OVSDB error payload returned for the failed operation.
     */
    readonly result: OvsdbError;
    /**
     * Raw transaction results returned by the server.
     */
    readonly results: Array<OperationResult<TDatabase, DatabaseOperation<TDatabase>> | OvsdbError>;
    /**
     * Creates a new transaction error wrapper.
     */
    constructor(options: {
        operationIndex: number;
        operation: DatabaseOperation<TDatabase>;
        result: OvsdbError;
        results: Array<OperationResult<TDatabase, DatabaseOperation<TDatabase>> | OvsdbError>;
    });
}
/**
 * Result payload returned by a staged transaction helper.
 */
export interface OvsdbTransactionOutcome<TDatabase extends DatabaseTableMap = DatabaseTableMap, TValue = void> {
    /**
     * Value returned by the transaction callback.
     */
    value: TValue;
    /**
     * Operations that were submitted to OVSDB.
     */
    operations: readonly DatabaseOperation<TDatabase>[];
    /**
     * Per-operation OVSDB results in submission order.
     */
    results: Array<OperationResult<TDatabase, DatabaseOperation<TDatabase>>>;
}
/**
 * Options for the staged transaction helper.
 */
export interface OvsdbTransactionOptions {
    /**
     * Appends a trailing `commit` operation when the callback succeeds and the
     * staged operations do not already include `commit` or `abort`.
     *
     * @defaultValue `true`
     */
    autoCommit?: boolean;
    /**
     * Durable flag used by the auto-generated `commit` operation.
     *
     * @defaultValue `false`
     */
    durable?: boolean;
}
/**
 * Stages OVSDB operations before sending them as a single `transact` request.
 */
export declare class OvsdbTransaction<TDatabase extends DatabaseTableMap = DatabaseTableMap> {
    private readonly stagedOperations;
    /**
     * Returns the currently staged operations.
     */
    get operations(): readonly DatabaseOperation<TDatabase>[];
    /**
     * Adds an operation to the transaction.
     */
    add<TOperation extends DatabaseOperation<TDatabase>>(operation: TOperation): TOperation;
    /**
     * Stages an insert operation.
     */
    insert<TOperation extends InsertOperation<TDatabase>>(operation: TOperation): TOperation;
    /**
     * Stages a select operation.
     */
    select<TOperation extends SelectOperation<TDatabase>>(operation: TOperation): TOperation;
    /**
     * Stages an update operation.
     */
    update<TOperation extends UpdateOperation<TDatabase>>(operation: TOperation): TOperation;
    /**
     * Stages a mutate operation.
     */
    mutate<TOperation extends MutateOperation<TDatabase>>(operation: TOperation): TOperation;
    /**
     * Stages a delete operation.
     */
    delete<TOperation extends DeleteOperation<TDatabase>>(operation: TOperation): TOperation;
    /**
     * Stages a wait operation.
     */
    wait<TOperation extends WaitOperation<TDatabase>>(operation: TOperation): TOperation;
    /**
     * Stages a comment operation.
     */
    comment(comment: string): CommentOperation;
    /**
     * Stages an assert operation.
     */
    assert(lock: string): AssertOperation;
    /**
     * Stages a commit operation.
     */
    commit(durable?: boolean): CommitOperation;
    /**
     * Stages an abort operation.
     */
    abort(): AbortOperation;
}
/**
 * A low-level, event-driven OVSDB client for Unix sockets, TCP, or TLS.
 *
 * The client exposes the RFC 7047 primitives together with common
 * Open vSwitch protocol extensions while keeping the API small and predictable.
 */
export declare class OVSDBClient<TDatabase extends DatabaseTableMap = DatabaseTableMap> extends EventEmitter<OvsdbClientEvents<TDatabase>> implements AsyncDisposable {
    private readonly timeout;
    private readonly connectionOptions;
    private readonly connectionFactory?;
    private socket;
    private requestId;
    private receiveBuffer;
    private pendingRequests;
    private connected;
    private closeEmitted;
    /**
     * Creates a new OVSDB client instance.
     */
    constructor(options?: OvsdbClientOptions);
    /**
     * Returns `true` when the underlying socket is currently connected.
     */
    get isConnected(): boolean;
    /**
     * Opens the transport connection.
     *
     * @returns The connected client instance for chaining.
     */
    connect(): Promise<this>;
    /**
     * Sends a raw JSON-RPC request and resolves with its `result` payload.
     *
     * @param method RPC method name.
     * @param params RPC parameters.
     */
    request<TResult>(method: string, params?: JsonValue[]): Promise<TResult>;
    /**
     * Sends a JSON-RPC notification without waiting for a response.
     *
     * @param method RPC method name.
     * @param params RPC parameters.
     */
    notify(method: string, params?: JsonValue[]): Promise<void>;
    /**
     * Returns the database names exposed by the connected OVSDB server.
     */
    listDbs(): Promise<ListDbsResult>;
    /**
     * Returns the schema definition for a database.
     *
     * @param dbName Database name.
     */
    getSchema(dbName?: string): Promise<DatabaseSchema>;
    /**
     * Executes a single transaction.
     *
     * The response preserves operation ordering, so tuple inputs infer tuple outputs.
     *
     * @param dbName Database name.
     * @param operations Transaction operations.
     */
    transact<TOperations extends readonly DatabaseOperation<TDatabase>[]>(dbName: string, operations: [...TOperations]): Promise<OperationResults<TDatabase, TOperations>>;
    /**
     * Stages a transaction in a callback and submits it only if the callback
     * completes successfully.
     *
     * This helper is convenient when you want a scoped, imperative API while
     * still sending exactly one OVSDB `transact` request.
     *
     * @param dbName Database name.
     * @param callback Callback that stages operations on the transaction object.
     * @param options Auto-commit behavior for the staged transaction.
     */
    transaction<TValue>(dbName: string, callback: (transaction: OvsdbTransaction<TDatabase>) => Promise<TValue> | TValue, options?: OvsdbTransactionOptions): Promise<OvsdbTransactionOutcome<TDatabase, TValue>>;
    /**
     * Cancels a previously issued request by id.
     *
     * @param requestId JSON-RPC request id to cancel.
     */
    cancel(requestId: JsonValue): Promise<null | JsonObject>;
    /**
     * Starts a standard RFC 7047 monitor.
     *
     * @param dbName Database name.
     * @param monitorId Application-defined monitor id.
     * @param monitorRequests Per-table monitor definitions.
     */
    monitor(dbName: string, monitorId: JsonValue, monitorRequests: Record<string, MonitorRequest<TDatabase>>): Promise<TableUpdates<TDatabase>>;
    /**
     * Starts an Open vSwitch conditional monitor.
     *
     * @param dbName Database name.
     * @param monitorId Application-defined monitor id.
     * @param monitorRequests Per-table conditional monitor definitions.
     */
    monitorCond(dbName: string, monitorId: JsonValue, monitorRequests: Record<string, MonitorCondRequest<TDatabase>>): Promise<TableUpdates2<TDatabase>>;
    /**
     * Starts an Open vSwitch conditional monitor from a known transaction id.
     *
     * @param dbName Database name.
     * @param monitorId Application-defined monitor id.
     * @param monitorRequests Per-table conditional monitor definitions.
     * @param lastTransactionId Last seen transaction id, or `null` for a fresh snapshot.
     */
    monitorCondSince(dbName: string, monitorId: JsonValue, monitorRequests: Record<string, MonitorCondRequest<TDatabase>>, lastTransactionId?: string | null): Promise<MonitorCondSinceResult<TDatabase>>;
    /**
     * Cancels a monitor by its monitor id.
     *
     * @param monitorId Monitor id used when the monitor was created.
     */
    monitorCancel(monitorId: JsonValue): Promise<null | JsonObject>;
    /**
     * Acquires a named database lock.
     *
     * @param lockId Lock identifier.
     */
    lock(lockId: string): Promise<null | JsonObject>;
    /**
     * Forces ownership of a named database lock.
     *
     * @param lockId Lock identifier.
     */
    steal(lockId: string): Promise<null | JsonObject>;
    /**
     * Releases a previously acquired named database lock.
     *
     * @param lockId Lock identifier.
     */
    unlock(lockId: string): Promise<null | JsonObject>;
    /**
     * Sends an echo request to validate transport liveness.
     *
     * @param payload Values to be echoed back by the server.
     */
    echo<TPayload extends OvsdbValue[]>(...payload: TPayload): Promise<TPayload>;
    /**
     * Enables or disables Open vSwitch database change awareness.
     *
     * @param enabled Whether the server should report change awareness metadata.
     */
    setDbChangeAware(enabled?: boolean): Promise<boolean | null>;
    /**
     * Closes the connection and rejects all pending requests.
     */
    close(): Promise<void>;
    /**
     * Implements `AsyncDisposable`.
     */
    [Symbol.asyncDispose](): Promise<void>;
    private attachSocket;
    private readonly handleData;
    private readonly handleSocketError;
    private readonly handleSocketClose;
    private parseFrame;
    private handleMessage;
    private handleResponse;
    private handleIncomingRequest;
    private handleNotification;
    private emitProtocolError;
    private writeMessage;
    private assertConnected;
    private disposeTransport;
}
export * from './types';
/**
 * Resolves the user-supplied transport options into an explicit connection mode.
 */
export declare function resolveConnectionOptions(options?: OvsdbClientOptions): OvsdbResolvedConnectionOptions;
//# sourceMappingURL=index.d.ts.map