gearbox

README

gearbox ⚙ is a web framework for building micro services written in Go with a focus on high performance and memory optimization.

Currently, gearbox ⚙ is under development (not production ready) and built on fasthttp which is up to 10x faster than net/http

In gearbox, we care about peformance and memory which will be used by each method while building things up and how we can improve that. It also takes more time to research about each component that will be used and compare it with different implementations of other open source web frameworks. It may end up writing our own components in an optimized way to achieve our goals

gearbox seeks to be

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

Supported Go versions & installation

⚙ gearbox requires version 1.11 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.RequestCtx.Response.SetBodyString("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) {
		fmt.Printf("%s\n", ctx.Params["user"])
	})

	// Handler with optional parameter
	gb.Get("/search/:pattern?", func(ctx *gearbox.Context) {
		fmt.Printf("%s\n", ctx.Params["pattern"])
	})

	// Handler with regex parameter
	gb.Get("/book/:name:([a-z]+[0-3])", func(ctx *gearbox.Context) {
		fmt.Printf("%s\n", ctx.Params["name"])
	})

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

Middlewares

package main

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

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

	// create a logger middleware
	logMiddleware := func(ctx *gearbox.Context) {
		log.Printf(ctx.RequestCtx.String())
		ctx.Next() // Next is what allows the request to continue to the next middleware/handler
	}

	// create an unauthorized middleware
	unAuthorizedMiddleware := func(ctx *gearbox.Context) {
		ctx.RequestCtx.SetStatusCode(401) // unauthorized status code
		ctx.RequestCtx.Response.SetBodyString("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.RequestCtx.Response.SetBodyString("Hello World!")
	})
    
	// Register the routes to be used when grouping routes
	routes := []*gearbox.Route {
		gb.Get("/id", func(ctx *gearbox.Context) {
			ctx.RequestCtx.Response.SetBodyString("User X")
		}),
		gb.Delete("/id", func(ctx *gearbox.Context) {
			ctx.RequestCtx.Response.SetBodyString("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.RequestCtx.Response.SetBodyString("You accessed a protected page")
	})

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

Contribute & Support

• Add a GitHub Star
• Suggest new features, ideas and optimizations
• Report issues

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

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

Documentation

Overview

Package gearbox is a web framework with a focus on high performance and memory optimization

Index

• Constants
• func GetString(b []byte) string
• type Cache
  • func NewCache(capacity int) Cache
• type Context
  • func (ctx *Context) Next()
• type Gearbox
  • func New(settings ...*Settings) Gearbox
• type Route
• type Settings

Examples

• GetString
• NewCache

Constants

const (
	Version = "1.0.2"   // 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.

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 Cache

type Cache interface {
	Set(key string, value interface{})
	Get(key string) interface{}
}

Cache returns LRU cache

func NewCache

func NewCache(capacity int) Cache

NewCache returns LRU cache

Example

ExampleNewCache tests Cache set and get methods

cache := NewCache(3)
cache.Set("user1", 1)
fmt.Println(cache.Get("user1").(int))

cache.Set("user2", 2)
fmt.Println(cache.Get("user2").(int))

cache.Set("user3", 3)
fmt.Println(cache.Get("user3").(int))

cache.Set("user4", 4)
fmt.Println(cache.Get("user1"))
fmt.Println(cache.Get("user2").(int))

cache.Set("user5", 5)
fmt.Println(cache.Get("user3"))

cache.Set("user5", 6)
fmt.Println(cache.Get("user5").(int))

cache2 := NewCache(0)
cache2.Set("user1", 1)
fmt.Println(cache2.Get("user1").(int))

Output:

1
2
3
<nil>
2
<nil>
6
1

type Context

type Context struct {
	RequestCtx *fasthttp.RequestCtx
	Params     map[string]string
	// contains filtered or unexported fields
}

Context defines the current context of request and handlers/middlewares to execute

func (*Context) Next

func (ctx *Context) Next()

Next function is used to successfully pass from current middleware to next middleware. if the middleware thinks it's okay to pass it.

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
	Method(method, path string, handlers ...handlerFunc) *Route
	Fallback(handlers ...handlerFunc) error
	Use(middlewares ...handlerFunc)
	Group(prefix string, routes []*Route) []*Route
}

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

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

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

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

	// 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
}

Settings struct holds server settings