Documentation
¶
Overview ¶
Package cache is the lifecycle facade for the Terraform registry cache. It is the only package internal/exec touches: it resolves the cache root, builds the storage backend, starts the caching proxy with the provider and module registry mirrors, contributes the network_mirror/host directives to the generated Terraform CLI config, and prints a per-run savings report on shutdown.
Import as tfcache to avoid colliding with pkg/cache.
Index ¶
- Constants
- func Delete(root, key string) error
- func InstallTrust(certPath string) error
- func ProxyCertPath(atmosConfig *schema.AtmosConfiguration) (string, error)
- func RemoveTrust(certPath string) error
- func ResolveRoot(atmosConfig *schema.AtmosConfiguration) (string, error)
- func TrustInstructions() (required bool, note string)
- type Entry
- type Setup
- type Summary
Constants ¶
const ( // GroupProvider/GroupModule classify a cache object by its top-level directory. GroupProvider = "provider" GroupModule = "module" )
Variables ¶
This section is empty.
Functions ¶
func Delete ¶
Delete removes a single cached object (and its sidecar), cleaning up emptied parent directories up to the root. Idempotent.
func InstallTrust ¶
InstallTrust adds the proxy certificate to the OS trust store so terraform/tofu trust the cache proxy. Used by `atmos terraform cache trust`. It is a no-op (nil) on platforms where Atmos handles trust via SSL_CERT_FILE.
func ProxyCertPath ¶
func ProxyCertPath(atmosConfig *schema.AtmosConfiguration) (string, error)
ProxyCertPath returns the on-disk path of the cache proxy certificate for the given configuration, whether or not it has been generated yet. Used by the `cache trust` command to locate the certificate.
func RemoveTrust ¶
RemoveTrust removes the proxy certificate from the OS trust store. Used by `atmos terraform cache untrust`.
func ResolveRoot ¶
func ResolveRoot(atmosConfig *schema.AtmosConfiguration) (string, error)
ResolveRoot resolves the cache root for the given configuration (the configured location, else the XDG cache directory). It does not create anything.
func TrustInstructions ¶
TrustInstructions returns whether OS trust-store installation is required on this platform, plus a human note. On Linux/BSD Atmos trusts the cert via SSL_CERT_FILE automatically, so no trust-store change is needed.
Types ¶
type Entry ¶
type Entry struct {
// Key is the canonical cache key (the object's path under the root, forward-slashed).
Key string `json:"key"`
// Group classifies the object: provider, module, or other.
Group string `json:"group"`
// Kind is the artifact kind from the sidecar (metadata or artifact), if known.
Kind string `json:"kind,omitempty"`
// Size is the object size in bytes.
Size int64 `json:"size"`
// ModTime is the filesystem modification time.
ModTime time.Time `json:"mod_time"`
// FetchedAt is when the object was cached (from the sidecar), if recorded.
FetchedAt time.Time `json:"fetched_at,omitempty"`
}
Entry describes a single cached object on disk.
func List ¶
List walks the cache root and returns every cached artifact: provider and module objects only. It excludes metadata sidecars, lock files, in-flight temp files, and proxy infrastructure that is co-located in the cache root but is not a cached artifact — notably the self-signed TLS certificate under tls/ (see tls.go) and the vestigial layout directories. Because Summarize/Delete/Prune all build on List, the TLS material is never counted in stats and never pruned or deleted.
type Setup ¶
type Setup struct {
// contains filtered or unexported fields
}
Setup is a started registry cache. Close shuts it down and reports savings.
func Start ¶
Start resolves the cache root, builds the backend and mirrors, and starts the proxy. It returns (nil, nil) when caching is disabled so callers can no-op.
func (*Setup) CertPath ¶
CertPath returns the on-disk path of the proxy's TLS certificate (PEM). Callers use it to wire trust into the terraform/tofu subprocess. Empty on a nil Setup.
func (*Setup) Close ¶
Close shuts the proxy down and prints the savings report when bytes were served from cache. Safe to call on a nil Setup.
func (*Setup) Contribute ¶
Contribute returns the Terraform CLI-config directives the cache injects into the generated RC: a provider_installation network_mirror (covering all provider hosts) plus a direct{} fallback, and a host override for each public registry that routes modules.v1 through the proxy while preserving the upstream providers.v1.
A host block REPLACES the host's whole service-discovery document, so it must also declare providers.v1 — otherwise a direct provider lookup (e.g. a mirror miss) reports "host does not offer a provider registry".
func (*Setup) TrustEnv ¶
TrustEnv returns environment variables that make the terraform/tofu subprocess trust the proxy's certificate (SSL_CERT_FILE bundle). Honored on Linux/BSD; on macOS/Windows trust requires installing the cert in the OS trust store. Returns nil on a nil Setup.
func (*Setup) VerifyTrust ¶
VerifyTrust checks, before terraform/tofu runs, whether the OS trust store trusts the proxy's certificate, so the user gets an actionable message instead of a raw x509 error from the subprocess. It only probes on platforms where trust is installed in the OS store (macOS/Windows); on Linux/BSD trust comes from the SSL_CERT_FILE bundle Atmos sets on the subprocess, so it is a no-op.
type Summary ¶
type Summary struct {
Root string `json:"root"`
ObjectCount int `json:"object_count"`
TotalSize int64 `json:"total_size"`
Providers int `json:"providers"`
Modules int `json:"modules"`
Largest *Entry `json:"largest,omitempty"`
Oldest *Entry `json:"oldest,omitempty"`
}
Summary aggregates filesystem facts about the cache. It deliberately contains NO hit rate: there is no persistent hit/miss store (the filesystem is the index). Hit statistics are per-run only, surfaced by the savings report.
Source Files