@temporalio/core-bridge 1.11.8 → 1.12.0

package/lib/native.d.ts

@@ -0,0 +1,330 @@
+/**
+ * Indicates a property that is allowed to be unspecified when calling in or out of
+ * native code (the equivalent of the `Option<T>` type in Rust).
+ *
+ * Always use either this type or the `T | null` idiom to indicate a property that may
+ * legitimately be left unspecified when calling into or out of native code. Never use
+ * `T | undefined` or `prop?: T` on TS/Rust interfaces.
+ *
+ * ### Rationale
+ *
+ * Differentiating between "a property that is set to an unspecified optional value"
+ * and "a non-existant property" allows eager detection of some of the most common
+ * bug patterns resulting from incoherencies between the JS and Rust type definitions
+ * (e.g. optional properties whose names differ between the two languages, or that
+ * are missing in the JS interface, etc.).
+ *
+ * Unfortunately, it is not possible at present in Neon to differentiate between
+ * a property that is set to `undefined` and a property that is missing;
+ * i.e. `obj.get_value(cx, "prop")` will return `undefined` in both cases.
+ *
+ * We therefore follow the following principles for our TypeScript/Rust interfaces:
+ *
+ * - Always use `null` to indicate an intentionally unspecified optional value
+ *   in TypeScript interfaces. This will be converted to `None` on the Rust side.
+ * - Explicitly set _every_ properties on objects sent to the native code,
+ *   including optional properties (e.g. `{ prop: input.prop ?? null }`).
+ * - Never use the "optional property" syntax in TypeScript (i.e. `prop?: T`).
+ *
+ * Thanks to those conventions, a property that reads as `undefined` is known to to always
+ * indicate an _unintentionally missing_ property, which will results in a runtime error.
+ */
+type Option<T> = T | null;
+/**
+ * Marker for values that are transferred as JSON strings.
+ */
+export type JsonString<_T> = string;
+export declare function newRuntime(telemOptions: RuntimeOptions): Runtime;
+export declare function runtimeShutdown(runtime: Runtime): void;
+export interface Runtime {
+    type: 'runtime';
+}
+export type RuntimeOptions = {
+    logExporter: LogExporterOptions;
+    telemetry: TelemetryOptions;
+    metricsExporter: MetricExporterOptions;
+};
+export type TelemetryOptions = {
+    attachServiceName: boolean;
+    metricPrefix: string;
+};
+export type LogExporterOptions = {
+    type: 'console';
+    filter: string;
+} | {
+    type: 'forward';
+    filter: string;
+    receiver: (entries: JsonString<LogEntry>[]) => void;
+};
+export type MetricExporterOptions = PrometheusMetricsExporterOptions | OtelMetricsExporterOptions | null;
+export interface PrometheusMetricsExporterOptions {
+    type: 'prometheus';
+    socketAddr: string;
+    globalTags: Record<string, string>;
+    countersTotalSuffix: boolean;
+    unitSuffix: boolean;
+    useSecondsForDurations: boolean;
+    histogramBucketOverrides: Record<string, number[]>;
+}
+export interface OtelMetricsExporterOptions {
+    type: 'otel';
+    url: string;
+    headers: Record<string, string>;
+    metricPeriodicity: number;
+    metricTemporality: 'cumulative' | 'delta';
+    globalTags: Record<string, string>;
+    useSecondsForDurations: boolean;
+    histogramBucketOverrides: Record<string, number[]>;
+    protocol: 'http' | 'grpc';
+}
+export declare function newClient(runtime: Runtime, clientOptions: ClientOptions): Promise<Client>;
+export declare function clientUpdateHeaders(client: Client, headers: Record<string, string>): void;
+export declare function clientUpdateApiKey(client: Client, apiKey: string): void;
+export declare function clientSendRequest(client: Client, call: RpcCall): Promise<Buffer>;
+export declare function clientClose(client: Client): void;
+export interface Client {
+    type: 'client';
+}
+export interface ClientOptions {
+    targetUrl: string;
+    clientName: string;
+    clientVersion: string;
+    tls: Option<TLSConfig>;
+    httpConnectProxy: Option<HttpConnectProxy>;
+    headers: Option<Record<string, string>>;
+    apiKey: Option<string>;
+    disableErrorCodeMetricTags: boolean;
+}
+export interface TLSConfig {
+    domain: Option<string>;
+    serverRootCaCert: Option<Buffer>;
+    clientTlsConfig: Option<TlsConfigClientCertPair>;
+}
+export interface TlsConfigClientCertPair {
+    clientCert: Buffer;
+    clientPrivateKey: Buffer;
+}
+export interface HttpConnectProxy {
+    targetHost: string;
+    basicAuth: Option<{
+        username: string;
+        password: string;
+    }>;
+}
+export interface HttpConnectProxyBasicAuth {
+    username: string;
+    password: string;
+}
+export interface RpcCall {
+    rpc: string;
+    req: Buffer;
+    retry: boolean;
+    metadata: Record<string, string>;
+    timeout: Option<number>;
+}
+export declare function newWorker(client: Client, workerOptions: WorkerOptions): Worker;
+export declare function workerValidate(worker: Worker): Promise<void>;
+export declare function workerPollWorkflowActivation(worker: Worker): Promise<Buffer>;
+export declare function workerCompleteWorkflowActivation(worker: Worker, result: Buffer): Promise<void>;
+export declare function workerPollActivityTask(worker: Worker): Promise<Buffer>;
+export declare function workerCompleteActivityTask(worker: Worker, result: Buffer): Promise<void>;
+export declare function workerRecordActivityHeartbeat(worker: Worker, heartbeat: Buffer): void;
+export declare function workerInitiateShutdown(worker: Worker): void;
+export declare function workerFinalizeShutdown(worker: Worker): Promise<void>;
+export interface Worker {
+    type: 'worker';
+}
+export interface WorkerOptions {
+    identity: string;
+    buildId: string;
+    useVersioning: boolean;
+    workerDeploymentOptions: Option<WorkerDeploymentOptions>;
+    taskQueue: string;
+    namespace: string;
+    tuner: WorkerTunerOptions;
+    nonStickyToStickyPollRatio: number;
+    workflowTaskPollerBehavior: PollerBehavior;
+    activityTaskPollerBehavior: PollerBehavior;
+    enableNonLocalActivities: boolean;
+    stickyQueueScheduleToStartTimeout: number;
+    maxCachedWorkflows: number;
+    maxHeartbeatThrottleInterval: number;
+    defaultHeartbeatThrottleInterval: number;
+    maxTaskQueueActivitiesPerSecond: Option<number>;
+    maxActivitiesPerSecond: Option<number>;
+    shutdownGraceTime: number;
+}
+export type PollerBehavior = {
+    type: 'simple-maximum';
+    maximum: number;
+} | {
+    type: 'autoscaling';
+    minimum: number;
+    maximum: number;
+    initial: number;
+};
+export type WorkerDeploymentOptions = {
+    version: WorkerDeploymentVersion;
+    useWorkerVersioning: boolean;
+    defaultVersioningBehavior: VersioningBehavior;
+};
+export type WorkerDeploymentVersion = {
+    buildId: string;
+    deploymentName: string;
+};
+export type VersioningBehavior = {
+    type: 'pinned';
+} | {
+    type: 'auto-upgrade';
+};
+export interface WorkerTunerOptions {
+    workflowTaskSlotSupplier: SlotSupplierOptions;
+    activityTaskSlotSupplier: SlotSupplierOptions;
+    localActivityTaskSlotSupplier: SlotSupplierOptions;
+}
+export type SlotSupplierOptions = FixedSizeSlotSupplierOptions | ResourceBasedSlotSupplierOptions | CustomSlotSupplierOptions<any>;
+interface FixedSizeSlotSupplierOptions {
+    type: 'fixed-size';
+    numSlots: number;
+}
+interface ResourceBasedSlotSupplierOptions {
+    type: 'resource-based';
+    minimumSlots: number;
+    maximumSlots: number;
+    rampThrottle: number;
+    tunerOptions: ResourceBasedTunerOptions;
+}
+interface ResourceBasedTunerOptions {
+    targetMemoryUsage: number;
+    targetCpuUsage: number;
+}
+export interface CustomSlotSupplierOptions<SI extends SlotInfo> {
+    type: 'custom';
+    reserveSlot(ctx: SlotReserveContext, abortSignal: AbortSignal): Promise<SlotPermit>;
+    tryReserveSlot(ctx: SlotReserveContext): Option<SlotPermit>;
+    markSlotUsed(ctx: SlotMarkUsedContext<SI>): void;
+    releaseSlot(ctx: SlotReleaseContext<SI>): void;
+}
+export type SlotInfo = {
+    type: 'workflow';
+    workflowType: string;
+    isSticky: boolean;
+} | {
+    type: 'activity';
+    activityType: string;
+} | {
+    type: 'local-activity';
+    activityType: string;
+} | {
+    type: 'nexus';
+    service: string;
+    operation: string;
+};
+export interface SlotReserveContext {
+    slotType: SlotInfo['type'];
+    taskQueue: string;
+    workerIdentity: string;
+    workerDeploymentVersion: Option<WorkerDeploymentVersion>;
+    isSticky: boolean;
+}
+export interface SlotMarkUsedContext<SI extends SlotInfo> {
+    slotInfo: SI;
+    permit: SlotPermit;
+}
+export interface SlotReleaseContext<SI extends SlotInfo> {
+    slotInfo: Option<SI>;
+    permit: SlotPermit;
+}
+export interface SlotPermit {
+}
+export declare function newReplayWorker(runtime: Runtime, workerOptions: WorkerOptions): [Worker, HistoryPusher];
+export declare function pushHistory(pusher: HistoryPusher, workflowId: string, history: Buffer): Promise<void>;
+export declare function closeHistoryStream(pusher: HistoryPusher): void;
+export interface HistoryPusher {
+    type: 'history-pusher';
+}
+export declare function newEphemeralServer(runtime: Runtime, config: EphemeralServerConfig): Promise<EphemeralServer>;
+export declare function ephemeralServerGetTarget(server: EphemeralServer): string;
+export declare function ephemeralServerShutdown(server: EphemeralServer): Promise<void>;
+export interface EphemeralServer {
+    type: 'ephemeral-server';
+}
+export type EphemeralServerConfig = TimeSkippingServerConfig | DevServerConfig;
+export interface TimeSkippingServerConfig {
+    type: 'time-skipping';
+    exe: EphemeralServerExecutableConfig;
+    port: Option<number>;
+    extraArgs: string[];
+}
+export interface DevServerConfig {
+    type: 'dev-server';
+    exe: EphemeralServerExecutableConfig;
+    namespace: string;
+    ip: string;
+    port: Option<number>;
+    uiPort: Option<number>;
+    dbFilename: Option<string>;
+    ui: boolean;
+    log: DevServerLogConfig;
+    extraArgs: string[];
+}
+export interface DevServerLogConfig {
+    format: string;
+    level: string;
+}
+export type EphemeralServerExecutableConfig = CachedDownloadConfig | ExistingPathConfig;
+export interface CachedDownloadConfig {
+    type: 'cached-download';
+    downloadDir: Option<string>;
+    version: string;
+    ttl: number;
+    sdkName: string;
+    sdkVersion: string;
+}
+export interface ExistingPathConfig {
+    type: 'existing-path';
+    path: string;
+}
+export declare function getTimeOfDay(): bigint;
+export interface LogEntry {
+    target: string;
+    message: string;
+    timestamp: string;
+    level: LogLevel;
+    fields: LogEntryMetadata;
+    spanContexts: string[];
+}
+type LogLevel = 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+type LogEntryMetadata = {
+    [key: string]: string | number | boolean | LogEntryMetadata;
+};
+export interface MetricMeter {
+    type: 'metric-meter';
+}
+export interface MetricCounter {
+    type: 'metric-counter';
+}
+export interface MetricHistogram {
+    type: 'metric-histogram';
+}
+export interface MetricHistogramF64 {
+    type: 'metric-histogram-f64';
+}
+export interface MetricGauge {
+    type: 'metric-gauge';
+}
+export interface MetricGaugeF64 {
+    type: 'metric-gauge-f64';
+}
+export type MetricAttributes = Record<string, string | number | boolean>;
+export declare function newMetricCounter(runtime: Runtime, name: string, unit: string, description: string): MetricCounter;
+export declare function newMetricHistogram(runtime: Runtime, name: string, unit: string, description: string): MetricHistogram;
+export declare function newMetricHistogramF64(runtime: Runtime, name: string, unit: string, description: string): MetricHistogramF64;
+export declare function newMetricGauge(runtime: Runtime, name: string, unit: string, description: string): MetricGauge;
+export declare function newMetricGaugeF64(runtime: Runtime, name: string, unit: string, description: string): MetricGaugeF64;
+export declare function addMetricCounterValue(counter: MetricCounter, value: number, attrs: JsonString<MetricAttributes>): void;
+export declare function recordMetricHistogramValue(histogram: MetricHistogram, value: number, attrs: JsonString<MetricAttributes>): void;
+export declare function recordMetricHistogramF64Value(histogram: MetricHistogramF64, value: number, attrs: JsonString<MetricAttributes>): void;
+export declare function setMetricGaugeValue(gauge: MetricGauge, value: number, attrs: JsonString<MetricAttributes>): void;
+export declare function setMetricGaugeF64Value(gauge: MetricGaugeF64, value: number, attrs: JsonString<MetricAttributes>): void;
+export {};

package/lib/{worker-tuner.js → native.js}

@@ -1,3 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=worker-tuner.js.map
+//# sourceMappingURL=native.js.map

package/lib/native.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.js","sourceRoot":"","sources":["../ts/native.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temporalio/core-bridge",
-  "version": "1.11.8",
+  "version": "1.12.0",
   "description": "Temporal.io SDK Core<>Node bridge",
   "main": "index.js",
   "types": "lib/index.d.ts",
@@ -22,7 +22,8 @@
   "author": "Temporal Technologies Inc. <sdk@temporal.io>",
   "license": "MIT",
   "dependencies": {
-    "@temporalio/common": "1.11.8",
+    "@grpc/grpc-js": "^1.12.4",
+    "@temporalio/common": "1.12.0",
     "arg": "^5.0.2",
     "cargo-cp-artifact": "^0.1.8",
     "which": "^4.0.0"
@@ -36,6 +37,9 @@
     "directory": "packages/core-bridge"
   },
   "homepage": "https://github.com/temporalio/sdk-typescript/tree/main/packages/core-bridge",
+  "engines": {
+    "node": ">= 18.0.0"
+  },
   "files": [
     "scripts",
     "src",
@@ -52,5 +56,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "0a757c370012d89babb668fbd799d83b55c83a1b"
+  "gitHead": "8757698f4d722f392e4d606a215e84c32420aa25"
 }

package/sdk-core/.cargo/config.toml

@@ -4,8 +4,14 @@
 CLI_VERSION_OVERRIDE = "v1.3.1-priority.0"
 
 [alias]
-integ-test = ["run", "--package", "temporal-sdk-core", "--example", "integ_runner", "--"]
+integ-test = ["test", "--features", "temporal-sdk-core-protos/serde_serialize", "--package", "temporal-sdk-core", "--test", "integ_runner", "--"]
 lint = ["clippy", "--workspace", "--examples", "--all-features",
-    "--test", "integ_tests", "--test", "heavy_tests", "--", "--D", "warnings"]
+    "--test", "integ_tests", "--test", "heavy_tests", "--test", "manual_tests",
+    "--", "--D", "warnings"]
+lint-fix = ["clippy", "--workspace", "--examples", "--all-features",
+    "--test", "integ_tests", "--test", "heavy_tests", "--test", "manual_tests",
+    "--fix", "--allow-dirty"]
 test-lint = ["clippy", "--all", "--all-features", "--examples", "--workspace",
     "--tests", "--", "--D", "warnings"]
+test-lint-fix = ["clippy", "--all", "--all-features", "--examples", "--workspace",
+    "--tests", "--fix", "--allow-dirty"]

package/sdk-core/.cargo/multi-worker-manual-test

@@ -0,0 +1,15 @@
+#!/bin/sh
+
+# Use this script during manual testing against a server to run multiple instances
+# of a test, thus acting like multiple workers are running concurrently
+
+# Usage: multi-worker-heavy-test <number of workers> <integ test name>
+
+# You may want to set env vars for targeting cloud first, ex (fish syntax):
+# set -gx TEMPORAL_SERVICE_ADDRESS "https://sj-poller-test.e2e.tmprl-test.cloud:7233"
+# set -gx TEMPORAL_USE_TLS 1
+# set -gx TEMPORAL_NAMESPACE sj-poller-test.e2e
+
+cargo integ-test -c "--release" -t manual_tests --just-build
+
+parallel --line-buffer --process-slot-var=PAR_JOBNUM -j $1 cargo integ-test -c "--release" -s external -t manual_tests -- --nocapture $2 ::: $(seq 1 $1)

package/sdk-core/.github/workflows/per-pr.yml

@@ -11,7 +11,7 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  build-and-test:
+  build-and-lint:
     name: "Format, docs, and lint"
     timeout-minutes: 10
     runs-on: ubuntu-latest
@@ -21,7 +21,7 @@ jobs:
           submodules: recursive
       - uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.85.0
+          toolchain: 1.88.0
       - name: Install protoc
         uses: arduino/setup-protoc@v3
         with:
@@ -56,13 +56,22 @@ jobs:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.85.0
+          toolchain: 1.88.0
       - name: Install protoc
         uses: arduino/setup-protoc@v3
         with:
           # TODO: Upgrade proto once https://github.com/arduino/setup-protoc/issues/99 is fixed
           version: '23.x'
           repo-token: ${{ secrets.GITHUB_TOKEN }}
+      # Workaround for https://github.com/actions/runner-images/issues/12432
+      # from https://github.com/rust-lang/rust/issues/141626#issuecomment-2919419236
+      # Visual Studio bug tracker https://developercommunity.visualstudio.com/t/Regression-from-1943:-linkexe-crashes/10912960
+      - name: Setup RUSTFLAGS (Windows)
+        if: runner.os == 'Windows'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            core.exportVariable('RUSTFLAGS', '-Csymbol-mangling-version=v0');
       - uses: Swatinem/rust-cache@v2
       - run: cargo test -- --include-ignored --nocapture
       - uses: actions/upload-artifact@v4
@@ -76,11 +85,6 @@ jobs:
 
   integ-tests:
     name: Integ tests
-    env:
-      TEMPORAL_CLOUD_ADDRESS: https://${{ vars.TEMPORAL_CLIENT_NAMESPACE }}.tmprl.cloud:7233
-      TEMPORAL_CLOUD_NAMESPACE: ${{ vars.TEMPORAL_CLIENT_NAMESPACE }}
-      TEMPORAL_CLIENT_CERT: ${{ secrets.TEMPORAL_CLIENT_CERT }}
-      TEMPORAL_CLIENT_KEY: ${{ secrets.TEMPORAL_CLIENT_KEY }}
     timeout-minutes: 20
     strategy:
       fail-fast: false
@@ -100,7 +104,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.85.0
+          toolchain: 1.88.0
       - name: Install protoc
         uses: arduino/setup-protoc@v3
         with:
@@ -111,6 +115,31 @@ jobs:
       - uses: Swatinem/rust-cache@v2
       - run: cargo integ-test
 
+  cloud-tests:
+    if: github.event.pull_request.head.repo.full_name == '' || github.event.pull_request.head.repo.full_name == 'temporalio/sdk-core'
+    name: Cloud tests
+    env:
+      TEMPORAL_CLOUD_ADDRESS: https://${{ vars.TEMPORAL_CLIENT_NAMESPACE }}.tmprl.cloud:7233
+      TEMPORAL_NAMESPACE: ${{ vars.TEMPORAL_CLIENT_NAMESPACE }}
+      TEMPORAL_CLIENT_CERT: ${{ secrets.TEMPORAL_CLIENT_CERT }}
+      TEMPORAL_CLIENT_KEY: ${{ secrets.TEMPORAL_CLIENT_KEY }}
+    timeout-minutes: 20
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: 1.88.0
+      - name: Install protoc
+        uses: arduino/setup-protoc@v3
+        with:
+          # TODO: Upgrade proto once https://github.com/arduino/setup-protoc/issues/99 is fixed
+          version: '23.x'
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo test --test cloud_tests
+
   docker-integ-tests:
     name: Docker integ tests
     env:
@@ -125,7 +154,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.85.0
+          toolchain: 1.88.0
       - name: Install protoc
         uses: arduino/setup-protoc@v3
         with:
@@ -137,4 +166,4 @@ jobs:
         with:
           compose-file: ./docker/docker-compose-ci.yaml
       - uses: Swatinem/rust-cache@v2
-      - run: cargo integ-test test_docker_
+      - run: cargo integ-test docker_

package/sdk-core/AGENTS.md

@@ -0,0 +1,73 @@
+# Contributor Guidance for `sdk-core`
+
+This repository provides a Rust workspace for the Temporal Core SDK and related crates. Use this
+document as your quick reference when submitting pull requests.
+
+## Where Things Are
+
+- `core/` – implementation of the core SDK
+- `client/` – clients for communicating with Temporal clusters
+- `core-api/` – API definitions exposed by core
+- `sdk/` – pre-alpha Rust SDK built on top of core (used mainly for tests)
+- `sdk-core-protos/` – protobuf definitions shared across crates
+- `fsm/` – state machine implementation and macros
+- `test-utils/` – helpers and binaries for tests
+- `tests/` – integration, heavy, and manual tests
+- `arch_docs/` – architectural design documents
+- Contributor guide: `README.md`
+
+## Repo Specific Utilities
+
+- `.cargo/config.toml` defines useful cargo aliases:
+    - `cargo lint` – run clippy on workspace crates
+    - `cargo test-lint` – run clippy on tests
+    - `cargo integ-test` – run the integration test runner
+- `cargo-tokio-console.sh` – run any cargo command with the `tokio-console` feature
+- `integ-with-otel.sh` – run integration tests with OpenTelemetry enabled
+- `.cargo/multi-worker-manual-test` – helper script for spawning multiple workers during manual
+  testing
+
+## Building and Testing
+
+The following commands are enforced for each pull request (see `README.md`):
+
+```bash
+cargo build            # build all crates
+cargo test             # run unit tests
+cargo integ-test       # integration tests (starts ephemeral server by default)
+cargo test --test heavy_tests  # load tests -- agents do not need to run this and should not
+```
+
+Additional checks:
+
+```bash
+cargo fmt --all        # format code
+cargo clippy --all -- -D warnings  # lint
+```
+
+Documentation can be generated with `cargo doc`.
+
+## Expectations for Pull Requests
+
+- Format and lint your code before submitting.
+- Ensure all tests pass locally. Integration tests may require a running Temporal server or the
+  ephemeral server started by `cargo integ-test`.
+- Keep commit messages short and in the imperative mood.
+- Provide a clear PR description outlining what changed and why.
+- Reviewers expect new features or fixes to include corresponding tests when applicable.
+
+## Review Checklist
+
+Reviewers will look for:
+
+- All builds, tests, and lints passing in CI
+- New tests covering behavior changes
+- Clear and concise code following existing style (see `README.md` for error handling guidance)
+- Documentation updates for any public API changes
+
+## Notes
+
+- Fetch workflow histories with `cargo run --bin histfetch <workflow_id> [run_id]` (binary lives in
+  `test-utils`).
+- Protobuf files under `sdk-core-protos/protos/api_upstream` are a git subtree; see `README.md` for
+  update instructions.