Skip to content

Commit 2ebdbe0

Browse files
slinkydeveloperslinkydeveloper
committed
Merge commit 'fee21034d86f3a53ee0ee9c409b49950a0bcfce8'
2 parents eebca2c + fee2103 commit 2ebdbe0

File tree

3 files changed

+88
-71
lines changed

3 files changed

+88
-71
lines changed

‎sdk-core/src/main/service-protocol/dev/restate/service/discovery.proto

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
// Copyright (c) 2023 - Restate Software, Inc., Restate GmbH
22
//
3-
// This file is part of the Restate Java SDK,
4-
// which is released under the MIT license.
3+
// This file is part of the Restate service protocol, which is
4+
// released under the MIT license.
55
//
66
// You can find a copy of the license in file LICENSE in the root
77
// directory of this repository or package, or at
8-
// https://github.com/restatedev/sdk-java/blob/main/LICENSE
8+
// https://github.com/restatedev/service-protocol/blob/main/LICENSE
9+
910
syntax = "proto3";
1011

1112
package dev.restate.service.discovery;

‎sdk-core/src/main/service-protocol/dev/restate/service/protocol.proto

Lines changed: 38 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
// Copyright (c) 2023 - Restate Software, Inc., Restate GmbH
22
//
3-
// This file is part of the Restate Java SDK,
4-
// which is released under the MIT license.
3+
// This file is part of the Restate service protocol, which is
4+
// released under the MIT license.
55
//
66
// You can find a copy of the license in file LICENSE in the root
77
// directory of this repository or package, or at
8-
// https://github.com/restatedev/sdk-java/blob/main/LICENSE
8+
// https://github.com/restatedev/service-protocol/blob/main/LICENSE
9+
910
syntax = "proto3";
1011

1112
package dev.restate.service.protocol;
@@ -41,7 +42,6 @@ message StartMessage {
4142
}
4243

4344
// Type: 0x0000 + 1
44-
// Note: Acks to custom messages will have the `empty` field filled.
4545
message CompletionMessage {
4646
uint32 entry_index = 1;
4747

@@ -52,6 +52,11 @@ message CompletionMessage {
5252
};
5353
}
5454

55+
// Type: 0x0000 + 4
56+
message EntryAckMessage {
57+
uint32 entry_index = 1;
58+
}
59+
5560
// Type: 0x0000 + 2
5661
// Implementations MUST send this message when suspending an invocation.
5762
message SuspensionMessage {
@@ -91,13 +96,18 @@ message ErrorMessage {
9196

9297
// ------ Input and output ------
9398

94-
// Kind: Completable JournalEntry
99+
// Completable: Yes
100+
// Fallible: No
95101
// Type: 0x0400 + 0
96102
message PollInputStreamEntryMessage {
97-
bytes value = 14;
103+
oneof result {
104+
bytes value = 14;
105+
Failure failure = 15;
106+
}
98107
}
99108

100-
// Kind: Non-Completable JournalEntry
109+
// Completable: No
110+
// Fallible: No
101111
// Type: 0x0400 + 1
102112
message OutputStreamEntryMessage {
103113
oneof result {
@@ -108,43 +118,52 @@ message OutputStreamEntryMessage {
108118

109119
// ------ State access ------
110120

111-
// Kind: Completable JournalEntry
121+
// Completable: Yes
122+
// Fallible: No
112123
// Type: 0x0800 + 0
113124
message GetStateEntryMessage {
114125
bytes key = 1;
115126

116127
oneof result {
117128
google.protobuf.Empty empty = 13;
118129
bytes value = 14;
130+
Failure failure = 15;
119131
};
120132
}
121133

122-
// Kind: Non-Completable JournalEntry
134+
// Completable: No
135+
// Fallible: No
123136
// Type: 0x0800 + 1
124137
message SetStateEntryMessage {
125138
bytes key = 1;
126139
bytes value = 3;
127140
}
128141

129-
// Kind: Non-Completable JournalEntry
142+
// Completable: No
143+
// Fallible: No
130144
// Type: 0x0800 + 2
131145
message ClearStateEntryMessage {
132146
bytes key = 1;
133147
}
134148

135149
// ------ Syscalls ------
136150

137-
// Kind: Completable JournalEntry
151+
// Completable: Yes
152+
// Fallible: No
138153
// Type: 0x0C00 + 0
139154
message SleepEntryMessage {
140155
// Wake up time.
141156
// The time is set as duration since UNIX Epoch.
142157
uint64 wake_up_time = 1;
143158

144-
google.protobuf.Empty result = 13;
159+
oneof result {
160+
google.protobuf.Empty empty = 13;
161+
Failure failure = 15;
162+
}
145163
}
146164

147-
// Kind: Completable JournalEntry
165+
// Completable: Yes
166+
// Fallible: Yes
148167
// Type: 0x0C00 + 1
149168
message InvokeEntryMessage {
150169
string service_name = 1;
@@ -158,7 +177,8 @@ message InvokeEntryMessage {
158177
};
159178
}
160179

161-
// Kind: Non-Completable JournalEntry
180+
// Completable: No
181+
// Fallible: Yes
162182
// Type: 0x0C00 + 2
163183
message BackgroundInvokeEntryMessage {
164184
string service_name = 1;
@@ -173,7 +193,8 @@ message BackgroundInvokeEntryMessage {
173193
uint64 invoke_time = 4;
174194
}
175195

176-
// Kind: Completable JournalEntry
196+
// Completable: Yes
197+
// Fallible: No
177198
// Type: 0x0C00 + 3
178199
// Awakeables are addressed by an identifier exposed to the user. See the spec for more details.
179200
message AwakeableEntryMessage {
@@ -183,7 +204,8 @@ message AwakeableEntryMessage {
183204
};
184205
}
185206

186-
// Kind: Non-Completable JournalEntry
207+
// Completable: No
208+
// Fallible: Yes
187209
// Type: 0x0C00 + 4
188210
message CompleteAwakeableEntryMessage {
189211
// Identifier of the awakeable. See the spec for more details.

‎sdk-core/src/main/service-protocol/service-invocation-protocol.md

Lines changed: 46 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -161,49 +161,38 @@ Flags:
161161

162162
### Entries and Completions
163163

164-
We distinguish among two types of journal entries:
164+
For each journal entry the runtime commits the entry message and executes the corresponding action atomically. The
165+
runtime won't commit the entry, nor perform the action, if the entry is invalid. If an entry is not committed, all the
166+
subsequent entries are not committed as well.
165167

166-
- Completable journal entries. These represent actions the runtime will perform, and for which consequently provide a
167-
completion value. All these entries have a `result` field defined in the message descriptor, defining the different
168-
variants of the completion value, and have a `COMPLETED` flag in the header.
169-
- Non-completable journal entries. These represent actions the runtime will perform, but won't provide any completion
170-
value to it.
168+
Entries can be:
171169

172-
Whether a journal entry is completable or not is intrinsic in the definition of the journal action itself.
170+
- Completable or not: These represent actions the runtime will perform, and for which consequently provide a completion
171+
value. All these entries have a `result` field defined in the message descriptor, defining the different variants of
172+
the completion value, and have a `COMPLETED` flag in the header.
173+
- Fallible or not: These can be rejected by the runtime when trying to commit them. The failure is not recorded in the
174+
journal, thus the runtime will abort the stream after receiving an invalid entry from the SDK.
175+
176+
The type of the journal entry is intrinsic in the definition of the journal action itself.
173177

174178
The header format for journal entries applies both when the runtime is sending entries to the SDK during a replay, and
175179
when the SDK sends entries to the runtime during processing.
176180

177181
**Headers**
178182

179-
Completable journal entries:
180-
181-
0 1 2 3
182-
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
183-
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
184-
| Type | Reserved |C|
185-
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
186-
| Length |
187-
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
188-
189-
Flags:
190-
191-
- 15 bits (MSB): Reserved
192-
- 1 bit `C`: `COMPLETED` flag. Mask: `0x0000_0001_0000_0000`
193-
194-
Non-Completable journal entries:
195-
196183
0 1 2 3
197184
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
198185
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
199-
| Type | Reserved |
186+
| Type |A| Reserved |C|
200187
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
201188
| Length |
202189
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
203190

204191
Flags:
205192

206-
- 16 bits (MSB): Reserved
193+
- 1 bit (MSB) `A`: [`REQUIRES_ACK` flag](#acknowledgment-of-stored-entries). Mask: `0x0000_8000_0000_0000`
194+
- 14 bits: Reserved
195+
- 1 bit `C`: `COMPLETED` flag (only Completable journal entries). Mask: `0x0000_0001_0000_0000`
207196

208197
#### Completable journal entries and `CompletionMessage`
209198

@@ -240,30 +229,39 @@ which `result`s the SDK is interested, and in which order.
240229
| Length |
241230
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
242231

243-
### Journal entries reference
232+
#### Acknowledgment of stored entries
244233

245-
The following tables describe the currently available journal entries. For more details, check the protobuf message
246-
descriptions in [`protocol.proto`](dev/restate/service/protocol.proto).
234+
If the SDK needs an acknowledgment that a journal entry, of any type, has been persisted, it can set the `REQUIRES_ACK`
235+
flag in the header. When set, as soon as the entry is persisted, the runtime will send back a `EntryAckMessage` with the
236+
index of the corresponding entry.
237+
238+
**`EntryAckMessage` Header**
247239

248-
**Completable journal entries**
240+
0 1 2 3
241+
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
242+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
243+
| 0x0004 | Reserved |
244+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
245+
| Length |
246+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
249247

250-
| Message | Type | Description |
251-
| ----------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
252-
| `PollInputStreamEntryMessage` | `0x0400` | Carries the service method input message(s) of the invocation. Note: currently the runtime always sends this entry completed, but this may change in future. |
253-
| `GetStateEntryMessage` | `0x0800` | Get the value of a service instance state key. |
254-
| `SleepEntryMessage` | `0x0C00` | Initiate a timer that completes after the given time. |
255-
| `InvokeEntryMessage` | `0x0C01` | Invoke another Restate service. |
256-
| `AwakeableEntryMessage` | `0x0C03` | Arbitrary result container which can be completed from another service, given a specific id. See [Awakeable identifier](#awakeable-identifier) for more details. |
248+
### Journal entries reference
257249

258-
**Non-Completable journal entries**
250+
The following tables describe the currently available journal entries. For more details, check the protobuf message
251+
descriptions in [`protocol.proto`](dev/restate/service/protocol.proto).
259252

260-
| Message | Type | Description |
261-
| ------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
262-
| `OutputStreamEntryMessage` | `0x0401` | Carries the service method output message(s) or terminal failure of the invocation. Note: currently the runtime accepts only one entry of this type, but this may change in future. |
263-
| `SetStateEntryMessage` | `0x0800` | Set the value of a service instance state key. |
264-
| `ClearStateEntryMessage` | `0x0801` | Clear the value of a service instance state key. |
265-
| `BackgroundInvokeEntryMessage` | `0x0C02` | Invoke another Restate service at the given time, without waiting for the response. |
266-
| `CompleteAwakeableEntryMessage` | `0x0C04` | Complete an `Awakeable`, given its id. See [Awakeable identifier](#awakeable-identifier) for more details. |
253+
| Message | Type | Completable | Fallible | Description |
254+
| ------------------------------- | -------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
255+
| `PollInputStreamEntryMessage` | `0x0400` | Yes | No | Carries the service method input message(s) of the invocation. Note: currently the runtime always sends this entry completed, but this may change in future. |
256+
| `GetStateEntryMessage` | `0x0800` | Yes | No | Get the value of a service instance state key. |
257+
| `SleepEntryMessage` | `0x0C00` | Yes | No | Initiate a timer that completes after the given time. |
258+
| `InvokeEntryMessage` | `0x0C01` | Yes | Yes | Invoke another Restate service. |
259+
| `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. |
260+
| `BackgroundInvokeEntryMessage` | `0x0C02` | No | Yes | Invoke another Restate service at the given time, without waiting for the response. |
261+
| `CompleteAwakeableEntryMessage` | `0x0C04` | No | Yes | Complete an `Awakeable`, given its id. See [Awakeable identifier](#awakeable-identifier) for more details. |
262+
| `OutputStreamEntryMessage` | `0x0401` | No | No | Carries the service method output message(s) or terminal failure of the invocation. Note: currently the runtime accepts only one entry of this type, but this may change in future. |
263+
| `SetStateEntryMessage` | `0x0800` | No | No | Set the value of a service instance state key. |
264+
| `ClearStateEntryMessage` | `0x0801` | No | No | Clear the value of a service instance state key. |
267265

268266
#### Awakeable identifier
269267

@@ -332,16 +330,12 @@ additional features to the users.
332330
The protocol allows the SDK to register an arbitrary entry type within the journal. The type MUST be `>= 0xFC00`. The
333331
runtime will treat this entry as any other entry, persisting it and sending it during replay in the correct order.
334332

335-
If the SDK needs an acknowledgment that the entry has been persisted, it can set the `REQUIRES_ACK` flag in the header.
336-
When set, as soon as the entry is persisted, the runtime will send back a `CompletionMessage` with the `result.empty`
337-
field set, as described in [Entries and Completions section](#entries-and-completions).
338-
339333
**Header**
340334

341335
0 1 2 3
342336
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
343337
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
344-
| Type | Reserved |A|
338+
| Type |A| Reserved |
345339
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
346340
| Length |
347341
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
@@ -350,8 +344,8 @@ field set, as described in [Entries and Completions section](#entries-and-comple
350344

351345
Flags:
352346

353-
- 15 bits (MSB): Reserved
354-
- 1 bit `A`: `REQUIRES_ACK` flag. Mask: `0x0000_0001_0000_0000`
347+
- 1 bit (MSB) `A`: [`REQUIRES_ACK` flag](#acknowledgment-of-stored-entries). Mask: `0x0000_8000_0000_0000`
348+
- 15 bits: Reserved
355349

356350
### Eager state
357351

0 commit comments

Comments
 (0)