vcstime

Documentation

Overview

Package vcstime provides a file system wrapper that gives embedded files a meaningful modification time.

embed.FS stores and serves no ModTime: files report a zero fs.FileInfo.ModTime, which disables HTTP caching semantics when served with net/http: no Last-Modified header is sent and If-Modified-Since requests are never answered with a 304. vcstime derives a modification time from the vcs.time build setting recorded by the go command (see "go version -m" or debug.BuildInfo), enabling [http.FS] to provide working cache headers for clean builds.

FS wraps an fs.FS (typically an embed.FS) and reports that time as the modification time of every file that does not have a real timestamp of its own. Usage:

//go:embed internal/whatever/*.*
var content embed.FS

mux.Handle("/", http.FileServer(http.FS(vcstime.FS(content))))

vcs.time is the commit time of the revision that was built, not the wall-clock build time: the two coincide for clean CI builds, but a tree with local modifications yields an older commit time. Binaries built without VCS stamping (for example with -buildvcs=false) have no vcs.time, and FS then behaves exactly like the file system it wraps.

Index

• func FS(fsys fs.FS) fs.FS
• func ModTime() time.Time
• func New(fsys fs.FS, mod time.Time) fs.FS

Functions

func FS

func FS(fsys fs.FS) fs.FS

FS returns an fs.FS that serves files from fsys, reporting ModTime as the modification time of any file that has no real timestamp of its own.

It is intended for wrapping an embed.FS, whose files always report a zero ModTime. Files that already have a real timestamp (for example in an [fstest.MapFS] or os-backed file system) are passed through unchanged, so it is always safe to wrap.

If the binary carries no vcs.time stamp, fsys itself is returned unchanged.

func ModTime

func ModTime() time.Time

ModTime returns the modification time reported for timestamp-less files by file systems created with FS: the vcs.time commit time of the running binary's source revision, or the zero time if the binary carries no VCS build stamp.

func New

func New(fsys fs.FS, mod time.Time) fs.FS

New is like FS, but with an explicit modification time to report for files that have none of their own. If mod is the zero time, fsys is returned unchanged.

This exists mostly for tests; prefer FS in production code.