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 CountProfile(profile string) (int, error)
- func Exists(profile, resource string) (bool, error)
- func IssueKeys(profile string) []string
- func Key(profile, siteURL, configPath string) string
- func Path(profile, resource string) (string, error)
- func RecordIssueKeys(profile string, keys []string) error
- type Entry
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 IssueKeysResource = "issuekeys"
IssueKeysResource names the per-profile MRU list of recently used issue keys. Unlike the fetched metadata resources it is never primed from Jira: commands write it as a side effect of touching keys, and shell completion reads it, so freshness windows do not apply — the newest entry is by definition current.
const SchemaVersion = 1
SchemaVersion is the on-disk cache-entry shape version. Any change to a cached resource's shape bumps this constant; every entry stamped with an older 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. Version 1 added status_category to cached statuses (version 0 was the originally-unversioned shape; entries written before the field existed decode to Schema=0 and are refetched).
Variables ¶
This section is empty.
Functions ¶
func Clear ¶
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 ¶
ClearProfile wipes every cache file under a profile (the parent directory). Returns the number of files removed.
func CountProfile ¶ added in v0.10.0
CountProfile reports how many cache files a ClearProfile would remove, without removing anything. The dry-run half of a whole-profile `cache clear`.
func Exists ¶ added in v0.10.0
Exists reports whether a cache file is present for (profile, resource) — what a Clear would remove — without touching it. The dry-run half of `cache clear <resource>`. Like every xos boolean probe it treats a regular file where a directory should be (ENOTDIR mid-path) as absent, so on a hand-corrupted cache tree the preview says "nothing to remove" where the live Clear surfaces the error.
func IssueKeys ¶ added in v0.10.15
IssueKeys returns the profile's recently used issue keys, newest first. Any miss — no cache, unreadable file, wrong shape — returns nil so completion and rendering degrade to nothing rather than erroring.
func Key ¶
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 ¶
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.
func RecordIssueKeys ¶ added in v0.10.15
RecordIssueKeys merges keys into the profile's most-recent-first list: incoming keys (already normalized by the caller's parse) move to or enter the front in the order given, duplicates collapse onto their newest position, and the tail truncates at the cap. Recording is a side effect of real work — callers ignore the error by design, so a broken cache can never fail a command.
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 ¶
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 ¶ added in v0.4.1
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.
Source Files