README

gentleman/mux Build Status GoDoc API Go Report Card

mux package implements a versatile HTTP client multiplexer with built-in matchers for easy plugin composition.

multiplexer can be used to compose plugins for both request/response phases.

Installation

go get -u gopkg.in/h2non/gentleman.v2/mux

API

See godoc reference.

Example

Create a multiplexer filtered by a custom matcher function:

package main

import (
  "fmt"
  "gopkg.in/h2non/gentleman.v2"
  "gopkg.in/h2non/gentleman.v2/mux"
  "gopkg.in/h2non/gentleman.v2/context"
  "gopkg.in/h2non/gentleman.v2/plugins/url"
)

func main() {
  // Create a new client
  cli := gentleman.New()

  // Use a custom multiplexer for GET requests
  cli.Use(mux.New().AddMatcher(func (ctx *context.Context) bool {
    return ctx.GetString("$phase") == "request" && ctx.Request.Method == "GET"
  }).Use(url.URL("http://httpbin.org/headers")))

  // Perform the request
  res, err := cli.Request().Send()
  if err != nil {
    fmt.Printf("Request error: %s\n", err)
    return
  }
  if !res.Ok {
    fmt.Printf("Invalid server response: %d\n", res.StatusCode)
    return
  }

  fmt.Printf("Status: %d\n", res.StatusCode)
  fmt.Printf("Body: %s", res.String())
}

Plugin composition via multiplexer:

package main

import (
  "fmt"
  "gopkg.in/h2non/gentleman.v2"
  "gopkg.in/h2non/gentleman.v2/mux"
  "gopkg.in/h2non/gentleman.v2/plugins/url"
)

func main() {
  // Create a new client
  cli := gentleman.New()

  // Define the server url (must be first)
  cli.Use(url.URL("http://httpbin.org"))

  // Create a new multiplexer based on multiple matchers
  mx := mux.If(mux.Method("GET"), mux.Host("httpbin.org"))

  // Attach a custom plugin on the multiplexer that will be executed if the matchers passes
  mx.Use(url.Path("/headers"))

  // Attach the multiplexer on the main client
  cli.Use(mx)

  // Perform the request
  res, err := cli.Request().Send()
  if err != nil {
    fmt.Printf("Request error: %s\n", err)
    return
  }
  if !res.Ok {
    fmt.Printf("Invalid server response: %d\n", res.StatusCode)
    return
  }

  fmt.Printf("Status: %d\n", res.StatusCode)
  fmt.Printf("Body: %s", res.String())
}

License

MIT - Tomas Aparicio

Documentation

Overview

    Package mux implements an HTTP domain-specific traffic multiplexer with built-in matchers and features for easy plugin composition and activable logic.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    Types

    type Matcher

    type Matcher func(ctx *c.Context) bool

      Matcher represent the function interface implemented by matchers

      type Mux

      type Mux struct {
      	// Mux also implements a plugin capable interface.
      	*plugin.Layer
      
      	// Matchers stores a list of matcher functions.
      	Matchers []Matcher
      
      	// Middleware stores the multiplexer middleware layer.
      	Middleware middleware.Middleware
      }

        Mux is a HTTP request/response/error multiplexer who implements both middleware and plugin interfaces. It has been designed for easy plugin composition based on HTTP matchers/filters.

        func Error

        func Error() *Mux

          Error returns a new multiplexer who matches errors originated in the client or in the server.

          func Host

          func Host(pattern string) *Mux

            Host returns a new multiplexer who matches an HTTP request URL host based on the given regexp pattern.

            func If

            func If(muxes ...*Mux) *Mux

              If creates a new multiplexer that will be executed if all the mux matchers passes.

              func Match

              func Match(matchers ...Matcher) *Mux

                Match creates a new multiplexer based on a given matcher function.

                func Method

                func Method(methods ...string) *Mux

                  Method returns a new multiplexer who matches an HTTP request based on the given method/s.

                  func New

                  func New() *Mux

                    New creates a new multiplexer with default settings.

                    func Or

                    func Or(muxes ...*Mux) *Mux

                      Or creates a new multiplexer that will be executed if at least one mux matcher passes.

                      func Path

                      func Path(pattern string) *Mux

                        Path returns a new multiplexer who matches an HTTP request path based on the given regexp pattern.

                        func Query

                        func Query(key, pattern string) *Mux

                          Query returns a new multiplexer who matches an HTTP request query param based on the given key and regexp pattern.

                          func RequestHeader

                          func RequestHeader(key, pattern string) *Mux

                            RequestHeader returns a new multiplexer who matches an HTTP request header field based on the given key and regexp pattern.

                            func ResponseHeader

                            func ResponseHeader(key, pattern string) *Mux

                              ResponseHeader returns a new multiplexer who matches an HTTP response header field based on the given key and regexp pattern.

                              func ServerError

                              func ServerError() *Mux

                                ServerError returns a new multiplexer who matches response errors by the server.

                                func Status

                                func Status(codes ...int) *Mux

                                  Status returns a new multiplexer who matches an HTTP response status code based on the given status codes.

                                  func StatusRange

                                  func StatusRange(start, end int) *Mux

                                    StatusRange returns a new multiplexer who matches an HTTP response status code based on the given status range, including both numbers.

                                    func Type

                                    func Type(kind string) *Mux

                                      Type returns a new multiplexer who matches an HTTP response Content-Type header field based on the given type string.

                                      func URL

                                      func URL(pattern string) *Mux

                                        URL returns a new multiplexer who matches an HTTP request URL based on the given regexp pattern.

                                        func (*Mux) AddMatcher

                                        func (m *Mux) AddMatcher(matchers ...Matcher) *Mux

                                          AddMatcher adds a new matcher function in the current mumultiplexer matchers stack.

                                          func (*Mux) Clone

                                          func (m *Mux) Clone() middleware.Middleware

                                            Clone creates a new Middleware instance based on the current one.

                                            func (*Mux) Flush

                                            func (m *Mux) Flush()

                                              Flush flushes the plugins stack.

                                              func (*Mux) GetStack

                                              func (m *Mux) GetStack() []plugin.Plugin

                                                GetStack gets the current middleware plugins stack.

                                                func (*Mux) Handler

                                                func (m *Mux) Handler() c.HandlerFunc

                                                  Handler returns the function handler to match an incoming HTTP transacion and trigger the equivalent middleware phase.

                                                  func (*Mux) Match

                                                  func (m *Mux) Match(ctx *c.Context) bool

                                                    Match matches the give Context againts a list of matchers and returns `true` if all the matchers passed.

                                                    func (*Mux) Run

                                                    func (m *Mux) Run(phase string, ctx *c.Context) *c.Context

                                                      Run triggers the middleware call chain for the given phase.

                                                      func (*Mux) SetStack

                                                      func (m *Mux) SetStack(stack []plugin.Plugin)

                                                        SetStack sets the middleware plugin stack overriding the existent one.

                                                        func (*Mux) Use

                                                        func (m *Mux) Use(p plugin.Plugin) *Mux

                                                          Use registers a new plugin in the middleware stack.

                                                          func (*Mux) UseError

                                                          func (m *Mux) UseError(fn c.HandlerFunc) *Mux

                                                            UseError registers a new error phase middleware handler.

                                                            func (*Mux) UseHandler

                                                            func (m *Mux) UseHandler(phase string, fn c.HandlerFunc) *Mux

                                                              UseHandler registers a new error phase middleware handler.

                                                              func (*Mux) UseParent

                                                              func (m *Mux) UseParent(parent middleware.Middleware) *Mux

                                                                UseParent attachs a parent middleware.

                                                                func (*Mux) UseRequest

                                                                func (m *Mux) UseRequest(fn c.HandlerFunc) *Mux

                                                                  UseRequest registers a new request phase middleware handler.

                                                                  func (*Mux) UseResponse

                                                                  func (m *Mux) UseResponse(fn c.HandlerFunc) *Mux

                                                                    UseResponse registers a new response phase middleware handler.