Skip to content
This repository was archived by the owner on Feb 14, 2025. It is now read-only.

Commit e34e186

Browse files
slinkydeveloperslinkydeveloper
committed
Carry around format information in the protocol.
1 parent d909638 commit e34e186

File tree

2 files changed

+47
-30
lines changed

2 files changed

+47
-30
lines changed

‎dev/restate/service/protocol.proto

Lines changed: 30 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,8 @@ message StartMessage {
4747
}
4848

4949
// Type: 0x0000 + 1
50+
// For more details about completions,
51+
// see https://github.com/restatedev/service-protocol/blob/main/service-invocation-protocol.md#completable-journal-entries-and-completionmessage
5052
message CompletionMessage {
5153
uint32 entry_index = 1;
5254

@@ -99,7 +101,7 @@ message EndMessage {
99101
// Depending on the semantics of the corresponding syscall, the entry can represent the result field with any of these three types:
100102
//
101103
// * google.protobuf.Empty empty = 13 for cases when we need to propagate to user code the distinction between default value or no value.
102-
// * bytes value = 14 for carrying the result value
104+
// * T value = 14 for carrying the result value. The value carried by CompletionMessage carry the same type T carried here.
103105
// * Failure failure = 15 for carrying a failure
104106
//
105107
// The tag numbers 13, 14 and 15 are reserved and shouldn't be used for other fields.
@@ -111,7 +113,7 @@ message EndMessage {
111113
// Type: 0x0400 + 0
112114
message PollInputStreamEntryMessage {
113115
oneof result {
114-
bytes value = 14;
116+
Payload value = 14;
115117
Failure failure = 15;
116118
}
117119
}
@@ -121,7 +123,7 @@ message PollInputStreamEntryMessage {
121123
// Type: 0x0400 + 1
122124
message OutputStreamEntryMessage {
123125
oneof result {
124-
bytes value = 14;
126+
Payload value = 14;
125127
Failure failure = 15;
126128
};
127129
}
@@ -136,7 +138,7 @@ message GetStateEntryMessage {
136138

137139
oneof result {
138140
google.protobuf.Empty empty = 13;
139-
bytes value = 14;
141+
Payload value = 14;
140142
Failure failure = 15;
141143
};
142144
}
@@ -146,7 +148,7 @@ message GetStateEntryMessage {
146148
// Type: 0x0800 + 1
147149
message SetStateEntryMessage {
148150
bytes key = 1;
149-
bytes value = 3;
151+
Payload value = 3;
150152
}
151153

152154
// Completable: No
@@ -198,16 +200,15 @@ message SleepEntryMessage {
198200
message InvokeEntryMessage {
199201
string service_name = 1;
200202
string method_name = 2;
203+
// If this invocation has a key associated (e.g. for objects and workflows), then this key is filled in. Empty otherwise.
204+
string key = 5;
201205

202-
bytes parameter = 3;
206+
Payload parameter = 3;
203207

204208
repeated Header headers = 4;
205209

206-
// If this invocation has a key associated (e.g. for objects and workflows), then this key is filled in. Empty otherwise.
207-
string key = 5;
208-
209210
oneof result {
210-
bytes value = 14;
211+
Payload value = 14;
211212
Failure failure = 15;
212213
};
213214
}
@@ -218,8 +219,10 @@ message InvokeEntryMessage {
218219
message BackgroundInvokeEntryMessage {
219220
string service_name = 1;
220221
string method_name = 2;
222+
// If this invocation has a key associated (e.g. for objects and workflows), then this key is filled in. Empty otherwise.
223+
string key = 6;
221224

222-
bytes parameter = 3;
225+
Payload parameter = 3;
223226

224227
// Time when this BackgroundInvoke should be executed.
225228
// The time is set as duration since UNIX Epoch.
@@ -228,9 +231,6 @@ message BackgroundInvokeEntryMessage {
228231
uint64 invoke_time = 4;
229232

230233
repeated Header headers = 5;
231-
232-
// If this invocation has a key associated (e.g. for objects and workflows), then this key is filled in. Empty otherwise.
233-
string key = 6;
234234
}
235235

236236
// Completable: Yes
@@ -239,7 +239,7 @@ message BackgroundInvokeEntryMessage {
239239
// Awakeables are addressed by an identifier exposed to the user. See the spec for more details.
240240
message AwakeableEntryMessage {
241241
oneof result {
242-
bytes value = 14;
242+
Payload value = 14;
243243
Failure failure = 15;
244244
};
245245
}
@@ -252,7 +252,7 @@ message CompleteAwakeableEntryMessage {
252252
string id = 1;
253253

254254
oneof result {
255-
bytes value = 5;
255+
Payload value = 5;
256256
Failure failure = 6;
257257
};
258258
}
@@ -275,3 +275,17 @@ message Header {
275275
string key = 1;
276276
string value = 2;
277277
}
278+
279+
// Payload is a generic message used to carry around a value with some format metadata.
280+
// Those metadata are mostly used by runtime observability tools and to aid the SDK to deserialize the payload.
281+
message Payload {
282+
bytes value = 1;
283+
Format format = 2;
284+
}
285+
286+
// Format of the payload/state entry.
287+
enum Format {
288+
UNKNOWN = 0;
289+
JSON = 1;
290+
UTF8_STRING = 2;
291+
}

‎service-invocation-protocol.md

Lines changed: 17 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -249,6 +249,9 @@ also not be interested in the `result` of completable journal entries, or it mig
249249
different order used to create the related journal entries. Usually it's the service business logic that dictates in
250250
which `result`s the SDK is interested, and in which order.
251251

252+
The content of `CompletionMessage.value` depends on the completed entry itself, see
253+
[Journal entries reference](#journal-entries-reference) for more details.
254+
252255
**`CompletionMessage` Header**
253256

254257
0 1 2 3
@@ -280,20 +283,20 @@ index of the corresponding entry.
280283
The following tables describe the currently available journal entries. For more details, check the protobuf message
281284
descriptions in [`protocol.proto`](dev/restate/service/protocol.proto).
282285

283-
| Message | Type | Completable | Fallible | Description |
284-
| ------------------------------- | -------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
285-
| `PollInputStreamEntryMessage` | `0x0400` | Yes | No | Carries the invocation input message(s) of the invocation. Note: currently the runtime always sends this entry completed, but this may change in future. |
286-
| `GetStateEntryMessage` | `0x0800` | Yes | No | Get the value of a service instance state key. |
287-
| `GetStateKeysEntryMessage` | `0x0804` | Yes | No | Get all the known state keys for this service instance. Note: the completion value for this message is a protobuf of type `GetStateKeysEntryMessage.StateKeys`. |
288-
| `SleepEntryMessage` | `0x0C00` | Yes | No | Initiate a timer that completes after the given time. |
289-
| `InvokeEntryMessage` | `0x0C01` | Yes | Yes | Invoke another Restate service. |
290-
| `AwakeableEntryMessage` | `0x0C03` | Yes | No | Arbitrary result container which can be completed from another service, given a specific id. See [Awakeable identifier](#awakeable-identifier) for more details. |
291-
| `BackgroundInvokeEntryMessage` | `0x0C02` | No | Yes | Invoke another Restate service at the given time, without waiting for the response. |
292-
| `CompleteAwakeableEntryMessage` | `0x0C04` | No | Yes | Complete an `Awakeable`, given its id. See [Awakeable identifier](#awakeable-identifier) for more details. |
293-
| `OutputStreamEntryMessage` | `0x0401` | No | No | Carries the invocation output message(s) or terminal failure of the invocation. |
294-
| `SetStateEntryMessage` | `0x0800` | No | No | Set the value of a service instance state key. |
295-
| `ClearStateEntryMessage` | `0x0801` | No | No | Clear the value of a service instance state key. |
296-
| `ClearAllStateEntryMessage` | `0x0802` | No | No | Clear all the values of the service instance state. |
286+
| Message | Type | Completable | Fallible | Description |
287+
| ------------------------------- | -------- | --------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
288+
| `PollInputStreamEntryMessage` | `0x0400` | Yes with value `Payload` | No | Carries the invocation input message(s) of the invocation. Note: currently the runtime always sends this entry completed, but this may change in future. |
289+
| `GetStateEntryMessage` | `0x0800` | Yes with value `Payload` or empty | No | Get the value of a service instance state key. |
290+
| `GetStateKeysEntryMessage` | `0x0804` | Yes with value `GetStateKeysEntryMessage.StateKeys` | No | Get all the known state keys for this service instance. |
291+
| `SleepEntryMessage` | `0x0C00` | Yes only with empty | No | Initiate a timer that completes after the given time. |
292+
| `InvokeEntryMessage` | `0x0C01` | Yes with `Payload` | Yes | Invoke another Restate service. |
293+
| `AwakeableEntryMessage` | `0x0C03` | Yes with `Payload` | No | Arbitrary result container which can be completed from another service, given a specific id. See [Awakeable identifier](#awakeable-identifier) for more details. |
294+
| `BackgroundInvokeEntryMessage` | `0x0C02` | No | Yes | Invoke another Restate service at the given time, without waiting for the response. |
295+
| `CompleteAwakeableEntryMessage` | `0x0C04` | No | Yes | Complete an `Awakeable`, given its id. See [Awakeable identifier](#awakeable-identifier) for more details. |
296+
| `OutputStreamEntryMessage` | `0x0401` | No | No | Carries the invocation output message(s) or terminal failure of the invocation. |
297+
| `SetStateEntryMessage` | `0x0800` | No | No | Set the value of a service instance state key. |
298+
| `ClearStateEntryMessage` | `0x0801` | No | No | Clear the value of a service instance state key. |
299+
| `ClearAllStateEntryMessage` | `0x0802` | No | No | Clear all the values of the service instance state. |
297300

298301
#### Awakeable identifier
299302

0 commit comments

Comments
 (0)