vroomy

package module
v0.17.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 17, 2024 License: MIT Imports: 18 Imported by: 27

README

Vroomy

All Contributors

billboard Vroomy is a plugin-based server. Vroomy can be used for anything, from a static file server to a full-blown back-end service!

Installation

Installing by compilation is very straight forward. The following dependencies are required:

  • Go
  • GCC
Fresh Install

If you need to install vroomy use this method! (This installs vroomy, vpm, and all of their dependencies)

curl -s https://raw.githubusercontent.com/vroomy/vroomy/main/bin/init | bash -s
Self Upgrade

If you already have vroomy installed, it can upgrade itself! (NOTE: this will attempt to self-sign vroomy on osx and support setcap for selinux. For more info, check the directions during install process)

vroomy upgrade && vpm upgrade

Usage

Test vroomy (run without http listen)
# Set custom config location (remember to revert if desired)
vroomy test
Start (with default config)
# With default config (./config.toml)
vroomy
Start with custom config
# Set custom config location (remember to revert if desired)
export VROOMY_CONFIG="custom.toml"
vroomy
Update plugins
vpm update
Update plugins with custom config
vpm update -config custom.toml
Update plugins with branch/channel
vpm update -b staging
Update filtered plugins
vpm update plugin1 plugin2
Update specific plugin at specific version
vpm update plugin1 -b v0.1.0

Example configuration

port = 8080
tlsPort = 10443 
tlsDir = "./tls"

[[route]]
httpPath = "/"
target = "./public_html/index.html"

[[route]]
httpPath = "/js/*"
target = "./public_html/js"

[[route]]
httpPath = "/css/*"
target = "./public_html/css"

Note: Please see config.example.toml for a more in depth example

Performance
# nginx
$ wrk -c60 -d20s https://josh.usehatchapp.com
Running 20s test @ https://josh.usehatchapp.com
  2 threads and 60 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency    17.66ms    1.59ms  30.31ms   88.20%
    Req/Sec     1.68k   102.72     1.91k    85.43%
  66500 requests in 20.01s, 7.44GB read
Requests/sec:   3323.69
Transfer/sec:    380.91MB

# vroomy
$ wrk -c60 -d20s https://josh.usehatchapp.com
Running 20s test @ https://josh.usehatchapp.com
  2 threads and 60 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency    14.28ms    9.45ms  98.77ms   73.79%
    Req/Sec     2.17k   304.46     3.03k    76.52%
  86013 requests in 20.01s, 9.62GB read
Requests/sec:   4297.88
Transfer/sec:    492.22MB

Flags

[-dataDir -d]

:: Initializes backends in provided directory. Overrides value set in config and default values. Ignored when testing in favor of dir "testData".
Use vroomy -d <dir>

Contributors ✨

Thanks goes to these wonderful people (emoji key):


Josh
💻 📖
Derek Halman
💻
Matt Stay
🎨

This project follows the all-contributors specification. Contributions of any kind welcome!

Documentation

Index

Constants

View Source 
const (
	// ErrProtectedFlag is returned when a protected flag is used
	ErrProtectedFlag = errors.Error("cannot use protected flag")
	// ErrInvalidHostPolicy is returned when the HostPolicy does not match the intended signature
	ErrInvalidHostPolicy = errors.Error("invalid HostPolicy handler within the autocert plugin")
)
View Source 
const (
	// ErrInvalidTLSDirectory is returned when a tls directory is unset when the tls port has been set
	ErrInvalidTLSDirectory = errors.Error("invalid tls directory, cannot be empty when tls port has been set")
	// ErrInvalidPreInitFunc is returned when an unsupported pre initialization function is encountered
	ErrInvalidPreInitFunc = errors.Error("unsupported header for Init func encountered")
	// ErrInvalidLoadFunc is returned when an unsupported initialization function is encountered
	ErrInvalidLoadFunc = errors.Error("unsupported header for Load func encountered")
	// ErrNotAddressable is returned when a plugin is not addressable
	ErrNotAddressable = errors.Error("provided backend must be addressable")
	// ErrInvalidDir is returned when a directory is empty
	ErrInvalidDir = errors.Error("invalid directory, cannot be empty")
	// ErrPluginKeyExists is returned when a plugin cannot be added because it already exists
	ErrPluginKeyExists = errors.Error("plugin cannot be added, key already exists")
	// ErrPluginNotLoaded is returned when a plugin namespace is provided that has not been loaded
	ErrPluginNotLoaded = errors.Error("plugin with that key has not been loaded")
	// ErrExpectedEndParen is returned when an ending parenthesis is missing
	ErrExpectedEndParen = errors.Error("expected ending parenthesis")
	// ErrInvalidPluginHandler is returned when a plugin handler is not valid
	ErrInvalidPluginHandler = errors.Error("plugin handler not valid")
)
View Source 
const (
	// ErrGroupNotFound is returned when a group cannot be found by name
	ErrGroupNotFound = errors.Error("group not found")
)

Variables

This section is empty.

Functions

func Register added in v0.11.0 

func Register(key string, pi Plugin) error

Register will register a plugin with a given key

Types

type BasePlugin added in v0.11.0 

type BasePlugin struct{}

func (*BasePlugin) Backend added in v0.11.0 

func (b *BasePlugin) Backend() interface{}

func (*BasePlugin) Close added in v0.11.0 

func (b *BasePlugin) Close() error

func (*BasePlugin) Init added in v0.11.0 

func (b *BasePlugin) Init(env Environment) error

func (*BasePlugin) Load added in v0.11.0 

func (b *BasePlugin) Load(env Environment) error

type Config added in v0.15.0 

type Config struct {
	Name string `toml:"name"`

	Dir  string `toml:"dir"`
	Port uint16 `toml:"port"`
	// TLSPort to listen on. To use TLS one of the two must be set:
	//	- TLSDir
	//	- AutoCertHosts/AutoCertDir
	TLSPort uint16 `toml:"tlsPort"`

	TLSDir string `toml:"tlsDir"`

	IncludeConfig

	Flags map[string]string `toml:"-"`

	// Plugin keys as they are referenced by the plugins store
	PluginKeys []string

	ErrorLogger func(error)
}

Config is the configuration needed to initialize a new instance of Service

func NewConfig added in v0.15.0 

func NewConfig(loc string) (cfg *Config, err error)

NewConfig will return a new configuration

func (*Config) GetRouteGroup added in v0.15.0 

func (c *Config) GetRouteGroup(name string) (g *RouteGroup, err error)

GetGroup will return group with name

type Environment added in v0.13.0 

type Environment map[string]string

func (Environment) Get added in v0.13.0 

func (e Environment) Get(key string) (out string)

func (Environment) Must added in v0.13.0 

func (e Environment) Must(key string) (out string, err error)

type Flag added in v0.15.0 

type Flag struct {
	Name         string `toml:"name"`
	DefaultValue string `toml:"defaultValue"`
	Usage        string `toml:"usage"`
}

Flag represents a flag entry

type IncludeConfig added in v0.15.0 

type IncludeConfig struct {
	AutoCertHosts []string `toml:"autoCertHosts"`
	AutoCertDir   string   `toml:"autoCertDir"`

	// Application environment
	Environment map[string]string `toml:"env"`

	// Allow included files to add includes
	Include []string `toml:"include"`

	// Specify which plugins are in scope
	Plugins []string `toml:"plugins"`

	// Flags are the dynamic flags specified in config
	FlagEntries []*Flag `toml:"flag"`

	// Groups are the route groups
	Groups []*RouteGroup `toml:"group"`
	// Routes are the routes to listen for and serve
	Routes []*Route `toml:"route"`
}

IncludeConfig will include routes

type Plugin added in v0.11.0 

type Plugin interface {
	Init(env Environment) error
	Load(env Environment) error
	Backend() interface{}
	Close() error
}

type Plugins added in v0.11.0 

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

Plugins manages loaded plugins

func (*Plugins) Close added in v0.11.0 

func (p *Plugins) Close() (err error)

Close will close plugins

func (*Plugins) Get added in v0.11.0 

func (p *Plugins) Get(key string) (pi Plugin, err error)

Get will get a plugin by it's key

func (*Plugins) Loaded added in v0.11.0 

func (p *Plugins) Loaded() (pm map[string]Plugin)

func (*Plugins) Register added in v0.11.0 

func (p *Plugins) Register(key string, pi Plugin) (err error)

New will load a new plugin by key

func (*Plugins) Test added in v0.11.0 

func (p *Plugins) Test() (err error)

Test will test all of the plugins

func (*Plugins) TestAsync added in v0.11.0 

func (p *Plugins) TestAsync(q *queue.Queue) (err error)

TestAsync will test all of the plugins asynchronously

type Response added in v0.15.0 

type Response struct {
	StatusCode  int
	ContentType string
	Value       interface{}

	// Optional fields used by a minority of responses
	Adopted  bool
	Callback string
}

Response determines how the server will respond

func NewAdopedtResponse added in v0.15.0 

func NewAdopedtResponse() *Response

NewAdopedtResponse will return a new adopted Response

func NewResponse added in v0.15.0 

func NewResponse(statusCode int, contentType string, value interface{}) *Response

NewResponse will return a new Response

type Route added in v0.15.0 

type Route struct {
	// Target plug-in handler
	HTTPHandlers []httpserve.Handler `toml:"-"`

	// Route name/description
	Name string `toml:"name"`
	// Route group
	Group string `toml:"group"`
	// HTTP method
	Method string `toml:"method"`
	// HTTP path
	HTTPPath string `toml:"httpPath"`
	// Directory or file to serve
	Target string `toml:"target"`
	// Plugin handlers
	Handlers []string `toml:"handlers"`
}

Route represents a listening route

func (*Route) String added in v0.15.0 

func (r *Route) String() string

String will return a formatted version of the route

type RouteGroup added in v0.15.0 

type RouteGroup struct {
	Name string `toml:"name"`
	// Route group
	Group string `toml:"group"`
	// HTTP method
	Method string `toml:"method"`
	// HTTP path
	HTTPPath string `toml:"httpPath"`
	// Plugin handlers
	Handlers []string `toml:"handlers"`

	HTTPHandlers []httpserve.Handler `toml:"-"`

	G httpserve.Group `toml:"-"`
}

RouteGroup represents a route group

type Vroomy added in v0.9.0 

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

Vroomy manages the web service

func New 

func New(configLocation string) (sp *Vroomy, err error)

New will return a new instance of service

func NewWithConfig added in v0.9.0 

func NewWithConfig(cfg *Config) (vp *Vroomy, err error)

NewWithConfig will return a new instance of service with a provided config

func (*Vroomy) Close added in v0.9.0 

func (v *Vroomy) Close() (err error)

Close will close the selected service

func (*Vroomy) Listen added in v0.9.0 

func (v *Vroomy) Listen(ctx context.Context) (err error)

Listen will listen to the configured port

func (*Vroomy) Port added in v0.9.0 

func (v *Vroomy) Port() uint16

Port will return the current HTTP port

func (*Vroomy) TLSPort added in v0.9.0 

func (v *Vroomy) TLSPort() uint16

TLSPort will return the current HTTPS port

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.