mux

README

gentleman/mux

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

• type Matcher
• type Mux
  • func Error() *Mux
  • func Host(pattern string) *Mux
  • func If(muxes ...*Mux) *Mux
  • func Match(matchers ...Matcher) *Mux
  • func Method(methods ...string) *Mux
  • func New() *Mux
  • func Or(muxes ...*Mux) *Mux
  • func Path(pattern string) *Mux
  • func Query(key, pattern string) *Mux
  • func RequestHeader(key, pattern string) *Mux
  • func ResponseHeader(key, pattern string) *Mux
  • func ServerError() *Mux
  • func Status(codes ...int) *Mux
  • func StatusRange(start, end int) *Mux
  • func Type(kind string) *Mux
  • func URL(pattern string) *Mux
  • func (m *Mux) AddMatcher(matchers ...Matcher) *Mux
  • func (m *Mux) Clone() middleware.Middleware
  • func (m *Mux) Flush()
  • func (m *Mux) GetStack() []plugin.Plugin
  • func (m *Mux) Handler() c.HandlerFunc
  • func (m *Mux) Match(ctx *c.Context) bool
  • func (m *Mux) Run(phase string, ctx *c.Context) *c.Context
  • func (m *Mux) SetStack(stack []plugin.Plugin)
  • func (m *Mux) Use(p plugin.Plugin) *Mux
  • func (m *Mux) UseError(fn c.HandlerFunc) *Mux
  • func (m *Mux) UseHandler(phase string, fn c.HandlerFunc) *Mux
  • func (m *Mux) UseParent(parent middleware.Middleware) *Mux
  • func (m *Mux) UseRequest(fn c.HandlerFunc) *Mux
  • func (m *Mux) UseResponse(fn c.HandlerFunc) *Mux

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.