# Go CORS handler [![godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/rs/cors) [![license](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](https://raw.githubusercontent.com/rs/cors/master/LICENSE) [![Go Coverage](https://github.com/rs/cors/wiki/coverage.svg)](https://raw.githack.com/wiki/rs/cors/coverage.html)

CORS is a `net/http` handler implementing [Cross Origin Resource Sharing W3 specification](http://www.w3.org/TR/cors/) in Golang.

## Getting Started

After installing Go and setting up your [GOPATH](http://golang.org/doc/code.html#GOPATH), create your first `.go` file. We'll call it `server.go`.

```go
package main

import (
    "net/http"

    "github.com/rs/cors"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        w.Write([]byte("{\"hello\": \"world\"}"))
    })

    // cors.Default() setup the middleware with default options being
    // all origins accepted with simple methods (GET, POST). See
    // documentation below for more options.
    handler := cors.Default().Handler(mux)
    http.ListenAndServe(":8080", handler)
}
```

Install `cors`:

    go get github.com/rs/cors

Then run your server:

    go run server.go

The server now runs on `localhost:8080`:

    $ curl -D - -H 'Origin: http://foo.com' http://localhost:8080/
    HTTP/1.1 200 OK
    Access-Control-Allow-Origin: foo.com
    Content-Type: application/json
    Date: Sat, 25 Oct 2014 03:43:57 GMT
    Content-Length: 18

    {"hello": "world"}

### Allow * With Credentials Security Protection

This library has been modified to avoid a well known security issue when configured with `AllowedOrigins` to `*` and `AllowCredentials` to `true`. Such setup used to make the library reflects the request `Origin` header value, working around a security protection embedded into the standard that makes clients to refuse such configuration. This behavior has been removed with [#55](https://github.com/rs/cors/issues/55) and [#57](https://github.com/rs/cors/issues/57).

If you depend on this behavior and understand the implications, you can restore it using the `AllowOriginFunc` with `func(origin string) {return true}`.

Please refer to [#55](https://github.com/rs/cors/issues/55) for more information about the security implications.

### More Examples

* `net/http`: [examples/nethttp/server.go](https://github.com/rs/cors/blob/master/examples/nethttp/server.go)
* [Goji](https://goji.io): [examples/goji/server.go](https://github.com/rs/cors/blob/master/examples/goji/server.go)
* [Martini](http://martini.codegangsta.io): [examples/martini/server.go](https://github.com/rs/cors/blob/master/examples/martini/server.go)
* [Negroni](https://github.com/codegangsta/negroni): [examples/negroni/server.go](https://github.com/rs/cors/blob/master/examples/negroni/server.go)
* [Alice](https://github.com/justinas/alice): [examples/alice/server.go](https://github.com/rs/cors/blob/master/examples/alice/server.go)
* [HttpRouter](https://github.com/julienschmidt/httprouter): [examples/httprouter/server.go](https://github.com/rs/cors/blob/master/examples/httprouter/server.go)
* [Gorilla](http://www.gorillatoolkit.org/pkg/mux): [examples/gorilla/server.go](https://github.com/rs/cors/blob/master/examples/gorilla/server.go)
* [Buffalo](https://gobuffalo.io): [examples/buffalo/server.go](https://github.com/rs/cors/blob/master/examples/buffalo/server.go)
* [Gin](https://gin-gonic.github.io/gin): [examples/gin/server.go](https://github.com/rs/cors/blob/master/examples/gin/server.go)
* [Chi](https://github.com/go-chi/chi): [examples/chi/server.go](https://github.com/rs/cors/blob/master/examples/chi/server.go)

## Parameters

Parameters are passed to the middleware thru the `cors.New` method as follow:

```go
c := cors.New(cors.Options{
    AllowedOrigins: []string{"http://foo.com", "http://foo.com:8080"},
    AllowCredentials: true,
    // Enable Debugging for testing, consider disabling in production
    Debug: true,
})

// Insert the middleware
handler = c.Handler(handler)
```

* **AllowedOrigins** `[]string`: A list of origins a cross-domain request can be executed from. If the special `*` value is present in the list, all origins will be allowed. An origin may contain a wildcard (`*`) to replace 0 or more characters (i.e.: `http://*.domain.com`). Usage of wildcards implies a small performance penality. Only one wildcard can be used per origin. The default value is `*`.
* **AllowOriginFunc** `func (origin string) bool`: A custom function to validate the origin. It takes the origin as an argument and returns true if allowed, or false otherwise. If this option is set, the content of `AllowedOrigins` is ignored.
* **AllowOriginRequestFunc** `func (r *http.Request, origin string) bool`: A custom function to validate the origin. It takes the HTTP Request object and the origin as argument and returns true if allowed or false otherwise. If this option is set, the contents of `AllowedOrigins` and `AllowOriginFunc` are ignored.
Deprecated: use `AllowOriginVaryRequestFunc` instead.
* **AllowOriginVaryRequestFunc** `func(r *http.Request, origin string) (bool, []string)`: A custom function to validate the origin. It takes the HTTP Request object and the origin as argument and returns true if allowed or false otherwise with a list of headers used to take that decision if any so they can be added to the Vary header. If this option is set, the contents of `AllowedOrigins`, `AllowOriginFunc` and `AllowOriginRequestFunc` are ignored.
* **AllowedMethods** `[]string`: A list of methods the client is allowed to use with cross-domain requests. Default value is simple methods (`GET` and `POST`).
* **AllowedHeaders** `[]string`: A list of non simple headers the client is allowed to use with cross-domain requests.
* **ExposedHeaders** `[]string`: Indicates which headers are safe to expose to the API of a CORS API specification.
* **AllowCredentials** `bool`: Indicates whether the request can include user credentials like cookies, HTTP authentication or client side SSL certificates. The default is `false`.
* **AllowPrivateNetwork** `bool`: Indicates whether to accept cross-origin requests over a private network.
* **MaxAge** `int`: Indicates how long (in seconds) the results of a preflight request can be cached. The default is `0` which stands for no max age.
* **OptionsPassthrough** `bool`: Instructs preflight to let other potential next handlers to process the `OPTIONS` method. Turn this on if your application handles `OPTIONS`.
* **OptionsSuccessStatus** `int`: Provides a status code to use for successful OPTIONS requests. Default value is `http.StatusNoContent` (`204`).
* **Debug** `bool`: Debugging flag adds additional output to debug server side CORS issues.

See [API documentation](http://godoc.org/github.com/rs/cors) for more info.

## Benchmarks

```
goos: darwin
goarch: arm64
pkg: github.com/rs/cors
BenchmarkWithout-10            	135325480	         8.124 ns/op	       0 B/op	       0 allocs/op
BenchmarkDefault-10            	24082140	        51.40 ns/op	       0 B/op	       0 allocs/op
BenchmarkAllowedOrigin-10      	16424518	        88.25 ns/op	       0 B/op	       0 allocs/op
BenchmarkPreflight-10          	 8010259	       147.3 ns/op	       0 B/op	       0 allocs/op
BenchmarkPreflightHeader-10    	 6850962	       175.0 ns/op	       0 B/op	       0 allocs/op
BenchmarkWildcard/match-10     	253275342	         4.714 ns/op	       0 B/op	       0 allocs/op
BenchmarkWildcard/too_short-10 	1000000000	         0.6235 ns/op	       0 B/op	       0 allocs/op
PASS
ok  	github.com/rs/cors	99.131s
```

## Licenses

All source code is licensed under the [MIT License](https://raw.github.com/rs/cors/master/LICENSE).


CORS

negroni

Go package for easily rendering JSON, XML, and HTML template responses

# Render [![GoDoc](https://pkg.go.dev/badge/github.com/unrolled/render)](http://godoc.org/github.com/unrolled/render) [![Test](https://github.com/unrolled/render/actions/workflows/test.yaml/badge.svg)](https://github.com/unrolled/render/actions)


Render is a package that provides functionality for easily rendering JSON, XML, text, binary data, and HTML templates.

## Usage
Render can be used with pretty much any web framework providing you can access the `http.ResponseWriter` from your handler. The rendering functions simply wraps Go's existing functionality for marshaling and rendering data.

- HTML: Uses the [html/template](http://golang.org/pkg/html/template/) package to render HTML templates.
- JSON: Uses the [encoding/json](http://golang.org/pkg/encoding/json/) package to marshal data into a JSON-encoded response.
- XML: Uses the [encoding/xml](http://golang.org/pkg/encoding/xml/) package to marshal data into an XML-encoded response.
- Binary data: Passes the incoming data straight through to the `http.ResponseWriter`.
- Text: Passes the incoming string straight through to the `http.ResponseWriter`.

~~~ go
// main.go
package main

import (
    "encoding/xml"
    "net/http"

    "github.com/unrolled/render"
)

type ExampleXml struct {
    XMLName xml.Name `xml:"example"`
    One     string   `xml:"one,attr"`
    Two     string   `xml:"two,attr"`
}

func main() {
    r := render.New()
    mux := http.NewServeMux()

    mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
        w.Write([]byte("Welcome, visit sub pages now."))
    })

    mux.HandleFunc("/data", func(w http.ResponseWriter, req *http.Request) {
        r.Data(w, http.StatusOK, []byte("Some binary data here."))
    })

    mux.HandleFunc("/text", func(w http.ResponseWriter, req *http.Request) {
        r.Text(w, http.StatusOK, "Plain text here")
    })

    mux.HandleFunc("/json", func(w http.ResponseWriter, req *http.Request) {
        r.JSON(w, http.StatusOK, map[string]string{"hello": "json"})
    })

    mux.HandleFunc("/jsonp", func(w http.ResponseWriter, req *http.Request) {
        r.JSONP(w, http.StatusOK, "callbackName", map[string]string{"hello": "jsonp"})
    })

    mux.HandleFunc("/xml", func(w http.ResponseWriter, req *http.Request) {
        r.XML(w, http.StatusOK, ExampleXml{One: "hello", Two: "xml"})
    })

    mux.HandleFunc("/html", func(w http.ResponseWriter, req *http.Request) {
        // Assumes you have a template in ./templates called "example.tmpl"
        // $ mkdir -p templates && echo "<h1>Hello {{.}}.</h1>" > templates/example.tmpl
        r.HTML(w, http.StatusOK, "example", "World")
    })

    http.ListenAndServe("127.0.0.1:3000", mux)
}
~~~

~~~ html

<h1>Hello {{.}}.</h1>
~~~

### Available Options
Render comes with a variety of configuration options _(Note: these are not the default option values. See the defaults below.)_:

~~~ go
// ...
r := render.New(render.Options{
    Directory: "templates", // Specify what path to load the templates from.
    FileSystem: &LocalFileSystem{}, // Specify filesystem from where files are loaded.
    Asset: func(name string) ([]byte, error) { // Load from an Asset function instead of file.
      return []byte("template content"), nil
    },
    AssetNames: func() []string { // Return a list of asset names for the Asset function
      return []string{"filename.tmpl"}
    },
    Layout: "layout", // Specify a layout template. Layouts can call {{ yield }} to render the current template or {{ partial "css" }} to render a partial from the current template.
    Extensions: []string{".tmpl", ".html"}, // Specify extensions to load for templates.
    Funcs: []template.FuncMap{AppHelpers}, // Specify helper function maps for templates to access.
    Delims: render.Delims{"{[{", "}]}"}, // Sets delimiters to the specified strings.
    Charset: "UTF-8", // Sets encoding for content-types. Default is "UTF-8".
    DisableCharset: true, // Prevents the charset from being appended to the content type header.
    IndentJSON: true, // Output human readable JSON.
    IndentXML: true, // Output human readable XML.
    PrefixJSON: []byte(")]}',\n"), // Prefixes JSON responses with the given bytes.
    PrefixXML: []byte("<?xml version='1.0' encoding='UTF-8'?>"), // Prefixes XML responses with the given bytes.
    HTMLContentType: "application/xhtml+xml", // Output XHTML content type instead of default "text/html".
    IsDevelopment: true, // Render will now recompile the templates on every HTML response.
    UseMutexLock: true, // Overrides the default no lock implementation and uses the standard `sync.RWMutex` lock.
    UnEscapeHTML: true, // Ensure '&<>' are output correctly (JSON only).
    StreamingJSON: true, // Streams the JSON response via json.Encoder.
    HTMLTemplateOption: "missingkey=error", // Sets the option value for HTML templates. See https://pkg.go.dev/html/template#Template.Option for a list of known options.
    RequirePartials: true, // Return an error if a template is missing a partial used in a layout.
    DisableHTTPErrorRendering: true, // Disables automatic rendering of http.StatusInternalServerError when an error occurs.
    JSONEncoder: func(w io.Writer) render.JSONEncoder { // Use jsoniter "github.com/json-iterator"
        return jsoniter.NewEncoder(w)
    },
})
// ...
~~~

### Default Options
These are the preset options for Render:

~~~ go
r := render.New()

// Is the same as the default configuration options:

r := render.New(render.Options{
    Directory: "templates",
    FileSystem: &LocalFileSystem{},
    Asset: nil,
    AssetNames: nil,
    Layout: "",
    Extensions: []string{".tmpl"},
    Funcs: []template.FuncMap{},
    Delims: render.Delims{"{{", "}}"},
    Charset: "UTF-8",
    DisableCharset: false,
    IndentJSON: false,
    IndentXML: false,
    PrefixJSON: []byte(""),
    PrefixXML: []byte(""),
    BinaryContentType: "application/octet-stream",
    HTMLContentType: "text/html",
    JSONContentType: "application/json",
    JSONPContentType: "application/javascript",
    TextContentType: "text/plain",
    XMLContentType: "application/xhtml+xml",
    IsDevelopment: false,
    UseMutexLock: false,
    UnEscapeHTML: false,
    HTMLTemplateOption: "",
    StreamingJSON: false,
    RequirePartials: false,
    DisableHTTPErrorRendering: false,
    RenderPartialsWithoutPrefix: false,
    BufferPool: GenericBufferPool,
    JSONEncoder: nil,
})
~~~

### JSON vs Streaming JSON
By default, Render does **not** stream JSON to the `http.ResponseWriter`. It instead marshalls your object into a byte array, and if no errors occurred, writes that byte array to the `http.ResponseWriter`. If you would like to use the built it in streaming functionality (`json.Encoder`), you can set the `StreamingJSON` setting to `true`. This will stream the output directly to the `http.ResponseWriter`. Also note that streaming is only implemented in `render.JSON` and not `render.JSONP`.

### Loading Templates
By default Render will attempt to load templates with a '.tmpl' extension from the "templates" directory. Templates are found by traversing the templates directory and are named by path and basename. For instance, the following directory structure:

~~~
templates/
  |
  |__ admin/
  |      |
  |      |__ index.tmpl
  |      |
  |      |__ edit.tmpl
  |
  |__ home.tmpl
~~~

Will provide the following templates:
~~~
admin/index
admin/edit
home
~~~

Templates can be loaded from an `embed.FS`.

~~~ go
// ...

//go:embed templates/*.html templates/*.tmpl
var embeddedTemplates embed.FS

// ...

r := render.New(render.Options{
    Directory: "templates",
    FileSystem: &render.EmbedFileSystem{
        FS: embeddedTemplates,
    },
    Extensions: []string{".html", ".tmpl"},
})
// ...
~~~

You can also load templates from memory by providing the `Asset` and `AssetNames` options,
e.g. when generating an asset file using [go-bindata](https://github.com/jteeuwen/go-bindata).

### Layouts
Render provides `yield` and `partial` functions for layouts to access:
~~~ go
// ...
r := render.New(render.Options{
    Layout: "layout",
})
// ...
~~~

~~~ html

<html>
  <head>
    <title>My Layout</title>
    
    {{ partial "css" }}
  </head>
  <body>
    
    {{ partial "header" }}
    
    {{ yield }}
    
    {{ partial "footer" }}
  </body>
</html>
~~~

`current` can also be called to get the current template being rendered.
~~~ html

<html>
  <head>
    <title>My Layout</title>
  </head>
  <body>
    This is the {{ current }} page.
  </body>
</html>
~~~

Partials are defined by individual templates as seen below. The partial template's
name needs to be defined as "{partial name}-{template name}".
~~~ html

{{ define "header-home" }}
<h1>Home</h1>
{{ end }}

{{ define "footer-home"}}
<p>The End</p>
{{ end }}
~~~

By default, the template is not required to define all partials referenced in the
layout. If you want an error to be returned when a template does not define a
partial, set `Options.RequirePartials = true`.

### Character Encodings
Render will automatically set the proper Content-Type header based on which function you call. See below for an example of what the default settings would output (note that UTF-8 is the default, and binary data does not output the charset):
~~~ go
// main.go
package main

import (
    "encoding/xml"
    "net/http"

    "github.com/unrolled/render"
)

type ExampleXml struct {
    XMLName xml.Name `xml:"example"`
    One     string   `xml:"one,attr"`
    Two     string   `xml:"two,attr"`
}

func main() {
    r := render.New(render.Options{})
    mux := http.NewServeMux()

    // This will set the Content-Type header to "application/octet-stream".
    // Note that this does not receive a charset value.
    mux.HandleFunc("/data", func(w http.ResponseWriter, req *http.Request) {
        r.Data(w, http.StatusOK, []byte("Some binary data here."))
    })

    // This will set the Content-Type header to "application/json; charset=UTF-8".
    mux.HandleFunc("/json", func(w http.ResponseWriter, req *http.Request) {
        r.JSON(w, http.StatusOK, map[string]string{"hello": "json"})
    })

    // This will set the Content-Type header to "text/xml; charset=UTF-8".
    mux.HandleFunc("/xml", func(w http.ResponseWriter, req *http.Request) {
        r.XML(w, http.StatusOK, ExampleXml{One: "hello", Two: "xml"})
    })

    // This will set the Content-Type header to "text/plain; charset=UTF-8".
    mux.HandleFunc("/text", func(w http.ResponseWriter, req *http.Request) {
        r.Text(w, http.StatusOK, "Plain text here")
    })

    // This will set the Content-Type header to "text/html; charset=UTF-8".
    mux.HandleFunc("/html", func(w http.ResponseWriter, req *http.Request) {
        // Assumes you have a template in ./templates called "example.tmpl"
        // $ mkdir -p templates && echo "<h1>Hello {{.}}.</h1>" > templates/example.tmpl
        r.HTML(w, http.StatusOK, "example", "World")
    })

    http.ListenAndServe("127.0.0.1:3000", mux)
}
~~~

In order to change the charset, you can set the `Charset` within the `render.Options` to your encoding value:
~~~ go
// main.go
package main

import (
    "encoding/xml"
    "net/http"

    "github.com/unrolled/render"
)

type ExampleXml struct {
    XMLName xml.Name `xml:"example"`
    One     string   `xml:"one,attr"`
    Two     string   `xml:"two,attr"`
}

func main() {
    r := render.New(render.Options{
        Charset: "ISO-8859-1",
    })
    mux := http.NewServeMux()

    // This will set the Content-Type header to "application/octet-stream".
    // Note that this does not receive a charset value.
    mux.HandleFunc("/data", func(w http.ResponseWriter, req *http.Request) {
        r.Data(w, http.StatusOK, []byte("Some binary data here."))
    })

    // This will set the Content-Type header to "application/json; charset=ISO-8859-1".
    mux.HandleFunc("/json", func(w http.ResponseWriter, req *http.Request) {
        r.JSON(w, http.StatusOK, map[string]string{"hello": "json"})
    })

    // This will set the Content-Type header to "text/xml; charset=ISO-8859-1".
    mux.HandleFunc("/xml", func(w http.ResponseWriter, req *http.Request) {
        r.XML(w, http.StatusOK, ExampleXml{One: "hello", Two: "xml"})
    })

    // This will set the Content-Type header to "text/plain; charset=ISO-8859-1".
    mux.HandleFunc("/text", func(w http.ResponseWriter, req *http.Request) {
        r.Text(w, http.StatusOK, "Plain text here")
    })

    // This will set the Content-Type header to "text/html; charset=ISO-8859-1".
    mux.HandleFunc("/html", func(w http.ResponseWriter, req *http.Request) {
        // Assumes you have a template in ./templates called "example.tmpl"
        // $ mkdir -p templates && echo "<h1>Hello {{.}}.</h1>" > templates/example.tmpl
        r.HTML(w, http.StatusOK, "example", "World")
    })

    http.ListenAndServe("127.0.0.1:3000", mux)
}
~~~

### Error Handling

The rendering functions return any errors from the rendering engine.
By default, they will also write the error to the HTTP response and set the status code to 500. You can disable
this behavior so that you can handle errors yourself by setting
`Options.DisableHTTPErrorRendering: true`.

~~~go
r := render.New(render.Options{
  DisableHTTPErrorRendering: true,
})

//...

err := r.HTML(w, http.StatusOK, "example", "World")
if err != nil{
  http.Redirect(w, r, "/my-custom-500", http.StatusFound)
}
~~~

## Integration Examples

### [Echo](https://github.com/labstack/echo)
~~~ go
// main.go
package main

import (
    "io"
    "net/http"

    "github.com/labstack/echo"
    "github.com/unrolled/render"
)

type RenderWrapper struct { // We need to wrap the renderer because we need a different signature for echo.
    rnd *render.Render
}

func (r *RenderWrapper) Render(w io.Writer, name string, data interface{},c echo.Context) error {
    return r.rnd.HTML(w, 0, name, data) // The zero status code is overwritten by echo.
}

func main() {
    r := &RenderWrapper{render.New()}

    e := echo.New()

    e.Renderer = r

    e.GET("/", func(c echo.Context) error {
        return c.Render(http.StatusOK, "TemplateName", "TemplateData")
    })

    e.Logger.Fatal(e.Start("127.0.0.1:8080"))
}
~~~

### [Gin](https://github.com/gin-gonic/gin)
~~~ go
// main.go
package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
    "github.com/unrolled/render"
)

func main() {
    r := render.New(render.Options{
        IndentJSON: true,
    })

    router := gin.Default()

    router.GET("/", func(c *gin.Context) {
        r.JSON(c.Writer, http.StatusOK, map[string]string{"welcome": "This is rendered JSON!"})
    })

    router.Run("127.0.0.1:8080")
}
~~~

### [Goji](https://github.com/zenazn/goji)
~~~ go
// main.go
package main

import (
    "net/http"

    "github.com/zenazn/goji"
    "github.com/zenazn/goji/web"
    "github.com/unrolled/render"
)

func main() {
    r := render.New(render.Options{
        IndentJSON: true,
    })

    goji.Get("/", func(c web.C, w http.ResponseWriter, req *http.Request) {
        r.JSON(w, http.StatusOK, map[string]string{"welcome": "This is rendered JSON!"})
    })
    goji.Serve()  // Defaults to ":8000".
}
~~~

### [Negroni](https://github.com/codegangsta/negroni)
~~~ go
// main.go
package main

import (
    "net/http"

    "github.com/urfave/negroni"
    "github.com/unrolled/render"
)

func main() {
    r := render.New(render.Options{
        IndentJSON: true,
    })
    mux := http.NewServeMux()

    mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
        r.JSON(w, http.StatusOK, map[string]string{"welcome": "This is rendered JSON!"})
    })

    n := negroni.Classic()
    n.UseHandler(mux)
    n.Run("127.0.0.1:8080")
}
~~~

### [Traffic](https://github.com/pilu/traffic)
~~~ go
// main.go
package main

import (
    "net/http"

    "github.com/pilu/traffic"
    "github.com/unrolled/render"
)

func main() {
    r := render.New(render.Options{
        IndentJSON: true,
    })

    router := traffic.New()
    router.Get("/", func(w traffic.ResponseWriter, req *traffic.Request) {
        r.JSON(w, http.StatusOK, map[string]string{"welcome": "This is rendered JSON!"})
    })

    router.Run()  // Defaults to "127.0.0.1:3000".
}
~~~

render

# Fault

[![PkgGoDev](https://pkg.go.dev/badge/github.com/lingrino/go-fault)](https://pkg.go.dev/github.com/lingrino/go-fault) [![goreportcard](https://goreportcard.com/badge/github.com/lingrino/go-fault)](https://goreportcard.com/report/github.com/lingrino/go-fault)

The fault package provides go http middleware that makes it easy to inject faults into your service. Use the fault package to reject incoming requests, respond with an HTTP error, inject latency into a percentage of your requests, or inject any of your own custom faults.

## Features

The fault package works through [standard go http middleware](https://pkg.go.dev/net/http/?tab=doc#Handler). You first create an `Injector`, which is a middleware with the code to be run on injection. Then you wrap that `Injector` in a `Fault` which handles logic about when to run your `Injector`.

There are currently three kinds of injectors: `SlowInjector`, `ErrorInjector`, and `RejectInjector`. Each of these injectors can be configured through a `Fault` to run on a small percent of your requests. You can also configure the `Fault` to blocklist/allowlist certain paths.

See the usage section below for an example of how to get started and the [godoc](https://pkg.go.dev/github.com/lingrino/go-fault?tab=doc) for further documentation.

## Limitations

This package is useful for safely testing failure scenarios in go services that can make use of `net/http` handlers/middleware.

One common failure scenario that we cannot perfectly simulate is dropped requests. The `RejectInjector` will always return immediately to the user, but in many cases requests can be dropped without ever sending a response. The best way to simulate this scenario using the fault package is to chain a `SlowInjector` with a very long wait time in front of an eventual `RejectInjector`.

## Status

This project is in a stable and supported state. There are no plans to introduce significant new features however we welcome and encourage any ideas and contributions from the community. Contributions should follow the guidelines in our [CONTRIBUTING.md](.github/CONTRIBUTING.md).

## Usage

```go
// main.go
package main

import (
        "net/http"
        "time"

        "github.com/lingrino/go-fault"
)

var mainHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        http.Error(w, http.StatusText(http.StatusOK), http.StatusOK)
})

func main() {
        slowInjector, _ := fault.NewSlowInjector(time.Second * 2)
        slowFault, _ := fault.NewFault(slowInjector,
                fault.WithEnabled(true),
                fault.WithParticipation(0.25),
                fault.WithPathBlocklist([]string{"/ping", "/health"}),
        )

        // Add 2 seconds of latency to 25% of our requests
        handlerChain := slowFault.Handler(mainHandler)

        http.ListenAndServe("127.0.0.1:3000", handlerChain)
}
```

## Development

This package uses standard go tooling for testing and development. The [go](https://golang.org/dl/) language is all you need to contribute. Tests use the popular [testify/assert](https://github.com/stretchr/testify/) which will be downloaded automatically the first time you run tests. GitHub Actions will also run a linter using [golangci-lint](https://github.com/golangci/golangci-lint) after you push. You can also download the linter and use `golangci-lint run` to run locally.

## Testing

The fault package has extensive tests that are run in [GitHub Actions](https://github.com/lingrino/go-fault/actions?query=workflow%3AValidate) on every push. Code coverage is 100% and is published as an artifact on every Actions run.

You can also run tests locally:

```shell
$ go test -v -cover -race ./...
[...]
PASS
coverage: 100.0% of statements
ok      github.com/lingrino/go-fault      0.575s
```

## Benchmarks

The fault package is safe to leave implemented even when you are not running a fault injection. While the fault is disabled there is negligible performance degradation compared to removing the package from the request path. While enabled there may be minor performance differences, but this will only be the case *while you are already injecting faults.*

Benchmarks are provided to compare without faults, with faults disabled, and with faults enabled. Benchmarks are uploaded as artifacts in GitHub Actions and you can download them from any [Validate Workflow](https://github.com/lingrino/go-fault/actions?query=workflow%3AValidate).

You can also run benchmarks locally (example output):

```shell
$ go test -run=XXX -bench=.
goos: darwin
goarch: amd64
pkg: github.com/lingrino/go-fault
BenchmarkNoFault-8                        684826              1734 ns/op
BenchmarkFaultDisabled-8                  675291              1771 ns/op
BenchmarkFaultErrorZeroPercent-8          667903              1823 ns/op
BenchmarkFaultError100Percent-8           663661              1833 ns/op
PASS
ok      github.com/lingrino/go-fault      8.814s
```

## Maintainers

[@lingrino](https://github.com/lingrino)

### Contributors

[@mrfaizal](https://github.com/mrfaizal)
[@vroldanbet](https://github.com/vroldanbet)
[@fatih](https://github.com/fatih)

## License

This project is licensed under the [MIT License](LICENSE.md).


go-fault

# Limiter

[![Documentation][godoc-img]][godoc-url]
![License][license-img]
[![Build Status][circle-img]][circle-url]
[![Go Report Card][goreport-img]][goreport-url]

_Dead simple rate limit middleware for Go._

- Simple API
- "Store" approach for backend
- Redis support (but not tied too)
- Middlewares: HTTP, [FastHTTP][6] and [Gin][4]

## Installation

Using [Go Modules](https://github.com/golang/go/wiki/Modules)

```bash
$ go get github.com/ulule/limiter/v3@v3.11.2
```

## Usage

In five steps:

- Create a `limiter.Rate` instance _(the number of requests per period)_
- Create a `limiter.Store` instance _(see [Redis](https://github.com/ulule/limiter/blob/master/drivers/store/redis/store.go) or [In-Memory](https://github.com/ulule/limiter/blob/master/drivers/store/memory/store.go))_
- Create a `limiter.Limiter` instance that takes store and rate instances as arguments
- Create a middleware instance using the middleware of your choice
- Give the limiter instance to your middleware initializer

**Example:**

```go
// Create a rate with the given limit (number of requests) for the given
// period (a time.Duration of your choice).
import "github.com/ulule/limiter/v3"

rate := limiter.Rate{
    Period: 1 * time.Hour,
    Limit:  1000,
}

// You can also use the simplified format "<limit>-<period>"", with the given
// periods:
//
// * "S": second
// * "M": minute
// * "H": hour
// * "D": day
//
// Examples:
//
// * 5 reqs/second: "5-S"
// * 10 reqs/minute: "10-M"
// * 1000 reqs/hour: "1000-H"
// * 2000 reqs/day: "2000-D"
//
rate, err := limiter.NewRateFromFormatted("1000-H")
if err != nil {
    panic(err)
}

// Then, create a store. Here, we use the bundled Redis store. Any store
// compliant to limiter.Store interface will do the job. The defaults are
// "limiter" as Redis key prefix and a maximum of 3 retries for the key under
// race condition.
import "github.com/ulule/limiter/v3/drivers/store/redis"

store, err := redis.NewStore(client)
if err != nil {
    panic(err)
}

// Alternatively, you can pass options to the store with the "WithOptions"
// function. For example, for Redis store:
import "github.com/ulule/limiter/v3/drivers/store/redis"

store, err := redis.NewStoreWithOptions(pool, limiter.StoreOptions{
    Prefix:   "your_own_prefix",
})
if err != nil {
    panic(err)
}

// Or use a in-memory store with a goroutine which clears expired keys.
import "github.com/ulule/limiter/v3/drivers/store/memory"

store := memory.NewStore()

// Then, create the limiter instance which takes the store and the rate as arguments.
// Now, you can give this instance to any supported middleware.
instance := limiter.New(store, rate)

// Alternatively, you can pass options to the limiter instance with several options.
instance := limiter.New(store, rate, limiter.WithClientIPHeader("True-Client-IP"), limiter.WithIPv6Mask(mask))

// Finally, give the limiter instance to your middleware initializer.
import "github.com/ulule/limiter/v3/drivers/middleware/stdlib"

middleware := stdlib.NewMiddleware(instance)
```

See middleware examples:

- [HTTP](https://github.com/ulule/limiter-examples/tree/master/http/main.go)
- [Gin](https://github.com/ulule/limiter-examples/tree/master/gin/main.go)
- [Beego](https://github.com/ulule/limiter-examples/blob/master//beego/main.go)
- [Chi](https://github.com/ulule/limiter-examples/tree/master/chi/main.go)
- [Echo](https://github.com/ulule/limiter-examples/tree/master/echo/main.go)
- [Fasthttp](https://github.com/ulule/limiter-examples/tree/master/fasthttp/main.go)

## How it works

The ip address of the request is used as a key in the store.

If the key does not exist in the store we set a default
value with an expiration period.

You will find two stores:

- Redis: rely on [TTL](http://redis.io/commands/ttl) and incrementing the rate limit on each request.
- In-Memory: rely on a fork of [go-cache](https://github.com/patrickmn/go-cache) with a goroutine to clear expired keys using a default interval.

When the limit is reached, a `429` HTTP status code is sent.

## Limiter behind a reverse proxy

### Introduction

If your limiter is behind a reverse proxy, it could be difficult to obtain the "real" client IP.

Some reverse proxies, like AWS ALB, lets all header values through that it doesn't set itself.
Like for example, `True-Client-IP` and `X-Real-IP`.
Similarly, `X-Forwarded-For` is a list of comma-separated IPs that gets appended to by each traversed proxy.
The idea is that the first IP _(added by the first proxy)_ is the true client IP. Each subsequent IP is another proxy along the path.

An attacker can spoof either of those headers, which could be reported as a client IP.

By default, limiter doesn't trust any of those headers: you have to explicitly enable them in order to use them.
If you enable them, **you must always be aware** that any header added by any _(reverse)_ proxy not controlled
by you **are completely unreliable.**

### X-Forwarded-For

For example, if you make this request to your load balancer:
```bash
curl -X POST https://example.com/login -H "X-Forwarded-For: 1.2.3.4, 11.22.33.44"
```

And your server behind the load balancer obtain this:
```
X-Forwarded-For: 1.2.3.4, 11.22.33.44, <actual client IP>
```

That's mean you can't use `X-Forwarded-For` header, because it's **unreliable** and **untrustworthy**.
So keep `TrustForwardHeader` disabled in your limiter option.

However, if you have configured your reverse proxy to always remove/overwrite `X-Forwarded-For` and/or `X-Real-IP` headers
so that if you execute this _(same)_ request:
```bash
curl -X POST https://example.com/login -H "X-Forwarded-For: 1.2.3.4, 11.22.33.44"
```

And your server behind the load balancer obtain this:
```
X-Forwarded-For: <actual client IP>
```

Then, you can enable `TrustForwardHeader` in your limiter option.

### Custom header

Many CDN and Cloud providers add a custom header to define the client IP. Like for example, this non exhaustive list:

* `Fastly-Client-IP` from Fastly
* `CF-Connecting-IP` from Cloudflare
* `X-Azure-ClientIP` from Azure

You can use these headers using `ClientIPHeader` in your limiter option.

### None of the above

If none of the above solution are working, please use a custom `KeyGetter` in your middleware.

You can use this excellent article to help you define the best strategy depending on your network topology and your security need:
https://adam-p.ca/blog/2022/03/x-forwarded-for/

If you have any idea/suggestions on how we could simplify this steps, don't hesitate to raise an issue.
We would like some feedback on how we could implement this steps in the Limiter API.

Thank you.

## Why Yet Another Package

You could ask us: why yet another rate limit package?

Because existing packages did not suit our needs.

We tried a lot of alternatives:

1. [Throttled][1]. This package uses the generic cell-rate algorithm. To cite the
   documentation: _"The algorithm has been slightly modified from its usual form to
   support limiting with an additional quantity parameter, such as for limiting the
   number of bytes uploaded"_. It is brilliant in term of algorithm but
   documentation is quite unclear at the moment, we don't need _burst_ feature for
   now, impossible to get a correct `After-Retry` (when limit exceeds, we can still
   make a few requests, because of the max burst) and it only supports `http.Handler`
   middleware (we use [Gin][4]). Currently, we only need to return `429`
   and `X-Ratelimit-*` headers for `n reqs/duration`.

2. [Speedbump][3]. Good package but maybe too lightweight. No `Reset` support,
   only one middleware for [Gin][4] framework and too Redis-coupled. We rather
   prefer to use a "store" approach.

3. [Tollbooth][5]. Good one too but does both too much and too little. It limits by
   remote IP, path, methods, custom headers and basic auth usernames... but does not
   provide any Redis support (only _in-memory_) and a ready-to-go middleware that sets
   `X-Ratelimit-*` headers. `tollbooth.LimitByRequest(limiter, r)` only returns an HTTP
   code.

4. [ratelimit][2]. Probably the closer to our needs but, once again, too
   lightweight, no middleware available and not active (last commit was in August
   2014). Some parts of code (Redis) comes from this project. It should deserve much
   more love.

There are other many packages on GitHub but most are either too lightweight, too
old (only support old Go versions) or unmaintained. So that's why we decided to
create yet another one.

## Contributing

- Ping us on twitter:
  - [@oibafsellig](https://twitter.com/oibafsellig)
  - [@thoas](https://twitter.com/thoas)
  - [@novln\_](https://twitter.com/novln_)
- Fork the [project](https://github.com/ulule/limiter)
- Fix [bugs](https://github.com/ulule/limiter/issues)

Don't hesitate ;)

[1]: https://github.com/throttled/throttled
[2]: https://github.com/r8k/ratelimit
[3]: https://github.com/etcinit/speedbump
[4]: https://github.com/gin-gonic/gin
[5]: https://github.com/didip/tollbooth
[6]: https://github.com/valyala/fasthttp
[godoc-url]: https://pkg.go.dev/github.com/ulule/limiter/v3
[godoc-img]: https://pkg.go.dev/badge/github.com/ulule/limiter/v3
[license-img]: https://img.shields.io/badge/license-MIT-blue.svg
[goreport-url]: https://goreportcard.com/report/github.com/ulule/limiter
[goreport-img]: https://goreportcard.com/badge/github.com/ulule/limiter
[circle-url]: https://circleci.com/gh/ulule/limiter/tree/master
[circle-img]: https://circleci.com/gh/ulule/limiter.svg?style=shield&circle-token=baf62ec320dd871b3a4a7e67fa99530fbc877c99


Limiter

Go middleware for monetizing APIs on a per-request basis with the Lightning Network (Bitcoin)

ln-paywall
==========

[![GoDoc](http://www.godoc.org/github.com/philippgille/ln-paywall/wall?status.svg)](http://www.godoc.org/github.com/philippgille/ln-paywall/wall) [![Build Status](https://travis-ci.org/philippgille/ln-paywall.svg?branch=master)](https://travis-ci.org/philippgille/ln-paywall) [![Go Report Card](https://goreportcard.com/badge/github.com/philippgille/ln-paywall)](https://goreportcard.com/report/github.com/philippgille/ln-paywall) [![GitHub Releases](https://img.shields.io/github/release/philippgille/ln-paywall.svg)](https://github.com/philippgille/ln-paywall/releases)

Go middleware for monetizing your API on a per-request basis with Bitcoin and Lightning ⚡️

Middlewares for:

- [X] [net/http](https://golang.org/pkg/net/http/) `HandlerFunc`
- [X] [net/http](https://golang.org/pkg/net/http/) `Handler`
	- Compatible with routers like [gorilla/mux](https://github.com/gorilla/mux), [httprouter](https://github.com/julienschmidt/httprouter) and [chi](https://github.com/go-chi/chi)
- [X] [Gin](https://github.com/gin-gonic/gin)
- [X] [Echo](https://github.com/labstack/echo)

A client package exists as well to make *consuming* LN-paywalled APIs extremely easy (you just use it like the standard Go `http.Client` and the payment handling is done in the background).

An API gateway is on the roadmap as well, which you can use to monetize your API that's written in *any* language, not just in Go.

Contents
--------

- [Purpose](#purpose)
- [How it works](#how-it-works)
- [Prerequisites](#prerequisites)
- [Usage](#usage)
	- [Middleware](#middleware)
		- [List of examples](#list-of-examples)
	- [Client](#client)
- [Related projects](#related-projects)

Purpose
-------

Until the rise of cryptocurrencies, if you wanted to monetize your API (set up a paywall), you had to:

1. Use a centralized service (like PayPal)
    - Can shut you down any time
    - High fees
    - Your API users need an account
    - Can be hacked
2. Keep track of your API users (keep accounts and their API keys in some database)
    - Privacy concerns
    - Data breaches / leaks
3. Charge for a bunch of requests, like 10.000 at a time, because real per-request payments weren't possible

With cryptocurrencies in general some of those problems were solved, but with long confirmation times and high per-transaction fees a real per-request billing was still not feasable.

But then came the [Lightning Network](https://lightning.network/), an implementation of routed payment channels, which enables *real* **near-instant microtransactions** with **extremely low fees**, which cryptocurrencies have long promised, but never delivered. It's a *second layer* on top of existing cryptocurrencies like Bitcoin that scales far beyond the limitations of the underlying blockchain.

`ln-paywall` makes it easy to set up an API paywall for payments over the Lightning Network.

How it works
------------

With `ln-paywall` you can simply use one of the provided middlewares in your Go web service to have your web service do two things:

1. The first request gets rejected with the `402 Payment Required` HTTP status, a `Content-Type: application/vnd.lightning.bolt11` header and a Lightning ([BOLT-11](https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md)-conforming) invoice in the body
2. The second request must contain a `X-Preimage` header with the preimage of the paid Lightning invoice (hex encoded). The middleware checks if 1) the invoice was paid and 2) not already used for a previous request. If both preconditions are met, it continues to the next middleware or final request handler.

Prerequisites
-------------

There are currently two prerequisites:

1. A running Lightning Network node. The middleware connects to the node for example to create invoices for a request. The `ln` package currently provides factory functions for the following LN implementations:
	- [X] [lnd](https://github.com/lightningnetwork/lnd)
		- Requires the node to listen to gRPC connections
		- If you don't run it locally, it needs to listen to connections from external machines (so for example on 0.0.0.0 instead of localhost) and has the TLS certificate configured to include the external IP address of the node.
	- [X] [c-lightning](https://github.com/ElementsProject/lightning) with [Lightning Charge](https://github.com/ElementsProject/lightning-charge)
		- Run for example with Docker: ``docker run -d -u `id -u` -v `pwd`/data:/data -p 9112:9112 -e API_TOKEN=secret shesek/lightning-charge``
		- Vanilla c-lightning (without Lightning Charge) won't be supported as long as c-lightning's RPC API only works via Unix socket and cannot be used as a remote server, because this is not a good fit for potentially multiple web service instances elastically scaled across a cluster of host machines
	- [ ] [eclair](https://github.com/ACINQ/eclair) (not implemented yet - [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) )
	- Roll your own!
		- Just implement the simple `wall.LNClient` interface (only two methods!)
2. A supported storage mechanism. It's used to cache preimages that have been used as a payment for an API call, so that a user can't do multiple requests with the same preimage of a settled Lightning payment. The `wall` package currently provides factory functions for the following storages:
	- [X] A simple Go map
		- The fastest option, but 1) can't be used across horizontally scaled service instances and 2) doesn't persist data, so when you restart your server, users can re-use old preimages
	- [X] [bbolt](https://github.com/coreos/bbolt) - a fork of [Bolt](https://github.com/boltdb/bolt) maintained by CoreOS
		- Very fast, doesn't require any remote or local TCP connections and persists the data, but can't be used across horizontally scaled service instances because it's file-based. Production-ready for single-instance web services though.
	- [X] [Redis](https://redis.io/)
		- Although the slowest of these options, still fast and most suited for popular web services: Requires a remote or local TCP connection and some administration, but allows data persistency and can even be used with a horizontally scaled web service
		- Run for example with Docker: `docker run -d -p 6379:6379 redis`
			- Note: In production you should use a configuration with password (check out [`bitnami/redis`](https://hub.docker.com/r/bitnami/redis/) which makes that easy)!
	- [ ] [groupcache](https://github.com/golang/groupcache) (not implemented yet - [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) )
	- Roll your own!
		- Just implement the simple `wall.StorageClient` interface (only two methods!)

Usage
-----

[![GoDoc](http://www.godoc.org/github.com/philippgille/ln-paywall?status.svg)](http://www.godoc.org/github.com/philippgille/ln-paywall)

Get the package with `go get -u github.com/philippgille/ln-paywall/...`.

We strongly encourage you to use vendoring, because as long as `ln-paywall` is version `0.x`, breaking changes may be introduced in new versions, including changes to the package name / import path. The project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html) and all notable changes to this project are documented in [RELEASES.md](https://github.com/philippgille/ln-paywall/blob/master/RELEASES.md).

### Middleware

The best way to see how to use `ln-paywall` is by example. In the below examples we create a web service that responds to requests to `/ping` with "pong", using Gin as the web framework.

```Go
package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
	"github.com/philippgille/ln-paywall/ln"
	"github.com/philippgille/ln-paywall/storage"
	"github.com/philippgille/ln-paywall/wall"
)

func main() {
	r := gin.Default()

	// Configure middleware
	invoiceOptions := wall.DefaultInvoiceOptions // Price: 1 Satoshi; Memo: "API call"
	lndOptions := ln.DefaultLNDoptions           // Address: "localhost:10009", CertFile: "tls.cert", MacaroonFile: "invoice.macaroon"
	storageClient := storage.NewGoMap()          // Local in-memory cache
	lnClient, err := ln.NewLNDclient(lndOptions)
	if err != nil {
		panic(err)
	}
	// Use middleware
	r.Use(wall.NewGinMiddleware(invoiceOptions, lnClient, storageClient))

	r.GET("/ping", func(c *gin.Context) {
		c.String(http.StatusOK, "pong")
	})

	r.Run() // Listen and serve on 0.0.0.0:8080
}
```

This is just the most basic example. See the list of examples below for examples with other web frameworks / routers / just the stdlib, as well as for a more complex and useful example.

#### List of examples

Follow the links to the example code files.

Simple examples to show the use for the different web frameworks / routers / just the stdlib:

- [Gin](examples/ping/gin/main.go)
- [Gin (with c-lightning + Lightning Charge as backend)](examples/ping/gin-charge/main.go)
- [gorilla/mux](examples/ping/gorilla-mux/main.go)
- [net/http HandlerFunc](examples/ping/handlerfunc/main.go)
- [Echo](examples/ping/echo/main.go)

More complex and useful example:

- [QR code generation API using Gin](examples/qr-code/main.go)
	- Ready-to-use Docker image: [https://hub.docker.com/r/philippgille/qr-code/](https://hub.docker.com/r/philippgille/qr-code/)
	- Try out the demo deployed on [https://lightning.ws](https://lightning.ws)

### Client

```Go
package main

import (
	"fmt"
	"io/ioutil"

	"github.com/philippgille/ln-paywall/ln"
	"github.com/philippgille/ln-paywall/pay"
)

func main() {
	// Set up client
	lndOptions := ln.LNDoptions{ // Default address: "localhost:10009", CertFile: "tls.cert"
		MacaroonFile: "admin.macaroon", // admin.macaroon is required for making payments
	}
	lnClient, err := ln.NewLNDclient(lndOptions)
	if err != nil {
		panic(err)
	}
	client := pay.NewClient(nil, lnClient) // Uses http.DefaultClient if no http.Client is passed

	// Send request to an ln-paywalled API
	res, err := client.Get("http://localhost:8080/ping")
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	// Print response body
	resBody, err := ioutil.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(resBody))
}
```

You can also view this example [here](examples/client/main.go).

Related Projects
----------------

- [https://github.com/ElementsProject/paypercall](https://github.com/ElementsProject/paypercall)
    - Middleware for the JavaScript web framework [Express](https://expressjs.com/)
    - Can also act as reverse proxy for web services that aren't written in JavaScript
    - Payment: Lightning Network
    - Backend: c-lightning only (no lnd)
- [https://github.com/interledgerjs/koa-web-monetization](https://github.com/interledgerjs/koa-web-monetization)
    - Middleware for the JavaScript web framework [Koa](https://koajs.com/)
    - Payment: Interledger
- [https://moonbanking.com/api](https://moonbanking.com/api)
    - API that *uses* a similar functionality, not *providing* it
- [https://www.coinbee.io/](https://www.coinbee.io/)
	- Paid service for Bitcoin paywalls (no Lightning)
	- Looks like its meant for websites only, not APIs, because the browser session is involved


ln-paywall

Miscellaneous HTTP middleware features: idiomatic error return from handlers; receive/respond with JSON data; request tracing; and more

# Mid - Assorted middleware for HTTP services.

[![Go Reference](https://pkg.go.dev/badge/github.com/bobg/mid.svg)](https://pkg.go.dev/github.com/bobg/mid)
[![Go Report Card](https://goreportcard.com/badge/github.com/bobg/mid)](https://goreportcard.com/report/github.com/bobg/mid)
[![Tests](https://github.com/bobg/mid/actions/workflows/go.yml/badge.svg)](https://github.com/bobg/mid/actions/workflows/go.yml)
[![Coverage Status](https://coveralls.io/repos/github/bobg/mid/badge.svg?branch=master)](https://coveralls.io/github/bobg/mid?branch=master)

This is mid,
a collection of useful middleware for HTTP services.

## Err

The `Err` function turns a `func(http.ResponseWriter, *http.Request) error`
into an `http.Handler`,
allowing handler functions to return errors in a more natural fashion.
These errors result in the handler producing an HTTP 500 status code,
but `CodeErr` and `Responder` allow you to control this behavior
(see below).
A `nil` return produces a `200`,
or a `204` (“no content”) if no bytes were written to the response object.

Usage:

```go
func main() {
  http.Handle("/foo", Err(fooHandler))
  http.ListenAndServe(":8080", nil)
}

func fooHandler(w http.ResponseWriter, req *http.Request) error {
  if x := req.FormValue("x"); x != "secret password" {
    return CodeErr{C: http.StatusUnauthorized}
  }
  fmt.Fprintf(w, "You know the secret password")
  return nil
}
```

## JSON

The `JSON` function turns a `func(context.Context, X) (Y, error)`
into an `http.Handler`,
where `X` is the type of a parameter into which the HTTP request body is automatically JSON-unmarshaled,
and `Y` is the type of a result that is automatically JSON-marshaled into the HTTP response.
Any error is handled as with `Err`
(see above).
All parts of the `func` signature are optional:
the `context.Context` parameter,
the `X` parameter,
the `Y` result,
and the `error` result.

Usage:

```go
func main() {
  // Parses the request body as a JSON-encoded array of strings,
  // then sorts, re-encodes, and returns that array.
  http.Handle("/bar", JSON(barHandler))

  http.ListenAndServe(":8080", nil)
}

func barHandler(inp []string) []string {
  sort.Strings(inp)
  return inp
}
```

## CodeErr and Responder

`CodeErr` is an `error` type suitable for returning from `Err`- and `JSON`-wrapped handlers that can control the HTTP status code that gets returned.
It contains an HTTP status code field and a nested `error`.

`Responder` is an interface
(implemented by `CodeErr`)
that allows an error type to control how `Err`- and `JSON`-wrapped handlers respond to the pending request.

## ResponseWrapper

`ResponseWrapper` is an `http.ResponseWriter` that wraps a nested `http.ResponseWriter` and also records the status code and number of bytes sent in the response.

## Trace

The `Trace` function wraps an `http.Handler` and decorates the `context.Context` in its `*http.Request` with any “trace ID” string found in the request header.

## Log

The `Log` function wraps an `http.Handler` with a function that writes a simple log line on the way into and out of the handler.
The log line includes any “trace ID” found in the request’s `context.Context`.


Middleware for Gin framework with logging, metrics, auth, tracing etc

rk-gin

Middleware for gRPC with logging, metrics, auth, tracing etc

rk-grpc

[![GoDoc](https://godoc.org/github.com/didip/tollbooth?status.svg)](http://godoc.org/github.com/didip/tollbooth)
[![license](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](https://raw.githubusercontent.com/didip/tollbooth/master/LICENSE)

## Tollbooth

This is a generic middleware to rate-limit HTTP requests.

**NOTE 1:** This library is considered finished.

**NOTE 2:** Major version changes are backward-incompatible. `v2.0.0` streamlines the ugliness of the old API.

## Versions

**v1.0.0:** This version maintains the old API but all the thirdparty modules are moved to their own repo.

**v2.x.x:** Brand-new API for the sake of code cleanup, thread safety, & auto-expiring data structures.

**v3.x.x:** Apparently we have been using golang.org/x/time/rate incorrectly. See issue #48. It always limits X number per 1 second. The time duration is not changeable, so it does not make sense to pass TTL to tollbooth.

**v4.x.x:** Float64 for max requests per second

**v5.x.x:** go.mod and go.sum

**v6.x.x:** Replaced `go-cache` with `github.com/go-pkgz/expirable-cache` because `go-cache` leaks goroutines.

**v7.x.x:** Replaced `time/rate` with `embedded time/rate` so that we can support more rate limit headers.

**v8.x.x:** Address `RemoteIP` vulnerability concern by replacing `SetIPLookups` with `SetIPLookup`, an explicit way to pick the IP address. New `HTTPMiddleware` function which is compatible with standard routers.

## Five Minute Tutorial

```go
package main

import (
	"net/http"

	"github.com/didip/tollbooth/v8/limiter"
)

func HelloHandler(w http.ResponseWriter, req *http.Request) {
	w.Write([]byte("Hello, World!"))
}

func main() {
	// Create a request limiter per handler.
	lmt := tollbooth.NewLimiter(1, nil)

	// New in version >= 8, you must explicitly define how to pick the IP address.
	lmt.SetIPLookup(limiter.IPLookup{
		Name:           "X-Real-IP",
		IndexFromRight: 0,
	})

	// New in version >= 8, HTTPMiddleware is a standard router compatible alternative to the previously used LimitFuncHandler.
	http.Handle("/", tollbooth.HTTPMiddleware(lmt)(http.HandlerFunc(HelloHandler)))
	// Old syntax:
	// http.Handle("/", tollbooth.LimitFuncHandler(lmt, HelloHandler))

	http.ListenAndServe(":12345", nil)
}

```

## Features

1. Rate-limit by request's remote IP, path, methods, custom headers, & basic auth usernames.

    ```go
    import (
        "time"

        "github.com/didip/tollbooth/v8"
        "github.com/didip/tollbooth/v8/limiter"
    )

    lmt := tollbooth.NewLimiter(1, nil)

    // or create a limiter with expirable token buckets
    // This setting means:
    // create a 1 request/second limiter and
    // every token bucket in it will expire 1 hour after it was initially set.
    lmt = tollbooth.NewLimiter(1, &limiter.ExpirableOptions{DefaultExpirationTTL: time.Hour})

    // New in version >= 8, you must explicitly define how to pick the IP address.
    // If IP address cannot be found, rate limiter will not be activated.
    lmt.SetIPLookup(limiter.IPLookup{
        // The name of lookup method.
        // Possible options are: RemoteAddr, X-Forwarded-For, X-Real-IP, CF-Connecting-IP
        // All other headers are considered unknown and will be ignored.
        Name: "X-Real-IP",

        // The index position to pick the ip address from a comma separated list.
        // The index goes from right to left.
        //
        // When there are multiple of the same headers,
        // we will concat them together in the order of first to last seen.
        // And then we pick the IP using this index position.
        IndexFromRight: 0,
    })

    // In version >= 8, lmt.SetIPLookups and lmt.GetIPLookups are removed.

    // Limit only GET and POST requests.
    lmt.SetMethods([]string{"GET", "POST"})

    // Limit based on basic auth usernames.
    // You add them on-load, or later as you handle requests.
    lmt.SetBasicAuthUsers([]string{"bob", "jane", "didip", "vip"})
    // You can remove them later as well.
    lmt.RemoveBasicAuthUsers([]string{"vip"})

    // Limit request headers containing certain values.
    // You add them on-load, or later as you handle requests.
    lmt.SetHeader("X-Access-Token", []string{"abc123", "xyz098"})
    // You can remove all entries at once.
    lmt.RemoveHeader("X-Access-Token")
    // Or remove specific ones.
    lmt.RemoveHeaderEntries("X-Access-Token", []string{"limitless-token"})

    // By the way, the setters are chainable. Example:
    lmt.SetMethods([]string{"GET", "POST"}).
        SetBasicAuthUsers([]string{"sansa"}).
        SetBasicAuthUsers([]string{"tyrion"})
    ```

2. Compose your own middleware by using `LimitByKeys()`.

3. Header entries and basic auth users can expire over time (to conserve memory).

    ```go
    import "time"

    lmt := tollbooth.NewLimiter(1, nil)

    // Set a custom expiration TTL for token bucket.
    lmt.SetTokenBucketExpirationTTL(time.Hour)

    // Set a custom expiration TTL for basic auth users.
    lmt.SetBasicAuthExpirationTTL(time.Hour)

    // Set a custom expiration TTL for header entries.
    lmt.SetHeaderEntryExpirationTTL(time.Hour)
    ```

4. Upon rejection, the following HTTP response headers are available to users:

    * `X-Rate-Limit-Limit` The maximum request limit.

    * `X-Rate-Limit-Duration` The rate-limiter duration.

    * `X-Rate-Limit-Request-Forwarded-For` The rejected request `X-Forwarded-For`.

    * `X-Rate-Limit-Request-Remote-Addr` The rejected request `RemoteAddr`.

   Upon both success and rejection [RateLimit](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers) headers are sent:

   * `RateLimit-Limit` The maximum request limit within the time window (1s).

   * `RateLimit-Reset` The rate-limiter time window duration in seconds (always 1s).

   * `RateLimit-Remaining` The remaining tokens.

5. Customize your own message or function when limit is reached.

    ```go
    lmt := tollbooth.NewLimiter(1, nil)

    // New in version >= 8, you must explicitly define how to pick the IP address.
    lmt.SetIPLookup(limiter.IPLookup{
        Name:           "X-Forwarded-For",
        IndexFromRight: 0,
    })

    // Set a custom message.
    lmt.SetMessage("You have reached maximum request limit.")

    // Set a custom content-type.
    lmt.SetMessageContentType("text/plain; charset=utf-8")

    // Set a custom function for rejection.
    lmt.SetOnLimitReached(func(w http.ResponseWriter, r *http.Request) { fmt.Println("A request was rejected") })
    ```

6. Tollbooth does not require external storage since it uses an algorithm called [Token Bucket](http://en.wikipedia.org/wiki/Token_bucket) [(Go library: golang.org/x/time/rate)](https://godoc.org/golang.org/x/time/rate).

## Other Web Frameworks

Sometimes, other frameworks require a little bit of shim to use Tollbooth. These shims below are contributed by the community, so I make no promises on how well they work. The one I am familiar with are: Chi, Gin, and Negroni.

* [Chi](https://github.com/didip/tollbooth_chi)

* [Echo](https://github.com/didip/tollbooth_echo)

* [FastHTTP](https://github.com/didip/tollbooth_fasthttp)

* [Gin](https://github.com/didip/tollbooth_gin)

* [GoRestful](https://github.com/didip/tollbooth_gorestful)

* [HTTPRouter](https://github.com/didip/tollbooth_httprouter)

* [Iris](https://github.com/didip/tollbooth_iris)

* [Negroni](https://github.com/didip/tollbooth_negroni)

## My other Go libraries

* [ErrStack](https://github.com/didip/errstack): A small library to combine errors and also display filename and line number.

* [Stopwatch](https://github.com/didip/stopwatch): A small library to measure latency of things. Useful if you want to report latency data to Graphite.

* [LaborUnion](https://github.com/didip/laborunion): A dynamic worker pool library.

* [Gomet](https://github.com/didip/gomet): Simple HTTP client & server long poll library for Go. Useful for receiving live updates without needing Websocket.

## Contributions

Before sending a PR with code changes, please make sure altered code is covered with tests which are passing, and that golangci-lint shows no errors.

To check the linter output, [install it](https://golangci-lint.run/usage/install/#local-installation) and then run `golangci-lint run` in the root directory of the repository.


Tollbooth

http.Handler wrapper catenation (same API as "chain")

# catena

    go get -u github.com/codemodus/catena

Package catena aides gRPC interceptor catenation.

## Usage

```go
type UnaryServerCatena
    func NewUnaryServerCatena(is ...grpc.UnaryServerInterceptor) *UnaryServerCatena
    func (c *UnaryServerCatena) Append(is ...grpc.UnaryServerInterceptor) *UnaryServerCatena
    func (c *UnaryServerCatena) Copy(catena *UnaryServerCatena)
    func (c *UnaryServerCatena) Interceptor() grpc.UnaryServerInterceptor
    func (c *UnaryServerCatena) Merge(cs ...*UnaryServerCatena) *UnaryServerCatena
    func (c *UnaryServerCatena) ServerOption() grpc.ServerOption
```

### Setup

```go
soon...
```

## More Info

## Documentation

View the [GoDoc](http://godoc.org/github.com/codemodus/catena)


catena

Go package that handles HTML, JSON, XML and etc. responses. Useful for RESTful APIs

# gores 

[![Build Status](https://travis-ci.org/alioygur/gores.svg?branch=master)](https://travis-ci.org/alioygur/gores) 
[![GoDoc](https://godoc.org/github.com/alioygur/gores?status.svg)](https://godoc.org/github.com/alioygur/gores)
[![Go Report Card](https://goreportcard.com/badge/github.com/alioygur/gores)](https://goreportcard.com/report/github.com/alioygur/gores)

http response utility library for Go

this package is very small and lightweight, useful for RESTful APIs.


## installation

`go get github.com/alioygur/gores`

## requirements

gores library requires Go version `>=1.7`

## usage

```go
package main

import (
	"log"
	"net/http"

	"github.com/alioygur/gores"
)

type User struct {
	Name  string
	Email string
	Age   int
}

func main() {
	// Plain text response
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		gores.String(w, http.StatusOK, "Hello World")
	})

	// HTML response
	http.HandleFunc("/html", func(w http.ResponseWriter, r *http.Request) {
		gores.HTML(w, http.StatusOK, "<h1>Hello World</h1>")
	})

	// JSON response
	http.HandleFunc("/json", func(w http.ResponseWriter, r *http.Request) {
		user := User{Name: "Ali", Email: "ali@example.com", Age: 28}
		gores.JSON(w, http.StatusOK, user)
	})

	// File response
	http.HandleFunc("/file", func(w http.ResponseWriter, r *http.Request) {
		err := gores.File(w, r, "./path/to/file.html")

		if err != nil {
			log.Println(err.Error())
		}
	})

	// Download file
	http.HandleFunc("/download-file", func(w http.ResponseWriter, r *http.Request) {
		err := gores.Download(w, r, "./path/to/file.pdf", "example.pdf")

		if err != nil {
			log.Println(err.Error())
		}
	})

	// No content
	http.HandleFunc("/no-content", func(w http.ResponseWriter, r *http.Request) {
		gores.NoContent(w)
	})

	// Error response
	http.HandleFunc("/error", func(w http.ResponseWriter, r *http.Request) {
		gores.Error(w, http.StatusInternalServerError, http.StatusText(http.StatusInternalServerError))
	})

	err := http.ListenAndServe(":8000", nil)
	if err != nil {
		log.Fatal("ListenAndServe: ", err)
	}
}
```

for more documentation [godoc](https://godoc.org/github.com/alioygur/gores)

## Contribute

**Use issues for everything**

- Report problems
- Discuss before sending a pull request
- Suggest new features/recipes
- Improve/fix documentation

## Thanks & Authors

I use code/got inspiration from these excellent libraries:

- [labstack/echo](https://github.com/labstack/echo) micro web framework


gores

Minimalist net/http middleware for golang

interpose
=========

Interpose is a minimalist net/http middleware framework for golang. It uses 
`http.Handler` as its core unit of functionality, minimizing complexity
and maximizing inter-operability with other middleware frameworks.

All that it does is manage middleware. It comes with nothing baked in. You 
bring your own router, etc. See below for some well-baked examples.

Because of its reliance on the net/http standard, Interpose is out-of-the-box 
compatible with the Gorilla framework, goji, nosurf, and many other frameworks and 
standalone middleware. 

Many projects claim to be `http.Handler`-compliant but actually just use `http.Handlers` 
to create a more complicated/less compatible abstraction. Therefore, a goal of the 
project is also to create adaptors so that non-`http.Handler` compliant middleware can 
still be used. As an example of this, an adaptor for Negroni middleware is available, 
meaning that **any middleware that is Negroni compliant is also Interpose compliant**. 
The same is true for Martini middleware.

## API change

Please note that the API has recently changed. Previously, the framework applied
middleware in LIFO order. Now it applies middleware in FIFO order.

## Usage

To use, first:

`go get github.com/carbocation/interpose`

## Basic usage example

Here is one example of using Interpose to execute 
middleware that adds the HTTP header "X-Server-Name" to every response.

Create a file `main.go` with the following:
```go
package main

import (
	"fmt"
	"net/http"

	"github.com/carbocation/interpose"
)

func main() {
	middle := interpose.New()

	// Send a header telling the world this is coming from an Interpose Test Server
	// You could imagine setting Content-type application/json or other useful
	// headers in other circumstances.
	middle.UseHandler(http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
		rw.Header().Set("X-Server-Name", "Interpose Test Server")
	}))

	// In this example, we use a basic router with a catchall route that
	// matches any path. In other examples in this project, we use a
	// more advanced router.
	// The last middleware added is the last executed, so by adding the router
	// last, our other middleware get a chance to modify HTTP headers before our
	// router writes to the HTTP Body
	router := http.NewServeMux()
	middle.UseHandler(router)

	router.Handle("/", http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
		fmt.Fprintf(w, "Welcome to %s!", req.URL.Path)
	}))

	http.ListenAndServe(":3001", middle)
}

```

In the same path as that file, type `go run main.go`

Now launch your browser and point it to `http://localhost:3001/world` to see output.

Additional examples can be found below.

## Philosophy

Interpose is a minimalist Golang middleware that uses only `http.Handler` and
`func(http.Handler)http.Handler`. Interpose takes advantage of closures to create
a stack of native net/http middleware. Unlike other middleware libraries which
create their own net/http-like signatures, interpose uses literal net/http
signatures, thus minimizing package lock-in and maximizing inter-compatibility.

Middleware is called in nested FIFO fashion, which means that the first middleware
to be added will be the first middleware to be called. Because the middleware is
nested, it actually means that the first middleware to be added gets the
opportunity to make the first and the last calls in the stack. For example,
if there are 3 middlewares added in order (0, 1, 2), the calls look like so:

	//0 START
		//1 START
			//2 START
			//2 END
		//1 END
	//0 END

## Middleware

Here is a current list of Interpose compatible middleware that have pre-built 
examples working with Interpose. Any middleware that yields an `http.Handler` 
or a `func(http.Handler)http.Handler` should be compliant. Pull requests linking 
to other middleware are encouraged.


| Middleware | Usage example | Author | Description |
| -----------|---------------|--------|-------------|
| [Graceful](https://github.com/stretchr/graceful) | [Graceful example](https://github.com/carbocation/interpose/blob/master/examples/graceful/main.go) | [Tyler Bunnell](https://github.com/tylerb) | Graceful HTTP Shutdown |
| [secure](https://github.com/unrolled/secure) | [Secure example](https://github.com/carbocation/interpose/blob/master/examples/secure/main.go) | [Cory Jacobsen](https://github.com/unrolled) | Middleware that implements a few quick security wins |
| [Gorilla logger](https://github.com/gorilla/handlers) | [Gorilla log example](https://github.com/carbocation/interpose/blob/master/examples/gorillalog/main.go) | [Gorilla team](https://github.com/gorilla/) | Gorilla Apache CombinedLogger |
| [Logrus](https://github.com/meatballhat/negroni-logrus) | [Logrus example](https://github.com/carbocation/interpose/blob/master/examples/adaptors/logrus/main.go) | [Dan Buch](https://github.com/meatballhat) | Logrus-based logger, also demonstrating how Negroni packages can be used in Interpose |
| [Buffered output](https://github.com/goods/httpbuf) | [Buffer example](https://github.com/carbocation/interpose/blob/master/examples/buffer/main.go) | [zeebo](https://github.com/zeebo) | Output buffering demonstrating how headers can be written after HTTP body is sent |
| [nosurf](https://github.com/justinas/nosurf) | [nosurf example](https://github.com/carbocation/interpose/blob/master/examples/nosurf/main.go) | [justinas](https://github.com/justinas) | A CSRF protection middleware for Go. |
| [BasicAuth](https://github.com/carbocation/interpose/blob/master/middleware/basicAuth.go)| [BasicAuth example](https://github.com/carbocation/interpose/blob/master/examples/basicAuth/main.go)| [Jeremy Saenz](http://github.com/codegangsta) & [Brendon Murphy](http://github.com/bemurphy) | [HTTP BasicAuth](https://en.wikipedia.org/wiki/Basic_access_authentication) - based on martini's [auth](https://github.com/martini-contrib/auth) middleware|
| [Martini Auth](https://github.com/martini-contrib/auth) | [Martini Auth example](https://github.com/carbocation/interpose/blob/master/examples/adaptors/martiniauth/main.go) | [Jeremy Saenz](https://github.com/codegangsta) & [Brendon Murphy](http://github.com/bemurphy) | A basic HTTP Auth implementation that also demonstrates how Martini middleware packages can be used directly in Interpose with a simple wrapper. |

## Adaptors

Some frameworks that are not strictly `http.Handler` compliant use middleware that 
can be readily converted into Interpose-compliant middleware. So far, adaptors for 
Martini and Negroni have been created. 

For example, to use github.com/urfave/negroni middleware in Interpose, you 
can use `adaptors.FromNegroni`:

```go
	middle := interpose.New()

	// has signature `negroni.Handler`
	negroniMiddleware := negronilogrus.NewMiddleware()

	// Use the Negroni middleware within Interpose
	middle.Use(adaptors.FromNegroni(negroniMiddleware))

```

## More examples

### Routing, graceful shutdown, and headers

In this example, we use the `graceful` package to gracefully release 
connections after the shutdown signal is encountered. A more powerful 
router than in our prior example, Gorilla mux, is used. Also, we send 
the browser headers indicating that this came from a server named 
"Interpose Test Server."

```go
package main

import (
	"fmt"
	"net/http"
	"time"

	"github.com/carbocation/interpose"
	"github.com/gorilla/mux"
	"github.com/stretchr/graceful"
)

func main() {
	middle := interpose.New()

	// Tell the browser which server this came from.
	// This modifies headers, so we want this to be called before
	// any middleware which might modify the body (in HTTP, the headers cannot be
	// modified after the body is modified)
	middle.Use(func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
			rw.Header().Set("X-Server-Name", "Interpose Test Server")
			next.ServeHTTP(rw, req)
		})
	})

	// Apply the router. By adding it last, all of our other middleware will be
	// executed before the router, allowing us to modify headers before any
	// output has been generated.
	router := mux.NewRouter()
	middle.UseHandler(router)

	router.HandleFunc("/{user}", func(w http.ResponseWriter, req *http.Request) {
		fmt.Fprintf(w, "Welcome to the home page, %s!", mux.Vars(req)["user"])
	})

	// Launch and permit graceful shutdown, allowing up to 10 seconds for existing
	// connections to end
	graceful.Run(":3001", 10*time.Second, middle)
}

```

### Combined logging and gzipping

Print an Apache CombinedLog-compatible log statement to StdOut and 
gzip the HTTP response it if the client has gzip capabilities:

```go
package main

import (
	"compress/gzip"
	"fmt"
	"net/http"

	"github.com/carbocation/interpose"
	"github.com/carbocation/interpose/middleware"
	"github.com/gorilla/mux"
)

func main() {
	middle := interpose.New()

	// First apply any middleware that will not write output to http body

	// Log to stdout. Taken from Gorilla
	middle.Use(middleware.GorillaLog())

	// Gzip output that follows. Taken from Negroni
	middle.Use(middleware.NegroniGzip(gzip.DefaultCompression))

	// Now apply any middleware that modify the http body.
	router := mux.NewRouter()
	middle.UseHandler(router)

	router.HandleFunc("/{user}", func(w http.ResponseWriter, req *http.Request) {
		fmt.Fprintf(w, "Welcome to the home page, %s!", mux.Vars(req)["user"])
	})

	http.ListenAndServe(":3001", middle)
}


```

### Wrapped middleware

Middleware can be wrapped around other middleware. In this example, 
we greet people who arrive at `/{user}`, but we offer a special greeting
to those who arrive at `/green/{user}`:

```go
package main

import (
	"fmt"
	"net/http"

	"github.com/carbocation/interpose"
	"github.com/carbocation/interpose/middleware"
	"github.com/gorilla/mux"
)

func main() {
	middle := interpose.New()

	// Invoke the Gorilla framework's combined logger
	middle.Use(middleware.GorillaLog())

	// Create a router to serve HTTP content at two paths
	// and tell our middleware about the router
	router := mux.NewRouter()
	middle.UseHandler(router)

	router.PathPrefix("/green").Subrouter().Handle("/{name}", Green(http.HandlerFunc(welcomeHandler)))
	router.Handle("/{name}", http.HandlerFunc(welcomeHandler))

	http.ListenAndServe(":3001", middle)
}

func welcomeHandler(rw http.ResponseWriter, req *http.Request) {
	fmt.Fprintf(rw, "Welcome to the home page, %s", mux.Vars(req)["name"])
}

func Green(next http.Handler) http.Handler {
	return http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
		rw.Header().Set("X-Favorite-Color", "green")
		next.ServeHTTP(rw, req)
		fmt.Fprint(rw, " who likes green")
	})
}

```

### Nested middleware: adding headers for only some routes

In the last example, we applied different middleware to different routes. 
Here we will expand this idea to created fully nested middleware stacks 
within different routes. This approach, while more verbose than the last 
example, is arbitrarily powerful. In this example, routes starting with 
/green are given a special HTTP header X-Favorite-Color: green, 
but you can also imagine using this same approach to automatically apply 
the JSON content header for JSON requests, putting authentication in front of
protected paths, etc.

```go
package main

import (
	"compress/gzip"
	"fmt"
	"net/http"

	"github.com/carbocation/interpose"
	"github.com/carbocation/interpose/middleware"
	"github.com/gorilla/mux"
)

func main() {
	middle := interpose.New()

	// First call middleware that may manipulate HTTP headers, since
	// they must be called before the HTTP body is manipulated

	// Using Gorilla framework's combined logger
	middle.Use(middleware.GorillaLog())

	//Using Negroni's Gzip functionality
	middle.Use(middleware.NegroniGzip(gzip.DefaultCompression))

	// Now call middleware that can manipulate the HTTP body

	// Define the router. Note that we can add the router to our
	// middleware stack before we define the routes, if we want.
	router := mux.NewRouter()
	middle.UseHandler(router)

	// Configure our router
	router.HandleFunc("/{user}", func(w http.ResponseWriter, req *http.Request) {
		fmt.Fprintf(w, "Welcome to the home page, %s!", mux.Vars(req)["user"])
	})

	// Define middleware that will apply to only some routes
	greenMiddle := interpose.New()

	// Tell the main router to send /green requests to our subrouter.
	// Again, we can do this before defining the full middleware stack.
	router.Methods("GET").PathPrefix("/green").Handler(greenMiddle)

	// Within the secondary middleware, just like above, we want to call anything that
	// will modify the HTTP headers before anything that will modify the body
	greenMiddle.UseHandler(http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
		rw.Header().Set("X-Favorite-Color", "green")
	}))

	// Finally, define a sub-router based on our love of the color green
	// When you call any url such as http://localhost:3001/green/man , you will
	// also see an HTTP header sent called X-Favorite-Color with value "green"
	greenRouter := mux.NewRouter().Methods("GET").PathPrefix("/green").Subrouter() //Headers("Accept", "application/json")
	greenMiddle.UseHandler(greenRouter)

	greenRouter.HandleFunc("/{user}", func(w http.ResponseWriter, req *http.Request) {
		fmt.Fprintf(w, "Welcome to the home page, green %s!", mux.Vars(req)["user"])
	})

	http.ListenAndServe(":3001", middle)
}

```

For more examples, please look at the [examples folder](https://github.com/carbocation/interpose/tree/master/examples) 
as well as its subfolder, the [menagerie folder](https://github.com/carbocation/interpose/tree/master/examples/menagerie)

## Authors
Originally developed by [carbocation](https://github.com/carbocation). Please see the 
[contributors](https://github.com/carbocation/interpose/blob/master/CONTRIBUTORS.md) 
file for an expanded list of contributors.


interpose

Simple, lightweight and faster response (JSON, JSONP, XML, YAML, HTML, File) rendering package for Go

Package renderer
==================
[![Build Status](https://travis-ci.org/thedevsaddam/renderer.svg?branch=master)](https://travis-ci.org/thedevsaddam/renderer)
[![Project status](https://img.shields.io/badge/version-1.2-green.svg)](https://github.com/thedevsaddam/renderer/releases)
[![Go Report Card](https://goreportcard.com/badge/github.com/thedevsaddam/renderer)](https://goreportcard.com/report/github.com/thedevsaddam/renderer)
[![Coverage Status](https://coveralls.io/repos/github/thedevsaddam/renderer/badge.svg?branch=master)](https://coveralls.io/github/thedevsaddam/renderer?branch=master)
[![GoDoc](https://godoc.org/github.com/thedevsaddam/renderer?status.svg)](https://godoc.org/github.com/thedevsaddam/renderer)
[![License](https://img.shields.io/dub/l/vibe-d.svg)](https://github.com/thedevsaddam/renderer/blob/dev/LICENSE.md)

Simple, lightweight and faster response (JSON, JSONP, XML, YAML, HTML, File) rendering package for Go

### Installation

Install the package using
```go
$ go get github.com/thedevsaddam/renderer/...
```

### Usage

To use the package import it in your `*.go` code
```go
import "github.com/thedevsaddam/renderer"
```
### Example

```go
package main

import (
	"io"
	"log"
	"net/http"
	"os"

	"github.com/thedevsaddam/renderer"
)

func main() {
	rnd := renderer.New()

	mux := http.NewServeMux()

	usr := struct {
		Name string
		Age  int
	}{"John Doe", 30}

	// serving String as text/plain
	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		rnd.String(w, http.StatusOK, "Welcome to renderer")
	})

	// serving success but no content
	mux.HandleFunc("/no-content", func(w http.ResponseWriter, r *http.Request) {
		rnd.NoContent(w)
	})

	// serving string as html
	mux.HandleFunc("/html-string", func(w http.ResponseWriter, r *http.Request) {
		rnd.HTMLString(w, http.StatusOK, "<h1>Hello Renderer!</h1>")
	})

	// serving JSON
	mux.HandleFunc("/json", func(w http.ResponseWriter, r *http.Request) {
		rnd.JSON(w, http.StatusOK, usr)
	})

	// serving JSONP
	mux.HandleFunc("/jsonp", func(w http.ResponseWriter, r *http.Request) {
		rnd.JSONP(w, http.StatusOK, "callback", usr)
	})

	// serving XML
	mux.HandleFunc("/xml", func(w http.ResponseWriter, r *http.Request) {
		rnd.XML(w, http.StatusOK, usr)
	})

	// serving YAML
	mux.HandleFunc("/yaml", func(w http.ResponseWriter, r *http.Request) {
		rnd.YAML(w, http.StatusOK, usr)
	})

	// serving File as arbitary binary data
	mux.HandleFunc("/binary", func(w http.ResponseWriter, r *http.Request) {
		var reader io.Reader
		reader, _ = os.Open("../README.md")
		rnd.Binary(w, http.StatusOK, reader, "readme.md", true)
	})

	// serving File as inline
	mux.HandleFunc("/file-inline", func(w http.ResponseWriter, r *http.Request) {
		rnd.FileView(w, http.StatusOK, "../README.md", "readme.md")
	})

	// serving File as attachment
	mux.HandleFunc("/file-download", func(w http.ResponseWriter, r *http.Request) {
		rnd.FileDownload(w, http.StatusOK, "../README.md", "readme.md")
	})

	// serving File from reader as inline
	mux.HandleFunc("/file-reader", func(w http.ResponseWriter, r *http.Request) {
		var reader io.Reader
		reader, _ = os.Open("../README.md")
		rnd.File(w, http.StatusOK, reader, "readme.md", true)
	})

	// serving custom response using render and chaining methods
	mux.HandleFunc("/render", func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set(renderer.ContentType, renderer.ContentText)
		rnd.Render(w, http.StatusOK, []byte("Send the message as text response"))
	})

	port := ":9000"
	log.Println("Listening on port", port)
	http.ListenAndServe(port, mux)
}

```

### How to render html template?

Well, you can parse html template using `HTML`, `View`, `Template` any of these method. These are based on `html/template` package.

When using `Template` method you can simply pass the base layouts, templates path as a slice of string.

***Template example***

You can parse template on the fly using `Template` method. You can set delimiter, inject FuncMap easily.

template/layout.tmpl
```html
<html>
  <head>
    <title>{{ template "title" . }}</title>
  </head>
  <body>
    {{ template "content" . }}
  </body>
  {{ block "sidebar" .}}{{end}}
</html>
```
template/index.tmpl
```html
{{ define "title" }}Home{{ end }}

{{ define "content" }}
  <h1>Hello, {{ .Name | toUpper }}</h1>
  <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit.</p>
{{ end }}
```
template/partial.tmpl
```html
{{define "sidebar"}}
  simple sidebar code
{{end}}

```

template.go
```go
package main

import (
	"html/template"
	"log"
	"net/http"
	"strings"

	"github.com/thedevsaddam/renderer"
)

var rnd *renderer.Render

func init() {
	rnd = renderer.New()
}

func toUpper(s string) string {
	return strings.ToUpper(s)
}

func handler(w http.ResponseWriter, r *http.Request) {
	usr := struct {
		Name string
		Age  int
	}{"john doe", 30}

	tpls := []string{"template/layout.tmpl", "template/index.tmpl", "template/partial.tmpl"}
	rnd.FuncMap(template.FuncMap{
		"toUpper": toUpper,
	})
	err := rnd.Template(w, http.StatusOK, tpls, usr)
	if err != nil {
		log.Fatal(err) //respond with error page or message
	}
}

func main() {
	http.HandleFunc("/", handler)
	log.Println("Listening port: 9000")
	http.ListenAndServe(":9000", nil)
}
```

***HTML example***

When using `HTML` you can parse a template directory using `pattern` and call the template by their name. See the example code below:

html/index.html
```html
{{define "indexPage"}}
    <html>
    {{template "header"}}
    <body>
        <h3>Index</h3>
        <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit</p>
    </body>
    {{template "footer"}}
    </html>
{{end}}
```

html/header.html
```html
{{define "header"}}
     <head>
         <title>Header</title>
         <h1>Header section</h1>
     </head>
{{end}}
```

html/footer.html
```html
{{define "footer"}}
     <footer>Copyright &copy; 2020</footer>
{{end}}
```

html.go
```go
package main

import (
	"log"
	"net/http"

	"github.com/thedevsaddam/renderer"
)

var rnd *renderer.Render

func init() {
	rnd = renderer.New(
		renderer.Options{
			ParseGlobPattern: "html/*.html",
		},
	)
}

func handler(w http.ResponseWriter, r *http.Request) {
	err := rnd.HTML(w, http.StatusOK, "indexPage", nil)
	if err != nil {
		log.Fatal(err)
	}
}

func main() {
	http.HandleFunc("/", handler)
	log.Println("Listening port: 9000")
	http.ListenAndServe(":9000", nil)
}
```

***View example***

When using `View` for parsing template you can pass multiple layout and templates. Here template name will be the file name. See the example to get the idea.

view/base.lout
```html
<html>
  <head>
     <title>{{block "title" .}} {{end}}</title>
  </head>
  <body>
    {{ template "content" . }}
  </body>
</html>
```

view/home.tpl
```html
{{define "title"}}Home{{end}}
{{define "content"}}
<h3>Home page</h3>
    <ul>
        <li><a href="/">Home</a></li>
        <li><a href="/about">About Me</a></li>
    </ul>
    <p>
    Lorem ipsum dolor sit amet</p>
{{end}}
```
view/about.tpl
```html
{{define "title"}}About Me{{end}}
{{define "content"}}
<h2>This is About me page.</h2>
<ul>
    Lorem ipsum dolor sit amet, consectetur adipisicing elit,
</ul>
<p><a href="/">Home</a></p>
{{end}}
```

view.go
```go
package main

import (
	"log"
	"net/http"

	"github.com/thedevsaddam/renderer"
)

var rnd *renderer.Render

func init() {
	rnd = renderer.New(renderer.Options{
		TemplateDir: "view",
	})
}

func home(w http.ResponseWriter, r *http.Request) {
	err := rnd.View(w, http.StatusOK, "home", nil)
	if err != nil {
		log.Fatal(err)
	}
}

func about(w http.ResponseWriter, r *http.Request) {
	err := rnd.View(w, http.StatusOK, "about", nil)
	if err != nil {
		log.Fatal(err)
	}
}

func main() {
	http.HandleFunc("/", home)
	http.HandleFunc("/about", about)
	log.Println("Listening port: 9000\n / is root \n /about is about page")
	http.ListenAndServe(":9000", nil)
}
```

***Note:*** This is a wrapper on top of go built-in packages to provide syntactic sugar.

### Contribution
Your suggestions will be more than appreciated.
[Read the contribution guide here](CONTRIBUTING.md)

### See all [contributors](https://github.com/thedevsaddam/renderer/graphs/contributors)

### Read [API doc](https://godoc.org/github.com/thedevsaddam/renderer) to know about ***Available options and Methods***

### **License**
The **renderer** is an open-source software licensed under the [MIT License](LICENSE.md).


renderer

Go middleware that stores various information about your web application

Go stats handler
================

.. image:: https://secure.travis-ci.org/thoas/stats.svg?branch=master
    :alt: Build Status
    :target: http://travis-ci.org/thoas/stats

stats is a ``net/http`` handler in golang reporting various metrics about
your web application.

This middleware has been developed and required for the need of picfit_,
an image resizing server written in Go.

Compatibility
-------------

This handler supports the following frameworks at the moment:

* `negroni`_
* `martini`_
* `gocraft/web <https://github.com/gocraft/web>`_
* `Gin <https://github.com/gin-gonic/gin>`_
* `Goji <https://github.com/zenazn/goji>`_
* `Beego <https://github.com/astaxie/beego>`_
* `HTTPRouter <https://github.com/julienschmidt/httprouter>`_

We don't support your favorite Go framework? Send me a PR or
create a new `issue <https://github.com/thoas/stats/issues>`_ and
I will implement it :)

Installation
------------

1. Make sure you have a Go language compiler >= 1.3 (required) and git installed.
2. Make sure you have the following go system dependencies in your $PATH: bzr, svn, hg, git
3. Ensure your GOPATH_ is properly set.
4. Download it:

::

    go get github.com/thoas/stats


Usage
-----

Basic net/http
..............

To use this handler directly with ``net/http``, you need to call the
middleware with the handler itself:

.. code-block:: go

    package main

    import (
        "net/http"
        "github.com/thoas/stats"
    )

    func main() {
        h := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            w.Header().Set("Content-Type", "application/json")
            w.Write([]byte("{\"hello\": \"world\"}"))
        })

        handler := stats.New().Handler(h)
        http.ListenAndServe(":8080", handler)
    }

Negroni
.......

If you are using negroni_ you can implement the handler as
a simple middleware in ``server.go``:

.. code-block:: go

    package main

    import (
        "net/http"
        "github.com/codegangsta/negroni"
        "github.com/thoas/stats"
        "encoding/json"
    )

    func main() {
        middleware := stats.New()

        mux := http.NewServeMux()

        mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
            w.Header().Set("Content-Type", "application/json")
            w.Write([]byte("{\"hello\": \"world\"}"))
        })

        mux.HandleFunc("/stats", func(w http.ResponseWriter, r *http.Request) {
            w.Header().Set("Content-Type", "application/json")

            stats := middleware.Data()

            b, _ := json.Marshal(stats)

            w.Write(b)
        })

        n := negroni.Classic()
        n.Use(middleware)
        n.UseHandler(mux)
        n.Run(":3000")
    }

HTTPRouter
.......

If you are using HTTPRouter_ you need to call the middleware with the handler itself:

.. code-block:: go
    
    package main                                                                          

    import (
            "encoding/json"
            "github.com/julienschmidt/httprouter"
            "github.com/thoas/stats"
            "net/http"
    )
    
    func main() {
            router := httprouter.New()
            s := stats.New()
            router.GET("/stats", func(w http.ResponseWriter, _ *http.Request, _ httprouter.Params) {
                    w.Header().Set("Content-Type", "application/json; charset=utf-8")
                    s, err := json.Marshal(s.Data())
                    if err != nil {
                            http.Error(w, err.Error(), http.StatusInternalServerError)
                    }
                    w.Write(s)
            })
            http.ListenAndServe(":8080", s.Handler(router))
    }
    
    
Martini
.......

If you are using martini_, you can implement the handler as a wrapper of
a ``Martini.Context`` in ``server.go``:


.. code-block:: go

    package main

    import (
        "encoding/json"
        "github.com/go-martini/martini"
        "github.com/thoas/stats"
        "net/http"
    )

    func main() {
        middleware := stats.New()

        m := martini.Classic()
        m.Get("/", func(w http.ResponseWriter, r *http.Request) {
            w.Header().Set("Content-Type", "application/json")
            w.Write([]byte("{\"hello\": \"world\"}"))
        })
        m.Get("/stats", func(w http.ResponseWriter, r *http.Request) {
            w.Header().Set("Content-Type", "application/json")

            stats := middleware.Data()

            b, _ := json.Marshal(stats)

            w.Write(b)
        })

        m.Use(func(c martini.Context, w http.ResponseWriter, r *http.Request) {
            beginning, recorder := middleware.Begin(w)

            c.Next()

            middleware.End(beginning, stats.WithRecorder(recorder))
        })
        m.Run()
    }

Run it in a shell:

::

    $ go run server.go

Then in another shell run:

::

    $ curl http://localhost:3000/stats | python -m "json.tool"

Expect the following result:

.. code-block:: json

    {
        "total_response_time": "1.907382ms",
        "average_response_time": "86.699\u00b5s",
        "average_response_time_sec": 8.6699e-05,
        "count": 1,
        "pid": 99894,
        "status_code_count": {
            "200": 1
        },
        "time": "2015-03-06 17:23:27.000677896 +0100 CET",
        "total_count": 22,
        "total_response_time_sec": 0.0019073820000000002,
        "total_status_code_count": {
            "200": 22
        },
        "unixtime": 1425659007,
        "uptime": "4m14.502271612s",
        "uptime_sec": 254.502271612
    }

See `examples <https://github.com/thoas/stats/blob/master/examples>`_ to
test them.


Inspiration
-----------

`Antoine Imbert <https://github.com/ant0ine>`_ is the original author
of this middleware.

Originally developed for `go-json-rest <https://github.com/ant0ine/go-json-rest>`_,
it had been ported as a simple Golang handler by `Florent Messa <https://github.com/thoas>`_
to be used in various frameworks.

This middleware implements a ticker which is launched every seconds to
reset requests/sec and will implement new features in a near future :)

.. _GOPATH: http://golang.org/doc/code.html#GOPATH
.. _StatusMiddleware: https://github.com/ant0ine/go-json-rest/blob/master/rest/status.go
.. _go-json-rest: https://github.com/ant0ine/go-json-rest
.. _negroni: https://github.com/codegangsta/negroni
.. _martini: https://github.com/go-martini/martini
.. _picfit: https://github.com/thoas/picfit
.. _HTTPRouter: https://github.com/julienschmidt/httprouter


stats

# client-timing

[![Build Status](https://travis-ci.org/posener/client-timing.svg?branch=master)](https://travis-ci.org/posener/client-timing)
[![codecov](https://codecov.io/gh/posener/client-timing/branch/master/graph/badge.svg)](https://codecov.io/gh/posener/client-timing)
[![GoDoc](https://godoc.org/github.com/posener/client-timing?status.svg)](http://godoc.org/github.com/posener/client-timing)
[![Go Report Card](https://goreportcard.com/badge/github.com/posener/client-timing)](https://goreportcard.com/report/github.com/posener/client-timing)

An HTTP client for [go-server-timing](https://github.com/mitchellh/go-server-timing) middleware.

## Features:

* An HTTP `Client` or `RoundTripper`, fully compatible with Go's standard library.
* Automatically time HTTP requests sent from an HTTP handler.
* Collects all timing headers from upstream servers.
* Customize timing headers according to the request, response and error of the HTTP round trip.

## Install

`go get -u github.com/posener/client-timing`

## Usage

1. Add a `*clienttiming.Timer` to your server handler, or create it in the handler function itself.
2. Wrap the `http.Handler` with [`servertiming.Middleware`](https://godoc.org/github.com/mitchellh/go-server-timing#Middleware).
2. In the handler function, having `timer` of type `*clienttiming.Timer` and `req` is the `*http.Request`:

    a. Create an [`*http.Client`](https://godoc.org/net/http#Client) using `timer.Client(req.Context())`

    b. Or create an [`http.RoundTripper`](https://godoc.org/net/http#RoundTripper) using `timer.Transport(req.Context())`

3. Use option a or b directly or inject it to a library that accepts them, in your outgoing HTTP request
   from the handler.
4. That is it! the timing header will appear in the response from the handler.

## Example

Suppose we have an HTTP handler:

```go
type handler struct {
	timer *clienttiming.Timer
}
```

Our usage of that handler will be:

```go
func main() {
	h := &handler{
		timer: clienttiming.New(clienttiming.WithName("my-server")),
	}
	log.Fatal(http.ListenAndServe(":8080", servertiming.Middleware(h)))
}
```


### Example for `Client` function:

```go
func (h *handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	// Create an http client using the request context
	c := h.timer.Client(r.Context())

	// Perform HTTP requests, as many as you like
	resp, err := c.Get("https://golang.org/")

	...
}
```

### Example for `Transport` function:

```go
func (h *handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	// Instrument an http client with a timing transport
	c := &http.Client{
		Transport: h.timer.Transport(r.Context()),
	}

	// Perform HTTP requests, as many as you like
	resp, err := c.Get("https://golang.org/")

	...
}
```

### Run the [example](./example/main.go)

`go run ./example/main.go`


client-timing

Middleware for Echo framework with logging and metrics

# Echo Framework - Middlewares

[![Build Status](https://img.shields.io/github/actions/workflow/status/faabiosr/echo-middleware/test.yml?logo=github&style=flat-square)](https://github.com/faabiosr/echo-middleware/actions?query=workflow:test)
[![Codecov branch](https://img.shields.io/codecov/c/github/faabiosr/echo-middleware/master.svg?style=flat-square)](https://codecov.io/gh/faabiosr/echo-middleware)
[![Go Reference](https://pkg.go.dev/badge/github.com/faabiosr/echo-middleware.svg)](https://pkg.go.dev/github.com/faabiosr/echo-middleware)
[![Go Report Card](https://goreportcard.com/badge/github.com/faabiosr/echo-middleware?style=flat-square)](https://goreportcard.com/report/github.com/faabiosr/echo-middleware)
[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://github.com/faabiosr/echo-middleware/blob/master/LICENSE)

## :tada: Overview
echo-middleware is a Go package that provides multiple middlewares for Echo Framework.

## :relaxed: Motivation
After writing these middlewares several times, it was decided to create a package with useful middlewares for echo.

## :dart: Installation

### Requirements
echo-middleware requires Go 1.21 or later and Echo Framework v4.

### How to use
Use go get.
```sh
$ go get github.com/faabiosr/echo-middleware
```

Then import the package into your own code:
```
import "github.com/faabiosr/echo-middleware"
```

## :toolbox: Development

### Requirements
- Install [Go](https://golang.org)
- Install [GolangCI-Lint](https://github.com/golangci/golangci-lint#install)

### Makefile
Please run `make help` to see all the available targets.

## :page_with_curl: License
This project is released under the MIT licence. See [LICENSE](https://github.com/faabiosr/echo-middleware/blob/master/LICENSE) for more details.


echo-middleware

Transparently handle JSON input as a standard form POST

# Go JSON handler [![godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/rs/formjson) [![license](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](https://raw.githubusercontent.com/rs/formjson/master/LICENSE) [![build](https://img.shields.io/travis/rs/formjson.svg?style=flat)](https://travis-ci.org/rs/formjson)

FormJSON is a `net/http` handler implementing content negotiation for posted data in order to transparently expose posted JSON as if it was `application/x-www-form-urlencoded`. The posted data is then available using built-in `r.FormValue("key")`'s `http.Request` method.

To match capabilities of `application/x-www-form-urlencoded`, only single depth JSON object with `string` as keys and values is supported.

## Usage

```go
package main

import (
    "net/http"
    "fmt"

    "github.com/rs/formjson"
)

func main() {
    h := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        body := fmt.Sprintf("Hello %s!", r.FormValue("name"))
        w.Write([]byte(body))
    })

    handler := formjson.Handler(h)
    http.ListenAndServe(":8080", handler)
}
```

Then this request:

    curl -H "Content-Type:application/json" -d '{"name":"World"}' :8080

is now equivalent to this one:

    curl -d name=World :8080

## Licenses

All source code is licensed under the [MIT License](https://raw.github.com/rs/formjson/master/LICENSE).


formjson

Handle `X-Forwarded-For` header and friends

# X-Forwarded-For middleware fo Go [![godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/sebest/xff) [![Build Status](https://travis-ci.org/sebest/xff.svg?branch=master)](https://travis-ci.org/sebest/xff)

Package `xff` is a `net/http` middleware/handler to parse [Forwarded HTTP Extension](http://tools.ietf.org/html/rfc7239) in Golang.

## Example usage

Install `xff`:

    go get github.com/sebest/xff

Edit `server.go`:

```go
package main

import (
  "net/http"

  "github.com/sebest/xff"
)

func main() {
  handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("hello from " + r.RemoteAddr + "\n"))
  })

  xffmw, _ := xff.Default()
  http.ListenAndServe(":8080", xffmw.Handler(handler))
}
```

Then run your server:

    go run server.go

The server now runs on `localhost:8080`:

    $ curl -D - -H 'X-Forwarded-For: 42.42.42.42' http://localhost:8080/
    HTTP/1.1 200 OK
    Date: Fri, 20 Feb 2015 20:03:02 GMT
    Content-Length: 29
    Content-Type: text/plain; charset=utf-8

    hello from 42.42.42.42:52661


# Alice 

[![GoDoc](https://godoc.org/github.com/golang/gddo?status.svg)](http://godoc.org/github.com/justinas/alice)
[![Build Status](https://travis-ci.org/justinas/alice.svg?branch=master)](https://travis-ci.org/justinas/alice)
[![Coverage](http://gocover.io/_badge/github.com/justinas/alice)](http://gocover.io/github.com/justinas/alice)

Alice provides a convenient way to chain 
your HTTP middleware functions and the app handler.

In short, it transforms

```go
Middleware1(Middleware2(Middleware3(App)))
```

to

```go
alice.New(Middleware1, Middleware2, Middleware3).Then(App)
```

### Why?

None of the other middleware chaining solutions
behaves exactly like Alice.
Alice is as minimal as it gets:
in essence, it's just a for loop that does the wrapping for you.

Check out [this blog post](http://justinas.org/alice-painless-middleware-chaining-for-go/)
for explanation how Alice is different from other chaining solutions.

### Usage

Your middleware constructors should have the form of

```go
func (http.Handler) http.Handler
```

Some middleware provide this out of the box.
For ones that don't, it's trivial to write one yourself.

```go
func myStripPrefix(h http.Handler) http.Handler {
    return http.StripPrefix("/old", h)
}
```

This complete example shows the full power of Alice.

```go
package main

import (
    "net/http"
    "time"

    "github.com/throttled/throttled"
    "github.com/justinas/alice"
    "github.com/justinas/nosurf"
)

func timeoutHandler(h http.Handler) http.Handler {
    return http.TimeoutHandler(h, 1*time.Second, "timed out")
}

func myApp(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("Hello world!"))
}

func main() {
    th := throttled.Interval(throttled.PerSec(10), 1, &throttled.VaryBy{Path: true}, 50)
    myHandler := http.HandlerFunc(myApp)

    chain := alice.New(th.Throttle, timeoutHandler, nosurf.NewPure).Then(myHandler)
    http.ListenAndServe(":8000", chain)
}
```

Here, the request will pass [throttled](https://github.com/PuerkitoBio/throttled) first,
then an http.TimeoutHandler we've set up,
then [nosurf](https://github.com/justinas/nosurf)
and will finally reach our handler.

Note that Alice makes **no guarantees** for
how one or another piece of  middleware will behave.
Once it passes the execution to the outer layer of middleware,
it has no saying in whether middleware will execute the inner handlers.
This is intentional behavior.

Alice works with Go 1.0 and higher.

### Contributing

0. Find an issue that bugs you / open a new one.
1. Discuss.
2. Branch off, commit, test.
3. Make a pull request / attach the commits to the issue.


alice

Handler wrapper chaining with scoped data (net/context-based "middleware")

# chain

    go get github.com/codemodus/chain

Package chain aids the composition of nested http.Handler instances.

Nesting functions is a simple concept.  If your nested handler order does not 
need to be composable, please do not use this or any similar package and avoid 
adding a dependency to your project.

## Usage

```go
type Chain
    func New(handlers ...func(http.Handler) http.Handler) *Chain
    func (c *Chain) Append(handlers ...func(http.Handler) http.Handler) *Chain
    func (c *Chain) Copy(chain *Chain)
    func (c *Chain) End(handler http.Handler) http.Handler
    func (c *Chain) EndFn(handlerFunc http.HandlerFunc) http.Handler
    func (c *Chain) Merge(chains ...*Chain) *Chain
```

### Setup

```go
import (
    // ...

    "github.com/codemodus/chain"
)

func main() {
    // ...

  	// Nested handlers write either "0" or "1" to the response body before
	// and after ServeHTTP() is called.
	//
	// endHandler writes "_END_" to the response body.

	ch00 := New(nestedHandler0, nestedHandler0)
	ch001 := ch00.Append(nestedHandler1)

	ch1 := New(nestedHandler1)
	ch1001 := ch1.Merge(ch001)

	mux := http.NewServeMux()
	mux.Handle("/00_End", ch00.EndFn(endHandler))     // Resp Body: "00_END_00"
	mux.Handle("/001_End", ch001.EndFn(endHandler))   // Resp Body: "001_END_100"
	mux.Handle("/1001_End", ch1001.EndFn(endHandler)) // Resp Body: "1001_END_1001"

    // ...
}
```

### Nestable http.Handler

```go
func nestableHandler(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // ...
        
        next.ServeHTTP(w, r)
    	
        // ...
    })
}
```

## More Info

### Changes in go1.7+/chain2.0+

As of Go 1.7, the http package's Request type includes a field (accessed via 
the Context() method) which holds an implementation of context.Context. Further, 
the context package has been added to the standard library. There is now no need 
for the custom Handler defined in previous versions of chain. Please refer to 
the following command to ease the process of updating your source.

    sed -r -e 's/chain\.Handler/http.Handler/g' \
        -e 's/[a-zA-Z0-9]+ context\.Context, ([a-zA-Z0-9]+) (http\.ResponseWriter)/\1 \2/' \
        -e 's/ServeHTTPContext\([a-zA-Z0-9]+, /ServeHTTP(/'

Beyond this, any usage of chain.Set(context.Context) will need to be modified
manually. Adding the affected logic as a nested handler is a simple and 
effective alternative. Don't forget to run gofmt/goimports.

## Documentation

View the [GoDoc](http://godoc.org/github.com/codemodus/chain)

## Benchmarks

These results are for comparison of normally nested functions, and chained 
functions.  Each benchmark includes 10 functions prior to the final handler.

    go1.7
    benchmark             iter      time/iter   bytes alloc         allocs
    ---------             ----      ---------   -----------         ------
    BenchmarkChain10     20000    61.01 μs/op     3684 B/op   51 allocs/op
    BenchmarkChain10-4   20000    68.62 μs/op     3691 B/op   51 allocs/op
    BenchmarkChain10-8   20000    69.33 μs/op     3696 B/op   51 allocs/op
    BenchmarkNest10      20000    60.36 μs/op     3684 B/op   51 allocs/op
    BenchmarkNest10-4    20000    70.82 μs/op     3692 B/op   51 allocs/op
    BenchmarkNest10-8    20000    71.03 μs/op     3697 B/op   51 allocs/op


chain

add interceptors to `http.Client` to allow dumping/shaping/tracing/... of requests/responses

# mediary

[![Go Report Card](https://goreportcard.com/badge/github.com/HereMobilityDevelopers/mediary)](https://goreportcard.com/report/github.com/HereMobilityDevelopers/mediary)
[![Coverage Status](https://coveralls.io/repos/github/HereMobilityDevelopers/mediary/badge.svg?branch=master)](https://coveralls.io/github/HereMobilityDevelopers/mediary?branch=master)
[![Build Status](https://travis-ci.com/HereMobilityDevelopers/mediary.svg?branch=master)](https://travis-ci.com/HereMobilityDevelopers/mediary)
[![Go package dev](https://godoc.org/github.com/HereMobilityDevelopers/mediary?status.svg)](https://godoc.org/github.com/HereMobilityDevelopers/mediary)

Add interceptors to http.Client and you will be able to
* Dump request and/or response to a `Log`
* Alter your requests before they are sent or responses before they are returned
* Add Tracing information using `Opentracing`/`Jaeger`
* Send metrics to `statsd`

All this and more while using a "regular" `http.Client` 

## Usage
```go
var client *http.Client
client = mediary.Init().AddInterceptors(your interceptor).Build()
client.Get("https://golang.org")
```

## Dump Example
```go
client := mediary.Init().AddInterceptors(dumpInterceptor).Build()
client.Get("https://golang.org")

func dumpInterceptor(req *http.Request, handler mediary.Handler) (*http.Response, error) {
	if bytes, err := httputil.DumpRequestOut(req, true); err == nil {
		fmt.Printf("%s", bytes)

		//GET / HTTP/1.1
		//Host: golang.org
		//User-Agent: Go-http-client/1.1
		//Accept-Encoding: gzip
	}
	return handler(req)
}
```

## Interceptor
**Interceptor** is a function 

<code>type Interceptor func(*http.Request, Handler) (*http.Response, error)</code>

**Handler** is just an alias to <code>http.Roundtripper</code> function called `RoundTrip`

<code>type Handler func(*http.Request) (*http.Response, error) </code>

## Multiple interceptors

It's possible to chain interceptors

```go
client := mediary.Init().
    AddInterceptors(First Interceptor, Second Interceptor).
    AddInterceptors(Third Interceptor).
    Build()

```
This is how it actually works
- First Intereptor: *Request*
    - Second Interceptor: *Request*
        - Third Interceptor: *Request*
            - **Handler** <-- Actual http call
        - Third Interceptor: *Response*
    - Second Interceptor: *Response*
- First Interceptor: *Response*

## Using custom client/transport

If you already have a pre-configured `http.Client` you can use it as well
```go
yourClient := &http.Client{}
yourClientWithInterceptor := mediary.Init().
    WithPreconfiguredClient(yourClient).
    AddInterceptors(your interceptor).
    Build()
```

Read [this](https://github.com/HereMobilityDevelopers/mediary/wiki/Reasoning) for more information


mediary

# MuxChain

MuxChain is a small package designed to complement [net/http](http://golang.org/pkg/net/http) for specifying chains of handlers. With it, you can succinctly compose layers of middleware without introducing large dependencies or effectively defeating the type system.

#### Example

```
muxchain.Chain("/", logger, gzipHandler, echoHandler)
http.ListenAndServe(":8080", muxchain.Default)
```

This specifies that all patterns matched should be handled by the logger, then gzip, then echo. Since we're chaining to the default MuxChain, we can just pass that to `http.ListenAndServe`. You can see a more complete example in the "sample" directory.

#### License

BSD 3-clause (see LICENSE file)


The Best Go Libraries For Web Frameworks - Middlewares (23)