Documentation
¶
Index ¶
- Constants
- Variables
- func FingerprintConfig(v any) (string, error)
- func ResolveRoot(cfg Config) (string, error)
- func ResumeCommand(operation, runID string) (string, error)
- type CheckpointEvent
- type Classification
- type ClassifierInput
- type Config
- type Envelope
- type ErrorCause
- type ErrorClass
- type ErrorRecord
- type ErrorRecordData
- type Identity
- type Lease
- type LeaseHeartbeat
- type Store
- func (s *Store) CheckpointPath(operation, runID string) (string, error)
- func (s *Store) ClaimLease(ctx context.Context, operation, runID, holderID string, ttl time.Duration) (*Lease, error)
- func (s *Store) ReadCheckpoint(ctx context.Context, operation, runID string) (*Envelope, error)
- func (s *Store) ReleaseLease(operation string, lease Lease) error
- func (s *Store) RenewLease(ctx context.Context, operation string, lease Lease, ttl time.Duration) (*Lease, error)
- func (s *Store) RootDir() string
- func (s *Store) StartLeaseHeartbeat(ctx context.Context, operation string, lease *Lease, ...) (*LeaseHeartbeat, error)
- func (s *Store) ValidateIdentity(env *Envelope, want Identity) error
- func (s *Store) WriteCheckpoint(ctx context.Context, env Envelope) error
Constants ¶
const ( SchemaVersion = 1 StatusFailedResumable = "failed-resumable" StatusResuming = "resuming" StatusSuccess = "success" )
const ErrorRecordType = "gonimbus.operation.error.v1"
Variables ¶
var ( ErrPathInsideForbiddenRoot = errors.New("checkpoint path resolves inside a forbidden worktree") ErrLeaseHeld = errors.New("resume lease is already held") ErrIdentityMismatch = errors.New("checkpoint identity mismatch") ErrCredentialMaterial = errors.New("checkpoint contains credential material") )
var ErrCredentialsRefreshFailed = provider.ErrCredentialsRefreshFailed
ErrCredentialsRefreshFailed is retained for callers/tests that imported the opcheckpoint sentinel before the provider-layer sentinel existed.
Functions ¶
func FingerprintConfig ¶
func ResolveRoot ¶
func ResumeCommand ¶
Types ¶
type CheckpointEvent ¶
type CheckpointEvent struct {
Type string `json:"type"`
At time.Time `json:"at"`
ErrorClass ErrorClass `json:"error_class,omitempty"`
Detail string `json:"detail,omitempty"`
}
CheckpointEvent preserves audit evidence across failed-resumable -> resuming -> success promotion without forcing every operation into index-run tables.
type Classification ¶
type Classification struct {
Class ErrorClass
Resumable bool
}
Classification is the operation-level interpretation of a fatal error.
func ClassifyFatalError ¶
func ClassifyFatalError(err error, in ClassifierInput) Classification
ClassifyFatalError keeps auth-deny failures ahead of credential-refresh detection so revoked or invalid credentials are never presented as benignly resumable refresh failures.
type ClassifierInput ¶
type ClassifierInput struct {
RefreshableCredentials bool
Interrupted bool
TransientRetryExhausted bool
}
ClassifierInput describes the auth model and trigger context available at the command boundary. RefreshableCredentials permits legacy text-based refresh detection for provider adapters that cannot surface provider.ErrCredentialsRefreshFailed. Prefer provider-marked refresh errors for new provider paths.
type Config ¶
type Config struct {
// RootDir is an explicit checkpoint root. Empty uses AppDataDir.
RootDir string
// AppDataDir is the application data directory used for default storage.
AppDataDir string
// ForbiddenRoots are repo/worktree roots where checkpoint artifacts must not
// be written. Paths are resolved before comparison.
ForbiddenRoots []string
}
Config controls the local operation-checkpoint store.
type Envelope ¶
type Envelope struct {
SchemaVersion int `json:"schema_version"`
Operation string `json:"operation"`
RunID string `json:"run_id"`
ConfigFingerprint string `json:"config_fingerprint"`
CheckpointID string `json:"checkpoint_id"`
Status string `json:"status"`
ErrorClass ErrorClass `json:"error_class,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
Progress map[string]int64 `json:"progress,omitempty"`
Payload json.RawMessage `json:"payload,omitempty"`
Events []CheckpointEvent `json:"events,omitempty"`
}
Envelope is the shared checkpoint wrapper. Operation-specific serializers own Payload; the shared layer owns identity, status, error class, progress, and lease semantics.
type ErrorCause ¶
type ErrorCause struct {
Code string `json:"code"`
Reason string `json:"reason"`
Message string `json:"message"`
Resumable bool `json:"resumable"`
Disposition string `json:"disposition"`
}
ErrorCause carries an additive, command-level classification of the root failure that caused a resumable operation checkpoint.
type ErrorClass ¶
type ErrorClass string
ErrorClass is the stable operation-level failure class emitted in structured runtime errors and stored with resumable checkpoints.
const ( ErrorClassAuthDenied ErrorClass = "auth_denied" ErrorClassCredentialsRefreshFailed ErrorClass = "credentials_refresh_failed" ErrorClassInterrupted ErrorClass = "interrupted" ErrorClassTransientRetryExhausted ErrorClass = "transient_retry_exhausted" ErrorClassRuntimeFailure ErrorClass = "runtime_failure" )
type ErrorRecord ¶
type ErrorRecord struct {
Type string `json:"type"`
TS string `json:"ts"`
Data ErrorRecordData `json:"data"`
}
ErrorRecord is the redacted structured runtime failure surface shared by resumable operations.
func NewErrorRecord ¶
func NewErrorRecord(operation, runID string, class ErrorClass, progress map[string]int64, at time.Time) (ErrorRecord, error)
func NewErrorRecordWithCause ¶
func NewErrorRecordWithCause(operation, runID string, class ErrorClass, cause *ErrorCause, progress map[string]int64, at time.Time) (ErrorRecord, error)
type ErrorRecordData ¶
type ErrorRecordData struct {
Operation string `json:"operation"`
RunID string `json:"run_id"`
ErrorClass ErrorClass `json:"error_class"`
Cause *ErrorCause `json:"cause,omitempty"`
Progress map[string]int64 `json:"progress,omitempty"`
ResumeCommand string `json:"resume_command,omitempty"`
}
type Identity ¶
Identity identifies the operation state that must match before resume may skip work or promote a run.
type Lease ¶
type Lease struct {
RunID string `json:"run_id"`
HolderID string `json:"holder_id"`
ClaimedAt time.Time `json:"claimed_at"`
ExpiresAt time.Time `json:"expires_at"`
}
Lease records an exclusive resume claim.
type LeaseHeartbeat ¶
type LeaseHeartbeat struct {
// contains filtered or unexported fields
}
LeaseHeartbeat renews a resume lease until stopped or until renewal fails.
func (*LeaseHeartbeat) Context ¶
func (h *LeaseHeartbeat) Context() context.Context
func (*LeaseHeartbeat) Stop ¶
func (h *LeaseHeartbeat) Stop() error
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store persists sensitive local operation checkpoints outside the repository.
Source Files