runs

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: 23 Imported by: 0

Documentation

Overview

Package runs prepares frozen runs and owns their durable execution lifecycle. Hosts execute prepared snapshots without a catalog or credential store.

Index

Constants

View Source
const DefaultCaseConcurrency uint32 = 4
View Source
const MaxCaseConcurrency uint32 = 8

Variables

View Source
var (
	ErrInvalid         = errors.New("runs: invalid input")
	ErrNotActive       = errors.New("runs: run is not active")
	ErrNotRunnable     = errors.New("runs: plan target is not runnable")
	ErrClosed          = errors.New("runs: service is closed")
	ErrAlreadyAccepted = errors.New("runs: run is already accepted")
)
View Source
var ErrQuickTaskCredential = errors.New("runs: remembered quick task credential is unavailable")

Functions

func RecoverInterrupted

func RecoverInterrupted(ctx context.Context, repository RecoveryRepository, clock Clock) error

RecoverInterrupted cancels durable non-terminal runs left by a previous process. Restart never resumes paid network traffic implicitly; comparison refresh can then deterministically seal any affected comparison.

Types

type Clock

type Clock interface {
	Now() time.Time
}

type ConnectionCommand added in v0.1.5

type ConnectionCommand struct {
	Protocol        domain.Protocol `json:"protocol"`
	Model           string          `json:"model"`
	ChannelID       string          `json:"channel_id,omitempty"`
	BaseURL         string          `json:"base_url,omitempty"`
	APIKey          string          `json:"api_key,omitempty"`
	CredentialRunID string          `json:"credential_run_id,omitempty"`
}

ConnectionCommand selects an upstream model with a saved channel or a temporary credential. It is consumed before a prepared Run is persisted.

func (ConnectionCommand) GoString added in v0.1.5

func (command ConnectionCommand) GoString() string

func (ConnectionCommand) String added in v0.1.5

func (command ConnectionCommand) String() string

type CredentialStore

type CredentialStore interface {
	Get(context.Context, credentials.StoreRef) (*credentials.Lease, error)
}

type Dependencies

type Dependencies struct {
	Repository           Repository
	QuickTasks           QuickTaskCatalog
	CaseTypes            *casetypes.Registry
	Credentials          CredentialStore
	QuickTaskCredentials credentials.Store
	// MissingRun declares the repository adapter's private not-found sentinel;
	// see PreparationDependencies.MissingRun.
	MissingRun       error
	Executor         Executor
	Clock            Clock
	MetaFactory      MetaFactory
	Environment      EnvironmentProvider
	Reporter         ReportGenerator
	ReportError      func(error)
	ReportDiagnostic func(Diagnostic)
}

type Diagnostic

type Diagnostic struct {
	RunID        string
	RequestID    string
	Operation    string
	ErrorCode    string
	Duration     time.Duration
	DroppedCount uint64
	Err          error
}

type EnvironmentProvider

type EnvironmentProvider func() domain.EnvironmentSnapshot

type ExecutionRepository

type ExecutionRepository interface {
	GetRun(context.Context, string) (domain.Run, error)
	UpdateRun(context.Context, uint64, domain.Run) error
	// AppendResults atomically writes outputs whose suite and case identities
	// have been resolved against the prepared run snapshot by the caller.
	AppendResults(context.Context, ...domain.Result) error
}

ExecutionRepository contains only execution facts, never authored catalogs.

type ExecutionRequest

type ExecutionRequest struct {
	Run         domain.Run
	Entry       domain.RunEntrySnapshot
	Cases       []domain.TestCase
	Credential  *credentials.Lease
	StopSending <-chan struct{}
	OnProgress  func(load.Progress)
}

func (ExecutionRequest) LoadProfile

func (request ExecutionRequest) LoadProfile() domain.LoadProfile

LoadProfile schedules complete Case executions using the entry's policy.

type Executor

type Executor interface {
	Execute(context.Context, ExecutionRequest, func(ResultDraft) error) error
}

type Host

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

Host executes complete frozen runs independently of the preparing client.

func NewHost

func NewHost(dependencies HostDependencies) (*Host, error)

func (*Host) ActivateRun

func (service *Host) ActivateRun(ctx context.Context, runID string) error

func (*Host) AdoptQueued

func (service *Host) AdoptQueued(
	ctx context.Context,
	runID string,
	lease *credentials.Lease,
) error

AdoptQueued takes ownership of lease on every path. Admission must already have persisted the complete Run; adoption never creates execution facts.

func (*Host) CancelRun

func (service *Host) CancelRun(ctx context.Context, runID string) error

func (*Host) Close

func (service *Host) Close() error

func (*Host) FailRun

func (service *Host) FailRun(ctx context.Context, runID string, failure domain.RunFailure) error

FailRun records an explicit owner failure before stopping active requests. It also stops this Run's terminal retry loop when storage is unavailable.

func (*Host) GetRun

func (service *Host) GetRun(ctx context.Context, runID string) (domain.Run, error)

func (*Host) StopSending

func (service *Host) StopSending(ctx context.Context, runID string) error

func (*Host) WaitRun

func (service *Host) WaitRun(ctx context.Context, runID string) (domain.Run, error)

WaitRun observes completion without owning or cancelling execution. A terminal status alone is insufficient: all workers and report callbacks must finish before the owner can release resources or settle a complete Job.

type HostDependencies

type HostDependencies struct {
	Repository       ExecutionRepository
	Executor         Executor
	Clock            Clock
	MetaFactory      MetaFactory
	Reporter         ReportGenerator
	ReportError      func(error)
	ReportDiagnostic func(Diagnostic)
	RequestProgress  func(string, load.Progress)
	// PersistenceFailure is a synchronous owner signal, separate from lossy
	// diagnostics. It must return promptly and must not call back into this Host.
	PersistenceFailure func(string)
}

type MetaFactory

type MetaFactory func(time.Time) (domain.EntityMeta, error)

type PreparationDependencies

type PreparationDependencies struct {
	Repository           PreparationRepository
	QuickTasks           QuickTaskCatalog
	CaseTypes            *casetypes.Registry
	Credentials          CredentialStore
	QuickTaskCredentials credentials.Store
	// MissingRun declares the repository adapter's private not-found sentinel
	// so a quick task whose draft references a deleted source run can start
	// from the submitted form values instead of failing.
	MissingRun  error
	Clock       Clock
	MetaFactory MetaFactory
	Environment EnvironmentProvider
}

type PreparationRepository

type PreparationRepository interface {
	GetPlan(context.Context, string) (domain.Plan, error)
	ResolvePlanTargetSelection(
		context.Context, domain.Plan, string, string,
	) (domain.Model, domain.Channel, domain.ChannelModel, error)
	ListTestCases(context.Context) ([]domain.TestCase, error)
	ListSuites(context.Context) ([]domain.Suite, error)
	GetRun(context.Context, string) (domain.Run, error)
}

PreparationRepository is read-only. Preparing a submission cannot start or persist a run in the desktop's operational repository.

type PreparedRun

type PreparedRun struct {
	Meta     domain.EntityMeta  `json:"meta"`
	PlanID   string             `json:"plan_id"`
	Snapshot domain.RunSnapshot `json:"snapshot"`
}

PreparedRun is the complete non-secret input accepted by an execution host. Credentials are transferred separately as a lease and cannot be serialized.

type Preparer

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

Preparer resolves all catalog references before input crosses a host boundary.

func NewPreparer

func NewPreparer(dependencies PreparationDependencies) (*Preparer, error)

func (*Preparer) BuildQuickTask

func (service *Preparer) BuildQuickTask(
	ctx context.Context,
	command QuickTaskCommand,
) (PreparedRun, *credentials.Lease, error)

func (*Preparer) BuildTarget

func (service *Preparer) BuildTarget(
	ctx context.Context,
	command StartCommand,
) (PreparedRun, *credentials.Lease, error)

BuildTarget freezes a target without creating a queued Run. The caller owns the returned lease and must either transfer it to a host or close it.

func (*Preparer) Close

func (service *Preparer) Close()

func (*Preparer) ForgetQuickTaskCredential

func (service *Preparer) ForgetQuickTaskCredential(ctx context.Context, runID string) error

func (*Preparer) LeaseQuickTaskCredential

func (service *Preparer) LeaseQuickTaskCredential(ctx context.Context, runID, baseURL string, protocol domain.Protocol) (*credentials.Lease, error)

LeaseQuickTaskCredential binds a remembered key to its original protocol and complete base URL. A different model/Suite at that target can reuse the key.

func (*Preparer) QuickTask

func (service *Preparer) QuickTask(ctx context.Context, runID string) (QuickTaskDetail, error)

func (*Preparer) QuickTaskPerformancePath

func (service *Preparer) QuickTaskPerformancePath(ctx context.Context, command QuickTaskCommand, selectedProtocol domain.Protocol) (string, error)

QuickTaskPerformancePath resolves the native create endpoint from the selected definitions; performance inputs remain owned by the performance service.

func (*Preparer) RememberQuickTaskCredential

func (service *Preparer) RememberQuickTaskCredential(ctx context.Context, command RememberQuickTaskCredentialCommand) error

RememberQuickTaskCredential is a separate, explicit action after a Run exists. That Run identity owns the keyring entry, so no authored target or credential metadata file is needed and failed attempts cannot orphan an unreferenced key.

type ProtocolExecutor

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

ProtocolExecutor schedules complete Case workflows and immediately emits their bounded results. HTTP status and scheduler completion never fabricate a verdict.

func NewProtocolExecutor

func NewProtocolExecutor(transport http.RoundTripper) *ProtocolExecutor

func (*ProtocolExecutor) Execute

func (executor *ProtocolExecutor) Execute(ctx context.Context, request ExecutionRequest, emit func(ResultDraft) error) error

type QuickTaskCatalog

type QuickTaskCatalog interface {
	GetSuite(context.Context, string) (domain.Suite, error)
	GetChannel(context.Context, string) (domain.Channel, error)
	ListChannelModels(context.Context) ([]domain.ChannelModel, error)
}

type QuickTaskCommand

type QuickTaskCommand struct {
	SuiteID               string                     `json:"suite_id"`
	Seed                  uint64                     `json:"seed"`
	RequestTimeoutSeconds float64                    `json:"request_timeout_seconds"`
	CaseConcurrency       uint32                     `json:"case_concurrency,omitempty"`
	Model                 string                     `json:"model"`
	ChannelID             string                     `json:"channel_id,omitempty"`
	BaseURL               string                     `json:"base_url,omitempty"`
	APIKey                string                     `json:"api_key,omitempty"`
	Inputs                map[string]json.RawMessage `json:"inputs"`
	SourceRunID           string                     `json:"source_run_id,omitempty"`
	CredentialRunID       string                     `json:"credential_run_id,omitempty"`
}

QuickTaskCommand selects the current task definition and either a saved channel or a temporary connection. Model is the upstream identifier, not a catalog ID.

type QuickTaskDetail

type QuickTaskDetail struct {
	Seed                  uint64                     `json:"seed"`
	RequestTimeoutSeconds float64                    `json:"request_timeout_seconds"`
	CaseConcurrency       uint32                     `json:"case_concurrency"`
	SchemaVersion         int                        `json:"schema_version"`
	RunID                 string                     `json:"run_id"`
	Suite                 QuickTaskSuite             `json:"suite"`
	Model                 string                     `json:"model"`
	BaseURL               string                     `json:"base_url"`
	ChannelID             string                     `json:"channel_id,omitempty"`
	CredentialRunID       string                     `json:"credential_run_id,omitempty"`
	Inputs                map[string]json.RawMessage `json:"inputs"`
}

QuickTaskDetail exposes only fields needed to restore a task form. Credentials, request definitions, response bodies, and environment details stay in Core.

type QuickTaskSuite

type QuickTaskSuite struct {
	domain.Suite
	CaseCount int `json:"case_count"`
}

type RecoveryRepository

type RecoveryRepository interface {
	ListRecoveryRuns(context.Context) ([]domain.Run, error)
	UpdateRun(context.Context, uint64, domain.Run) error
}

type RememberQuickTaskCredentialCommand

type RememberQuickTaskCredentialCommand struct {
	RunID    string          `json:"run_id"`
	BaseURL  string          `json:"base_url"`
	Protocol domain.Protocol `json:"protocol"`
	APIKey   string          `json:"api_key"`
}

type ReportGenerator

type ReportGenerator interface {
	Generate(context.Context, string) error
}

type Repository

type Repository interface {
	ExecutionRepository
	PreparationRepository
	CreateRun(context.Context, domain.Run) error
}

type ResultDraft

type ResultDraft struct {
	Performance     json.RawMessage
	CaseID          string
	RequestID       string
	ExecutionStatus domain.ExecutionStatus
	Verification    testspec.Verdict
	Observation     *testspec.Observation
	Failure         domain.FailureKind
	ErrorCode       domain.ErrorCode
	Detail          *domain.ProviderDetail
	Dimensions      map[string]string
	Metrics         map[string]float64
	EvidenceIDs     []string
}

type Service

type Service struct {
	*Host
	*Preparer
	// contains filtered or unexported fields
}

func New

func New(dependencies Dependencies) (*Service, error)

func (*Service) AcceptPrepared

func (service *Service) AcceptPrepared(
	ctx context.Context,
	prepared PreparedRun,
	lease *credentials.Lease,
) (string, error)

AcceptPrepared is the local admission facade. The shared execution Host only adopts existing rows; a Job repository can create a whole group atomically.

func (*Service) Close

func (service *Service) Close() error

func (*Service) PrepareQuickTask

func (service *Service) PrepareQuickTask(ctx context.Context, command QuickTaskCommand) (string, error)

func (*Service) PrepareTarget

func (service *Service) PrepareTarget(ctx context.Context, command StartCommand) (string, error)

PrepareTarget resolves and persists an immutable queued run without starting network work. Comparison orchestration uses this to durably link every target before any goroutine can complete independently.

func (*Service) StartQuickTask

func (service *Service) StartQuickTask(ctx context.Context, command QuickTaskCommand) (string, error)

func (*Service) StartTarget

func (service *Service) StartTarget(ctx context.Context, command StartCommand) (string, error)

type StartCommand

type StartCommand struct {
	PlanID          string             `json:"plan_id"`
	ModelID         string             `json:"model_id"`
	ChannelID       string             `json:"channel_id"`
	CaseConcurrency uint32             `json:"case_concurrency,omitempty"`
	Connection      *ConnectionCommand `json:"connection,omitempty"`
}

func (StartCommand) GoString added in v0.1.5

func (command StartCommand) GoString() string

func (StartCommand) String added in v0.1.5

func (command StartCommand) String() string

Jump to

Keyboard shortcuts

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