package vmware.concord.execution.v1

Get desktop application:
View/edit binary Protocol Buffers messages

The ExecutionService executes requests submitted by a Concord Replica on behalf of Concord Clients. The scheduling of request execution is coordinated by the Concord Replicas, whereby each replica uses its own ExecutionService to execute requests. An ExecutionService SHOULD support executing many requests in parallel for improved performance.

• rpc Execute (stream MessageToExecuteInstance, stream MessageFromExecuteInstance)

  execution_engine.proto:243

  Execute a single request. Bidirectional streaming is used to interleave request execution and reading values from the KV state of the Concord Replica. The flow in general is: 1. Request execution always starts with the Concord Replica issuing a new `Execute` rpc call, and sending a single `ExecutionRequest` on the rpc call's input stream. 2.a) The rpc call instance can read values from the key-value store by sending one or more `ReadKeysRequest` message on the output stream. 2.b) The Concord Replica answers each `ReadKeysRequests` in the order they are issued using matching `ReadKeysResult` messages. 3. Request execution terminates when the Concord Replica receives an ExecutionResult sent by the rpc call instance. Request execution MUST be deterministic, but MAY cache `ReadKeysResult`s across executions. Request execution MUST by default terminate with an `ExecutionResult`. If an EE fails to produce a result, Concord may retry the request to recover from transient failures. However, a correctly implemented EE should never consistently fail to produce an `ExecutionResult` when processing a specific request. Otherwise, Concord may end up in state where it is unable to make progress. To limit the damages from a misbehaving EE Concord will respond to at most max_ee_read_requests ReadKeysRequest messages where max_ee_read_requests (a configuration parameter in Concord) is set to 10 by default. Fingerprints and caching ------------------------ The KV store associates short unique fingerprints to all key-value pairs. They are used for read-write conflict detection, and can be used for caching the results of reads across `Execute` rpc calls. The fingerprint implementation itself is determined by Concord. There are no guarantees about the contents of the fingerprints and they can be changed at any time. Also there is no guarantee that the A-B-A problem can be detected via fingerprints. The Execution Engine MUST treat the fingerprint as an opaque value. Fingerprints are used as a shorthand for the values in the read set of the execution `ExecutionResult` If a key is not present in the KV Store, the KV Store MUST return `a special` fingerprint (different from all other ones). For illustration, a fingerprint can be the value itself, a hash of the value, or the block height at which the value was written.

  message MessageToExecuteInstance

  execution_engine.proto:251

  Messages sent from a Concord Replica to an EE.

  • oneof message_to_instance

    • ExecutionRequest execution_request = 1

    • ReadKeysResult read_keys_result = 2

  message MessageFromExecuteInstance

  execution_engine.proto:259

  Messages sent from an EE to a Concord Replica.

  • oneof message_from_instance

    • ExecutionResult execution_result = 1

    • ReadKeysRequest read_keys_request = 2

Used in: Event, KeyValueMetadata

• optional AccessControlList.Restricted restricted = 2

  Optional: if absent then the access is unrestricted (public). If present, it can still contain an empty client_id list, which means that no Concord Clients will see the access-controlled data.

Used in: AccessControlList

• repeated string client_id = 1

Used in: ExecutionResult

• bytes payload = 1

  The payload that the EE would like to deliver to the Concord Clients.

• optional AccessControlList access = 2

  The Concord Clients that can see this event's payload.

• bytes key = 3

An execution request submitted by a Concord Client with extra metadata provided by the Concord Replica scheduling its execution.

Used in: MessageToExecuteInstance

• optional google.protobuf.Any application_request = 1

  The actual application request is wrapped in `google.protobuf.Any`. The EE MUST determine the appropriate execution mode based on its `type_url`.

• string submitting_client_id = 2

  The Concord Client id of the client submitting the request. The EE can assume that Concord authenticated this id.

• string correlation_id = 101

  Correlation-id to use in log messages emitted when processing this request. The execution result MUST not depend on this ID.

The result of request execution.

Used in: MessageFromExecuteInstance

• optional google.protobuf.Timestamp min_record_time = 1

  If set, then the execution result is conditional on the record time associated to the request execution being equal or larger than this field.

• optional google.protobuf.Timestamp max_record_time = 2

  If set, then the execution result is conditional on the record time associated to the request execution being smaller or equal than this field.

• optional ReadKeysRequest read_set = 3

  A list of keys stating for every key-value pair the fingerprint that must be associated with it for this request execution to be valid. If any of these fingerprints have changed, the request execution is aborted. This condition is intended to be used to guard against read-write conflicts due to concurrent request execution (both sequential and with pre-execution). Note that keys that are assumed to be non-existent must not have a fingerprint set.

• repeated Event events = 4

  Events to be appended to the event log *provided* the above conditions are satisfied. The event log can be used as message queue with access control to implement exactly-once multi-cast message delivery of events to multiple Concord Clients.

• repeated KeyValueMetadataTriple write_set = 5

  Key-value pairs to be written *provided* the above conditions are satisfied. MUST not contain duplicate keys.

• optional google.protobuf.Any client_response = 6

  Response to be sent by the Concord Client to the application that submitted the request *provided* the above conditions are satisfied. EEs SHOULD document how applications should parse these responses. The EE is responsible for ensuring that the bytes inside the `google.protobuf.Any` are deterministic across the different EE instances executing the request. Protobuf serialization MAY be used, but EE developers should be aware of the caveats that apply wrt deterministic and canonical serialization in Protobuf: https://gist.github.com/kchristidis/39c8b310fd9da43d515c4394c3cd9510

An unambigous reference to a key within a storage space.

Used in: KeyValueMetadataTriple, ReadKeysRequest.ReadKeyRequest, ReadKeysResult.ReadKeyResult

• StorageSpace storage_space = 1

• bytes key = 2

Metadata for key-value pairs written to the KV store.

Used in: KeyValueMetadataTriple.Update

• optional google.protobuf.Timestamp expires_after = 1

  Keys with an expiry will be present in the state until the `expires_after` time as measured by the time service, unless manually deleted before. Concord may delete the key at any time after the expiry time (e.g. as part of Replica pruning), but there is no time bound on when the deletion must happen.

• optional AccessControlList access = 2

  The Concord Clients that are allowed to see this key-value pair. Ignored for keys in STORAGE_SPACE_PLAIN.

Represents a key-value pair with an ACL. There are two possible operations on the key: - update, which either creates new key or updates existing one - delete All fields are required.

Used in: ExecutionResult

• optional KeyReference key = 1

• oneof operation

  • KeyValueMetadataTriple.Update update = 2

  • KeyValueMetadataTriple.Delete delete = 3

Used in: KeyValueMetadataTriple

(message has no fields)

Used in: KeyValueMetadataTriple

• bytes value = 1

• optional KeyValueMetadata metadata = 2

  Hints for Concord on how to handle the KV pair.

A request to atomically read multiple key-value pairs from a replica's KV store. This message is used in two other messages - MessageFromExecuteInstance and ExecutionResult

Used in: ExecutionResult, MessageFromExecuteInstance

• repeated ReadKeysRequest.ReadKeyRequest key_descriptors = 1

  The keys to read.

Used in: ReadKeysRequest

• optional KeyReference key = 1

• optional bytes fingerprint = 2

  Represents the current value of the key according to the EE. If not set - EE considers that the key doesn't exist or is deleted. When defining a read-set, keys that were non-existent at the time of reading will not have this field set either.

The result of a ReadKeysRequest.

Used in: MessageToExecuteInstance

• repeated ReadKeysResult.ReadKeyResult read_key_results = 1

  The read key-value pairs are delivered in the same order as the key_descriptors of the ReadKeysRequest. All results have been read at the same block height (atomic reads).

The result of reading a single key-value pair.

Used in: ReadKeysResult

• optional KeyReference key = 1

• oneof read_result

  • google.protobuf.Empty matching_fingerprint = 2

    A conditional read was made and the fingerprint matches.

  • ReadKeyResult.ValueAndFingerprint value_and_fingerprint = 3

    The read value and its fingerprint.

  • google.protobuf.Empty non_existent = 4

    Key doesn't exist - either not created or deleted.

Used in: ReadKeyResult

• optional bytes value = 1

  Value is returned only if the key has been explicitly created.

• bytes fingerprint = 2

  Note that the fingerprint does not identify the value itself. Instead a fingerprint identifies the fact that the read key is currently assigned the given value. What does this mean in practice? Let's assume the following operations are performed: 1: x=1 with fingerprint f1 2: x=2 with fingerprint f2 3: x=1 with fingerprint f3 Despite x having the same value after operations 1 and 3, there is neither a guarantee that f1 == f3 nor is there a guarantee that f1 != f3. The only guarantee that is given is that if the fingerprints of two key-value pairs (k,v1) and (k,v2) agree, then v1 == v2. This guarantee is sufficient for an EE to do conditional reads.

Concord's key-value store organizes keys within two separate storage spaces: - STORAGE_SPACE_PLAIN: is a key-value store whose entries can only be read by Concord Replicas; and therefore no proof can be provided for these keys. - STORAGE_SPACE_MERKLE: is a key value store whose entries can be read by both Concord replicas and Concord Clients. This key value store allows Concord Clients to receive proofs. Note that these are storage spaces and the same key bytes `k` can be mapped to different values in these two storage spaces. The `KeyReference` type is used to unambigously reference key-value pairs in these storage spaces.

Used in: KeyReference

• STORAGE_SPACE_PLAIN = 0

• STORAGE_SPACE_MERKLE = 1

Contents of a time update entry which contains the block's summarized time.

• optional google.protobuf.Timestamp record_time = 1

• oneof payload

  • google.protobuf.Empty time_update_entry = 101