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
- Variables
- func RecoverInterrupted(ctx context.Context, repository RecoveryRepository, clock Clock) error
- type Clock
- type ConnectionCommand
- type CredentialStore
- type Dependencies
- type Diagnostic
- type EnvironmentProvider
- type ExecutionRepository
- type ExecutionRequest
- type Executor
- type Host
- func (service *Host) ActivateRun(ctx context.Context, runID string) error
- func (service *Host) AdoptQueued(ctx context.Context, runID string, lease *credentials.Lease) error
- func (service *Host) CancelRun(ctx context.Context, runID string) error
- func (service *Host) Close() error
- func (service *Host) FailRun(ctx context.Context, runID string, failure domain.RunFailure) error
- func (service *Host) GetRun(ctx context.Context, runID string) (domain.Run, error)
- func (service *Host) StopSending(ctx context.Context, runID string) error
- func (service *Host) WaitRun(ctx context.Context, runID string) (domain.Run, error)
- type HostDependencies
- type MetaFactory
- type PreparationDependencies
- type PreparationRepository
- type PreparedRun
- type Preparer
- func (service *Preparer) BuildQuickTask(ctx context.Context, command QuickTaskCommand) (PreparedRun, *credentials.Lease, error)
- func (service *Preparer) BuildTarget(ctx context.Context, command StartCommand) (PreparedRun, *credentials.Lease, error)
- func (service *Preparer) Close()
- func (service *Preparer) ForgetQuickTaskCredential(ctx context.Context, runID string) error
- func (service *Preparer) LeaseQuickTaskCredential(ctx context.Context, runID, baseURL string, protocol domain.Protocol) (*credentials.Lease, error)
- func (service *Preparer) QuickTask(ctx context.Context, runID string) (QuickTaskDetail, error)
- func (service *Preparer) QuickTaskPerformancePath(ctx context.Context, command QuickTaskCommand, ...) (string, error)
- func (service *Preparer) RememberQuickTaskCredential(ctx context.Context, command RememberQuickTaskCredentialCommand) error
- type ProtocolExecutor
- type QuickTaskCatalog
- type QuickTaskCommand
- type QuickTaskDetail
- type QuickTaskSuite
- type RecoveryRepository
- type RememberQuickTaskCredentialCommand
- type ReportGenerator
- type Repository
- type ResultDraft
- type Service
- func (service *Service) AcceptPrepared(ctx context.Context, prepared PreparedRun, lease *credentials.Lease) (string, error)
- func (service *Service) Close() error
- func (service *Service) PrepareQuickTask(ctx context.Context, command QuickTaskCommand) (string, error)
- func (service *Service) PrepareTarget(ctx context.Context, command StartCommand) (string, error)
- func (service *Service) StartQuickTask(ctx context.Context, command QuickTaskCommand) (string, error)
- func (service *Service) StartTarget(ctx context.Context, command StartCommand) (string, error)
- type StartCommand
Constants ¶
const DefaultCaseConcurrency uint32 = 4
const MaxCaseConcurrency uint32 = 8
Variables ¶
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") )
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 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 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 (*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) FailRun ¶
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) StopSending ¶
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) ForgetQuickTaskCredential ¶
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) 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 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 RecoveryRepository ¶
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 ¶
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) PrepareQuickTask ¶
func (*Service) PrepareTarget ¶
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) StartTarget ¶
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