feat(worker): Add support for HTTP CONNECT Proxy (#1411)

Author: mjameswh

.github/workflows/ci.yml

@@ -89,7 +89,7 @@ jobs:
           prefix-key: corebridge-buildcache
           shared-key: ${{ matrix.platform }}
           env-vars: ''
-          save-if: ${{ env.IS_MAIN_OR_RELEASE }}
+          save-if: env.IS_MAIN_OR_RELEASE == 'true'
 
       - name: Compile rust code
         if: steps.cached-artifact.outputs.cache-hit != 'true'
@@ -182,7 +182,7 @@ jobs:
       - name: Save NPM cache
         uses: actions/cache/save@v4
         # Only saves NPM cache from the main branch, to reduce pressure on the cache (limited to 10GB).
-        if: ${{ env.IS_MAIN_OR_RELEASE }}
+        if: env.IS_MAIN_OR_RELEASE == 'true'
         with:
           path: ${{ steps.npm-cache-dir.outputs.dir }}
           key: npm-main-${{ matrix.platform }}-${{ hashFiles('./package-lock.json') }}
@@ -254,11 +254,11 @@ jobs:
         run: npm run build -- --ignore @temporalio/core-bridge
 
       - name: Install Temporal CLI
-        if: ${{ matrix.server == 'cli' }}
+        if: matrix.server == 'cli'
         uses: temporalio/setup-temporal@v0
 
       - name: Run Temporal CLI
-        if: ${{ matrix.server == 'cli' }}
+        if: matrix.server == 'cli'
         shell: bash
         run: |
           temporal server start-dev --headless &
@@ -357,11 +357,11 @@ jobs:
         run: node scripts/init-from-verdaccio.js --registry-dir ./tmp/registry --sample https://github.com/temporalio/samples-typescript/tree/next/${{ matrix.sample }} --target-dir ${{ runner.temp }}/example
 
       - name: Install Temporal CLI
-        if: ${{ matrix.server == 'cli' }}
+        if: matrix.server == 'cli'
         uses: temporalio/setup-temporal@v0
 
       - name: Run Temporal CLI
-        if: ${{ matrix.server == 'cli' }}
+        if: matrix.server == 'cli'
         shell: bash
         run: |
           temporal server start-dev --headless &
@@ -370,12 +370,12 @@ jobs:
       - name: Create certs dir
         shell: bash
         run: node scripts/create-certs-dir.js "${{ runner.temp }}/certs"
-        if: ${{ matrix.server == 'cloud' }}
+        if: matrix.server == 'cloud'
 
       - name: Test run a workflow (non-cloud)
         run: node scripts/test-example.js --work-dir "${{ runner.temp }}/example"
         shell: bash
-        if: ${{ matrix.server == 'cli' }}
+        if: matrix.server == 'cli'
 
       - name: Test run a workflow (cloud)
         run: node scripts/test-example.js --work-dir "${{ runner.temp }}/example"
@@ -387,7 +387,7 @@ jobs:
           TEMPORAL_CLIENT_CERT_PATH: ${{ runner.temp }}/certs/client.pem
           TEMPORAL_CLIENT_KEY_PATH: ${{ runner.temp }}/certs/client.key
           TEMPORAL_TASK_QUEUE: ${{ format('{0}-{1}-{2}', matrix.platform, matrix.node, matrix.sample) }}
-        if: ${{ matrix.server == 'cloud' }}
+        if: matrix.server == 'cloud'
 
       - name: Destroy certs dir
         if: always()
@@ -404,6 +404,7 @@ jobs:
       typescript-repo-path: ${{github.event.pull_request.head.repo.full_name}}
       version: ${{github.event.pull_request.head.ref}}
       version-is-repo-ref: true
+      features-repo-ref: http-connect-proxy-typescript
 
   stress-tests-no-reuse-context:
     name: Stress Tests (No Reuse V8 Context)
@@ -541,10 +542,10 @@ jobs:
           ALGOLIA_API_KEY: ${{ secrets.ALGOLIA_API_KEY }}
 
       - name: Deploy prod docs # TODO: only deploy prod docs when we publish a new version
-        if: ${{ env.IS_MAIN_OR_RELEASE }}
+        if: env.IS_MAIN_OR_RELEASE == 'true'
         run: npx vercel deploy packages/docs/build -t ${{ secrets.VERCEL_TOKEN }} --name typescript --scope temporal --prod --yes
 
       - name: Deploy draft docs
         # Don't run on forks, since secrets won't be available, and command will fail
-        if: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && github.ref != 'refs/heads/main' }}
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && github.ref != 'refs/heads/main'
         run: npx vercel deploy packages/docs/build -t ${{ secrets.VERCEL_TOKEN }} --name typescript --scope temporal --yes

.github/workflows/stress.yml

@@ -99,7 +99,7 @@ jobs:
           prefix-key: corebridge-buildcache
           shared-key: linux-intel
           env-vars: ''
-          save-if: ${{ env.IS_MAIN_BRANCH }}
+          save-if: env.IS_MAIN_BRANCH == 'true'
 
       - name: Download dependencies
         # Make up to 3 attempts to install NPM dependencies, to work around transient NPM errors
@@ -126,16 +126,16 @@ jobs:
           timeout ${{ inputs.test-timeout-minutes }}m npm run ${{ inputs.test-type }}
 
       - run: for f in $TEMPORAL_TESTING_LOG_DIR/*.log; do tail -20000 $f > $TEMPORAL_TESTING_LOG_DIR/tails/$(basename $f); done
-        if: ${{ always() }}
+        if: always()
 
       - uses: actions/upload-artifact@v4
-        if: ${{ always() }}
+        if: always()
         with:
           name: worker-logs-${{ inputs.reuse-v8-context && 'reuse-v8' || 'no-reuse-v8' }}
           path: ${{ env.TEMPORAL_TESTING_LOG_DIR }}/tails
 
       - uses: actions/upload-artifact@v4
-        if: ${{ always() }}
+        if: always()
         with:
           name: worker-mem-logs-${{ inputs.reuse-v8-context && 'reuse-v8' || 'no-reuse-v8' }}
           path: ${{ env.TEMPORAL_TESTING_MEM_LOG_DIR }}

packages/client/src/connection.ts

@@ -1,7 +1,12 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import * as grpc from '@grpc/grpc-js';
 import type { RPCImpl } from 'protobufjs';
-import { filterNullAndUndefined, normalizeTlsConfig, TLSConfig } from '@temporalio/common/lib/internal-non-workflow';
+import {
+  filterNullAndUndefined,
+  normalizeTlsConfig,
+  TLSConfig,
+  normalizeTemporalGrpcEndpointAddress,
+} from '@temporalio/common/lib/internal-non-workflow';
 import { Duration, msOptionalToNumber } from '@temporalio/common/lib/time';
 import { isGrpcServiceError, ServiceError } from './errors';
 import { defaultGrpcRetryOptions, makeGrpcRetryInterceptor } from './grpc-retry';
@@ -13,8 +18,9 @@ import { CallContext, HealthService, Metadata, OperatorService, WorkflowService
  */
 export interface ConnectionOptions {
   /**
-   * Server hostname and optional port.
-   * Port defaults to 7233 if address contains only host.
+   * The address of the Temporal server to connect to, in `hostname:port` format.
+   *
+   * Port defaults to 7233. Raw IPv6 addresses must be wrapped in square brackets (e.g. `[ipv6]:port`).
    *
    * @default localhost:7233
    */
@@ -167,10 +173,7 @@ function normalizeGRPCConfig(options?: ConnectionOptions): ConnectionOptions {
     }
   }
   if (rest.address) {
-    // eslint-disable-next-line prefer-const
-    let [host, port] = rest.address.split(':', 2);
-    port = port || '7233';
-    rest.address = `${host}:${port}`;
+    rest.address = normalizeTemporalGrpcEndpointAddress(rest.address);
   }
   const tls = normalizeTlsConfig(tlsFromConfig);
   if (tls) {

packages/common/src/internal-non-workflow/index.ts

@@ -6,5 +6,7 @@
 export * from './codec-helpers';
 export * from './codec-types';
 export * from './data-converter-helpers';
+export * from './parse-host-uri';
+export * from './proxy-config';
 export * from './tls-config';
 export * from './utils';

packages/common/src/internal-non-workflow/parse-host-uri.ts

@@ -0,0 +1,102 @@
+/**
+ * This file contain helper functions to parse specific subsets of URIs.
+ *
+ * The ECMAScript-compliant URL class don't properly handle some syntaxes that
+ * we care about, such as not providing a protocol (e.g. '127.0.0.1:7233'), and
+ * performs some normalizations that are not desirable for our use cases
+ * (e.g. parsing 'http://127.0.0.1:7233' adds a '/' path). On the other side,
+ * simply using `split(':')` breaks on IPv6 addresses. Hence these helpers.
+ */
+
+/**
+ * Scheme. Requires but doesn't capture the ':' or '://' separator that follows.
+ * e.g. `http:` will be captured as 'http'.
+ */
+const scheme = '(?:(?<scheme>[a-z][a-z0-9]+):(?:\\/\\/)?)';
+
+/**
+ * IPv4-style hostname. Not captured.
+ * e.g.: `192.168.1.100`.
+ */
+const ipv4Hostname = '(?:\\d{1,3}(?:\\.\\d{1,3}){3})';
+
+/**
+ * IPv6-style hostname; must be enclosed in square brackets. Not captured.
+ * e.g.: `[::1]`, `[2001:db8::1]`, `[::FFFF:129.144.52.38]`, etc.
+ */
+const ipv6Hostname = '(?:\\[(?<ipv6>[0-9a-fA-F.:]+)\\])';
+
+// DNS-style hostname. Not captured.
+// e.g.: `test.com` or `localhost`.
+const dnsHostname = '(?:[^:/]+)';
+
+const hostname = `(?:${ipv4Hostname}|${ipv6Hostname}|${dnsHostname})`;
+
+// Port number. Requires but don't capture a preceeding ':' separator.
+// For example, `:7233` will be captured as `7233`.
+const port = '(?::(?<port>\\d+))';
+
+const protoHostPortRegex = new RegExp(`^${scheme}??(?<hostname>${hostname})${port}?$`);
+
+export interface ProtoHostPort {
+  scheme?: string;
+  hostname: string;
+  port?: number;
+}
+
+/**
+ * Split a URI composed only of a scheme, a hostname, and port.
+ * The scheme and port are optional.
+ *
+ * Examples of valid URIs for HTTP CONNECT proxies:
+ *
+ * ```
+ * http://test.com:8080 => { scheme: 'http', host: 'test.com', port: 8080 }
+ * http://192.168.0.1:8080 => { scheme: 'http', host: '192.168.0.1', port: 8080 }
+ * [::1]:8080 => { scheme: 'http', host: '::1', port: 8080 }
+ * [::ffff:192.0.2.128]:8080 => { scheme: 'http', host: '::ffff:192.0.2.128', port: 8080 }
+ * 192.168.0.1:8080 => { scheme: 'http', host: '192.168.0.1', port: 8080 }
+ * ```
+ */
+export function splitProtoHostPort(uri: string): ProtoHostPort | undefined {
+  const match = protoHostPortRegex.exec(uri);
+  if (!match?.groups) return undefined;
+  return {
+    scheme: match.groups.scheme,
+    hostname: match.groups.ipv6 ?? match.groups.hostname,
+    port: match.groups.port !== undefined ? Number(match.groups.port) : undefined,
+  };
+}
+
+export function joinProtoHostPort(components: ProtoHostPort): string {
+  const { scheme, hostname, port } = components;
+  const schemeText = scheme ? `${scheme}:` : '';
+  const hostnameText = hostname.includes(':') ? `[${hostname}]` : hostname;
+  const portText = port !== undefined ? `:${port}` : '';
+  return `${schemeText}${hostnameText}${portText}`;
+}
+
+/**
+ * Parse the address for the gRPC endpoint of a Temporal server.
+ *
+ * - The URI may only contain a hostname and a port.
+ * - Port is optional; it defaults to 7233.
+ *
+ * Examples of valid URIs:
+ *
+ * ```
+ * 127.0.0.1:7233 => { host: '192.168.0.1', port: 7233 }
+ * my.temporal.service.com:7233 => { host: 'my.temporal.service.com', port: 7233 }
+ * [::ffff:192.0.2.128]:8080 => { host: '[::ffff:192.0.2.128]', port: 8080 }
+ * ```
+ */
+export function normalizeTemporalGrpcEndpointAddress(uri: string): string {
+  const splitted = splitProtoHostPort(uri);
+  if (!splitted || splitted.scheme !== undefined) {
+    throw new TypeError(
+      `Invalid address for Temporal gRPC endpoint: expected URI of the form 'hostname' or 'hostname:port'; got '${uri}'`
+    );
+  }
+  splitted.port ??= 7233;
+  return joinProtoHostPort(splitted);
+}

packages/common/src/internal-non-workflow/proxy-config.ts

@@ -0,0 +1,60 @@
+import { ProtoHostPort, splitProtoHostPort } from './parse-host-uri';
+
+/**
+ * Configuration for HTTP CONNECT proxying.
+ */
+export interface HttpConnectProxyConfig {
+  type: 'http-connect';
+
+  /**
+   * Address of the HTTP CONNECT proxy server, in either `hostname:port` or `http://hostname:port` formats.
+   *
+   * Port is required, and only the `http` scheme is supported. Raw IPv6 addresses must be wrapped in square brackets
+   * (e.g. `[ipv6]:port`).
+   */
+  targetHost: string;
+
+  /**
+   * Basic auth for the HTTP CONNECT proxy, if any.
+   *
+   * Neither username nor password may contain `:` or `@`.
+   *
+   * Note that these credentials will be exposed through environment variables, and will be exchanged in non-encrypted
+   * form ovrer the network. The connection to the proxy server is not encrypted.
+   */
+  basicAuth?: {
+    username: string;
+    password: string;
+  };
+}
+
+export type ProxyConfig = HttpConnectProxyConfig;
+
+/**
+ * Parse the address of a HTTP CONNECT proxy endpoint.
+ *
+ * - The URI may only contain a scheme, a hostname, and a port;
+ * - If specified, scheme must be 'http';
+ * - Port is required.
+ *
+ * Examples of valid URIs:
+ *
+ * ```
+ * 127.0.0.1:8080 => { scheme: 'http', host: '192.168.0.1', port: 8080 }
+ * my.temporal.service.com:8888 => { scheme: 'http', host: 'my.temporal.service.com', port: 8888 }
+ * [::ffff:192.0.2.128]:8080 => { scheme: 'http', host: '::ffff:192.0.2.128', port: 8080 }
+ * ```
+ */
+export function parseHttpConnectProxyAddress(target: string): ProtoHostPort {
+  const match = splitProtoHostPort(target);
+  if (!match)
+    throw new TypeError(
+      `Invalid address for HTTP CONNECT proxy: expected 'hostname:port' or '[ipv6 address]:port'; got '${target}'`
+    );
+  const { scheme = 'http', hostname: host, port } = match;
+  if (scheme !== 'http')
+    throw new TypeError(`Invalid address for HTTP CONNECT proxy: scheme must be http'; got '${target}'`);
+  if (port === undefined)
+    throw new TypeError(`Invalid address for HTTP CONNECT proxy: port is required; got '${target}'`);
+  return { scheme, hostname: host, port };
+}

packages/core-bridge/src/conversions.rs

@@ -6,6 +6,7 @@ use neon::{
     types::{JsBoolean, JsNumber, JsString},
 };
 use std::{collections::HashMap, net::SocketAddr, sync::Arc, time::Duration};
+use temporal_client::HttpConnectProxyOptions;
 use temporal_sdk_core::{
     api::telemetry::{Logger, MetricTemporality, TelemetryOptions, TelemetryOptionsBuilder},
     api::{
@@ -121,6 +122,26 @@ impl ObjectHandleConversionsExt for Handle<'_, JsObject> {
             }
         };
 
+        let proxy_cfg = match js_optional_getter!(cx, self, "proxy", JsObject) {
+            None => None,
+            Some(proxy) => {
+                let target_addr = js_value_getter!(cx, &proxy, "targetHost", JsString);
+
+                let basic_auth = match js_optional_getter!(cx, &proxy, "basicAuth", JsObject) {
+                    None => None,
+                    Some(proxy_obj) => Some((
+                        js_value_getter!(cx, &proxy_obj, "username", JsString),
+                        js_value_getter!(cx, &proxy_obj, "password", JsString),
+                    )),
+                };
+
+                Some(HttpConnectProxyOptions {
+                    target_addr,
+                    basic_auth,
+                })
+            }
+        };
+
         let retry_config = match js_optional_getter!(cx, self, "retry", JsObject) {
             None => RetryConfig::default(),
             Some(ref retry_config) => RetryConfig {
@@ -158,6 +179,7 @@ impl ObjectHandleConversionsExt for Handle<'_, JsObject> {
         if let Some(tls_cfg) = tls_cfg {
             client_options.tls_cfg(tls_cfg);
         }
+        client_options.http_connect_proxy(proxy_cfg);
         let headers = match js_optional_getter!(cx, self, "metadata", JsObject) {
             None => None,
             Some(h) => Some(h.as_hash_map_of_string_to_string(cx).map_err(|reason| {

packages/core-bridge/ts/index.ts

@@ -1,7 +1,7 @@
 import { LogLevel, Duration } from '@temporalio/common';
-import type { TLSConfig } from '@temporalio/common/lib/internal-non-workflow';
+import type { TLSConfig, ProxyConfig, HttpConnectProxyConfig } from '@temporalio/common/lib/internal-non-workflow';
 
-export { TLSConfig };
+export type { TLSConfig, ProxyConfig, HttpConnectProxyConfig };
 
 /** @deprecated Import from @temporalio/common instead */
 export { LogLevel };
@@ -55,6 +55,13 @@ export interface ClientOptions {
    */
   tls?: TLSConfig;
 
+  /**
+   * Proxying configuration.
+   *
+   * @experimental
+   */
+  proxy?: ProxyConfig;
+
   /**
    * Optional retry options for server requests.
    */