@gizmodata/hardcharger-mcp 0.0.0 → 2.1.0

package/dist/connection.d.ts

@@ -0,0 +1,260 @@
+import { type BrowserSignInTarget, type Connection, type ConnectOptions } from "@gizmodata/hardcharger";
+import { Table } from "apache-arrow";
+import type { OAuthConfig } from "./oauth.js";
+import type { BoundParams } from "./params.js";
+/** How a connection signs in. */
+export type AuthMethod = "password" | "token" | "mtls" | "sso" | "none";
+/** Settings for one Hardcharger server. */
+export interface ConnectionConfig {
+    /** Unique, case-insensitive name used in tool arguments (e.g. "default", "prod"). */
+    name: string;
+    /** `hardcharger://host[:port][/prefix][?tls=false]` (TLS unless `?tls=false`, port 31337 by default). */
+    uri: string;
+    /** Host and TLS of `uri`, as the client reads it. */
+    host: string;
+    port: number;
+    tls: boolean;
+    /** Password sign-in. */
+    username?: string;
+    password?: string;
+    /** A signed sign-in token (an identity provider's ID token, or one minted for Hardcharger): the token_exchange grant. */
+    token?: string;
+    /** Client certificate and key (PEM file paths) for mutual TLS. Alone, the certificate is the credential. */
+    mtlsCertFile?: string;
+    mtlsKeyFile?: string;
+    /** CA bundle (PEM file path) that verifies the server's certificate, for a private CA. */
+    tlsRootsFile?: string;
+    tlsSkipVerify: boolean;
+    /** Catalog to use at session start (optional). */
+    defaultCatalog?: string;
+    /** Schema to use at session start (optional). */
+    defaultSchema?: string;
+    /** Per-statement timeout applied to this connection's statements (0 = none). */
+    queryTimeoutSeconds: number;
+}
+/** Whole-server settings plus every configured connection (the first is the initial default). */
+export interface McpConfig {
+    connections: ConnectionConfig[];
+    allowWrites: boolean;
+    maxRows: number;
+    maxCellChars: number;
+    queryTimeoutSeconds: number;
+    /** Bearer token required on every Streamable HTTP request (http transport only). */
+    mcpBearerToken?: string;
+    /** OAuth resource-server settings for the HTTP transport (set when HARDCHARGER_MCP_OAUTH_ISSUER is configured). */
+    mcpOAuth?: OAuthConfig;
+    /** HTTP transport with OAuth: seconds a per-user session may sit idle before its connections are closed. */
+    mcpSessionIdleSeconds: number;
+    /** HTTP transport with OAuth: cap on concurrent per-user sessions (least recently used is closed first). */
+    mcpMaxSessions: number;
+    /** Enables the optional `login_sso` tool (the server's OAuth browser sign-in). */
+    enableSso: boolean;
+}
+export declare const DEFAULTS: {
+    readonly maxRows: 500;
+    readonly maxCellChars: 200;
+    readonly queryTimeoutSeconds: 60;
+    readonly connectionName: "default";
+    readonly sessionIdleSeconds: 1800;
+    readonly maxSessions: 200;
+};
+/** Extra connection slots the Claude Desktop manifest exposes (`HARDCHARGER_2_*`, `HARDCHARGER_3_*`). */
+export declare const MANIFEST_SLOTS: readonly ["2", "3"];
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/** True when an env value should be treated as absent. */
+export declare function isUnset(raw: string | undefined): boolean;
+export declare function parseBoolean(name: string, raw: string | undefined, fallback: boolean): boolean;
+export declare function parseInteger(name: string, raw: string | undefined, fallback: number, { min, max }: {
+    min: number;
+    max?: number;
+}): number;
+/** Env-variable key fragment for a connection key: `prod-eu` -> `PROD_EU`. */
+export declare function envKey(key: string): string;
+/** Reads and validates a `hardcharger://` URI the way the client will (throws ConfigError). */
+export declare function parseHardchargerUri(name: string, raw: string): {
+    uri: string;
+    host: string;
+    port: number;
+    tls: boolean;
+};
+/**
+ * Builds the effective configuration from environment variables.
+ *
+ * Connections:
+ * - primary: `HARDCHARGER_URI` etc. (name `HARDCHARGER_CONNECTION_NAME`, default "default");
+ * - manifest slots: `HARDCHARGER_2_URI` / `HARDCHARGER_3_URI` etc. (names `HARDCHARGER_2_NAME`,
+ *   default "server2"/"server3");
+ * - any names listed in `HARDCHARGER_CONNECTIONS` (comma separated), read from
+ *   `HARDCHARGER_<NAME>_URI` etc. with the name upper-cased and non-alphanumerics
+ *   replaced by `_`.
+ * Slots without a URI are ignored. At least one connection is required.
+ */
+export declare function parseConfig(env?: NodeJS.ProcessEnv): McpConfig;
+/** Default claim precedence used to name an authenticated caller. */
+export declare const DEFAULT_USER_CLAIMS: readonly ["email", "preferred_username", "upn", "name", "sub"];
+/**
+ * Reads the OAuth resource-server settings for the HTTP transport. Returns
+ * undefined unless HARDCHARGER_MCP_OAUTH_ISSUER is set. Plain http URLs are
+ * accepted for the issuer and public URL only when
+ * HARDCHARGER_MCP_OAUTH_ALLOW_INSECURE=true (local testing).
+ */
+export declare function parseOAuth(env: NodeJS.ProcessEnv): OAuthConfig | undefined;
+/** The sign-in a connection's settings call for (before any login_sso). */
+export declare function authMethod(config: Pick<ConnectionConfig, "username" | "token" | "mtlsCertFile">): AuthMethod;
+/** Replaces every configured secret in `text` with `***`. */
+export declare function redactSecrets(text: string, secrets: Array<string | undefined>): string;
+export declare class QueryTimeoutError extends Error {
+    constructor(seconds: number);
+}
+/** A capped result: up to `maxRows + 1` rows so callers can detect truncation. */
+export interface CappedResult {
+    table: Table;
+    /** True when more rows existed beyond `maxRows` (the extra row is not in `table`). */
+    truncated: boolean;
+}
+/** The error's Hardcharger (Chargewire) code, if it is one of the client's errors. */
+export declare function errorCode(err: unknown): string | undefined;
+/**
+ * Does this error mean the connection (or the server's session behind it) is gone in a
+ * way that a fresh connection with the same credentials cures? The client itself already
+ * replaces a session the server lost (`session_not_found`, an expired token) and replays
+ * the session's options; this covers what it can't: a session an administrator ended
+ * (`session_ended` with reason `killed`, e.g. `KILL SESSION`, an expired token, or a reason
+ * this server doesn't know), a closed connection, a transport failure, and a lost session
+ * the client could not replace. A refused credential is never retried, and neither is a
+ * session ended because the sign-in was withdrawn (`token_revoked`, `credentials_changed`,
+ * `principal_dropped`).
+ */
+export declare function isConnectionLost(err: unknown): boolean;
+export interface SessionOverrides {
+    /**
+     * Replaces the configured credentials with the Hardcharger access token a browser sign-in
+     * (login_sso) handed out; kept in memory only and used as is, never renewed.
+     */
+    accessToken?: string;
+}
+/** The session's catalog and schema, kept by the client and replayed on a replacement session. */
+export interface SearchPath {
+    catalog?: string;
+    schema?: string;
+}
+export interface RunOptions {
+    /** Overrides the configured timeout for this operation (seconds; 0 = none). */
+    timeoutSeconds?: number;
+}
+/** What `run` hands each operation: the connection and the statement options to use. */
+export interface RunContext {
+    signal: AbortSignal | undefined;
+    /** The server-side timeout (§6.9) for statements, when one applies. */
+    statementTimeoutMs: number | undefined;
+}
+/** Setting names read from hardcharger_settings() and reported by server_info. */
+export declare const SERVER_SETTINGS_OF_INTEREST: readonly ["hardcharger.version", "hardcharger.read_only", "hardcharger.max_sessions", "hardcharger.session_idle_timeout", "hardcharger.query_timeout", "hardcharger.memory_limit", "hardcharger.max_concurrent_statements", "hardcharger.instance_id", "hardcharger.cluster_id"];
+export interface ConnectionHooks {
+    /** Test hook: opens the client connection (defaults to `connect` from @gizmodata/hardcharger). */
+    connect?: (options: ConnectOptions) => Promise<Connection>;
+}
+/**
+ * One Hardcharger connection per configured server, opened lazily and serialized so a
+ * single statement is in flight at a time. Timeouts are enforced by the server
+ * (`statementTimeoutMs`, Chargewire §6.9) with a client-side abort as backstop that cancels
+ * the statement on the server; only if that fails to settle the call is the connection
+ * dropped and reopened. The client replaces a session the server lost and replays its
+ * catalog and schema; a connection that is gone altogether (a killed session, a closed
+ * connection, a transport failure) is reopened once and the operation retried.
+ */
+export declare class HardchargerConnection {
+    readonly config: ConnectionConfig;
+    private readonly log;
+    private client;
+    private connecting;
+    private queue;
+    private overrides;
+    private warnings;
+    private searchPath;
+    /** Wall-clock at which the current client was opened (for server_info). */
+    connectedAt: Date | null;
+    /** Sessions the server lost and the client replaced, over every client this connection opened. */
+    private replacedBefore;
+    /** Times a lost connection was reopened by this layer (a killed session, a transport failure). */
+    reconnects: number;
+    /** The server's startup settings from hardcharger_settings(); null until read or when unavailable. */
+    private serverSettings;
+    private readonly openClient;
+    constructor(config: ConnectionConfig, log?: (message: string) => void, hooks?: ConnectionHooks);
+    /** The search path (catalog, schema) applied to every session. */
+    currentSearchPath(): SearchPath;
+    /**
+     * Switches the session's default catalog and/or schema (Chargewire session options, which
+     * the client replays on a replacement session). Throws when the server refuses it.
+     */
+    useSchema(path: SearchPath): Promise<SearchPath>;
+    /**
+     * Re-reads the session's catalog and schema (after a `USE`, which the server applies but
+     * the client does not replay) and sets both as session options, so a replacement session
+     * gets the same search path.
+     */
+    syncSearchPath(): Promise<SearchPath>;
+    private pinSearchPath;
+    /** Secrets to redact from any message that might reach a client. */
+    secrets(): Array<string | undefined>;
+    redact(text: string): string;
+    /** Effective auth method, taking login_sso into account. */
+    effectiveAuth(): {
+        method: AuthMethod;
+        user?: string;
+    };
+    /** Session-setup warnings (e.g. a default catalog the server does not have). */
+    sessionWarnings(): string[];
+    /** Sessions the server lost and the client replaced (over this connection's lifetime). */
+    sessionReplacements(): number;
+    /** The server's idle timeout for this connection's session, as the session document announced it. */
+    sessionIdleTimeoutSeconds(): Promise<number | null>;
+    /** The server's discovery document (name, version, capabilities, grants), once connected. */
+    discovery(): Connection["server"] | null;
+    /** Swaps in new credentials (login_sso) and drops the current connection. */
+    useCredentials(overrides: SessionOverrides): Promise<void>;
+    /** Where a browser sign-in (login_sso) runs: the connection's own URI, with its TLS settings. */
+    signInTarget(): BrowserSignInTarget;
+    /** The TLS settings (roots, client certificate, skip verify) for this connection, if any. */
+    private tlsOptions;
+    /** The client's connect options for this connection's settings. */
+    clientOptions(): ConnectOptions;
+    /** Opens a fresh client and applies the session settings. */
+    private open;
+    /**
+     * The search path, as Chargewire session options. A catalog or schema the server does not
+     * have is reported (with the catalogs it does have) instead of failing the connection;
+     * the server's default then applies.
+     */
+    private applySessionSettings;
+    /** Reads the server's startup settings once per connection; never fails the connection. */
+    private probeServerSettings;
+    /** The server's reported startup settings (name -> value); empty when unknown. */
+    serverSettingsSnapshot(): Record<string, string>;
+    /** Returns the shared client, opening it on first use. */
+    get(): Promise<Connection>;
+    /** Closes the current client (ending its session on the server). */
+    reset(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Runs `fn` against the shared client with: serialization, one retry after the
+     * connection was lost (see isConnectionLost), and a deadline: the server's statement
+     * timeout, a client-side abort a few seconds later that cancels the statement on the
+     * server, and as a last resort dropping the connection.
+     */
+    run<T>(fn: (client: Connection, ctx: RunContext) => Promise<T>, options?: RunOptions): Promise<T>;
+    private withDeadline;
+    /** Convenience: execute a query returning an Arrow table. */
+    query(sql: string, params?: BoundParams, options?: RunOptions): Promise<Table>;
+    /**
+     * Executes a query and reads at most `maxRows + 1` rows from one result stream, then
+     * closes the stream, which stops the statement on the server: no further batches are
+     * transferred or computed.
+     */
+    queryCapped(sql: string, params: BoundParams | undefined, maxRows: number, options?: RunOptions): Promise<CappedResult>;
+    /** Convenience: execute a statement returning the affected-row count (-1 when the engine does not count). */
+    update(sql: string, params?: BoundParams, options?: RunOptions): Promise<number>;
+}