filecache

Documentation

Overview

Package filecache provides a file based cache for Hugo.

Index

• Constants
• Variables
• type Cache
  • func NewCache(fs afero.Fs, maxAge time.Duration, pruneAllRootDir string) *Cache
  • func (c *Cache) AsHTTPCache() httpcache.Cache
  • func (c *Cache) Get(id string) (ItemInfo, io.ReadCloser, error)
  • func (c *Cache) GetBytes(id string) (ItemInfo, []byte, error)
  • func (c *Cache) GetOrCreate(id string, create func() (io.ReadCloser, error)) (ItemInfo, io.ReadCloser, error)
  • func (c *Cache) GetOrCreateBytes(id string, create func() ([]byte, error)) (ItemInfo, []byte, error)
  • func (c *Cache) GetString(id string) string
  • func (c *Cache) NamedLock(id string) func()
  • func (c *Cache) Prune(force bool) (int, error)
  • func (c *Cache) ReadOrCreate(id string, read func(info ItemInfo, r io.ReadSeeker) error, ...) (info ItemInfo, err error)
  • func (c *Cache) WriteCloser(id string) (ItemInfo, io.WriteCloser, error)
• type Caches
  • func NewCaches(p *helpers.PathSpec) (Caches, error)
  • func (f Caches) AssetsCache() *Cache
  • func (f Caches) Get(name string) *Cache
  • func (f Caches) GetCSVCache() *Cache
  • func (f Caches) GetJSONCache() *Cache
  • func (f Caches) GetResourceCache() *Cache
  • func (f Caches) ImageCache() *Cache
  • func (f Caches) ModulesCache() *Cache
  • func (c Caches) Prune() (int, error)
• type Configs
  • func DecodeConfig(fs afero.Fs, bcfg config.BaseConfig, m map[string]any) (Configs, error)
  • func (c Configs) CacheDirModules() string
• type FileCacheConfig
• type ItemInfo

Constants

const (
	CacheKeyGetJSON     = "getjson"
	CacheKeyGetCSV      = "getcsv"
	CacheKeyImages      = "images"
	CacheKeyAssets      = "assets"
	CacheKeyModules     = "modules"
	CacheKeyGetResource = "getresource"
)

const (
	FilecacheRootDirname = "filecache"
)

Variables

var ErrFatal = errors.New("fatal filecache error")

ErrFatal can be used to signal an unrecoverable error.

Types

type Cache

type Cache struct {
	Fs afero.Fs
	// contains filtered or unexported fields
}

Cache caches a set of files in a directory. This is usually a file on disk, but since this is backed by an Afero file system, it can be anything.

func NewCache

func NewCache(fs afero.Fs, maxAge time.Duration, pruneAllRootDir string) *Cache

NewCache creates a new file cache with the given filesystem and max age.

func (*Cache) AsHTTPCache

func (c *Cache) AsHTTPCache() httpcache.Cache

AsHTTPCache returns an httpcache.Cache implementation for this file cache. Note that none of the methods are protected by named locks, so you need to make sure to do that in your own code.

func (*Cache) Get

func (c *Cache) Get(id string) (ItemInfo, io.ReadCloser, error)

Get gets the file with the given id from the cache, nil if none found.

func (*Cache) GetBytes

func (c *Cache) GetBytes(id string) (ItemInfo, []byte, error)

GetBytes gets the file content with the given id from the cache, nil if none found.

func (*Cache) GetOrCreate

func (c *Cache) GetOrCreate(id string, create func() (io.ReadCloser, error)) (ItemInfo, io.ReadCloser, error)

GetOrCreate tries to get the file with the given id from cache. If not found or expired, create will be invoked and the result cached. This method is protected by a named lock using the given id as identifier.

func (*Cache) GetOrCreateBytes

func (c *Cache) GetOrCreateBytes(id string, create func() ([]byte, error)) (ItemInfo, []byte, error)

GetOrCreateBytes is the same as GetOrCreate, but produces a byte slice.

func (*Cache) GetString

func (c *Cache) GetString(id string) string

For testing

func (*Cache) NamedLock

func (c *Cache) NamedLock(id string) func()

NamedLock locks the given id. The lock is released when the returned function is called.

func (*Cache) Prune

func (c *Cache) Prune(force bool) (int, error)

Prune removes expired and unused items from this cache. If force is set, everything will be removed not considering expiry time.

func (*Cache) ReadOrCreate

func (c *Cache) ReadOrCreate(id string,
	read func(info ItemInfo, r io.ReadSeeker) error,
	create func(info ItemInfo, w io.WriteCloser) error,
) (info ItemInfo, err error)

ReadOrCreate tries to lookup the file in cache. If found, it is passed to read and then closed. If not found a new file is created and passed to create, which should close it when done.

func (*Cache) WriteCloser

func (c *Cache) WriteCloser(id string) (ItemInfo, io.WriteCloser, error)

WriteCloser returns a transactional writer into the cache. It's important that it's closed when done.

type Caches

type Caches map[string]*Cache

Caches is a named set of caches.

func NewCaches

func NewCaches(p *helpers.PathSpec) (Caches, error)

NewCaches creates a new set of file caches from the given configuration.

func (Caches) AssetsCache

func (f Caches) AssetsCache() *Cache

AssetsCache gets the file cache for assets (processed resources, SCSS etc.).

func (Caches) Get

func (f Caches) Get(name string) *Cache

Get gets a named cache, nil if none found.

func (Caches) GetCSVCache

func (f Caches) GetCSVCache() *Cache

GetCSVCache gets the file cache for getCSV.

func (Caches) GetJSONCache

func (f Caches) GetJSONCache() *Cache

GetJSONCache gets the file cache for getJSON.

func (Caches) GetResourceCache

func (f Caches) GetResourceCache() *Cache

GetResourceCache gets the file cache for remote resources.

func (Caches) ImageCache

func (f Caches) ImageCache() *Cache

ImageCache gets the file cache for processed images.

func (Caches) ModulesCache

func (f Caches) ModulesCache() *Cache

ModulesCache gets the file cache for Hugo Modules.

func (Caches) Prune

func (c Caches) Prune() (int, error)

Prune removes expired and unused items from this cache. The last one requires a full build so the cache usage can be tracked. Note that we operate directly on the filesystem here, so this is not thread safe.

type Configs

type Configs map[string]FileCacheConfig

func DecodeConfig

func DecodeConfig(fs afero.Fs, bcfg config.BaseConfig, m map[string]any) (Configs, error)

func (Configs) CacheDirModules

func (c Configs) CacheDirModules() string

For internal use.

type FileCacheConfig

type FileCacheConfig struct {
	// Max age of cache entries in this cache. Any items older than this will
	// be removed and not returned from the cache.
	// A negative value means forever, 0 means cache is disabled.
	// Hugo is lenient with what types it accepts here, but we recommend using
	// a duration string, a sequence of  decimal numbers, each with optional fraction and a unit suffix,
	// such as "300ms", "1.5h" or "2h45m".
	// Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
	MaxAge time.Duration

	// The directory where files are stored.
	Dir         string
	DirCompiled string `json:"-"`

	// Will resources/_gen will get its own composite filesystem that
	// also checks any theme.
	IsResourceDir bool `json:"-"`
}

type ItemInfo

type ItemInfo struct {
	// This is the file's name relative to the cache's filesystem.
	Name string
}

ItemInfo contains info about a cached file.