Skip to content

Commit

Permalink
Introduce the distinction fallible journal entries/actionable journal…
Browse files Browse the repository at this point in the history 
… entries (#50)

* Introduce the distinction fallible journal entries/actionable journal entries

* Feedback
  • Loading branch information
@slinkydeveloper
slinkydeveloper authored Dec 14, 2023
1 parent b86343b commit 98ec66e
Show file tree
Hide file tree
Showing 2 changed files with 44 additions and 54 deletions.
30 changes: 20 additions & 10 deletions dev/restate/service/protocol.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -96,13 +96,15 @@ message ErrorMessage {

// ------ Input and output ------

// Kind: Completable JournalEntry
// Completable: Yes
// Fallible: No
// Type: 0x0400 + 0
message PollInputStreamEntryMessage {
bytes value = 14;
}

// Kind: Non-Completable JournalEntry
// Completable: No
// Fallible: No
// Type: 0x0400 + 1
message OutputStreamEntryMessage {
oneof result {
Expand All @@ -113,7 +115,8 @@ message OutputStreamEntryMessage {

// ------ State access ------

// Kind: Completable JournalEntry
// Completable: Yes
// Fallible: No
// Type: 0x0800 + 0
message GetStateEntryMessage {
bytes key = 1;
Expand All @@ -124,22 +127,25 @@ message GetStateEntryMessage {
};
}

// Kind: Non-Completable JournalEntry
// Completable: No
// Fallible: No
// Type: 0x0800 + 1
message SetStateEntryMessage {
bytes key = 1;
bytes value = 3;
}

// Kind: Non-Completable JournalEntry
// Completable: No
// Fallible: No
// Type: 0x0800 + 2
message ClearStateEntryMessage {
bytes key = 1;
}

// ------ Syscalls ------

// Kind: Completable JournalEntry
// Completable: Yes
// Fallible: No
// Type: 0x0C00 + 0
message SleepEntryMessage {
// Wake up time.
Expand All @@ -149,7 +155,8 @@ message SleepEntryMessage {
google.protobuf.Empty result = 13;
}

// Kind: Completable JournalEntry
// Completable: Yes
// Fallible: Yes
// Type: 0x0C00 + 1
message InvokeEntryMessage {
string service_name = 1;
Expand All @@ -163,7 +170,8 @@ message InvokeEntryMessage {
};
}

// Kind: Non-Completable JournalEntry
// Completable: No
// Fallible: Yes
// Type: 0x0C00 + 2
message BackgroundInvokeEntryMessage {
string service_name = 1;
Expand All @@ -178,7 +186,8 @@ message BackgroundInvokeEntryMessage {
uint64 invoke_time = 4;
}

// Kind: Completable JournalEntry
// Completable: Yes
// Fallible: No
// Type: 0x0C00 + 3
// Awakeables are addressed by an identifier exposed to the user. See the spec for more details.
message AwakeableEntryMessage {
Expand All @@ -188,7 +197,8 @@ message AwakeableEntryMessage {
};
}

// Kind: Non-Completable JournalEntry
// Completable: No
// Fallible: Yes
// Type: 0x0C00 + 4
message CompleteAwakeableEntryMessage {
// Identifier of the awakeable. See the spec for more details.
Expand Down
68 changes: 24 additions & 44 deletions service-invocation-protocol.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -161,23 +161,25 @@ Flags:

### Entries and Completions

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

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

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

The type of the journal entry is intrinsic in the definition of the journal action itself.

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

**Headers**

Completable journal entries:

0 1 2 3
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Expand All @@ -190,22 +192,7 @@ Flags:

- 1 bit (MSB) `A`: [`REQUIRES_ACK` flag](#acknowledgment-of-stored-entries). Mask: `0x0000_8000_0000_0000`
- 14 bits: Reserved
- 1 bit `C`: `COMPLETED` flag. Mask: `0x0000_0001_0000_0000`

Non-Completable journal entries:

0 1 2 3
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type |A| Reserved |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Flags:

- 1 bit (MSB) `A`: [`REQUIRES_ACK` flag](#acknowledgment-of-stored-entries). Mask: `0x0000_8000_0000_0000`
- 15 bits (MSB): Reserved
- 1 bit `C`: `COMPLETED` flag (only Completable journal entries). Mask: `0x0000_0001_0000_0000`

#### Completable journal entries and `CompletionMessage`

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

**Completable journal entries**

| Message | Type | Description |
| ----------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
| `GetStateEntryMessage` | `0x0800` | Get the value of a service instance state key. |
| `SleepEntryMessage` | `0x0C00` | Initiate a timer that completes after the given time. |
| `InvokeEntryMessage` | `0x0C01` | Invoke another Restate service. |
| `AwakeableEntryMessage` | `0x0C03` | Arbitrary result container which can be completed from another service, given a specific id. See [Awakeable identifier](#awakeable-identifier) for more details. |

**Non-Completable journal entries**

| Message | Type | Description |
| ------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
| `SetStateEntryMessage` | `0x0800` | Set the value of a service instance state key. |
| `ClearStateEntryMessage` | `0x0801` | Clear the value of a service instance state key. |
| `BackgroundInvokeEntryMessage` | `0x0C02` | Invoke another Restate service at the given time, without waiting for the response. |
| `CompleteAwakeableEntryMessage` | `0x0C04` | Complete an `Awakeable`, given its id. See [Awakeable identifier](#awakeable-identifier) for more details. |
| Message | Type | Completable | Fallible | Description |
| ------------------------------- | -------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
| `GetStateEntryMessage` | `0x0800` | Yes | No | Get the value of a service instance state key. |
| `SleepEntryMessage` | `0x0C00` | Yes | No | Initiate a timer that completes after the given time. |
| `InvokeEntryMessage` | `0x0C01` | Yes | Yes | Invoke another Restate service. |
| `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. |
| `BackgroundInvokeEntryMessage` | `0x0C02` | No | Yes | Invoke another Restate service at the given time, without waiting for the response. |
| `CompleteAwakeableEntryMessage` | `0x0C04` | No | Yes | Complete an `Awakeable`, given its id. See [Awakeable identifier](#awakeable-identifier) for more details. |
| `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. |
| `SetStateEntryMessage` | `0x0800` | No | No | Set the value of a service instance state key. |
| `ClearStateEntryMessage` | `0x0801` | No | No | Clear the value of a service instance state key. |

#### Awakeable identifier

Expand Down

0 comments on commit 98ec66e

Please sign in to comment.