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 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.

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