Documentation
¶
Overview ¶
Package kassets provides functions and helpers to register static assets typically built into your binary with go_embed_data() in an http Mux object.
The assets are minimally pre-processed so, for example:
- the MIME type is precomputed - once - and always reused.
- the path of the file is mangled so that modern conventions are followed (file extension from .html file is stripped, for example, and an index.html is used when a directory is requested)
- files are pre-compressed, so if gzip encoding by the browser is supported, those files are not re-compressed on the fly every time. The pre-compression is dropped if there is not enough saving.
- ...
The assets preprocessing is configurable by chaining functions together in different ways.
Index ¶
- func AcceptsEncoding(accepts, encoding string) bool
- func EmbedFSToMap(embedded embed.FS) (map[string][]byte, error)
- func EmbedFSToMapOrPanic(embedded embed.FS) map[string][]byte
- func RegisterAssets(stats *AssetStats, assets map[string][]byte, base string, mapper AssetMapper)
- type AssetMapper
- func BasicMapper(mapper AssetMapper) AssetMapper
- func DefaultMapper(mux *http.ServeMux) AssetMapper
- func MapWrapper(mapping map[string]Wrapper, child AssetMapper) AssetMapper
- func MuxMapper(mux *http.ServeMux) AssetMapper
- func PrefixMapper(prefix string, mapper AssetMapper) AssetMapper
- func StripExtensionMapper(mapper AssetMapper) AssetMapper
- func WrapMapper(wrap Wrapper, mapper AssetMapper) AssetMapper
- type AssetResource
- type AssetStats
- func (as *AssetStats) AddCompressed(size int)
- func (as *AssetStats) AddJsCompressed(size int)
- func (as *AssetStats) AddJsTotal(size int)
- func (as *AssetStats) AddMapped(res AssetResource)
- func (as *AssetStats) AddSkipped(res AssetResource)
- func (as *AssetStats) AddTotal(size int)
- func (as AssetStats) Log(p logger.Printer)
- type Wrapper
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AcceptsEncoding ¶
AcceptsEncoding returns true if the "Accept-Encoding" header supplied in the accepts parameter supports the encoding specified in the encoding parameter.
The answer is believed to be RFC compliant, but the header parsing in this function is not complete: it does the bare minimum necessary to determine if the encoding is accepted, or not.
If accepted, true is returned. false otherwise.
func EmbedFSToMap ¶
EmbedFSToMap converts an embed.FS to a map of file paths to their contents.
Use this function to convert a go embed variable to a map of strings to bytes, very similar to how go_embed_data used to work in Bazel.
Example usage:
In your BUILD.bazel file:
go_library(
name = "assets", srcs = ["assets.go"], embedsrcs = glob(["*.html"]), importpath = "your/import/path/assets",
)
In your assets.go file:
package assets
import (
"embed" "github.com/ccontavalli/enkit/lib/khttp/kassets"
)
//go:embed *.html var embedded embed.FS
func Data() map[string][]byte {
return kassets.EmbedFSToMapOrPanic(embedded)
}
func EmbedFSToMapOrPanic ¶
EmbedFSToMapOrPanic is like EmbedFSToMap but panics on error.
func RegisterAssets ¶
func RegisterAssets(stats *AssetStats, assets map[string][]byte, base string, mapper AssetMapper)
RegisterAssets goes oever each asset supplied, creates an http handler, and registers it with AssetMapper.
assets is a dict generated via a go_embed_data target, basically a map between a path and byte array with the content of the file. base is a string determining the top level directory containing the assets, can be empty. mapper is a function in charge of mapping the asset and detected handler with the mux.
Example: if you set base to be "/data/", assets like "foo/bar/baz/data/test.html" will be mapped as "test.html", all that's after "/data/". Files not containing "/data/" will be skipped.
Types ¶
type AssetMapper ¶
type AssetMapper func(original, name string, handler khttp.FuncHandler) []string
AssetMapper is a function capable of taking a file name as found in the assets (original), the desired name or path to be used on the web server (name) together with a handler to be associated with it.
It returns the actual set of paths programmed in the web server.
AssetMappers are designed to be chained together: imagine that a file, index.html is to be served in the web server.
The first AssetMapper in the chain may strip the extension (turning /path/index.html into /path/index), the second AssettMapper may decide to use index.html as a directory index, mapping /path/ to the file, together with /path/index (serving the same file) and /path (serving a redirect to /path/). This second AssetMapper would invoke child AssetMappers multiple times with the original name (/path/index.html) and each one of the names listed.
It would then return all the names generated by concatenating the names returned by each child AssetMapper, which may in turn mangle, change, drop or add additional names.
func BasicMapper ¶
func BasicMapper(mapper AssetMapper) AssetMapper
BasicMapper returns an AssetMapper to apply simple normalizations to paths.
Specifically: - leaves favicon.ico alone. - removes the .html extension. - maps index.html files to /.
func DefaultMapper ¶
func DefaultMapper(mux *http.ServeMux) AssetMapper
DefaultMapper returns a mapper doing the bare minimum necessary.
func MapWrapper ¶
func MapWrapper(mapping map[string]Wrapper, child AssetMapper) AssetMapper
MapWrapper allows to use different wrappers for different URLs.
For example, you can use MapWrapper to wrap "/index.html" with oauth.MakeAuthHandler, while leaving the other pages alone.
The map uses the full "original" name in your assets as the path to match against, not the path mangled by other AssetMapper.
Using an empty string "" as a key in the map configures a default action for URLs that cannot be otherwise found in the map.
If a match in the map results in nil, the URL is not wrapped with any wrapper. If neither a match nor a default match can be found, the URL is EXCLUDED from further processing - no other AssetMapper is applied.
func MuxMapper ¶
func MuxMapper(mux *http.ServeMux) AssetMapper
MuxMapper returns an AssetMapper that simply returns the specified name with an http.ServeMux.
func PrefixMapper ¶
func PrefixMapper(prefix string, mapper AssetMapper) AssetMapper
PrefixMapper returns an AssetMapper that always prepends a prefix.
func StripExtensionMapper ¶
func StripExtensionMapper(mapper AssetMapper) AssetMapper
StripExtensionMapper returns an AssetMapper to strip all extensions.
func WrapMapper ¶
func WrapMapper(wrap Wrapper, mapper AssetMapper) AssetMapper
WrapMapper will wrap the computed handler with a handler of your choice.
For example, you can use WrapMapper to wrap the handler for a path behind oauth.MakeAuthHandler, or oauth.MakeLoginHandler.
The function you provide (Wrapper) will be invoked and expected to return a new handler replacing the originally computed one.
type AssetResource ¶
type AssetResource struct {
Base string
Name string
Mime string
Size int
Compressed int
Paths []string
}
AssetResource represents an asset after beign pre-processed.
type AssetStats ¶
type AssetStats struct {
Skipped []AssetResource
Mapped []AssetResource
Total, Compressed uint64
JsTotal, JsCompressed uint64
}
AssetStats represents asset statistics useful for debugging.
func (*AssetStats) AddCompressed ¶
func (as *AssetStats) AddCompressed(size int)
func (*AssetStats) AddJsCompressed ¶
func (as *AssetStats) AddJsCompressed(size int)
func (*AssetStats) AddJsTotal ¶
func (as *AssetStats) AddJsTotal(size int)
func (*AssetStats) AddMapped ¶
func (as *AssetStats) AddMapped(res AssetResource)
func (*AssetStats) AddSkipped ¶
func (as *AssetStats) AddSkipped(res AssetResource)
func (*AssetStats) AddTotal ¶
func (as *AssetStats) AddTotal(size int)
func (AssetStats) Log ¶
func (as AssetStats) Log(p logger.Printer)
Log will log all statistics collected by an AssetStats object.
type Wrapper ¶
type Wrapper func(khttp.FuncHandler) khttp.FuncHandler
Source Files