uhttp

README

HTTP Module

The HTTP module is built on top of Gorilla Mux, but the details of that are abstracted away through uhttp.RouteHandler.

package main

import (
  "io"
  "net/http"

  "go.uber.org/fx"
  "go.uber.org/fx/modules/uhttp"
  "go.uber.org/fx/service"
)

func main() {
  svc, err := service.WithModules(
    uhttp.New(registerHTTP),
  ).Build()

  if err != nil {
    log.Fatal("Could not initialize service: ", err)
  }

  svc.Start(true)
}

func registerHTTP(service service.Host) []uhttp.RouteHandler {
    handleHome := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    ulog.Logger(r.Context()).Info("Inside the handler")
    io.WriteString(w, "Hello, world")
  })

  return []uhttp.RouteHandler{
    uhttp.NewRouteHandler("/", handleHome)
  }
}

HTTP handlers are set up with inbound middleware that inject tracing, authentication information etc. into the request context. Request tracing, authentication and context-aware logging are set up by default. With context-aware logging, all log statements include trace information such as traceID and spanID. This allows service owners to easily find logs corresponding to a request within and even across services.

HTTP Client

The http client serves similar purpose as http module, but for making requests. It has a set of auth and tracing outbound middleware for http requests and a default timeout set to 2 minutes.

package main

import (
  "log"
  "net/http"

  "go.uber.org/fx/modules/uhttp/client"
  "go.uber.org/fx/service"
)

func main() {
  svc, err := service.WithModules().Build()

  if err != nil {
    log.Fatal("Could not initialize service: ", err)
  }

  client := client.New(svc)
  client.Get("https://www.uber.com")
}

Benchmark results:

Current performance benchmark data:
BenchmarkClientMiddleware/empty-8         	100000000	        10.8 ns/op	       0 B/op	       0 allocs/op
BenchmarkClientMiddleware/tracing-8       	  500000	      3918 ns/op	    1729 B/op	      27 allocs/op
BenchmarkClientMiddleware/auth-8          	 1000000	      1866 ns/op	     719 B/op	      14 allocs/op
BenchmarkClientMiddleware/default-8       	  300000	      5604 ns/op	    2477 B/op	      41 allocs/op

Documentation

Overview

Package uhttp is the HTTP Module.

The HTTP module is built on top of Gorilla Mux (https://github.com/gorilla/mux), but the details of that are abstracted away through uhttp.RouteHandler.

package main

import (
  "io"
  "net/http"

  "go.uber.org/fx"
  "go.uber.org/fx/modules/uhttp"
  "go.uber.org/fx/service"
)

func main() {
  svc, err := service.WithModules(
    uhttp.New(registerHTTP),
  ).Build()

  if err != nil {
    log.Fatal("Could not initialize service: ", err)
  }

  svc.Start(true)
}

func registerHTTP(service service.Host) []uhttp.RouteHandler {
    handleHome := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    ulog.Logger(r.Context()).Info("Inside the handler")
    io.WriteString(w, "Hello, world")
  })

  return []uhttp.RouteHandler{
    uhttp.NewRouteHandler("/", handleHome)
  }
}

HTTP handlers are set up with inbound middleware that inject tracing, authentication information etc. into the request context. Request tracing, authentication and context-aware logging are set up by default. With context-aware logging, all log statements include trace information such as traceID and spanID. This allows service owners to easily find logs corresponding to a request within and even across services.

HTTP Client

The http client serves similar purpose as http module, but for making requests. It has a set of auth and tracing outbound middleware for http requests and a default timeout set to 2 minutes.

package main

import (
  "log"
  "net/http"

  "go.uber.org/fx/modules/uhttp/client"
  "go.uber.org/fx/service"
)

func main() {
  svc, err := service.WithModules().Build()

  if err != nil {
    log.Fatal("Could not initialize service: ", err)
  }

  client := client.New(svc)
  client.Get("https://www.uber.com")
}

Benchmark results:

Current performance benchmark data:
BenchmarkClientMiddleware/empty-8         	100000000	        10.8 ns/op	       0 B/op	       0 allocs/op
BenchmarkClientMiddleware/tracing-8       	  500000	      3918 ns/op	    1729 B/op	      27 allocs/op
BenchmarkClientMiddleware/auth-8          	 1000000	      1866 ns/op	     719 B/op	      14 allocs/op
BenchmarkClientMiddleware/default-8       	  300000	      5604 ns/op	    2477 B/op	      41 allocs/op

Index

• Constants
• func New(hookup GetHandlersFunc, options ...modules.Option) service.ModuleCreateFunc
• func WithInboundMiddleware(m ...InboundMiddleware) modules.Option
• type Config
• type GetHandlersFunc
• type InboundMiddleware
• type InboundMiddlewareFunc
  • func (f InboundMiddlewareFunc) Handle(w http.ResponseWriter, r *http.Request, next http.Handler)
• type Module
  • func (m *Module) IsRunning() bool
  • func (m *Module) Start(ready chan<- struct{}) <-chan error
  • func (m *Module) Stop() error
• type Route
  • func FromGorilla(r *mux.Route) Route
  • func (r Route) GorillaMux() *mux.Route
  • func (r Route) Headers(headerPairs ...string) Route
  • func (r Route) Methods(methods ...string) Route
• type RouteHandler
  • func NewRouteHandler(path string, handler http.Handler) RouteHandler
• type Router
  • func NewRouter(host service.Host) *Router
  • func (h *Router) Handle(path string, handler http.Handler)

Constants

const (
	// ContentType is the header key that contains the body type
	ContentType = "Content-Type"
	// ContentLength is the length of the HTTP body
	ContentLength = "Content-Length"
	// ContentTypeText is the plain content type
	ContentTypeText = "text/plain"
	// ContentTypeJSON is the JSON content type
	ContentTypeJSON = "application/json"
)

Functions

func New

func New(hookup GetHandlersFunc, options ...modules.Option) service.ModuleCreateFunc

New returns a new HTTP module

func WithInboundMiddleware

func WithInboundMiddleware(m ...InboundMiddleware) modules.Option

WithInboundMiddleware adds inbound middleware to uhttp Module that will be applied to all incoming http requests.

Types

type Config

type Config struct {
	modules.ModuleConfig
	Port    int           `yaml:"port"`
	Timeout time.Duration `yaml:"timeout"`
	Debug   *bool         `yaml:"debug"`
}

Config handles config for HTTP modules

type GetHandlersFunc

type GetHandlersFunc func(service service.Host) []RouteHandler

GetHandlersFunc returns a slice of registrants from a service host

type InboundMiddleware

type InboundMiddleware interface {
	Handle(w http.ResponseWriter, r *http.Request, next http.Handler)
}

InboundMiddleware applies inbound middleware on requests or responses such as adding tracing to the context.

type InboundMiddlewareFunc

type InboundMiddlewareFunc func(w http.ResponseWriter, r *http.Request, next http.Handler)

InboundMiddlewareFunc is an adaptor to call normal functions to apply inbound middleware.

func (InboundMiddlewareFunc) Handle

func (f InboundMiddlewareFunc) Handle(w http.ResponseWriter, r *http.Request, next http.Handler)

Handle implements Handle from the InboundMiddleware interface and simply delegates to the function

type Module

type Module struct {
	modules.ModuleBase
	// contains filtered or unexported fields
}

A Module is a module to handle HTTP requests

func (*Module) IsRunning

func (m *Module) IsRunning() bool

IsRunning returns whether the module is currently running

func (*Module) Start

func (m *Module) Start(ready chan<- struct{}) <-chan error

Start begins serving requests over HTTP

func (*Module) Stop

func (m *Module) Stop() error

Stop shuts down an HTTP module

type Route

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

A Route represents a handler for HTTP requests, with restrictions

func FromGorilla

func FromGorilla(r *mux.Route) Route

FromGorilla turns a gorilla mux route into an UberFx route

func (Route) GorillaMux

func (r Route) GorillaMux() *mux.Route

GorillaMux returns the underlying mux if you need to use it directly

func (Route) Headers

func (r Route) Headers(headerPairs ...string) Route

Headers allows easy enforcement of headers

func (Route) Methods

func (r Route) Methods(methods ...string) Route

Methods allows easy enforcement of metthods (HTTP Verbs)

type RouteHandler

type RouteHandler struct {
	Path    string
	Handler http.Handler
}

A RouteHandler is an HTTP handler for a single route

func NewRouteHandler

func NewRouteHandler(path string, handler http.Handler) RouteHandler

NewRouteHandler creates a route handler

type Router

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

Router is wrapper around gorila mux

func NewRouter

func NewRouter(host service.Host) *Router

NewRouter creates a new empty router

func (*Router) Handle

func (h *Router) Handle(path string, handler http.Handler)

Handle wraps and calls the http.Handler underneath