aero

README

Aero is a high-performance web server with a clean API for web development.

Installation

go get -u github.com/aerogo/aero/...

Usage

Run this in an empty directory:

aero -new

Now you can build your app with go build or use the run development server.

Benchmarks

Features

• Makes it easy to reach top scores in Lighthouse, PageSpeed and Mozilla Observatory
• Optimized for low latency
• Best practices are enabled by default
• Has a strict content security policy
• Calculates E-Tags out of the box
• Saves you a lot of bandwidth using browser cache validation
• Finishes ongoing requests on a server shutdown
• Lets you push resources via HTTP/2
• Supports session data with custom stores
• Allows sending live data to the client via SSE
• Provides http and https listener
• Shows response time and size for your routes
• Can run standalone without nginx babysitting it

Optional

• pack to compile Pixy, Scarlet and JS assets in record time
• run which automatically restarts your server on code/template/style changes
• pixy as a high-performance template engine similar to Jade/Pug
• scarlet as an aggressively compressing stylesheet preprocessor
• nano as a fast, decentralized and git-trackable database
• layout as a layout system
• manifest to load and manipulate web manifests
• markdown as an overly simplified markdown wrapper
• graphql to automatically implement your GraphQL API
• packet as a way to send TCP/UDP messages between nodes
• http as an HTTP client with a simple and clean API
• log for simple & performant logging

Documentation

• API
• Configuration
• Benchmarks

Others

• Slides for OWDDM talk (Osaka, May 2018)
• Discord
• Twitter
• Facebook

Style

Please take a look at the style guidelines if you'd like to make a pull request.

Sponsors

Cedric Fung	Scott Rayapoullé	Eduard Urbach

Want to see your own name here?

Documentation

Index

• func ETag(b []byte) string
• func ETagString(b string) string
• type Application
  • func New() *Application
  • func (app *Application) AddPushCondition(test func(Context) bool)
  • func (app *Application) Any(path string, handler Handler)
  • func (app *Application) BindMiddleware()
  • func (app *Application) Delete(path string, handler Handler)
  • func (app *Application) Get(path string, handler Handler)
  • func (app *Application) ListenAndServe()
  • func (app *Application) Load()
  • func (app *Application) NewContext(req *http.Request, res http.ResponseWriter) *context
  • func (app *Application) OnEnd(callback func())
  • func (app *Application) OnError(callback func(Context, error))
  • func (app *Application) OnPush(callback func(Context))
  • func (app *Application) OnStart(callback func())
  • func (app *Application) Post(path string, handler Handler)
  • func (app *Application) Put(path string, handler Handler)
  • func (app *Application) Rewrite(rewrite func(RewriteContext))
  • func (app *Application) Router() *Router
  • func (app *Application) Run()
  • func (app *Application) ServeHTTP(response http.ResponseWriter, request *http.Request)
  • func (app *Application) Shutdown()
  • func (app *Application) StartTime() time.Time
  • func (app *Application) Test(route string, paths ...string)
  • func (app *Application) TestRoute(route string, uri string)
  • func (app *Application) TestRoutes()
  • func (app *Application) Use(middlewares ...Middleware)
• type ApplicationSecurity
  • func (security *ApplicationSecurity) Load(certificate string, key string)
• type Body
  • func (body Body) Bytes() ([]byte, error)
  • func (body Body) JSON() (interface{}, error)
  • func (body Body) JSONObject() (map[string]interface{}, error)
  • func (body Body) Reader() io.ReadCloser
  • func (body Body) String() (string, error)
• type Configuration
  • func LoadConfig(path string) (*Configuration, error)
  • func (config *Configuration) Reset()
• type Context
• type Event
• type EventStream
  • func NewEventStream() *EventStream
• type Handler
  • func (handler Handler) Simulate(ctx Context) (*httptest.ResponseRecorder, error)
• type Linter
• type Listener
  • func (listener Listener) Accept() (net.Conn, error)
• type Middleware
• type PortConfiguration
• type Request
• type Response
• type RewriteContext
• type Router
  • func (router *Router) Add(method string, path string, handler Handler)
  • func (router *Router) Each(callback func(*tree))
  • func (router *Router) Find(method string, path string) Handler
  • func (router *Router) Lookup(method string, path string, ctx *context)
  • func (router *Router) Print(method string)

Functions

func ETag

func ETag(b []byte) string

ETag produces a hash for the given slice of bytes. It is the same hash that Aero uses for its ETag header.

func ETagString

func ETagString(b string) string

ETagString produces a hash for the given string. It is the same hash that Aero uses for its ETag header.

Types

type Application

type Application struct {
	Config                *Configuration
	Sessions              session.Manager
	Security              ApplicationSecurity
	Linters               []Linter
	ContentSecurityPolicy *csp.ContentSecurityPolicy
	// contains filtered or unexported fields
}

Application represents a single web service.

func New

func New() *Application

New creates a new application.

func (*Application) AddPushCondition

func (app *Application) AddPushCondition(test func(Context) bool)

AddPushCondition registers a callback that needs to return true before an HTTP/2 push happens.

func (*Application) Any

func (app *Application) Any(path string, handler Handler)

Any registers your function to be called with any http method.

func (*Application) BindMiddleware

func (app *Application) BindMiddleware()

BindMiddleware applies the middleware to every router node. This is called by `Run` automatically and should never be called outside of tests.

func (*Application) Delete

func (app *Application) Delete(path string, handler Handler)

Delete registers your function to be called when the given DELETE path has been requested.

func (*Application) Get

func (app *Application) Get(path string, handler Handler)

Get registers your function to be called when the given GET path has been requested.

func (*Application) ListenAndServe

func (app *Application) ListenAndServe()

ListenAndServe starts the server. It guarantees that a TCP listener is listening on the ports defined in the config when the function returns.

func (*Application) Load

func (app *Application) Load()

Load loads the application configuration from config.json.

func (*Application) NewContext

func (app *Application) NewContext(req *http.Request, res http.ResponseWriter) *context

NewContext returns a new context from the pool.

func (*Application) OnEnd

func (app *Application) OnEnd(callback func())

OnEnd registers a callback to be executed on server shutdown.

func (*Application) OnError

func (app *Application) OnError(callback func(Context, error))

OnError registers a callback to be executed on server errors.

func (*Application) OnPush

func (app *Application) OnPush(callback func(Context))

OnPush registers a callback to be executed when an HTTP/2 push happens.

func (*Application) OnStart

func (app *Application) OnStart(callback func())

OnStart registers a callback to be executed on server start.

func (*Application) Post

func (app *Application) Post(path string, handler Handler)

Post registers your function to be called when the given POST path has been requested.

func (*Application) Put

func (app *Application) Put(path string, handler Handler)

Put registers your function to be called when the given PUT path has been requested.

func (*Application) Rewrite

func (app *Application) Rewrite(rewrite func(RewriteContext))

Rewrite adds a URL path rewrite function.

func (*Application) Router

func (app *Application) Router() *Router

Router returns the router used by the application.

func (*Application) Run

func (app *Application) Run()

Run starts your application.

func (*Application) ServeHTTP

func (app *Application) ServeHTTP(response http.ResponseWriter, request *http.Request)

ServeHTTP responds to the given request.

func (*Application) Shutdown

func (app *Application) Shutdown()

Shutdown will gracefully shut down all servers.

func (*Application) StartTime

func (app *Application) StartTime() time.Time

StartTime returns the time the application started.

func (*Application) Test

func (app *Application) Test(route string, paths ...string)

Test tests the given URI paths when the application starts.

func (*Application) TestRoute

func (app *Application) TestRoute(route string, uri string)

TestRoute tests the given route.

func (*Application) TestRoutes

func (app *Application) TestRoutes()

TestRoutes tests your application's routes.

func (*Application) Use

func (app *Application) Use(middlewares ...Middleware)

Use adds middleware to your middleware chain.

type ApplicationSecurity

type ApplicationSecurity struct {
	Certificate string
	Key         string
}

ApplicationSecurity stores the certificate data.

func (*ApplicationSecurity) Load

func (security *ApplicationSecurity) Load(certificate string, key string)

Load expects the path of the certificate and the key.

type Body

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

Body represents a request body.

func (Body) Bytes

func (body Body) Bytes() ([]byte, error)

Bytes returns a slice of bytes containing the request body.

func (Body) JSON

func (body Body) JSON() (interface{}, error)

JSON parses the body as a JSON object.

func (Body) JSONObject

func (body Body) JSONObject() (map[string]interface{}, error)

JSONObject parses the body as a JSON object and returns a map[string]interface{}.

func (Body) Reader

func (body Body) Reader() io.ReadCloser

Reader returns an io.Reader for the request body.

func (Body) String

func (body Body) String() (string, error)

String returns a string containing the request body.

type Configuration

type Configuration struct {
	Push  []string          `json:"push"`
	GZip  bool              `json:"gzip"`
	Ports PortConfiguration `json:"ports"`
}

Configuration represents the data in your config.json file.

func LoadConfig

func LoadConfig(path string) (*Configuration, error)

LoadConfig loads the application configuration from the file system.

func (*Configuration) Reset

func (config *Configuration) Reset()

Reset resets all fields to the default configuration.

type Context

type Context interface {
	App() *Application
	Bytes([]byte) error
	Close()
	CSS(string) error
	Get(string) string
	GetInt(string) (int, error)
	Error(int, ...interface{}) error
	EventStream(stream *EventStream) error
	File(string) error
	HasSession() bool
	HTML(string) error
	IP() string
	JavaScript(string) error
	JSON(interface{}) error
	Path() string
	Push(paths ...string) error
	Query(param string) string
	ReadAll(io.Reader) error
	Reader(io.Reader) error
	ReadSeeker(io.ReadSeeker) error
	Redirect(status int, url string) error
	RemoteIP() string
	Request() Request
	Response() Response
	Session() *session.Session
	SetStatus(int)
	Status() int
	String(string) error
	Text(string) error
}

Context represents the interface for a request & response context.

type Event

type Event struct {
	Name string
	Data interface{}
}

Event represents a single event in an event stream.

type EventStream

type EventStream struct {
	Events chan *Event
	Closed chan struct{}
}

EventStream includes a channel of events that we can send to and a closed channel that we can check for closed connections.

func NewEventStream

func NewEventStream() *EventStream

NewEventStream creates a new event stream.

type Handler

type Handler func(Context) error

Handler is a function that deals with the given request/response context.

func (Handler) Simulate

func (handler Handler) Simulate(ctx Context) (*httptest.ResponseRecorder, error)

Simulate simulates the request with the given handler and context and returns the recorded response.

type Linter

type Linter interface {
	Begin(route string, uri string)
	End(route string, uri string, response *client.Response)
}

Linter interface defines Begin and End methods that linters can implement.

type Listener

type Listener struct {
	*net.TCPListener
}

Listener sets TCP keep-alive timeouts on accepted connections.

func (Listener) Accept

func (listener Listener) Accept() (net.Conn, error)

Accept accepts incoming connections.

type Middleware

type Middleware func(Handler) Handler

Middleware is a function that accepts a handler and transforms it into a different handler.

type PortConfiguration

type PortConfiguration struct {
	HTTP  int `json:"http"`
	HTTPS int `json:"https"`
}

PortConfiguration lets you configure the ports that Aero will listen on.

type Request

type Request interface {
	Body() Body
	Context() stdContext.Context
	Header(string) string
	Host() string
	Internal() *http.Request
	Method() string
	Path() string
	Protocol() string
}

Request is an interface for HTTP requests.

type Response

type Response interface {
	Header(string) string
	Internal() http.ResponseWriter
	SetHeader(string, string)
	SetInternal(http.ResponseWriter)
}

Response is the interface for an HTTP response.

type RewriteContext

type RewriteContext interface {
	Path() string
	SetPath(string)
}

RewriteContext is the interface for the URI rewrite ability.

type Router

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

Router is a high-performance router.

func (*Router) Add

func (router *Router) Add(method string, path string, handler Handler)

Add registers a new handler for the given method and path.

func (*Router) Each

func (router *Router) Each(callback func(*tree))

Each traverses all trees and calls the given function on every node.

func (*Router) Find

func (router *Router) Find(method string, path string) Handler

Find returns the handler for the given route. This is only useful for testing purposes. Use Lookup instead.

func (*Router) Lookup

func (router *Router) Lookup(method string, path string, ctx *context)

Lookup finds the handler and parameters for the given route and assigns them to the given context.

func (*Router) Print

func (router *Router) Print(method string)

Print shows a pretty print of the routes.