update

Documentation

Overview

Package update implements the cubox-cli self-update notification check.

The check is split into two operations:

• Lookup is a synchronous, network-free read of an on-disk cache. It returns whatever the last successful registry fetch wrote, plus a hint about whether the cache should be refreshed.
• RefreshCache performs a single HTTP GET against the npm registry and writes the response (or a negative-cache marker on failure) back to disk. It is meant to be invoked from a goroutine while the main command runs, so its result is observed on the *next* invocation in the common case.

All file and network errors are deliberately swallowed: an update notice is best-effort and must never block or break a normal CLI invocation.

Index

• func DefaultCachePath() string
• type Info
• type Notifier
  • func Default(version string) *Notifier
  • func (n *Notifier) Lookup() State
  • func (n *Notifier) RefreshCache(ctx context.Context)
• type State

Functions

func DefaultCachePath

func DefaultCachePath() string

DefaultCachePath returns the default on-disk cache location. Returns "" when the user home directory cannot be determined.

Types

type Info

type Info struct {
	Current string `json:"current"`
	Latest  string `json:"latest"`
	Message string `json:"message"`
	Command string `json:"command"`
}

Info is the payload included as `_notice.update` in JSON output and printed to stderr in text mode. The Command field is a human/agent display hint and MUST NOT be executed automatically.

type Notifier

type Notifier struct {
	// Version is the current binary version. Empty, "dev", or a git-describe
	// suffix disables the check (see shouldCheck).
	Version string

	// RegistryURL is the npm registry endpoint (`/<package>/latest`).
	RegistryURL string

	// CachePath overrides the default cache file location. When empty
	// DefaultCachePath() is used.
	CachePath string

	// HTTPClient allows tests to inject transports. When nil, a client with
	// HTTPTimeout is constructed lazily.
	HTTPClient *http.Client

	// UserAgent is sent on registry requests.
	UserAgent string

	// CacheTTL is how long a successfully-fetched value remains fresh.
	CacheTTL time.Duration

	// NegativeTTL is how long after a failed fetch we suppress retries to
	// avoid hammering an offline / blocked registry on every invocation.
	NegativeTTL time.Duration

	// HTTPTimeout caps the registry request when HTTPClient is nil.
	HTTPTimeout time.Duration

	// UpdateCommand is the install/refresh hint embedded into Info.
	UpdateCommand string

	// Now is the clock source. nil means time.Now.
	Now func() time.Time

	// Getenv overrides os.Getenv for tests. nil means os.Getenv.
	Getenv func(key string) string

	// Debug, when non-nil, receives diagnostic messages. Use Default's
	// CUBOX_DEBUG-aware implementation in production.
	Debug func(format string, args ...any)
}

Notifier coordinates lookups and background refreshes. A single Notifier per process is expected. Methods are not safe for concurrent use within one instance unless documented otherwise; the typical pattern is:

n := update.Default(Version)
state := n.Lookup()
go n.RefreshCache(ctx) // optional, when state.NeedsRefresh

Lookup and RefreshCache may safely run concurrently across goroutines: the cache file is written via a temp-file + rename, so a concurrent reader observes either the previous or the next complete file, never a partial one.

func Default

func Default(version string) *Notifier

Default returns a Notifier wired up for production use.

func (*Notifier) Lookup

func (n *Notifier) Lookup() State

Lookup returns the current update state read synchronously from cache. It performs no network I/O. A "" or "dev" Version, a git-describe build, CI environments, or an explicit opt-out short-circuit to a zero State so dev / non-interactive contexts never trigger the machinery.

func (*Notifier) RefreshCache

func (n *Notifier) RefreshCache(ctx context.Context)

RefreshCache fetches the latest version and writes the result to disk. On any error a negative-cache entry is written so subsequent Lookups can honor NegativeTTL and avoid retry storms. Honors the supplied context's deadline / cancellation.

type State

type State struct {
	Info         *Info // non-nil when a strictly newer version is known
	NeedsRefresh bool  // true when the cache is stale or empty (and not throttled)
	CacheEmpty   bool  // true when no usable cached version was found
}

State describes the update information available from a synchronous Lookup.