remotestate

package
v1.12.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 3, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package remotestate provides the HTTP client, token resolution, plan conversion, and run-ID derivation for orun-backend remote state.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BackendJobStatusToLocal 

func BackendJobStatusToLocal(s string) string

BackendJobStatusToLocal converts a backend job status string to the local status string used by state.JobState.

func DeriveRunID 

func DeriveRunID(planID, explicitID string) string

DeriveRunID computes the remote run ID according to the documented precedence:

  1. explicitID (from --exec-id or ORUN_EXEC_ID)
  2. GitHub Actions: gh-{GITHUB_RUN_ID}-{GITHUB_RUN_ATTEMPT}-{planID}
  3. Local fallback: local-{planID}-{randomHex6}

func LocalJobStatusToBackend 

func LocalJobStatusToBackend(s string) string

LocalJobStatusToBackend converts a local job status to a backend status value.

Types

type APIError 

type APIError struct {
	Message string `json:"error"`
	Code    string `json:"code"`
}

APIError represents a decoded backend error envelope.

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) IsAuth 

func (e *APIError) IsAuth() bool

IsAuth reports whether the error is an authentication/authorization failure.

type BackendPlan 

type BackendPlan struct {
	Checksum  string           `json:"checksum"`
	Version   string           `json:"version"`
	Jobs      []BackendPlanJob `json:"jobs"`
	CreatedAt string           `json:"createdAt"`
}

BackendPlan is the plan format expected by the orun-backend CreateRun API.

func ConvertPlan 

func ConvertPlan(plan *model.Plan) *BackendPlan

ConvertPlan converts a CLI model.Plan to the BackendPlan format without mutating the original plan.

type BackendPlanJob 

type BackendPlanJob struct {
	JobID     string            `json:"jobId"`
	Component string            `json:"component"`
	Deps      []string          `json:"deps"`
	Steps     []BackendPlanStep `json:"steps"`
}

BackendPlanJob is a job entry in BackendPlan.

type BackendPlanStep 

type BackendPlanStep struct {
	StepID string                 `json:"stepId"`
	Uses   string                 `json:"uses"`
	With   map[string]interface{} `json:"with"`
}

BackendPlanStep is a step entry in BackendPlanJob.

type ClaimJobRequest 

type ClaimJobRequest struct {
	RunnerID string `json:"runnerId"`
}

ClaimJobRequest is the body for POST /v1/runs/{runID}/jobs/{jobID}/claim.

type ClaimJobResponse 

type ClaimJobResponse struct {
	Claimed       bool   `json:"claimed"`
	Takeover      bool   `json:"takeover,omitempty"`
	CurrentStatus string `json:"currentStatus,omitempty"`
	DepsWaiting   bool   `json:"depsWaiting,omitempty"`
	DepsBlocked   bool   `json:"depsBlocked,omitempty"`
}

ClaimJobResponse represents the extended coordinator claim result.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is an HTTP client for the orun-backend REST API.

func NewClient 

func NewClient(baseURL, version string, tokenSrc TokenSource) *Client

NewClient creates a Client for baseURL using the given TokenSource and CLI version.

func (*Client) ClaimJob 

func (c *Client) ClaimJob(ctx context.Context, runID, jobID, runnerID string) (*ClaimJobResponse, error)

ClaimJob calls POST /v1/runs/{runID}/jobs/{jobID}/claim. This operation is not retried on 5xx because partial state may exist.

func (*Client) CreateRun 

func (c *Client) CreateRun(ctx context.Context, req CreateRunRequest) (*RunResponse, error)

CreateRun calls POST /v1/runs. Idempotent: if the run already exists the backend verifies the plan checksum and returns the existing run.

func (*Client) GetLog 

func (c *Client) GetLog(ctx context.Context, runID, jobID string) (string, error)

GetLog calls GET /v1/runs/{runID}/logs/{jobID} and returns the log as a string.

func (*Client) GetRun 

func (c *Client) GetRun(ctx context.Context, runID string) (*RunResponse, error)

GetRun calls GET /v1/runs/{runID}.

func (*Client) GetRunnable 

func (c *Client) GetRunnable(ctx context.Context, runID string) ([]string, error)

GetRunnable calls GET /v1/runs/{runID}/runnable.

func (*Client) Heartbeat 

func (c *Client) Heartbeat(ctx context.Context, runID, jobID, runnerID string) error

Heartbeat calls POST /v1/runs/{runID}/jobs/{jobID}/heartbeat.

func (*Client) ListJobs 

func (c *Client) ListJobs(ctx context.Context, runID string) ([]JobResponse, error)

ListJobs calls GET /v1/runs/{runID}/jobs.

func (*Client) UpdateJob 

func (c *Client) UpdateJob(ctx context.Context, runID, jobID, runnerID, status, errText string) error

UpdateJob calls POST /v1/runs/{runID}/jobs/{jobID}/update. Not retried because the backend is idempotent by run+job+runner identity and a duplicate terminal update is harmless.

func (*Client) UploadLog 

func (c *Client) UploadLog(ctx context.Context, runID, jobID, content string) error

UploadLog calls POST /v1/runs/{runID}/logs/{jobID} with the log content as plain text. Uses the longer log upload timeout.

type CreateRunRequest 

type CreateRunRequest struct {
	Plan        *BackendPlan `json:"plan"`
	RunID       string       `json:"runId,omitempty"`
	DryRun      bool         `json:"dryRun,omitempty"`
	TriggerType string       `json:"triggerType,omitempty"`
	Actor       string       `json:"actor,omitempty"`
}

CreateRunRequest is the body for POST /v1/runs.

type HeartbeatRequest 

type HeartbeatRequest struct {
	RunnerID string `json:"runnerId"`
}

HeartbeatRequest is the body for POST /v1/runs/{runID}/jobs/{jobID}/heartbeat.

type HeartbeatResponse 

type HeartbeatResponse struct {
	OK bool `json:"ok"`
}

HeartbeatResponse is returned by the heartbeat endpoint.

type JobResponse 

type JobResponse struct {
	JobID       string   `json:"jobId"`
	RunID       string   `json:"runId"`
	Component   string   `json:"component"`
	Status      string   `json:"status"`
	Deps        []string `json:"deps"`
	RunnerID    *string  `json:"runnerId"`
	StartedAt   *string  `json:"startedAt"`
	FinishedAt  *string  `json:"finishedAt"`
	LastError   *string  `json:"lastError"`
	HeartbeatAt *string  `json:"heartbeatAt"`
	LogRef      *string  `json:"logRef"`
}

JobResponse is the backend Job object.

type ListJobsResponse 

type ListJobsResponse struct {
	Jobs []JobResponse `json:"jobs"`
}

ListJobsResponse wraps the job list from GET /v1/runs/{runID}/jobs.

type LogUploadResponse 

type LogUploadResponse struct {
	OK     bool   `json:"ok"`
	LogRef string `json:"logRef"`
}

LogUploadResponse is returned by POST /v1/runs/{runID}/logs/{jobID}.

type OIDCTokenSource 

type OIDCTokenSource struct {
	Audience string
	// contains filtered or unexported fields
}

OIDCTokenSource requests a GitHub Actions OIDC token from the GitHub Actions token endpoint with the configured audience.

func NewOIDCTokenSource 

func NewOIDCTokenSource(audience string) *OIDCTokenSource

NewOIDCTokenSource returns an OIDCTokenSource using the given audience (default "orun" if empty).

func (*OIDCTokenSource) Token 

func (o *OIDCTokenSource) Token(ctx context.Context) (string, error)

Token fetches a fresh OIDC token from the GitHub Actions token endpoint.

type RunResponse 

type RunResponse struct {
	RunID        string  `json:"runId"`
	Status       string  `json:"status"`
	PlanChecksum string  `json:"planChecksum"`
	TriggerType  string  `json:"triggerType"`
	Actor        *string `json:"actor"`
	CreatedAt    string  `json:"createdAt"`
	UpdatedAt    string  `json:"updatedAt"`
	FinishedAt   *string `json:"finishedAt"`
	JobTotal     int     `json:"jobTotal"`
	JobDone      int     `json:"jobDone"`
	JobFailed    int     `json:"jobFailed"`
	DryRun       bool    `json:"dryRun"`
}

RunResponse is the backend Run object returned by /v1/runs/*.

type RunnableResponse 

type RunnableResponse struct {
	JobIDs []string `json:"jobs"`
}

RunnableResponse is from GET /v1/runs/{runID}/runnable.

type StaticTokenSource 

type StaticTokenSource struct {
	// contains filtered or unexported fields
}

StaticTokenSource returns a pre-configured bearer token as-is.

func NewStaticTokenSource 

func NewStaticTokenSource(token string) *StaticTokenSource

NewStaticTokenSource wraps a fixed bearer token (e.g. from ORUN_TOKEN).

func (*StaticTokenSource) Token 

func (s *StaticTokenSource) Token(_ context.Context) (string, error)

Token returns the static token or an error if it is empty.

type TokenSource 

type TokenSource interface {
	Token(ctx context.Context) (string, error)
}

TokenSource resolves the bearer token for backend requests.

func ResolveTokenSource 

func ResolveTokenSource() (TokenSource, error)

ResolveTokenSource returns the appropriate TokenSource based on the current environment:

  • GitHub Actions with id-token:write → OIDCTokenSource (audience "orun")
  • ORUN_TOKEN set → StaticTokenSource
  • Otherwise → error

type UpdateJobRequest 

type UpdateJobRequest struct {
	RunnerID string `json:"runnerId"`
	Status   string `json:"status"`
	Error    string `json:"error,omitempty"`
}

UpdateJobRequest is the body for POST /v1/runs/{runID}/jobs/{jobID}/update.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.