Skip to content

Commit 4f08e24

Browse files
slinkydeveloperslinkydeveloper
committed
Squashed 'sdk-core/src/main/service-protocol/' changes from 185da8b..8a5b977
8a5b977 Reintroduce error message (#61) 5417fee Modify End of Stream. (#51) git-subtree-dir: sdk-core/src/main/service-protocol git-subtree-split: 8a5b9770425dc8c6683ab744c0d5abb258e04467
1 parent bac6768 commit 4f08e24

File tree

2 files changed

+71
-36
lines changed

2 files changed

+71
-36
lines changed

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

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -52,11 +52,6 @@ message CompletionMessage {
5252
};
5353
}
5454

55-
// Type: 0x0000 + 4
56-
message EntryAckMessage {
57-
uint32 entry_index = 1;
58-
}
59-
6055
// Type: 0x0000 + 2
6156
// Implementations MUST send this message when suspending an invocation.
6257
message SuspensionMessage {
@@ -83,6 +78,16 @@ message ErrorMessage {
8378
string description = 3;
8479
}
8580

81+
// Type: 0x0000 + 4
82+
message EntryAckMessage {
83+
uint32 entry_index = 1;
84+
}
85+
86+
// Type: 0x0000 + 5
87+
// Implementations MUST send this message when the invocation lifecycle ends.
88+
message EndMessage {
89+
}
90+
8691
// --- Journal Entries ---
8792

8893
// Every Completable JournalEntry has a result field, filled only and only if the entry is in DONE state.

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

Lines changed: 61 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -27,21 +27,31 @@ Every invocation state machine begins when the stream is opened and ends when th
2727
arbitrary interaction can be performed from the Service endpoint to the Runtime and vice versa via well-defined
2828
messages.
2929

30-
### Syscalls
31-
32-
Most Restate features, such as interaction with other services, accessing service instance state, and so on, are defined
33-
as _Restate syscalls_ and exposed through the service protocol. The user interacts with these syscalls using the SDK
34-
APIs, which generate _Journal Entry_ messages that will be handled by the invocation state machine.
35-
36-
Depending on the specific syscall, the Restate runtime generates as response either:
37-
38-
- A completion, that is the response to the syscall
39-
- An ack, that is a confirmation the syscall has been persisted and **will** be executed
40-
- Nothing
41-
42-
Each syscall defines a priori whether it replies with an ack or a completion, or doesn't reply at all.
43-
44-
There are a couple of special message streams for initializing and closing the invocation.
30+
The state machine is summarized in the following diagram:
31+
32+
```mermaid
33+
sequenceDiagram
34+
Note over Runtime,SDK: Start
35+
Runtime->>SDK: HTTP Request to /invoke/{service}/{method}
36+
Runtime->>SDK: StartMessage
37+
Note over Runtime,SDK: Replaying
38+
Runtime->>SDK: [...]EntryMessage(s)
39+
Note over Runtime,SDK: Processing
40+
loop
41+
SDK->>Runtime: [...]EntryMessage
42+
Runtime->>SDK: CompletionMessage and/or EntryAckMessage
43+
end
44+
Note over SDK: Reached close condition
45+
alt
46+
SDK->>Runtime: SuspensionMessage
47+
else
48+
SDK->>Runtime: ErrorMessage
49+
else
50+
SDK->>Runtime: EndMessage
51+
end
52+
SDK->>Runtime: Close HTTP Response
53+
Note over Runtime,SDK: Closed
54+
```
4555

4656
### Replaying and Processing
4757

@@ -64,6 +74,20 @@ There are a couple of properties that we enforce through the design of the proto
6474
- Only in processing state the runtime can send
6575
[`CompletionMessage`](#completable-journal-entries-and-completionmessage)
6676

77+
### Syscalls
78+
79+
Most Restate features, such as interaction with other services, accessing service instance state, and so on, are defined
80+
as _Restate syscalls_ and exposed through the service protocol. The user interacts with these syscalls using the SDK
81+
APIs, which generate _Journal Entry_ messages that will be handled by the invocation state machine.
82+
83+
Depending on the specific syscall, the Restate runtime generates as response either:
84+
85+
- A completion, that is the response to the syscall
86+
- An ack, that is a confirmation the syscall has been persisted and **will** be executed
87+
- Nothing
88+
89+
Each syscall defines a priori whether it replies with an ack or a completion, or doesn't reply at all.
90+
6791
## Messages
6892

6993
The protocol is composed by messages that are sent back and forth between runtime and service Endpoint. The protocol
@@ -73,6 +97,8 @@ mandates the following messages:
7397
- `[..]EntryMessage`
7498
- `CompletionMessage`
7599
- `SuspensionMessage`
100+
- `EntryAckMessage`
101+
- `EndMessage`
76102

77103
### Message stream
78104

@@ -112,10 +138,14 @@ the stream replying back with a `404` status code.
112138

113139
A message stream MUST start with `StartMessage` and MUST end with either:
114140

115-
- One `OutputStreamEntry`
116141
- One [`SuspensionMessage`](#suspension)
117-
- One [`ErrorMessage`](#failures).
118-
- None of the above, which is equivalent to sending an empty [`ErrorMessage`](#failures).
142+
- One [`ErrorMessage`](#failures)
143+
- One `EndMessage`
144+
145+
If the message stream does not end with any of these two messages, it will be considered equivalent to sending an
146+
`ErrorMessage` with an [unknown failure](#failures).
147+
148+
The `EndMessage` marks the end of the invocation lifecycle, that is the end of the journal.
119149

120150
### Message header
121151

@@ -250,18 +280,18 @@ index of the corresponding entry.
250280
The following tables describe the currently available journal entries. For more details, check the protobuf message
251281
descriptions in [`protocol.proto`](dev/restate/service/protocol.proto).
252282

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. |
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+
| `SleepEntryMessage` | `0x0C00` | Yes | No | Initiate a timer that completes after the given time. |
288+
| `InvokeEntryMessage` | `0x0C01` | Yes | Yes | Invoke another Restate service. |
289+
| `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. |
290+
| `BackgroundInvokeEntryMessage` | `0x0C02` | No | Yes | Invoke another Restate service at the given time, without waiting for the response. |
291+
| `CompleteAwakeableEntryMessage` | `0x0C04` | No | Yes | Complete an `Awakeable`, given its id. See [Awakeable identifier](#awakeable-identifier) for more details. |
292+
| `OutputStreamEntryMessage` | `0x0401` | No | No | Carries the invocation output message(s) or terminal failure of the invocation. |
293+
| `SetStateEntryMessage` | `0x0800` | No | No | Set the value of a service instance state key. |
294+
| `ClearStateEntryMessage` | `0x0801` | No | No | Clear the value of a service instance state key. |
265295

266296
#### Awakeable identifier
267297

@@ -299,7 +329,7 @@ To notify a failure, the SDK can either:
299329

300330
- Close the stream with `ErrorMessage` as last message. This message is used by the runtime for accurate reporting to
301331
the user.
302-
- Close the stream without `OutputStreamEntry` or `SuspensionMessage` or `ErrorMessage`. This is equivalent to sending
332+
- Close the stream without `EndMessage` or `SuspensionMessage` or `ErrorMessage`. This is equivalent to sending
303333
an `ErrorMessage` with unknown reason.
304334

305335
The runtime takes care of retrying to execute the invocation after such failures occur, following a defined set of

0 commit comments

Comments
 (0)