Protocol Documentation

Table of Contents

schema.proto

Top

Cache

Cache is a persisted value that will expire after a period of time. It is held in memory for maximum performance.

FieldTypeLabelDescription
domain string

the cached value's business domain(ex: accounting)

key string

the cached value's key (unique within domain)

value google.protobuf.Value

the cached value's value to store

exp google.protobuf.Timestamp

exp is the time at which the cached value will expire if exp is 0, the value will never expire

Validated Fields

Field Validations
domain
  • regex: ^\S+$
key
  • regex: ^\S+$
value
  • msg_exists: true

CacheRef

CacheRef is a reference to a cached value

FieldTypeLabelDescription
domain string

the cached value's business domain(ex: accounting) must not be empty or contain spaces

key string

cached value's key (unique within domain) must not be empty or contain spaces

Validated Fields

Field Validations
domain
  • regex: ^\S+$
key
  • regex: ^\S+$

Entities

Entities is an array of Entity

FieldTypeLabelDescription
entities Entity repeated

Entity

Entity represents a single record(k/v pairs) with a unique key with a given [type](https://en.wikipedia.org/wiki/Type_system), belonging to a particular [domain](https://en.wikipedia.org/wiki/Domain-driven_design)

EventService clients should use the EntityService to persist & interact with the current state of an entity.

FieldTypeLabelDescription
domain string

the entity's business domain(ex: accounting) must not be empty or contain spaces

type string

the entity's type (ex: user) must not be empty or contain spaces

key string

the entity's key (unique within type). must not be empty or contain spaces

values google.protobuf.Struct

the entity's values (k/v pairs)

Validated Fields

Field Validations
domain
  • regex: ^\S+$
type
  • regex: ^\S+$
key
  • regex: ^\S+$
values
  • msg_exists: true

EntityRef

EntityRef is a reference to an existing entity

FieldTypeLabelDescription
domain string

the entity's business domain(ex: accounting) must not be empty or contain spaces

type string

entity type (ex: user) must not be empty or contain spaces

key string

entity key (unique within type) must not be empty or contain spaces

Validated Fields

Field Validations
domain
  • regex: ^\S+$
type
  • regex: ^\S+$
key
  • regex: ^\S+$

Event

Event is primitive that represents a single state change to an entity

Events are persisted to history & broadcasted to interested consumers(Stream) any time an entity is created/modified/deleted

Events are immutable after creation and may be searched.

EventService client's may search events to query previous state of an entity(s)

FieldTypeLabelDescription
id string

identifies the event(uuid v4).

entity Entity

state of an Entity after it has been mutated

method string

the invoked method that triggered the event

claims google.protobuf.Struct

the authentication claims of the event producer.

time int64

timestamp(ns) of when the event was received.

Validated Fields

Field Validations
id
  • uuid_ver: 4
entity
  • msg_exists: true
method
  • string_not_empty: true
claims
  • msg_exists: true
time
  • int_gt: 0

EventRef

EventRef holds options for reverting an entity to a previous version of itself

FieldTypeLabelDescription
domain string

the event's entity's business domain(ex: accounting) must not be empty or contain spaces

type string

event entity type (ex: user) must not be empty or contain spaces

key string

event's entity's key (unique within type) must not be empty or contain spaces

id string

id is the event id.

Validated Fields

Field Validations
domain
  • regex: ^\S+$
type
  • regex: ^\S+$
key
  • regex: ^\S+$
id
  • uuid_ver: 4

Events

Events is an array of events

FieldTypeLabelDescription
events Event repeated

Message

Message is an arbitrary message to be delivered to a Peer

Messages are NOT persisted and should only be used to communicate with other Peers

FieldTypeLabelDescription
domain string

the message's business domain(ex: accounting) must not be empty or contain spaces

channel string

the message's channel(ex: general) must not be empty or contain spaces

type string

message's type (ex: comment) must not be empty or contain spaces

body google.protobuf.Struct

the body of the message(k/v values).

Validated Fields

Field Validations
domain
  • regex: ^\S+$
channel
  • regex: ^\S+$
type
  • regex: ^\S+$
body
  • msg_exists: true

Mutex

Mutex is a distributed mutex for preventing data-races amongst peer services

FieldTypeLabelDescription
domain string

the mutex's business domain(ex: accounting)

key string

mutex key (unique within domain)

exp google.protobuf.Timestamp

exp is the time at which the mutex value will expire if exp is 0, the mutex will never expire

Validated Fields

Field Validations
domain
  • regex: ^\S+$
key
  • regex: ^\S+$

MutexRef

MutexRef is a reference to a distributed mutex

FieldTypeLabelDescription
domain string

the mutex's business domain(ex: accounting)

key string

mutex key (unique within domain)

Validated Fields

Field Validations
domain
  • regex: ^\S+$
key
  • regex: ^\S+$

PeerMessage

PeerMessage is a message produced by a client to the PeerService

PeerMessages are NOT persisted and should only be used to communicate with other Peers

FieldTypeLabelDescription
id string

the unique id of the message

domain string

the message's business domain(ex: accounting) must not be empty or contain spaces

channel string

the message's channel(ex: general) must not be empty or contain spaces

type string

message's type (ex: comment) must not be empty or contain spaces

body google.protobuf.Struct

the body of the message(k/v values).

claims google.protobuf.Struct

the authentication claims of the message producer.

time int64

timestamp(ns) of when the message was broadcasted.

Validated Fields

Field Validations
id
  • uuid_ver: 4
domain
  • regex: ^\S+$
channel
  • regex: ^\S+$
type
  • regex: ^\S+$
body
  • msg_exists: true
claims
  • msg_exists: true
time
  • int_gt: 0

SearchEntityOpts

SearchEntityOpts are options when querying the current values of entities.

If historical values are needed, SearchEvents should be used

FieldTypeLabelDescription
domain string

the entity's business domain(ex: accounting) must not be empty or contain spaces

type string

State type (ex: user) must not be empty or contain spaces

query_string string

json string to filter records that have values match k/v pairs ex: { "message": "hello world" } please note that dot notation may be used to access nested fields

limit int32

limit number of returned values

offset int32

offset returned events(pagination)

sort Sort

sort sorts the returned entities by a specified field

Validated Fields

Field Validations
domain
  • regex: ^\S+$
type
  • regex: ^\S+$
limit
  • int_gt: 0

SearchEventOpts

SearchEventOpts are options when querying historical events emitted from mutations made from State mutations

FieldTypeLabelDescription
domain string

the entity's business domain(ex: accounting) must not be empty or contain spaces

type string

entity's type (ex: user) must not be empty or contain spaces

query_string string

json string to filter events based with values that match k/v pairs ex: { "entity.values.message": "hello world" }. please note that dot notation may be used to access nested fields

min int64

only return events that occurred after specified min timestamp

max int64

only return events that occurred before specified max timestamp

limit int32

limit number of returned values

offset int32

offset returned events(pagination)

sort Sort

sort sorts the returned entities by a specified field

Validated Fields

Field Validations
domain
  • regex: ^\S+$
type
  • regex: ^\S+$
limit
  • int_gt: 0

Sort

Sort is a primitive used to sort an array

FieldTypeLabelDescription
field string

field is a field to sort the array by please note that dot notation may be used to access nested fields

reverse bool

reverse reverses the direction of the sort

StreamEventOpts

StreamEventOpts are options for consumers looking to stream events.

Events are automatically emitted from mutations made from State mutations within the EntityService

FieldTypeLabelDescription
domain string

the domain of the entity (ex: acme) that triggered the event * indicates any domain must not be empty or contain spaces

type string

the type of the entity (ex: user) that triggered the event * indicates any type must not be empty or contain spaces

consumer_group string

consumer_group

Validated Fields

Field Validations
domain
  • regex: ^\S+$
type
  • regex: ^\S+$

StreamMessageOpts

StreamMessageOpts holds options for streaming messages produced by Peers

FieldTypeLabelDescription
domain string

the message's business domain(ex: accounting) to subscribe to must not be empty or contain spaces * indicates any domain

channel string

the message's channel(ex: general) to subscribe to must not be empty or contain spaces * indicates any channel

type string

message's type (ex: comment) to subscribe to must not be empty or contain spaces * indicates any type

consumer_group string

consumer_group

Validated Fields

Field Validations
domain
  • regex: ^\S+$
channel
  • regex: ^\S+$
type
  • regex: ^\S+$

CacheService

CacheService is for persisting short lived values in memory for performance-critical operations

Method NameRequest TypeResponse TypeDescription
Set Cache .google.protobuf.Empty

Set sets a value in the cache
Get CacheRef Cache

Get gets a value from the cache
Del CacheRef .google.protobuf.Empty

Del deletes a value from the cache

Methods with HTTP bindings

Method Name Method Pattern Body
Set PUT /api/cache/ref/{domain}/{key}
Get GET /api/cache/ref/{domain}/{key}
Del DELETE /api/cache/ref/{domain}/{key}

EntityService

EntityService serves API methods to clients that modify/query the current state of an entity

An Entity is a single object with a type, domain, key, and k/v values

Method NameRequest TypeResponse TypeDescription
Set Entity .google.protobuf.Empty

Set sets the current state value of an entity, adds it to the event log, then broadcast the event to all interested consumers(EventService.Stream)
Edit Entity Entity

Edit overwrites the k/v pairs present in the entity request without replacing the entire entity. It then adds the state change to the event log, then broadcast the event to all interested consumers(EventService.Stream) Edit returns the current state of the Entity after the mutation.
Revert EventRef Entity

Revert reverts an Entity to a previous version of itself by querying the event store. Reverting an entity dispatches another event since it is a state change
Get EntityRef Entity

Get gets an entity's current state
Del EntityRef .google.protobuf.Empty

Del hard deletes an entity from current state store, adds it's state prior to deletion to the event log, then broadcast the event to all interested consumers(EventService.Stream) an Entity may be recovered via querying the Event store for historical records of the deleted Entity.
Search SearchEntityOpts Entities

Search queries the current state of entities

Methods with HTTP bindings

Method Name Method Pattern Body
Set PUT /api/entity/ref/{domain}/{type}/{key}
Edit PATCH /api/entity/ref/{domain}/{type}/{key}
Revert PUT /api/entity/ref/{domain}/{type}/{key}/revert
Get GET /api/entity/ref/{domain}/{type}/{key}
Del DELETE /api/entity/ref/{domain}/{type}/{key}
Search GET /api/entity/search

EventService

EventService serves API methods related to stategate Event Consumers

Events are automatically emitted from mutations made from State mutations within the EntityService

Method NameRequest TypeResponse TypeDescription
Stream StreamEventOpts Event stream

Stream creates an event stream/subscription to state changes to entities in real time. Glob matching is supported.
Search SearchEventOpts Events

Search queries historical events - every historical state change to an entity may be queried.
Get EventRef Event

Get gets a single event

Methods with HTTP bindings

Method Name Method Pattern Body
Stream GET /api/event/stream
Search GET /api/event/search
Get GET /api/event/ref/{domain}/{type}/{key}/{id}

MutexService

MutexService offers distributed locking capabilities for client's that need to coordinate with peer services.

Method NameRequest TypeResponse TypeDescription
Lock Mutex .google.protobuf.Empty

Lock locks a value for a period of time if it is not locked already. If it is already locked, an error will be returned It is best practice for client's to call Unlock when the distributed lock operation is completed instead of relying on the TTL
Unlock MutexRef .google.protobuf.Empty

Unlock unlocks the key(if it's currently locked) so that it may be locked again. It is best practice for client's to call Unlock when the distributed lock operation is completed instead of relying on the TTL

Methods with HTTP bindings

Method Name Method Pattern Body
Lock PUT /api/mutex/ref/{domain}/{key}
Unlock PUT /api/mutex/ref/{domain}/{key}

PeerService

PeerService provides a means for clients to communicate directly with one another WITHOUT making any state changes.

Please note that all messages transported via the PeerService are not persisted in any way.

Method NameRequest TypeResponse TypeDescription
Broadcast Message .google.protobuf.Empty

Broadcast broadcasts a message to N subscribers(clients calling Stream)
Stream StreamMessageOpts PeerMessage stream

Stream consumes/streams messages from message producers(clients calling broadcast)

Methods with HTTP bindings

Method Name Method Pattern Body
Broadcast POST /api/peer/broadcast *
Stream GET /api/peer/stream

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)