vfshash

README

vfshash

A package to make a http.FileSystem content-addressable for use with shurcooL/vfsgen. It adds a truncated cryptographic digest to file names.

This package is useful for giving web assets content-addressable URLs which can safely be used with long cache times (a year or more).

Usage

import "go.tmthrgd.dev/vfshash"

Follow the usage instructions for shurcooL/vfsgen and wrap the fs with NewFileSystem to generate a content-addressable file system.

var fs http.FileSystem = http.Dir("/path/to/assets")

fs = vfshash.NewFileSystem(fs)

err := vfsgen.Generate(fs, vfsgen.Options{})
if err != nil {
	log.Fatalln(err)
}

Embedded in the file system is a manifest that maps the original names for files to their content-addressable equivalents. This can be accessed with the AssetNames API.

names := vfshash.NewAssetNames(assets)

// returns /example-deadbeef.css
names.Lookup("/example.css")

// returns /does.not.exist.txt as is
names.Lookup("/does.not.exist.txt")

// opens /example-deadbeef.js
names.Open("/example.js")

AssetNames implements http.FileSystem so it can be passed to http.FileServer to serve assets with their original names.

If the http.FileSystem passed to NewAssetNames doesn't contain the manifest, Lookup will return the name as is. This makes development easier as a regular http.Dir can be passed in without problem.

License

BSD 3-Clause License

Documentation

Overview

Package vfshash offers a http.FileSystem that wraps an underlying http.FileSystem to make resources content-addressable by adding a truncated cryptographic digest to the file names.

Index

• type AssetNames
  • func NewAssetNames(fs http.FileSystem) *AssetNames
  • func (n *AssetNames) IsContentAddressable() bool
  • func (n *AssetNames) Lookup(name string) string
  • func (n *AssetNames) Open(name string) (http.File, error)
• type FileSystem
  • func NewFileSystem(fs http.FileSystem) *FileSystem
  • func (fs *FileSystem) Open(name string) (http.File, error)

Examples

• AssetNames
• FileSystem

Types

type AssetNames

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

AssetNames maps asset paths to their content-addressable equivalents.

Example

package main

import (
	"net/http"

	"go.tmthrgd.dev/vfshash"
)

var assets struct{ http.FileSystem }

func main() {
	names := vfshash.NewAssetNames(assets.FileSystem)

	// returns /example-deadbeef.css
	names.Lookup("/example.css")

	// returns /does.not.exist.txt as is
	names.Lookup("/does.not.exist.txt")

	// opens /example-deadbeef.js
	names.Open("/example.js")
}

func NewAssetNames

func NewAssetNames(fs http.FileSystem) *AssetNames

NewAssetNames returns an AssetNames using the given http.FileSystem.

func (*AssetNames) IsContentAddressable

func (n *AssetNames) IsContentAddressable() bool

IsContentAddressable reports whether the underlying http.FileSystem is using content-addressable names. This is the case when it was wrapped with FileSystem.

func (*AssetNames) Lookup

func (n *AssetNames) Lookup(name string) string

Lookup returns the content-addressable name of an asset that matches the given name.

If the name isn't known, or the http.FileSystem wasn't wrapped with FileSystem, the name is returned as is.

func (*AssetNames) Open

func (n *AssetNames) Open(name string) (http.File, error)

Open converts name into the content-addressable name of an asset and then calls Open on the underlying http.FileSystem.

type FileSystem

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

FileSystem wraps a http.FileSystem to make assets content-addressable by adding a truncated cryptographic digest to the file names.

Example

package main

import (
	"log"
	"net/http"

	"github.com/shurcooL/vfsgen"
	"go.tmthrgd.dev/vfshash"
)

func main() {
	fs := vfshash.NewFileSystem(http.Dir("assets"))

	err := vfsgen.Generate(fs, vfsgen.Options{})
	if err != nil {
		log.Fatal(err)
	}
}

func NewFileSystem

func NewFileSystem(fs http.FileSystem) *FileSystem

NewFileSystem returns an FileSystem using the given http.FileSystem.

func (*FileSystem) Open

func (fs *FileSystem) Open(name string) (http.File, error)

Open calls Open on the underlying http.FileSystem while making every file content-addressable.