hashets

Documentation

Overview

Package hashets provides hash-based cache busting for fs.FS.

Index

• func DefaultNamingFunc(name, hash string) string
• func HashFile(name string, in io.Reader, o Options) (string, error)
• func IgnorePrefix(prefixes ...string) func(string) bool
• func WrapFS(filesys fs.FS, o Options) (*FSWrapper, Map, error)
• type FSWrapper
  • func (fsw *FSWrapper) Open(name string) (fs.File, error)
  • func (fsw *FSWrapper) ReadFile(name string) ([]byte, error)
• type Map
  • func Hash(inFS fs.FS, o Options) (Map, error)
  • func HashToDir(inFS fs.FS, outPath string, o Options) (Map, error)
  • func HashToTempDir(inFS fs.FS, o Options) (_ fs.FS, _ Map, cleanup func() error, _ error)
  • func (m Map) Get(name string) string
• type Options

Functions

func DefaultNamingFunc

func DefaultNamingFunc(name, hash string) string

DefaultNamingFunc is the default naming function used by Options.

For a file "foo.txt" with the hash "1234", it would generate "foo_1234.txt".

func HashFile

func HashFile(name string, in io.Reader, o Options) (string, error)

HashFile takes the given io.Reader, calculates the hash of its contents and returns the hashed file name, as returned by [Options.NamingFunc], using name as the original file name.

func IgnorePrefix

func IgnorePrefix(prefixes ...string) func(string) bool

IgnorePrefix returns a func to be used with [Options.Ignore] that ignores all files that starts with one of the passed prefixes.

func WrapFS

func WrapFS(filesys fs.FS, o Options) (*FSWrapper, Map, error)

WrapFS generates file names containing hashes from the given fs.FS using Hash(filesys, o).

It then returns a FSWrapper that, for each hashed file name, returns the original file. Those mappings are stored in the returned Map.

Files that are ignored, are left unhashed and can be accessed by their original file names.

Types

type FSWrapper

type FSWrapper struct {
	// contains filtered or unexported fields
}

FSWrapper wraps an fs.FS that maps hashed file names to the original file names of the wrapped fs.FS, so that a request for "foo_1234.txt" returns the contents of "foo.txt".

func (*FSWrapper) Open

func (fsw *FSWrapper) Open(name string) (fs.File, error)

Open returns the file represented by the passed hashed name.

If there is no file mapped to the passed name, it looks for directly for a file with the given name.

func (*FSWrapper) ReadFile

func (fsw *FSWrapper) ReadFile(name string) ([]byte, error)

type Map

type Map map[string]string

Map represents a map of file paths to file paths with hashed names.

For example for a file ./foo.txt with the hash 1234. Map["foo.txt"] would return "foo_1234.txt", which is the name of the hashed file.

func Hash

func Hash(inFS fs.FS, o Options) (Map, error)

Hash takes the given fs.FS, hashes all its files using the options provided, and returns a Map that maps the original file path to the same path, but with the file name replaced with the hashed file name, as returned by [Options.NamingFunc].

func HashToDir

func HashToDir(inFS fs.FS, outPath string, o Options) (Map, error)

HashToDir takes the given fs.FS, hashes all its files using the options provided and writes the hashed files to the given directory.

The returned Map provides mappings from the original file path to the same path, but with the file name replaced with the hashed file name, as returned by [Options.NamingFunc].

It is explicitly allowed for the output directory to match the input fs.FS. That means HashToDir(os.DirFS("/some/path"), "/some/path", o) is valid and will work as expected.

func HashToTempDir

func HashToTempDir(inFS fs.FS, o Options) (_ fs.FS, _ Map, cleanup func() error, _ error)

HashToTempDir takes the given fs.FS, hashes all its files using the options provided and returns a new fs.FS that stores the hashed files in a temp directory on the local filesystem.

If HashToTempDir returns without an error, the temporary directory has been created, and it is the responsibility of the caller to call the returned cleanup function to remove the temporary directory after it is no longer needed, most commonly after the program exits.

If HashToTempDir has created the temporary directory, but returns an error, the temporary directory will have been removed by HashToTempDir itself, and the caller need not call the cleanup function. However, the cleanup will never be nil, so it is safe to call it even if an error was returned.

The returned Map provides mappings from the original file path to the same path, but with the file name replaced with the hashed file name, as returned by [Options.NamingFunc].

func (Map) Get

func (m Map) Get(name string) string

Get returns the hashed file path for the given file path to the unhashed equivalent.

If m is nil, the original file path is returned. This is useful if the unhashed files are replaced with hashed files in production, but are left unhashed in development.

See the readme of this repository for an example of such a case.

type Options

type Options struct {
	// HashFunc is the hash function to use.
	//
	// Defaults to [sha256.New].
	Hash hash.Hash

	// NamingFunc is the function used to generate the file name for the hashed
	// file.
	//
	// For each generated file, NamingFunc is called with the original file
	// name (not path) and the textual hash of the file, as returned by
	// [Options.HashToText].
	// It is expected to return a new file name containing the hash.
	//
	// Defaults to DefaultNamingFunc.
	NamingFunc func(name, hash string) string

	// HashToText is the function to convert the hash to a string.
	//
	// Defaults to [hex.EncodeToString].
	HashToText func([]byte) string

	// Ignore is called for each file and, if it returns true, the file is
	// ignored, i.e. not hashed.
	//
	// Use the IgnorePrefix helper to ignore files with a certain prefix.
	//
	// Defaults to ignoring no files.
	Ignore func(path string) bool
}

Options provides configuration options for the Hash* functions.