// Copyright (c) 2023 - Restate Software, Inc., Restate GmbH
//
// This file is part of the Restate service protocol, which is
// released under the MIT license.
//
// You can find a copy of the license in file LICENSE in the root
// directory of this repository or package, or at
// https://github.com/restatedev/service-protocol/blob/main/LICENSE

syntax = "proto3";

package dev.restate.service.protocol;

option java_package = "dev.restate.generated.service.protocol";
option go_package = "restate.dev/sdk-go/pb/service/protocol";

// Service protocol version.
enum ServiceProtocolVersion {
  SERVICE_PROTOCOL_VERSION_UNSPECIFIED = 0;
  // initial service protocol version
  V1 = 1;
  // Added
  // * Entry retry mechanism: ErrorMessage.next_retry_delay, StartMessage.retry_count_since_last_stored_entry and StartMessage.duration_since_last_stored_entry
  V2 = 2;
}

// --- Core frames ---

// Type: 0x0000 + 0
message StartMessage {
  message StateEntry {
    bytes key = 1;
    // If value is an empty byte array,
    // then it means the value is empty and not "missing" (e.g. empty string).
    bytes value = 2;
  }

  // Unique id of the invocation. This id is unique across invocations and won't change when replaying the journal.
  bytes id = 1;

  // Invocation id that can be used for logging.
  // The user can use this id to address this invocation in admin and status introspection apis.
  string debug_id = 2;

  uint32 known_entries = 3;

  // protolint:disable:next REPEATED_FIELD_NAMES_PLURALIZED
  repeated StateEntry state_map = 4;
  bool partial_state = 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;

  // Retry count since the last stored entry.
  //
  // Please note that this count might not be accurate, as it's not durably stored,
  // thus it might get reset in case Restate crashes/changes leader.
  uint32 retry_count_since_last_stored_entry = 7;

  // Duration since the last stored entry, in milliseconds.
  //
  // Please note this duration might not be accurate,
  // and might change depending on which Restate replica executes the request.
  uint64 duration_since_last_stored_entry = 8;
}

// Type: 0x0000 + 1
message CompletionMessage {
  uint32 entry_index = 1;

  oneof result {
    Empty empty = 13;
    bytes value = 14;
    Failure failure = 15;
  };
}

// Type: 0x0000 + 2
// Implementations MUST send this message when suspending an invocation.
message SuspensionMessage {
  // This list represents any of the entry_index the invocation is waiting on to progress.
  // The runtime will resume the invocation as soon as one of the given entry_index is completed.
  // This list MUST not be empty.
  // False positive, entry_indexes is a valid plural of entry_indices.
  // https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/i/index-indexes-indices
  repeated uint32 entry_indexes = 1;  // protolint:disable:this REPEATED_FIELD_NAMES_PLURALIZED
}

// Type: 0x0000 + 3
message ErrorMessage {
  // The code can be any HTTP status code, as described https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml.
  // In addition, we define the following error codes that MAY be used by the SDK for better error reporting:
  // * JOURNAL_MISMATCH = 570, that is when the SDK cannot replay a journal due to the mismatch between the journal and the actual code.
  // * PROTOCOL_VIOLATION = 571, that is when the SDK receives an unexpected message or an expected message variant, given its state.
  uint32 code = 1;
  // Contains a concise error message, e.g. Throwable#getMessage() in Java.
  string message = 2;
  // Contains a verbose error description, e.g. the exception stacktrace.
  string description = 3;

  // Entry that caused the failure. This may be outside the current stored journal size.
  // If no specific entry caused the failure, the current replayed/processed entry can be used.
  optional uint32 related_entry_index = 4;
  // Name of the entry that caused the failure.
  optional string related_entry_name = 5;
  // Entry type.
  optional uint32 related_entry_type = 6;

  // Delay before executing the next retry, specified as duration in milliseconds.
  // If provided, it will override the default retry policy used by Restate's invoker ONLY for the next retry attempt.
  optional uint64 next_retry_delay = 8;
}

// Type: 0x0000 + 4
message EntryAckMessage {
  uint32 entry_index = 1;
}

// Type: 0x0000 + 5
// Implementations MUST send this message when the invocation lifecycle ends.
message EndMessage {
}

// --- Journal Entries ---

// Every Completable JournalEntry has a result field, filled only and only if the entry is in DONE state.
//
// For every journal entry, fields 12, 13, 14 and 15 are reserved.
//
// The field 12 is used for name. The name is used by introspection/observability tools.
//
// Depending on the semantics of the corresponding syscall, the entry can represent the completion 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
//   * Failure failure = 15 for carrying a failure

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

// Completable: No
// Fallible: No
// Type: 0x0400 + 0
message InputEntryMessage {
  repeated Header headers = 1;

  bytes value = 14;

  // Entry name
  string name = 12;
}

// Completable: No
// Fallible: No
// Type: 0x0400 + 1
message OutputEntryMessage {
  oneof result {
    bytes value = 14;
    Failure failure = 15;
  };

  // Entry name
  string name = 12;
}

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

// Completable: Yes
// Fallible: No
// Type: 0x0800 + 0
message GetStateEntryMessage {
  bytes key = 1;

  oneof result {
    Empty empty = 13;
    bytes value = 14;
    Failure failure = 15;
  };

  // Entry name
  string name = 12;
}

// Completable: No
// Fallible: No
// Type: 0x0800 + 1
message SetStateEntryMessage {
  bytes key = 1;
  bytes value = 3;

  // Entry name
  string name = 12;
}

// Completable: No
// Fallible: No
// Type: 0x0800 + 2
message ClearStateEntryMessage {
  bytes key = 1;

  // Entry name
  string name = 12;
}

// Completable: No
// Fallible: No
// Type: 0x0800 + 3
message ClearAllStateEntryMessage {
  // Entry name
  string name = 12;
}

// Completable: Yes
// Fallible: No
// Type: 0x0800 + 4
message GetStateKeysEntryMessage {
  message StateKeys {
    repeated bytes keys = 1;
  }

  oneof result {
    StateKeys value = 14;
    Failure failure = 15;
  };

  // Entry name
  string name = 12;
}

// Completable: Yes
// Fallible: No
// Type: 0x0800 + 8
message GetPromiseEntryMessage {
  string key = 1;

  oneof result {
    bytes value = 14;
    Failure failure = 15;
  };

  // Entry name
  string name = 12;
}

// Completable: Yes
// Fallible: No
// Type: 0x0800 + 9
message PeekPromiseEntryMessage {
  string key = 1;

  oneof result {
    Empty empty = 13;
    bytes value = 14;
    Failure failure = 15;
  };

  // Entry name
  string name = 12;
}

// Completable: Yes
// Fallible: No
// Type: 0x0800 + A
message CompletePromiseEntryMessage {
  string key = 1;

  // The value to use to complete the promise
  oneof completion {
    bytes completion_value = 2;
    Failure completion_failure = 3;
  };

  oneof result {
    // Returns empty if value was set successfully
    Empty empty = 13;
    // Returns a failure if the promise was already completed
    Failure failure = 15;
  }

  // Entry name
  string name = 12;
}

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

// Completable: Yes
// Fallible: No
// Type: 0x0C00 + 0
message SleepEntryMessage {
  // Wake up time.
  // The time is set as duration since UNIX Epoch.
  uint64 wake_up_time = 1;

  oneof result {
    Empty empty = 13;
    Failure failure = 15;
  }

  // Entry name
  string name = 12;
}

// Completable: Yes
// Fallible: Yes
// Type: 0x0C00 + 1
message CallEntryMessage {
  string service_name = 1;
  string handler_name = 2;

  bytes 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;
    Failure failure = 15;
  };

  // Entry name
  string name = 12;
}

// Completable: No
// Fallible: Yes
// Type: 0x0C00 + 2
message OneWayCallEntryMessage {
  string service_name = 1;
  string handler_name = 2;

  bytes parameter = 3;

  // Time when this BackgroundInvoke should be executed.
  // The time is set as duration since UNIX Epoch.
  // If this value is not set, equal to 0, or past in time,
  // the runtime will execute this BackgroundInvoke as soon as possible.
  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;

  // Entry name
  string name = 12;
}

// 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 {
  oneof result {
    bytes value = 14;
    Failure failure = 15;
  };

  // Entry name
  string name = 12;
}

// Completable: No
// Fallible: Yes
// Type: 0x0C00 + 4
message CompleteAwakeableEntryMessage {
  // Identifier of the awakeable. See the spec for more details.
  string id = 1;

  oneof result {
    bytes value = 14;
    Failure failure = 15;
  };

  // Entry name
  string name = 12;
}

// Completable: No
// Fallible: No
// Type: 0x0C00 + 5
// Flag: RequiresRuntimeAck
message RunEntryMessage {
  oneof result {
    bytes value = 14;
    dev.restate.service.protocol.Failure failure = 15;
  };

  // Entry name
  string name = 12;
}

// --- Nested messages

// This failure object carries user visible errors,
// e.g. invocation failure return value or failure result of an InvokeEntryMessage.
message Failure {
  // The code can be any HTTP status code, as described https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml.
  uint32 code = 1;
  // Contains a concise error message, e.g. Throwable#getMessage() in Java.
  string message = 2;
}

message Header {
  string key = 1;
  string value = 2;
}

message Empty {
}