Skip to content

Add Runners service proto definitions and related proto changes #66

Description

@rowan-stein

User Request

Add proto definitions for the new Runners service and make additive changes to existing protos needed for the orchestrator refactoring.

Specification

1. New file: proto/agynio/api/runners/v1/runners.proto

Package: agynio.api.runners.v1
Go package: github.com/agynio/api/gen/agynio/api/runners/v1;runnersv1

Service: RunnersService with the following RPCs:

Runner Management

RPC Description
RegisterRunner Register a new runner
GetRunner Get runner by ID
ListRunners List runners (with optional org filter, pagination)
DeleteRunner Delete a runner
ValidateServiceToken Validate service token hash, resolve runner

Workload State

RPC Description
CreateWorkload Record a new workload (caller-provided ID)
UpdateWorkloadStatus Update workload status and containers
DeleteWorkload Remove a workload record
GetWorkload Get workload by ID
ListWorkloadsByThread List workloads for a thread (paginated)
ListWorkloads List all workloads with status filter (paginated) — used by orchestrator

Messages

Runner:

  • EntityMeta (id, created_at, updated_at)
  • Runner (meta, name, organization_id?, identity_id, status)
  • RunnerStatus enum: UNSPECIFIED, PENDING, ENROLLED, OFFLINE

Workload:

  • Workload (meta, runner_id, thread_id, agent_id, organization_id, status, containers[], ziti_identity_id)
  • WorkloadStatus enum: UNSPECIFIED, STARTING, RUNNING, STOPPING, STOPPED, FAILED
  • Container (container_id, name, role, image, status)
  • ContainerRole enum: UNSPECIFIED, MAIN, SIDECAR, INIT
  • ContainerStatus enum: UNSPECIFIED, RUNNING, TERMINATED, WAITING

Conventions to follow:

  • EntityMeta pattern from apps/v1/apps.proto
  • optional string organization_id on Runner (nullable for cluster-scoped)
  • Non-optional organization_id on Workload
  • Service token: RegisterRunnerResponse returns plaintext token; ValidateServiceTokenRequest takes token_hash; Runner message excludes hash
  • All enums prefixed with type name per Buf STANDARD lint
  • Pagination: page_size/page_token/next_page_token

2. New file: proto/agynio/api/gateway/v1/runners.proto

Service: RunnersGateway exposing only:

  • ListWorkloadsByThread — reuses request/response from internal proto
  • GetWorkload — reuses request/response from internal proto

Pattern: Same as gateway/v1/agents.proto — import internal messages, fully-qualified types.

3. Additive change: proto/agynio/api/runner/v1/runner.proto

Add runner_id field to StartWorkloadResponse:

message StartWorkloadResponse {
  string id = 1;
  WorkloadContainers containers = 2;
  WorkloadStatus status = 3;
  WorkloadFailure failure = 4;
  string runner_id = 5;  // NEW
}

4. Additive change: proto/agynio/api/agents/v1/agents.proto

Add organization_id field to Agent message (find appropriate field number — likely next available after existing fields).

Validation

  • All changes must pass buf lint with the repo's existing config
  • buf breaking should pass (all changes are additive)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions