package spec.proto.runtime.v1
Get desktop application:
View/edit binary Protocol Buffers messages
service AppCallback
appcallback.proto:16AppCallback V1 allows user application to interact with runtime. User application needs to implement AppCallback service if it needs to receive message from runtime.
Lists all topics subscribed by this app.
message
appcallback.proto:80ListTopicSubscriptionsResponse is the message including the list of the subscribing topics.
repeated subscriptions = 1
The list of topics.
rpc OnTopicEvent (, )
appcallback.proto:22Subscribes events from Pubsub
service Lifecycle
lifecycle.proto:11Lifecycle API is used to manage the sidecar lifecycle. For example, by invoking the lifecycle API, you can modify the components' configuration during runtime
rpc ApplyConfiguration (, )
lifecycle.proto:15Apply the dynamic configuration. The DynamicConfiguration here should be full configuration, not incremental configuration
message
lifecycle.proto:20The dynamic configuration of the sidecar
optional component_config = 1
Required. The dynamic configuration of a component
message
lifecycle.proto:28The response of the `ApplyConfiguration` method.
(message has no fields)
service Runtime
runtime.proto:15Runtime encapsulates variours Runtime APIs(such as Configuration API, Pub/Sub API, etc)
rpc SayHello (, )
runtime.proto:17SayHello used for test
message
runtime.proto:345Hello request message
string service_name = 1
The name of service
string name = 2
Reuqest name
optional data = 3
Optional. This field is used to control the packet size during load tests.
message
runtime.proto:355Hello response message
string hello = 1
Hello
optional data = 2
Hello message of data
rpc InvokeService (, )
runtime.proto:20InvokeService do rpc calls
message
runtime.proto:363Invoke service request message
string id = 1
The identify of InvokeServiceRequest
optional message = 3
InvokeServiceRequest message
message
runtime.proto:416Invoke service response message is result of invoke service queset
optional data = 1
The response data
string content_type = 2
The content type of response data
rpc GetConfiguration (, )
runtime.proto:23GetConfiguration gets configuration from configuration store.
message
runtime.proto:446GetConfigurationRequest is the message to get a list of key-value configuration from specified configuration store.
string store_name = 1
The name of configuration store.
string app_id = 2
The application id which Only used for admin, Ignored and reset for normal client
string group = 3
The group of keys.
string label = 4
The label for keys.
repeated string keys = 5
The keys to get.
map<string, string> metadata = 6
The metadata which will be sent to configuration store components.
bool subscribe_update = 7
Subscribes update event for given keys. If true, when any configuration item in this request is updated, app will receive event by OnConfigurationEvent() of app callback
message
runtime.proto:472GetConfigurationResponse is the response conveying the list of configuration values.
repeated items = 1
The list of items containing configuration values.
rpc SaveConfiguration (, )
runtime.proto:26SaveConfiguration saves configuration into configuration store.
message
runtime.proto:513SaveConfigurationRequest is the message to save a list of key-value configuration into specified configuration store.
string store_name = 1
The name of configuration store.
string app_id = 2
The application id which Only used for admin, ignored and reset for normal client
repeated items = 3
The list of configuration items to save. To delete a exist item, set the key (also label) and let content to be empty
map<string, string> metadata = 4
The metadata which will be sent to configuration store components.
rpc DeleteConfiguration (, )
runtime.proto:29DeleteConfiguration deletes configuration from configuration store.
message
runtime.proto:530DeleteConfigurationRequest is the message to delete a list of key-value configuration from specified configuration store.
string store_name = 1
The name of configuration store.
string app_id = 2
The application id which Only used for admin, Ignored and reset for normal client
string group = 3
The group of keys.
string label = 4
The label for keys.
repeated string keys = 5
The keys to get.
map<string, string> metadata = 6
The metadata which will be sent to configuration store components.
rpc SubscribeConfiguration (stream , stream )
runtime.proto:32SubscribeConfiguration gets configuration from configuration store and subscribe the updates.
message
runtime.proto:478SubscribeConfigurationRequest is the message to get a list of key-value configuration from specified configuration store.
string store_name = 1
The name of configuration store.
string app_id = 2
The application id which Only used for admin, ignored and reset for normal client
string group = 3
The group of keys.
string label = 4
The label for keys.
repeated string keys = 5
The keys to get.
map<string, string> metadata = 6
The metadata which will be sent to configuration store components.
message
runtime.proto:500SubscribeConfigurationResponse is the response conveying the list of configuration values.
string store_name = 1
The name of configuration store.
string app_id = 2
The application id. Only used for admin client.
repeated items = 3
The list of items containing configuration values.
rpc TryLock (, )
runtime.proto:36Distributed Lock API A non-blocking method trying to get a lock with ttl.
message
runtime.proto:255Lock request message is distributed lock API which is not blocking method tring to get a lock with ttl
string store_name = 1
Required. The lock store name,e.g. `redis`.
string resource_id = 2
Required. resource_id is the lock key. e.g. `order_id_111` It stands for "which resource I want to protect"
string lock_owner = 3
Required. lock_owner indicate the identifier of lock owner. You can generate a uuid as lock_owner.For example,in golang: req.LockOwner = uuid.New().String() This field is per request,not per process,so it is different for each request, which aims to prevent multi-thread in the same process trying the same lock concurrently. The reason why we don't make it automatically generated is: 1. If it is automatically generated,there must be a 'my_lock_owner_id' field in the response. This name is so weird that we think it is inappropriate to put it into the api spec 2. If we change the field 'my_lock_owner_id' in the response to 'lock_owner',which means the current lock owner of this lock, we find that in some lock services users can't get the current lock owner.Actually users don't need it at all. 3. When reentrant lock is needed,the existing lock_owner is required to identify client and check "whether this client can reenter this lock". So this field in the request shouldn't be removed.
int32 expire = 4
Required. expire is the time before expire.The time unit is second.
message
runtime.proto:282Lock response message returns is the lock obtained.
bool success = 1
Is lock success
rpc Unlock (, )
runtime.proto:39A method trying to unlock.
message
runtime.proto:288UnLock request message
string store_name = 1
The name of store
string resource_id = 2
resource_id is the lock key.
string lock_owner = 3
The owner of the lock
message
runtime.proto:298UnLock response message
UnlockResponse.Status status = 1
The status of unlock
rpc LockKeepAlive (, )
runtime.proto:42A method used to support lease renewal for distributed lock.
message
runtime.proto:316LockKeepAlive request message
string store_name = 1
Required. The lock store name,e.g. `redis`.
string resource_id = 2
Required. resource_id is the lock key.
string lock_owner = 3
Required. The owner of the lock.
int32 expire = 4
Required. expire is the time before expire.The time unit is second.
message
runtime.proto:328LockKeepAlive response message
LockKeepAliveResponse.Status status = 1
The status of LockKeepAlive
rpc GetNextId (, )
runtime.proto:46Sequencer API Get next unique id with some auto-increment guarantee
message
runtime.proto:207Get next id request message
string store_name = 1
Required. Name of sequencer storage
string key = 2
Required. key is the identifier of a sequencer namespace,e.g. "order_table".
optional options = 3
(optional) SequencerOptions configures requirements for auto-increment guarantee
map<string, string> metadata = 4
(optional) The metadata which will be sent to the component.
message
runtime.proto:248Get next id response message
int64 next_id = 1
The next unique id Fixed int64 overflow problems on JavaScript https://github.com/improbable-eng/ts-protoc-gen#gotchas
rpc GetState (, )
runtime.proto:53Gets the state for a specific key.
message
runtime.proto:553GetStateRequest is the message to get key-value states from specific state store.
string store_name = 1
Required. The name of state store.
string key = 2
Required. The key of the desired state
StateOptions.StateConsistency consistency = 3
(optional) read consistency mode
map<string, string> metadata = 4
(optional) The metadata which will be sent to state store components.
message
runtime.proto:609GetStateResponse is the response conveying the state value and etag.
bytes data = 1
The byte array data
string etag = 2
The entity tag which represents the specific version of data. ETag format is defined by the corresponding data store.
map<string, string> metadata = 3
The metadata which will be sent to app.
rpc GetBulkState (, )
runtime.proto:56Gets a bulk of state items for a list of keys
message
runtime.proto:568GetBulkStateRequest is the message to get a list of key-value states from specific state store.
string store_name = 1
Required. The name of state store.
repeated string keys = 2
Required. The keys to get.
int32 parallelism = 3
(optional) The number of parallel operations executed on the state store for a get operation.
map<string, string> metadata = 4
(optional) The metadata which will be sent to state store components.
message
runtime.proto:583GetBulkStateResponse is the response conveying the list of state values.
repeated items = 1
The list of items containing the keys to get values for.
rpc SaveState (, )
runtime.proto:59Saves an array of state objects
message
runtime.proto:651SaveStateRequest is the message to save multiple states into state store.
string store_name = 1
Required. The name of state store.
repeated states = 2
Required. The array of the state key values.
rpc DeleteState (, )
runtime.proto:62Deletes the state for a specific key.
message
runtime.proto:622DeleteStateRequest is the message to delete key-value states in the specific state store.
string store_name = 1
Required. The name of state store.
string key = 2
Required. The key of the desired state
optional etag = 3
(optional) The entity tag which represents the specific version of data. The exact ETag format is defined by the corresponding data store.
optional options = 4
(optional) State operation options which includes concurrency/ consistency/retry_policy.
map<string, string> metadata = 5
(optional) The metadata which will be sent to state store components.
rpc DeleteBulkState (, )
runtime.proto:65Deletes a bulk of state items for a list of keys
message
runtime.proto:642DeleteBulkStateRequest is the message to delete a list of key-value states from specific state store.
string store_name = 1
Required. The name of state store.
repeated states = 2
Required. The array of the state key values.
Executes transactions for a specified store
message
runtime.proto:732ExecuteStateTransactionRequest is the message to execute multiple operations on a specified store.
string storeName = 1
Required. name of state store.
repeated operations = 2
Required. transactional operation list.
map<string, string> metadata = 3
(optional) The metadata used for transactional operations.
rpc PublishEvent (, )
runtime.proto:71Publishes events to the specific topic
message
runtime.proto:744PublishEventRequest is the message to publish event data to pubsub topic
string pubsub_name = 1
The name of the pubsub component
string topic = 2
The pubsub topic
bytes data = 3
The data which will be published to topic.
string data_content_type = 4
The content type for the data (optional).
map<string, string> metadata = 5
The metadata passing to pub components metadata property: - key : the key of the message.
rpc SubscribeTopicEvents (stream , stream )
runtime.proto:75SubscribeTopicEvents subscribes to a PubSub topic and receives topic events from it.
message
runtime.proto:768SubscribeTopicEventsRequest is a message containing the details for subscribing to a topic via streaming. The first message must always be the initial request. All subsequent messages must be event processed responses.
oneof subscribe_topic_events_request_type
The unique identifier for the subscription request.
initial_request = 1
The initial message containing the details for subscribing to a topic.
event_processed = 2
The message containing the subscription to a topic.
message
runtime.proto:810SubscribeTopicEventsResponse is a message returned from layotto when subscribing to a topic via streaming.
oneof subscribe_topic_events_response_type
The unique identifier for the subscription request.
initial_response = 1
The initial response from layotto when subscribing to a topic.
event_message = 2
The event message from the topic.
rpc GetFile (, stream )
runtime.proto:78Get file with stream
message
runtime.proto:131Get file request message
string store_name = 1
The name of store
string name = 2
The name of the file or object want to get.
map<string, string> metadata = 3
The metadata for user extension.
message
runtime.proto:141Get file response message
bytes data = 1
The data of file
rpc PutFile (stream , )
runtime.proto:81Put file with stream
message
runtime.proto:147Put file request message
string store_name = 1
The name of store
string name = 2
The name of the file or object want to put.
bytes data = 3
The data will be store.
map<string, string> metadata = 4
The metadata for user extension.
rpc ListFile (, )
runtime.proto:84List all files
message
runtime.proto:169List file request message
optional request = 1
File request
int32 page_size = 2
Page size
string marker = 3
Marker
message
runtime.proto:191List file response message
repeated files = 1
File info
string marker = 2
Marker
bool is_truncated = 3
Is truncated
rpc DelFile (, )
runtime.proto:87Delete specific file
message
runtime.proto:201Delete file request message
optional request = 1
File request
rpc GetFileMeta (, )
runtime.proto:90Get file meta data, if file not exist,return code.NotFound error
message
runtime.proto:103Get fileMeta request message
optional request = 1
File meta request
message
runtime.proto:109Get fileMeta response message
int64 size = 1
The size of file
string last_modified = 2
The modified time of file
optional response = 3
File meta response
rpc InvokeBinding (, )
runtime.proto:93Invokes binding data to specific output bindings
message
runtime.proto:825InvokeBindingRequest is the message to send data to output bindings
string name = 1
The name of the output binding to invoke.
bytes data = 2
The data which will be sent to output binding.
map<string, string> metadata = 3
The metadata passing to output binding components Common metadata property: - ttlInSeconds : the time to live in seconds for the message. If set in the binding definition will cause all messages to have a default time to live. The message ttl overrides any value in the binding definition.
string operation = 4
The name of the operation type for the binding to invoke
message
runtime.proto:845InvokeBindingResponse is the message returned from an output binding invocation
bytes data = 1
The data which will be sent to output binding.
map<string, string> metadata = 2
The metadata returned from an external system
rpc GetSecret (, )
runtime.proto:96Gets secrets from secret stores.
message
runtime.proto:854GetSecretRequest is the message to get secret from secret store.
string store_name = 1
The name of secret store.
string key = 2
The name of secret key.
map<string, string> metadata = 3
The metadata which will be sent to secret store components. Contains version, status, and so on...
message
runtime.proto:867GetSecretResponse is the response message to convey the requested secret.
map<string, string> data = 1
data is the secret value. Some secret store, such as kubernetes secret store, can save multiple secrets for single secret key.
rpc GetBulkSecret (, )
runtime.proto:99Gets a bulk of secrets
message
runtime.proto:875GetBulkSecretRequest is the message to get the secrets from secret store.
string store_name = 1
The name of secret store.
map<string, string> metadata = 2
The metadata which will be sent to secret store components.
message
runtime.proto:885GetBulkSecretResponse is the response message to convey the requested secrets.
map<string, > data = 1
data hold the secret values. Some secret store, such as kubernetes secret store, can save multiple secrets for single secret key.
message
runtime.proto:590BulkStateItem is the response item for a bulk get operation. Return values include the item key, data and etag.
Used in:
string key = 1
state item key
bytes data = 2
The byte array data
string etag = 3
The entity tag which represents the specific version of data. ETag format is defined by the corresponding data store.
string error = 4
The error that was returned from the state store in case of a failed get operation.
map<string, string> metadata = 5
The metadata which will be sent to app.
message
runtime.proto:371Common invoke request message which includes invoke method and data
Used in:
string method = 1
The method of requset
optional data = 2
The request data
string content_type = 3
The content type of request data
optional http_extension = 4
The extra information of http
message
lifecycle.proto:33The dynamic configuration of a component
Used in:
string kind = 1
Required. Which kind of API you are using, e.g. `lock`, `state`
string name = 2
Required. The component name, e.g. `state_demo`
map<string, string> metadata = 3
Required. The dynamic configuration of this component
message
runtime.proto:424ConfigurationItem represents a configuration item with key, content and other information.
Used in: , ,
string key = 1
Required. The key of configuration item
string content = 2
The content of configuration item Empty if the configuration is not set, including the case that the configuration is changed from value-set to value-not-set.
string group = 3
The group of configuration item.
string label = 4
The label of configuration item.
map<string, string> tags = 5
The tag list of configuration item.
map<string, string> metadata = 6
The metadata which will be passed to configuration store component.
message
runtime.proto:679Etag represents a state item version
Used in: ,
string value = 1
value sets the etag value
message
runtime.proto:179File info message
Used in:
string file_name = 1
The name of file
int64 size = 2
The size of file
string last_modified = 3
The modified time of file
map<string, string> metadata = 4
The metadata for user extension.
message
runtime.proto:125A map that store FileMetaValue
Used in:
map<string, > metadata = 1
A data structure to store metadata
message
runtime.proto:119FileMeta value
Used in:
repeated string value = 1
File meta value
message
runtime.proto:159File request message
Used in: , ,
string store_name = 1
The name of store
string name = 2
The name of the directory
map<string, string> metadata = 3
The metadata for user extension.
message
runtime.proto:383Http extension message is about invoke http information
Used in:
HTTPExtension.Verb verb = 1
The method of http reuest
string querystring = 2
The query information of http
The enum of http reuest method
Used in:
NONE = 0
NONE
GET = 1
GET method
HEAD = 2
HEAD method
POST = 3
POST method
PUT = 4
PUT method
DELETE = 5
DELETE method
CONNECT = 6
CONNECT method
OPTIONS = 7
CONNECT method
TRACE = 8
CONNECT method
PATCH = 9
PATCH method
The enum of LockKeepAlive status
Used in:
SUCCESS = 0
Lease renewal success
LOCK_UNEXIST = 1
The lock is not exist
LOCK_BELONG_TO_OTHERS = 2
The lock is belong to others
INTERNAL_ERROR = 3
Internal error
message
runtime.proto:893SecretResponse is a map of decrypted string/string values
Used in:
map<string, string> secrets = 1
The data struct of secrets
message
runtime.proto:219SequencerOptions configures requirements for auto-increment guarantee
Used in:
SequencerOptions.AutoIncrement increment = 1
Default STRONG auto-increment
requirements for auto-increment guarantee
Used in:
WEAK = 0
(default) WEAK means a "best effort" incrementing service.But there is no strict guarantee of global monotonically increasing. The next id is "probably" greater than current id.
STRONG = 1
STRONG means a strict guarantee of global monotonically increasing. The next id "must" be greater than current id.
message
runtime.proto:660StateItem represents state key, value, and additional options to save state.
Used in: , ,
string key = 1
Required. The state key
bytes value = 2
Required. The state data for key
optional etag = 3
(optional) The entity tag which represents the specific version of data. The exact ETag format is defined by the corresponding data store. Layotto runtime only treats ETags as opaque strings.
map<string, string> metadata = 4
(optional) additional key-value pairs to be passed to the state store.
optional options = 5
(optional) Options for concurrency and consistency to save the state.
message
runtime.proto:685StateOptions configures concurrency and consistency for state operations
Used in: ,
StateOptions.StateConcurrency concurrency = 1
The state operation of concurrency
StateOptions.StateConsistency consistency = 2
The state operation of consistency
Enum describing the supported concurrency for state. The API server uses Optimized Concurrency Control (OCC) with ETags. When an ETag is associated with an save or delete request, the store shall allow the update only if the attached ETag matches with the latest ETag in the database. But when ETag is missing in the write requests, the state store shall handle the requests in the specified strategy(e.g. a last-write-wins fashion).
Used in:
CONCURRENCY_UNSPECIFIED = 0
Concurrency state is unspecified
CONCURRENCY_FIRST_WRITE = 1
First write wins
CONCURRENCY_LAST_WRITE = 2
Last write wins
Enum describing the supported consistency for state.
Used in: ,
CONSISTENCY_UNSPECIFIED = 0
Consistency state is unspecified
CONSISTENCY_EVENTUAL = 1
The API server assumes data stores are eventually consistent by default.A state store should: - For read requests, the state store can return data from any of the replicas - For write request, the state store should asynchronously replicate updates to configured quorum after acknowledging the update request.
CONSISTENCY_STRONG = 2
When a strong consistency hint is attached, a state store should: - For read requests, the state store should return the most up-to-date data consistently across replicas. - For write/delete requests, the state store should synchronisely replicate updated data to configured quorum before completing the write request.
message
runtime.proto:780SubscribeTopicEventsRequestInitial is the initial message containing the details for subscribing to a topic via streaming.
Used in:
string pubsub_name = 1
The name of the pubsub component
string topic = 2
The pubsub topic
map<string, string> metadata = 3
The metadata passing to pub components metadata property: - key : the key of the message.
optional string dead_letter_topic = 4
dead_letter_topic is the topic to which messages that fail to be processed are sent.
message
runtime.proto:800SubscribeTopicEventsRequestProcessed is the message containing the subscription to a topic.
Used in:
string id = 1
id is the unique identifier for the subscription request.
optional status = 2
status is the result of the subscription request.
message
runtime.proto:822SubscribeTopicEventsResponseInitialAlpha1 is the initial response from layotto when subscribing to a topic.
Used in:
(message has no fields)
message
appcallback.proto:28TopicEventRequest message is compatible with CloudEvent spec v1.0 https://github.com/cloudevents/spec/blob/v1.0/spec.md
Used as request type in: AppCallback.OnTopicEvent
Used as field type in:
string id = 1
id identifies the event. Producers MUST ensure that source + id is unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same id.
string source = 2
source identifies the context in which an event happened. Often this will include information such as the type of the event source, the organization publishing the event or the process that produced the event. The exact syntax and semantics behind the data encoded in the URI is defined by the event producer.
string type = 3
The type of event related to the originating occurrence.
string spec_version = 4
The version of the CloudEvents specification.
string data_content_type = 5
The content type of data value.
bytes data = 7
The content of the event.
string topic = 6
The pubsub topic which publisher sent to.
string pubsub_name = 8
The name of the pubsub the publisher sent to.
map<string, string> metadata = 10
add a map to pass some extra properties.
message
appcallback.proto:64TopicEventResponse is response from app on published message
Used as response type in: AppCallback.OnTopicEvent
Used as field type in:
TopicEventResponse.TopicEventResponseStatus status = 1
The list of output bindings.
TopicEventResponseStatus allows apps to have finer control over handling of the message.
Used in:
SUCCESS = 0
SUCCESS is the default behavior: message is acknowledged and not retried or logged.
RETRY = 1
RETRY status signals runtime to retry the message as part of an expected scenario (no warning is logged).
DROP = 2
DROP status signals runtime to drop the message as part of an unexpected scenario (warning is logged).
message
appcallback.proto:86TopicSubscription represents topic and metadata.
Used in:
string pubsub_name = 1
Required. The name of the pubsub containing the topic below to subscribe to.
string topic = 2
Required. The name of topic which will be subscribed
map<string, string> metadata = 3
The optional properties used for this topic's subscription e.g. session id
message
runtime.proto:721TransactionalStateOperation is the message to execute a specified operation with a key-value pair.
Used in:
string operationType = 1
Required. The type of operation to be executed. Legal values include: "upsert" represents an update or create operation "delete" represents a delete operation
optional request = 2
Required. State values to be operated on
The enum of unlock status
Used in:
SUCCESS = 0
Unlock is success
LOCK_UNEXIST = 1
The lock is not exist
LOCK_BELONG_TO_OTHERS = 2
The lock is belong to others
INTERNAL_ERROR = 3
Internal error