README

Oxy Build Status

Oxy is a Go library with HTTP handlers that enhance HTTP standard library:

  • Buffer retries and buffers requests and responses
  • Stream passes-through requests, supports chunked encoding with configurable flush interval
  • Forward forwards requests to remote location and rewrites headers
  • Roundrobin is a round-robin load balancer
  • Circuit Breaker Hystrix-style circuit breaker
  • Connlimit Simultaneous connections limiter
  • Ratelimit Rate limiter (based on tokenbucket algo)
  • Trace Structured request and response logger

It is designed to be fully compatible with http standard library, easy to customize and reuse.

Status

  • Initial design is completed
  • Covered by tests
  • Used as a reverse proxy engine in Vulcand

Quickstart

Every handler is http.Handler, so writing and plugging in a middleware is easy. Let us write a simple reverse proxy as an example:

Simple reverse proxy


import (
  "net/http"
  "github.com/vulcand/oxy/forward"
  "github.com/vulcand/oxy/testutils"
  )

// Forwards incoming requests to whatever location URL points to, adds proper forwarding headers
fwd, _ := forward.New()

redirect := http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
    // let us forward this request to another server
		req.URL = testutils.ParseURI("http://localhost:63450")
		fwd.ServeHTTP(w, req)
})
	
// that's it! our reverse proxy is ready!
s := &http.Server{
	Addr:           ":8080",
	Handler:        redirect,
}
s.ListenAndServe()

As a next step, let us add a round robin load-balancer:


import (
  "net/http"
  "github.com/vulcand/oxy/forward"
  "github.com/vulcand/oxy/roundrobin"
  )

// Forwards incoming requests to whatever location URL points to, adds proper forwarding headers
fwd, _ := forward.New()
lb, _ := roundrobin.New(fwd)

lb.UpsertServer(url1)
lb.UpsertServer(url2)

s := &http.Server{
	Addr:           ":8080",
	Handler:        lb,
}
s.ListenAndServe()

What if we want to handle retries and replay the request in case of errors? buffer handler will help:


import (
  "net/http"
  "github.com/vulcand/oxy/forward"
  "github.com/vulcand/oxy/buffer"
  "github.com/vulcand/oxy/roundrobin"
  )

// Forwards incoming requests to whatever location URL points to, adds proper forwarding headers

fwd, _ := forward.New()
lb, _ := roundrobin.New(fwd)

// buffer will read the request body and will replay the request again in case if forward returned status
// corresponding to nework error (e.g. Gateway Timeout)
buffer, _ := buffer.New(lb, buffer.Retry(`IsNetworkError() && Attempts() < 2`))

lb.UpsertServer(url1)
lb.UpsertServer(url2)

// that's it! our reverse proxy is ready!
s := &http.Server{
	Addr:           ":8080",
	Handler:        buffer,
}
s.ListenAndServe()
Expand ▾ Collapse ▴

Directories

Path Synopsis
buffer Package buffer provides http.Handler middleware that solves several problems when dealing with http requests: Reads the entire request and response into buffer, optionally buffering it to disk for large requests.
cbreaker Package cbreaker implements circuit breaker similar to https://github.com/Netflix/Hystrix/wiki/How-it-Works Vulcan circuit breaker watches the error condtion to match after which it activates the fallback scenario, e.g.
connlimit Package connlimit provides control over simultaneous connections coming from the same source
forward Package forward implements http handler that forwards requests to remote server and serves back the response websocket proxying support based on https://github.com/yhat/wsutil
memmetrics
ratelimit Package ratelimit Tokenbucket based request rate limiter
roundrobin Package roundrobin implements dynamic weighted round robin load balancer http handler
stream Package stream provides http.Handler middleware that passes-through the entire request Stream works around several limitations caused by buffering implementations, but also introduces certain risks.
testutils
trace Package trace implement structured logging of requests
utils