Allow to provide a custom http agent and disable the auth header

[slvrtrn]

New features

• Added an option to provide a custom HTTP Agent in the client configuration via the http_agent option (#283, related: #278). The following conditions apply if a custom HTTP Agent is provided:

  • The max_open_connections and tls options will have no effect and will be ignored by the client, as it is a part of the underlying (default) HTTP Agent configuration.
  • keep_alive.enabled will only regulate the default value of the Connection header (true -> Connection: keep-alive, false -> Connection: close).
  • While the idle socket management will still work, it is now possible to disable it completely by setting the keep_alive.idle_socket_ttl value to 0.

• Added a new client configuration option: set_basic_auth_header which disables the Authorization header that is set by the client by default for every outgoing HTTP request. One of the possible scenarios when it is necessary to disable this header is when a custom HTTPS agent is used, and the server requires TLS authorization with certificates. For example:

  const agent = new https.Agent({
    ca: fs.readFileSync('./ca.crt'),
  })
  const client = createClient({
    url: 'https://server.clickhouseconnect.test:8443',
    http_agent: agent,
    // With a custom HTTPS agent, the client won't use the default HTTPS connection implementation; the basic TLS headers should be provided manually
    http_headers: {
      'X-ClickHouse-User': 'default',
      'X-ClickHouse-Key': '',
    },
    // Authorization header conflicts with the TLS headers; disable it.
    set_basic_auth_header: false,
  })

NB: It is currently not possible to set the set_basic_auth_header option via the URL params.

Checklist

• Unit and integration tests covering the common scenarios were added
• A human-readable description of the changes was provided to include in CHANGELOG
• For significant changes, documentation in https://github.com/ClickHouse/clickhouse-docs was updated with further explanations or tutorials - Update the CHJS docs for 1.2.0 clickhouse-docs#2412

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
94.6% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud

[slvrtrn]

Docs: ClickHouse/clickhouse-docs#2412

[mshustov]

can't we run the test against Cloud?

[slvrtrn]

We can, but this is slightly more annoying - it will have to choose between HTTP and HTTPS agent, plus I wanted to test the auth with a CA cert (so I'll need to add that to the repo as well).

[mshustov]

what if we change the client signature

  /** The name of the user on whose behalf requests are made.
   *  @default default */
  username?: string | null
  /** The user password.
   *  @default empty string */
  password?: string | null

if null is provided, no defaults are applied, and no auth header is set?