openapi: 3.1.0 info: title: Loam Live version: v1 description: '**Status: In progress.** The `loam.live.v1` protocol is defined on the engine''s main branch; the server that serves it is built and landing. Nothing below runs on a released build yet. Loam Live is a reactive database on TiKV. Clients call `Query` and `Mutate` on server functions, and `Watch` a query set to receive a new result whenever a commit touches a key the query read. The service speaks Connect, gRPC and gRPC-Web, in JSON or binary, over HTTP/1.1 and HTTP/2. This reference shows the Connect JSON mapping: every call is `POST /loam.live.v1.LiveService/`. It listens on `127.0.0.1:7710`, loopback only and unauthenticated until the auth work lands. `Watch` is a server stream: use a Connect or gRPC client, not a plain HTTP request. Generated from `proto/loam/live/v1/live.proto` with protoc-gen-connect-openapi. ' servers: - url: http://127.0.0.1:7710 description: Local engine (loopback) paths: /loam.live.v1.LiveService/Deploy: post: tags: - loam.live.v1.LiveService summary: Deploy description: 'Admin: deploys a function bundle and a schema.' operationId: loam.live.v1.LiveService.Deploy parameters: - name: Connect-Protocol-Version in: header description: Define the version of the Connect protocol schema: $ref: '#/components/schemas/connect-protocol-version' example: 1 - name: Connect-Timeout-Ms in: header description: Define the timeout, in ms schema: $ref: '#/components/schemas/connect-timeout-header' example: 1000 requestBody: content: application/json: schema: $ref: '#/components/schemas/loam.live.v1.DeployRequest' required: true responses: default: description: Error content: application/json: schema: $ref: '#/components/schemas/connect.error' '200': description: Success content: application/json: schema: $ref: '#/components/schemas/loam.live.v1.DeployResponse' x-badges: &id001 - name: In progress color: '#c0842f' /loam.live.v1.LiveService/ModifyQuerySet: post: tags: - loam.live.v1.LiveService summary: ModifyQuerySet description: "Adds and removes queries in an open session. The next Transition\n reflects the change." operationId: loam.live.v1.LiveService.ModifyQuerySet parameters: - name: Connect-Protocol-Version in: header description: Define the version of the Connect protocol schema: $ref: '#/components/schemas/connect-protocol-version' example: 1 - name: Connect-Timeout-Ms in: header description: Define the timeout, in ms schema: $ref: '#/components/schemas/connect-timeout-header' example: 1000 requestBody: content: application/json: schema: $ref: '#/components/schemas/loam.live.v1.ModifyQuerySetRequest' required: true responses: default: description: Error content: application/json: schema: $ref: '#/components/schemas/connect.error' '200': description: Success content: application/json: schema: $ref: '#/components/schemas/loam.live.v1.ModifyQuerySetResponse' x-badges: *id001 /loam.live.v1.LiveService/Mutate: post: tags: - loam.live.v1.LiveService summary: Mutate description: Runs a mutation; returns its commit timestamp and result. operationId: loam.live.v1.LiveService.Mutate parameters: - name: Connect-Protocol-Version in: header description: Define the version of the Connect protocol schema: $ref: '#/components/schemas/connect-protocol-version' example: 1 - name: Connect-Timeout-Ms in: header description: Define the timeout, in ms schema: $ref: '#/components/schemas/connect-timeout-header' example: 1000 requestBody: content: application/json: schema: $ref: '#/components/schemas/loam.live.v1.MutateRequest' required: true responses: default: description: Error content: application/json: schema: $ref: '#/components/schemas/connect.error' '200': description: Success content: application/json: schema: $ref: '#/components/schemas/loam.live.v1.MutateResponse' x-badges: *id001 /loam.live.v1.LiveService/Query: post: tags: - loam.live.v1.LiveService summary: Query description: A one-shot query, at the latest tick or at a given timestamp. operationId: loam.live.v1.LiveService.Query parameters: - name: Connect-Protocol-Version in: header description: Define the version of the Connect protocol schema: $ref: '#/components/schemas/connect-protocol-version' example: 1 - name: Connect-Timeout-Ms in: header description: Define the timeout, in ms schema: $ref: '#/components/schemas/connect-timeout-header' example: 1000 requestBody: content: application/json: schema: $ref: '#/components/schemas/loam.live.v1.QueryRequest' required: true responses: default: description: Error content: application/json: schema: $ref: '#/components/schemas/connect.error' '200': description: Success content: application/json: schema: $ref: '#/components/schemas/loam.live.v1.QueryResponse' x-badges: *id001 /loam.live.v1.LiveService/Watch: post: tags: - loam.live.v1.LiveService summary: Watch operationId: loam.live.v1.LiveService.Watch description: 'Open a session and stream a `Transition` every time a commit changes the result of a query in the session''s query set. Resume after a disconnect with `resume` and the last `StateVersion` you saw. Server-streaming RPC: with Connect, the request and each response message are enveloped (`application/connect+json`). Use a Connect or gRPC client.' x-badges: - name: In progress color: '#c0842f' requestBody: required: true content: application/connect+json: schema: $ref: '#/components/schemas/loam.live.v1.WatchRequest' responses: '200': description: A stream of transitions. content: application/connect+json: schema: $ref: '#/components/schemas/loam.live.v1.Transition' components: schemas: connect-protocol-version: type: number examples: - 1 title: Connect-Protocol-Version description: Define the version of the Connect protocol const: 1 connect-timeout-header: type: number examples: - 1000 title: Connect-Timeout-Ms description: Define the timeout, in ms connect.error: type: object properties: code: type: string examples: - not_found enum: - canceled - unknown - invalid_argument - deadline_exceeded - not_found - already_exists - permission_denied - resource_exhausted - failed_precondition - aborted - out_of_range - unimplemented - internal - unavailable - data_loss - unauthenticated description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. message: type: string description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. details: type: array items: $ref: '#/components/schemas/connect.error_details.Any' description: A list of messages that carry the error details. There is no limit on the number of messages. title: Connect Error additionalProperties: true description: 'Error type returned by Connect: https://connectrpc.com/docs/go/errors/#http-representation' connect.error_details.Any: type: object properties: type: type: string description: 'A URL that acts as a globally unique identifier for the type of the serialized message. For example: `type.googleapis.com/google.rpc.ErrorInfo`.' value: type: string format: binary description: The Protobuf message, serialized as bytes and base64-encoded. The specific message type is identified by the `type` field. debug: type: object title: Debug additionalProperties: true description: Deserialized error detail payload. The 'type' field indicates the schema. This field is for easier debugging and should not be relied upon for application logic. additionalProperties: true description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message, with an additional debug field for ConnectRPC error details. loam.live.v1.Array: type: object properties: values: type: array items: $ref: '#/components/schemas/loam.live.v1.Value' title: values title: Array additionalProperties: false description: An ordered list of values (currently at most 8 192 elements). loam.live.v1.DeployRequest: type: object properties: bundle: type: string title: bundle format: byte description: One ES module. schema: allOf: - $ref: '#/components/schemas/loam.live.v1.Schema' title: schema title: DeployRequest additionalProperties: false loam.live.v1.DeployResponse: type: object properties: deploymentId: type: string title: deployment_id title: DeployResponse additionalProperties: false loam.live.v1.ErrorCode: type: string title: ErrorCode enum: - ERROR_CODE_UNSPECIFIED - ERROR_CODE_INVALID_ARGUMENT - ERROR_CODE_NOT_FOUND - ERROR_CODE_FAILED_PRECONDITION - ERROR_CODE_RESOURCE_EXHAUSTED - ERROR_CODE_FUNCTION_ERROR - ERROR_CODE_FUNCTION_TIMEOUT - ERROR_CODE_FUNCTION_OUT_OF_MEMORY - ERROR_CODE_UNAVAILABLE - ERROR_CODE_INTERNAL loam.live.v1.IndexSchema: type: object properties: name: type: string title: name fields: type: array items: type: string title: fields description: Up to 16 field names; `_creationTime` and `_id` are appended. title: IndexSchema additionalProperties: false loam.live.v1.LiveError: type: object properties: code: allOf: - $ref: '#/components/schemas/loam.live.v1.ErrorCode' title: code message: type: string title: message title: LiveError additionalProperties: false description: "An error for one query in a Transition. Call errors use the Connect error\n codes;\ \ this carries the same meaning inside a stream that stays open." loam.live.v1.ModifyQuerySetRequest: type: object properties: sessionId: type: string title: session_id baseVersion: type: string title: base_version format: int64 description: "Must equal the session's current query-set version, else\n FailedPrecondition." newVersion: type: string title: new_version format: int64 changes: type: array items: $ref: '#/components/schemas/loam.live.v1.QuerySetChange' title: changes title: ModifyQuerySetRequest additionalProperties: false loam.live.v1.ModifyQuerySetResponse: type: object title: ModifyQuerySetResponse additionalProperties: false loam.live.v1.MutateRequest: type: object properties: function: type: string title: function args: allOf: - $ref: '#/components/schemas/loam.live.v1.Value' title: args idempotencyKey: type: - string - 'null' title: idempotency_key description: "A retried call with the same key returns the recorded commit timestamp\n and result\ \ instead of running again." title: MutateRequest additionalProperties: false loam.live.v1.MutateResponse: type: object properties: commitTs: type: string title: commit_ts format: int64 result: allOf: - $ref: '#/components/schemas/loam.live.v1.Value' title: result title: MutateResponse additionalProperties: false loam.live.v1.Null: type: object title: 'Null' additionalProperties: false description: "The null value. An empty message rather than an enum, so the JSON form is\n `{\"nullValue\"\ : {}}` in every client." loam.live.v1.Object: type: object properties: fields: type: object title: fields additionalProperties: allOf: - $ref: '#/components/schemas/loam.live.v1.Value' title: value title: Object additionalProperties: false description: "A map of field name to value (currently at most 1 024 fields). Field order is\n not significant." loam.live.v1.QueryRequest: type: object properties: function: type: string title: function args: allOf: - $ref: '#/components/schemas/loam.live.v1.Value' title: args ts: type: - string - 'null' title: ts format: int64 description: A TSO timestamp to read at; the latest tick when unset. title: QueryRequest additionalProperties: false loam.live.v1.QueryResponse: type: object properties: ts: type: string title: ts format: int64 description: The timestamp the query was evaluated at. result: allOf: - $ref: '#/components/schemas/loam.live.v1.Value' title: result title: QueryResponse additionalProperties: false loam.live.v1.QuerySet: type: object properties: version: type: string title: version format: int64 queries: type: array items: $ref: '#/components/schemas/loam.live.v1.QuerySpec' title: queries title: QuerySet additionalProperties: false loam.live.v1.QuerySetChange: type: object anyOf: - type: object properties: add: allOf: - $ref: '#/components/schemas/loam.live.v1.QuerySpec' title: add title: add - type: object properties: remove: type: integer title: remove description: The query id to remove. title: remove unevaluatedProperties: false not: allOf: - anyOf: - required: - add - required: - remove - not: oneOf: - required: - add - required: - remove title: QuerySetChange loam.live.v1.QuerySpec: type: object properties: queryId: type: integer title: query_id description: Chosen by the client, unique within its session. function: type: string title: function description: '"module:export", or a built-in such as "_system:query".' args: allOf: - $ref: '#/components/schemas/loam.live.v1.Value' title: args title: QuerySpec additionalProperties: false loam.live.v1.QueryUpdate: type: object anyOf: - type: object properties: error: allOf: - $ref: '#/components/schemas/loam.live.v1.LiveError' title: error title: error - type: object properties: removed: allOf: - $ref: '#/components/schemas/loam.live.v1.Removed' title: removed title: removed - type: object properties: value: allOf: - $ref: '#/components/schemas/loam.live.v1.Value' title: value title: value unevaluatedProperties: false not: allOf: - anyOf: - required: - error - required: - removed - required: - value - not: oneOf: - required: - error - required: - removed - required: - value properties: queryId: type: integer title: query_id title: QueryUpdate loam.live.v1.Removed: type: object title: Removed additionalProperties: false description: The query left the query set. loam.live.v1.Resume: type: object properties: lastVersion: allOf: - $ref: '#/components/schemas/loam.live.v1.StateVersion' title: last_version querySet: allOf: - $ref: '#/components/schemas/loam.live.v1.QuerySet' title: query_set title: Resume additionalProperties: false loam.live.v1.Schema: type: object properties: tables: type: array items: $ref: '#/components/schemas/loam.live.v1.TableSchema' title: tables title: Schema additionalProperties: false description: 'A deployed schema: tables and their indexes (validators are planned).' loam.live.v1.StateVersion: type: object properties: querySet: type: string title: query_set format: int64 identity: type: string title: identity format: int64 ts: type: string title: ts format: int64 description: The TSO timestamp every query of the session was evaluated at. title: StateVersion additionalProperties: false description: "A session's state: (query-set version, identity version, ts). A client\n applies a\ \ Transition only if its `start` equals the client's current\n version; a gap means it resumes.\ \ The zero version is {0, 0, 0}." loam.live.v1.TableSchema: type: object properties: name: type: string title: name indexes: type: array items: $ref: '#/components/schemas/loam.live.v1.IndexSchema' title: indexes description: User indexes; `by_id` and `by_creation_time` are implicit. title: TableSchema additionalProperties: false loam.live.v1.Transition: type: object properties: sessionId: type: string title: session_id start: allOf: - $ref: '#/components/schemas/loam.live.v1.StateVersion' title: start description: Must equal the client's current version. end: allOf: - $ref: '#/components/schemas/loam.live.v1.StateVersion' title: end updates: type: array items: $ref: '#/components/schemas/loam.live.v1.QueryUpdate' title: updates description: 'Per query id: a value, an error, or removed.' more: type: boolean title: more description: "Chunked: more Transition messages with the same `end` follow, and the\n client\ \ applies them together." title: Transition additionalProperties: false description: One step of a session, from `start` to `end`. loam.live.v1.Value: type: object anyOf: - type: object properties: arrayValue: allOf: - $ref: '#/components/schemas/loam.live.v1.Array' title: array_value title: array_value - type: object properties: boolValue: type: boolean title: bool_value title: bool_value - type: object properties: bytesValue: type: string title: bytes_value format: byte title: bytes_value - type: object properties: doubleValue: type: number title: double_value format: double title: double_value - type: object properties: int64Value: type: string title: int64_value format: int64 title: int64_value - type: object properties: nullValue: allOf: - $ref: '#/components/schemas/loam.live.v1.Null' title: null_value title: null_value - type: object properties: objectValue: allOf: - $ref: '#/components/schemas/loam.live.v1.Object' title: object_value title: object_value - type: object properties: stringValue: type: string title: string_value title: string_value unevaluatedProperties: false not: allOf: - anyOf: - required: - arrayValue - required: - boolValue - required: - bytesValue - required: - doubleValue - required: - int64Value - required: - nullValue - required: - objectValue - required: - stringValue - not: oneOf: - required: - arrayValue - required: - boolValue - required: - bytesValue - required: - doubleValue - required: - int64Value - required: - nullValue - required: - objectValue - required: - stringValue title: Value description: A Loam Live value. loam.live.v1.WatchRequest: type: object anyOf: - type: object properties: initial: allOf: - $ref: '#/components/schemas/loam.live.v1.QuerySet' title: initial description: A new session with this query set. title: initial - type: object properties: resume: allOf: - $ref: '#/components/schemas/loam.live.v1.Resume' title: resume description: "A reconnect: rerun the set at a tick at or after `last_version.ts`\n and send\ \ full results." title: resume unevaluatedProperties: false not: allOf: - anyOf: - required: - initial - required: - resume - not: oneOf: - required: - initial - required: - resume title: WatchRequest security: [] tags: - name: loam.live.v1.LiveService x-displayName: LiveService description: Server functions, reactive queries and deploys. The server is built and landing; it is not on the main branch yet.