Allow selecting HTTP transport in DBSQLClient.connect()

Bắt đầu với lib/contracts/IDBSQLClient.ts và lib/DBSQLClient.ts, sau đó kiểm tra các bài kiểm thử HTTP transport hiện có và bài kiểm thử E2E của HTTP proxy. Xác nhận rằng các tùy chọn kết nối công khai expose thiết lập transport đã thống nhất, HTTPS vẫn là mặc định và việc chọn HTTP một cách tường minh sẽ đi tới implementation kết nối hiện có mà không cần workaround bằng private method.

Summary

Please expose the existing HTTP transport support through the public DBSQLClient.connect() options.
I would be happy to submit a PR implementing this change if the maintainers agree with the proposed direction and public API.

The lower-level connection implementation supports both HTTP and HTTPS, but DBSQLClient currently hardcodes HTTPS.

Motivation

Some deployments connect to Databricks through a trusted local or internal reverse proxy, sidecar, or gateway:

Application --HTTP--> Internal proxy --HTTPS--> Databricks

In our concrete setup, authentication is also handled at the proxy level. The proxy injects the Databricks bearer token, while the application intentionally provides no authorization header.

This authentication arrangement is only one use case. The general issue is that callers cannot select the transport protocol for the endpoint supplied to DBSQLClient.

The existing proxy option does not address this scenario because it represents a forward proxy using CONNECT semantics, rather than a reverse proxy exposed as the Databricks endpoint.

Current behavior

The public ConnectionOptions type in lib/contracts/IDBSQLClient.ts does not expose an HTTP/HTTPS option.

Additionally, DBSQLClient.getConnectionOptions() in lib/DBSQLClient.ts hardcodes:

https: true,

Consequently, passing an untyped https: false value does not work: it is discarded and the client still connects using an https:// URL.

The internal implementation already appears to support the requested behavior:

• IConnectionOptions includes https?: boolean
• HttpConnection selects either http.Agent or https.Agent
• HttpConnection constructs either an http:// or https:// URL
• existing tests exercise the HTTP behavior
• the HTTP proxy E2E test overrides getConnectionOptions() to set https = false

Proposed API

Expose the existing option publicly while preserving HTTPS as the default:

await client.connect({
  host: 'localhost',
  port: 3015,
  path: '/proxy/databricks/sql/1.0/warehouses/<warehouse-id>',
  https: false,
  authType: 'custom',
  provider: {
    async authenticate() {
      return {};
    },
  },
});

The implementation could map it as follows:

https: options.https ?? true,

Alternatively, a more explicit public option could be introduced:

protocol?: 'http' | 'https';

HTTPS should remain the default, and HTTP should require explicit opt-in.

Current workaround

We currently override the private connection-options mapper:

type PublicConnectionOptions = Parameters<DBSQLClient['connect']>[0];

type InternalConnectionOptions = {
  https?: boolean;
  [key: string]: unknown;
};

type ClientConnectionOptionsFactory = {
  getConnectionOptions(
    options: PublicConnectionOptions,
  ): InternalConnectionOptions;
};

const client = new DBSQLClient();
const internalClient =
  client as unknown as ClientConnectionOptionsFactory;

const getConnectionOptions =
  internalClient.getConnectionOptions.bind(client);

internalClient.getConnectionOptions = (options) => ({
  ...getConnectionOptions(options),
  https: false,
});

This works end to end and preserves the driver's normal connection handling, but it relies on a private method and may break between releases.

Security considerations

Plain HTTP should be documented as appropriate only for trusted local or private-network connections.

In our setup:

• the application-to-proxy connection is local/internal
• the proxy injects the Databricks token at the proxy layer
• the application does not send Databricks credentials over HTTP
• the proxy-to-Databricks connection uses HTTPS

Environment

• @databricks/sql: 2.0.0