From 5d6b1ef78a1b006e3595449efd42941fee4460b7 Mon Sep 17 00:00:00 2001 From: Mohammad Dashti Date: Thu, 15 Oct 2026 00:22:21 -0700 Subject: [PATCH 1/3] Added the Activity owner to the stream service contract and tokens. Bridge serves Activity-owned streams over Nexus. The contract names an Activity by an optional member, so every caller built before still parses a Workflow ref, and a Workflow's token keeps its bytes. --- .../temporal/sdk/core/streams/nexus.proto | 5 + crates/sdk-core/CHANGELOG.md | 6 + .../nexus/operation_token_vectors.json | 32 ++++- .../nexus/temporal_streams.nexusrpc.yaml | 21 ++-- crates/streams/src/nexus/mod.rs | 1 + crates/streams/src/nexus/operation.rs | 112 +++++++++++++++--- crates/streams/src/nexus/wire.rs | 2 + crates/streams/tests/nexus_contract.rs | 38 ++++++ 8 files changed, 192 insertions(+), 25 deletions(-) diff --git a/crates/protos/protos/local/temporal/sdk/core/streams/nexus.proto b/crates/protos/protos/local/temporal/sdk/core/streams/nexus.proto index 225039bb0d..2bd82f3f14 100644 --- a/crates/protos/protos/local/temporal/sdk/core/streams/nexus.proto +++ b/crates/protos/protos/local/temporal/sdk/core/streams/nexus.proto @@ -73,6 +73,11 @@ message CodecWork { repeated temporal.api.common.v1.Payload payloads = 4; // Hand back in `NexusResumeRequest`. Core forgets a continuation 60 s after it asked. uint64 continuation = 5; + // The kind of the stream's owner. For a standalone Activity owner, `workflow_id` is empty and + // `activity_id` names the Activity, and the codec context has the namespace and the Activity id + // only. + StreamOwnerKind owner_kind = 6; + string activity_id = 7; } message NexusResumeRequest { diff --git a/crates/sdk-core/CHANGELOG.md b/crates/sdk-core/CHANGELOG.md index 911594ef19..30aa13ff92 100644 --- a/crates/sdk-core/CHANGELOG.md +++ b/crates/sdk-core/CHANGELOG.md @@ -205,6 +205,12 @@ relevant information. attempt that writes on after a newer one started reads as stale. Without the field the attempt is the Temporal attempt as before. `testdata/streams/activity_attempts.json` in `temporalio-streams` pins the formula for other SDKs. +* Experimental: the stream service contract's `StreamRef` gains the optional member + `activity_id`, and `kind` takes `"activity"`. An Activity's ref sends `workflow_id` as `""`, + and its `chain_run_id` is the Activity run. A stream operation token carries the kind and the + Activity id, keeps version 2, and leaves `activity_id` out of a Workflow's ref, so a Workflow's + token keeps its bytes. `operation_token_vectors.json` has Activity tokens. `CodecWork` gains + `owner_kind` and `activity_id`. The Nexus calls still refuse an Activity ref. ### Breaking Changes * Replay detects changes to the service or operation of scheduled Nexus operations, reporting diff --git a/crates/streams/nexus/operation_token_vectors.json b/crates/streams/nexus/operation_token_vectors.json index 0178de9ab0..9356df50aa 100644 --- a/crates/streams/nexus/operation_token_vectors.json +++ b/crates/streams/nexus/operation_token_vectors.json @@ -1,5 +1,5 @@ { - "comment": "Token v2 of a stream-returning Nexus operation: base64url JSON, no padding, keys sorted, non-ASCII escaped, and no chain_run_id for a ref to the newest chain. Core's encoder and every SDK's encoder write the vectors, and every decoder reads them. Decoders also read decode_only, the null chain_run_id that SDK releases before Core wrote.", + "comment": "Token v2 of a stream-returning Nexus operation: base64url JSON, no padding, keys sorted, non-ASCII escaped, no chain_run_id for a ref to the newest chain, and no activity_id for a Workflow's ref. An Activity's ref has kind activity, an empty workflow_id and its activity_id, and its chain is the Activity run. Core's encoder and every SDK's encoder write the vectors, and every decoder reads them. Decoders also read decode_only, the null chain_run_id that SDK releases before Core wrote.", "vectors": [ { "ref": { @@ -51,6 +51,29 @@ "attach": "a", "chain": "c", "token": "eyJhdHRhY2giOiJhXHUwMDdmIiwiY2hhaW4iOiJjIiwicmVmIjp7ImtpbmQiOiJ3b3JrZmxvdyIsInRvcGljIjoidFx1MDA3ZiIsIndvcmtmbG93X2lkIjoiZGVsXHUwMDdmd2YifSwidiI6Mn0" + }, + { + "ref": { + "kind": "activity", + "workflow_id": "", + "activity_id": "tool-1", + "chain_run_id": "act-run-1", + "topic": "tokens" + }, + "attach": "attach-1", + "chain": "act-run-1", + "token": "eyJhdHRhY2giOiJhdHRhY2gtMSIsImNoYWluIjoiYWN0LXJ1bi0xIiwicmVmIjp7ImFjdGl2aXR5X2lkIjoidG9vbC0xIiwiY2hhaW5fcnVuX2lkIjoiYWN0LXJ1bi0xIiwia2luZCI6ImFjdGl2aXR5IiwidG9waWMiOiJ0b2tlbnMiLCJ3b3JrZmxvd19pZCI6IiJ9LCJ2IjoyfQ" + }, + { + "ref": { + "kind": "activity", + "workflow_id": "", + "activity_id": "tool \"é\"", + "topic": "tokens" + }, + "attach": "attach-2", + "chain": "act-run-2", + "token": "eyJhdHRhY2giOiJhdHRhY2gtMiIsImNoYWluIjoiYWN0LXJ1bi0yIiwicmVmIjp7ImFjdGl2aXR5X2lkIjoidG9vbCBcIlx1MDBlOVwiIiwia2luZCI6ImFjdGl2aXR5IiwidG9waWMiOiJ0b2tlbnMiLCJ3b3JrZmxvd19pZCI6IiJ9LCJ2IjoyfQ" } ], "decode_only": [ @@ -73,6 +96,11 @@ "eyJ2IjogMSwgImF0dGFjaCI6ICJhdHRhY2gtMSIsICJjaGFpbiI6ICJjaGFpbi0xIiwgInJlZiI6IHsia2luZCI6ICJ3b3JrZmxvdyIsICJ3b3JrZmxvd19pZCI6ICJvd25lci0xIiwgInJ1bl9pZCI6IG51bGwsICJ0b3BpYyI6ICJ0b2tlbnMifX0=", "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwiZXh0cmEiOjEsInJlZiI6eyJraW5kIjoid29ya2Zsb3ciLCJ0b3BpYyI6InQiLCJ3b3JrZmxvd19pZCI6IncifSwidiI6Mn0", "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwicmVmIjp7ImN1cnNvciI6IngiLCJraW5kIjoid29ya2Zsb3ciLCJ0b3BpYyI6InQiLCJ3b3JrZmxvd19pZCI6IncifSwidiI6Mn0", - "eyJhdHRhY2giOiJhdHRhY2gtMSIsImNoYWluIjoicnVuLTEiLCJyZWYiOnsia2luZCI6IndvcmtmbG93IiwicnVuX2lkIjoicnVuLTIiLCJ0b3BpYyI6InRva2VucyIsIndvcmtmbG93X2lkIjoib3duZXItMSJ9LCJ2IjoyfQ" + "eyJhdHRhY2giOiJhdHRhY2gtMSIsImNoYWluIjoicnVuLTEiLCJyZWYiOnsia2luZCI6IndvcmtmbG93IiwicnVuX2lkIjoicnVuLTIiLCJ0b3BpYyI6InRva2VucyIsIndvcmtmbG93X2lkIjoib3duZXItMSJ9LCJ2IjoyfQ", + "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwicmVmIjp7ImtpbmQiOiJhY3Rpdml0eSIsInRvcGljIjoidCIsIndvcmtmbG93X2lkIjoiIn0sInYiOjJ9", + "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwicmVmIjp7ImFjdGl2aXR5X2lkIjoiIiwia2luZCI6ImFjdGl2aXR5IiwidG9waWMiOiJ0Iiwid29ya2Zsb3dfaWQiOiIifSwidiI6Mn0", + "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwicmVmIjp7ImFjdGl2aXR5X2lkIjoiYSIsImtpbmQiOiJhY3Rpdml0eSIsInRvcGljIjoidCIsIndvcmtmbG93X2lkIjoidyJ9LCJ2IjoyfQ", + "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwicmVmIjp7ImFjdGl2aXR5X2lkIjoiYSIsImtpbmQiOiJ3b3JrZmxvdyIsInRvcGljIjoidCIsIndvcmtmbG93X2lkIjoidyJ9LCJ2IjoyfQ", + "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwicmVmIjp7ImtpbmQiOiJuZXh1cyIsInRvcGljIjoidCIsIndvcmtmbG93X2lkIjoidyJ9LCJ2IjoyfQ" ] } diff --git a/crates/streams/nexus/temporal_streams.nexusrpc.yaml b/crates/streams/nexus/temporal_streams.nexusrpc.yaml index 1bb8e2bcfc..9396a6a484 100644 --- a/crates/streams/nexus/temporal_streams.nexusrpc.yaml +++ b/crates/streams/nexus/temporal_streams.nexusrpc.yaml @@ -80,18 +80,24 @@ $defs: kind: type: string description: >- - What owns the stream. Only "workflow" is opened in this release, and - a call with another kind is refused. + What owns the stream, "workflow" or "activity". A call with another + kind is refused. workflow_id: type: string - description: "The owning Workflow." + description: "The owning Workflow. Empty for kind activity." + activity_id: + oneOf: [{ type: string }, { type: "null" }] + description: >- + The owning standalone Activity, for kind activity. Absent or null + for kind workflow. chain_run_id: oneOf: [{ type: string }, { type: "null" }] description: >- - Names the run chain that holds this run. Absent or null names the - Workflow id's newest chain. It never stops a read at this run: a - read follows the chain across Continue-as-New and ends with the - chain. + For kind workflow, names the run chain that holds this run. Absent + or null names the Workflow id's newest chain. It never stops a read + at this run: a read follows the chain across Continue-as-New and + ends with the chain. For kind activity, the Activity run. Absent or + null names the Activity id's newest run when the read starts. topic: type: string description: "The topic on the owner's stream." @@ -421,5 +427,6 @@ $defs: description: >- The first run of the run chain the start attached to, so a cancel detaches from it even after the Workflow id moved on to a new chain. + For an Activity owner, the Activity run. required: [v, ref, attach, chain] additionalProperties: false diff --git a/crates/streams/src/nexus/mod.rs b/crates/streams/src/nexus/mod.rs index 39df9bf21c..33f5899823 100644 --- a/crates/streams/src/nexus/mod.rs +++ b/crates/streams/src/nexus/mod.rs @@ -668,6 +668,7 @@ impl NexusCalls { workflow_id: workflow_id.to_string(), payloads, continuation, + ..Default::default() })), } } diff --git a/crates/streams/src/nexus/operation.rs b/crates/streams/src/nexus/operation.rs index 049edb3bc4..30993a3e76 100644 --- a/crates/streams/src/nexus/operation.rs +++ b/crates/streams/src/nexus/operation.rs @@ -176,7 +176,7 @@ pub struct OperationToken { /// The start's request id, which the attach was keyed by. pub attach_request_id: String, /// The first run of the chain the start attached to, so a cancel detaches from that chain - /// even after the Workflow id moved on to a new one. + /// even after the Workflow id moved on to a new one. For an Activity owner, the Activity run. pub chain_first_run_id: String, } @@ -195,6 +195,9 @@ struct TokenBody { #[derive(Serialize, Deserialize)] #[serde(deny_unknown_fields)] struct TokenRef { + // A Workflow's ref has none, so its tokens keep the bytes they had before the Activity kind. + #[serde(default, skip_serializing_if = "Option::is_none")] + activity_id: Option, // A ref to the newest chain has none, as the generated SDK writers leave an unset member out. // SDK releases before Core wrote null, which reads the same. #[serde(default, skip_serializing_if = "Option::is_none")] @@ -204,7 +207,28 @@ struct TokenRef { workflow_id: String, } -const WORKFLOW_KIND: &str = "workflow"; +/// The `kind` of a contract `StreamRef`, by Core's owner kind. +const KINDS: [(&str, StreamOwnerKind); 2] = [ + ("workflow", StreamOwnerKind::Workflow), + ("activity", StreamOwnerKind::Activity), +]; + +/// The owner kind a contract `kind` names, or `None` for a kind no release opens. +pub(crate) fn owner_kind(kind: &str) -> Option { + KINDS + .iter() + .find(|(name, _)| *name == kind) + .map(|(_, owner_kind)| *owner_kind) +} + +/// The contract `kind` of an owner kind. Any kind but the Activity one is a Workflow, as an +/// unset kind is in a `ChainId`. +pub(crate) fn kind_name(owner_kind: i32) -> &'static str { + KINDS + .iter() + .find(|(_, kind)| *kind as i32 == owner_kind) + .map_or(KINDS[0].0, |(name, _)| name) +} impl OperationToken { /// The token's text: base64url JSON with sorted keys and no padding. @@ -213,8 +237,10 @@ impl OperationToken { attach: self.attach_request_id.clone(), chain: self.chain_first_run_id.clone(), stream: TokenRef { + activity_id: (self.stream.owner_kind == StreamOwnerKind::Activity as i32) + .then(|| self.stream.activity_id.clone()), chain_run_id: (!self.stream.run_id.is_empty()).then(|| self.stream.run_id.clone()), - kind: WORKFLOW_KIND.to_string(), + kind: kind_name(self.stream.owner_kind).to_string(), topic: self.stream.topic.clone(), workflow_id: self.stream.workflow_id.clone(), }, @@ -243,17 +269,38 @@ impl OperationToken { } let body: TokenBody = serde_json::from_value(version).map_err(|error| refuse(&error.to_string()))?; - if body.stream.kind != WORKFLOW_KIND { - return Err(refuse("the stream's owner is not a Workflow")); - } + let owner_kind = match owner_kind(&body.stream.kind) { + Some(StreamOwnerKind::Activity) => { + if body + .stream + .activity_id + .as_deref() + .unwrap_or_default() + .is_empty() + || !body.stream.workflow_id.is_empty() + { + return Err(refuse( + "an Activity's stream names its Activity id and no Workflow id", + )); + } + StreamOwnerKind::Activity + } + Some(_) if body.stream.activity_id.is_none() => StreamOwnerKind::Workflow, + Some(_) => return Err(refuse("a Workflow's stream names no Activity id")), + None => { + return Err(refuse( + "the stream's owner is neither a Workflow nor an Activity", + )); + } + }; Ok(Self { stream: StreamAddress { namespace: namespace.to_string(), - owner_kind: StreamOwnerKind::Workflow as i32, + owner_kind: owner_kind as i32, workflow_id: body.stream.workflow_id, run_id: body.stream.chain_run_id.unwrap_or_default(), topic: body.stream.topic, - ..Default::default() + activity_id: body.stream.activity_id.unwrap_or_default(), }, attach_request_id: body.attach, chain_first_run_id: body.chain, @@ -262,12 +309,7 @@ impl OperationToken { /// The chain the start attached to. pub fn chain(&self) -> ChainId { - ChainId { - namespace: self.stream.namespace.clone(), - workflow_id: self.stream.workflow_id.clone(), - first_run_id: self.chain_first_run_id.clone(), - ..Default::default() - } + crate::handle::chain_of(&self.stream, &self.chain_first_run_id) } } @@ -948,11 +990,11 @@ mod tests { OperationToken { stream: StreamAddress { namespace: "ns".to_string(), - owner_kind: StreamOwnerKind::Workflow as i32, + owner_kind: owner_kind(&vector.stream.kind).unwrap() as i32, workflow_id: vector.stream.workflow_id.clone(), run_id: vector.stream.chain_run_id.clone().unwrap_or_default(), topic: vector.stream.topic.clone(), - ..Default::default() + activity_id: vector.stream.activity_id.clone().unwrap_or_default(), }, attach_request_id: vector.attach.clone(), chain_first_run_id: vector.chain.clone(), @@ -986,6 +1028,44 @@ mod tests { } } + #[test] + fn an_activity_token_names_the_activity_run_as_its_chain() { + let vectors = vectors(); + let vector = vectors + .vectors + .iter() + .find(|vector| vector.stream.kind == "activity") + .unwrap(); + let token = OperationToken::decode("ns", &vector.token).unwrap(); + assert_eq!(token.stream.owner_kind, StreamOwnerKind::Activity as i32); + assert_eq!( + token.chain(), + ChainId { + namespace: "ns".to_string(), + first_run_id: vector.chain.clone(), + owner_kind: StreamOwnerKind::Activity as i32, + activity_id: vector.stream.activity_id.clone().unwrap(), + ..Default::default() + } + ); + // A Workflow's token keeps the bytes it had, with no `activity_id` member. + let workflow = vectors + .vectors + .iter() + .find(|vector| vector.stream.kind == "workflow") + .unwrap(); + assert_eq!(token_of(workflow).chain().owner_kind, 0); + assert!( + !String::from_utf8( + base64::engine::general_purpose::URL_SAFE_NO_PAD + .decode(&workflow.token) + .unwrap() + ) + .unwrap() + .contains("activity_id") + ); + } + #[test] fn a_token_from_before_core_still_decodes() { for vector in vectors().decode_only { diff --git a/crates/streams/src/nexus/wire.rs b/crates/streams/src/nexus/wire.rs index 0273160e4b..0ab855655c 100644 --- a/crates/streams/src/nexus/wire.rs +++ b/crates/streams/src/nexus/wire.rs @@ -57,6 +57,8 @@ pub(crate) struct StreamRef { pub(crate) kind: String, pub(crate) workflow_id: String, #[serde(default)] + pub(crate) activity_id: Option, + #[serde(default)] pub(crate) chain_run_id: Option, pub(crate) topic: String, } diff --git a/crates/streams/tests/nexus_contract.rs b/crates/streams/tests/nexus_contract.rs index 4eea856aff..4f6b5dfc45 100644 --- a/crates/streams/tests/nexus_contract.rs +++ b/crates/streams/tests/nexus_contract.rs @@ -47,6 +47,7 @@ fn full_input(contract: &Value, name: &str, workflow_id: &str) -> Value { (_, "stream") => { let mut stream = stream(workflow_id, "out"); stream["chain_run_id"] = Value::Null; + stream["activity_id"] = Value::Null; stream } ("AppendInput", "producer_id") => json!("p"), @@ -194,6 +195,43 @@ fn a_replay_range_names_what_read_range_takes() { assert!(!required(model(&contract, "ReadInput")).contains(&"floor_holder".to_string())); } +#[test] +fn a_stream_ref_names_an_activity_owner_by_an_optional_member() { + // Every caller built before the Activity kind still parses a Workflow ref, since the member + // is optional and `workflow_id` stays required. + let contract = contract(); + let stream_ref = model(&contract, "StreamRef"); + assert_eq!( + stream_ref["properties"]["activity_id"]["oneOf"], + json!([{ "type": "string" }, { "type": "null" }]) + ); + assert_eq!( + stream_ref["properties"]["activity_id"]["oneOf"], + stream_ref["properties"]["chain_run_id"]["oneOf"] + ); + let mut required = required(stream_ref); + required.sort(); + assert_eq!(required, ["kind", "topic", "workflow_id"]); +} + +#[tokio::test] +async fn an_activity_ref_matches_the_contract() { + let calls = service(memory(), NexusOptions::default()); + let input = json!({ + "stream": { + "kind": "activity", + "workflow_id": "", + "activity_id": "tool-1", + "chain_run_id": "act-run-1", + "topic": "out", + }, + }); + let step = calls.read(call(input)).await; + if let Err(failure) = drive(&calls, step, Codec::Sealing).await { + assert!(!is_contract_mistake(&failure), "{}", failure.message); + } +} + #[test] fn the_operation_token_model_is_closed_and_versioned() { // The generated token helpers refuse a token model that isn't closed or that lacks a From b10ac0531265c32c0ccd806aab06ff3d40191516 Mon Sep 17 00:00:00 2001 From: Mohammad Dashti Date: Thu, 15 Oct 2026 00:27:15 -0700 Subject: [PATCH 2/3] Served streams that a standalone Activity owns over Nexus. Every Bridge path keys on Core's address and chain, which already take the Activity kind. A wake token now matches its read on the whole owner, since every Activity ref has the same empty Workflow id. --- crates/sdk-core/CHANGELOG.md | 7 + crates/streams/src/handle.rs | 4 +- crates/streams/src/nexus/mod.rs | 81 ++++----- crates/streams/src/nexus/operation.rs | 69 +++++++- crates/streams/tests/nexus_service.rs | 200 +++++++++++++++++++++- crates/streams/tests/nexus_support/mod.rs | 10 ++ 6 files changed, 316 insertions(+), 55 deletions(-) diff --git a/crates/sdk-core/CHANGELOG.md b/crates/sdk-core/CHANGELOG.md index 30aa13ff92..8f671cc9e5 100644 --- a/crates/sdk-core/CHANGELOG.md +++ b/crates/sdk-core/CHANGELOG.md @@ -211,6 +211,13 @@ relevant information. Activity id, keeps version 2, and leaves `activity_id` out of a Workflow's ref, so a Workflow's token keeps its bytes. `operation_token_vectors.json` has Activity tokens. `CodecWork` gains `owner_kind` and `activity_id`. The Nexus calls still refuse an Activity ref. +* Experimental: the stream service's Nexus calls serve streams that a standalone Activity owns. + `append`, `read`, `read_range`, `latest_only`, the floor holder, `AttachCaller` with + `wake_after_counter`, `DetachCaller` and the read-first wake all take an Activity ref. A read's + `wake_token` must name the read's owner kind, Workflow id, Activity id and topic, so a token of + one Activity never wakes another Activity's reader on the same topic. `CodecWork` names the + Activity, so lang's codec context is the namespace and the Activity id. A ref of kind + `activity` with a Workflow id, or of kind `workflow` with an Activity id, is a bad request. ### Breaking Changes * Replay detects changes to the service or operation of scheduled Nexus operations, reporting diff --git a/crates/streams/src/handle.rs b/crates/streams/src/handle.rs index 9aabe6f9ff..014d25ebd7 100644 --- a/crates/streams/src/handle.rs +++ b/crates/streams/src/handle.rs @@ -447,8 +447,8 @@ impl Streams { Ok(described) if described.first_run_id != first_run_id => { return Err(StreamError::cursor(format!( "the read state names run {first_run_id:?}, which doesn't start a run chain \ - of Workflow {:?}", - stream.workflow_id + of {}", + key.label() ))); } // A chain Temporal no longer holds leaves nothing another chain's reader could diff --git a/crates/streams/src/nexus/mod.rs b/crates/streams/src/nexus/mod.rs index 33f5899823..d31b22aa80 100644 --- a/crates/streams/src/nexus/mod.rs +++ b/crates/streams/src/nexus/mod.rs @@ -272,14 +272,7 @@ impl NexusCalls { if finish { return self.finish(work, Vec::new()).await; } - self.ask_codec( - work, - bytes, - true, - &call.namespace, - &input.stream.workflow_id, - parsed, - ) + self.ask_codec(work, bytes, true, &call.namespace, &input.stream, parsed) } /// Serves the `read` operation: the records after the caller's cursor, waiting for some. @@ -315,8 +308,12 @@ impl NexusCalls { let floor_holder = input.floor_holder.unwrap_or_default(); let wake = match &input.wake_token { Some(token) => match OperationToken::decode(&call.namespace, token) { + // A token of another owner with the same topic must not wake this reader, and + // every Activity's ref has the same empty Workflow id. Ok(token) - if token.stream.workflow_id == address.workflow_id + if token.stream.owner_kind == address.owner_kind + && token.stream.workflow_id == address.workflow_id + && token.stream.activity_id == address.activity_id && token.stream.topic == address.topic => { Some(token) @@ -449,14 +446,7 @@ impl NexusCalls { if payloads.is_empty() { return self.finish(work, Vec::new()).await; } - self.ask_codec( - work, - bytes, - false, - &call.namespace, - &input.stream.workflow_id, - payloads, - ) + self.ask_codec(work, bytes, false, &call.namespace, &input.stream, payloads) } /// Asks the notifier to wake the operation callback that `token` names once the stream moves @@ -476,12 +466,7 @@ impl NexusCalls { })?; client .wait_callback( - crate::proto::ChainId { - namespace: address.namespace.clone(), - workflow_id: address.workflow_id.clone(), - first_run_id: token.chain_first_run_id.clone(), - ..Default::default() - }, + crate::handle::chain_of(address, &token.chain_first_run_id), address.topic.clone(), token.attach_request_id.clone(), read.response.wake_after, @@ -565,14 +550,7 @@ impl NexusCalls { if payloads.is_empty() { return self.finish(work, Vec::new()).await; } - self.ask_codec( - work, - bytes, - false, - &call.namespace, - &input.stream.workflow_id, - payloads, - ) + self.ask_codec(work, bytes, false, &call.namespace, &input.stream, payloads) } /// `address` without its run, and a state that names the chain the run picked. A state the @@ -629,7 +607,7 @@ impl NexusCalls { bytes: usize, encode: bool, namespace: &str, - workflow_id: &str, + stream: &StreamRef, payloads: Vec, ) -> NexusStep { let continuation = self.next.fetch_add(1, Ordering::Relaxed); @@ -665,10 +643,13 @@ impl NexusCalls { step: Some(nexus_step::Step::Codec(CodecWork { encode, namespace: namespace.to_string(), - workflow_id: workflow_id.to_string(), + workflow_id: stream.workflow_id.clone(), payloads, continuation, - ..Default::default() + // The address check already refused any other kind. + owner_kind: operation::owner_kind(&stream.kind).unwrap_or(StreamOwnerKind::Workflow) + as i32, + activity_id: stream.activity_id.clone().unwrap_or_default(), })), } } @@ -1089,31 +1070,45 @@ fn carried_state(state: Option) -> Result, Box> { /// The stream address a call names. An owner kind this release can't open is refused before any /// codec work. fn address(namespace: &str, stream: &StreamRef) -> Result> { - if stream.kind != "workflow" { + let Some(owner_kind) = operation::owner_kind(&stream.kind) else { return Err(Box::new(failure::of_stream(&StreamError::unsupported( format!( - "this release opens streams of Workflows only, not of kind {}", + "this release opens streams of Workflows and standalone Activities only, not of \ + kind {}", failure::named(&stream.kind) ), )))); - } + }; if let Err(reason) = temporalio_common::streams::check_topic(&stream.topic) { return Err(Box::new(failure::input_mistake(failure::without_values( &reason, )))); } - if stream.workflow_id.is_empty() { - return Err(Box::new(failure::input_mistake( - "a stream needs its owner's Workflow id", - ))); + let activity_id = stream.activity_id.clone().unwrap_or_default(); + let mistake = match owner_kind { + StreamOwnerKind::Activity if activity_id.is_empty() => { + Some("a stream that an Activity owns needs its owner's Activity id") + } + StreamOwnerKind::Activity if !stream.workflow_id.is_empty() => { + Some("a stream that an Activity owns names an empty Workflow id") + } + StreamOwnerKind::Activity => None, + _ if stream.workflow_id.is_empty() => Some("a stream needs its owner's Workflow id"), + _ if stream.activity_id.is_some() => { + Some("a stream that a Workflow owns names no Activity id") + } + _ => None, + }; + if let Some(mistake) = mistake { + return Err(Box::new(failure::input_mistake(mistake))); } Ok(StreamAddress { namespace: namespace.to_string(), - owner_kind: StreamOwnerKind::Workflow as i32, + owner_kind: owner_kind as i32, workflow_id: stream.workflow_id.clone(), run_id: stream.chain_run_id.clone().unwrap_or_default(), topic: stream.topic.clone(), - ..Default::default() + activity_id, }) } diff --git a/crates/streams/src/nexus/operation.rs b/crates/streams/src/nexus/operation.rs index 30993a3e76..177c02e95e 100644 --- a/crates/streams/src/nexus/operation.rs +++ b/crates/streams/src/nexus/operation.rs @@ -136,16 +136,26 @@ async fn detach( /// crosses as the caller's input mistake. fn checked(stream: Option<&StreamAddress>) -> StreamResult<&StreamAddress> { let stream = stream.ok_or_else(|| bad_input("an attach needs its stream"))?; - if stream.owner_kind != StreamOwnerKind::Workflow as i32 { - return Err(StreamError::unsupported(format!( - "this release opens streams of Workflows only, not owner kind {}", - stream.owner_kind + let (owner_id, other_id, kind) = match StreamOwnerKind::try_from(stream.owner_kind) { + Ok(StreamOwnerKind::Workflow) => (&stream.workflow_id, &stream.activity_id, "Workflow"), + Ok(StreamOwnerKind::Activity) => (&stream.activity_id, &stream.workflow_id, "Activity"), + _ => { + return Err(StreamError::unsupported(format!( + "this release opens streams of Workflows and standalone Activities only, not \ + owner kind {}", + stream.owner_kind + ))); + } + }; + if stream.namespace.is_empty() || owner_id.is_empty() { + return Err(bad_input(&format!( + "a stream needs its namespace and its owner's {kind} id" ))); } - if stream.namespace.is_empty() || stream.workflow_id.is_empty() { - return Err(bad_input( - "a stream needs its namespace and its owner's Workflow id", - )); + if !other_id.is_empty() { + return Err(bad_input(&format!( + "a stream that a {kind} owns names only its {kind} id" + ))); } // The topic is the caller's own value, so the message names the rule and not the topic. temporalio_common::streams::check_topic(&stream.topic) @@ -612,6 +622,49 @@ mod tests { ); } + #[tokio::test] + async fn an_activity_stream_start_attaches_waits_and_detaches_on_the_activity_run() { + let setup = setup(); + let activity = StreamAddress { + owner_kind: StreamOwnerKind::Activity as i32, + workflow_id: String::new(), + activity_id: "tool-1".to_string(), + ..stream("") + }; + let start = AttachCallerRequest { + stream: Some(activity.clone()), + wake_after_counter: Some(0), + ..attach_request("temporal://system") + }; + let token = attach(&setup.service, start).await.unwrap(); + let run = ChainId { + namespace: "default".to_string(), + first_run_id: "chain-1".to_string(), + owner_kind: StreamOwnerKind::Activity as i32, + activity_id: "tool-1".to_string(), + ..Default::default() + }; + assert_eq!(setup.notifier.attached.lock().unwrap()[0].chain, run); + assert_eq!(setup.notifier.waits.lock().unwrap()[0].0, run); + let decoded = OperationToken::decode("default", &token).unwrap(); + assert_eq!(decoded.stream, activity); + assert_eq!(decoded.chain(), run); + detach(&setup.service, &token).await.unwrap(); + assert_eq!(setup.notifier.detached.lock().unwrap()[0].0, run); + // An Activity's address names no Workflow id. + let refused = AttachCallerRequest { + stream: Some(StreamAddress { + workflow_id: "owner-1".to_string(), + ..activity + }), + ..attach_request("temporal://system") + }; + assert_eq!( + attach(&setup.service, refused).await.unwrap_err().kind, + "BAD_REQUEST" + ); + } + #[tokio::test] async fn a_start_attaches_an_idle_callback_and_announces_nothing() { let setup = setup(); diff --git a/crates/streams/tests/nexus_service.rs b/crates/streams/tests/nexus_service.rs index 893a18daec..d210094293 100644 --- a/crates/streams/tests/nexus_service.rs +++ b/crates/streams/tests/nexus_service.rs @@ -159,6 +159,22 @@ fn operation_token(wf: &str) -> String { .encode() } +/// The token of Activity `id`'s stream operation, attached as `attach-1` on its run `run-1`. +fn activity_operation_token(id: &str) -> String { + OperationToken { + stream: StreamAddress { + namespace: NAMESPACE.to_string(), + owner_kind: StreamOwnerKind::Activity as i32, + activity_id: id.to_string(), + topic: TOPIC.to_string(), + ..Default::default() + }, + attach_request_id: "attach-1".to_string(), + chain_first_run_id: "run-1".to_string(), + } + .encode() +} + fn waking(wf: &str, after: &str) -> Value { let mut input = read_input(wf, after); input["wake_token"] = json!(operation_token(wf)); @@ -533,7 +549,7 @@ mod cases { let calls = service(store, NexusOptions::default()); let refused = read( &calls, - json!({"stream": {"kind": "activity", "workflow_id": "wf", "topic": "t"}}), + json!({"stream": {"kind": "nexus", "workflow_id": "wf", "topic": "t"}}), ) .await .unwrap_err(); @@ -543,7 +559,137 @@ mod cases { kind_of(&refused), ("NOT_IMPLEMENTED", false, "StreamUnsupportedError") ); - assert!(refused.message.contains("activity"), "{}", refused.message); + assert!(refused.message.contains("nexus"), "{}", refused.message); + // An Activity's ref names the Activity and an empty Workflow id, and a Workflow's ref no + // Activity. + for stream in [ + json!({"kind": "activity", "workflow_id": "wf", "activity_id": "a", "topic": "t"}), + json!({"kind": "activity", "workflow_id": "", "topic": "t"}), + json!({"kind": "activity", "workflow_id": "", "activity_id": "", "topic": "t"}), + json!({"kind": "workflow", "workflow_id": "wf", "activity_id": "a", "topic": "t"}), + ] { + let refused = read(&calls, json!({ "stream": stream.clone() })) + .await + .unwrap_err(); + assert_eq!(kind_of(&refused).0, "BAD_REQUEST", "{stream}"); + } + } + + pub(crate) async fn an_activity_stream_appends_and_reads_apart_from_a_workflow( + store: Arc, + ) { + let calls = service(store, NexusOptions::default()); + let id = workflow(); + let activity = |texts: &[&str], sequence: i64| { + let mut input = append_input(&id, "p", 1, sequence, texts); + input["stream"] = activity_stream(&id, TOPIC); + input + }; + append(&calls, activity(&["one", "two"], 1)).await.unwrap(); + // A Workflow with the same id owns another stream. + write(&calls, &id, 1, &["workflow"]).await; + let answer = read(&calls, json!({"stream": activity_stream(&id, TOPIC)})) + .await + .unwrap(); + assert_eq!(texts(&answer), ["one", "two"]); + assert_eq!(texts(&read_after(&calls, &id, "").await), ["workflow"]); + let latest = read( + &calls, + json!({"stream": activity_stream(&id, TOPIC), "latest_only": true}), + ) + .await + .unwrap(); + assert_eq!(latest["next_token"], answer["next_token"]); + // A cursor of the Activity's stream is not one of the Workflow's. + let refused = read(&calls, read_input(&id, token(&answer))) + .await + .unwrap_err(); + assert_eq!(kind_of(&refused).2, "StreamCursorError"); + } + + pub(crate) async fn an_activity_read_says_done_once_the_run_ends(store: Arc) { + let id = workflow(); + let mut input = append_input(&id, "p", 1, 1, &["one"]); + input["stream"] = activity_stream(&id, TOPIC); + append(&service(store.clone(), NexusOptions::default()), input) + .await + .unwrap(); + let ended = NexusCalls::new( + Arc::new(Streams::new( + store, + Arc::new(Ended), + StreamsOptions::default(), + )), + NexusOptions::default(), + ); + let mut input = json!({"stream": activity_stream(&id, TOPIC), "wait_ms": 2000}); + let mut seen = vec![]; + for _ in 0..10 { + let answer = read(&ended, input.clone()).await.unwrap(); + seen.extend(texts(&answer)); + if answer["done"] == true { + assert_eq!(seen, ["one"]); + return; + } + input["after_token"] = answer["next_token"].clone(); + input["state"] = answer["state"].clone(); + } + panic!("the read never ended"); + } + + pub(crate) async fn a_wake_token_of_another_activity_is_refused(store: Arc) { + let waker = Arc::new(Waker::default()); + let calls = service(store, NexusOptions::default()).with_callers(waker.clone()); + let id = workflow(); + // Every Activity's ref has the same empty Workflow id, so only the Activity id tells + // the two streams apart. + for (stream, token) in [ + ( + activity_stream(&id, TOPIC), + activity_operation_token("other"), + ), + (activity_stream(&id, TOPIC), operation_token("")), + (stream(&id, TOPIC), activity_operation_token(&id)), + ] { + let input = json!({"stream": stream, "wake_token": token}); + let refused = read(&calls, input).await.unwrap_err(); + assert_eq!(kind_of(&refused).0, "BAD_REQUEST", "{stream}"); + } + assert!(waker.waits.lock().unwrap().is_empty()); + } + + pub(crate) async fn an_empty_activity_read_wakes_its_operation_on_the_activity_run( + store: Arc, + ) { + let waker = Arc::new(Waker::default()); + let calls = service(store, NexusOptions::default()).with_callers(waker.clone()); + let id = workflow(); + let mut input = append_input(&id, "p", 1, 1, &["one"]); + input["stream"] = activity_stream(&id, TOPIC); + let last = append(&calls, input).await.unwrap()["cursor"].clone(); + let input = json!({ + "stream": activity_stream(&id, TOPIC), + "after_token": last, + "wake_token": activity_operation_token(&id), + }); + let caught_up = read(&calls, input).await.unwrap(); + assert!(records(&caught_up).is_empty()); + let waits = waker.waits.lock().unwrap().clone(); + let [(chain, topic, request_id, after)] = waits.as_slice() else { + panic!("one wait, not {waits:?}"); + }; + assert_eq!( + chain, + &ChainId { + namespace: NAMESPACE.to_string(), + first_run_id: "run-1".to_string(), + owner_kind: StreamOwnerKind::Activity as i32, + activity_id: id.clone(), + ..Default::default() + } + ); + assert_eq!((topic.as_str(), request_id.as_str()), (TOPIC, "attach-1")); + assert!(*after > 0); } pub(crate) async fn a_read_says_done_once_the_owner_ends(store: Arc) { @@ -915,6 +1061,10 @@ macro_rules! all_cases { a_record_that_lands_before_the_wait_is_in_the_answer, a_positions_reader_waits_and_rereads_too, a_wake_token_of_another_stream_is_refused, + an_activity_stream_appends_and_reads_apart_from_a_workflow, + an_activity_read_says_done_once_the_run_ends, + a_wake_token_of_another_activity_is_refused, + an_empty_activity_read_wakes_its_operation_on_the_activity_run, ); }; } @@ -1385,3 +1535,49 @@ async fn a_range_from_a_trimmed_start_is_lost_on_redis() { refused.message ); } + +#[tokio::test] +async fn an_activity_range_replays_and_names_only_the_activity_run() { + let calls = service(memory(), NexusOptions::default()); + let id = workflow(); + let mut input = append_input(&id, "p", 1, 1, &["one", "two"]); + input["stream"] = activity_stream(&id, TOPIC); + append(&calls, input).await.unwrap(); + let answer = read( + &calls, + json!({"stream": activity_stream(&id, TOPIC), "floor_holder": HOLDER}), + ) + .await + .unwrap(); + assert_eq!(answer["replay"]["chain_first_run_id"], "run-1"); + let replay = replay_input(activity_stream(&id, TOPIC), &answer, Value::Null); + let replayed = read_range(&calls, replay.clone()).await.unwrap(); + assert_eq!(replayed["records"], answer["records"]); + let mut other_run = replay; + other_run["chain_first_run_id"] = json!("run-9"); + let refused = read_range(&calls, other_run).await.unwrap_err(); + assert_eq!( + kind_of(&refused), + ("BAD_REQUEST", false, "StreamCursorError") + ); +} + +#[tokio::test] +async fn an_activity_streams_codec_work_names_the_activity() { + let calls = service(memory(), NexusOptions::default()); + let mut input = append_input("unused", "p", 1, 1, &["one"]); + input["stream"] = activity_stream("tool-1", TOPIC); + let step = calls.append(call(input)).await; + let Some(temporalio_streams::proto::nexus_step::Step::Codec(work)) = step.step else { + panic!("an append asks for codec work first, not {step:?}"); + }; + assert_eq!( + ( + work.namespace.as_str(), + work.owner_kind, + work.workflow_id.as_str(), + work.activity_id.as_str() + ), + (NAMESPACE, StreamOwnerKind::Activity as i32, "", "tool-1") + ); +} diff --git a/crates/streams/tests/nexus_support/mod.rs b/crates/streams/tests/nexus_support/mod.rs index 091e57dfba..5d6a7869e0 100644 --- a/crates/streams/tests/nexus_support/mod.rs +++ b/crates/streams/tests/nexus_support/mod.rs @@ -189,6 +189,16 @@ pub(crate) fn replay_input(stream: Value, answer: &Value, state: Value) -> Value }) } +/// A stream reference to `topic` of standalone Activity `activity_id`, on its newest run. +pub(crate) fn activity_stream(activity_id: &str, topic: &str) -> Value { + serde_json::json!({ + "kind": "activity", + "workflow_id": "", + "activity_id": activity_id, + "topic": topic, + }) +} + /// A stream reference to `topic` of Workflow `workflow_id`. pub(crate) fn stream(workflow_id: &str, topic: &str) -> Value { serde_json::json!({"kind": "workflow", "workflow_id": workflow_id, "topic": topic}) From 7d2129a1abb0524831dc9e2247097c9030519a0a Mon Sep 17 00:00:00 2001 From: Mohammad Dashti Date: Thu, 15 Oct 2026 07:14:32 -0700 Subject: [PATCH 3/3] Served Workflow Activity streams over Nexus. Callers in other namespaces reach a tool stream only through Nexus. The contract takes the kind with no new member, and the scheduling run stays in every address and token, since an Activity id repeats in each run. --- .../temporal/sdk/core/streams/nexus.proto | 3 +- crates/sdk-core/CHANGELOG.md | 7 ++ .../nexus/operation_token_vectors.json | 32 ++++- .../nexus/temporal_streams.nexusrpc.yaml | 20 +-- crates/streams/src/handle.rs | 10 ++ crates/streams/src/nexus/mod.rs | 38 ++++-- crates/streams/src/nexus/operation.rs | 108 +++++++++++++++- crates/streams/tests/nexus_contract.rs | 24 ++++ crates/streams/tests/nexus_service.rs | 115 ++++++++++++++++++ crates/streams/tests/nexus_support/mod.rs | 17 +++ 10 files changed, 352 insertions(+), 22 deletions(-) diff --git a/crates/protos/protos/local/temporal/sdk/core/streams/nexus.proto b/crates/protos/protos/local/temporal/sdk/core/streams/nexus.proto index 2bd82f3f14..9cbf474ec4 100644 --- a/crates/protos/protos/local/temporal/sdk/core/streams/nexus.proto +++ b/crates/protos/protos/local/temporal/sdk/core/streams/nexus.proto @@ -75,7 +75,8 @@ message CodecWork { uint64 continuation = 5; // The kind of the stream's owner. For a standalone Activity owner, `workflow_id` is empty and // `activity_id` names the Activity, and the codec context has the namespace and the Activity id - // only. + // only. For a Workflow Activity owner, both are set, and the codec context has the namespace, + // the Activity id and the Workflow id. StreamOwnerKind owner_kind = 6; string activity_id = 7; } diff --git a/crates/sdk-core/CHANGELOG.md b/crates/sdk-core/CHANGELOG.md index e685f0c8f0..57d9c1e867 100644 --- a/crates/sdk-core/CHANGELOG.md +++ b/crates/sdk-core/CHANGELOG.md @@ -222,6 +222,13 @@ relevant information. one Activity never wakes another Activity's reader on the same topic. `CodecWork` names the Activity, so lang's codec context is the namespace and the Activity id. A ref of kind `activity` with a Workflow id, or of kind `workflow` with an Activity id, is a bad request. +* Experimental: the stream service contract and its Nexus calls serve Workflow Activity streams. + `StreamRef.kind` takes `"workflow_activity"`, with `workflow_id`, `activity_id` and the + scheduling run as `chain_run_id`, all required, and no new member. A stream operation token + carries the kind and the Activity id, keeps version 2, and its chain is the scheduling run. + Reads and replays keep the run, since it names the stream. A carried state must name that run. + A read's `wake_token` must also name the read's run for this kind. `CodecWork` names the + Workflow and the Activity. `operation_token_vectors.json` has Workflow Activity tokens. * Experimental: the Activity attempt key is `started_unix_ms << 11 | min(attempt, 2047)`, so it fits 53 bits and a JSON number holds it exactly. The Nexus contract's models and JavaScript refused the earlier 16-bit form. A start time from May 2109 on is refused. The vector file diff --git a/crates/streams/nexus/operation_token_vectors.json b/crates/streams/nexus/operation_token_vectors.json index 9356df50aa..2dbd0cf16d 100644 --- a/crates/streams/nexus/operation_token_vectors.json +++ b/crates/streams/nexus/operation_token_vectors.json @@ -1,5 +1,5 @@ { - "comment": "Token v2 of a stream-returning Nexus operation: base64url JSON, no padding, keys sorted, non-ASCII escaped, no chain_run_id for a ref to the newest chain, and no activity_id for a Workflow's ref. An Activity's ref has kind activity, an empty workflow_id and its activity_id, and its chain is the Activity run. Core's encoder and every SDK's encoder write the vectors, and every decoder reads them. Decoders also read decode_only, the null chain_run_id that SDK releases before Core wrote.", + "comment": "Token v2 of a stream-returning Nexus operation: base64url JSON, no padding, keys sorted, non-ASCII escaped, no chain_run_id for a ref to the newest chain, and no activity_id for a Workflow's ref. An Activity's ref has kind activity, an empty workflow_id and its activity_id, and its chain is the Activity run. A Workflow Activity's ref has kind workflow_activity, its workflow_id, its activity_id and the scheduling run as chain_run_id, which is also its chain. Core's encoder and every SDK's encoder write the vectors, and every decoder reads them. Decoders also read decode_only, the null chain_run_id that SDK releases before Core wrote.", "vectors": [ { "ref": { @@ -74,6 +74,30 @@ "attach": "attach-2", "chain": "act-run-2", "token": "eyJhdHRhY2giOiJhdHRhY2gtMiIsImNoYWluIjoiYWN0LXJ1bi0yIiwicmVmIjp7ImFjdGl2aXR5X2lkIjoidG9vbCBcIlx1MDBlOVwiIiwia2luZCI6ImFjdGl2aXR5IiwidG9waWMiOiJ0b2tlbnMiLCJ3b3JrZmxvd19pZCI6IiJ9LCJ2IjoyfQ" + }, + { + "ref": { + "kind": "workflow_activity", + "workflow_id": "agent", + "activity_id": "tool-42", + "chain_run_id": "run-1", + "topic": "tokens" + }, + "attach": "attach-3", + "chain": "run-1", + "token": "eyJhdHRhY2giOiJhdHRhY2gtMyIsImNoYWluIjoicnVuLTEiLCJyZWYiOnsiYWN0aXZpdHlfaWQiOiJ0b29sLTQyIiwiY2hhaW5fcnVuX2lkIjoicnVuLTEiLCJraW5kIjoid29ya2Zsb3dfYWN0aXZpdHkiLCJ0b3BpYyI6InRva2VucyIsIndvcmtmbG93X2lkIjoiYWdlbnQifSwidiI6Mn0" + }, + { + "ref": { + "kind": "workflow_activity", + "workflow_id": "agent \"é\"", + "activity_id": "1", + "chain_run_id": "run-2", + "topic": "out" + }, + "attach": "attach-4", + "chain": "run-2", + "token": "eyJhdHRhY2giOiJhdHRhY2gtNCIsImNoYWluIjoicnVuLTIiLCJyZWYiOnsiYWN0aXZpdHlfaWQiOiIxIiwiY2hhaW5fcnVuX2lkIjoicnVuLTIiLCJraW5kIjoid29ya2Zsb3dfYWN0aXZpdHkiLCJ0b3BpYyI6Im91dCIsIndvcmtmbG93X2lkIjoiYWdlbnQgXCJcdTAwZTlcIiJ9LCJ2IjoyfQ" } ], "decode_only": [ @@ -101,6 +125,10 @@ "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwicmVmIjp7ImFjdGl2aXR5X2lkIjoiIiwia2luZCI6ImFjdGl2aXR5IiwidG9waWMiOiJ0Iiwid29ya2Zsb3dfaWQiOiIifSwidiI6Mn0", "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwicmVmIjp7ImFjdGl2aXR5X2lkIjoiYSIsImtpbmQiOiJhY3Rpdml0eSIsInRvcGljIjoidCIsIndvcmtmbG93X2lkIjoidyJ9LCJ2IjoyfQ", "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwicmVmIjp7ImFjdGl2aXR5X2lkIjoiYSIsImtpbmQiOiJ3b3JrZmxvdyIsInRvcGljIjoidCIsIndvcmtmbG93X2lkIjoidyJ9LCJ2IjoyfQ", - "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwicmVmIjp7ImtpbmQiOiJuZXh1cyIsInRvcGljIjoidCIsIndvcmtmbG93X2lkIjoidyJ9LCJ2IjoyfQ" + "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwicmVmIjp7ImtpbmQiOiJuZXh1cyIsInRvcGljIjoidCIsIndvcmtmbG93X2lkIjoidyJ9LCJ2IjoyfQ", + "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwicmVmIjp7ImFjdGl2aXR5X2lkIjoiYSIsImtpbmQiOiJ3b3JrZmxvd19hY3Rpdml0eSIsInRvcGljIjoidCIsIndvcmtmbG93X2lkIjoidyJ9LCJ2IjoyfQ", + "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwicmVmIjp7ImFjdGl2aXR5X2lkIjoiYSIsImNoYWluX3J1bl9pZCI6InIiLCJraW5kIjoid29ya2Zsb3dfYWN0aXZpdHkiLCJ0b3BpYyI6InQiLCJ3b3JrZmxvd19pZCI6IiJ9LCJ2IjoyfQ", + "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwicmVmIjp7ImNoYWluX3J1bl9pZCI6InIiLCJraW5kIjoid29ya2Zsb3dfYWN0aXZpdHkiLCJ0b3BpYyI6InQiLCJ3b3JrZmxvd19pZCI6IncifSwidiI6Mn0", + "eyJhdHRhY2giOiJhIiwiY2hhaW4iOiJjIiwicmVmIjp7ImFjdGl2aXR5X2lkIjoiIiwiY2hhaW5fcnVuX2lkIjoiciIsImtpbmQiOiJ3b3JrZmxvd19hY3Rpdml0eSIsInRvcGljIjoidCIsIndvcmtmbG93X2lkIjoidyJ9LCJ2IjoyfQ" ] } diff --git a/crates/streams/nexus/temporal_streams.nexusrpc.yaml b/crates/streams/nexus/temporal_streams.nexusrpc.yaml index 9396a6a484..ccfc954c0b 100644 --- a/crates/streams/nexus/temporal_streams.nexusrpc.yaml +++ b/crates/streams/nexus/temporal_streams.nexusrpc.yaml @@ -80,16 +80,19 @@ $defs: kind: type: string description: >- - What owns the stream, "workflow" or "activity". A call with another - kind is refused. + What owns the stream: "workflow", "activity" for a standalone + Activity, or "workflow_activity" for an Activity that a Workflow + run scheduled. A call with another kind is refused. workflow_id: type: string - description: "The owning Workflow. Empty for kind activity." + description: >- + The owning Workflow, or for kind workflow_activity the Workflow that + scheduled the Activity. Empty for kind activity. activity_id: oneOf: [{ type: string }, { type: "null" }] description: >- - The owning standalone Activity, for kind activity. Absent or null - for kind workflow. + The owning Activity, for kinds activity and workflow_activity. Absent + or null for kind workflow. chain_run_id: oneOf: [{ type: string }, { type: "null" }] description: >- @@ -97,7 +100,9 @@ $defs: or null names the Workflow id's newest chain. It never stops a read at this run: a read follows the chain across Continue-as-New and ends with the chain. For kind activity, the Activity run. Absent or - null names the Activity id's newest run when the read starts. + null names the Activity id's newest run when the read starts. For + kind workflow_activity, the run that scheduled the Activity, which is + required, since an Activity id repeats in each run. topic: type: string description: "The topic on the owner's stream." @@ -427,6 +432,7 @@ $defs: description: >- The first run of the run chain the start attached to, so a cancel detaches from it even after the Workflow id moved on to a new chain. - For an Activity owner, the Activity run. + For an Activity owner, the Activity run. For a Workflow Activity + owner, the run that scheduled it. required: [v, ref, attach, chain] additionalProperties: false diff --git a/crates/streams/src/handle.rs b/crates/streams/src/handle.rs index 91188a008c..a69f3ecf41 100644 --- a/crates/streams/src/handle.rs +++ b/crates/streams/src/handle.rs @@ -452,6 +452,16 @@ impl Streams { stream: &StreamAddress, first_run_id: &str, ) -> StreamResult<()> { + if stream.owner_kind == StreamOwnerKind::WorkflowActivity as i32 { + // The address names the run that keys the stream, so no describe is needed. + if first_run_id != stream.run_id { + return Err(StreamError::cursor(format!( + "the read state names run {first_run_id:?}, which is not the run of {}", + owner_key(stream).label() + ))); + } + return Ok(()); + } let key = OwnerKey { run_id: first_run_id.to_string(), ..owner_key(stream) diff --git a/crates/streams/src/nexus/mod.rs b/crates/streams/src/nexus/mod.rs index 009d39ae67..2a1778899f 100644 --- a/crates/streams/src/nexus/mod.rs +++ b/crates/streams/src/nexus/mod.rs @@ -309,11 +309,14 @@ impl NexusCalls { let wake = match &input.wake_token { Some(token) => match OperationToken::decode(&call.namespace, token) { // A token of another owner with the same topic must not wake this reader, and - // every Activity's ref has the same empty Workflow id. + // every Activity's ref has the same empty Workflow id. A Workflow Activity's id + // repeats in each run, so its run is part of the owner. Ok(token) if token.stream.owner_kind == address.owner_kind && token.stream.workflow_id == address.workflow_id && token.stream.activity_id == address.activity_id + && (address.owner_kind != StreamOwnerKind::WorkflowActivity as i32 + || token.stream.run_id == address.run_id) && token.stream.topic == address.topic => { Some(token) @@ -504,8 +507,11 @@ impl NexusCalls { Ok(address) => address, Err(failure) => return failed(*failure), }; - // The chain names the run chain, so the ref's run picks nothing here. - address.run_id.clear(); + // The chain names the run chain, so the ref's run picks nothing here. A Workflow + // Activity's run names the stream itself. + if address.owner_kind != StreamOwnerKind::WorkflowActivity as i32 { + address.run_id.clear(); + } if !(0..=MAX_RECORDS).contains(&input.stored_records) { return failed(failure::input_mistake(format!( "stored_records is from 0 to {MAX_RECORDS}, not {}", @@ -554,13 +560,16 @@ impl NexusCalls { } /// `address` without its run, and a state that names the chain the run picked. A state the - /// caller passed back already names its chain. + /// caller passed back already names its chain. A Workflow Activity keeps its run, which names + /// the stream itself. async fn chain_by_state( &self, mut address: StreamAddress, state: Vec, ) -> Result<(StreamAddress, Vec), StreamError> { - if address.run_id.is_empty() { + if address.run_id.is_empty() + || address.owner_kind == StreamOwnerKind::WorkflowActivity as i32 + { return Ok((address, state)); } let state = if state.is_empty() { @@ -1074,8 +1083,8 @@ fn address(namespace: &str, stream: &StreamRef) -> Result Result None, + StreamOwnerKind::WorkflowActivity + if stream.workflow_id.is_empty() + || activity_id.is_empty() + || stream + .chain_run_id + .as_deref() + .unwrap_or_default() + .is_empty() => + { + Some( + "a stream that a Workflow Activity owns needs its Workflow id, the run that \ + scheduled it as chain_run_id, and its Activity id", + ) + } + StreamOwnerKind::WorkflowActivity => None, _ if stream.workflow_id.is_empty() => Some("a stream needs its owner's Workflow id"), _ if stream.activity_id.is_some() => { Some("a stream that a Workflow owns names no Activity id") diff --git a/crates/streams/src/nexus/operation.rs b/crates/streams/src/nexus/operation.rs index a6d8fd0ceb..88ea423c64 100644 --- a/crates/streams/src/nexus/operation.rs +++ b/crates/streams/src/nexus/operation.rs @@ -189,10 +189,25 @@ fn checked(stream: Option<&StreamAddress>) -> StreamResult<&StreamAddress> { let (owner_id, other_id, kind) = match StreamOwnerKind::try_from(stream.owner_kind) { Ok(StreamOwnerKind::Workflow) => (&stream.workflow_id, &stream.activity_id, "Workflow"), Ok(StreamOwnerKind::Activity) => (&stream.activity_id, &stream.workflow_id, "Activity"), + Ok(StreamOwnerKind::WorkflowActivity) => { + if stream.namespace.is_empty() + || stream.workflow_id.is_empty() + || stream.run_id.is_empty() + || stream.activity_id.is_empty() + { + return Err(bad_input( + "a stream that a Workflow Activity owns needs its namespace, its Workflow \ + id, the run that scheduled it and its Activity id", + )); + } + temporalio_common::streams::check_topic(&stream.topic) + .map_err(|reason| bad_input(&super::failure::without_values(&reason)))?; + return Ok(stream); + } _ => { return Err(StreamError::unsupported(format!( - "this release opens streams of Workflows and standalone Activities only, not \ - owner kind {}", + "this release opens streams of Workflows, standalone Activities and Workflow \ + Activities only, not owner kind {}", stream.owner_kind ))); } @@ -268,9 +283,10 @@ struct TokenRef { } /// The `kind` of a contract `StreamRef`, by Core's owner kind. -const KINDS: [(&str, StreamOwnerKind); 2] = [ +const KINDS: [(&str, StreamOwnerKind); 3] = [ ("workflow", StreamOwnerKind::Workflow), ("activity", StreamOwnerKind::Activity), + ("workflow_activity", StreamOwnerKind::WorkflowActivity), ]; /// The owner kind a contract `kind` names, or `None` for a kind no release opens. @@ -297,7 +313,8 @@ impl OperationToken { attach: self.attach_request_id.clone(), chain: self.chain_first_run_id.clone(), stream: TokenRef { - activity_id: (self.stream.owner_kind == StreamOwnerKind::Activity as i32) + activity_id: (self.stream.owner_kind != StreamOwnerKind::Workflow as i32 + && self.stream.owner_kind != StreamOwnerKind::Unspecified as i32) .then(|| self.stream.activity_id.clone()), chain_run_id: (!self.stream.run_id.is_empty()).then(|| self.stream.run_id.clone()), kind: kind_name(self.stream.owner_kind).to_string(), @@ -345,11 +362,24 @@ impl OperationToken { } StreamOwnerKind::Activity } + Some(StreamOwnerKind::WorkflowActivity) => { + let empty = |id: &Option| id.as_deref().unwrap_or_default().is_empty(); + if empty(&body.stream.activity_id) + || empty(&body.stream.chain_run_id) + || body.stream.workflow_id.is_empty() + { + return Err(refuse( + "a Workflow Activity's stream names its Workflow id, the run that \ + scheduled it and its Activity id", + )); + } + StreamOwnerKind::WorkflowActivity + } Some(_) if body.stream.activity_id.is_none() => StreamOwnerKind::Workflow, Some(_) => return Err(refuse("a Workflow's stream names no Activity id")), None => { return Err(refuse( - "the stream's owner is neither a Workflow nor an Activity", + "the stream's owner is no Workflow, standalone Activity or Workflow Activity", )); } }; @@ -776,6 +806,48 @@ mod tests { ); } + #[tokio::test] + async fn a_workflow_activity_stream_start_attaches_on_its_scheduling_run() { + let setup = setup(); + let tool = StreamAddress { + owner_kind: StreamOwnerKind::WorkflowActivity as i32, + run_id: "run-7".to_string(), + activity_id: "1".to_string(), + ..stream("") + }; + let start = AttachCallerRequest { + stream: Some(tool.clone()), + wake_after_counter: Some(0), + ..attach_request("temporal://system") + }; + let token = attach(&setup.service, start).await.unwrap(); + let run = ChainId { + namespace: "default".to_string(), + workflow_id: tool.workflow_id.clone(), + first_run_id: "run-7".to_string(), + owner_kind: StreamOwnerKind::WorkflowActivity as i32, + activity_id: "1".to_string(), + }; + assert_eq!(setup.notifier.attached.lock().unwrap()[0].chain, run); + let decoded = OperationToken::decode("default", &token).unwrap(); + assert_eq!(decoded.stream, tool); + assert_eq!(decoded.chain(), run); + detach(&setup.service, &token).await.unwrap(); + assert_eq!(setup.notifier.detached.lock().unwrap()[0].0, run); + // A Workflow Activity's address names its run. + let refused = AttachCallerRequest { + stream: Some(StreamAddress { + run_id: String::new(), + ..tool + }), + ..attach_request("temporal://system") + }; + assert_eq!( + attach(&setup.service, refused).await.unwrap_err().kind, + "BAD_REQUEST" + ); + } + #[tokio::test] async fn a_start_attaches_an_idle_callback_and_announces_nothing() { let setup = setup(); @@ -1230,6 +1302,32 @@ mod tests { ); } + #[test] + fn a_workflow_activity_token_names_its_scheduling_run_as_its_chain() { + let vectors = vectors(); + let vector = vectors + .vectors + .iter() + .find(|vector| vector.stream.kind == "workflow_activity") + .unwrap(); + let token = OperationToken::decode("ns", &vector.token).unwrap(); + assert_eq!( + token.stream.owner_kind, + StreamOwnerKind::WorkflowActivity as i32 + ); + assert_eq!( + token.chain(), + ChainId { + namespace: "ns".to_string(), + workflow_id: vector.stream.workflow_id.clone(), + first_run_id: vector.stream.chain_run_id.clone().unwrap(), + owner_kind: StreamOwnerKind::WorkflowActivity as i32, + activity_id: vector.stream.activity_id.clone().unwrap(), + } + ); + assert_eq!(token.encode(), vector.token); + } + #[test] fn a_token_from_before_core_still_decodes() { for vector in vectors().decode_only { diff --git a/crates/streams/tests/nexus_contract.rs b/crates/streams/tests/nexus_contract.rs index 2c041f5394..edbfc3e08c 100644 --- a/crates/streams/tests/nexus_contract.rs +++ b/crates/streams/tests/nexus_contract.rs @@ -232,6 +232,30 @@ async fn an_activity_ref_matches_the_contract() { } } +#[tokio::test] +async fn a_workflow_activity_ref_matches_the_contract() { + let calls = service(memory(), NexusOptions::default()); + let input = json!({ + "stream": { + "kind": "workflow_activity", + "workflow_id": "agent", + "activity_id": "tool-42", + "chain_run_id": "run-1", + "topic": "out", + }, + }); + let step = calls.read(call(input)).await; + if let Err(failure) = drive(&calls, step, Codec::Sealing).await { + assert!(!is_contract_mistake(&failure), "{}", failure.message); + } + let contract = contract(); + let kind = model(&contract, "StreamRef")["properties"]["kind"]["description"] + .as_str() + .unwrap() + .to_string(); + assert!(kind.contains("\"workflow_activity\""), "{kind}"); +} + #[test] fn the_operation_token_model_is_closed_and_versioned() { // The generated token helpers refuse a token model that isn't closed or that lacks a diff --git a/crates/streams/tests/nexus_service.rs b/crates/streams/tests/nexus_service.rs index d210094293..700bb74d7e 100644 --- a/crates/streams/tests/nexus_service.rs +++ b/crates/streams/tests/nexus_service.rs @@ -692,6 +692,69 @@ mod cases { assert!(*after > 0); } + pub(crate) async fn a_workflow_activity_stream_reads_apart_from_its_workflow_and_other_runs( + store: Arc, + ) { + let calls = service(store, NexusOptions::default()); + let id = workflow(); + let tool = |run: &str| workflow_activity_stream(&id, run, "1", TOPIC); + let mut input = append_input(&id, "p", 1, 1, &["one", "two"]); + input["stream"] = tool("run-1"); + append(&calls, input).await.unwrap(); + write(&calls, &id, 1, &["workflow"]).await; + let answer = read(&calls, json!({"stream": tool("run-1")})) + .await + .unwrap(); + assert_eq!(texts(&answer), ["one", "two"]); + assert_eq!(texts(&read_after(&calls, &id, "").await), ["workflow"]); + // Activity `1` of the next run is another stream, and its cursors are its own. + let next = read(&calls, json!({"stream": tool("run-2")})) + .await + .unwrap(); + assert!(texts(&next).is_empty()); + let refused = read( + &calls, + json!({"stream": tool("run-2"), "after_token": token(&answer)}), + ) + .await + .unwrap_err(); + assert_eq!(kind_of(&refused).2, "StreamCursorError"); + // The run is part of the owner, so another run's token wakes nothing here. + let other_run = OperationToken { + stream: StreamAddress { + namespace: NAMESPACE.to_string(), + owner_kind: StreamOwnerKind::WorkflowActivity as i32, + workflow_id: id.clone(), + run_id: "run-2".to_string(), + topic: TOPIC.to_string(), + activity_id: "1".to_string(), + }, + attach_request_id: "attach-1".to_string(), + chain_first_run_id: "run-2".to_string(), + } + .encode(); + let refused = read( + &calls, + json!({"stream": tool("run-1"), "wake_token": other_run}), + ) + .await + .unwrap_err(); + assert_eq!(kind_of(&refused).0, "BAD_REQUEST"); + // A Workflow Activity's ref names its Workflow, its run and its Activity. + for stream in [ + json!({"kind": "workflow_activity", "workflow_id": id, "activity_id": "1", "topic": "t"}), + json!({"kind": "workflow_activity", "workflow_id": "", "activity_id": "1", + "chain_run_id": "run-1", "topic": "t"}), + json!({"kind": "workflow_activity", "workflow_id": id, "chain_run_id": "run-1", + "topic": "t"}), + ] { + let refused = read(&calls, json!({ "stream": stream.clone() })) + .await + .unwrap_err(); + assert_eq!(kind_of(&refused).0, "BAD_REQUEST", "{stream}"); + } + } + pub(crate) async fn a_read_says_done_once_the_owner_ends(store: Arc) { let wf = workflow(); write( @@ -1065,6 +1128,7 @@ macro_rules! all_cases { an_activity_read_says_done_once_the_run_ends, a_wake_token_of_another_activity_is_refused, an_empty_activity_read_wakes_its_operation_on_the_activity_run, + a_workflow_activity_stream_reads_apart_from_its_workflow_and_other_runs, ); }; } @@ -1581,3 +1645,54 @@ async fn an_activity_streams_codec_work_names_the_activity() { (NAMESPACE, StreamOwnerKind::Activity as i32, "", "tool-1") ); } + +#[tokio::test] +async fn a_workflow_activity_range_replays_and_names_only_its_run() { + let calls = service(memory(), NexusOptions::default()); + let id = workflow(); + let tool = workflow_activity_stream(&id, "run-3", "1", TOPIC); + let mut input = append_input(&id, "p", 1, 1, &["one", "two"]); + input["stream"] = tool.clone(); + append(&calls, input).await.unwrap(); + let answer = read(&calls, json!({"stream": tool, "floor_holder": HOLDER})) + .await + .unwrap(); + assert_eq!(answer["replay"]["chain_first_run_id"], "run-3"); + // A later call carries the state, which names the run. + let next = read( + &calls, + json!({"stream": tool, "after_token": answer["next_token"], "state": answer["state"]}), + ) + .await + .unwrap(); + assert!(texts(&next).is_empty()); + let replay = replay_input(tool.clone(), &answer, Value::Null); + let replayed = read_range(&calls, replay.clone()).await.unwrap(); + assert_eq!(replayed["records"], answer["records"]); + let mut other_run = replay; + other_run["chain_first_run_id"] = json!("run-9"); + let refused = read_range(&calls, other_run).await.unwrap_err(); + assert_eq!( + kind_of(&refused), + ("BAD_REQUEST", false, "StreamCursorError") + ); +} + +#[tokio::test] +async fn a_workflow_activity_streams_codec_work_names_the_activity_and_its_workflow() { + let calls = service(memory(), NexusOptions::default()); + let mut input = append_input("unused", "p", 1, 1, &["one"]); + input["stream"] = workflow_activity_stream("agent", "run-1", "tool-42", TOPIC); + let step = calls.append(call(input)).await; + let Some(temporalio_streams::proto::nexus_step::Step::Codec(work)) = step.step else { + panic!("an append asks for codec work first, not {step:?}"); + }; + assert_eq!( + ( + work.owner_kind, + work.workflow_id.as_str(), + work.activity_id.as_str() + ), + (StreamOwnerKind::WorkflowActivity as i32, "agent", "tool-42") + ); +} diff --git a/crates/streams/tests/nexus_support/mod.rs b/crates/streams/tests/nexus_support/mod.rs index 5d6a7869e0..eebe7c33a6 100644 --- a/crates/streams/tests/nexus_support/mod.rs +++ b/crates/streams/tests/nexus_support/mod.rs @@ -199,6 +199,23 @@ pub(crate) fn activity_stream(activity_id: &str, topic: &str) -> Value { }) } +/// A stream reference to `topic` of Activity `activity_id` that run `run_id` of Workflow +/// `workflow_id` scheduled. +pub(crate) fn workflow_activity_stream( + workflow_id: &str, + run_id: &str, + activity_id: &str, + topic: &str, +) -> Value { + serde_json::json!({ + "kind": "workflow_activity", + "workflow_id": workflow_id, + "activity_id": activity_id, + "chain_run_id": run_id, + "topic": topic, + }) +} + /// A stream reference to `topic` of Workflow `workflow_id`. pub(crate) fn stream(workflow_id: &str, topic: &str) -> Value { serde_json::json!({"kind": "workflow", "workflow_id": workflow_id, "topic": topic})