Skip to content

Commit 44519d8

Browse files
moetempmoetemp
committed
Added the Stream service messages as experimental.
The crate, sdk-python and later the server read one copy of these messages. The gRPC service and its Nexus annotations come with the server.
1 parent d21dd97 commit 44519d8

3 files changed

Lines changed: 404 additions & 0 deletions

File tree

‎temporal/api/enums/v1/stream.proto‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
syntax = "proto3";
2+
3+
package temporal.api.enums.v1;
4+
5+
option go_package = "go.temporal.io/api/enums/v1;enums";
6+
option java_package = "io.temporal.api.enums.v1";
7+
option java_multiple_files = true;
8+
option java_outer_classname = "StreamProto";
9+
option ruby_package = "Temporalio::Api::Enums::V1";
10+
option csharp_namespace = "Temporalio.Api.Enums.V1";
11+
12+
// Experimental. Might change in the future.
13+
enum StreamProducerKind {
14+
STREAM_PRODUCER_KIND_UNSPECIFIED = 0;
15+
STREAM_PRODUCER_KIND_WORKFLOW = 1;
16+
STREAM_PRODUCER_KIND_LOCAL_ACTIVITY = 2;
17+
STREAM_PRODUCER_KIND_ACTIVITY = 3;
18+
STREAM_PRODUCER_KIND_CLIENT = 4;
19+
STREAM_PRODUCER_KIND_STANDALONE_ACTIVITY = 5;
20+
}
21+
22+
// Experimental. Might change in the future.
23+
// How a Stream closed, so a reader tells a terminated or timed out owner from a failed one
24+
// without parsing the failure.
25+
// (-- api-linter: core::0216::synonyms=disabled
26+
// aip.dev/not-precedent: Named consistently with WorkflowExecutionStatus. --)
27+
enum StreamCloseStatus {
28+
STREAM_CLOSE_STATUS_UNSPECIFIED = 0;
29+
STREAM_CLOSE_STATUS_COMPLETED = 1;
30+
STREAM_CLOSE_STATUS_FAILED = 2;
31+
STREAM_CLOSE_STATUS_CANCELED = 3;
32+
// TERMINATED and TIMED_OUT come only from the owner's end, never from a caller.
33+
STREAM_CLOSE_STATUS_TERMINATED = 4;
34+
STREAM_CLOSE_STATUS_TIMED_OUT = 5;
35+
}
36+
37+
// Experimental. Might change in the future.
38+
// (-- api-linter: core::0216::synonyms=disabled
39+
// aip.dev/not-precedent: Named consistently with WorkflowExecutionStatus. --)
40+
enum StreamStatus {
41+
STREAM_STATUS_UNSPECIFIED = 0;
42+
STREAM_STATUS_OPEN = 1;
43+
STREAM_STATUS_CLOSED = 2;
44+
STREAM_STATUS_EXPIRED = 3;
45+
}
46+
47+
// Experimental. Might change in the future.
48+
enum StreamReadStart {
49+
STREAM_READ_START_UNSPECIFIED = 0;
50+
STREAM_READ_START_BEGINNING = 1;
51+
STREAM_READ_START_END = 2;
52+
}
53+
54+
// Experimental. Might change in the future.
55+
// Why a Stream call failed. Each reason has one gRPC status code.
56+
enum StreamErrorReason {
57+
STREAM_ERROR_REASON_UNSPECIFIED = 0;
58+
// Nobody created the Stream, even after `create_wait`. NOT_FOUND.
59+
STREAM_ERROR_REASON_NOT_FOUND = 1;
60+
// The Stream's Retention or safety TTL passed. NOT_FOUND.
61+
STREAM_ERROR_REASON_EXPIRED = 2;
62+
// The Stream is closed. FAILED_PRECONDITION.
63+
STREAM_ERROR_REASON_CLOSED = 3;
64+
// The Producer's epoch is lower than the newest one, its Workflow Task was withdrawn, or a
65+
// Workflow retry withdrew its run. FAILED_PRECONDITION.
66+
STREAM_ERROR_REASON_FENCED = 4;
67+
// The batch has a lower `sequence` than the last one of its epoch. FAILED_PRECONDITION.
68+
STREAM_ERROR_REASON_SEQUENCE = 5;
69+
// The batch has the `sequence` of the last one of its epoch, and other content.
70+
// FAILED_PRECONDITION.
71+
STREAM_ERROR_REASON_SEQ_DIVERGENT = 6;
72+
// A create names another owner than the Stream has, or the owner doesn't allow this close.
73+
// FAILED_PRECONDITION.
74+
STREAM_ERROR_REASON_NOT_OWNER = 7;
75+
// A newer format version wrote the Stream. FAILED_PRECONDITION.
76+
STREAM_ERROR_REASON_FORMAT_TOO_NEW = 8;
77+
// The offset is past the newest offset + 1, for example after a failover lost the newest
78+
// Records. A read from it works again once the Stream has Records up to it. OUT_OF_RANGE.
79+
STREAM_ERROR_REASON_OFFSET = 9;
80+
// A Record or a batch is over the Store's limit. INVALID_ARGUMENT.
81+
STREAM_ERROR_REASON_TOO_LARGE = 10;
82+
// The request is malformed. INVALID_ARGUMENT.
83+
STREAM_ERROR_REASON_INVALID = 11;
84+
// The Store failed or did not answer. UNAVAILABLE.
85+
STREAM_ERROR_REASON_STORAGE = 12;
86+
// No writer has the id. The SDK's in-process writer only. NOT_FOUND.
87+
STREAM_ERROR_REASON_UNKNOWN_WRITER = 13;
88+
// The Store lacks a capability that the call needs. UNIMPLEMENTED.
89+
STREAM_ERROR_REASON_UNSUPPORTED = 14;
90+
}

‎temporal/api/stream/v1/message.proto‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
syntax = "proto3";
2+
3+
package temporal.api.stream.v1;
4+
5+
option go_package = "go.temporal.io/api/stream/v1;stream";
6+
option java_package = "io.temporal.api.stream.v1";
7+
option java_multiple_files = true;
8+
option java_outer_classname = "MessageProto";
9+
option ruby_package = "Temporalio::Api::Stream::V1";
10+
option csharp_namespace = "Temporalio.Api.Stream.V1";
11+
12+
import "google/protobuf/timestamp.proto";
13+
14+
import "temporal/api/common/v1/message.proto";
15+
import "temporal/api/enums/v1/stream.proto";
16+
import "temporal/api/failure/v1/message.proto";
17+
18+
// Experimental. Might change in the future.
19+
// Identifies one Stream. The id is opaque to callers.
20+
message StreamRef {
21+
string id = 1;
22+
// Unset for a client's Stream. For a Workflow, business_id is the Workflow ID and run_id is
23+
// the first execution run id of its run chain. For a Standalone Activity, business_id is the
24+
// activity ID and run_id is its run id. A create and a close of a Workflow-owned Stream must
25+
// name its owner.
26+
temporal.api.common.v1.Execution owner = 2;
27+
// The name of the backend that holds the Stream, as the Worker and client config register
28+
// it, so every process routes a ref it receives. Empty is the default backend. The Store
29+
// never reads it.
30+
string backend = 3;
31+
}
32+
33+
// Experimental. Might change in the future.
34+
// The ordered attempt of a Producer. Compared in this order: task_started_event_id,
35+
// task_attempt, task_started_time, attempt_scheduled_time, attempt. A field that a kind does
36+
// not use is empty and compares as zero. A timestamp compares seconds, then nanos.
37+
message ProducerEpoch {
38+
// The Workflow Task of a Workflow, or the one that dispatched a Local Activity.
39+
int64 task_started_event_id = 1;
40+
int32 task_attempt = 2;
41+
// Tells a reused started event id apart, for example after a dropped speculative task.
42+
google.protobuf.Timestamp task_started_time = 5;
43+
// When the server scheduled an Activity's attempt. A reset makes it later.
44+
google.protobuf.Timestamp attempt_scheduled_time = 3;
45+
// Activity, Local Activity and client attempt.
46+
int32 attempt = 4;
47+
}
48+
49+
// Experimental. Might change in the future.
50+
message Producer {
51+
temporal.api.enums.v1.StreamProducerKind kind = 1;
52+
string id = 2;
53+
ProducerEpoch epoch = 3;
54+
// The run of the Producer, so nobody parses the id. Empty for a client.
55+
string run_id = 4;
56+
}
57+
58+
// Experimental. Might change in the future.
59+
message WorkflowTaskEpoch {
60+
int64 started_event_id = 1;
61+
int32 attempt = 2;
62+
google.protobuf.Timestamp started_time = 3;
63+
}
64+
65+
// Experimental. Might change in the future.
66+
message AppendRecord {
67+
reserved 1;
68+
reserved "topic";
69+
temporal.api.common.v1.Payload body = 2;
70+
}
71+
72+
// Experimental. Might change in the future.
73+
message Supersession {
74+
temporal.api.enums.v1.StreamProducerKind producer_kind = 1;
75+
string producer_id = 2;
76+
ProducerEpoch epoch = 3;
77+
// Workflow only.
78+
WorkflowTaskEpoch previous_completed_task = 4;
79+
repeated int64 failed_tasks = 5;
80+
// Workflow retry only. The previous run. Every Record whose Producer carries it is withdrawn.
81+
string withdraw_run = 6;
82+
// The run of the Producer, so nobody parses the id. Empty for a client.
83+
string run_id = 7;
84+
}
85+
86+
// Experimental. Might change in the future.
87+
// One Record that a Producer appended.
88+
message StreamData {
89+
reserved 1;
90+
reserved "topic";
91+
Producer producer = 2;
92+
temporal.api.common.v1.Payload body = 3;
93+
}
94+
95+
// Experimental. Might change in the future.
96+
// The close of a Stream. A Stream has at most one, and a read returns it last.
97+
message StreamClose {
98+
// The Producer that closed the Stream.
99+
Producer producer = 1;
100+
temporal.api.common.v1.Payload result = 2;
101+
temporal.api.failure.v1.Failure failure = 3;
102+
// The result or the failure stays next to it.
103+
temporal.api.enums.v1.StreamCloseStatus status = 4;
104+
}
105+
106+
// Experimental. Might change in the future.
107+
// An offset is ordered and unique in one Stream, and it is sparse. Offsets have gaps, so they
108+
// don't count Records. Zero is never an offset. A read names its Stream, so the read checks the
109+
// offset against that Stream.
110+
message StreamRecord {
111+
int64 offset = 1;
112+
// A read item is a Record, a Superseded item or the close.
113+
oneof item {
114+
StreamData data = 2;
115+
// The first batch of a higher epoch carries it. It withdraws the earlier Records that its
116+
// facts name, and a reader drops them.
117+
Supersession superseded = 3;
118+
StreamClose close = 4;
119+
}
120+
}
121+
122+
// Experimental. Might change in the future.
123+
// The details of a failed Stream call, in the gRPC status details and in the details of the
124+
// application failure of a Nexus operation.
125+
message StreamErrorDetails {
126+
temporal.api.enums.v1.StreamErrorReason reason = 1;
127+
}

0 commit comments

Comments
 (0)