Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
493 lines (452 sloc) 15.7 KB
syntax = "proto3";
package api;
option go_package = "coreapi";
// This is the primary API to interact with MESG Core functionalities.
// It can be consumed by any applications or tools that you'd like to interact with MESG Core.
// It is actually used by the MESG CLI and MESG Application libraries.
//
// This API is only accessible through [gRPC](https://grpc.io/).
//
// Services must not use this API, but rather use the [Service API](./service.md).
//
// The source file of this API is hosted on [GitHub](https://github.com/mesg-foundation/core/blob/master/protobuf/coreapi/api.proto).
service Core {
// Subscribe to a stream that listens for events from a service.
rpc ListenEvent (ListenEventRequest) returns (stream EventData) {}
// Subscribe to a stream that listens for task's result from a service.
rpc ListenResult (ListenResultRequest) returns (stream ResultData) {}
// Execute a service's task through Core.
rpc ExecuteTask (ExecuteTaskRequest) returns (ExecuteTaskReply) {}
// Start a service. The service must be already deployed to Core.
rpc StartService (StartServiceRequest) returns (StartServiceReply) {}
// Stop a service. The service must be already deployed to Core.
rpc StopService (StopServiceRequest) returns (StopServiceReply) {}
// Deploy a service to Core. This will give you an unique identifier which is used to interact with the service.
rpc DeployService (stream DeployServiceRequest) returns (stream DeployServiceReply) {}
// Delete a service from Core. This function only deletes a deployed service in Core. If the service's code is on your computer, the source code will not be deleted.
rpc DeleteService (DeleteServiceRequest) returns (DeleteServiceReply) {}
// List all services already deployed in Core.
rpc ListServices (ListServicesRequest) returns (ListServicesReply) {}
// Get the definition of an already-deployed service from its ID.
rpc GetService (GetServiceRequest) returns (GetServiceReply) {}
// ServiceLogs gives a stream for dependency logs of a service.
rpc ServiceLogs (ServiceLogsRequest) returns (stream LogData) {}
}
// The request's data for the `ListenEvent` stream's API.
//
// **Example**
// ```json
// {
// "serviceID": "__SERVICE_ID__",
// "eventFilter": "__EVENT_KEY_TO_MATCH__"
// }
// ```
message ListenEventRequest {
string serviceID = 1; // The Service ID. Generated when using the [`DeployService` API](#deployservice).
string eventFilter = 2; // __Optional.__ Event's key to filter. The event must match this key. The default is `*` which matches any event.
}
// The data received from the stream of the `ListenEvent` API.
// The data will be received over time as long as the stream is open.
//
// **Example**
// ```json
// {
// "eventKey": "__EVENT_KEY__",
// "eventData": "{\"foo\":\"bar\"}"
// }
// ```
message EventData {
string eventKey = 1; // The event's key.
string eventData = 2; // The event's data encoded in JSON.
}
// The request's data for the `ListenResult` stream API.
//
// **Example**
// ```json
// {
// "serviceID": "__SERVICE_ID__",
// "taskFilter": "__TASK_KEY_TO_MATCH__",
// "outputFilter": "__OUTPUT_KEY_TO_MATCH__",
// "tagFilters": ["tagX"]
// }
// ```
message ListenResultRequest {
string serviceID = 1; // The Service ID. Generated when using the [`DeployService` API](#deployservice).
string taskFilter = 2; // __Optional.__ The task's key to filter. The task must match this key. The default is `*` which matches any task.
string outputFilter = 3; // __Optional.__ The output's key from the task to filter. The task must return this output's key. The default is `*` which matches any output.
repeated string tagFilters = 4; // __Optional.__ The list of tags to filter. This is a "match all" list. All tags in parameters should be included in the execution to match.
}
// The data received from the stream of the `ListenResult` API.
// The data will be received over time as long as the stream is open.
//
// **Example**
// ```json
// {
// "executionID": "__EXECUTION_ID__",
// "taskKey": "__TASK_KEY__",
// "outputKey": "__OUTPUT_KEY__",
// "outputData": "{\"foo\":\"bar\"}",
// "executionTags": ["executionX", "test"],
// "error": "error from the execution if something went wrong",
// }
// ```
message ResultData {
string executionID = 1; // The unique identifier of the execution.
string taskKey = 2; // The key of the executed task.
string outputKey = 3; // The output's key from the returned task.
string outputData = 4; // The output's data from the returned task, encoded in JSON.
repeated string executionTags = 5; // The list of tags associated with the execution.
string error = 6; // The execution's error if something went wrong.
}
// The request's data for the `ExecuteTask` API.
//
// **Example**
// ```json
// {
// "serviceID": "__SERVICE_ID__",
// "taskKey": "__TASK_KEY__",
// "inputData": "{\"foo\":\"bar\"}",
// "executionTags": ["executionX", "test"]
// }
// ```
message ExecuteTaskRequest {
string serviceID = 1; // The Service ID. Generated when using the [`DeployService` API](#deployservice).
string taskKey = 2; // The task's key to execute.
string inputData = 3; // The inputs of the task to execute, encoded in JSON.
repeated string executionTags = 4; // __Optional.__ The list of tags to associate with the execution
}
// The reply's data of the `ExecuteTask` API.
//
// **Example**
// ```json
// {
// "executionID": "__EXECUTION_ID__"
// }
// ```
message ExecuteTaskReply {
string executionID = 1; // The unique identifier of the execution.
}
// The request's data for the `StartService` API.
//
// **Example**
// ```json
// {
// "serviceID": "__SERVICE_ID__"
// }
// ```
message StartServiceRequest {
string serviceID = 1; // The Service ID. Generated when using the [`DeployService` API](#deployservice).
}
// Reply of `StartService` API doesn't contain any data.
message StartServiceReply {
}
// The request's data for the `StopService` API.
//
// **Example**
// ```json
// {
// "serviceID": "__SERVICE_ID__"
// }
// ```
message StopServiceRequest {
string serviceID = 1; // The Service ID. Generated when using the [`DeployService` API](#deployservice).
}
// Reply of `StopService` API doesn't contain any data.
message StopServiceReply {
}
// The data sent to the request stream of the `DeployService` API.
// Stream should be closed after url or all chunks sent to server.
//
// **Example**
// ```json
// {
// "env": {
// "key": "value"
// },
// "url": "__SERVICE_GIT_URL__"
// }
// ```
// or
// ```json
// {
// "env": {
// "key": "value"
// },
// "chunk": "__SERVICE_GZIPPED_TAR_FILE_CHUNK__"
// }
// ```
message DeployServiceRequest {
oneof value {
string url = 2; // Git repo url of service. When url provided, stream will be closed after the first receive.
bytes chunk = 3; // Chunks of gzipped tar archive of service. If chunk provided, stream should be closed by client after all chunks sent.
}
map<string, string> env = 4; // Env used to deploy service.
}
// The data received from the reply stream of the `DeployService` API.
// Stream will be closed by server after deployment is done.
//
// **Example**
// ```json
// {
// "status": {
// "message": "__STATUS_MESSAGE__",
// "type": "__STATUS_TYPE__",
// }
// }
// ```
// or
// ```json
// {
// "serviceID": "__SERVICE_ID__"
// }
// ```
// or
// ```json
// {
// "validationError": "__SERVICE_VALIDATION_ERROR__"
// }
// ```
message DeployServiceReply {
message Status {
enum Type {
RUNNING = 0; // RUNNING indicates that status message belongs to a continuous state.
DONE_POSITIVE = 1; // DONE_POSITIVE indicates that status message belongs to a positive noncontinuous state.
DONE_NEGATIVE = 2; // DONE_NEGATIVE indicates that status message belongs to a negative noncontinuous state.
}
string message = 1; // Status message.
Type type = 2; // Type of status message.
}
oneof value {
Status status = 2; // `status` will be sent after each status change.
string serviceID = 3; // `serviceID` will be sent as the last message of stream when service deployed successfully.
string validationError = 4; // `validationError` will be sent as the last message of stream when there is a validation error.
}
}
// Request's data of the `DeleteService` API.
//
// **Example**
// ```json
// {
// "serviceID": "__SERVICE_ID__"
// }
// ```
message DeleteServiceRequest {
string serviceID = 1; // The Service ID. Generated when using the [`DeployService` API](#deployservice).
bool deleteData = 2; // When enabled, any persistent data (volumes) that belongs to service and its dependencies will be also deleted.
}
// Reply of `DeleteService` API doesn't contain any data.
message DeleteServiceReply {
}
// Reply of `ListServices` API doesn't contain any data.
message ListServicesRequest {
}
// The reply's data of the `ListServices` API.
//
// **Example**
// ```json
// {
// "services": [{
// "id": "idX",
// "sid": "sidX",
// "name": "serviceX",
// "description": "descriptionX",
// "status": "statusX",
// "events": [{
// "key": "eventX",
// "name": "nameX",
// "description": "descriptionX",
// "data": [{
// "key": "dataX",
// "name": "nameX",
// "description": "descriptionX",
// "type": "String",
// "optional": true
// }]
// }],
// "tasks": [{
// "key": "taskX",
// "name": "nameX",
// "description": "descriptionX",
// "inputs": [{
// "key": "foo",
// "name": "nameX",
// "description": "descriptionX",
// "type": "String",
// "optional": true
// }],
// "outputs": [{
// "key": "outputX",
// "name": "nameX",
// "description": "descriptionX",
// "data": [{
// "key": "resX",
// "name": "nameX",
// "description": "descriptionX",
// "type": "String",
// "optional": false
// }]
// }]
// }]
// }]
// }
// ```
message ListServicesReply {
repeated Service services = 1; // The list of previously-deployed services' definitions.
}
// The request's data for the `GetService` API.
//
// **Example**
// ```json
// {
// "serviceID": "__SERVICE_ID__"
// }
// ```
message GetServiceRequest {
string serviceID = 1; // The Service ID. Generated when using the [`DeployService` API](#deployservice).
}
// The reply's data of the `GetService` API.
//
// **Example**
// ```json
// {
// "service": {
// "id": "idX",
// "sid": "sidX",
// "name": "serviceX",
// "description": "descriptionX",
// "status": "statusX",
// "events": [{
// "key": "eventX",
// "name": "nameX",
// "description": "descriptionX",
// "data": [{
// "key": "dataX",
// "name": "nameX",
// "description": "descriptionX",
// "type": "String",
// "optional": true
// }]
// }],
// "tasks": [{
// "key": "taskX",
// "name": "nameX",
// "description": "descriptionX",
// "inputs": [{
// "key": "foo",
// "name": "nameX",
// "description": "descriptionX",
// "type": "String",
// "optional": true
// }],
// "outputs": [{
// "key": "outputX",
// "name": "nameX",
// "description": "descriptionX",
// "data": [{
// "key": "resX",
// "name": "nameX",
// "description": "descriptionX",
// "type": "String",
// "optional": false
// }]
// }]
// }]
// }
// }
// ```
message GetServiceReply {
Service service = 1; // Service's definition.
}
// The request's data for `ServiceLogs` API.
//
// **Example**
// ```json
// {
// "serviceID": "__SERVICE_ID__",
// "dependencies": ["__SERVICE_DEPENDENCY__"]
// }
// ```
message ServiceLogsRequest {
string serviceID = 1; // The Service ID. Generated when using the [`DeployService` API](#deployservice).
repeated string dependencies = 2; // __Optional.__ List of dependencies to filter service logs. All by default.
}
// The data received from the stream of the `ServiceLogs` API.
// The data will be received over time as long as the stream is open.
//
// **Example**
// ```json
// {
// "dependency": "__SERVICE_DEPENDENCY__",
// "type": "__LOG_TYPE__",
// "data": "__LOG_CHUNK__",
// }
// ```
message LogData {
enum Type {
Standard = 0; // Standard represents standard log output.
Error = 1; // Error represents error log output.
}
string dependency = 1; // Service dependency that data belongs.
Type type = 2; // The log type.
bytes data = 3; // Log data chunk.
}
// This is the definition of a MESG Service.
message Service {
enum Status {
UNKNOWN = 0;
STOPPED = 1;
STARTING = 2;
PARTIAL = 3;
RUNNING = 4;
}
string hash = 10; // Service's hash.
string sid = 12; // Service's sid.
string name = 1; // Service's name.
string description = 2; // Service's description.
repeated Task tasks = 5; // The list of tasks this service can execute.
repeated Event events = 6; // The list of events this service can emit.
repeated Dependency dependencies = 7; // The Docker dependencies this service requires.
string repository = 9; // Service's repository that contain its source code.
Status status = 11; // Service's status.
}
// Events are emitted by the service whenever the service wants.
message Event {
string key = 4; // Event's key.
string name = 1; // Event's name.
string description = 2; // Event's description.
repeated Parameter data = 3; // List of data of this event.
}
// A task is a function that requires inputs and returns output.
message Task {
string key = 8; // Task's key.
string name = 1; // Task's name.
string description = 2; // Task's description.
repeated Parameter inputs = 6; // List inputs of this task.
repeated Output outputs = 7; // List of outputs this task can return.
}
// A output is the data a task must return.
message Output {
string key = 4; // Output's key.
string name = 1; // Output's name.
string description = 2; // Output's description.
repeated Parameter data = 3; // List of data of this output.
}
// A parameter is the definition of a specific value.
message Parameter {
string key = 8; // Parameter's key.
string name = 1; // Parameter's name.
string description = 2; // Parameter's description.
string type = 3; // Parameter's type: `String`, `Number`, `Boolean`, `Object` or `Any`.
bool optional = 4; // Set the parameter as optional.
bool repeated = 9; // Mark a parameter as an array of the defined type
repeated Parameter object = 10; // Optional object structure definition when type is set to `Object`
}
// A dependency is a configuration of an other Docker container that runs separately from the service.
message Dependency {
string key = 8; // Dependency's key.
string image = 1; // Image's name of the Docker.
repeated string volumes = 2; // List of volumes.
repeated string volumesfrom = 3; // List of volumes mounted from other dependencies.
repeated string ports = 4; // List of ports the container exposes.
string command = 5; // Command to run the container.
}