Documentation
¶
Overview ¶
Package cache is the lifecycle facade for the Terraform registry cache. 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 StartForExecution ¶
func StartForExecution(ctx context.Context, atmosConfig *schema.AtmosConfiguration) (*Setup, func(), error)
StartForExecution starts and verifies a registry cache for one complete Terraform execution. The returned cleanup is non-nil, intended to be deferred once, and uses a fresh context so cancellation of the execution cannot prevent a graceful proxy shutdown (and its final savings report).
Callers that fan one execution out to multiple Terraform subprocesses should share the returned Setup and invoke cleanup once after every subprocess exits.
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