Documentation
¶
Overview ¶
Package worker implements the eval queue worker's run loop: claim a job from the server, materialise a local whetstone workspace from the downloaded skill bundle and suite, run the evaluation, and post the report back. The Runner interface abstracts the actual eval execution (Docker and all) out of this package, so the loop itself — claiming, heartbeating, abandoning a lost lease, reporting a failure — is fully testable without Docker or a network.
Index ¶
- func Materialize(dir string, in MaterializeInput) (_ *store.Store, err error)
- type API
- type Config
- type HTTPAPI
- func (h *HTTPAPI) Claim(_ context.Context, workerID string, lease time.Duration) (*evalqueue.Job, string, bool, error)
- func (h *HTTPAPI) FailJob(_ context.Context, id evalqueue.JobID, token, cause string) error
- func (h *HTTPAPI) FetchBundle(_ context.Context, skill string, version int) ([]byte, error)
- func (h *HTTPAPI) FetchSuite(_ context.Context, ref string) ([]byte, error)
- func (h *HTTPAPI) Heartbeat(_ context.Context, id evalqueue.JobID, token string) error
- func (h *HTTPAPI) PostReport(_ context.Context, id evalqueue.JobID, token string, r *report.Report) error
- func (h *HTTPAPI) SuiteMeta(_ context.Context, ref string) (SuiteMeta, error)
- type MaterializeInput
- type RunInput
- type Runner
- type SuiteMeta
- type Worker
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, recording the registry's checks so the eval's oracle gate is satisfied by the author's recorded run rather than bypassed.
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
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)
}
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 HTTPAPI ¶
type HTTPAPI struct {
// contains filtered or unexported fields
}
HTTPAPI implements API over the skael HTTP surface, reusing cli/client's retry-with-backoff behaviour and 30s timeout rather than a bare http.Client (which has none).
func NewHTTPAPI ¶
NewHTTPAPI builds an HTTPAPI talking to endpoint, authenticated with apiKey.
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) FetchBundle ¶
FetchBundle calls GET /api/skills/{name}/versions/{version}/download.
func (*HTTPAPI) FetchSuite ¶
FetchSuite calls GET /api/eval/suites/{ref} and returns the raw archive.
func (*HTTPAPI) Heartbeat ¶
Heartbeat calls POST /api/eval/jobs/{id}/heartbeat. A 409 response — the job is no longer running, or its lease already lapsed — is surfaced as evalqueue.ErrLeaseLost, exactly as the in-process queue's own Heartbeat does, so the worker's lease-lost handling does not need to know whether it is talking to Postgres directly or through HTTP.
A 403 is treated the same way here, specifically for Heartbeat: the server's heartbeat handler (internal/evalqueue/routes.go) returns 403 for "the claim just doesn't verify", which covers both a forged token and the case where the job is still `running` with a technically-live lease but this worker's claim_token_hash no longer matches — the lapse-and-reclaim race. Treating only 409 as lease-lost left that branch heartbeating (and eventually trying to post a report) for a job this worker no longer owns; the server would reject the post, but the abandon-promptly property this package exists for would have silently failed in the meantime. FailJob and PostReport keep the narrower 409-only mapping: a 403 there is far more likely a genuinely invalid claim than a live reclaim race, and treating it as lease-lost buys nothing once the run has already finished.
type MaterializeInput ¶
type MaterializeInput struct {
Skill string
Bundle []byte
SuiteArchive []byte
Checks []evalsuite.Check
// Spec is the authored spec.SkillSpec this suite was checked against
// (see evalsuite.Registry.Put's specJSON). Nil when the suite predates
// this field, or the pusher genuinely sent none — Materialize falls back
// to a placeholder reconstructed from the bundle's SKILL.md frontmatter
// in that case, and logs loudly when it does, because that fallback
// silently drops the skill's real deps and purpose.
Spec *spec.SkillSpec
// WantSuiteRef, if set, is checked against the ref of the materialized
// suite tree before anything else runs. A mismatch here means the job's
// suite_ref and the archive FetchSuite actually returned disagree —
// failing fast catches that before an evaluation runs against it for
// however long, only to be rejected when the score is posted.
WantSuiteRef string
}
MaterializeInput is what Materialize needs to build one job's workspace.
type RunInput ¶
type RunInput struct {
JobID evalqueue.JobID
Skill string
Version int
SuiteRef string
Tier string
Panel evalqueue.Panel
// WorkspaceDir already contains an initialised whetstone workspace with
// the skill bundle, the suite, and the suite's recorded checks.
WorkspaceDir string
}
RunInput is what a Runner needs to execute one job's evaluation.
type SuiteMeta ¶
SuiteMeta is everything about a stored suite the worker needs besides the archive bytes themselves: the oracle-gate checks (without which RunEvalWith's gate refuses to run at all) and the spec it was checked against (nil if none was recorded — see MaterializeInput.Spec).
type Worker ¶
type Worker struct {
// contains filtered or unexported fields
}
Worker runs the claim/materialise/evaluate/report loop.
func New ¶
New builds a Worker. cfg's zero-value fields are filled with defaults. WorkRoot is created here (if missing) so a bad path fails at startup rather than on every subsequent job.