gearbox

README

gearbox ⚙ is a web framework for building micro services written in Go with a focus on high performance. It's built on fasthttp which is up to 10x faster than net/http

gearbox seeks to be

• Secure 🔐
• Fast 🚀
• Easy to use 👓
• Lightweight

Supported Go versions & installation

⚙ gearbox requires version 1.14 or higher of Go (Download Go)

Just use go get to download and install gearbox

go get -u github.com/gogearbox/gearbox

Examples

package main

import (
	"github.com/gogearbox/gearbox"
)

func main() {
	// Setup gearbox
	gb := gearbox.New()

	// Define your handlers
	gb.Get("/hello", func(ctx gearbox.Context) {
		ctx.SendString("Hello World!")
	})

	// Start service
	gb.Start(":3000")
}

Parameters

package main

import (
	"github.com/gogearbox/gearbox"
)

func main() {
	// Setup gearbox
	gb := gearbox.New()

	// Handler with parameter
	gb.Get("/users/:user", func(ctx gearbox.Context) {
		ctx.SendString(ctx.Param("user"))
	})

	// Start service
	gb.Start(":3000")
}

Middlewares

package main

import (
	"log"

	"github.com/gogearbox/gearbox"
)

func main() {
	// Setup gearbox
	gb := gearbox.New()

	// create a logger middleware
	logMiddleware := func(ctx gearbox.Context) {
		log.Printf("log message!")

		// Next is what allows the request to continue to the next
		// middleware/handler
		ctx.Next()
	}

	// create an unauthorized middleware
	unAuthorizedMiddleware := func(ctx gearbox.Context) {
		ctx.Status(gearbox.StatusUnauthorized)
			.SendString("You are unauthorized to access this page!")
	}

	// Register the log middleware for all requests
	gb.Use(logMiddleware)

	// Define your handlers
	gb.Get("/hello", func(ctx gearbox.Context) {
		ctx.SendString("Hello World!")
	})

	// Register the routes to be used when grouping routes
	routes := []*gearbox.Route{
		gb.Get("/id", func(ctx gearbox.Context) {
			ctx.SendString("User X")
		}),
		gb.Delete("/id", func(ctx gearbox.Context) {
			ctx.SendString("Deleted")
		}),
	}

	// Group account routes
	accountRoutes := gb.Group("/account", routes)

	// Group account routes to be under api
	gb.Group("/api", accountRoutes)

	// Define a route with unAuthorizedMiddleware as the middleware
	// you can define as many middlewares as you want and have
	// the handler as the last argument
	gb.Get("/protected", unAuthorizedMiddleware, func(ctx gearbox.Context) {
		ctx.SendString("You accessed a protected page")
	})

	// Start service
	gb.Start(":3000")
}

Static Files

package main

import (
	"github.com/gogearbox/gearbox"
)

func main() {
	// Setup gearbox
	gb := gearbox.New()

	// Serve files in assets directory for prefix static
	// for example /static/gearbox.png, etc.
	gb.Static("/static", "./assets")

	// Start service
	gb.Start(":3000")
}

Benchmarks

• CPU 3.1 GHz Intel Xeon® Platinum 8175M (24 physical cores, 48 logical cores)
• MEMORY 192GB
• GO go 1.14.6 linux/amd64
• OS Linux

For more results, check Our Docs

Contribute & Support

• Add a GitHub Star
• Suggest new features, ideas and optimizations
• Report issues
• Donating a cup of coffee

Check Our Docs for more information about gearbox and how to contribute

Sponsors

Organizations that are helping to manage, promote, and support Gearbox ⚙

trella: A B2B technology platform and trucking marketplace that connects shippers with carriers

Who uses Gearbox

Gearbox ⚙ is being used by multiple organizations including but not limited to

Contributors

Get in touch!

Feel free to chat with us on Discord, or email us at gearbox@googlegroups.com if you have questions, or suggestions

License

gearbox is licensed under MIT License

Logo is created by Mahmoud Sayed and distributed under Creative Commons License

Third-party library licenses

• FastHTTP
• json-iterator

Documentation

Overview

Package gearbox is a web framework with a focus on high performance

Index

• Constants
• func GetString(b []byte) string
• type Context
• type Gearbox
  • func New(settings ...*Settings) Gearbox
• type Route
• type Settings

Examples

• GetString

Constants

const (
	Version = "1.2.3"   // Version of gearbox
	Name    = "Gearbox" // Name of gearbox

)

Exported constants

const (
	MethodGet     = "GET"     // RFC 7231, 4.3.1
	MethodHead    = "HEAD"    // RFC 7231, 4.3.2
	MethodPost    = "POST"    // RFC 7231, 4.3.3
	MethodPut     = "PUT"     // RFC 7231, 4.3.4
	MethodPatch   = "PATCH"   // RFC 5789
	MethodDelete  = "DELETE"  // RFC 7231, 4.3.5
	MethodConnect = "CONNECT" // RFC 7231, 4.3.6
	MethodOptions = "OPTIONS" // RFC 7231, 4.3.7
	MethodTrace   = "TRACE"   // RFC 7231, 4.3.8
)

HTTP methods were copied from net/http.

const (
	StatusContinue           = 100 // RFC 7231, 6.2.1
	StatusSwitchingProtocols = 101 // RFC 7231, 6.2.2
	StatusProcessing         = 102 // RFC 2518, 10.1

	StatusOK                   = 200 // RFC 7231, 6.3.1
	StatusCreated              = 201 // RFC 7231, 6.3.2
	StatusAccepted             = 202 // RFC 7231, 6.3.3
	StatusNonAuthoritativeInfo = 203 // RFC 7231, 6.3.4
	StatusNoContent            = 204 // RFC 7231, 6.3.5
	StatusResetContent         = 205 // RFC 7231, 6.3.6
	StatusPartialContent       = 206 // RFC 7233, 4.1
	StatusMultiStatus          = 207 // RFC 4918, 11.1
	StatusAlreadyReported      = 208 // RFC 5842, 7.1
	StatusIMUsed               = 226 // RFC 3229, 10.4.1

	StatusMultipleChoices  = 300 // RFC 7231, 6.4.1
	StatusMovedPermanently = 301 // RFC 7231, 6.4.2
	StatusFound            = 302 // RFC 7231, 6.4.3
	StatusSeeOther         = 303 // RFC 7231, 6.4.4
	StatusNotModified      = 304 // RFC 7232, 4.1
	StatusUseProxy         = 305 // RFC 7231, 6.4.5

	StatusTemporaryRedirect = 307 // RFC 7231, 6.4.7
	StatusPermanentRedirect = 308 // RFC 7538, 3

	StatusBadRequest                   = 400 // RFC 7231, 6.5.1
	StatusUnauthorized                 = 401 // RFC 7235, 3.1
	StatusPaymentRequired              = 402 // RFC 7231, 6.5.2
	StatusForbidden                    = 403 // RFC 7231, 6.5.3
	StatusNotFound                     = 404 // RFC 7231, 6.5.4
	StatusMethodNotAllowed             = 405 // RFC 7231, 6.5.5
	StatusNotAcceptable                = 406 // RFC 7231, 6.5.6
	StatusProxyAuthRequired            = 407 // RFC 7235, 3.2
	StatusRequestTimeout               = 408 // RFC 7231, 6.5.7
	StatusConflict                     = 409 // RFC 7231, 6.5.8
	StatusGone                         = 410 // RFC 7231, 6.5.9
	StatusLengthRequired               = 411 // RFC 7231, 6.5.10
	StatusPreconditionFailed           = 412 // RFC 7232, 4.2
	StatusRequestEntityTooLarge        = 413 // RFC 7231, 6.5.11
	StatusRequestURITooLong            = 414 // RFC 7231, 6.5.12
	StatusUnsupportedMediaType         = 415 // RFC 7231, 6.5.13
	StatusRequestedRangeNotSatisfiable = 416 // RFC 7233, 4.4
	StatusExpectationFailed            = 417 // RFC 7231, 6.5.14
	StatusTeapot                       = 418 // RFC 7168, 2.3.3
	StatusUnprocessableEntity          = 422 // RFC 4918, 11.2
	StatusLocked                       = 423 // RFC 4918, 11.3
	StatusFailedDependency             = 424 // RFC 4918, 11.4
	StatusUpgradeRequired              = 426 // RFC 7231, 6.5.15
	StatusPreconditionRequired         = 428 // RFC 6585, 3
	StatusTooManyRequests              = 429 // RFC 6585, 4
	StatusRequestHeaderFieldsTooLarge  = 431 // RFC 6585, 5
	StatusUnavailableForLegalReasons   = 451 // RFC 7725, 3

	StatusInternalServerError           = 500 // RFC 7231, 6.6.1
	StatusNotImplemented                = 501 // RFC 7231, 6.6.2
	StatusBadGateway                    = 502 // RFC 7231, 6.6.3
	StatusServiceUnavailable            = 503 // RFC 7231, 6.6.4
	StatusGatewayTimeout                = 504 // RFC 7231, 6.6.5
	StatusHTTPVersionNotSupported       = 505 // RFC 7231, 6.6.6
	StatusVariantAlsoNegotiates         = 506 // RFC 2295, 8.1
	StatusInsufficientStorage           = 507 // RFC 4918, 11.5
	StatusLoopDetected                  = 508 // RFC 5842, 7.2
	StatusNotExtended                   = 510 // RFC 2774, 7
	StatusNetworkAuthenticationRequired = 511 // RFC 6585, 6
)

HTTP status codes were copied from net/http.

const (
	MIMEApplicationJSON = "application/json"
)

MIME types

Functions

func GetString

func GetString(b []byte) string

GetString gets the content of a string as a []byte without copying #nosec G103

Example

ExampleGetString tests converting []byte to string

b := []byte("ABC€")
str := GetString(b)
fmt.Println(str)
fmt.Println(len(b) == len(str))

b = []byte("مستخدم")
str = GetString(b)
fmt.Println(str)
fmt.Println(len(b) == len(str))

b = nil
str = GetString(b)
fmt.Println(str)
fmt.Println(len(b) == len(str))
fmt.Println(len(str))

Output:

ABC€
true
مستخدم
true

true
0

Types

type Context

type Context interface {
	Next()
	Context() *fasthttp.RequestCtx
	Param(key string) string
	Query(key string) string
	SendBytes(value []byte) Context
	SendString(value string) Context
	SendJSON(in interface{}) error
	Status(status int) Context
	Set(key string, value string)
	Get(key string) string
	SetLocal(key string, value interface{})
	GetLocal(key string) interface{}
	Body() string
	ParseBody(out interface{}) error
}

Context interface

type Gearbox

type Gearbox interface {
	Start(address string) error
	Stop() error
	Get(path string, handlers ...handlerFunc) *Route
	Head(path string, handlers ...handlerFunc) *Route
	Post(path string, handlers ...handlerFunc) *Route
	Put(path string, handlers ...handlerFunc) *Route
	Patch(path string, handlers ...handlerFunc) *Route
	Delete(path string, handlers ...handlerFunc) *Route
	Connect(path string, handlers ...handlerFunc) *Route
	Options(path string, handlers ...handlerFunc) *Route
	Trace(path string, handlers ...handlerFunc) *Route
	Group(prefix string, routes []*Route) []*Route
	Static(prefix, root string)
	NotFound(handlers ...handlerFunc)
	Use(middlewares ...handlerFunc)
}

Gearbox interface

func New

func New(settings ...*Settings) Gearbox

New creates a new instance of gearbox

type Route

type Route struct {
	Method   string
	Path     string
	Handlers handlersChain
}

Route struct which holds each route info

type Settings

type Settings struct {
	// Enable case sensitive routing
	CaseInSensitive bool // default false

	// Maximum size of LRU cache that will be used in routing if it's enabled
	CacheSize int // default 1000

	// Enables answering with HTTP status code 405 if request does not match
	// with any route, but there are another methods are allowed for that route
	// otherwise answer with Not Found handlers or status code 404.
	HandleMethodNotAllowed bool // default false

	// Enables automatic replies to OPTIONS requests if there are no handlers
	// registered for that route
	HandleOPTIONS bool // default false

	// Enables automatic recovering from panic while executing handlers by
	// answering with HTTP status code 500 and logging error message without
	// stopping service
	AutoRecover bool // default false

	// ServerName for sending in response headers
	ServerName string // default ""

	// Maximum request body size
	MaxRequestBodySize int // default 4 * 1024 * 1024

	// Maximum number of route params count
	MaxRouteParams int // default 1024

	// Max request url length
	MaxRequestURLLength int // default 2048

	// Maximum number of concurrent connections
	Concurrency int // default 256 * 1024

	// This will spawn multiple Go processes listening on the same port
	// Default: false
	Prefork bool

	// LRU caching used to speed up routing
	DisableCaching bool // default false

	// Disable printing gearbox banner
	DisableStartupMessage bool // default false

	// Disable keep-alive connections, the server will close incoming connections after sending the first response to client
	DisableKeepalive bool // default false

	// When set to true causes the default date header to be excluded from the response
	DisableDefaultDate bool // default false

	// When set to true, causes the default Content-Type header to be excluded from the Response
	DisableDefaultContentType bool // default false

	// By default all header names are normalized: conteNT-tYPE -> Content-Type
	DisableHeaderNormalizing bool // default false

	// The amount of time allowed to read the full request including body
	ReadTimeout time.Duration // default unlimited

	// The maximum duration before timing out writes of the response
	WriteTimeout time.Duration // default unlimited

	// The maximum amount of time to wait for the next request when keep-alive is enabled
	IdleTimeout time.Duration // default unlimited

	// Enable TLS or not
	TLSEnabled bool // default false

	// The path of the TLS certificate
	TLSCertPath string // default ""

	// The path of the TLS key
	TLSKeyPath string // default ""
}

Settings struct holds server settings