@clickhouse/client 1.22.0 → 1.23.0-head.c8dc8d8.1

package/dist/common/settings.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SettingsMap = void 0;
+class SettingsMap {
+    record;
+    constructor(record) {
+        this.record = record;
+    }
+    toString() {
+        return `{${Object.entries(this.record)
+            .map(([k, v]) => `'${k}':'${v}'`)
+            .join(",")}}`;
+    }
+    static from(record) {
+        return new this(record);
+    }
+}
+exports.SettingsMap = SettingsMap;
+//# sourceMappingURL=settings.js.map

package/dist/common/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../src/common/settings.ts"],"names":[],"mappings":";;;AA+6DA,MAAa,WAAW;IACL,MAAM,CAAyB;IAChD,YAAoB,MAA8B;QAChD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;aACnC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;aAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAClB,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,MAA8B;QACxC,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;CACF;AAfD,kCAeC"}

package/dist/common/tracing.d.ts

@@ -0,0 +1,146 @@
+/**
+ * A minimal, dependency-free tracer interface that is a structural subset of
+ * the {@link https://opentelemetry.io/docs/specs/otel/trace/api/#tracer OpenTelemetry `Tracer` API}.
+ *
+ * The shapes below are deliberately declared so that a raw OpenTelemetry
+ * tracer (the object returned by `trace.getTracer(...)` from
+ * `@opentelemetry/api`) is assignable to {@link ClickHouseTracer} **as-is**,
+ * with no adapter and no casts:
+ *
+ * ```ts
+ * import { trace } from '@opentelemetry/api'
+ * const client = createClient({ tracer: trace.getTracer('clickhouse-js') })
+ * ```
+ *
+ * At the same time, the client itself imports nothing from OpenTelemetry -
+ * non-OTEL backends (Prometheus counters, an `EventEmitter`, a plain logger)
+ * can implement the same small surface directly.
+ *
+ * When a {@link ClickHouseTracer} is provided via
+ * {@link BaseClickHouseClientConfigOptions.tracer}, the client runs each
+ * tracked operation (`query`, `command`, `exec`, `insert`, `ping`) inside
+ * {@link ClickHouseTracer.startActiveSpan}, mutates the provided
+ * {@link ClickHouseSpan} during the operation
+ * ({@link ClickHouseSpan.setAttributes}, {@link ClickHouseSpan.setStatus},
+ * {@link ClickHouseSpan.recordException}), and calls
+ * {@link ClickHouseSpan.end} exactly once. For `command`, `exec`, `insert`,
+ * and `ping`, the span ends when the operation settles (regardless of
+ * outcome). For `query`, two spans are emitted: the `clickhouse.query` span
+ * ends as soon as the HTTP response headers are received; a child
+ * `clickhouse.query.stream` span is then handed to the `ResultSet`, which
+ * tracks the streaming progress and ends it when the response stream is fully
+ * consumed, closed, or fails.
+ *
+ * Calls are inlined directly into the client's hot path - there is no
+ * defensive wrapper around them. Any exception thrown by a tracer or span
+ * method will propagate up to the caller of the corresponding client method
+ * (`query`/`command`/`exec`/`insert`/`ping`). Implementations are therefore
+ * expected to be non-throwing; a trivial e2e test against your tracer is
+ * usually enough to catch regressions.
+ */
+export interface ClickHouseTracer<TSpan extends ClickHouseSpan = ClickHouseSpan> {
+    /**
+     * Called when a tracked operation begins. Same shape as OpenTelemetry's
+     * `Tracer.startActiveSpan(name, options, fn)` overload: implementations
+     * must invoke `fn` with the new span and return `fn`'s result untouched.
+     * The client runs the entire operation (an `async` function) inside `fn`,
+     * mutates the span during the operation, and ends it exactly once.
+     *
+     * @note The callback is asynchronous under the hood: the client keeps using
+     * the span across `await` points inside `fn`. For OpenTelemetry, active-span
+     * context propagation across those `await`s requires the
+     * `AsyncLocalStorageContextManager` (from
+     * `@opentelemetry/context-async-hooks`) to be registered - which is the
+     * default context manager in the OpenTelemetry Node.js SDK
+     * (`@opentelemetry/sdk-node` / `NodeTracerProvider`). With it in place,
+     * auto-instrumented child spans (e.g. from
+     * `@opentelemetry/instrumentation-http`) are parented under the ClickHouse
+     * operation span.
+     */
+    startActiveSpan<T>(name: string, options: ClickHouseSpanOptions, fn: (span: TSpan) => T): T;
+}
+/** Structural subset of the OpenTelemetry `Span` interface - a real OTEL
+ *  `Span` is assignable to this type as-is. Methods are declared as
+ *  `void`-returning, so OTEL's chainable `this`-returning methods remain
+ *  compatible. */
+export interface ClickHouseSpan {
+    /** Attach additional attributes to an in-flight span. Called at least once
+     *  for every span - typically right before {@link ClickHouseSpan.end} -
+     *  with operation-specific attributes such as `clickhouse.request.query_id`. */
+    setAttributes(attributes: ClickHouseSpanAttributes): void;
+    /** Set the logical status of the span. The codes are value-identical to
+     *  OTEL's `SpanStatusCode`; see {@link ClickHouseSpanStatusCode}. */
+    setStatus(status: ClickHouseSpanStatus): void;
+    /** Attach an exception that occurred during the span. Called before
+     *  {@link ClickHouseSpan.setStatus} with the `ERROR` code, before
+     *  {@link ClickHouseSpan.end}. Non-`Error` throwables are normalized
+     *  to `Error` by the client before this call. */
+    recordException(error: Error): void;
+    /** Called exactly once per span, regardless of success or failure. */
+    end(): void;
+}
+/** Structural subset of OTEL's `SpanOptions`. */
+export interface ClickHouseSpanOptions {
+    /** Value-identical to OTEL's `SpanKind`; see {@link ClickHouseSpanKind}.
+     *  The client always passes {@link ClickHouseSpanKind.CLIENT}, per the
+     *  OTEL database semantic conventions. */
+    kind?: number;
+    /** Initial attributes for the span. */
+    attributes?: ClickHouseSpanAttributes;
+}
+/** Span status; `code` values are listed in {@link ClickHouseSpanStatusCode}
+ *  and are value-identical to OTEL's `SpanStatusCode`. */
+export interface ClickHouseSpanStatus {
+    code: number;
+    message?: string;
+}
+/** Value-identical to OTEL's `SpanStatusCode`, so non-OTEL implementations
+ *  do not have to deal with magic numbers. */
+export declare const ClickHouseSpanStatusCode: {
+    readonly UNSET: 0;
+    readonly OK: 1;
+    readonly ERROR: 2;
+};
+/** Value-identical to OTEL's `SpanKind`. The client only ever uses
+ *  {@link ClickHouseSpanKind.CLIENT}. */
+export declare const ClickHouseSpanKind: {
+    readonly INTERNAL: 0;
+    readonly SERVER: 1;
+    readonly CLIENT: 2;
+    readonly PRODUCER: 3;
+    readonly CONSUMER: 4;
+};
+/** Free-form attribute bag; a subset of OTEL's `Attributes`. Implementations
+ *  should be tolerant of `undefined` values (skip them) and stringify
+ *  non-primitive values as needed. */
+export type ClickHouseSpanAttributes = Record<string, string | number | boolean | undefined>;
+/** Span name constants used by the client when starting spans.
+ *  Exposed so that adapters and tests can match on them. */
+export declare const ClickHouseSpanNames: {
+    readonly query: "clickhouse.query";
+    /** A child of {@link ClickHouseSpanNames.query} that covers the lifetime
+     *  of the `ResultSet` stream - from the first byte read to full
+     *  consumption, cancellation, or failure.  Ends with
+     *  `clickhouse.response.decoded_bytes` and (for row-streaming paths)
+     *  `db.response.returned_rows`. */
+    readonly query_stream: "clickhouse.query.stream";
+    readonly command: "clickhouse.command";
+    readonly exec: "clickhouse.exec";
+    readonly insert: "clickhouse.insert";
+    readonly ping: "clickhouse.ping";
+};
+export type ClickHouseSpanName = (typeof ClickHouseSpanNames)[keyof typeof ClickHouseSpanNames];
+/** Shared no-op span handed out by {@link NoopClickHouseTracer}. @internal */
+export declare const NoopClickHouseSpan: ClickHouseSpan;
+/** No-op tracer assigned once at client creation when no tracer is
+ *  configured, so the hot path stays branch-free (monomorphic call sites
+ *  that the JIT can inline). @internal */
+export declare const NoopClickHouseTracer: ClickHouseTracer;
+/** Records the exception on the span and marks it with the ERROR status,
+ *  normalizing non-`Error` throwables to `Error`.
+ *
+ *  Sets the {@link https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/#error-type `error.type`}
+ *  attribute to the error class name (e.g. `ClickHouseError`, `TypeError`),
+ *  and, for server-side errors ({@link ClickHouseError}), the numeric server
+ *  error code as `clickhouse.error.code`. */
+export declare function recordSpanError(span: ClickHouseSpan, err: unknown): void;

package/dist/common/tracing.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoopClickHouseTracer = exports.NoopClickHouseSpan = exports.ClickHouseSpanNames = exports.ClickHouseSpanKind = exports.ClickHouseSpanStatusCode = void 0;
+exports.recordSpanError = recordSpanError;
+const error_1 = require("./error");
+/** Value-identical to OTEL's `SpanStatusCode`, so non-OTEL implementations
+ *  do not have to deal with magic numbers. */
+exports.ClickHouseSpanStatusCode = {
+    UNSET: 0,
+    OK: 1,
+    ERROR: 2,
+};
+/** Value-identical to OTEL's `SpanKind`. The client only ever uses
+ *  {@link ClickHouseSpanKind.CLIENT}. */
+exports.ClickHouseSpanKind = {
+    INTERNAL: 0,
+    SERVER: 1,
+    CLIENT: 2,
+    PRODUCER: 3,
+    CONSUMER: 4,
+};
+/** Span name constants used by the client when starting spans.
+ *  Exposed so that adapters and tests can match on them. */
+exports.ClickHouseSpanNames = {
+    query: "clickhouse.query",
+    /** A child of {@link ClickHouseSpanNames.query} that covers the lifetime
+     *  of the `ResultSet` stream - from the first byte read to full
+     *  consumption, cancellation, or failure.  Ends with
+     *  `clickhouse.response.decoded_bytes` and (for row-streaming paths)
+     *  `db.response.returned_rows`. */
+    query_stream: "clickhouse.query.stream",
+    command: "clickhouse.command",
+    exec: "clickhouse.exec",
+    insert: "clickhouse.insert",
+    ping: "clickhouse.ping",
+};
+const noop = () => undefined;
+/** Shared no-op span handed out by {@link NoopClickHouseTracer}. @internal */
+exports.NoopClickHouseSpan = {
+    setAttributes: noop,
+    setStatus: noop,
+    recordException: noop,
+    end: noop,
+};
+/** No-op tracer assigned once at client creation when no tracer is
+ *  configured, so the hot path stays branch-free (monomorphic call sites
+ *  that the JIT can inline). @internal */
+exports.NoopClickHouseTracer = {
+    startActiveSpan: (_name, _options, fn) => fn(exports.NoopClickHouseSpan),
+};
+/** Records the exception on the span and marks it with the ERROR status,
+ *  normalizing non-`Error` throwables to `Error`.
+ *
+ *  Sets the {@link https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/#error-type `error.type`}
+ *  attribute to the error class name (e.g. `ClickHouseError`, `TypeError`),
+ *  and, for server-side errors ({@link ClickHouseError}), the numeric server
+ *  error code as `clickhouse.error.code`. */
+function recordSpanError(span, err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    const attributes = {
+        "error.type": error.constructor.name,
+    };
+    if (error instanceof error_1.ClickHouseError) {
+        const code = Number(error.code);
+        attributes["clickhouse.error.code"] = Number.isNaN(code)
+            ? error.code
+            : code;
+    }
+    span.setAttributes(attributes);
+    span.recordException(error);
+    span.setStatus({
+        code: exports.ClickHouseSpanStatusCode.ERROR,
+        message: error.message,
+    });
+}
+//# sourceMappingURL=tracing.js.map

package/dist/common/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../../src/common/tracing.ts"],"names":[],"mappings":";;;AA+KA,0CAiBC;AAhMD,mCAA0C;AA4G1C;8CAC8C;AACjC,QAAA,wBAAwB,GAAG;IACtC,KAAK,EAAE,CAAC;IACR,EAAE,EAAE,CAAC;IACL,KAAK,EAAE,CAAC;CACA,CAAC;AAEX;yCACyC;AAC5B,QAAA,kBAAkB,GAAG;IAChC,QAAQ,EAAE,CAAC;IACX,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;IACT,QAAQ,EAAE,CAAC;IACX,QAAQ,EAAE,CAAC;CACH,CAAC;AAUX;4DAC4D;AAC/C,QAAA,mBAAmB,GAAG;IACjC,KAAK,EAAE,kBAAkB;IACzB;;;;uCAImC;IACnC,YAAY,EAAE,yBAAyB;IACvC,OAAO,EAAE,oBAAoB;IAC7B,IAAI,EAAE,iBAAiB;IACvB,MAAM,EAAE,mBAAmB;IAC3B,IAAI,EAAE,iBAAiB;CACf,CAAC;AAIX,MAAM,IAAI,GAAG,GAAS,EAAE,CAAC,SAAS,CAAC;AACnC,8EAA8E;AACjE,QAAA,kBAAkB,GAAmB;IAChD,aAAa,EAAE,IAAI;IACnB,SAAS,EAAE,IAAI;IACf,eAAe,EAAE,IAAI;IACrB,GAAG,EAAE,IAAI;CACV,CAAC;AAEF;;0CAE0C;AAC7B,QAAA,oBAAoB,GAAqB;IACpD,eAAe,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,0BAAkB,CAAC;CACjE,CAAC;AAEF;;;;;;6CAM6C;AAC7C,SAAgB,eAAe,CAAC,IAAoB,EAAE,GAAY;IAChE,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAClE,MAAM,UAAU,GAA6B;QAC3C,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI;KACrC,CAAC;IACF,IAAI,KAAK,YAAY,uBAAe,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChC,UAAU,CAAC,uBAAuB,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;YACtD,CAAC,CAAC,KAAK,CAAC,IAAI;YACZ,CAAC,CAAC,IAAI,CAAC;IACX,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IAC/B,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,CAAC,SAAS,CAAC;QACb,IAAI,EAAE,gCAAwB,CAAC,KAAK;QACpC,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAC,CAAC;AACL,CAAC"}

package/dist/common/ts_utils.d.ts

@@ -0,0 +1,4 @@
+/** Adjusted from https://stackoverflow.com/a/72801672/4575540.
+ *  Useful for checking if we could not infer a concrete literal type
+ *  (i.e. if instead of 'JSONEachRow' or other literal we just get a generic {@link DataFormat} as an argument). */
+export type IsSame<A, B> = [A] extends [B] ? B extends A ? true : false : false;

package/dist/common/ts_utils.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ts_utils.js.map

package/dist/common/ts_utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ts_utils.js","sourceRoot":"","sources":["../../src/common/ts_utils.ts"],"names":[],"mappings":""}

package/dist/common/utils/connection.d.ts

@@ -0,0 +1,21 @@
+import type { CompressionMethod } from "../connection";
+import type { ClickHouseSettings } from "../settings";
+export type HttpHeader = number | string | string[];
+export type HttpHeaders = Record<string, HttpHeader | undefined>;
+export declare function withCompressionHeaders({ headers, request_compression_codec, response_compression_codec, }: {
+    headers: HttpHeaders;
+    request_compression_codec: CompressionMethod | undefined;
+    response_compression_codec: CompressionMethod | undefined;
+}): Record<string, string>;
+export declare function withHttpSettings(clickhouse_settings?: ClickHouseSettings, compression?: {
+    codec: CompressionMethod;
+} | undefined): ClickHouseSettings;
+export declare function isSuccessfulResponse(statusCode?: number): boolean;
+export declare function isJWTAuth(auth: unknown): auth is {
+    access_token: string;
+};
+export declare function isCredentialsAuth(auth: unknown): auth is {
+    username: string;
+    password: string;
+};
+export declare const EXCEPTION_TAG_HEADER_NAME = "x-clickhouse-exception-tag";

package/dist/common/utils/connection.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXCEPTION_TAG_HEADER_NAME = void 0;
+exports.withCompressionHeaders = withCompressionHeaders;
+exports.withHttpSettings = withHttpSettings;
+exports.isSuccessfulResponse = isSuccessfulResponse;
+exports.isJWTAuth = isJWTAuth;
+exports.isCredentialsAuth = isCredentialsAuth;
+function withCompressionHeaders({ headers, request_compression_codec, response_compression_codec, }) {
+    return {
+        ...headers,
+        ...(response_compression_codec
+            ? { "Accept-Encoding": response_compression_codec }
+            : {}),
+        ...(request_compression_codec
+            ? { "Content-Encoding": request_compression_codec }
+            : {}),
+    };
+}
+function withHttpSettings(clickhouse_settings, compression) {
+    return {
+        ...(compression
+            ? {
+                enable_http_compression: 1,
+            }
+            : {}),
+        ...clickhouse_settings,
+    };
+}
+function isSuccessfulResponse(statusCode) {
+    return Boolean(statusCode && 200 <= statusCode && statusCode < 300);
+}
+function isJWTAuth(auth) {
+    return auth !== null && typeof auth === "object" && "access_token" in auth;
+}
+function isCredentialsAuth(auth) {
+    return (auth !== null &&
+        typeof auth === "object" &&
+        "username" in auth &&
+        "password" in auth);
+}
+exports.EXCEPTION_TAG_HEADER_NAME = "x-clickhouse-exception-tag";
+//# sourceMappingURL=connection.js.map

package/dist/common/utils/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../../src/common/utils/connection.ts"],"names":[],"mappings":";;;AAMA,wDAoBC;AAED,4CAYC;AAED,oDAEC;AAED,8BAEC;AAED,8CASC;AArDD,SAAgB,sBAAsB,CAAC,EACrC,OAAO,EACP,yBAAyB,EACzB,0BAA0B,GAO3B;IACC,OAAO;QACL,GAAG,OAAO;QACV,GAAG,CAAC,0BAA0B;YAC5B,CAAC,CAAC,EAAE,iBAAiB,EAAE,0BAA0B,EAAE;YACnD,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,yBAAyB;YAC3B,CAAC,CAAC,EAAE,kBAAkB,EAAE,yBAAyB,EAAE;YACnD,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;AACJ,CAAC;AAED,SAAgB,gBAAgB,CAC9B,mBAAwC,EACxC,WAAsD;IAEtD,OAAO;QACL,GAAG,CAAC,WAAW;YACb,CAAC,CAAC;gBACE,uBAAuB,EAAE,CAAC;aAC3B;YACH,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,mBAAmB;KACvB,CAAC;AACJ,CAAC;AAED,SAAgB,oBAAoB,CAAC,UAAmB;IACtD,OAAO,OAAO,CAAC,UAAU,IAAI,GAAG,IAAI,UAAU,IAAI,UAAU,GAAG,GAAG,CAAC,CAAC;AACtE,CAAC;AAED,SAAgB,SAAS,CAAC,IAAa;IACrC,OAAO,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,cAAc,IAAI,IAAI,CAAC;AAC7E,CAAC;AAED,SAAgB,iBAAiB,CAC/B,IAAa;IAEb,OAAO,CACL,IAAI,KAAK,IAAI;QACb,OAAO,IAAI,KAAK,QAAQ;QACxB,UAAU,IAAI,IAAI;QAClB,UAAU,IAAI,IAAI,CACnB,CAAC;AACJ,CAAC;AAEY,QAAA,yBAAyB,GAAG,4BAA4B,CAAC"}

package/dist/common/utils/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./connection";
+export * from "./multipart";
+export * from "./sleep";
+export * from "./stream";
+export * from "./url";

package/dist/common/utils/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./connection"), exports);
+__exportStar(require("./multipart"), exports);
+__exportStar(require("./sleep"), exports);
+__exportStar(require("./stream"), exports);
+__exportStar(require("./url"), exports);
+//# sourceMappingURL=index.js.map

package/dist/common/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/common/utils/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B;AAC7B,8CAA4B;AAC5B,0CAAwB;AACxB,2CAAyB;AACzB,wCAAsB"}

package/dist/common/utils/multipart.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Query parameters are URL-encoded into the request URL as `param_*` entries.
+ * Once their encoded length passes this budget, {@link serializeQueryParamsForUrl}
+ * returns null so that they are routed through the multipart body instead, keeping
+ * oversized payloads out of the URL where HTTP intermediaries (nginx, AWS ALB,
+ * CloudFront) reject them with HTTP 414 or 400. The threshold leaves ample
+ * headroom under common request line limits.
+ */
+export declare const MAX_URL_BIND_PARAM_LENGTH = 4096;
+/**
+ * Early-return variant of the `param_*` serialization performed by
+ * {@link toSearchParams}: serializes {@link query_params} into `param_*`
+ * URL entries, returning them so the caller can reuse the result without
+ * serializing the params a second time, or returns null as soon as the
+ * URL-encoded length exceeds {@link MAX_URL_BIND_PARAM_LENGTH} — in which
+ * case the params should be sent as a multipart/form-data body instead.
+ */
+export declare function serializeQueryParamsForUrl(query_params: Record<string, unknown>): [string, string][] | null;
+/**
+ * Builds a multipart/form-data body from a record of named string parts.
+ *
+ * Example output:
+ *
+ *   --BOUNDARY\r\n
+ *   Content-Disposition: form-data; name="query"\r\n
+ *   \r\n
+ *   SELECT * FROM t WHERE x IN {values:Array(String)}\r\n
+ *   --BOUNDARY\r\n
+ *   Content-Disposition: form-data; name="param_values"\r\n
+ *   \r\n
+ *   ['a@b.com','c@d.com']\r\n
+ *   --BOUNDARY--\r\n
+ */
+export declare function buildMultipartBody(parts: Record<string, string>, boundary: string): string;

package/dist/common/utils/multipart.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_URL_BIND_PARAM_LENGTH = void 0;
+exports.serializeQueryParamsForUrl = serializeQueryParamsForUrl;
+exports.buildMultipartBody = buildMultipartBody;
+const data_formatter_1 = require("../data_formatter");
+const SAFE_PART_NAME = /^[A-Za-z0-9_.-]+$/;
+/**
+ * Query parameters are URL-encoded into the request URL as `param_*` entries.
+ * Once their encoded length passes this budget, {@link serializeQueryParamsForUrl}
+ * returns null so that they are routed through the multipart body instead, keeping
+ * oversized payloads out of the URL where HTTP intermediaries (nginx, AWS ALB,
+ * CloudFront) reject them with HTTP 414 or 400. The threshold leaves ample
+ * headroom under common request line limits.
+ */
+exports.MAX_URL_BIND_PARAM_LENGTH = 4096;
+/**
+ * Early-return variant of the `param_*` serialization performed by
+ * {@link toSearchParams}: serializes {@link query_params} into `param_*`
+ * URL entries, returning them so the caller can reuse the result without
+ * serializing the params a second time, or returns null as soon as the
+ * URL-encoded length exceeds {@link MAX_URL_BIND_PARAM_LENGTH} — in which
+ * case the params should be sent as a multipart/form-data body instead.
+ */
+function serializeQueryParamsForUrl(query_params) {
+    const entries = [];
+    // Raw length is a lower bound on the encoded length, so large payloads
+    // short-circuit without materializing the encoded string.
+    let rawLength = 0;
+    for (const [key, value] of Object.entries(query_params)) {
+        const name = `param_${key}`;
+        const formatted = (0, data_formatter_1.formatQueryParams)({ value });
+        rawLength += name.length + formatted.length;
+        if (rawLength > exports.MAX_URL_BIND_PARAM_LENGTH) {
+            return null;
+        }
+        entries.push([name, formatted]);
+    }
+    // Measure the exact encoded length, accounting for percent-encoding expansion.
+    if (new URLSearchParams(entries).toString().length > exports.MAX_URL_BIND_PARAM_LENGTH) {
+        return null;
+    }
+    return entries;
+}
+/**
+ * Builds a multipart/form-data body from a record of named string parts.
+ *
+ * Example output:
+ *
+ *   --BOUNDARY\r\n
+ *   Content-Disposition: form-data; name="query"\r\n
+ *   \r\n
+ *   SELECT * FROM t WHERE x IN {values:Array(String)}\r\n
+ *   --BOUNDARY\r\n
+ *   Content-Disposition: form-data; name="param_values"\r\n
+ *   \r\n
+ *   ['a@b.com','c@d.com']\r\n
+ *   --BOUNDARY--\r\n
+ */
+function buildMultipartBody(parts, boundary) {
+    const chunks = [];
+    // Part names are validated against SAFE_PART_NAME to prevent header injection
+    // (a name could otherwise smuggle CRLF or quotes into the Content-Disposition
+    // line). Part values are intentionally NOT validated/escaped: the only way a
+    // value could forge a part delimiter is by containing the boundary, and the
+    // boundary is a random UUID generated per request by the caller, so it cannot
+    // be predicted or collided with by user-supplied input.
+    for (const [name, value] of Object.entries(parts)) {
+        if (!SAFE_PART_NAME.test(name)) {
+            throw new Error(`Invalid multipart part name: "${name}". ` +
+                `Part names must match ${SAFE_PART_NAME}.`);
+        }
+        chunks.push(`--${boundary}\r\n` +
+            `Content-Disposition: form-data; name="${name}"\r\n` +
+            `\r\n` +
+            `${value}\r\n`);
+    }
+    chunks.push(`--${boundary}--\r\n`);
+    return chunks.join("");
+}
+//# sourceMappingURL=multipart.js.map

package/dist/common/utils/multipart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.js","sourceRoot":"","sources":["../../../src/common/utils/multipart.ts"],"names":[],"mappings":";;;AAsBA,gEAuBC;AAiBD,gDA8BC;AA5FD,sDAAsD;AAEtD,MAAM,cAAc,GAAG,mBAAmB,CAAC;AAE3C;;;;;;;GAOG;AACU,QAAA,yBAAyB,GAAG,IAAI,CAAC;AAE9C;;;;;;;GAOG;AACH,SAAgB,0BAA0B,CACxC,YAAqC;IAErC,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,uEAAuE;IACvE,0DAA0D;IAC1D,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,GAAG,SAAS,GAAG,EAAE,CAAC;QAC5B,MAAM,SAAS,GAAG,IAAA,kCAAiB,EAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/C,SAAS,IAAI,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC;QAC5C,IAAI,SAAS,GAAG,iCAAyB,EAAE,CAAC;YAC1C,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,+EAA+E;IAC/E,IACE,IAAI,eAAe,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC,MAAM,GAAG,iCAAyB,EAC1E,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,kBAAkB,CAChC,KAA6B,EAC7B,QAAgB;IAEhB,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,8EAA8E;IAC9E,8EAA8E;IAC9E,6EAA6E;IAC7E,4EAA4E;IAC5E,8EAA8E;IAC9E,wDAAwD;IACxD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CACb,iCAAiC,IAAI,KAAK;gBACxC,yBAAyB,cAAc,GAAG,CAC7C,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,IAAI,CACT,KAAK,QAAQ,MAAM;YACjB,yCAAyC,IAAI,OAAO;YACpD,MAAM;YACN,GAAG,KAAK,MAAM,CACjB,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,KAAK,QAAQ,QAAQ,CAAC,CAAC;IAEnC,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACzB,CAAC"}

package/dist/common/utils/sleep.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @deprecated This utility function is not intended to be used outside of the client implementation anymore. Please, use `setTimeout` directly or a more full-featured utility library if you need additional features like cancellation or timers management.
+ */
+export declare function sleep(ms: number): Promise<void>;

package/dist/common/utils/sleep.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = sleep;
+/**
+ * @deprecated This utility function is not intended to be used outside of the client implementation anymore. Please, use `setTimeout` directly or a more full-featured utility library if you need additional features like cancellation or timers management.
+ */
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(() => {
+        resolve(void 0);
+    }, ms));
+}
+//# sourceMappingURL=sleep.js.map

package/dist/common/utils/sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.js","sourceRoot":"","sources":["../../../src/common/utils/sleep.ts"],"names":[],"mappings":";;AAGA,sBAMC;AATD;;GAEG;AACI,KAAK,UAAU,KAAK,CAAC,EAAU;IACpC,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAC5B,UAAU,CAAC,GAAG,EAAE;QACd,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAClB,CAAC,EAAE,EAAE,CAAC,CACP,CAAC;AACJ,CAAC"}

package/dist/common/utils/stream.d.ts

@@ -0,0 +1,15 @@
+export declare const CARET_RETURN: 13;
+/**
+ * After 25.11, a newline error character is preceded by a caret return
+ * this is a strong indication that we have an exception in the stream.
+ *
+ * Example with exception marker `FOOBAR`:
+ *
+ * \r\n__exception__\r\nFOOBAR
+ * boom
+ * 5 FOOBAR\r\n__exception__\r\n
+ *
+ * In this case, the exception length is 5 (including the newline character),
+ * and the exception message is "boom".
+ */
+export declare function extractErrorAtTheEndOfChunk(chunk: Uint8Array, exceptionTag: string): Error;

package/dist/common/utils/stream.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CARET_RETURN = void 0;
+exports.extractErrorAtTheEndOfChunk = extractErrorAtTheEndOfChunk;
+const error_1 = require("../error");
+const EXCEPTION_MARKER = "__exception__";
+const NEWLINE = 0x0a;
+exports.CARET_RETURN = 0x0d;
+/**
+ * After 25.11, a newline error character is preceded by a caret return
+ * this is a strong indication that we have an exception in the stream.
+ *
+ * Example with exception marker `FOOBAR`:
+ *
+ * \r\n__exception__\r\nFOOBAR
+ * boom
+ * 5 FOOBAR\r\n__exception__\r\n
+ *
+ * In this case, the exception length is 5 (including the newline character),
+ * and the exception message is "boom".
+ */
+function extractErrorAtTheEndOfChunk(chunk, exceptionTag) {
+    try {
+        const bytesCountAfterErrLenHint = 1 + // space
+            EXCEPTION_MARKER.length + // __exception__
+            2 + // \r\n
+            exceptionTag.length + // <value taken from the header>
+            2; // \r\n
+        let errMsgLenStartIdx = chunk.length - bytesCountAfterErrLenHint;
+        if (errMsgLenStartIdx < 1) {
+            return new Error("there was an error in the stream, but the last chunk is malformed");
+        }
+        do {
+            --errMsgLenStartIdx;
+        } while (chunk[errMsgLenStartIdx] !== NEWLINE);
+        const textDecoder = new TextDecoder("utf-8");
+        const errMsgLen = parseInt(textDecoder.decode(chunk.subarray(errMsgLenStartIdx, -bytesCountAfterErrLenHint)));
+        if (isNaN(errMsgLen) || errMsgLen <= 0) {
+            return new Error("there was an error in the stream; failed to parse the message length");
+        }
+        const errMsg = textDecoder.decode(chunk.subarray(errMsgLenStartIdx - errMsgLen + 1, // skipping the newline character
+        errMsgLenStartIdx));
+        return (0, error_1.parseError)(errMsg);
+    }
+    catch (err) {
+        // theoretically, it can happen if a proxy cuts the last chunk
+        return err;
+    }
+}
+//# sourceMappingURL=stream.js.map

package/dist/common/utils/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../../src/common/utils/stream.ts"],"names":[],"mappings":";;;AAoBA,kEAiDC;AArED,oCAAsC;AAEtC,MAAM,gBAAgB,GAAG,eAAe,CAAC;AAEzC,MAAM,OAAO,GAAG,IAAa,CAAC;AACjB,QAAA,YAAY,GAAG,IAAa,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,SAAgB,2BAA2B,CACzC,KAAiB,EACjB,YAAoB;IAEpB,IAAI,CAAC;QACH,MAAM,yBAAyB,GAC7B,CAAC,GAAG,QAAQ;YACZ,gBAAgB,CAAC,MAAM,GAAG,gBAAgB;YAC1C,CAAC,GAAG,OAAO;YACX,YAAY,CAAC,MAAM,GAAG,gCAAgC;YACtD,CAAC,CAAC,CAAC,OAAO;QAEZ,IAAI,iBAAiB,GAAG,KAAK,CAAC,MAAM,GAAG,yBAAyB,CAAC;QACjE,IAAI,iBAAiB,GAAG,CAAC,EAAE,CAAC;YAC1B,OAAO,IAAI,KAAK,CACd,mEAAmE,CACpE,CAAC;QACJ,CAAC;QAED,GAAG,CAAC;YACF,EAAE,iBAAiB,CAAC;QACtB,CAAC,QAAQ,KAAK,CAAC,iBAAiB,CAAC,KAAK,OAAO,EAAE;QAE/C,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC;QAE7C,MAAM,SAAS,GAAG,QAAQ,CACxB,WAAW,CAAC,MAAM,CAChB,KAAK,CAAC,QAAQ,CAAC,iBAAiB,EAAE,CAAC,yBAAyB,CAAC,CAC9D,CACF,CAAC;QAEF,IAAI,KAAK,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;YACvC,OAAO,IAAI,KAAK,CACd,sEAAsE,CACvE,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAC/B,KAAK,CAAC,QAAQ,CACZ,iBAAiB,GAAG,SAAS,GAAG,CAAC,EAAE,iCAAiC;QACpE,iBAAiB,CAClB,CACF,CAAC;QAEF,OAAO,IAAA,kBAAU,EAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,8DAA8D;QAC9D,OAAO,GAAY,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/common/utils/url.d.ts

@@ -0,0 +1,20 @@
+import type { ClickHouseSettings } from "../settings";
+export declare function transformUrl({ url, pathname, searchParams, }: {
+    url: URL;
+    pathname?: string;
+    searchParams?: URLSearchParams;
+}): URL;
+interface ToSearchParamsOptions {
+    database: string | undefined;
+    clickhouse_settings?: ClickHouseSettings;
+    query_params?: Record<string, unknown>;
+    /** Pre-serialized `param_*` entries (e.g. from {@link serializeQueryParamsForUrl});
+     *  used as-is instead of serializing {@link query_params} again. */
+    param_entries?: [string, string][];
+    query?: string;
+    session_id?: string;
+    query_id: string;
+    role?: string | Array<string>;
+}
+export declare function toSearchParams({ database, query, query_params, param_entries, clickhouse_settings, session_id, query_id, role, }: ToSearchParamsOptions): URLSearchParams;
+export {};