worker

package
v0.17.0 Latest Latest
Warning

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

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

Documentation

Overview

Package worker implements the eval queue worker's run loop: claim, materialise, evaluate, report. Runner abstracts Docker so the loop is testable.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Materialize

func Materialize(dir string, in MaterializeInput) (_ *store.Store, err error)

Materialize builds a whetstone workspace at dir from a downloaded bundle and suite.

Types

type API

type API interface {
	Claim(ctx context.Context, workerID string, lease time.Duration) (*evalqueue.Job, string, bool, error)
	Heartbeat(ctx context.Context, id evalqueue.JobID, token string) error
	PostReport(ctx context.Context, id evalqueue.JobID, token string, r *report.Report) error
	// PostContestReport sends every candidate's report, keyed by label. The
	// server decides the verdict: a worker sends measurements, never a result.
	PostContestReport(ctx context.Context, contestID string, jobID evalqueue.JobID, token string, reports map[string]*report.Report) error
	FailJob(ctx context.Context, id evalqueue.JobID, token, cause string) error
	FetchSuite(ctx context.Context, ref string) ([]byte, error)
	FetchBundle(ctx context.Context, skill string, version int) ([]byte, error)
	SuiteMeta(ctx context.Context, ref string) (SuiteMeta, error)
	PushSuite(ctx context.Context, in PushSuiteInput) (string, error)
}

API is the server surface the worker needs, so a test can fake it.

type Config

type Config struct {
	Endpoint string
	APIKey   string
	WorkerID string

	Lease        time.Duration // default 5m
	Heartbeat    time.Duration // default Lease/3
	PollInterval time.Duration // default 15s
	WorkRoot     string        // scratch; default os.TempDir()
	Tier         string        // default from the job
}

Config configures a Worker.

type DeriveInput added in v0.11.0

type DeriveInput struct {
	Skill  string
	Bundle []byte
	Tier   string
	Panel  evalqueue.Panel
}

DeriveInput is what a Deriver needs to build a suite for one job.

type DeriveResult added in v0.11.0

type DeriveResult struct {
	Archive []byte
	// Tasks is how many evals the derived suite holds, for the log line only.
	Tasks int
	Spec  *spec.SkillSpec
}

DeriveResult is a suite ready to push to the registry.

type Deriver added in v0.11.0

type Deriver interface {
	Derive(ctx context.Context, in DeriveInput) (*DeriveResult, error)
	// Contest derives one suite covering every candidate, so no candidate's
	// own claims set the bar.
	Contest(ctx context.Context, ins []DeriveInput) (*DeriveResult, error)
}

Deriver builds a suite for a skill that has none.

type HTTPAPI

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

HTTPAPI implements API over the skael HTTP surface.

func NewHTTPAPI

func NewHTTPAPI(endpoint, apiKey string) *HTTPAPI

NewHTTPAPI builds an HTTPAPI.

func (*HTTPAPI) Claim

func (h *HTTPAPI) Claim(_ context.Context, workerID string, lease time.Duration) (*evalqueue.Job, string, bool, error)

Claim calls POST /api/eval/jobs/claim.

func (*HTTPAPI) FailJob

func (h *HTTPAPI) FailJob(_ context.Context, id evalqueue.JobID, token, cause string) error

FailJob calls POST /api/eval/jobs/{id}/fail.

func (*HTTPAPI) FetchBundle

func (h *HTTPAPI) FetchBundle(_ context.Context, skill string, version int) ([]byte, error)

FetchBundle calls GET /api/skills/{name}/versions/{version}/download.

func (*HTTPAPI) FetchSuite

func (h *HTTPAPI) FetchSuite(_ context.Context, ref string) ([]byte, error)

FetchSuite calls GET /api/eval/suites/{ref} and returns the raw archive.

func (*HTTPAPI) Heartbeat

func (h *HTTPAPI) Heartbeat(_ context.Context, id evalqueue.JobID, token string) error

Heartbeat calls POST /api/eval/jobs/{id}/heartbeat. Both 409 (job no longer running) and 403 (claim does not verify, including a lapse-and-reclaim race) map to ErrLeaseLost.

func (*HTTPAPI) PostContestReport added in v0.14.0

func (h *HTTPAPI) PostContestReport(_ context.Context, contestID string, _ evalqueue.JobID, token string, reports map[string]*report.Report) error

PostContestReport sends every candidate's report keyed by label. The worker sends measurements; the server decides the verdict.

func (*HTTPAPI) PostReport

func (h *HTTPAPI) PostReport(_ context.Context, id evalqueue.JobID, token string, r *report.Report) error

PostReport calls POST /api/eval/jobs/{id}/report with r's JSON encoding.

func (*HTTPAPI) PushSuite added in v0.11.0

func (h *HTTPAPI) PushSuite(_ context.Context, in PushSuiteInput) (string, error)

PushSuite uploads a derived suite and returns its content-addressed ref.

func (*HTTPAPI) SuiteMeta

func (h *HTTPAPI) SuiteMeta(_ context.Context, ref string) (SuiteMeta, error)

SuiteMeta calls GET /api/eval/suites/{ref}/meta.

type MaterializeInput

type MaterializeInput struct {
	Skill        string
	Bundle       []byte
	SuiteArchive []byte
	// Spec is nil when the suite predates this field; Materialize falls back
	// to a placeholder from SKILL.md frontmatter.
	Spec         *spec.SkillSpec
	WantSuiteRef string
}

MaterializeInput is what Materialize needs to build one job's workspace.

type PushSuiteInput added in v0.11.0

type PushSuiteInput struct {
	Skill      string
	Archive    []byte
	Spec       *spec.SkillSpec
	JobID      evalqueue.JobID
	ClaimToken string
}

PushSuiteInput is one derived-suite upload.

type RunInput

type RunInput struct {
	JobID    evalqueue.JobID
	Skill    string
	Version  int
	SuiteRef string
	Tier     string
	Panel    evalqueue.Panel

	// AllowVoid excludes void tasks instead of refusing. Sourced from the
	// suite's machine_generated flag, not origin — an unreviewed authored
	// push is derived too, and reading origin would hand void tolerance to
	// a half-broken authored suite.
	AllowVoid    bool
	WorkspaceDir string
}

RunInput is what a Runner needs to execute one job's evaluation.

type Runner

type Runner interface {
	Run(ctx context.Context, in RunInput) (*report.Report, error)
}

Runner is the eval half, injected so the loop is testable with no Docker.

type SuiteMeta

type SuiteMeta struct {
	Spec             *spec.SkillSpec
	Origin           evalsuite.Origin
	MachineGenerated bool
}

SuiteMeta is the suite metadata the worker needs beside the archive bytes.

type Worker

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

Worker runs the claim/materialise/evaluate/report loop.

func New

func New(cfg Config, api API, r Runner, deriver Deriver) (*Worker, error)

New builds a Worker. deriver may be nil; such a worker only handles jobs that already name a suite.

func (*Worker) RunOnce

func (w *Worker) RunOnce(ctx context.Context) (worked bool, err error)

RunOnce claims at most one job and runs it to completion. It returns (false, nil) when the queue is empty.

Jump to

Keyboard shortcuts

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