cache

Documentation

Overview

Package cache is a tiny per-profile JSON file store for Jira metadata (labels, epics, projects, …) that's cheap to look up — used by the `jira cache <resource>` commands and (eventually) by Cobra shell completion functions.

The store is intentionally dumb: one JSON file per resource, atomic write, read-time freshness check. No locking — concurrent writers would race, but in practice each profile is driven by one user shell.

Index

• Constants
• func Clear(profile, resource string) (bool, error)
• func ClearProfile(profile string) (int, error)
• func Key(profile, siteURL, configPath string) string
• func Path(profile, resource string) (string, error)
• type Entry
  • func Read(profile, resource string, ttl time.Duration) (entry Entry, ok, stale bool, err error)
  • func ReadCachedOrEmpty(profile, resource string) (Entry, bool, error)
  • func Write(profile, resource string, data json.RawMessage) (Entry, error)

Constants

const DefaultTTL = 1 * time.Hour

DefaultTTL is the freshness window before `Read` reports stale=true. Callers can still use the cached value; this just signals "consider refreshing" to commands and completion functions.

const SchemaVersion = 0

SchemaVersion is the on-disk cache-entry shape version. The current, originally-unversioned shape is version 0, so legacy entries written before this field existed (which decode to Schema=0) stay valid — no upgrade wipes a usable cache. The first change to a cached resource's shape bumps this constant; every entry stamped with the old version then fails the read-time check below and is refetched, so a CLI upgrade can never mis-parse a stale shape. This is what lets the per-resource TTLs run long.

Functions

func Clear

func Clear(profile, resource string) (bool, error)

Clear removes the cache file for (profile, resource). Returns ok=true when a file existed and was removed; ok=false silently when none.

func ClearProfile

func ClearProfile(profile string) (int, error)

ClearProfile wipes every cache file under a profile (the parent directory). Returns the number of files removed.

func Key

func Key(profile, siteURL, configPath string) string

Key returns the stable namespace component for one config/site/profile identity. The human profile name stays visible in command output; this key is only for cache storage so profiles with the same name in different Jira sites or config files do not share metadata.

func Path

func Path(profile, resource string) (string, error)

Path returns the on-disk location for a (profile, resource) pair. The directory is created lazily; callers should treat the returned path purely as input to Read/Write.

Types

type Entry

type Entry struct {
	Profile   string          `json:"profile"`
	Resource  string          `json:"resource"`
	Schema    int             `json:"schema"`
	FetchedAt time.Time       `json:"fetched_at"`
	Data      json.RawMessage `json:"data"`
}

Entry wraps a cached value with its fetch timestamp + source profile. Stored verbatim on disk so consumers can introspect age and provenance.

func Read

func Read(profile, resource string, ttl time.Duration) (entry Entry, ok, stale bool, err error)

Read returns the cached entry. ok=false when no cache file exists. stale=true when the entry is older than ttl (or DefaultTTL when ttl<=0) — the value is still returned so callers can use stale data as a fallback while triggering a refresh.

func ReadCachedOrEmpty

func ReadCachedOrEmpty(profile, resource string) (Entry, bool, error)

ReadCachedOrEmpty returns the cached entry for (profile, resource) regardless of age, or ok=false when no usable entry exists — absent, unreadable, or written by an incompatible schema. It is the NeverBlock read: consumers that must serve cached-or-empty and never trigger a network fetch (shell completion, JQL field reference, board-scope resolution) call this, so cache age is irrelevant to them and a long resource TTL never changes what they see. The read error is still returned, so a caller that distinguishes "absent" from "broken" can; completion-style callers may treat any (!ok || err != nil) as empty.

func Write

func Write(profile, resource string, data json.RawMessage) (Entry, error)

Write atomically stores `data` (already JSON-encoded) under the (profile, resource) key. Uses a temp-file-then-rename to avoid leaving a half-written file when the process is killed mid-write.