statebackend

package
v1.13.1 Latest Latest
Warning

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

 Go to latest Published: May 12, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DeriveRunnerID 

func DeriveRunnerID() string

DeriveRunnerID builds a stable runner identifier from the environment. In GitHub Actions it includes the GITHUB_JOB and GITHUB_RUN_ID so that concurrent matrix jobs have distinct identifiers.

Types

type Backend 

type Backend interface {
	// InitRun creates or joins a run for the given plan. Returns the run handle.
	InitRun(ctx context.Context, plan *model.Plan, opts InitRunOptions) (*RunHandle, error)

	// ClaimJob attempts to claim a job for this runner. The caller must inspect
	// ClaimResult to decide whether to execute, wait, or exit.
	ClaimJob(ctx context.Context, runID string, job model.PlanJob, runnerID string) (*ClaimResult, error)

	// Heartbeat signals that the runner is still alive for the given job.
	Heartbeat(ctx context.Context, runID string, jobID string, runnerID string) (*HeartbeatResult, error)

	// UpdateJob sends the terminal status for a job.
	UpdateJob(ctx context.Context, runID string, jobID string, runnerID string, status JobStatus, errText string) error

	// AppendStepLog appends step output to the job-level log.
	AppendStepLog(ctx context.Context, runID string, jobID string, content string) error

	// RunnableJobs returns the list of job IDs that are currently runnable for the given run.
	RunnableJobs(ctx context.Context, runID string) ([]string, error)

	// LoadRunState reads run state for display (status/logs commands).
	LoadRunState(ctx context.Context, runID string) (*state.ExecState, *state.ExecMetadata, error)

	// ReadJobLog retrieves the combined log for a job.
	ReadJobLog(ctx context.Context, runID string, jobID string) (string, error)

	// Close releases any resources held by the backend.
	Close(ctx context.Context) error
}

Backend is the state backend seam. Local filesystem state and remote HTTP state each implement this interface so the runner and commands can use either without embedding transport details.

type ClaimResult 

type ClaimResult struct {
	Claimed       bool
	Takeover      bool
	CurrentStatus string // backend job status when not claimed
	DepsWaiting   bool
	DepsBlocked   bool
}

ClaimResult describes the outcome of a ClaimJob call.

type FileLock added in v1.12.1 

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

FileLock provides cross-process mutual exclusion using advisory file locks. The lock file is created if it does not exist. On Unix systems, the lock is automatically released when the process exits (even on crash).

func NewFileLock added in v1.12.1 

func NewFileLock(path string) *FileLock

NewFileLock returns a lock bound to the given path. The lock is not acquired until Lock or TryLock is called.

func (*FileLock) Lock added in v1.12.1 

func (fl *FileLock) Lock(ctx context.Context) error

Lock acquires an exclusive lock, blocking until the lock is available or ctx is cancelled. Returns a context error on timeout/cancellation.

func (*FileLock) TryLock added in v1.12.1 

func (fl *FileLock) TryLock() (bool, error)

TryLock attempts to acquire the lock without blocking. Returns true if the lock was acquired, false if it is held by another process.

func (*FileLock) Unlock added in v1.12.1 

func (fl *FileLock) Unlock() error

Unlock releases the lock. It is safe to call on an unlocked FileLock.

type FileStateBackend 

type FileStateBackend struct {
	Store *state.Store
	// contains filtered or unexported fields
}

FileStateBackend implements Backend using the local .orun/ filesystem store. When InitRun is called with a plan, the backend provides real cross-process claim semantics using advisory file locks scoped to the execution ID.

func NewFileStateBackend 

func NewFileStateBackend(store *state.Store) *FileStateBackend

NewFileStateBackend wraps an existing state.Store.

func (*FileStateBackend) AppendStepLog 

func (f *FileStateBackend) AppendStepLog(_ context.Context, _, _, _ string) error

AppendStepLog is a no-op locally — the runner writes logs via writeStepLog.

func (*FileStateBackend) ClaimJob 

func (f *FileStateBackend) ClaimJob(ctx context.Context, runID string, job model.PlanJob, _ string) (*ClaimResult, error)

ClaimJob acquires an execution-scoped file lock, checks the current state, and atomically marks the job as running if it can be claimed.

func (*FileStateBackend) Close 

func (f *FileStateBackend) Close(_ context.Context) error

func (*FileStateBackend) Heartbeat 

func (f *FileStateBackend) Heartbeat(_ context.Context, _, _, _ string) (*HeartbeatResult, error)

Heartbeat is a no-op locally.

func (*FileStateBackend) InitRun 

func (f *FileStateBackend) InitRun(_ context.Context, plan *model.Plan, opts InitRunOptions) (*RunHandle, error)

func (*FileStateBackend) InitRunPlan added in v1.12.1 

func (f *FileStateBackend) InitRunPlan(plan *model.Plan)

InitRunPlan stores the plan for dependency checking without creating execution directories. Use this when the runner creates the execution directory separately via Store.CreateExecution.

func (*FileStateBackend) LoadRunState 

func (f *FileStateBackend) LoadRunState(_ context.Context, runID string) (*state.ExecState, *state.ExecMetadata, error)

func (*FileStateBackend) ReadJobLog 

func (f *FileStateBackend) ReadJobLog(_ context.Context, runID string, jobID string) (string, error)

ReadJobLog concatenates all per-step log files for the given job.

func (*FileStateBackend) RunnableJobs 

func (f *FileStateBackend) RunnableJobs(_ context.Context, runID string) ([]string, error)

RunnableJobs returns job IDs whose dependencies are all completed.

func (*FileStateBackend) UpdateJob 

func (f *FileStateBackend) UpdateJob(ctx context.Context, runID, jobID, _ string, status JobStatus, errText string) error

UpdateJob persists the terminal job status under the file lock.

type HeartbeatResult 

type HeartbeatResult struct {
	OK bool
}

HeartbeatResult is returned by Heartbeat.

type InitRunOptions 

type InitRunOptions struct {
	RunID        string
	NamespaceID  string
	RepoFullName string
	DryRun       bool
	Actor        string
	TriggerType  string
}

InitRunOptions carries options for InitRun.

type JobStatus 

type JobStatus string

JobStatus mirrors the backend API terminal status values. 

const (
	JobStatusSuccess JobStatus = "success"
	JobStatusFailed  JobStatus = "failed"
)

type RemoteStateBackend 

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

RemoteStateBackend implements Backend using the orun-backend HTTP API.

func NewRemoteStateBackend 

func NewRemoteStateBackend(client *remotestate.Client, runnerID string) *RemoteStateBackend

NewRemoteStateBackend creates a RemoteStateBackend with the given HTTP client and runner identifier. runnerID should be unique per runner instance.

func (*RemoteStateBackend) AppendStepLog 

func (r *RemoteStateBackend) AppendStepLog(ctx context.Context, runID string, jobID string, content string) error

func (*RemoteStateBackend) ClaimJob 

func (r *RemoteStateBackend) ClaimJob(ctx context.Context, runID string, job model.PlanJob, runnerID string) (*ClaimResult, error)

func (*RemoteStateBackend) Close 

func (r *RemoteStateBackend) Close(_ context.Context) error

func (*RemoteStateBackend) Heartbeat 

func (r *RemoteStateBackend) Heartbeat(ctx context.Context, runID string, jobID string, runnerID string) (*HeartbeatResult, error)

func (*RemoteStateBackend) InitRun 

func (r *RemoteStateBackend) InitRun(ctx context.Context, plan *model.Plan, opts InitRunOptions) (*RunHandle, error)

func (*RemoteStateBackend) LoadRunState 

func (r *RemoteStateBackend) LoadRunState(ctx context.Context, runID string) (*state.ExecState, *state.ExecMetadata, error)

func (*RemoteStateBackend) ReadJobLog 

func (r *RemoteStateBackend) ReadJobLog(ctx context.Context, runID string, jobID string) (string, error)

func (*RemoteStateBackend) RunnableJobs 

func (r *RemoteStateBackend) RunnableJobs(ctx context.Context, runID string) ([]string, error)

func (*RemoteStateBackend) UpdateJob 

func (r *RemoteStateBackend) UpdateJob(ctx context.Context, runID string, jobID string, runnerID string, status JobStatus, errText string) error

type RunHandle 

type RunHandle struct {
	RunID string
}

RunHandle is returned by InitRun.

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.