@temporalio/core-bridge 1.14.2-canary-release-testing.0 → 1.16.0

package/bridge-macros/src/derive_tryintojs.rs

@@ -30,6 +30,46 @@ pub fn derive_tryintojs_struct(input: &DeriveInput, data: &syn::DataStruct) -> T
 }
 
 pub fn derive_tryintojs_enum(input: &DeriveInput, data: &syn::DataEnum) -> TokenStream {
+    let all_unit = data
+        .variants
+        .iter()
+        .all(|v| matches!(v.fields, syn::Fields::Unit));
+    if all_unit {
+        derive_tryintojs_enum_as_string(input, data)
+    } else {
+        derive_tryintojs_enum_as_objects(input, data)
+    }
+}
+
+fn derive_tryintojs_enum_as_string(input: &DeriveInput, data: &syn::DataEnum) -> TokenStream {
+    let enum_ident = &input.ident;
+    let generics = &input.generics;
+    let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
+
+    let variant_conversions = data.variants.iter().map(|v| {
+        let variant_ident = &v.ident;
+        let js_discriminant = variant_ident.to_string().to_case(Case::Camel);
+        quote! {
+            #enum_ident::#variant_ident => cx.string(#js_discriminant)
+        }
+    });
+
+    let expanded = quote! {
+        impl #impl_generics crate::helpers::TryIntoJs for #enum_ident #ty_generics #where_clause {
+            type Output = neon::types::JsString;
+
+            fn try_into_js<'a>(self, cx: &mut impl neon::prelude::Context<'a>) -> neon::result::JsResult<'a, Self::Output> {
+                Ok(match self {
+                    #(#variant_conversions),*
+                })
+            }
+        }
+    };
+
+    TokenStream::from(expanded)
+}
+
+fn derive_tryintojs_enum_as_objects(input: &DeriveInput, data: &syn::DataEnum) -> TokenStream {
     let enum_ident = &input.ident;
     let generics = &input.generics;
     let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();

package/lib/native.d.ts

@@ -57,7 +57,7 @@ export type LogExporterOptions = {
     filter: string;
     receiver: (entries: JsonString<LogEntry>[]) => void;
 };
-export type MetricExporterOptions = PrometheusMetricsExporterOptions | OtelMetricsExporterOptions | null;
+export type MetricExporterOptions = PrometheusMetricsExporterOptions | OtelMetricsExporterOptions | BufferedMetricsExporterOptions | null;
 export interface PrometheusMetricsExporterOptions {
     type: 'prometheus';
     socketAddr: string;
@@ -78,6 +78,11 @@ export interface OtelMetricsExporterOptions {
     histogramBucketOverrides: Record<string, number[]>;
     protocol: 'http' | 'grpc';
 }
+export interface BufferedMetricsExporterOptions {
+    type: 'buffer';
+    maxBufferSize: number;
+    useSecondsForDurations: boolean;
+}
 export declare function newClient(runtime: Runtime, clientOptions: ClientOptions): Promise<Client>;
 export declare function clientUpdateHeaders(client: Client, headers: Record<string, MetadataValue>): void;
 export declare function clientUpdateApiKey(client: Client, apiKey: string): void;
@@ -127,7 +132,7 @@ export interface RpcCall {
     timeout: Option<number>;
 }
 export declare function newWorker(client: Client, workerOptions: WorkerOptions): Worker;
-export declare function workerValidate(worker: Worker): Promise<void>;
+export declare function workerValidate(worker: Worker): Promise<Buffer>;
 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>;
@@ -137,6 +142,7 @@ export declare function workerPollNexusTask(worker: Worker): Promise<Buffer>;
 export declare function workerCompleteNexusTask(worker: Worker, result: Buffer): Promise<void>;
 export declare function workerInitiateShutdown(worker: Worker): void;
 export declare function workerFinalizeShutdown(worker: Worker): Promise<void>;
+export declare function workerReplaceClient(worker: Worker, client: Client): void;
 export interface Worker {
     type: 'worker';
 }
@@ -186,7 +192,7 @@ export type PollerBehavior = {
 export type WorkerDeploymentOptions = {
     version: WorkerDeploymentVersion;
     useWorkerVersioning: boolean;
-    defaultVersioningBehavior: VersioningBehavior;
+    defaultVersioningBehavior: Option<VersioningBehavior>;
 };
 export type WorkerDeploymentVersion = {
     buildId: string;
@@ -348,4 +354,19 @@ export declare function recordMetricHistogramValue(histogram: MetricHistogram, v
 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 declare function runtimeRetrieveBufferedMetrics(runtime: Runtime): BufferedMetricUpdate[];
+export interface BufferedMetricUpdate {
+    metric: BufferedMetric;
+    value: number;
+    attributes: MetricAttributes;
+}
+export interface BufferedMetric {
+    name: string;
+    description: string;
+    unit: string;
+    kind: BufferedMetricKind;
+    valueType: BufferedMetricValueType;
+}
+export type BufferedMetricKind = 'counter' | 'histogram' | 'gauge';
+export type BufferedMetricValueType = 'int' | 'float';
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temporalio/core-bridge",
-  "version": "1.14.2-canary-release-testing.0",
+  "version": "1.16.0",
   "description": "Temporal.io SDK Core<>Node bridge",
   "main": "index.js",
   "types": "lib/index.d.ts",
@@ -14,7 +14,7 @@
   "license": "MIT",
   "dependencies": {
     "@grpc/grpc-js": "^1.12.4",
-    "@temporalio/common": "1.14.2-canary-release-testing.0"
+    "@temporalio/common": "1.16.0"
   },
   "devDependencies": {
     "arg": "^5.0.2",
@@ -31,7 +31,7 @@
   },
   "homepage": "https://github.com/temporalio/sdk-typescript/tree/main/packages/core-bridge",
   "engines": {
-    "node": ">= 18.0.0"
+    "node": ">= 20.0.0"
   },
   "files": [
     "bridge-macros",
@@ -56,6 +56,6 @@
     "build-rust-release": "pnpm run build-rust --release",
     "format": "cargo fmt",
     "lint": "cargo clippy --fix --allow-staged",
-    "lint.check": "cargo clippy"
+    "lint:check": "cargo clippy"
   }
 }

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

@@ -25,7 +25,7 @@ jobs:
           submodules: recursive
       - uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.90.0
+          toolchain: 1.92.0
       - name: Install protoc
         uses: arduino/setup-protoc@v3
         with:
@@ -64,7 +64,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.90.0
+          toolchain: 1.92.0
       - name: Install protoc
         uses: arduino/setup-protoc@v3
         with:
@@ -143,7 +143,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.90.0
+          toolchain: 1.92.0
       - name: Install protoc
         uses: arduino/setup-protoc@v3
         with:
@@ -176,7 +176,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.90.0
+          toolchain: 1.92.0
       - name: Install protoc
         uses: arduino/setup-protoc@v3
         with:
@@ -201,7 +201,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.90.0
+          toolchain: 1.92.0
       - name: Install protoc
         uses: arduino/setup-protoc@v3
         with:
@@ -222,7 +222,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.90.0
+          toolchain: 1.92.0
       - name: Install protoc
         uses: arduino/setup-protoc@v3
         with:

package/sdk-core/AGENTS.md

@@ -3,51 +3,48 @@
 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
+## Requirements for coding agents
+
+- Always use `cargo integ-test <test_name>` for running integration tests. Do not run them directly. If you have added `dbg!` or println statements, you must add `-- --nocapture` to see them.
+- Unit tests may be run with `cargo test`. If you are about to run a test, you do not need to run
+  `cargo build` separately first. Just run the test, and it will build. Running `cargo build --test`
+  DOES NOT build integration tests. Use `cargo lint` for checking if integration tests compile
+  without running them.
+- Always use `cargo lint` for checking lints / clippy. Do not use clippy directly.
+- It is EXTREMELY IMPORTANT that any added comments should explain why something needs to be done,
+  rather than what it is. Comments that simply state a fact easily understood from type signatures
+  or other context should NEVER be added. Always prefer to avoid a comment unless it truly is 
+  clarifying something nonobvious.
+- Always make every attempt to avoid explicit sleeps in test code. Instead rely on synchronization
+  techniques like channels, Notify, etc.
+- Rust compilation can take some time. Do not interrupt builds or tests unless they are taking more
+  than 5 minutes. When making changes that may break integration tests, after compiling, run
+  integration tests with `timeout 180`, as it is possible to introduce test hangs.
+- DO NOT put use statements in function scope. Always put them at the top of the file, unless doing
+  so helps prevent ambiguous method resolution because of traits. Putting them at the top of a tests module is also acceptable.
 
-- `crates` - All crates in the workspace.
-  - `crates/core/` – implementation of the core SDK
-  - `crates/client/` – clients for communicating with Temporal clusters
-  - `crates/core-api/` – API definitions exposed by core
-  - `crates/core-c-bridge/` – C interface for core
-  - `crates/sdk/` – pre-alpha Rust SDK built on top of core (used mainly for tests)
-  - `crates/sdk-core-protos/` – protobuf definitions shared across crates
-  - `crates/fsm/` – state machine implementation and macros
-  - `crates/core/tests/` – integration, heavy, and manual tests
-- `arch_docs/` – architectural design documents
-- Contributor guide: `README.md`
-- `target/` - This contains compiled files. You never need to look in here.
 
 ## 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 lint` – run clippy on workspace crates and integration tests
+  - `cargo test-lint` – run clippy on unit tests
   - `cargo integ-test` – run the integration test runner
-- `etc` - Various helper scripts and configuration
-  - `etc/docker` - Docker compose files to help with CI or more complex local 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 fmt --all --check # ensure code is formatted
+cargo build             # build all crates
+cargo lint              # run lints
+cargo test-lint         # run lints on tests
+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
 ```
 
-Rust compilation can take some time. Do not interrupt builds or tests unless they are taking more
-than 10 minutes.
-
-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
@@ -70,9 +67,23 @@ Reviewers will look for:
 - Clear and concise code following existing style (see `README.md` for error handling guidance)
 - Documentation updates for any public API changes
 
+## Where Things Are
+
+- `crates` - All crates in the workspace.
+  - `crates/client/` – clients for communicating with Temporal clusters
+  - `crates/common/` – Common functionality & protobuf definitions
+  - `crates/macros/` – procedural macro implementations
+  - `crates/sdk/` – Rust SDK built on top of core
+  - `crates/sdk-core/` – implementation of the core SDK
+      - `crates/sdk-core/tests/` – integration, heavy, and manual tests
+  - `crates/sdk-core-c-bridge/` – C interface for core
+- `arch_docs/` – architectural design documents
+- Contributor guide: `README.md`
+- `target/` - This contains compiled files. You never need to look in here.
+
 ## Notes
 
 - Fetch workflow histories with `cargo run --bin histfetch <workflow_id> [run_id]` (binary lives in
   `crates/core/src/histfetch.rs`).
-- Protobuf files under `crates/sdk-core-protos/protos/api_upstream` are a git subtree; see
+- Protobuf files under `crates/common/protos/api_upstream` are a git subtree; see
   `README.md` for update instructions.

package/sdk-core/Cargo.toml

@@ -14,7 +14,7 @@ license = "MIT"
 license-file = "LICENSE.txt"
 
 [workspace.dependencies]
-derive_builder = "0.20"
+bon = { version = "3", features = ["implied-bounds"] }
 derive_more = { version = "2.0", features = [
     "constructor",
     "display",
@@ -30,6 +30,9 @@ tonic-prost-build = "0.14"
 opentelemetry = { version = "0.31", features = ["metrics"] }
 prost = "0.14"
 prost-types = { version = "0.7", package = "prost-wkt-types" }
+pbjson = "0.9"
+pbjson-types = "0.9"
+pbjson-build = "0.9"
 
 [workspace.lints.rust]
 unreachable_pub = "warn"

package/sdk-core/README.md

@@ -7,6 +7,20 @@ Core SDK that can be used as a base for other Temporal SDKs. It is currently use
 - [.NET SDK](https://github.com/temporalio/sdk-dotnet/)
 - [Ruby SDK](https://github.com/temporalio/sdk-ruby/)
 
+# Temporal Rust SDK
+
+[![crates.io](https://img.shields.io/crates/v/temporalio-sdk.svg)](https://crates.io/crates/temporalio-sdk)
+[![docs.rs](https://docs.rs/temporalio-sdk/badge.svg)](https://docs.rs/temporalio-sdk)
+
+Currently prerelease, see more in the [SDK README.md](crates/sdk/README.md)
+
+# Temporal Rust Client
+
+[![crates.io](https://img.shields.io/crates/v/temporalio-sdk.svg)](https://crates.io/crates/temporalio-client)
+[![docs.rs](https://docs.rs/temporalio-sdk/badge.svg)](https://docs.rs/temporalio-client)
+
+Currently prerelease, see more in the [client README.md](crates/client/README.md)
+
 # Documentation
 
 Core SDK documentation can be generated with `cargo doc`, output will be placed in the
@@ -87,13 +101,13 @@ equivalent.
 
 ## Proto files
 
-This repo uses a subtree for upstream protobuf files. The path `sdk-core-protos/protos/api_upstream`
+This repo uses a subtree for upstream protobuf files. The path `crates/common/protos/api_upstream`
 is a subtree. To update it, use:
 
-`git pull --squash --rebase=false -s subtree ssh://git@github.com/temporalio/api.git master --allow-unrelated-histories`
+`git pull --squash --rebase=false -s subtree -X subtree=crates/common/protos/api_upstream ssh://git@github.com/temporalio/api.git master --allow-unrelated-histories`
 
 Do not question why this git command is the way it is. It is not our place to interpret git's ways.
-This same approach can be taken for updating `sdk-core-protos/protos/api_cloud_upstream` from the
+This same approach can be taken for updating `crates/common/protos/api_cloud_upstream` from the
 `api-cloud` repo.
 
 The java testserver protos are also pulled from the sdk-java repo, but since we only need a
@@ -103,9 +117,9 @@ subdirectory of that repo, we just copy the files with read-tree:
 # add sdk-java as a remote if you have not already
 git remote add -f -t master --no-tags testsrv-protos git@github.com:temporalio/sdk-java.git
 # delete existing protos
-git rm -rf sdk-core-protos/protos/testsrv_upstream
+git rm -rf crates/common/protos/testsrv_upstream
 # pull from upstream & commit
-git read-tree --prefix sdk-core-protos/protos/testsrv_upstream -u testsrv-protos/master:temporal-test-server/src/main/proto
+git read-tree --prefix crates/common/protos/testsrv_upstream -u testsrv-protos/master:temporal-test-server/src/main/proto
 git commit
 ```
 
@@ -127,11 +141,3 @@ Any error which is returned from a public interface should be well-typed, and we
 
 Errors returned from things only used in testing are free to use
 [anyhow](https://github.com/dtolnay/anyhow) for less verbosity.
-
-# The Rust "SDK"
-
-This repo contains a *prototype* Rust sdk in the `sdk/` directory. This SDK should be considered
-pre-alpha in terms of its API surface. Since it's still using Core underneath, it is generally
-functional. We do not currently have any firm plans to productionize this SDK. If you want to write
-workflows and activities in Rust, feel free to use it - but be aware that the API may change at any
-time without warning and we do not provide any support guarantees.

package/sdk-core/crates/client/Cargo.toml

@@ -9,9 +9,11 @@ homepage = "https://temporal.io/"
 repository = "https://github.com/temporalio/sdk-core"
 keywords = ["temporal", "workflow"]
 categories = ["development-tools"]
+readme = "README.md"
 
 [features]
 telemetry = ["dep:opentelemetry"]
+core-based-sdk = []
 
 [dependencies]
 anyhow = "1.0"
@@ -42,10 +44,12 @@ rand = "0.9.2"
 
 [dependencies.temporalio-common]
 path = "../common"
+version = "0.1"
 
 [dev-dependencies]
 assert_matches = "1"
 mockall = "0.13"
+prost = "0.14"
 rstest = "0.26"
 
 [lints]

package/sdk-core/crates/client/README.md

@@ -0,0 +1,139 @@
+# Temporal Rust Client
+
+[![crates.io](https://img.shields.io/crates/v/temporalio-client.svg)](https://crates.io/crates/temporalio-client)
+[![docs.rs](https://docs.rs/temporalio-client/badge.svg)](https://docs.rs/temporalio-client)
+
+This crate provides a Rust client for interacting with the Temporal service. It can be used
+standalone to start and manage workflows, or together with the
+[`temporalio-sdk`](https://crates.io/crates/temporalio-sdk) crate to run workers.
+
+⚠️ **This crate is under active development and should be considered prerelease.** The API can and
+will continue to evolve.
+
+## Quick Start
+
+### Connecting and Starting Workflows
+
+```rust
+use temporalio_client::{
+    Client, ClientOptions, Connection, ConnectionOptions,
+    WorkflowOptions, GetWorkflowResultOptions,
+};
+use temporalio_sdk_core::{Url, CoreRuntime, RuntimeOptions};
+use std::str::FromStr;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let connection = Connection::connect(
+        ConnectionOptions::new(Url::from_str("http://localhost:7233")?)
+            .identity("my-client".to_string())
+            .build()
+    ).await?;
+
+    // "default" is your namespace
+    let client = Client::new(connection, ClientOptions::new("default").build());
+
+    // Start a workflow
+    let handle = client.start_workflow(
+        GreetingWorkflow::run,
+        "World".to_string(),
+        WorkflowOptions::new("my-task-queue", "greeting-workflow-1").build()
+    ).await?;
+
+    // Wait for the result
+    let result = handle.get_result(GetWorkflowResultOptions::default()).await?;
+
+    Ok(())
+}
+```
+
+### Signals, Queries, and Updates
+
+Once you have a workflow handle, you can interact with the running workflow:
+
+```rust
+use temporalio_client::{
+    SignalOptions, QueryOptions, UpdateOptions,
+    StartUpdateOptions, WorkflowUpdateWaitStage,
+    UntypedSignal,
+};
+use temporalio_common::data_converters::{PayloadConverter, RawValue};
+
+// Get a handle to an existing workflow (or use one from start_workflow)
+let handle = client.get_workflow_handle::<MyWorkflow>("workflow-id");
+
+// --- Signals (fire-and-forget messages) ---
+handle.signal(MyWorkflow::push_value, 42, SignalOptions::default()).await?;
+
+// --- Queries (read workflow state) ---
+let values = handle
+    .query(MyWorkflow::get_values, (), QueryOptions::default())
+    .await?;
+
+// --- Updates (modify state and get a result) ---
+let values = handle
+    .execute_update(MyWorkflow::add_wait_return, 100, UpdateOptions::default())
+    .await?;
+
+// Start an update and wait for acceptance only
+let update_handle = handle
+    .start_update(
+        MyWorkflow::add_wait_return,
+        50,
+        StartUpdateOptions::builder()
+            .wait_for_stage(WorkflowUpdateWaitStage::Accepted)
+            .build()
+    )
+    .await?;
+update_handle.get_result().await?;
+
+// --- Untyped interactions (when types aren't known at compile time) ---
+let pc = PayloadConverter::serde_json();
+handle
+    .signal(
+        UntypedSignal::new("increment"),
+        RawValue::from_value(&25i32, &pc),
+        SignalOptions::default(),
+    )
+    .await?;
+// UntypedQuery and UntypedUpdate work similarly
+```
+
+### Cancelling and Terminating Workflows
+
+```rust
+use temporalio_client::{CancelWorkflowOptions, TerminateWorkflowOptions};
+
+// Request cancellation (workflow can handle this gracefully)
+handle.cancel(CancelWorkflowOptions::builder().reason("No longer needed").build()).await?;
+
+// Terminate immediately (workflow cannot intercept this)
+handle.terminate(TerminateWorkflowOptions::builder().reason("Emergency shutdown").build()).await?;
+```
+
+### Listing Workflows
+
+```rust
+use temporalio_client::ListWorkflowsOptions;
+use futures_util::StreamExt;
+
+let mut stream = client.list_workflows(
+    "WorkflowType = 'GreetingWorkflow'",
+    ListWorkflowsOptions::builder().limit(10).build()
+);
+
+while let Some(result) = stream.next().await {
+    let execution = result?;
+    println!("Workflow: {} ({})", execution.id(), execution.workflow_type());
+}
+```
+
+## Raw gRPC Access
+
+For operations not covered by the high-level API, access the underlying gRPC service clients
+directly:
+
+```rust
+let mut workflowf_service = client.connection().workflow_service();
+let mut operator_service = client.connection().operator_service();
+```