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

Commit

Permalink
Carry around format information in the protocol.
Browse files Browse the repository at this point in the history
  • Loading branch information
@slinkydeveloper
slinkydeveloper committed Feb 20, 2024
1 parent d909638 commit e34e186
Show file tree
Hide file tree
Showing 2 changed files with 47 additions and 30 deletions.
46 changes: 30 additions & 16 deletions dev/restate/service/protocol.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,8 @@ message StartMessage {
}

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

Expand Down Expand Up @@ -99,7 +101,7 @@ message EndMessage {
// Depending on the semantics of the corresponding syscall, the entry can represent the result field with any of these three types:
//
// * google.protobuf.Empty empty = 13 for cases when we need to propagate to user code the distinction between default value or no value.
// * bytes value = 14 for carrying the result value
// * T value = 14 for carrying the result value. The value carried by CompletionMessage carry the same type T carried here.
// * Failure failure = 15 for carrying a failure
//
// The tag numbers 13, 14 and 15 are reserved and shouldn't be used for other fields.
Expand All @@ -111,7 +113,7 @@ message EndMessage {
// Type: 0x0400 + 0
message PollInputStreamEntryMessage {
oneof result {
bytes value = 14;
Payload value = 14;
Failure failure = 15;
}
}
Expand All @@ -121,7 +123,7 @@ message PollInputStreamEntryMessage {
// Type: 0x0400 + 1
message OutputStreamEntryMessage {
oneof result {
bytes value = 14;
Payload value = 14;
Failure failure = 15;
};
}
Expand All @@ -136,7 +138,7 @@ message GetStateEntryMessage {

oneof result {
google.protobuf.Empty empty = 13;
bytes value = 14;
Payload value = 14;
Failure failure = 15;
};
}
Expand All @@ -146,7 +148,7 @@ message GetStateEntryMessage {
// Type: 0x0800 + 1
message SetStateEntryMessage {
bytes key = 1;
bytes value = 3;
Payload value = 3;
}

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

bytes parameter = 3;
Payload parameter = 3;

repeated Header headers = 4;

// If this invocation has a key associated (e.g. for objects and workflows), then this key is filled in. Empty otherwise.
string key = 5;

oneof result {
bytes value = 14;
Payload value = 14;
Failure failure = 15;
};
}
Expand All @@ -218,8 +219,10 @@ message InvokeEntryMessage {
message BackgroundInvokeEntryMessage {
string service_name = 1;
string method_name = 2;
// If this invocation has a key associated (e.g. for objects and workflows), then this key is filled in. Empty otherwise.
string key = 6;

bytes parameter = 3;
Payload parameter = 3;

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

repeated Header headers = 5;

// If this invocation has a key associated (e.g. for objects and workflows), then this key is filled in. Empty otherwise.
string key = 6;
}

// Completable: Yes
Expand All @@ -239,7 +239,7 @@ message BackgroundInvokeEntryMessage {
// Awakeables are addressed by an identifier exposed to the user. See the spec for more details.
message AwakeableEntryMessage {
oneof result {
bytes value = 14;
Payload value = 14;
Failure failure = 15;
};
}
Expand All @@ -252,7 +252,7 @@ message CompleteAwakeableEntryMessage {
string id = 1;

oneof result {
bytes value = 5;
Payload value = 5;
Failure failure = 6;
};
}
Expand All @@ -275,3 +275,17 @@ message Header {
string key = 1;
string value = 2;
}

// Payload is a generic message used to carry around a value with some format metadata.
// Those metadata are mostly used by runtime observability tools and to aid the SDK to deserialize the payload.
message Payload {
bytes value = 1;
Format format = 2;
}

// Format of the payload/state entry.
enum Format {
UNKNOWN = 0;
JSON = 1;
UTF8_STRING = 2;
}
31 changes: 17 additions & 14 deletions service-invocation-protocol.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -249,6 +249,9 @@ also not be interested in the `result` of completable journal entries, or it mig
different order used to create the related journal entries. Usually it's the service business logic that dictates in
which `result`s the SDK is interested, and in which order.

The content of `CompletionMessage.value` depends on the completed entry itself, see
[Journal entries reference](#journal-entries-reference) for more details.

**`CompletionMessage` Header**

0 1 2 3
Expand Down Expand Up @@ -280,20 +283,20 @@ 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).

| Message | Type | Completable | Fallible | Description |
| ------------------------------- | -------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
| `GetStateEntryMessage` | `0x0800` | Yes | No | Get the value of a service instance state key. |
| `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`. |
| `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 invocation output message(s) or terminal failure of the invocation. |
| `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. |
| `ClearAllStateEntryMessage` | `0x0802` | No | No | Clear all the values of the service instance state. |
| Message | Type | Completable | Fallible | Description |
| ------------------------------- | -------- | --------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
| `GetStateEntryMessage` | `0x0800` | Yes with value `Payload` or empty | No | Get the value of a service instance state key. |
| `GetStateKeysEntryMessage` | `0x0804` | Yes with value `GetStateKeysEntryMessage.StateKeys` | No | Get all the known state keys for this service instance. |
| `SleepEntryMessage` | `0x0C00` | Yes only with empty | No | Initiate a timer that completes after the given time. |
| `InvokeEntryMessage` | `0x0C01` | Yes with `Payload` | Yes | Invoke another Restate service. |
| `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. |
| `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 invocation output message(s) or terminal failure of the invocation. |
| `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. |
| `ClearAllStateEntryMessage` | `0x0802` | No | No | Clear all the values of the service instance state. |

#### Awakeable identifier

Expand Down

0 comments on commit e34e186

Please sign in to comment.