jobhost

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

Documentation

Overview

Package jobhost owns complete-job admission, execution and durable control.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrClosed          = errors.New("job_host_closed")
	ErrCapacity        = errors.New("job_capacity_exceeded")
	ErrIdentity        = errors.New("job_host_identity_mismatch")
	ErrUnavailable     = errors.New("job_host_unavailable")
	ErrCancelled       = errors.New("job_cancelled")
	ErrLocalShutdown   = errors.New("local_shutdown")
	ErrInterrupted     = errors.New("runner_interrupted")
	ErrExecutionLimit  = errors.New("job_execution_timeout")
	ErrMaintenance     = errors.New("runner_maintenance")
	ErrSettlementLimit = errors.New("job_settlement_timeout")
)
View Source
var (
	ErrNotFound = errors.New("job_not_found")
	ErrConflict = errors.New("job_conflict")
	ErrInvalid  = errors.New("invalid_job")
)

Functions

func CoreCapabilities

func CoreCapabilities() jobcontract.RunnerCapabilities

CoreCapabilities describes execution shared by local and remote hosts. Transport-specific management and file services add their own capabilities.

Types

type Acceptance

type Acceptance struct {
	Spec             jobcontract.JobSpec
	Origin           domain.ExecutionOrigin
	SecretCommitment string
	AcceptedAt       time.Time
	ContentClaims    []jobcontent.Claim
}

Acceptance contains a keyed commitment, never task credential bytes.

type Change

type Change struct {
	JobID            string
	ExpectedRevision uint64
	Status           domain.RunStatus
	Failure          *domain.RunFailure
	At               time.Time
}

type Clock

type Clock interface{ Now() time.Time }

type Core

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

Core dispatches every current job kind to its existing execution component. Its owner must close JobHost before Core so owner interruption wins before execution resources are released.

func NewCore

func NewCore(dependencies CoreDependencies) (*Core, error)

func (*Core) Close

func (core *Core) Close() error

func (*Core) Execute

func (core *Core) Execute(ctx context.Context, execution Execution) (Outcome, error)

func (*Core) Settle

func (core *Core) Settle(ctx context.Context, spec jobcontract.JobSpec, outcome Outcome) error

type CoreDependencies

type CoreDependencies struct {
	Repository       CoreRepository
	Runs             runs.Executor
	Transport        http.RoundTripper
	Clock            Clock
	ReportDiagnostic func(runs.Diagnostic)
}

type CoreRepository

type CoreRepository interface {
	RunRepository
	PerformanceExecutionRepository
}

type Dependencies

type Dependencies struct {
	Repository     Repository
	Executor       Executor
	Guard          Guard
	Clock          Clock
	Policy         Policy
	Target         jobcontract.ExecutionTarget
	InstallationID string
	EngineBuildID  string
	NodeID         string
	RunnerVersion  string
	CommitmentKey  []byte
}

type EventPage

type EventPage struct {
	Events       []jobcontract.Event `json:"events"`
	LastSequence uint64              `json:"last_sequence"`
	HasMore      bool                `json:"has_more"`
}

type Execution

type Execution struct {
	Spec        jobcontract.JobSpec
	Secrets     map[string]*credentials.Lease
	StopSending <-chan struct{}
	OnProgress  func(quicktest.PerformanceProgress)
	// A known storage fault must make the owner unavailable before Core joins
	// its workers. This callback must not wait for execution to finish.
	OnPersistenceFailure func()
}

type Executor

type Executor interface {
	Execute(context.Context, Execution) (Outcome, error)
	Settle(context.Context, jobcontract.JobSpec, Outcome) error
}

Execute must return only after requests, callbacks and Core workers stop. Settle seals remaining child facts and reports without sending requests. A non-nil error means execution facts could not be safely persisted.

type Guard

type Guard interface {
	Reserve(context.Context, jobcontract.JobSpec) (io.Closer, error)
}

Guard reserves verified assets, disk space and other admission resources. The reservation remains owned by the Host until all execution has stopped.

type Host

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

func New

func New(ctx context.Context, dependencies Dependencies) (*Host, error)

func (*Host) ApplyCommand

func (host *Host) ApplyCommand(
	ctx context.Context,
	command jobcontract.Command,
) (jobcontract.CommandConfirmation, bool, error)

func (*Host) Close

func (host *Host) Close() error

func (*Host) GoString

func (*Host) GoString() string

func (*Host) Identity

func (host *Host) Identity() Identity

Identity returns non-secret admission identity and the current resource policy.

func (*Host) MarkUnavailable

func (host *Host) MarkUnavailable()

MarkUnavailable isolates dispatch after the process detects a storage fault.

func (*Host) Status

func (host *Host) Status() Status

func (*Host) String

func (*Host) String() string

func (*Host) Submit

func (host *Host) Submit(ctx context.Context, submission *jobcontract.Submission) (jobcontract.Snapshot, bool, error)

Submit consumes and clears the transport secret bytes on every path. Once accepted, neither request cancellation nor response loss owns the execution.

type Identity

type Identity struct {
	Target         jobcontract.ExecutionTarget
	InstallationID string
	EngineBuildID  string
	Origin         domain.ExecutionOrigin
	Policy         Policy
}

type JobListQuery

type JobListQuery struct {
	InstallationID string
	Target         jobcontract.ExecutionTarget
	After          uint64
	Limit          uint32
}

func (JobListQuery) Validate

func (query JobListQuery) Validate() error

type JobPage

type JobPage struct {
	Contract   int                    `json:"contract"`
	Jobs       []jobcontract.Snapshot `json:"jobs"`
	NextCursor string                 `json:"next_cursor"`
	HasMore    bool                   `json:"has_more"`
}

type LocalIdentity

type LocalIdentity struct {
	NodeID         string
	InstallationID string
	CommitmentKey  []byte
}

LocalIdentity belongs to the desktop's operational database. The commitment key authenticates idempotent submissions; it is never a channel credential.

func (*LocalIdentity) Clear

func (identity *LocalIdentity) Clear()

func (LocalIdentity) GoString

func (LocalIdentity) GoString() string

func (LocalIdentity) MarshalJSON

func (LocalIdentity) MarshalJSON() ([]byte, error)

func (LocalIdentity) String

func (LocalIdentity) String() string

func (LocalIdentity) Validate

func (identity LocalIdentity) Validate() error

type Maintenance

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

func NewMaintenance

func NewMaintenance(ctx context.Context, host *Host, store MaintenanceStore) (*Maintenance, error)

func (*Maintenance) Apply

func (maintenance *Maintenance) Apply(
	ctx context.Context,
	command jobcontract.MaintenanceCommand,
) (MaintenanceResult, error)

func (*Maintenance) Owns

func (maintenance *Maintenance) Owns(host *Host) bool

type MaintenanceResult

type MaintenanceResult struct {
	Record jobcontract.MaintenanceRecord `json:"record"`
	Status Status                        `json:"status"`
}

type MaintenanceStore

type MaintenanceStore interface {
	Read(context.Context) (*jobcontract.MaintenanceRecord, error)
	Write(context.Context, jobcontract.MaintenanceRecord) error
	// Sync establishes durability after an ambiguous write. Read visibility alone
	// cannot confirm a failed rename-directory fsync.
	Sync(context.Context) error
}

type Outcome

type Outcome struct {
	Status  domain.RunStatus
	Failure *domain.RunFailure
}

func (Outcome) Validate

func (outcome Outcome) Validate() error

type PerformanceArchiveDocument

type PerformanceArchiveDocument struct {
	Report    quicktest.PerformanceReport
	Reference jobcontract.ReportReference
	Document  []byte
}

Statistical archive bytes are distinct from the complete execution result.

type PerformanceExecutor

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

PerformanceExecutor runs only durably admitted Performance jobs. The JobHost owns dispatch, control and the winning terminal decision.

func NewPerformanceExecutor

func NewPerformanceExecutor(dependencies PerformanceExecutorDependencies) (*PerformanceExecutor, error)

func (*PerformanceExecutor) Execute

func (core *PerformanceExecutor) Execute(ctx context.Context, execution Execution) (Outcome, error)

func (*PerformanceExecutor) Settle

func (core *PerformanceExecutor) Settle(ctx context.Context, spec jobcontract.JobSpec, outcome Outcome) error

type PerformanceExecutorDependencies

type PerformanceExecutorDependencies struct {
	Repository PerformanceExecutionRepository
	Transport  http.RoundTripper
	Clock      Clock
}

type PerformanceObservationWrite

type PerformanceObservationWrite struct {
	JobID            string
	ExpectedRevision uint64
	At               time.Time
	Checkpoint       quicktest.PerformanceCheckpoint
}

type PerformanceRepository

type PerformanceRepository interface {
	RecordPerformanceObservation(context.Context, PerformanceObservationWrite) (jobcontract.PerformanceObservation, error)
	GetPerformanceObservation(context.Context, string) (jobcontract.PerformanceObservation, error)
	SealPerformanceResult(context.Context, string, time.Time) (PerformanceResultDocument, error)
	ReadPerformanceResult(context.Context, string) (PerformanceResultDocument, error)
}

type PerformanceResultDocument

type PerformanceResultDocument struct {
	Result    jobcontract.PerformanceResult
	Reference jobcontract.PerformanceResultReference
	Document  []byte
}

Document is the stored canonical byte sequence. Its digest and download must use these bytes rather than re-encoding Result through another JSON writer.

type Policy

type Policy struct {
	MaxActiveJobs    uint32        `json:"max_active_jobs"`
	MaxQueuedJobs    uint32        `json:"max_queued_jobs"`
	MaxConcurrency   uint32        `json:"max_concurrency"`
	QueueTimeout     time.Duration `json:"queue_timeout"`
	ExecutionTimeout time.Duration `json:"execution_timeout"`
}

func RemotePolicy

func RemotePolicy() Policy

func (Policy) Validate

func (policy Policy) Validate() error

type RunExecutor

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

RunExecutor executes Run and Comparison jobs through the existing Core. Performance jobs have their own execution and observation component.

func NewRunExecutor

func NewRunExecutor(dependencies RunExecutorDependencies) (*RunExecutor, error)

func (*RunExecutor) Close

func (core *RunExecutor) Close() error

Close follows JobHost.Close so it never reclassifies a remote interruption.

func (*RunExecutor) Execute

func (core *RunExecutor) Execute(ctx context.Context, execution Execution) (Outcome, error)

func (*RunExecutor) Settle

func (core *RunExecutor) Settle(ctx context.Context, spec jobcontract.JobSpec, outcome Outcome) error

type RunExecutorDependencies

type RunExecutorDependencies struct {
	Repository       RunRepository
	Executor         runs.Executor
	Clock            Clock
	ReportDiagnostic func(runs.Diagnostic)
}

type RunReportDocument

type RunReportDocument struct {
	Report    domain.Report
	Reference jobcontract.ReportReference
	Document  []byte
}

type Scheduling

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

func NewScheduling

func NewScheduling(host *Host, store TaskConcurrencyStore) (*Scheduling, error)

func (*Scheduling) Apply

func (scheduling *Scheduling) Apply(ctx context.Context, command jobcontract.TaskConcurrencyCommand) error

func (*Scheduling) Owns

func (scheduling *Scheduling) Owns(host *Host) bool

type Status

type Status struct {
	MaxActiveJobs          uint32 `json:"-"`
	Ready                  bool   `json:"ready"`
	Healthy                bool   `json:"healthy"`
	Active                 uint32 `json:"active"`
	Queued                 uint32 `json:"queued"`
	Pending                uint32 `json:"pending"`
	MaintenanceOperationID string `json:"maintenance_operation_id"`
}

type TaskConcurrencyStore

type TaskConcurrencyStore interface {
	Save(context.Context, uint32, uint32) error
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL