Documentation
¶
Overview ¶
Package pkg provides the core domain types and logic for the go-version-watcher service:
- Version — parsed Go release version with (major, minor, patch) comparison
- GoDevClient — queries https://go.dev/dl/?mode=json for the max stable version
- Cursor — single LastSeenVersion dedup state persisted to disk
- TaskPublisher — sends the CreateTaskCommand for the Go update runbook
- Watcher — the Poll loop tying it all together
See [[Go Version Watcher]] for the design, [[Watcher Writing Guide]] for the producer-side contract and [[Agent Task File Contract]] for the frontmatter/body shape this watcher emits.
Index ¶
- Constants
- func BuildCreateCommand(newVersion string, previousVersion string, releaseKind string, cfg TaskConfig) task.CreateCommand
- func DeriveTaskID(version string) uuid.UUID
- func SaveCursor(ctx context.Context, path string, c *Cursor) error
- type Cursor
- type GoDevClient
- type Metrics
- type TaskConfig
- type TaskPublisher
- type Version
- type Watcher
Constants ¶
const DefaultCursorPath = "/data/cursor.json"
DefaultCursorPath is the default cursor persistence location. k8s mounts /data as a PVC; main.go binds CURSOR_PATH=DefaultCursorPath.
const DefaultGoDevURL = "https://go.dev/dl/?mode=json"
DefaultGoDevURL is the go.dev release-list endpoint returning the JSON array of releases (including unstable ones — the client filters to stable).
Variables ¶
This section is empty.
Functions ¶
func BuildCreateCommand ¶
func BuildCreateCommand( newVersion string, previousVersion string, releaseKind string, cfg TaskConfig, ) task.CreateCommand
BuildCreateCommand assembles the CreateTaskCommand for a new Go version. newVersion and previousVersion are canonical go-version strings (e.g. "go1.27.0"); releaseKind is "minor" or "patch".
func DeriveTaskID ¶
DeriveTaskID returns a UUID5 derived deterministically from the Go version string (e.g. "go1.27.0").
Uniqueness set rationale (per [[Watcher Writing Guide]] § Deterministic task_identifier):
- Same version → same task_id → controller dedup makes re-emit a no-op.
- A newer version → new name → new task_id → fresh task.
Types ¶
type Cursor ¶
type Cursor struct {
LastSeenVersion string `json:"last_seen_version"`
}
Cursor is the single-value dedup state: the last Go version the watcher has seen and acted on. Empty LastSeenVersion means cold start (no prior run).
Concurrency: not safe for concurrent use. The Watcher loads at poll start and saves at poll end (single goroutine).
type GoDevClient ¶
type GoDevClient interface {
// LatestStable returns the maximum stable Go version reported by go.dev.
// It returns an error when the request fails, the response is malformed, or
// no stable, parseable version is present.
LatestStable(ctx context.Context) (Version, error)
}
GoDevClient is the upstream-source surface for the go-version watcher.
func NewGoDevClient ¶
func NewGoDevClient(httpClient *http.Client, url string) GoDevClient
NewGoDevClient returns the production GoDevClient backed by the given HTTP client and URL (typically DefaultGoDevURL).
type Metrics ¶
type Metrics interface {
// IncPollCycle — result: "success" | "go_dev_error"
IncPollCycle(result string)
// IncPublished — status: "create" | "error"
IncPublished(status string)
// IncFilterSkipped — reason: "version_unchanged"
IncFilterSkipped(reason string)
}
Metrics is the observable counter surface required by [[Watcher Writing Guide]] § Required observability.
func NewMetrics ¶
func NewMetrics(registerer prometheus.Registerer) Metrics
NewMetrics returns the Prometheus-backed Metrics implementation registered against the supplied Registerer. Pass nil for the default registry. Pre-initialises every label combination so Prometheus exposes a zero series before the first event fires.
type TaskConfig ¶
type TaskConfig struct {
Stage string // "dev" or "prod" — frontmatter `stage`
}
TaskConfig groups per-task envelope settings (stage routing).
type TaskPublisher ¶
type TaskPublisher interface {
PublishCreate(ctx context.Context, cmd task.CreateCommand) bool
}
TaskPublisher sends a pre-built CreateTaskCommand via the supplied CreateCommandSender. Returns true on successful send, false on error.
func NewTaskPublisher ¶
func NewTaskPublisher(sender task.CreateCommandSender, metrics Metrics) TaskPublisher
NewTaskPublisher returns a TaskPublisher that wraps the given sender + metrics.
type Version ¶
Version is a parsed Go release version. Patch defaults to 0 when the source string omits it (e.g. "go1.27" → patch 0). Raw preserves the original string.
func ParseVersion ¶
ParseVersion parses a Go release version string of the form go<major>.<minor>[.<patch>]. A missing patch component defaults to 0. Returns an error if the string does not match the expected shape.
func (Version) Compare ¶
Compare orders two versions by (major, minor, patch). It returns a negative number when v < other, zero when equal, and a positive number when v > other.
type Watcher ¶
type Watcher interface {
// Poll runs one scan cycle. Safe to call repeatedly on an interval.
Poll(ctx context.Context) error
}
Watcher polls go.dev for the max stable Go version and publishes a CreateTaskCommand when it advances beyond the cursor.
func NewWatcher ¶
func NewWatcher( client GoDevClient, publisher TaskPublisher, metrics Metrics, cursorPath string, cfg TaskConfig, ) Watcher
NewWatcher wires the watcher's collaborators.
Source Files
Directories