Skip to main content

entity.proto

path cloudstate/entity.proto

package cloudstate


Messages

ClientAction

An action for the client

NameTypeDescription
replyReplySend a reply
forwardForwardForward to another entity
failureFailureSend a failure to the client

Command

A command. For each command received, a reply must be sent with a matching command id.

NameTypeDescription
entity_idstringThe ID of the entity.
idint64A command id.
namestringCommand name
payloadgoogle.protobuf.AnyThe command payload.
streamedboolWhether the command is streamed or not.
metadataMetadataThe command metadata. Not all transports support per message metadata, for example, gRPC doesn't. The Cloudstate proxy MAY include metadata from other locations in this case, for example, in gRPC, a unary call MAY have the HTTP request headers attached to the command, while a streamed call MAY have the HTTP request headers attached as the metadata for either the first command, or every command. This specification leaves this behavior undefined.

Entity

NameTypeDescription
entity_typestringThe type of entity. By convention, this should be a fully qualified entity protocol grpc service name, for example, cloudstate.eventsourced.EventSourced.
service_namestringThe name of the service to load from the protobuf file.
persistence_idstringThe ID to namespace state by. How this is used depends on the type of entity, for example, event sourced entities will prefix this to the persistence id.
passivation_strategyEntityPassivationStrategyThe passivation strategy for the entity.

EntityPassivationStrategy

The semantics is to provide a flexible way for entity user functions to configure the passivation strategy. This strategy is sent to the proxy at discovery time allowing the proxy to configure the corresponding entities. The only passivation strategy supported is the timeout strategy and configuring this is optional for the entity. If an entity user function does not configure the passivation strategy the proxy uses its fallback default value. The passivation strategy for the entity user function.

NameTypeDescription
timeoutTimeoutPassivationStrategythe timeout passivation strategy.

EntitySpec

NameTypeDescription
protobytesThis should be the Descriptors.FileDescriptorSet in proto serialized from as generated by: protoc --include_imports \ --proto_path=<proto file directory> \ --descriptor_set_out=user-function.desc \ <path to .proto files>
entitiesEntityThe entities being served.
service_infoServiceInfoOptional information about the service.

Failure

A failure reply. If this is returned, it will be translated into a gRPC unknown error with the corresponding description if supplied.

NameTypeDescription
command_idint64The id of the command being replied to. Must match the input command.
descriptionstringA description of the error.
restartboolWhether this failure should trigger an entity restart.

Forward

Forwards handling of this request to another entity.

NameTypeDescription
service_namestringThe name of the service to forward to.
command_namestringThe name of the command.
payloadgoogle.protobuf.AnyThe payload.
metadataMetadataThe metadata to include with the forward

Metadata

Transport-specific metadata associated with a message. The semantics of the metadata are not defined in this protocol, but rather, depend on the transport on which a particular instance of the metadata maps to. What keys or values are allowed or disallowed, whether duplicate values for the same key are allowed and how they are handled, and whether key names are case sensitive or not, are all undefined in the context of the Cloudstate protocol. If a metadata entry associated with a message can't be expressed in an underlying transport, for example, due to invalid characters in a key or value, the behavior of the proxy is undefined. This is because metadata is transport specific, so if the user function chooses to use metadata, it is choosing to be specific to a particular transport, which is beyond the scope of the Cloudstate protocol, and it's therefore the user function's responsibility to adhere to the semantics of that transport. The proxy MAY decide to drop metadata entries if it knows they are invalid or unsupported. If a metadata entry is dropped, the proxy MAY inform the user function that the entry was dropped by sending an error message to the EntityDiscovery.ReportError gRPC call. The metadata MAY also contain CloudEvent metadata. If a message comes from a Cloudstate event source, the Cloudstate proxy MUST attach CloudEvent metadata to it if the event doesn't already have CloudEvent metadata attached to it. This metadata SHALL be encoded according to the binary mode of the CloudEvent HTTP protocol binding, which can be found here: https://github.com/cloudevents/spec/blob/master/http-protocol-binding.md The Cloudstate proxy MAY synthesize appropriate values for Cloudstate metadata if no equivalent metadata exists in the event source, for example, if there is no type, the Cloudstate proxy MAY use the name of the gRPC message as the CloudEvent type, and if there is no source, the Cloudstate proxy MAY use the name of the topic as the source. If an incoming message does have CloudEvent metadata attached to it, the Cloudstate proxy MUST transcode that CloudEvent metadata to the HTTP protocol binding as described above. Messages sent from the user function to an event destination MAY include CloudEvent metadata. If they include any CloudEvent metadata, they MUST include all required CloudEvent attributes, including id, source, specversion and type. The behavior of the proxy is undefined if some of these attributes, but not others, are included - the proxy MAY ignore them all, or MAY generate values itself, but SHOULD NOT fail sending the message. If the destination for the message is an event destination, the Cloudstate proxy MUST transcode the supplied Cloudstate metadata to a binding appropriate for the underlying transport for that event destination, it MUST NOT pass the CloudEvent metadata as is unless the transport uses the same binding rules.

NameTypeDescription
entriesMetadataEntryThe metadata entries.

MetadataEntry

A metadata entry.

NameTypeDescription
keystringKey for the entry. Valid keys depend on the transport from or to which this metadata is sent.
string_valuestringA string value. Valid values depend on the transport from or which this metadata is sent. If the transport does not support string values, the behavior of the Cloudstate proxy is undefined from the point of view of this protocol. If there is a convention in the protocol for encoding string values as UTF-8 bytes, then the Cloudstate proxy MAY do that.
bytes_valuebytesA bytes value. Valid values depend on the transport from or which this metadata is sent. If the transport does not support bytes values, the behavior of the Cloudstate proxy is undefined from the point of view of this protocol. If there is a convention in the protocol for encoding bytes values as Base64 encoded strings, then the Cloudstate proxy MAY do that.

ProxyInfo

NameTypeDescription
protocol_major_versionint32
protocol_minor_versionint32
proxy_namestring
proxy_versionstring
supported_entity_typesstring

Reply

A reply to the sender.

NameTypeDescription
payloadgoogle.protobuf.AnyThe reply payload
metadataMetadataMetadata for the reply Not all transports support per message metadata, for example, gRPC doesn't. The Cloudstate proxy MAY ignore the metadata in this case, or it MAY lift the metadata into another place, for example, in gRPC, a unary call MAY have its reply metadata placed in the headers of the HTTP response, or the first reply to a streamed call MAY have its metadata placed in the headers of the HTTP response. If the metadata is ignored, the Cloudstate proxy MAY notify the user function by sending an error message to the EntityDiscovery.ReportError gRPC call.

ServiceInfo

Information about the service that proxy is proxying to. All of the information in here is optional. It may be useful for debug purposes.

NameTypeDescription
service_namestringThe name of the service, eg, "shopping-cart".
service_versionstringThe version of the service.
service_runtimestringA description of the runtime for the service. Can be anything, but examples might be: - node v10.15.2 - OpenJDK Runtime Environment 1.8.0_192-b12
support_library_namestringIf using a support library, the name of that library, eg "cloudstate"
support_library_versionstringThe version of the support library being used.
protocol_major_versionint32Cloudstate protocol major version accepted by the support library.
protocol_minor_versionint32Cloudstate protocol minor version accepted by the support library.

SideEffect

A side effect to be done after this command is handled.

NameTypeDescription
service_namestringThe name of the service to perform the side effect on.
command_namestringThe name of the command.
payloadgoogle.protobuf.AnyThe payload of the command.
synchronousboolWhether this side effect should be performed synchronously, ie, before the reply is eventually sent, or not.
metadataMetadataThe metadata to include with the side effect

StreamCancelled

NameTypeDescription
entity_idstringThe ID of the entity
idint64The command id

TimeoutPassivationStrategy

A passivation strategy based on a timeout. The idle timeout after which a user function's entity is passivated.

NameTypeDescription
timeoutint64The timeout in millis

UserFunctionError

NameTypeDescription
messagestring

Services

EntityDiscovery

Entity discovery service.

discover

Methoddiscover
RequestProxyInfo
ResponseEntitySpec
DescriptionDiscover what entities the user function wishes to serve.

reportError

MethodreportError
RequestUserFunctionError
ResponseEmpty
DescriptionReport an error back to the user function. This will only be invoked to tell the user function that it has done something wrong, eg, violated the protocol, tried to use an entity type that isn't supported, or attempted to forward to an entity that doesn't exist, etc. These messages should be logged clearly for debugging purposes.