1# remote-apis 2 3This repository contains a collection of APIs which work together to enable 4large scale distributed execution and caching on source code and other inputs. 5It describes how to upload inputs, request the execution, monitor for results, 6and cache those results. It's overall aim is to enable large scale parallel executions 7that wouldn't be feasible on a single system, while minimizing the amount of uploads 8and executions needed by storing data in a content-addressable format and caching results. 9 10### [Remote Execution API](build/bazel/remote/execution/v2/remote_execution.proto) 11 12The Remote Execution API is an API that, at its most general, allows clients to request 13execution of binaries on a remote system. It is intended primarily for use by build systems, 14such as [Bazel](bazel.build), to distribute build and test actions through a worker pool, 15and also provide a central cache of build results. This allows builds to execute 16faster, both by reusing results already built by other clients and by allowing many 17actions to be executed in parallel, in excess of the resource limits of the machine 18running the build. 19 20### [Remote Asset API](build/bazel/remote/asset/v1/remote_asset.proto) 21 22The Remote Asset API is an API to associate Qualifiers and URIs to Digests stored in 23Content Addressable Storage. It is primary intended to allow clients to use semantically 24relevant identifiers, such as a git repository or tarball location, to get the corresponding 25Digest. This mapping may be pushed by a client directly, or dynamically resolved and added 26to CAS by the asset server when fetched by a client. 27 28### [Remote Logstream API](build/bazel/remote/logstream/v1/remote_logstream.proto) 29 30The Remote Logstream API is an API supporting ordered reads and writes of `LogStream` 31resources. It is intented primarily for streaming the stdout and stderr of ongoing Action 32executions, enabling clients to view them while the Action is executing instead of waiting 33for it's completion. 34 35## API users 36 37There are a number of clients and services using these APIs, they are listed 38below. 39 40### Clients 41These tools use the Remote Execution API to distribute builds to workers. 42 43* [Bazel](https://bazel.build) 44* [Buck2](https://github.com/facebook/buck2) 45* [BuildStream](https://buildstream.build/) 46* [Goma Server](https://chromium.googlesource.com/infra/goma/server/) 47* [Justbuild](https://github.com/just-buildsystem/justbuild) (via `--compatible`) 48* [Pants](https://www.pantsbuild.org) 49* [Please](https://please.build) 50* [Recc](https://gitlab.com/bloomberg/recc) 51* [Reclient](https://github.com/bazelbuild/reclient) 52* [Siso](https://chromium.googlesource.com/infra/infra/+/refs/heads/main/go/src/infra/build/siso/) 53 54### Servers 55These applications implement the Remote Execution API to serve build requests 56from the clients above. 57 58* [bazel-remote](https://github.com/buchgr/bazel-remote) (open source, cache only) 59* [Buildbarn](https://github.com/buildbarn) (open source) 60* [BuildBuddy](https://www.buildbuddy.io/) (commercial & open source) 61* [Buildfarm](https://github.com/bazelbuild/bazel-buildfarm) (open source) 62* [BuildGrid](https://buildgrid.build/) (open source) 63* [EngFlow](https://www.engflow.com/) (commercial) 64* [Flare Build Execution](https://flare.build/products/flare-build-execution) (commercial) 65* [Justbuild](https://github.com/just-buildsystem/justbuild/blob/master/doc/tutorial/just-execute.org) (via `--compatible`, open source) 66* [Kajiya](https://chromium.googlesource.com/infra/infra/+/refs/heads/main/go/src/infra/build/kajiya/) (open source) 67* [NativeLink](https://github.com/TraceMachina/nativelink) (open source) 68* [Scoot](https://github.com/twitter/scoot) (open source) 69 70### Workers 71Servers generally distribute work to a fleet of workers. 72The [Remote Worker API](https://docs.google.com/document/d/1s_AzRRD2mdyktKUj2HWBn99rMg_3tcPvdjx3MPbFidU) 73defines a generic protocol for worker and server communication, although, 74this API is considered too heavyweight for most use-cases. Because of that, 75many implementations have designed their own protocols. Links to these APIs 76are provided as a reference below. 77*Adhering to any one of these protocols is not a requirement.* 78 79* [Buildfarm Operation Queues](https://bazelbuild.github.io/bazel-buildfarm/docs/architecture/queues/) 80 * Uses sets of queues for managing different payload requirements. 81* [Buildbarn Remote Worker](https://github.com/buildbarn/bb-remote-execution/blob/master/pkg/proto/remoteworker/remoteworker.proto) 82 * Uses a custom protocol for workers to connect to a scheduler and receive instructions. 83* [BuildGrid Bots](https://buildgrid.build/developer/data_model.html#rwapi) 84 * A server implementation of the Remote Workers API. 85* [Buildbox Worker](https://gitlab.com/BuildGrid/buildbox/buildbox-worker) 86 * A worker implementation of the Remote Workers API. 87 88## API Community 89 90The [Remote Execution APIs 91group](https://groups.google.com/forum/#!forum/remote-execution-apis) hosts 92discussions related to the APIs in this repository. 93 94Interested parties meet monthly via VC to discuss issues related to the APIs, 95and several contributors have organized occasional meetups, hack-a-thons, and 96summits. Joining the email discussion group will automatically add you to the 97Google Calendar invite for the monthly meeting. 98 99## Dependencies 100 101The APIs in this repository refer to several general-purpose APIs published by 102Google in the [Google APIs 103repository](https://github.com/googleapis/googleapis). You will need to refer to 104packages from that repository in order to generate code using this API. If you 105build the repository using the included `BUILD` files, Bazel will fetch the 106protobuf compiler and googleapis automatically. 107 108## Using the APIs 109 110The repository contains `BUILD` files to build the protobuf library with 111[Bazel](https://bazel.build/). If you wish to use them with your own project in 112Bazel, you will possibly want to declare `cc_proto_library`, 113`java_proto_library`, etc. rules that depend on them. 114 115Other build systems will have to run protoc on the protobuf files, and link in 116the googleapis and well-known proto types, manually. 117 118### Go (for non-Bazel build systems) 119 120This repository contains the generated Go code for interacting with the API via 121gRPC. Get it with: 122 123``` 124go get github.com/bazelbuild/remote-apis 125``` 126 127Import it with, for example: 128 129``` 130repb "github.com/bazelbuild/remote-apis/build/bazel/remote/execution/v2" 131``` 132 133## Development 134 135Enable the git hooks to automatically generate Go proto code on commit: 136 137``` 138git config core.hooksPath hooks/ 139``` 140 141This is a local setting, so applies only to this repository. 142