Runs
Runs — run applications built by bldr (a docker-compose-equivalent "runnable"). A run is backed by a build that materialises the selected runnable; with watch, the build watches the workspace and a rebuilt artifact is hot-swapped into (or restarts) the running services. Progress is a task tree (build subtree + service states), like builds/deployments.
Runs — run applications built by bldr (a docker-compose-equivalent
"runnable"). A run is backed by a build that materialises the selected
runnable; with watch, the build watches the workspace and a rebuilt artifact
is hot-swapped into (or restarts) the running services. Progress is a task
tree (build subtree + service states), like builds/deployments.
Service builder.Runs, 5 rpcs.
CreateRun(CreateRunRequest) -> stream RunEvent
Create + attach to a run, streaming its progress tree + service snapshots. Detached: cancelling the stream leaves the run running (manage via StopRun).
Request: CreateRunRequest
message CreateRunRequest {
repeated PortForward publish = 5;
optional string runnable_cid = 6;
optional map<string, string> labels = 7;
}| Field | |
|---|---|
publish | Host→service port forwards, overriding/adding to the runnable's declared ports (applied to the runnable's single service, or by service via a service: prefix later). Reuses PortForward. |
runnable_cid | The Runnable block to run. |
labels | Free-form labels stamped onto the run. bldr.name is the well-known key carrying bldr run --name; it overrides the derived display name. |
Response: RunEvent
Streamed by CreateRun / WatchRun: a leading snapshot, then live events.
message RunEvent {
oneof event {
Run snapshot = 1;
TaskEvent task = 2;
}
}| Field | |
|---|---|
snapshot | |
task | a node in the run's progress tree |
ListRuns(ListRunsRequest) -> ListRunsResponse
Request: ListRunsRequest
message ListRunsRequest {
// no fields
}Response: ListRunsResponse
message ListRunsResponse {
repeated Run runs = 1;
}| Field | |
|---|---|
runs | newest first |
WatchRuns(WatchRunsRequest) -> stream ListRunsResponse
Request: WatchRunsRequest
message WatchRunsRequest {
// no fields
}Response: ListRunsResponse
The same message as ListRunsResponse.
WatchRun(WatchRunRequest) -> stream RunEvent
Request: WatchRunRequest
message WatchRunRequest {
optional string run_id = 1;
}Response: RunEvent
The same message as RunEvent.
StopRun(StopRunRequest) -> StopRunResponse
Stop a run: tear down its services + networks and remove it.
Request: StopRunRequest
message StopRunRequest {
optional string run_id = 1;
}Response: StopRunResponse
message StopRunResponse {
optional bool was_stopped = 1;
}| Field | |
|---|---|
was_stopped | false if the run_id was unknown |
Types used above
Run
A run: a running application. Returned by Create/List and carried as the
leading snapshot on the event streams.
message Run {
optional string id = 1;
optional string name = 2;
optional string runnable = 4;
optional RunState state = 5;
optional uint64 generation = 6;
optional string runnable_cid = 7;
optional string source_build_id = 8;
optional string error = 9;
repeated RunServiceState services = 10;
optional int64 created_at_seconds = 12;
optional int64 started_at_seconds = 13;
optional int64 finished_at_seconds = 14;
optional map<string, string> labels = 16;
}| Field | |
|---|---|
id | |
name | display: the user's --name, else runnable, else the short CID |
runnable | The run-target name the build asked for (bldr build … --run <name>). Empty for a run started from a bare CID: a Runnable block carries no name. |
state | |
generation | bumped each time the source build re-targets this run |
runnable_cid | the current Runnable block CID |
source_build_id | The build whose run target started this, empty when a caller started it from a CID. The only link a run has to a workspace. |
error | set when state == FAILED |
services | |
created_at_seconds | |
started_at_seconds | |
finished_at_seconds | |
labels | Free-form labels attached at create time (same shape as Build.labels / Deployment.labels). bldr.name carries bldr run --name and, when set, is what name above resolves to. |
RunServiceState
The live state of one service (a long-lived pod) in a run.
message RunServiceState {
optional string name = 1;
optional string pod_id = 2;
optional RunServiceStatus status = 3;
optional string log_stream_id = 4;
optional string image_cid = 5;
repeated RunMountState mounts = 6;
repeated RunPortMapping ports = 7;
}| Field | |
|---|---|
name | |
pod_id | |
status | |
log_stream_id | The pod's stdout/stderr log stream id ({peer}/{tenant}/{uuid}). |
image_cid | |
mounts | |
ports | Effective host→service port forwards (the runnable's declared ports plus any CLI -p overrides). The UI turns a TCP mapping into an "open" link. |
RunMountState
The live state of one mounted artifact in a service.
message RunMountState {
optional string dest = 1;
optional string cid = 2;
optional bool hotswap = 3;
optional bool hotswapped = 4;
}| Field | |
|---|---|
dest | |
cid | current backing CID |
hotswap | declared hot-swappable |
hotswapped | the last update was applied as a live hot-swap |
RunPortMapping
A live host→service port forward on a running service.
message RunPortMapping {
optional uint32 host_port = 1;
optional uint32 pod_port = 2;
optional bool udp = 3;
}RunState
enum RunState {
RUN_STATE_UNSPECIFIED = 0;
RUN_STATE_PENDING = 1;
RUN_STATE_BUILDING = 2;
RUN_STATE_RUNNING = 3;
RUN_STATE_FAILED = 4;
RUN_STATE_STOPPED = 5;
}| Value | |
|---|---|
RUN_STATE_UNSPECIFIED | |
RUN_STATE_PENDING | created; backing build not finished yet |
RUN_STATE_BUILDING | backing build running (materialising the runnable) |
RUN_STATE_RUNNING | services are up |
RUN_STATE_FAILED | build or start failed; error is set |
RUN_STATE_STOPPED | stopped by the user |
RunServiceStatus
enum RunServiceStatus {
RUN_SERVICE_STATUS_UNSPECIFIED = 0;
RUN_SERVICE_STATUS_STARTING = 1;
RUN_SERVICE_STATUS_RUNNING = 2;
RUN_SERVICE_STATUS_RESTARTING = 3;
RUN_SERVICE_STATUS_EXITED = 4;
}| Value | |
|---|---|
RUN_SERVICE_STATUS_UNSPECIFIED | |
RUN_SERVICE_STATUS_STARTING | |
RUN_SERVICE_STATUS_RUNNING | |
RUN_SERVICE_STATUS_RESTARTING | restarting after a non-hot-swappable change |
RUN_SERVICE_STATUS_EXITED |
Deployments
Deployments — invoke a Deployment block (a node function + options, declared by a build or addressed directly by CID) and track it like a build. A deployment is side-effecting and never cached: every CreateDeployment runs.
Logs
Logs — read content-addressed log streams by their full id {peer_id}/{tenant}/{uuid}. Auth is enforced here: a request may only touch a stream whose tenant equals the tenant stamped by the gRPC middleware.