diff --git a/dev/restate/service/protocol.proto b/dev/restate/service/protocol.proto index 8131bfb..00da7d7 100644 --- a/dev/restate/service/protocol.proto +++ b/dev/restate/service/protocol.proto @@ -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; @@ -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. @@ -111,7 +113,7 @@ message EndMessage { // Type: 0x0400 + 0 message PollInputStreamEntryMessage { oneof result { - bytes value = 14; + Payload value = 14; Failure failure = 15; } } @@ -121,7 +123,7 @@ message PollInputStreamEntryMessage { // Type: 0x0400 + 1 message OutputStreamEntryMessage { oneof result { - bytes value = 14; + Payload value = 14; Failure failure = 15; }; } @@ -136,7 +138,7 @@ message GetStateEntryMessage { oneof result { google.protobuf.Empty empty = 13; - bytes value = 14; + Payload value = 14; Failure failure = 15; }; } @@ -146,7 +148,7 @@ message GetStateEntryMessage { // Type: 0x0800 + 1 message SetStateEntryMessage { bytes key = 1; - bytes value = 3; + Payload value = 3; } // Completable: No @@ -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; }; } @@ -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. @@ -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 @@ -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; }; } @@ -252,7 +252,7 @@ message CompleteAwakeableEntryMessage { string id = 1; oneof result { - bytes value = 5; + Payload value = 5; Failure failure = 6; }; } @@ -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; +} \ No newline at end of file diff --git a/service-invocation-protocol.md b/service-invocation-protocol.md index d592ad0..63b7c90 100644 --- a/service-invocation-protocol.md +++ b/service-invocation-protocol.md @@ -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 @@ -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