vault

README

Vault

Vault is a simple tool to embed resource and asset files into a go binary. It generates go source files containing encoded and compressed resource files. The generated source code provides an api to retrieve the embedded resources without any additional dependencies and therefore the vault package is only needed to generate those source files.

Requirements

go 1.9.7+

Installation

Install tool with go get:

go get -u github.com/go-sharp/vault/vault-cli

Usage

Assuming a project folder like this:

webapp
    |- dist
    |   |- js
    |   |   |- app.js
    |   |   '- moment.js
    |   |- css
    |   |   '- app.css
    |   |- index.html
    |   '- bg.jpeg
    |- handlers.go
    |- models.go
    '- main.go

Generating embedded resources

#vault-cli [options] source destination
 vault-cli ./dist ./res

This command will generate source files containing index.html and bg.jpeg as resources. Now the project folder looks like this:

webapp
    |- dist
    |   |- js
    |   |   |- app.js
    |   |   '- moment.js
    |   |- css
    |   |   '- app.css
    |   |- index.html
    |   '- bg.jpeg
    |- res
    |   |- debug_dist_vault.go
    |   |- release_dist_vault.go
    |   '- shared_dist_vault.go
    |- handlers.go
    |- models.go
    '- main.go

To include files in subdirectories use the -s flag.

Include / Exclude files

Use the -i and -e flags to include or exclude files. Both flags expecting a regular expression as input (see regexp) and can be specified multiple times.

Include only specified files

vault-cli -s -i "[.]js$" -i "[.]html$" ./dist ./res

This will include only app.js, moment.js and index.html.

Exclude files

vault-cli -s -e "app.js$" - ./dist ./res

This will include all files except app.js. It is also possible to use both flags, so one could define a more general include pattern and then exclude some specific files. For example:

vault-cli -s -i "[.]js$" -e "test[.]js$" - ./dist ./res

This will include all javascript files but exclude test files.

Compression

Per default all included files will be compressed. If required, compression can be disabled with the -no-comp flag.

Go generate

The most straight forward way to invoke the vault-cli is to use the go:generate directive in the main.go file.

//go:generate vault-cli -s ./dist ./res

Then invoke the go generate command to generate the resource files.

Use the resource file

Create and use the asset loader in your program as shown below:

package main

import (
    "fmt"
    "log"

    "github.com/example/webapp/res"
)

func main() {
    // Create a loader (default: New{source folder name}Loader() -> can be changed with ResourceNameOption)
    loader := res.NewDistLoader()
    f, err := loader.Open("/bg.jpg")
    if err != nil {
        log.Fatalln(err)
    }

    // Check for error omitted, but you definitely should check for errors.
    defer f.Close()

    // Read content
    data, err := ioutil.ReadAll(f)
    if err != nil {
       log.Fatalln(err)
    }


    // Write content to a file
    if err := ioutil.WriteFile("bg.jpg", data, 0755); err != nil {
        log.Fatalln(err)
    }

    f2, err := loader.Open("/js/app.js")
    if err != nil {
        log.Fatalln(err)
    }

    // Check for error omitted, but you definitely should check for errors.
    defer f2.Close()

     // Read content
    data, err = ioutil.ReadAll(f2)
    if err != nil {
       log.Fatalln(err)
    }

    // Write to console
    fmt.Println(data)
}

AssetLoader uses the relative path to the file within the source directory to lookup the file in the vault. The loader uses slashes / as path separator on all platforms (macOS, Linux and Windows).

The asset loader implements only one method:

// AssetLoader implements a function to load an asset from the vault
type AssetLoader interface {
	// Open loads a file from the vault.
	Open(name string) (File, error)
}

Load returns a file instance with the following interface (see http.File) or an error:

// File is the interface definition in the http package.
type File interface {
        io.Closer
        io.Reader
        io.Seeker
        Readdir(count int) ([]os.FileInfo, error)
        Stat() (os.FileInfo, error)
}

Use Loader in the http.FileServer handler

The asset loader implements the http.FileSystem interface and can be used with the http.FileServer handler. Just pass the loader to the FileServer function as follows:

http.Handle("/", http.FileServer(res.NewDistLoader()))

Development Mode

Run or build a program with go run -tags debug main.go to enable the development mode. In development mode the loader bypasses the embedded files and reads directly from the source directory. Therefore it is important to run the program in the same folder as the vault-cli tool was invoked. Otherwise invoke vault-cli with the flag -rp and specify the relative path to the source directory from the directory where the program will be executed. For example (folder structure as above):

# WorkingDir WebApp/dist
$~/workspace/src/webapp/dist> vault-cli -s -rp "./dist" ./ ../res
# WorkingDir  WebApp
$~/workspace/src/webapp> go run -tags debug main.go

A simple webapp example

See Example folder

License

This software is licensed under the MIT License.

Documentation

Overview

Package vault is a simple tool to embed resource and asset files into a go binary. It generates go source files containing encoded and compressed resource files. The generated source code provides an api to retrieve the embedded resources without any additional dependencies and therefore the vault package is only needed to generate those source files.

Documentation see https://github.com/go-sharp/vault

Index

• Constants
• type Generator
  • func NewGenerator(src, dest string, options ...GeneratorOption) Generator
  • func (g *Generator) Run()
• type GeneratorConfig
• type GeneratorOption
  • func CompressOption(compress bool) GeneratorOption
  • func ExcludeFilesOption(name ...string) GeneratorOption
  • func IncludeFilesOption(name ...string) GeneratorOption
  • func PackageNameOption(name string) GeneratorOption
  • func RelativePathOption(p string) GeneratorOption
  • func ResourceNameOption(name string) GeneratorOption
  • func WithSubdirsOption(withSubdirs bool) GeneratorOption

Constants

const (
	// Version is the current vault version.
	Version = "2.0.0"
)

Types

type Generator

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

Generator creates a vault with embedded files.

func NewGenerator

func NewGenerator(src, dest string, options ...GeneratorOption) Generator

NewGenerator creates a new generator instance with the given options.

func (*Generator) Run

func (g *Generator) Run()

Run starts the vault generation, calls log.Fatal if an error occurs.

type GeneratorConfig

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

GeneratorConfig configures the vault generator.

type GeneratorOption

type GeneratorOption func(g *GeneratorConfig)

GeneratorOption configures the vault generator.

func CompressOption

func CompressOption(compress bool) GeneratorOption

CompressOption if set to true all files will be compressed, otherwise no compression is used.

func ExcludeFilesOption

func ExcludeFilesOption(name ...string) GeneratorOption

ExcludeFilesOption sets the files to exclude in the generation process. Only relative paths will be checked, so pattern must not include the fullpath. Pattern matching follows the rules of regexp.Match (see https://golang.org/pkg/regexp/#Match).

func IncludeFilesOption

func IncludeFilesOption(name ...string) GeneratorOption

IncludeFilesOption sets the files to include in the generation process. Only specified files and files not matching any exclusion pattern will be included in the generation process. Only relative paths will be checked, so pattern must not include the fullpath. Pattern matching follows the rules of regexp.Match (see https://golang.org/pkg/regexp/#Match).

func PackageNameOption

func PackageNameOption(name string) GeneratorOption

PackageNameOption sets the package name of the generated vault files. If not set, the generator tries to deduce the correct package name.

func RelativePathOption

func RelativePathOption(p string) GeneratorOption

RelativePathOption sets the relative path for the debug asset loader. If not specified the generator uses the relative path from the directory where the generator was invoked.

func ResourceNameOption

func ResourceNameOption(name string) GeneratorOption

ResourceNameOption sets the name of the generated resources.

func WithSubdirsOption

func WithSubdirsOption(withSubdirs bool) GeneratorOption

WithSubdirsOption if set to true, the generator will walk down the folder tree with the source directory as root.