@hatchet-dev/typescript-sdk 1.33.2 → 1.34.0-alpha.1

package/clients/admin/admin-client.d.ts

@@ -5,6 +5,7 @@ import { Logger } from '../../util/logger';
 import WorkflowRunRef from '../../util/workflow-run-ref';
 import { AdminServiceClient, CreateWorkflowVersionRequest } from '../../protoc/v1/workflows';
 import { Priority, RunsClient, WorkerLabelComparator } from '../../v1';
+import { type Transport } from '../transport';
 import { Api } from '../rest';
 import { WebhookWorkerCreateRequest, WorkflowRunStatus, WorkflowRunStatusList } from '../rest/generated/data-contracts';
 import { RunListenerClient } from '../listeners/run-listener/child-listener-client';
@@ -50,7 +51,11 @@ export declare class AdminClient {
     logger: Logger;
     listenerClient: RunListenerClient;
     workflows: RunsClient | undefined;
-    constructor(config: ClientConfig, channel: Channel, factory: ClientFactory, api: Api, tenantId: string, listenerClient: RunListenerClient, workflows: RunsClient | undefined);
+    /**
+     * The positional `channel` and `factory` parameters are part of the public constructor
+     * signature; the unary calls go over `transport` and the streaming clients own the channel.
+     */
+    constructor(config: ClientConfig, _channel: Channel, _factory: ClientFactory, api: Api, tenantId: string, listenerClient: RunListenerClient, workflows: RunsClient | undefined, transport?: Transport);
     /**
      * @deprecated use putWorkflow instead
      */

package/clients/admin/admin-client.js

@@ -29,8 +29,9 @@ const hatchet_error_1 = require("../../util/errors/hatchet-error");
 const v0_deprecation_warning_1 = require("../../util/v0-deprecation-warning");
 const retrier_1 = require("../../util/retrier");
 const workflow_run_ref_1 = __importDefault(require("../../util/workflow-run-ref"));
-const workflows_2 = require("../../protoc/v1/workflows");
 const apply_namespace_1 = require("../../util/apply-namespace");
+const transport_1 = require("../transport");
+const rpc_1 = require("./rpc");
 function convertDesiredWorkerLabels(labels) {
     return Object.fromEntries(Object.entries(labels).map(([key, label]) => [
         key,
@@ -44,10 +45,14 @@ function convertDesiredWorkerLabels(labels) {
     ]));
 }
 class AdminClient {
-    constructor(config, channel, factory, api, tenantId, listenerClient, workflows) {
+    /**
+     * The positional `channel` and `factory` parameters are part of the public constructor
+     * signature; the unary calls go over `transport` and the streaming clients own the channel.
+     */
+    constructor(config, _channel, _factory, api, tenantId, listenerClient, workflows, transport = (0, transport_1.createNodeTransport)(config)) {
         this.config = config;
-        this.client = factory.create(workflows_1.WorkflowServiceDefinition, channel);
-        this.v1Client = factory.create(workflows_2.AdminServiceDefinition, channel);
+        this.client = (0, rpc_1.createWorkflowsRpc)(transport);
+        this.v1Client = (0, rpc_1.createV1AdminRpc)(transport);
         this.api = api;
         this.tenantId = tenantId;
         this.logger = config.logger(`Admin`, config.log_level);

package/clients/admin/rpc.d.ts

@@ -0,0 +1,13 @@
+import { WorkflowServiceClient } from '../../protoc/workflows/workflows';
+import { AdminServiceClient } from '../../protoc/v1/workflows';
+import { type Transport } from '../transport';
+/**
+ * The `WorkflowService` client, every RPC of the generated `WorkflowServiceClient` interface,
+ * served by a Connect client on the given transport.
+ */
+export declare function createWorkflowsRpc(transport: Transport): WorkflowServiceClient;
+/**
+ * The v1 `AdminService` client, every RPC of the generated `AdminServiceClient` interface,
+ * served by a Connect client on the given transport.
+ */
+export declare function createV1AdminRpc(transport: Transport): AdminServiceClient;

package/clients/admin/rpc.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWorkflowsRpc = createWorkflowsRpc;
+exports.createV1AdminRpc = createV1AdminRpc;
+const workflows_1 = require("../../protoc/workflows/workflows");
+const workflows_pb_1 = require("../../protoc-es/workflows/workflows_pb");
+const workflows_2 = require("../../protoc/v1/workflows");
+const workflows_pb_2 = require("../../protoc-es/v1/workflows_pb");
+const transport_1 = require("../transport");
+/**
+ * The `WorkflowService` client, every RPC of the generated `WorkflowServiceClient` interface,
+ * served by a Connect client on the given transport.
+ */
+function createWorkflowsRpc(transport) {
+    return (0, transport_1.createTsProtoClient)(workflows_1.WorkflowServiceDefinition, workflows_pb_1.WorkflowService, transport);
+}
+/**
+ * The v1 `AdminService` client, every RPC of the generated `AdminServiceClient` interface,
+ * served by a Connect client on the given transport.
+ */
+function createV1AdminRpc(transport) {
+    return (0, transport_1.createTsProtoClient)(workflows_2.AdminServiceDefinition, workflows_pb_2.AdminService, transport);
+}

package/clients/event/event-client.d.ts

@@ -1,5 +1,6 @@
 import { Channel, ClientFactory } from 'nice-grpc';
 import { EventsServiceClient } from '../../protoc/events/events';
+import { type Transport } from '../transport';
 import { ClientConfig } from '../hatchet-client/client-config';
 import { Logger } from '../../util/logger';
 import { retrier } from '../../util/retrier';
@@ -28,7 +29,7 @@ export declare class EventClient {
     api: HatchetClient['api'];
     tenantId: string;
     logger: Logger;
-    constructor(config: ClientConfig, channel: Channel, factory: ClientFactory, api: HatchetClient['api']);
+    constructor(config: ClientConfig, _channel: Channel, _factory: ClientFactory, api: HatchetClient['api'], transport?: Transport);
     /**
      * @important This method is instrumented by HatchetInstrumentor._patchPushEvent.
      * Keep the signature in sync with the instrumentor wrapper.

package/clients/event/event-client.js

@@ -10,7 +10,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EventClient = exports.LogLevel = void 0;
-const events_1 = require("../../protoc/events/events");
+const transport_1 = require("../transport");
+const rpc_1 = require("./rpc");
 const hatchet_error_1 = require("../../util/errors/hatchet-error");
 const retrier_1 = require("../../util/retrier");
 const apply_namespace_1 = require("../../util/apply-namespace");
@@ -30,9 +31,11 @@ function injectSourceInfo(metadata) {
     return Object.assign(Object.assign({}, metadata), { hatchet__source_workflow_run_id: ctx.parentId, hatchet__source_step_run_id: ctx.parentTaskRunExternalId });
 }
 class EventClient {
-    constructor(config, channel, factory, api) {
+    // The positional channel and factory parameters are part of the public constructor signature;
+    // unary event calls go over the transport and do not use them.
+    constructor(config, _channel, _factory, api, transport = (0, transport_1.createNodeTransport)(config)) {
         this.config = config;
-        this.client = factory.create(events_1.EventsServiceDefinition, channel);
+        this.client = (0, rpc_1.createEventsRpc)(transport);
         this.logger = config.logger(`Dispatcher`, config.log_level);
         this.retrier = retrier_1.retrier;
         this.api = api;

package/clients/event/rpc.d.ts

@@ -0,0 +1,7 @@
+import { EventsServiceClient } from '../../protoc/events/events';
+import { type Transport } from '../transport';
+/**
+ * The `EventsService` client, every RPC of the generated `EventsServiceClient` interface,
+ * served by a Connect client on the given transport.
+ */
+export declare function createEventsRpc(transport: Transport): EventsServiceClient;

package/clients/event/rpc.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEventsRpc = createEventsRpc;
+const events_1 = require("../../protoc/events/events");
+const events_pb_1 = require("../../protoc-es/events/events_pb");
+const transport_1 = require("../transport");
+/**
+ * The `EventsService` client, every RPC of the generated `EventsServiceClient` interface,
+ * served by a Connect client on the given transport.
+ */
+function createEventsRpc(transport) {
+    return (0, transport_1.createTsProtoClient)(events_1.EventsServiceDefinition, events_pb_1.EventsService, transport);
+}

package/clients/hatchet-client/hatchet-logger.js

@@ -20,7 +20,8 @@ class HatchetLogger {
     }
     log(level, message, color = '37') {
         var _a;
-        if (logger_1.LogLevelEnum[level] >= logger_1.LogLevelEnum[this.logLevel]) {
+        // OFF disables all logger output, regardless of message level.
+        if (this.logLevel !== 'OFF' && logger_1.LogLevelEnum[level] >= logger_1.LogLevelEnum[this.logLevel]) {
             const time = new Date().toLocaleString('en-US', {
                 month: '2-digit',
                 day: '2-digit',

package/clients/rest/generated/data-contracts.d.ts

@@ -900,6 +900,8 @@ export interface Tenant {
     serverUrl?: string;
     /** Control-plane shard region for the tenant (e.g. aws:us-west-2). */
     region?: string;
+    /** The data retention period for the tenant, e.g. 720h. */
+    dataRetentionPeriod?: string;
 }
 export interface V1EventWorkflowRunSummary {
     /**

package/clients/transport/grpc-target.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Where a gRPC target points: the host and port to dial and the `:authority` grpc-js sends for
+ * it, which is the target's path as written (the first address for the IP schemes).
+ */
+export interface GrpcTarget {
+    host: string;
+    port: number;
+    authority: string;
+}
+/**
+ * Parses the target forms grpc-js accepts for `host_port`, so the unary transport dials the
+ * same endpoint the streaming channel does: `host:port`, `dns:host:port`, `dns:///host:port`,
+ * `ipv4:address:port` and `ipv6:[address]:port` (the first address of an address list). A
+ * missing port is grpc-js's default, 443. `unix:` sockets and a `dns://nameserver/` authority
+ * have no HTTP/2 equivalent here and are refused with a clear error.
+ */
+export declare function parseGrpcTarget(target: string): GrpcTarget;
+/** The base URL Connect dials for a target: an IPv6 host is bracketed as a URL requires. */
+export declare function grpcTargetBaseUrl(target: GrpcTarget, protocol: 'http' | 'https'): string;

package/clients/transport/grpc-target.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseGrpcTarget = parseGrpcTarget;
+exports.grpcTargetBaseUrl = grpcTargetBaseUrl;
+const net_1 = require("net");
+/** The port grpc-js dials when a target names none. */
+const DEFAULT_PORT = 443;
+/*
+ * grpc-js parses a target as `scheme:` `//authority/` `path`, all but the path optional; a
+ * scheme it has no resolver for (which is what `host:port` looks like) makes the whole string a
+ * `dns` path.
+ */
+const URI_REGEX = /^(?:([A-Za-z0-9+.-]+):)?(?:\/\/([^/]*)\/)?(.+)$/;
+const RESOLVER_SCHEMES = new Set(['dns', 'ipv4', 'ipv6', 'unix']);
+/**
+ * Parses the target forms grpc-js accepts for `host_port`, so the unary transport dials the
+ * same endpoint the streaming channel does: `host:port`, `dns:host:port`, `dns:///host:port`,
+ * `ipv4:address:port` and `ipv6:[address]:port` (the first address of an address list). A
+ * missing port is grpc-js's default, 443. `unix:` sockets and a `dns://nameserver/` authority
+ * have no HTTP/2 equivalent here and are refused with a clear error.
+ */
+function parseGrpcTarget(target) {
+    var _a;
+    const match = URI_REGEX.exec(target);
+    if (!match) {
+        throw new Error(`host_port ${JSON.stringify(target)} is not a gRPC target`);
+    }
+    const [, rawScheme, authority, rawPath] = match;
+    const known = rawScheme !== undefined && RESOLVER_SCHEMES.has(rawScheme);
+    const scheme = known ? rawScheme : 'dns';
+    const path = known ? rawPath : target;
+    if (scheme === 'unix') {
+        throw new Error(`host_port ${JSON.stringify(target)}: unix domain socket targets are not supported by the unary transport; use a host:port target`);
+    }
+    if (known && authority) {
+        throw new Error(`host_port ${JSON.stringify(target)}: a target-specific DNS server is not supported by the unary transport; use dns:///host:port`);
+    }
+    const address = scheme === 'dns' ? path : path.split(',')[0];
+    const hostPort = splitHostPort(address);
+    if (!hostPort) {
+        throw new Error(`host_port ${JSON.stringify(target)} is not a valid host and port`);
+    }
+    if (scheme === 'ipv4' && !(0, net_1.isIPv4)(hostPort.host)) {
+        throw new Error(`host_port ${JSON.stringify(target)} is not an IPv4 address`);
+    }
+    if (scheme === 'ipv6' && !(0, net_1.isIPv6)(hostPort.host)) {
+        throw new Error(`host_port ${JSON.stringify(target)} is not an IPv6 address`);
+    }
+    return { host: hostPort.host, port: (_a = hostPort.port) !== null && _a !== void 0 ? _a : DEFAULT_PORT, authority: address };
+}
+/** The base URL Connect dials for a target: an IPv6 host is bracketed as a URL requires. */
+function grpcTargetBaseUrl(target, protocol) {
+    const host = target.host.includes(':') ? `[${target.host}]` : target.host;
+    return `${protocol}://${host}:${target.port}`;
+}
+/*
+ * grpc-js's host:port split: a bracketed host is IPv6 with an optional `:port`, exactly one
+ * colon separates a host from a numeric port, and any other number of colons is a bare IPv6
+ * address with no port.
+ */
+function splitHostPort(address) {
+    if (address.startsWith('[')) {
+        const end = address.indexOf(']');
+        if (end === -1) {
+            return null;
+        }
+        const host = address.slice(1, end);
+        if (!host.includes(':')) {
+            return null;
+        }
+        const rest = address.slice(end + 1);
+        if (rest === '') {
+            return { host };
+        }
+        if (rest.startsWith(':') && /^\d+$/.test(rest.slice(1))) {
+            return { host, port: Number(rest.slice(1)) };
+        }
+        return null;
+    }
+    const parts = address.split(':');
+    if (parts.length === 2) {
+        return /^\d+$/.test(parts[1]) ? { host: parts[0], port: Number(parts[1]) } : null;
+    }
+    return { host: address };
+}

package/clients/transport/index.d.ts

@@ -0,0 +1,4 @@
+export { createAuthInterceptor, type Transport } from './transport';
+export { createNodeTransport } from './node-transport';
+export { fromProtobufEs, toProtobufEs, type DeepPartial, type TsProtoCodec, } from './message-bridge';
+export { createTsProtoClient, headersToMetadata, metadataToHeaders, toConnectCallOptions, type UnaryCallOptions, type UnaryCallOptionsExt, } from './ts-proto-client';

package/clients/transport/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toConnectCallOptions = exports.metadataToHeaders = exports.headersToMetadata = exports.createTsProtoClient = exports.toProtobufEs = exports.fromProtobufEs = exports.createNodeTransport = exports.createAuthInterceptor = void 0;
+var transport_1 = require("./transport");
+Object.defineProperty(exports, "createAuthInterceptor", { enumerable: true, get: function () { return transport_1.createAuthInterceptor; } });
+var node_transport_1 = require("./node-transport");
+Object.defineProperty(exports, "createNodeTransport", { enumerable: true, get: function () { return node_transport_1.createNodeTransport; } });
+var message_bridge_1 = require("./message-bridge");
+Object.defineProperty(exports, "fromProtobufEs", { enumerable: true, get: function () { return message_bridge_1.fromProtobufEs; } });
+Object.defineProperty(exports, "toProtobufEs", { enumerable: true, get: function () { return message_bridge_1.toProtobufEs; } });
+var ts_proto_client_1 = require("./ts-proto-client");
+Object.defineProperty(exports, "createTsProtoClient", { enumerable: true, get: function () { return ts_proto_client_1.createTsProtoClient; } });
+Object.defineProperty(exports, "headersToMetadata", { enumerable: true, get: function () { return ts_proto_client_1.headersToMetadata; } });
+Object.defineProperty(exports, "metadataToHeaders", { enumerable: true, get: function () { return ts_proto_client_1.metadataToHeaders; } });
+Object.defineProperty(exports, "toConnectCallOptions", { enumerable: true, get: function () { return ts_proto_client_1.toConnectCallOptions; } });

package/clients/transport/message-bridge.d.ts

@@ -0,0 +1,32 @@
+import { type DescMessage, type MessageShape } from '@bufbuild/protobuf';
+type Builtin = Date | ((...args: never[]) => unknown) | Uint8Array | string | number | boolean | undefined;
+/**
+ * The partial message shape the SDK's clients accept, matching the `DeepPartial` type each
+ * `src/protoc` module generates for its own messages.
+ */
+export type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+/**
+ * The part of a `ts-proto` message codec (what `src/protoc` exports under a message's name)
+ * the bridge needs: the wire codec and the partial-to-full normalizer.
+ */
+export interface TsProtoCodec<T> {
+    encode(message: T): {
+        finish(): Uint8Array;
+    };
+    decode(input: Uint8Array): T;
+    fromPartial(object: DeepPartial<T>): T;
+}
+/**
+ * Converts a `ts-proto` message to the protobuf-es message a Connect client sends. The two
+ * bindings share the wire format, so an encode/decode round trip is an exact translation and
+ * the SDK keeps its `ts-proto` types as the public request types.
+ */
+export declare function toProtobufEs<T, S extends DescMessage>(schema: S, codec: TsProtoCodec<T>, message: DeepPartial<T>): MessageShape<S>;
+/**
+ * Converts a protobuf-es message a Connect client received to the `ts-proto` message callers
+ * expect, the inverse of `toProtobufEs`.
+ */
+export declare function fromProtobufEs<T, S extends DescMessage>(codec: TsProtoCodec<T>, schema: S, message: MessageShape<S>): T;
+export {};

package/clients/transport/message-bridge.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toProtobufEs = toProtobufEs;
+exports.fromProtobufEs = fromProtobufEs;
+const protobuf_1 = require("@bufbuild/protobuf");
+/**
+ * Converts a `ts-proto` message to the protobuf-es message a Connect client sends. The two
+ * bindings share the wire format, so an encode/decode round trip is an exact translation and
+ * the SDK keeps its `ts-proto` types as the public request types.
+ */
+function toProtobufEs(schema, codec, message) {
+    return (0, protobuf_1.fromBinary)(schema, codec.encode(codec.fromPartial(message)).finish());
+}
+/**
+ * Converts a protobuf-es message a Connect client received to the `ts-proto` message callers
+ * expect, the inverse of `toProtobufEs`.
+ */
+function fromProtobufEs(codec, schema, message) {
+    return codec.decode((0, protobuf_1.toBinary)(schema, message));
+}

package/clients/transport/node-transport.d.ts

@@ -0,0 +1,50 @@
+import type { SecureClientSessionOptions } from 'http2';
+import { type GrpcTransportOptions } from '@connectrpc/connect-node';
+import type { ClientConfig } from '../hatchet-client/client-config';
+import { type Transport } from './transport';
+/**
+ * The largest message size Connect can enforce (a 32-bit length prefix). The config schema
+ * accepts any positive integer, as grpc-js does, so a larger configured limit is clamped to it
+ * rather than refused at the first call.
+ */
+export declare const MAX_MESSAGE_BYTES = 4294967295;
+/**
+ * The connection settings the `nice-grpc` channel uses (`grpc.keepalive_time_ms`,
+ * `grpc.keepalive_timeout_ms`, `grpc.keepalive_permit_without_calls` and
+ * `grpc.client_idle_timeout_ms` in `util/grpc-helpers.ts`), so a unary connection is kept alive,
+ * given up on and idled exactly as a streaming one.
+ */
+export declare const SESSION_OPTIONS: {
+    readonly pingIntervalMs: number;
+    readonly pingTimeoutMs: number;
+    readonly pingIdleConnection: true;
+    readonly idleConnectionTimeoutMs: number;
+};
+/**
+ * Builds the TLS session options for the engine connection from the client's `tls_config`:
+ * `none` means plaintext, `tls` verifies the server against the trusted roots, and `mtls` (the
+ * default when no strategy is set) additionally presents `cert_file` and `key_file`.
+ * `server_name` overrides the hostname used for SNI and certificate verification, which is what
+ * lets a client reach an engine through an address its certificate does not name.
+ *
+ * The roots and cipher suites follow grpc-js, which the streaming channel uses: `ca_file`, else
+ * the bundle `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH` names, else the platform roots; and
+ * `GRPC_SSL_CIPHER_SUITES` when set.
+ */
+export declare function tlsSessionOptions(tls: ClientConfig['tls_config']): SecureClientSessionOptions;
+/**
+ * Creates the Node transport: the gRPC protocol over HTTP/2 (`createGrpcTransport` speaks
+ * nothing else), the same wire the SDK's `nice-grpc` clients speak, so an engine sees no
+ * difference between the two. The bearer token from the config is attached to every call and
+ * the connection is kept alive with pings the way the `nice-grpc` channel is.
+ *
+ * The transport is built on the first call so that constructing a client reads no TLS files;
+ * a client whose unary RPCs are never used never touches them.
+ */
+export declare function createNodeTransport(config: ClientConfig): Transport;
+/**
+ * The options `createNodeTransport` builds its transport from, derived from the client config.
+ * The session manager is built here from `nodeOptions` and the session settings; Connect takes
+ * the connection from it and leaves those transport-level copies as the record of what it uses.
+ */
+export declare function nodeTransportOptions(config: ClientConfig): GrpcTransportOptions;

package/clients/transport/node-transport.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_OPTIONS = exports.MAX_MESSAGE_BYTES = void 0;
+exports.tlsSessionOptions = tlsSessionOptions;
+exports.createNodeTransport = createNodeTransport;
+exports.nodeTransportOptions = nodeTransportOptions;
+const fs_1 = require("fs");
+const connect_node_1 = require("@connectrpc/connect-node");
+const grpc_target_1 = require("./grpc-target");
+const transport_1 = require("./transport");
+const DEFAULT_MAX_MESSAGE_BYTES = 4 * 1024 * 1024;
+/**
+ * The largest message size Connect can enforce (a 32-bit length prefix). The config schema
+ * accepts any positive integer, as grpc-js does, so a larger configured limit is clamped to it
+ * rather than refused at the first call.
+ */
+exports.MAX_MESSAGE_BYTES = 0xffffffff;
+function messageLimit(configured) {
+    return Math.min(configured !== null && configured !== void 0 ? configured : DEFAULT_MAX_MESSAGE_BYTES, exports.MAX_MESSAGE_BYTES);
+}
+/**
+ * The connection settings the `nice-grpc` channel uses (`grpc.keepalive_time_ms`,
+ * `grpc.keepalive_timeout_ms`, `grpc.keepalive_permit_without_calls` and
+ * `grpc.client_idle_timeout_ms` in `util/grpc-helpers.ts`), so a unary connection is kept alive,
+ * given up on and idled exactly as a streaming one.
+ */
+exports.SESSION_OPTIONS = {
+    pingIntervalMs: 10 * 1000,
+    pingTimeoutMs: 60 * 1000,
+    pingIdleConnection: true,
+    idleConnectionTimeoutMs: 60 * 1000,
+};
+/**
+ * Builds the TLS session options for the engine connection from the client's `tls_config`:
+ * `none` means plaintext, `tls` verifies the server against the trusted roots, and `mtls` (the
+ * default when no strategy is set) additionally presents `cert_file` and `key_file`.
+ * `server_name` overrides the hostname used for SNI and certificate verification, which is what
+ * lets a client reach an engine through an address its certificate does not name.
+ *
+ * The roots and cipher suites follow grpc-js, which the streaming channel uses: `ca_file`, else
+ * the bundle `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH` names, else the platform roots; and
+ * `GRPC_SSL_CIPHER_SUITES` when set.
+ */
+function tlsSessionOptions(tls) {
+    // grpc-js verifies the peer regardless of NODE_TLS_REJECT_UNAUTHORIZED, which is Node's
+    // process-wide switch; set explicitly, the switch cannot weaken this connection either.
+    const options = { rejectUnauthorized: true };
+    const rootsFile = tls.ca_file || process.env.GRPC_DEFAULT_SSL_ROOTS_FILE_PATH;
+    if (rootsFile) {
+        options.ca = (0, fs_1.readFileSync)(rootsFile);
+    }
+    const ciphers = process.env.GRPC_SSL_CIPHER_SUITES;
+    if (ciphers) {
+        options.ciphers = ciphers;
+    }
+    if (tls.tls_strategy !== 'tls') {
+        // grpc-js refuses half a client identity with these messages rather than connecting without
+        // one, which an endpoint that does not require client certificates would silently accept.
+        if (tls.key_file && !tls.cert_file) {
+            throw new Error('Private key must be given with accompanying certificate chain');
+        }
+        if (tls.cert_file && !tls.key_file) {
+            throw new Error('Certificate chain must be given with accompanying private key');
+        }
+        if (tls.key_file && tls.cert_file) {
+            options.key = (0, fs_1.readFileSync)(tls.key_file);
+            options.cert = (0, fs_1.readFileSync)(tls.cert_file);
+        }
+    }
+    if (tls.server_name) {
+        options.servername = tls.server_name;
+    }
+    return options;
+}
+/**
+ * Creates the Node transport: the gRPC protocol over HTTP/2 (`createGrpcTransport` speaks
+ * nothing else), the same wire the SDK's `nice-grpc` clients speak, so an engine sees no
+ * difference between the two. The bearer token from the config is attached to every call and
+ * the connection is kept alive with pings the way the `nice-grpc` channel is.
+ *
+ * The transport is built on the first call so that constructing a client reads no TLS files;
+ * a client whose unary RPCs are never used never touches them.
+ */
+function createNodeTransport(config) {
+    let transport;
+    const get = () => {
+        if (!transport) {
+            transport = (0, connect_node_1.createGrpcTransport)(nodeTransportOptions(config));
+        }
+        return transport;
+    };
+    return {
+        unary: (...args) => get().unary(...args),
+        stream: (...args) => get().stream(...args),
+    };
+}
+/**
+ * The options `createNodeTransport` builds its transport from, derived from the client config.
+ * The session manager is built here from `nodeOptions` and the session settings; Connect takes
+ * the connection from it and leaves those transport-level copies as the record of what it uses.
+ */
+function nodeTransportOptions(config) {
+    const insecure = config.tls_config.tls_strategy === 'none';
+    const target = (0, grpc_target_1.parseGrpcTarget)(config.host_port);
+    const baseUrl = (0, grpc_target_1.grpcTargetBaseUrl)(target, insecure ? 'http' : 'https');
+    const nodeOptions = insecure ? undefined : tlsSessionOptions(config.tls_config);
+    return Object.assign({ baseUrl,
+        nodeOptions, sessionManager: createSessionManager(baseUrl, target.authority, nodeOptions), interceptors: [(0, transport_1.createAuthInterceptor)(config.token)], sendCompression: connect_node_1.compressionGzip, readMaxBytes: messageLimit(config.grpc_max_recv_message_length), writeMaxBytes: messageLimit(config.grpc_max_send_message_length) }, exports.SESSION_OPTIONS);
+}
+/**
+ * The HTTP/2 session for the transport, sending `:authority` as grpc-js does: the target as
+ * written, so `server_name` changes only SNI and certificate verification. Node otherwise
+ * derives the authority from `servername` when it is set, which would also change the virtual
+ * host a proxy in front of the engine routes on.
+ */
+function createSessionManager(baseUrl, authority, nodeOptions) {
+    const manager = new connect_node_1.Http2SessionManager(baseUrl, exports.SESSION_OPTIONS, nodeOptions);
+    return {
+        authority: manager.authority,
+        request: (method, path, headers, options) => manager.request(method, path, Object.assign({ ':authority': authority }, headers), options),
+        notifyResponseByteRead: (stream) => manager.notifyResponseByteRead(stream),
+    };
+}

package/clients/transport/transport.d.ts

@@ -0,0 +1,14 @@
+import type { Interceptor, Transport } from '@connectrpc/connect';
+/**
+ * The seam every Connect-backed client calls through. A transport carries the protocol
+ * (gRPC over HTTP/2 in Node, Connect over fetch elsewhere), the connection settings and the
+ * interceptors that apply to every call.
+ */
+export type { Transport };
+/**
+ * Sets the bearer token the engine authenticates every call with. The transport applies it to
+ * each request, so callers never pass credentials per call. A token that cannot be carried in a
+ * header is refused here with a fixed message, so the token's value never reaches a log or an
+ * error.
+ */
+export declare function createAuthInterceptor(token: string): Interceptor;

package/clients/transport/transport.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAuthInterceptor = createAuthInterceptor;
+/**
+ * The characters a token may contain and still travel in an HTTP header: the printable ASCII
+ * range, which is also what grpc-js accepts in metadata. Anything else would make the header
+ * layer reject the request with an error quoting the token.
+ */
+const HEADER_SAFE = /^[ -~]*$/;
+/**
+ * Sets the bearer token the engine authenticates every call with. The transport applies it to
+ * each request, so callers never pass credentials per call. A token that cannot be carried in a
+ * header is refused here with a fixed message, so the token's value never reaches a log or an
+ * error.
+ */
+function createAuthInterceptor(token) {
+    if (!HEADER_SAFE.test(token)) {
+        throw new Error('The Hatchet client token contains characters that cannot be sent in an HTTP header; check HATCHET_CLIENT_TOKEN for stray whitespace or line breaks');
+    }
+    return (next) => (req) => {
+        req.header.set('authorization', `Bearer ${token}`);
+        return next(req);
+    };
+}

package/clients/transport/ts-proto-client.d.ts

@@ -0,0 +1,41 @@
+import type { DescService } from '@bufbuild/protobuf';
+import { type CallOptions as ConnectCallOptions, type Transport } from '@connectrpc/connect';
+import type { Client, TsProtoServiceDefinition } from 'nice-grpc';
+import { Metadata, type CallOptions } from 'nice-grpc-common';
+/**
+ * The per-call options the Connect-backed clients accept: `nice-grpc`'s `CallOptions`
+ * (`signal`, `metadata`, `onHeader`, `onTrailer`) plus the `deadline` its deadline middleware
+ * adds, an absolute time as a `Date` or epoch milliseconds.
+ */
+export interface UnaryCallOptionsExt {
+    deadline?: Date | number;
+}
+export type UnaryCallOptions = CallOptions & UnaryCallOptionsExt;
+/**
+ * Builds the client a `ts-proto` service definition describes, with every method served by a
+ * Connect client for the matching protobuf-es service on `transport`. The result has the exact
+ * surface `nice-grpc`'s `ClientFactory.create(definition, channel)` produced: every RPC of the
+ * service as `(request, options?) => Promise<response>` with the SDK's `ts-proto` message types,
+ * so a caller holding one of the public client properties sees no difference.
+ *
+ * Both bindings are generated from the same proto, so a method's client name is the same in
+ * each and the protobuf-es descriptor can be looked up by it.
+ */
+export declare function createTsProtoClient<Def extends TsProtoServiceDefinition>(definition: Def, service: DescService, transport: Transport): Client<Def, UnaryCallOptionsExt>;
+/**
+ * Translates `nice-grpc` call options to Connect's: the signal passes through, an absolute
+ * deadline becomes the remaining time, request metadata becomes headers and the header and
+ * trailer callbacks receive `Metadata` built from the response headers.
+ */
+export declare function toConnectCallOptions(options?: UnaryCallOptions): ConnectCallOptions | undefined;
+/**
+ * gRPC metadata as HTTP headers: binary values (keys ending in `-bin`) are base64 encoded,
+ * which is how they travel on the wire in every gRPC implementation.
+ */
+export declare function metadataToHeaders(metadata: Metadata): Headers;
+/**
+ * Response headers as gRPC metadata, the inverse of `metadataToHeaders`. `Headers` joins
+ * repeated values with a comma, so a binary header is split back into its values before each
+ * is decoded.
+ */
+export declare function headersToMetadata(headers: Headers): Metadata;