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

package/README.md

@@ -49,6 +49,7 @@ TypeScript SDK reference (overview: https://docs.hatchet.run/reference/typescrip
 - Rate Limits: https://docs.hatchet.run/reference/typescript/feature-clients/ratelimits.md (guide: https://docs.hatchet.run/v1/rate-limits.md)
 - Runs: https://docs.hatchet.run/reference/typescript/feature-clients/runs.md (guide: https://docs.hatchet.run/v1/running-your-task.md)
 - Scheduled Runs: https://docs.hatchet.run/reference/typescript/feature-clients/schedules.md (guide: https://docs.hatchet.run/v1/scheduled-runs.md)
+- Streams: https://docs.hatchet.run/reference/typescript/feature-clients/streams.md
 - Tenant: https://docs.hatchet.run/reference/typescript/feature-clients/tenant.md
 - Webhooks: https://docs.hatchet.run/reference/typescript/feature-clients/webhooks.md (guide: https://docs.hatchet.run/v1/webhooks.md)
 - Workers: https://docs.hatchet.run/reference/typescript/feature-clients/workers.md (guide: https://docs.hatchet.run/v1/workers.md)

package/clients/admin/rpc.d.ts

@@ -1,6 +1,6 @@
 import { WorkflowServiceClient } from '../../protoc/workflows/workflows';
 import { AdminServiceClient } from '../../protoc/v1/workflows';
-import { type Transport } from '../transport';
+import type { Transport } from '../transport/transport';
 /**
  * The `WorkflowService` client, every RPC of the generated `WorkflowServiceClient` interface,
  * served by a Connect client on the given transport.

package/clients/admin/rpc.js

@@ -6,18 +6,18 @@ 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");
+const ts_proto_client_1 = require("../transport/ts-proto-client");
 /**
  * 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);
+    return (0, ts_proto_client_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);
+    return (0, ts_proto_client_1.createTsProtoClient)(workflows_2.AdminServiceDefinition, workflows_pb_2.AdminService, transport);
 }

package/clients/admin/trigger-request.d.ts

@@ -0,0 +1,18 @@
+import { ConnectError } from '@connectrpc/connect';
+import { BulkTriggerIdempotencyCollisionError } from '../../util/errors/bulk-trigger-idempotency-collision-error';
+import type { TriggerWorkflowRequest } from '../../protoc/v1/shared/trigger';
+import type { DeepPartial } from '../transport/message-bridge';
+import type { TriggerRunOptions } from '../../core/types';
+/**
+ * One builder for both clients, so a run triggered from the core client is indistinguishable
+ * to the engine from one triggered by the Node client.
+ */
+export declare function buildTriggerWorkflowRequest<Q>(workflowName: string, input: Q, options: TriggerRunOptions | undefined, namespace: string | undefined): DeepPartial<TriggerWorkflowRequest>;
+/**
+ * The engine answers a trigger whose idempotency key is already taken with `ALREADY_EXISTS`
+ * and attaches the collision details to the status. The Connect client decodes those details
+ * from the trailer, so the error carries everything needed to build the SDK's collision errors.
+ */
+export declare function isAlreadyExists(e: unknown): e is ConnectError;
+export declare function extractExistingRunId(e: ConnectError): string;
+export declare function extractBulkTriggerCollision(e: ConnectError): BulkTriggerIdempotencyCollisionError | null;

package/clients/admin/trigger-request.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTriggerWorkflowRequest = buildTriggerWorkflowRequest;
+exports.isAlreadyExists = isAlreadyExists;
+exports.extractExistingRunId = extractExistingRunId;
+exports.extractBulkTriggerCollision = extractBulkTriggerCollision;
+const connect_1 = require("@connectrpc/connect");
+const idempotency_collision_error_1 = require("../../util/errors/idempotency-collision-error");
+const bulk_trigger_idempotency_collision_error_1 = require("../../util/errors/bulk-trigger-idempotency-collision-error");
+const workflows_pb_1 = require("../../protoc-es/v1/workflows_pb");
+const apply_namespace_1 = require("../../util/apply-namespace");
+/**
+ * One builder for both clients, so a run triggered from the core client is indistinguishable
+ * to the engine from one triggered by the Node client.
+ */
+function buildTriggerWorkflowRequest(workflowName, input, options, namespace) {
+    var _a;
+    const opts = options !== null && options !== void 0 ? options : {};
+    return {
+        name: (0, apply_namespace_1.applyNamespace)(workflowName, namespace).toLowerCase(),
+        input: JSON.stringify(input),
+        parentId: opts.parentId,
+        parentTaskRunExternalId: (_a = opts.parentTaskRunExternalId) !== null && _a !== void 0 ? _a : opts.parentStepRunId,
+        childIndex: opts.childIndex,
+        childKey: opts.childKey,
+        additionalMetadata: opts.additionalMetadata
+            ? JSON.stringify(opts.additionalMetadata)
+            : undefined,
+        desiredWorkerId: opts.desiredWorkerId,
+        priority: opts.priority,
+        desiredWorkerLabels: opts.desiredWorkerLabels
+            ? convertDesiredWorkerLabels(opts.desiredWorkerLabels)
+            : {},
+    };
+}
+function convertDesiredWorkerLabels(labels) {
+    return Object.fromEntries(Object.entries(labels).map(([key, label]) => [
+        key,
+        {
+            strValue: typeof label.value === 'string' ? label.value : undefined,
+            intValue: typeof label.value === 'number' ? label.value : undefined,
+            required: label.required,
+            weight: label.weight,
+            comparator: label.comparator,
+        },
+    ]));
+}
+/**
+ * The engine answers a trigger whose idempotency key is already taken with `ALREADY_EXISTS`
+ * and attaches the collision details to the status. The Connect client decodes those details
+ * from the trailer, so the error carries everything needed to build the SDK's collision errors.
+ */
+function isAlreadyExists(e) {
+    return e instanceof connect_1.ConnectError && e.code === connect_1.Code.AlreadyExists;
+}
+function extractExistingRunId(e) {
+    var _a;
+    const [detail] = e.findDetails(workflows_pb_1.IdempotencyCollisionErrorSchema);
+    return (_a = detail === null || detail === void 0 ? void 0 : detail.existingRunExternalId) !== null && _a !== void 0 ? _a : '';
+}
+function extractBulkTriggerCollision(e) {
+    const [detail] = e.findDetails(workflows_pb_1.BulkTriggerIdempotencyCollisionErrorSchema);
+    if (!detail)
+        return null;
+    return new bulk_trigger_idempotency_collision_error_1.BulkTriggerIdempotencyCollisionError(detail.successfulWorkflowRunExternalIds, detail.collisions.map((c) => new idempotency_collision_error_1.IdempotencyCollisionError(c.existingRunExternalId)));
+}

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

@@ -5,23 +5,10 @@ import { ClientConfig } from '../hatchet-client/client-config';
 import { Logger } from '../../util/logger';
 import { retrier } from '../../util/retrier';
 import { HatchetClient } from '../../v1';
-export declare enum LogLevel {
-    INFO = "INFO",
-    WARN = "WARN",
-    ERROR = "ERROR",
-    DEBUG = "DEBUG"
-}
-export interface PushEventOptions {
-    additionalMetadata?: Record<string, string>;
-    priority?: number;
-    scope?: string;
-}
-export interface EventWithMetadata<T> {
-    payload: T;
-    additionalMetadata?: Record<string, unknown>;
-    priority?: number;
-    scope?: string;
-}
+import type { EventWithMetadata, PushEventOptions } from '../../core/types';
+import { LogLevel } from './rpc';
+export type { EventWithMetadata, PushEventOptions };
+export { LogLevel };
 export declare class EventClient {
     config: ClientConfig;
     client: EventsServiceClient;

package/clients/event/event-client.js

@@ -11,25 +11,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EventClient = exports.LogLevel = void 0;
 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");
-const parent_run_context_vars_1 = require("../../v1/parent-run-context-vars");
-var LogLevel;
-(function (LogLevel) {
-    LogLevel["INFO"] = "INFO";
-    LogLevel["WARN"] = "WARN";
-    LogLevel["ERROR"] = "ERROR";
-    LogLevel["DEBUG"] = "DEBUG";
-})(LogLevel || (exports.LogLevel = LogLevel = {}));
-function injectSourceInfo(metadata) {
-    const ctx = parent_run_context_vars_1.parentRunContextManager.getContext();
-    if (!(ctx === null || ctx === void 0 ? void 0 : ctx.parentId) || !(ctx === null || ctx === void 0 ? void 0 : ctx.parentTaskRunExternalId)) {
-        return metadata;
-    }
-    return Object.assign(Object.assign({}, metadata), { hatchet__source_workflow_run_id: ctx.parentId, hatchet__source_step_run_id: ctx.parentTaskRunExternalId });
-}
+const rpc_1 = require("./rpc");
+Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return rpc_1.LogLevel; } });
 class EventClient {
     // 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.
@@ -46,17 +32,8 @@ class EventClient {
      * Keep the signature in sync with the instrumentor wrapper.
      */
     push(type, input, options = {}) {
-        var _a;
         const namespacedType = (0, apply_namespace_1.applyNamespace)(type, this.config.namespace);
-        const enhancedMetadata = injectSourceInfo((_a = options.additionalMetadata) !== null && _a !== void 0 ? _a : {});
-        const req = {
-            key: namespacedType,
-            payload: JSON.stringify(input),
-            eventTimestamp: new Date(),
-            additionalMetadata: Object.keys(enhancedMetadata).length > 0 ? JSON.stringify(enhancedMetadata) : undefined,
-            priority: options.priority,
-            scope: options.scope,
-        };
+        const req = (0, rpc_1.buildPushEventRequest)(type, input, options, this.config.namespace);
         return this.retrier(() => __awaiter(this, void 0, void 0, function* () { return this.client.push(req); }), this.logger, this.config.retrier)
             .then((result) => {
             this.logger.info(`Event pushed: ${namespacedType}`);
@@ -72,22 +49,7 @@ class EventClient {
      */
     bulkPush(type, inputs, options = {}) {
         const namespacedType = (0, apply_namespace_1.applyNamespace)(type, this.config.namespace);
-        const events = inputs.map((input) => {
-            var _a, _b, _c, _d;
-            const baseMeta = (_b = (_a = input.additionalMetadata) !== null && _a !== void 0 ? _a : options.additionalMetadata) !== null && _b !== void 0 ? _b : {};
-            const enhanced = injectSourceInfo(baseMeta);
-            return {
-                key: namespacedType,
-                payload: JSON.stringify(input.payload),
-                eventTimestamp: new Date(),
-                additionalMetadata: Object.keys(enhanced).length > 0 ? JSON.stringify(enhanced) : undefined,
-                priority: (_c = input.priority) !== null && _c !== void 0 ? _c : options.priority,
-                scope: (_d = input.scope) !== null && _d !== void 0 ? _d : options.scope,
-            };
-        });
-        const req = {
-            events,
-        };
+        const req = (0, rpc_1.buildBulkPushEventRequest)(type, inputs, options, this.config.namespace);
         return this.retrier(() => __awaiter(this, void 0, void 0, function* () { return this.client.bulkPush(req); }), this.logger, this.config.retrier)
             .then((result) => {
             this.logger.info(`Bulk events pushed for type: ${namespacedType}`);
@@ -110,7 +72,7 @@ class EventClient {
                 taskRunExternalId,
                 createdAt,
                 message: log,
-                level: level || LogLevel.INFO,
+                level: level || rpc_1.LogLevel.INFO,
                 taskRetryCount,
                 metadata: metadata ? JSON.stringify(metadata) : undefined,
             })

package/clients/event/rpc.d.ts

@@ -1,7 +1,26 @@
-import { EventsServiceClient } from '../../protoc/events/events';
-import { type Transport } from '../transport';
+import { BulkPushEventRequest, EventsServiceClient, PushEventRequest } from '../../protoc/events/events';
+import type { Transport } from '../transport/transport';
+import type { EventWithMetadata, PushEventOptions } from '../../core/types';
+/** The levels a task run log line is stored with. */
+export declare enum LogLevel {
+    INFO = "INFO",
+    WARN = "WARN",
+    ERROR = "ERROR",
+    DEBUG = "DEBUG"
+}
 /**
  * The `EventsService` client, every RPC of the generated `EventsServiceClient` interface,
- * served by a Connect client on the given transport.
+ * served by a Connect client on the given transport. The Node and core clients both call
+ * through it.
  */
 export declare function createEventsRpc(transport: Transport): EventsServiceClient;
+/**
+ * One builder for both clients, so an event pushed from the core client is indistinguishable
+ * to the engine from one pushed by the Node client.
+ */
+export declare function buildPushEventRequest<T>(type: string, input: T, options: PushEventOptions, namespace: string | undefined): PushEventRequest;
+/**
+ * Builds the `BulkPush` request for events of one type. Each event's own metadata, priority
+ * and scope win over the shared options.
+ */
+export declare function buildBulkPushEventRequest<T>(type: string, inputs: EventWithMetadata<T>[], options: PushEventOptions, namespace: string | undefined): BulkPushEventRequest;

package/clients/event/rpc.js

@@ -1,13 +1,76 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogLevel = void 0;
 exports.createEventsRpc = createEventsRpc;
+exports.buildPushEventRequest = buildPushEventRequest;
+exports.buildBulkPushEventRequest = buildBulkPushEventRequest;
 const events_1 = require("../../protoc/events/events");
 const events_pb_1 = require("../../protoc-es/events/events_pb");
-const transport_1 = require("../transport");
+const ts_proto_client_1 = require("../transport/ts-proto-client");
+const apply_namespace_1 = require("../../util/apply-namespace");
+const parent_run_context_vars_1 = require("../../v1/parent-run-context-vars");
+/** The levels a task run log line is stored with. */
+var LogLevel;
+(function (LogLevel) {
+    LogLevel["INFO"] = "INFO";
+    LogLevel["WARN"] = "WARN";
+    LogLevel["ERROR"] = "ERROR";
+    LogLevel["DEBUG"] = "DEBUG";
+})(LogLevel || (exports.LogLevel = LogLevel = {}));
 /**
  * The `EventsService` client, every RPC of the generated `EventsServiceClient` interface,
- * served by a Connect client on the given transport.
+ * served by a Connect client on the given transport. The Node and core clients both call
+ * through it.
  */
 function createEventsRpc(transport) {
-    return (0, transport_1.createTsProtoClient)(events_1.EventsServiceDefinition, events_pb_1.EventsService, transport);
+    return (0, ts_proto_client_1.createTsProtoClient)(events_1.EventsServiceDefinition, events_pb_1.EventsService, transport);
+}
+/**
+ * When an event is pushed from inside a task, the run that pushed it is recorded in the
+ * event's metadata so the dashboard can link the two.
+ */
+function injectSourceInfo(metadata) {
+    const ctx = parent_run_context_vars_1.parentRunContextManager.getContext();
+    if (!(ctx === null || ctx === void 0 ? void 0 : ctx.parentId) || !(ctx === null || ctx === void 0 ? void 0 : ctx.parentTaskRunExternalId)) {
+        return metadata;
+    }
+    return Object.assign(Object.assign({}, metadata), { hatchet__source_workflow_run_id: ctx.parentId, hatchet__source_step_run_id: ctx.parentTaskRunExternalId });
+}
+/**
+ * One builder for both clients, so an event pushed from the core client is indistinguishable
+ * to the engine from one pushed by the Node client.
+ */
+function buildPushEventRequest(type, input, options, namespace) {
+    var _a;
+    const enhancedMetadata = injectSourceInfo((_a = options.additionalMetadata) !== null && _a !== void 0 ? _a : {});
+    return {
+        key: (0, apply_namespace_1.applyNamespace)(type, namespace),
+        payload: JSON.stringify(input),
+        eventTimestamp: new Date(),
+        additionalMetadata: Object.keys(enhancedMetadata).length > 0 ? JSON.stringify(enhancedMetadata) : undefined,
+        priority: options.priority,
+        scope: options.scope,
+    };
+}
+/**
+ * Builds the `BulkPush` request for events of one type. Each event's own metadata, priority
+ * and scope win over the shared options.
+ */
+function buildBulkPushEventRequest(type, inputs, options, namespace) {
+    const namespacedType = (0, apply_namespace_1.applyNamespace)(type, namespace);
+    return {
+        events: inputs.map((input) => {
+            var _a, _b, _c, _d;
+            const baseMeta = (_b = (_a = input.additionalMetadata) !== null && _a !== void 0 ? _a : options.additionalMetadata) !== null && _b !== void 0 ? _b : {};
+            const enhanced = injectSourceInfo(baseMeta);
+            return {
+                key: namespacedType,
+                payload: JSON.stringify(input.payload),
+                eventTimestamp: new Date(),
+                additionalMetadata: Object.keys(enhanced).length > 0 ? JSON.stringify(enhanced) : undefined,
+                priority: (_c = input.priority) !== null && _c !== void 0 ? _c : options.priority,
+                scope: (_d = input.scope) !== null && _d !== void 0 ? _d : options.scope,
+            };
+        }),
+    };
 }

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

@@ -0,0 +1,73 @@
+import { type Transport } from './transport';
+/**
+ * How a fetch-based client reaches the engine. `none` speaks plain HTTP; `tls` speaks HTTPS
+ * and verifies the server the way the runtime's `fetch` does. `serverName` is accepted so the
+ * config mirrors the Node client's `tls_config`, but `fetch` has no way to verify a
+ * certificate against a name other than the URL host, so it is only honored by a transport
+ * that can (a custom `transport` passed to the client).
+ */
+export interface FetchTlsConfig {
+    strategy: 'none' | 'tls';
+    serverName?: string;
+}
+export interface FetchTransportOptions {
+    /** The tenant API token, sent as a bearer token on every call. */
+    token: string;
+    /**
+     * The engine's base URL, for example `https://engine.example.com:7070`: an absolute
+     * `http://` or `https://` URL with no username, password, query string or fragment. The RPC
+     * paths are appended to it as given, minus trailing slashes. Its scheme must agree with
+     * `tls`: `http://` needs `{ strategy: 'none' }`, since the token travels on every call.
+     */
+    serverUrl?: string;
+    /** The engine's `host:port`; used with `tls` to build the base URL when `serverUrl` is unset. */
+    hostPort?: string;
+    /**
+     * Defaults to `tls`. `hostPort` takes its scheme from it (`https://` unless `none`), and a
+     * `serverUrl` must agree with it.
+     */
+    tls?: FetchTlsConfig;
+    /** The `fetch` to send requests with. Defaults to the runtime's global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * The largest response accepted, in bytes after the runtime's HTTP decompression. Defaults
+     * to 4 MiB, the Node transport's `grpc_max_recv_message_length` default.
+     */
+    maxReceiveMessageBytes?: number;
+    /**
+     * The largest request sent, in bytes. Defaults to 4 MiB, the Node transport's
+     * `grpc_max_send_message_length` default.
+     */
+    maxSendMessageBytes?: number;
+}
+/** The limits `limitMessageSizes` applies, in bytes. */
+export interface MessageSizeLimits {
+    receive: number;
+    send: number;
+}
+/**
+ * Resolves the engine's base URL from a `serverUrl` or from `hostPort` plus the TLS
+ * strategy, the two ways a fetch-based client can be pointed at an engine. `hostPort` takes
+ * the gRPC target forms the Node client takes (`host:port`, `dns:///host:port`, `ipv4:`,
+ * `ipv6:`), so a token or config shared with a Node client works unchanged. A `serverUrl` is
+ * checked against the rules its documentation states, so a plaintext URL cannot slip past
+ * the TLS default.
+ */
+export declare function resolveServerUrl(options: Pick<FetchTransportOptions, 'serverUrl' | 'hostPort' | 'tls'>): string;
+/**
+ * The transport for runtimes that only have `fetch` (Cloudflare Workers, Vercel Functions,
+ * Deno, Bun, browsers). It must not depend on the HTTP version, since the engine answers unary
+ * calls over whichever of HTTP/1.1 and HTTP/2 the runtime negotiates, and it enforces the Node
+ * transport's message size limits itself because connect-web has none.
+ */
+export declare function createFetchTransport(options: FetchTransportOptions): Transport;
+/**
+ * Wraps a `fetch` with the message size limits the Node transport enforces through Connect's
+ * `readMaxBytes` and `writeMaxBytes`, which the fetch transport has no option for. A request
+ * body over the send limit is refused before anything is sent, and a response body that grows
+ * past the receive limit is cancelled as it streams, counted after the runtime's HTTP
+ * decompression so a small compressed body cannot expand past it; the limit covers Connect
+ * error bodies as well as messages. Both surface as a `ConnectError` with
+ * `Code.ResourceExhausted`, as they do on the Node transport.
+ */
+export declare function limitMessageSizes(send: typeof globalThis.fetch, limits: MessageSizeLimits): typeof globalThis.fetch;

package/clients/transport/fetch-transport.js

@@ -0,0 +1,152 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveServerUrl = resolveServerUrl;
+exports.createFetchTransport = createFetchTransport;
+exports.limitMessageSizes = limitMessageSizes;
+const connect_1 = require("@connectrpc/connect");
+const connect_web_1 = require("@connectrpc/connect-web");
+const grpc_target_1 = require("./grpc-target");
+const transport_1 = require("./transport");
+/**
+ * Resolves the engine's base URL from a `serverUrl` or from `hostPort` plus the TLS
+ * strategy, the two ways a fetch-based client can be pointed at an engine. `hostPort` takes
+ * the gRPC target forms the Node client takes (`host:port`, `dns:///host:port`, `ipv4:`,
+ * `ipv6:`), so a token or config shared with a Node client works unchanged. A `serverUrl` is
+ * checked against the rules its documentation states, so a plaintext URL cannot slip past
+ * the TLS default.
+ */
+function resolveServerUrl(options) {
+    var _a, _b;
+    const strategy = (_b = (_a = options.tls) === null || _a === void 0 ? void 0 : _a.strategy) !== null && _b !== void 0 ? _b : 'tls';
+    if (options.serverUrl) {
+        return validateServerUrl(options.serverUrl, strategy);
+    }
+    if (options.hostPort) {
+        const scheme = strategy === 'none' ? 'http' : 'https';
+        return (0, grpc_target_1.grpcTargetBaseUrl)((0, grpc_target_1.parseGrpcTarget)(options.hostPort), scheme);
+    }
+    throw new Error('a fetch transport needs a serverUrl or a hostPort');
+}
+/*
+ * The messages name the field and the rule only: a URL can carry a password, and the token
+ * is never part of it, so neither is echoed.
+ */
+function validateServerUrl(serverUrl, strategy) {
+    let url;
+    try {
+        url = new URL(serverUrl);
+    }
+    catch (_a) {
+        throw new Error('serverUrl must be an absolute http:// or https:// URL');
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error('serverUrl must be an absolute http:// or https:// URL');
+    }
+    if (url.username || url.password) {
+        throw new Error('serverUrl must not carry a username or password; the client authenticates with its token');
+    }
+    if (serverUrl.includes('?') || serverUrl.includes('#')) {
+        throw new Error('serverUrl must not carry a query string or fragment; the RPC path is appended to it');
+    }
+    if (url.protocol === 'http:' && strategy !== 'none') {
+        throw new Error("serverUrl is http:// but tls.strategy is 'tls' (the default), which would send the token in plaintext; set tls: { strategy: 'none' } to reach an engine over plain HTTP");
+    }
+    if (url.protocol === 'https:' && strategy === 'none') {
+        throw new Error("serverUrl is https:// but tls.strategy is 'none'; use tls: { strategy: 'tls' } or an http:// serverUrl");
+    }
+    return serverUrl.replace(/\/+$/, '');
+}
+/**
+ * The transport for runtimes that only have `fetch` (Cloudflare Workers, Vercel Functions,
+ * Deno, Bun, browsers). It must not depend on the HTTP version, since the engine answers unary
+ * calls over whichever of HTTP/1.1 and HTTP/2 the runtime negotiates, and it enforces the Node
+ * transport's message size limits itself because connect-web has none.
+ */
+function createFetchTransport(options) {
+    var _a, _b, _c;
+    const send = (_a = options.fetch) !== null && _a !== void 0 ? _a : ((input, init) => globalThis.fetch(input, init));
+    const limits = {
+        receive: (_b = options.maxReceiveMessageBytes) !== null && _b !== void 0 ? _b : transport_1.DEFAULT_MAX_MESSAGE_BYTES,
+        send: (_c = options.maxSendMessageBytes) !== null && _c !== void 0 ? _c : transport_1.DEFAULT_MAX_MESSAGE_BYTES,
+    };
+    return (0, connect_web_1.createConnectTransport)({
+        baseUrl: resolveServerUrl(options),
+        useBinaryFormat: true,
+        interceptors: [(0, transport_1.createAuthInterceptor)(options.token)],
+        fetch: limitMessageSizes(send, limits),
+    });
+}
+/**
+ * Wraps a `fetch` with the message size limits the Node transport enforces through Connect's
+ * `readMaxBytes` and `writeMaxBytes`, which the fetch transport has no option for. A request
+ * body over the send limit is refused before anything is sent, and a response body that grows
+ * past the receive limit is cancelled as it streams, counted after the runtime's HTTP
+ * decompression so a small compressed body cannot expand past it; the limit covers Connect
+ * error bodies as well as messages. Both surface as a `ConnectError` with
+ * `Code.ResourceExhausted`, as they do on the Node transport.
+ */
+function limitMessageSizes(send, limits) {
+    return (input, init) => __awaiter(this, void 0, void 0, function* () {
+        const size = bodySize(init === null || init === void 0 ? void 0 : init.body);
+        if (size > limits.send) {
+            throw new connect_1.ConnectError(`message size ${size} is larger than configured maxSendMessageBytes ${limits.send}`, connect_1.Code.ResourceExhausted);
+        }
+        const response = yield send(input, init);
+        if (!response.body) {
+            return response;
+        }
+        return new Response(limitBody(response.body, limits.receive), {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+    });
+}
+/** The size of the bodies Connect sends; a body of another kind is not measured. */
+function bodySize(body) {
+    if (typeof body === 'string') {
+        return new TextEncoder().encode(body).byteLength;
+    }
+    if (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) {
+        return body.byteLength;
+    }
+    if (body instanceof Blob) {
+        return body.size;
+    }
+    return 0;
+}
+function limitBody(body, max) {
+    const reader = body.getReader();
+    let received = 0;
+    return new ReadableStream({
+        pull(controller) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const { done, value } = yield reader.read();
+                if (done) {
+                    controller.close();
+                    return;
+                }
+                received += value.byteLength;
+                if (received > max) {
+                    const error = new connect_1.ConnectError(`response body is larger than configured maxReceiveMessageBytes ${max}`, connect_1.Code.ResourceExhausted);
+                    yield reader.cancel(error).catch(() => undefined);
+                    controller.error(error);
+                    return;
+                }
+                controller.enqueue(value);
+            });
+        },
+        cancel(reason) {
+            return reader.cancel(reason);
+        },
+    });
+}

package/clients/transport/grpc-target.js

@@ -2,7 +2,52 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseGrpcTarget = parseGrpcTarget;
 exports.grpcTargetBaseUrl = grpcTargetBaseUrl;
-const net_1 = require("net");
+/**
+ * IP literal checks with the same outcome as Node's `net.isIPv4` and `net.isIPv6` for the
+ * addresses a gRPC target can name. They are written here rather than imported from `net`
+ * because the fetch transport parses targets too, and it runs where `net` does not exist.
+ */
+const IPV4 = /^(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)$/;
+const HEX_GROUP = /^[0-9a-fA-F]{1,4}$/;
+/** What Node accepts after the one `%` of a zone id: nonempty, letters, digits, `-`, `.` and `:`. */
+const ZONE_ID = /^[0-9a-zA-Z\-.:]+$/;
+function isIPv4(address) {
+    return IPV4.test(address);
+}
+function isIPv6(address) {
+    const zoneAt = address.indexOf('%');
+    if (zoneAt !== -1 && !ZONE_ID.test(address.slice(zoneAt + 1))) {
+        return false;
+    }
+    const literal = zoneAt === -1 ? address : address.slice(0, zoneAt);
+    const halves = literal.split('::');
+    if (halves.length > 2) {
+        return false;
+    }
+    // An embedded IPv4 address counts as two groups and may only end the whole literal: the
+    // last item of the part after `::`, or of the only part when there is no `::`.
+    const groups = (part, endsLiteral) => {
+        if (part === '') {
+            return [];
+        }
+        const items = part.split(':');
+        const last = items[items.length - 1];
+        if (endsLiteral && last.includes('.')) {
+            if (!isIPv4(last)) {
+                return null;
+            }
+            items.splice(items.length - 1, 1, '0', '0');
+        }
+        return items.every((item) => HEX_GROUP.test(item)) ? items : null;
+    };
+    const head = groups(halves[0], halves.length === 1);
+    const tail = halves.length === 2 ? groups(halves[1], true) : [];
+    if (!head || !tail) {
+        return false;
+    }
+    const count = head.length + tail.length;
+    return halves.length === 2 ? count < 8 : count === 8;
+}
 /** The port grpc-js dials when a target names none. */
 const DEFAULT_PORT = 443;
 /*
@@ -40,10 +85,10 @@ function parseGrpcTarget(target) {
     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)) {
+    if (scheme === 'ipv4' && !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)) {
+    if (scheme === 'ipv6' && !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 };

package/clients/transport/index.d.ts

@@ -1,4 +1,5 @@
-export { createAuthInterceptor, type Transport } from './transport';
+export { createAuthInterceptor, DEFAULT_MAX_MESSAGE_BYTES, type Transport } from './transport';
 export { createNodeTransport } from './node-transport';
+export { createFetchTransport, limitMessageSizes, resolveServerUrl, type FetchTlsConfig, type FetchTransportOptions, type MessageSizeLimits, } from './fetch-transport';
 export { fromProtobufEs, toProtobufEs, type DeepPartial, type TsProtoCodec, } from './message-bridge';
 export { createTsProtoClient, headersToMetadata, metadataToHeaders, toConnectCallOptions, type UnaryCallOptions, type UnaryCallOptionsExt, } from './ts-proto-client';