Documentation
¶
Overview ¶
Package lifecyclehooks runs trusted user-configured commands after WB changes a repository checkout. It is intentionally separate from package hooks, which manages Git's own hook shims and repository policy.
Index ¶
- Constants
- func IdentityFromOrigin(origin string) (string, error)
- func RepositoryIdentity(checkout string) (string, error)
- type Binding
- type CheckReport
- type Config
- type Dispatcher
- func (dispatcher Dispatcher) Check() (CheckReport, error)
- func (dispatcher Dispatcher) Dispatch(_ context.Context, events []Event) (Report, error)
- func (dispatcher Dispatcher) Drain(ctx context.Context, parallel int) (report Report, returnErr error)
- func (dispatcher Dispatcher) GC(options GCOptions) (GCReport, error)
- func (dispatcher Dispatcher) Plan(events []Event) ([]Planned, Report, error)
- func (dispatcher Dispatcher) Resume() (ResumeReport, error)
- func (dispatcher Dispatcher) Retry(receiptID string) (Report, error)
- func (dispatcher Dispatcher) Status(limit int) (Status, error)
- type Event
- type Executor
- type ExecutorCheck
- type FreshnessReader
- type FreshnessView
- type GCOptions
- type GCReport
- type Invocation
- type Match
- type Planned
- type Queued
- type Receipt
- type ReceiptRef
- type Record
- type Report
- type RepositoryMatch
- type ResumeReport
- type Status
- type WorkerHealth
- type WorkerRequest
Constants ¶
const ( ConfigVersion = 1 EventCheckoutUpdated = "checkout-updated" )
const ( ReceiptSucceeded = "succeeded" ReceiptFailed = "failed" )
Receipt statuses a worker writes.
Variables ¶
This section is empty.
Functions ¶
func IdentityFromOrigin ¶ added in v0.173.0
IdentityFromOrigin is the lower-case host/owner/name identity a checkout's origin URL names: the identity the worker puts in every event and receipt, and the one bindings are matched against. A reader that cannot ask Git the way RepositoryIdentity does, because it must run Git through its own hardened helper, derives the identity from the URL it read with this.
func RepositoryIdentity ¶
Types ¶
type CheckReport ¶ added in v0.128.0
type CheckReport struct {
ConfigPath string `json:"config_path"`
Configured bool `json:"configured"`
Executors []ExecutorCheck `json:"executors,omitempty"`
Findings []string `json:"findings,omitempty"`
}
type Config ¶
type Dispatcher ¶
type Dispatcher struct {
ConfigPath string
StateDir string
ReceiptPath string
Now func() time.Time
Run func(context.Context, Invocation) error
EvalSymlinks func(string) (string, error)
LaunchWorker func(WorkerRequest) error
VerifyCheckout func(Event) (string, os.FileInfo, error)
}
func DefaultDispatcher ¶
func DefaultDispatcher() Dispatcher
func (Dispatcher) Check ¶ added in v0.128.0
func (dispatcher Dispatcher) Check() (CheckReport, error)
func (Dispatcher) Dispatch ¶
Dispatch durably enqueues matching events and returns without waiting for external executors. A detached worker is only a wake-up mechanism: queued state remains authoritative if the worker cannot start or is interrupted.
func (Dispatcher) Drain ¶ added in v0.128.0
func (dispatcher Dispatcher) Drain(ctx context.Context, parallel int) (report Report, returnErr error)
Drain executes durable queue entries with bounded concurrency. Only one worker owns a state directory; enqueue uses a separate short-lived lock and therefore never waits for an external command to finish.
func (Dispatcher) GC ¶ added in v0.128.0
func (dispatcher Dispatcher) GC(options GCOptions) (GCReport, error)
func (Dispatcher) Plan ¶ added in v0.128.0
func (dispatcher Dispatcher) Plan(events []Event) ([]Planned, Report, error)
Plan reports the executor/checkouts that an event set would enqueue without mutating queue state or starting a worker.
func (Dispatcher) Resume ¶ added in v0.128.0
func (dispatcher Dispatcher) Resume() (ResumeReport, error)
type ExecutorCheck ¶ added in v0.128.0
type FreshnessReader ¶ added in v0.173.0
type FreshnessReader struct {
ConfigPath string
StateDir string
ReceiptPath string
// contains filtered or unexported fields
}
FreshnessReader reads indexer receipts without writing. A stream that has not changed is not parsed again, and one that only grew is parsed from where the last read ended, so a new receipt costs its own line. It is safe for concurrent use.
func NewFreshnessReader ¶ added in v0.173.0
func NewFreshnessReader(dispatcher Dispatcher) *FreshnessReader
NewFreshnessReader is a reader of dispatcher's configuration, queue and receipt stream, with the paths resolved as the lifecycle-hook worker resolves them: the same defaulting function (Dispatcher.defaults, from DefaultDispatcher) that `wb hooks lifecycle` runs with, so a process started with an XDG_STATE_HOME override reads the stream that override names. It does not start the dispatcher or create any of them.
func (*FreshnessReader) Read ¶ added in v0.173.0
func (r *FreshnessReader) Read() (*FreshnessView, error)
Read loads the hooks configuration, the receipts and the queue. A missing configuration, receipt stream or queue is an empty one, not an error; an invalid configuration, a receipt stream or queue directory that is not trusted (a symbolic link, or not owned by the current user or writable by others) and an unreadable one are errors.
type FreshnessView ¶ added in v0.173.0
type FreshnessView struct {
// contains filtered or unexported fields
}
FreshnessView is one consistent read: the configured executors with the repositories each is bound to, the receipts, and the queued runs.
func (*FreshnessView) Executors ¶ added in v0.173.0
func (v *FreshnessView) Executors(repository string) []string
Executors lists, sorted, the executors bound to a checkout-updated event of repository, which is the lower-case host/owner/name identity the dispatcher matches bindings against.
func (*FreshnessView) Record ¶ added in v0.173.0
func (v *FreshnessView) Record(executor, repository, checkout string) Record
Record is what the view holds of executor on checkout of repository. Receipts and queued jobs are matched on all three, so a path another repository once used does not lend its receipts.
func (*FreshnessView) Signature ¶ added in v0.173.0
func (v *FreshnessView) Signature(repository string, checkouts []string) string
Signature is a digest of everything Record and Executors say for repository on checkouts, so a caller can tell, without Git, that nothing a code-index state depends on besides HEAD has changed.
type Invocation ¶
type Match ¶
type Match struct {
Repositories RepositoryMatch `yaml:"repositories"`
}
type Receipt ¶ added in v0.128.0
type Receipt struct {
SchemaVersion int `json:"schema_version"`
ID string `json:"id"`
Event string `json:"event"`
Repository string `json:"repository"`
Checkout string `json:"checkout"`
OldSHA string `json:"old_sha,omitempty"`
NewSHA string `json:"new_sha"`
Cause string `json:"cause"`
OperationID string `json:"operation_id,omitempty"`
Executor string `json:"executor"`
CoalescedCount int `json:"coalesced_count,omitempty"`
QueuedAt time.Time `json:"queued_at"`
StartedAt time.Time `json:"started_at"`
FinishedAt time.Time `json:"finished_at"`
DurationMS int64 `json:"duration_ms"`
Status string `json:"status"`
Failure string `json:"failure,omitempty"`
Message string `json:"message,omitempty"`
StdoutPath string `json:"stdout_path,omitempty"`
StderrPath string `json:"stderr_path,omitempty"`
StdoutTruncated bool `json:"stdout_truncated,omitempty"`
StderrTruncated bool `json:"stderr_truncated,omitempty"`
}
Receipt is the private local audit record for one terminal hook attempt. Command output stays in bounded 0600 diagnostic files and is never copied into the receipt or normal WB output.
type ReceiptRef ¶ added in v0.173.0
ReceiptRef is the part of a receipt the freshness read keeps: its id, the SHA the executor ran for, its status and when it finished. Nothing else of a receipt, and no path, is carried.
type Record ¶ added in v0.173.0
type Record struct {
Pending bool
Last *ReceiptRef
Success *ReceiptRef
}
Record is what the receipts and the queue say of one executor on one checkout: whether a run is queued or running, the latest receipt, and the latest successful receipt. Last and Success are nil when there is none.
type Report ¶
type RepositoryMatch ¶
type ResumeReport ¶ added in v0.128.0
type Status ¶ added in v0.128.0
type Status struct {
StateDir string `json:"state_dir"`
ReceiptPath string `json:"receipt_path"`
Worker string `json:"worker"`
WorkerHealth *WorkerHealth `json:"worker_health,omitempty"`
UnseenFailures int `json:"unseen_failures"`
Quarantined int `json:"quarantined"`
Pending []Queued `json:"pending"`
Running []Queued `json:"running"`
Receipts []Receipt `json:"receipts"`
Findings []string `json:"findings,omitempty"`
}