Documentation
¶
Overview ¶
Package compserve serves static files with content negotiation for precompressed variants, and provides live compression for dynamic responses.
An Encoding describes a content coding's wire token and where its precompressed variants live.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultEncodings = []Encoding{Zstd, Gzip}
DefaultEncodings is the set of encodings used when Options does not specify any: zstd, then gzip for compatibility with file systems built before zstd-only asset generation. Ties prefer the earlier encoding.
var Gzip = Encoding{
Token: "gzip",
Ext: ".gz",
Decompress: decompressGzip,
}
Gzip serves gzip-precompressed variants ("*.gz"). It exists for transitional compatibility with file systems built before zstd-only asset generation, such as web-client-prebuilt modules published before cmd/build-webclient stopped writing gzip; file systems built since contain no .gz variants and never select it.
var Zstd = Encoding{
Token: "zstd",
Ext: ".zst",
Decompress: decompressZstd,
Compress: compressZstdLive,
}
Zstd serves zstd-precompressed variants ("*.zst", as generated by util/precompress). Encoding.Decompress lets ServeFile transcode the variant for clients that do not accept zstd.
Functions ¶
func CompressWriter ¶
func CompressWriter(w http.ResponseWriter, r *http.Request, encodings ...Encoding) *compressWriter
CompressWriter wraps w so that its response body is transparently compressed, incrementally as the handler writes it, with the first encoding from encodings (default: DefaultEncodings) that offers live compression and that r accepts.
The caller must call Close exactly once after the wrapped handler returns, to finish any compressed stream:
cw := compserve.CompressWriter(w, r) defer cw.Close() handler.ServeHTTP(cw, r)
func ServeFile ¶
ServeFile serves the file at path from fsys to w, negotiating a precompressed variant when the client accepts one and the variant exists. Clients that do not accept any offered encoding are served the raw file; if the raw file is absent (e.g. a file system shipping only precompressed variants), a variant with a Decompress hook is served decompressed instead.
ServeFile sets Vary: Accept-Encoding on every response and serves the content via http.ServeContent with the file's modification time (for embedded file systems, wrap fsys in tailscale.com/tsweb/vcstime.FS to supply one). Callers may set additional headers (e.g. Cache-Control) before calling. If ServeFile returns an error it has not written a response body, so callers may adjust headers and retry with a different path. If no representation of the file exists, the returned error wraps fs.ErrNotExist.
Types ¶
type Encoding ¶
type Encoding struct {
// Token is the Content-Encoding token for this coding, e.g. "zstd".
// Comparison against Accept-Encoding is case-insensitive.
Token string
// Ext is the file name extension (including the leading dot) of
// precompressed variants as produced by util/precompress, e.g. ".zst".
Ext string
// Decompress, if non-nil, wraps f and yields its decompressed content,
// taking ownership of f: the returned ReadCloser's Close closes f, and
// if Decompress returns an error it must have closed f already.
//
// When Decompress is set, a precompressed variant can also be served to
// clients that do not accept Token by decompressing it on the fly, so a
// file system shipping only precompressed variants can still serve
// every client. If nil, the variant is only served passthrough to
// clients that accept Token.
Decompress func(f fs.File) (io.ReadCloser, error)
// Compress, if non-nil, wraps w in a streaming compressor used by
// [CompressWriter] for live (non-precompressed) response compression:
// everything written to the returned WriteCloser is compressed and
// forwarded to w, and its Close finishes the stream and releases any
// pooled resources. Implementations should use a fast compression
// mode: live compression runs per request and must not add meaningful
// latency. If nil, the encoding is not offered for live compression.
Compress func(w io.Writer) (io.WriteCloser, error)
}
Encoding describes a single content coding (e.g. zstd) that this package can negotiate and serve.
Source Files