lifecyclehooks

package
v0.144.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 18, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

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

View Source
const (
	ConfigVersion        = 1
	EventCheckoutUpdated = "checkout-updated"
)

Variables

This section is empty.

Functions

func RepositoryIdentity

func RepositoryIdentity(checkout string) (string, error)

Types

type Binding

type Binding struct {
	On      []string `yaml:"on"`
	Match   Match    `yaml:"match"`
	Execute []string `yaml:"execute"`
}

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 Config struct {
	Version   int                 `yaml:"version"`
	Executors map[string]Executor `yaml:"executors"`
	Bindings  []Binding           `yaml:"bindings"`
}

func Load

func Load(configPath string) (Config, bool, error)

Load reads only the hooks section from the standard wb.yaml. Other WB sections are deliberately ignored while fields inside hooks are strict.

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

func (dispatcher Dispatcher) Dispatch(_ context.Context, events []Event) (Report, error)

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)

func (Dispatcher) Retry added in v0.128.0

func (dispatcher Dispatcher) Retry(receiptID string) (Report, error)

func (Dispatcher) Status added in v0.128.0

func (dispatcher Dispatcher) Status(limit int) (Status, error)

type Event

type Event struct {
	Name        string `json:"name"`
	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"`
}

type Executor

type Executor struct {
	Run     string   `yaml:"run"`
	Args    []string `yaml:"args"`
	CWD     string   `yaml:"cwd"`
	Mode    string   `yaml:"mode"`
	Timeout string   `yaml:"timeout"`
	Failure string   `yaml:"failure"`
}

type ExecutorCheck added in v0.128.0

type ExecutorCheck struct {
	Name     string `json:"name"`
	Run      string `json:"run"`
	Resolved string `json:"resolved,omitempty"`
	Delivery string `json:"delivery"`
	Status   string `json:"status"`
	Finding  string `json:"finding,omitempty"`
}

type GCOptions added in v0.128.0

type GCOptions struct {
	Apply     bool
	Keep      int
	OlderThan time.Duration
	Now       time.Time
}

type GCReport added in v0.128.0

type GCReport struct {
	Apply              bool     `json:"apply"`
	Receipts           int      `json:"receipts"`
	Candidates         []string `json:"candidates,omitempty"`
	RemovedReceipts    int      `json:"removed_receipts"`
	RemovedDiagnostics int      `json:"removed_diagnostics"`
	Findings           []string `json:"findings,omitempty"`
}

type Invocation

type Invocation struct {
	Executor string
	Run      string
	Args     []string
	Dir      string
	Env      []string
	Stdout   io.Writer
	Stderr   io.Writer
	// contains filtered or unexported fields
}

type Match

type Match struct {
	Repositories RepositoryMatch `yaml:"repositories"`
}

type Planned added in v0.128.0

type Planned struct {
	Executor       string `json:"executor"`
	Event          Event  `json:"event"`
	CoalescedCount int    `json:"coalesced_count"`
}

type Queued added in v0.128.0

type Queued struct {
	Executor       string    `json:"executor"`
	Event          Event     `json:"event"`
	CoalescedCount int       `json:"coalesced_count"`
	QueuedAt       time.Time `json:"queued_at"`
	UpdatedAt      time.Time `json:"updated_at"`
}

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 Report

type Report struct {
	Enqueued  int      `json:"enqueued"`
	Executed  int      `json:"executed"`
	Coalesced int      `json:"coalesced"`
	Warnings  []string `json:"warnings,omitempty"`
}

func Dispatch

func Dispatch(ctx context.Context, events []Event) (Report, error)

type RepositoryMatch

type RepositoryMatch struct {
	Include []string `yaml:"include"`
	Exclude []string `yaml:"exclude"`
}

type ResumeReport added in v0.128.0

type ResumeReport struct {
	Pending       int      `json:"pending"`
	Running       int      `json:"running"`
	WorkerStarted bool     `json:"worker_started"`
	Warnings      []string `json:"warnings,omitempty"`
}

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"`
}

type WorkerHealth added in v0.128.0

type WorkerHealth struct {
	SchemaVersion int       `json:"schema_version"`
	Status        string    `json:"status"`
	StartedAt     time.Time `json:"started_at,omitempty"`
	FinishedAt    time.Time `json:"finished_at,omitempty"`
	Message       string    `json:"message,omitempty"`
}

type WorkerRequest added in v0.128.0

type WorkerRequest struct {
	ConfigPath  string
	StateDir    string
	ReceiptPath string
}

Jump to

Keyboard shortcuts

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