vroomy

package module
v0.18.8 Latest Latest
Warning

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

 Go to latest Published: Feb 25, 2025 License: MIT Imports: 21 Imported by: 30

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

To add vroomy to your Go project, just call: go get github.com/vroomy/vroomy

Getting started

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

[env]
fqdn = "https://myserver.org"

[[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

Using the library

Getting started with vroomy is quite easy! Call vroomy.New with the location of your configuration file. For a more in-depth explanation, please check out our hello-world repository.

package main

import (
	"context"
	"log"

	"github.com/vroomy/vroomy"

	_ "github.com/vroomy/hello-world/plugins/companies"
)

func main() {
	var (
		svc *vroomy.Vroomy
		err error
	)

	if svc, err = vroomy.New("./config.toml"); err != nil {
		log.Fatal(err)
	}

	if err = svc.ListenUntilSignal(context.Background()); err != nil {
		log.Fatal(err)
	}
}

Usage

Environment.Get
func ExampleEnvironment_Get() {
	val := exampleEnvironment.Get("foo")
	fmt.Println("Value of foo is", val)
}
Environment.GetInt
func ExampleEnvironment_GetInt() {
	var (
		val int
		err error
	)

	if val, err = exampleEnvironment.GetInt("foo"); err != nil {
		// Handle error here
		return
	}

	fmt.Println("Value of foo is", val)
}
Environment.GetInt64
func ExampleEnvironment_GetInt64() {
	var (
		val int64
		err error
	)

	if val, err = exampleEnvironment.GetInt64("foo"); err != nil {
		// Handle error here
		return
	}

	fmt.Println("Value of foo is", val)
}
Environment.GetFloat64
func ExampleEnvironment_GetFloat64() {
	var (
		val float64
		err error
	)

	if val, err = exampleEnvironment.GetFloat64("foo"); err != nil {
		// Handle error here
		return
	}

	fmt.Println("Value of foo is", val)
}
Environment.GetTime
func ExampleEnvironment_GetTime() {
	var (
		val time.Time
		err error
	)

	if val, err = exampleEnvironment.GetTime("foo", "2006-01-02"); err != nil {
		// Handle error here
		return
	}

	fmt.Println("Value of foo is", val)
}
Environment.GetTimeInLocation
func ExampleEnvironment_GetTimeInLocation() {
	var (
		val time.Time
		err error
	)

	if val, err = exampleEnvironment.GetTimeInLocation("foo", "2006-01-02", time.Local); err != nil {
		// Handle error here
		return
	}

	fmt.Println("Value of foo is", val)
}
Environment.Must
func ExampleEnvironment_Must() {
	var (
		val string
		err error
	)

	if val, err = exampleEnvironment.Must("foo"); err != nil {
		// Handle error here
		return
	}

	fmt.Println("Value of foo is", val)
}
Environment.MustInt
func ExampleEnvironment_MustInt() {
	var (
		val int
		err error
	)

	if val, err = exampleEnvironment.MustInt("foo"); err != nil {
		// Handle error here
		return
	}

	fmt.Println("Value of foo is", val)
}
Environment.MustInt64
func ExampleEnvironment_MustInt64() {
	var (
		val int64
		err error
	)

	if val, err = exampleEnvironment.MustInt64("foo"); err != nil {
		// Handle error here
		return
	}

	fmt.Println("Value of foo is", val)
}
Environment.MustFloat64
func ExampleEnvironment_MustFloat64() {
	var (
		val float64
		err error
	)

	if val, err = exampleEnvironment.MustFloat64("foo"); err != nil {
		// Handle error here
		return
	}

	fmt.Println("Value of foo is", val)
}
Environment.MustTime
func ExampleEnvironment_MustTime() {
	var (
		val time.Time
		err error
	)

	if val, err = exampleEnvironment.MustTime("foo", "2006-01-02"); err != nil {
		// Handle error here
		return
	}

	fmt.Println("Value of foo is", val)
}
Environment.MustTimeInLocation
func ExampleEnvironment_MustTimeInLocation() {
	var (
		val time.Time
		err error
	)

	if val, err = exampleEnvironment.MustTimeInLocation("foo", "2006-01-02", time.Local); err != nil {
		// Handle error here
		return
	}

	fmt.Println("Value of foo is", val)
}

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

Examples

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"`
	AllowNonTLS bool   `toml:"allowNonTLS"`

	IncludeConfig

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

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

	ErrorLogger func(error) `toml:"-"`
}

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)
Example 
val := exampleEnvironment.Get("foo")
fmt.Println("Value of foo is", val)

func (Environment) GetFloat64 added in v0.18.0 

func (e Environment) GetFloat64(key string) (out float64, err error)
Example 
var (
	val float64
	err error
)

if val, err = exampleEnvironment.GetFloat64("foo"); err != nil {
	// Handle error here
	return
}

fmt.Println("Value of foo is", val)

func (Environment) GetInt added in v0.18.0 

func (e Environment) GetInt(key string) (out int, err error)
Example 
var (
	val int
	err error
)

if val, err = exampleEnvironment.GetInt("foo"); err != nil {
	// Handle error here
	return
}

fmt.Println("Value of foo is", val)

func (Environment) GetInt64 added in v0.18.0 

func (e Environment) GetInt64(key string) (out int64, err error)
Example 
var (
	val int64
	err error
)

if val, err = exampleEnvironment.GetInt64("foo"); err != nil {
	// Handle error here
	return
}

fmt.Println("Value of foo is", val)

func (Environment) GetTime added in v0.18.0 

func (e Environment) GetTime(key, layout string) (out time.Time, err error)
Example 
var (
	val time.Time
	err error
)

if val, err = exampleEnvironment.GetTime("foo", "2006-01-02"); err != nil {
	// Handle error here
	return
}

fmt.Println("Value of foo is", val)

func (Environment) GetTimeInLocation added in v0.18.0 

func (e Environment) GetTimeInLocation(key, layout string, loc *time.Location) (out time.Time, err error)
Example 
var (
	val time.Time
	err error
)

if val, err = exampleEnvironment.GetTimeInLocation("foo", "2006-01-02", time.Local); err != nil {
	// Handle error here
	return
}

fmt.Println("Value of foo is", val)

func (Environment) Must added in v0.13.0 

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

if val, err = exampleEnvironment.Must("foo"); err != nil {
	// Handle error here
	return
}

fmt.Println("Value of foo is", val)

func (Environment) MustFloat64 added in v0.18.0 

func (e Environment) MustFloat64(key string) (out float64, err error)
Example 
var (
	val float64
	err error
)

if val, err = exampleEnvironment.MustFloat64("foo"); err != nil {
	// Handle error here
	return
}

fmt.Println("Value of foo is", val)

func (Environment) MustInt added in v0.18.0 

func (e Environment) MustInt(key string) (out int, err error)
Example 
var (
	val int
	err error
)

if val, err = exampleEnvironment.MustInt("foo"); err != nil {
	// Handle error here
	return
}

fmt.Println("Value of foo is", val)

func (Environment) MustInt64 added in v0.18.0 

func (e Environment) MustInt64(key string) (out int64, err error)
Example 
var (
	val int64
	err error
)

if val, err = exampleEnvironment.MustInt64("foo"); err != nil {
	// Handle error here
	return
}

fmt.Println("Value of foo is", val)

func (Environment) MustTime added in v0.18.0 

func (e Environment) MustTime(key, layout string) (out time.Time, err error)
Example 
var (
	val time.Time
	err error
)

if val, err = exampleEnvironment.MustTime("foo", "2006-01-02"); err != nil {
	// Handle error here
	return
}

fmt.Println("Value of foo is", val)

func (Environment) MustTimeInLocation added in v0.18.0 

func (e Environment) MustTimeInLocation(key, layout string, loc *time.Location) (out time.Time, err error)
Example 
var (
	val time.Time
	err error
)

if val, err = exampleEnvironment.MustTimeInLocation("foo", "2006-01-02", time.Local); err != nil {
	// Handle error here
	return
}

fmt.Println("Value of foo is", val)

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) ListenUntilSignal added in v0.17.5 

func (v *Vroomy) ListenUntilSignal(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.