golemfactory / task-api

GNU General Public License v3.0
6 stars 2 forks source link

task-api

Golem - application communication interface

This work is in it's alpha stage and under heavy development so the interface may change frequently.

This repository contains the interface that the Golem compatible application should implement as well as constants used by the protocol. The interface and the constants are defined under the golem_task_api/proto directory in the Protocol Buffers files.

This repository also contains programming language specific packages of the gRPC protocol which may be used for concrete implementation. This is for the ease of development of the application but it's not required to use them in the application. If you don't see a programming language you're interested in, feel free to create an issue or even a pull request and we will add it.

The API

The API is divided into two independent parts - requestor and provider.

Requestor

For requestor the app should implement a long running RPC service which implements the RequestorApp interface from the proto files. The app should assume it will have access to a single directory (let's call it work_dir). Each task will have its own separate working directory under the main work_dir. You can assume that for a given task_id the first call will always be CreateTask and the following directories will exist under work_dir and they will be empty:

RPC methods

When the last subtask is successfully verified on the requestor's side, the work_dir/task_id/constants.TASK_OUTPUTS_DIR directory should contain all result files and nothing else.

Environments

Both provider and requestor apps run on top of Golem's execution environments. Environment for requestor is specified in the application definition and cannot vary. Provider environment is specified by the return value of CreateTask call. A single application could use different environments for different types of tasks, it could also use different environment for requestor and provider. Environments have their unique IDs and prerequisites formats. Prerequisites are additional requirements for the environment to run the app (e.g. Docker environment prerequisites specify image). Environment IDs and prerequisites formats are listed in envs.proto file.

Currently the following environments are supported:

Provider

Provider app should implement a short-lived RPC service which implements the ProviderApp interface from the proto files. Short-lived means that there will be only one request issued per service instance, i.e. the service should shutdown automatically after handling the first and only request.

RPC commands