bundle

README

bundle

is a workaround until 35950 is resolved. bundle embedds files, using a few wanted optimizations, and there is no other which supports this out of the box:

• give direct access to (cached) uncompressed, brotli and gzip streams
• optionally cache variants in memory (e.g. for web servers)
• uses one of the most efficient codecs (brotli), which compresses 14-21% better than gzip at comparable decompression speed
• uses base85 instead base64 to reduce embedding and parsing overhead from 33% to 25%. It is unclear if using base-122 would be a good choice. The resulting go-file has only around 21% overhead, if compressing again with bzip.
• optimized http handler which uses etags and no-cache headers and optimized in-memory caches of compression variants
• customizable resources at runtime
• only regenerates source code, if files have changed. Perfect for go generate.

alternatives

there are so many...

• fileembed - https://godoc.org/perkeep.org/pkg/fileembed
• packr - https://godoc.org/github.com/gobuffalo/packr
• stuffbin - https://godoc.org/github.com/knadh/stuffbin
• vfsgen - https://github.com/shurcooL/vfsgen
• go.rice - https://github.com/GeertJohan/go.rice
• statik - https://github.com/rakyll/statik
• esc - https://github.com/mjibson/esc
• go-embed - https://github.com/pyros2097/go-embed
• go-resources - https://github.com/omeid/go-resources
• statics - https://github.com/go-playground/statics
• templify - https://github.com/wlbr/templify
• gnoso/go-bindata - https://github.com/gnoso/go-bindata
• shuLhan/go-bindata - https://github.com/shuLhan/go-bindata
• fileb0x - https://github.com/UnnoTed/fileb0x
• gobundle - https://github.com/alecthomas/gobundle
• parcello - https://github.com/phogolabs/parcello

Documentation

Index

• func Embed(opts Options) error
• func Handle(prefix string, resources ...*Resource) func(http.ResponseWriter, *http.Request)
• type Bundle
  • func Make(resources ...*Resource) *Bundle
  • func (b *Bundle) Find(name string) *Resource
  • func (b *Bundle) Handler(prefix string) func(http.ResponseWriter, *http.Request)
  • func (b *Bundle) Put(resource *Resource) *Bundle
  • func (b *Bundle) Remove(name string) *Bundle
• type Filesystem
  • func NewFilesystem(resources ...*Resource) *Filesystem
  • func (b Filesystem) Open(name string) (http.File, error)
• type Options
• type Resource
  • func NewResource(name string, size int64, mode os.FileMode, lastMod time.Time, sha256 string, ...) *Resource
  • func NewResourceFromBytes(name string, buf []byte) *Resource
  • func (r *Resource) AsBytes() []byte
  • func (r *Resource) AsString() string
  • func (r *Resource) IsDir() bool
  • func (r *Resource) ModTime() time.Time
  • func (r *Resource) Mode() os.FileMode
  • func (r *Resource) Name() string
  • func (r *Resource) Read() io.Reader
  • func (r *Resource) ReadBrotli() io.Reader
  • func (r *Resource) ReadGzip() io.Reader
  • func (r *Resource) Size() int64
  • func (r *Resource) Sys() interface{}
  • func (r *Resource) Version() string
  • func (r *Resource) Write(dst io.Writer) (int, error)
  • func (r *Resource) WriteBrotli(dst io.Writer) (int, error)
  • func (r *Resource) WriteGzip(dst io.Writer) (int, error)

Functions

func Embed

func Embed(opts Options) error

Embed includes the given files or folders and creates a new go src file. It expects a working dir somewhere within a go module and picks the root itself.

func Handle

func Handle(prefix string, resources ...*Resource) func(http.ResponseWriter, *http.Request)

Handle is currently a trivial implementation for delivering resources, however it will use the resources to support gzip and brotli compression and more importantly etags. It simply matches the url path against the name of a resource.

Types

type Bundle

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

Bundle contains a bunch of resources.

func Make

func Make(resources ...*Resource) *Bundle

Make creates a new bundle from the given resources. We use Make here to avoid stuttering like bundle.NewBundle(). Takes ownership of resources.

func (*Bundle) Find

func (b *Bundle) Find(name string) *Resource

Find returns the resource or nil

func (*Bundle) Handler

func (b *Bundle) Handler(prefix string) func(http.ResponseWriter, *http.Request)

Handler returns a new http handler, providing resources for the given prefix

func (*Bundle) Put

func (b *Bundle) Put(resource *Resource) *Bundle

Put returns a new bundle instance with the given resource replacing any other resource with the same name. The current bundle is unchanged.

func (*Bundle) Remove

func (b *Bundle) Remove(name string) *Bundle

Remove tries to delete the resource from the bundle and returns a new potentionally modified instance.

type Filesystem

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

Filesystem is an implementation on top of the bundle resources. However better use the handler, which returns handles compression better.

func NewFilesystem

func NewFilesystem(resources ...*Resource) *Filesystem

func (Filesystem) Open

func (b Filesystem) Open(name string) (http.File, error)

type Options

type Options struct {
	TargetDir            string
	PackageName          string
	Include              []string
	StripPrefixes        []string // removes this prefix from all Include paths, if they begin with it
	Prefix               string   // attach this prefix to all included files
	IgnoreRegex          string   // e.g. '.*\.map|^\..*' will ignore all map and hidden files from inclusion
	DisableCacheUnpacked bool
	DisableCacheGzip     bool
	DisableCacheBrotli   bool
}

type Resource

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

A Resource relates a bunch of bytes with a name and optionally cached variants of the same data.

func NewResource

func NewResource(name string, size int64, mode os.FileMode, lastMod time.Time, sha256 string, cacheUnpacked, cacheBrotli, cacheGzip bool, data string) *Resource

func NewResourceFromBytes

func NewResourceFromBytes(name string, buf []byte) *Resource

NewResourceFromBytes creates a new resource for the given buffer

func (*Resource) AsBytes

func (r *Resource) AsBytes() []byte

AsBytes returns the internal byte sequence as a defensive copy

func (*Resource) AsString

func (r *Resource) AsString() string

AsString returns the internal byte sequence as string

func (*Resource) IsDir

func (r *Resource) IsDir() bool

func (*Resource) ModTime

func (r *Resource) ModTime() time.Time

func (*Resource) Mode

func (r *Resource) Mode() os.FileMode

func (*Resource) Name

func (r *Resource) Name() string

Name returns the resources unique name

func (*Resource) Read

func (r *Resource) Read() io.Reader

Read opens the resource to read the unpacked data.

func (*Resource) ReadBrotli

func (r *Resource) ReadBrotli() io.Reader

ReadGzip opens the resource to read the data as gzip stream

func (*Resource) ReadGzip

func (r *Resource) ReadGzip() io.Reader

ReadGzip opens the resource to read the data as gzip stream

func (*Resource) Size

func (r *Resource) Size() int64

Size returns the uncompressed length in bytes

func (*Resource) Sys

func (r *Resource) Sys() interface{}

func (*Resource) Version

func (r *Resource) Version() string

Version returns the hex variant of the sha256 hash

func (*Resource) Write

func (r *Resource) Write(dst io.Writer) (int, error)

Write transfers the uncompressed data into the writer

func (*Resource) WriteBrotli

func (r *Resource) WriteBrotli(dst io.Writer) (int, error)

WriteBrotli writes the datastream as a brotli buffer into the writer

func (*Resource) WriteGzip

func (r *Resource) WriteGzip(dst io.Writer) (int, error)

WriteGzip writes the datastream as a gzip buffer into the writer