plugin

README

gentleman/plugin

plugin package implements a simple middleware-based plugin layer especially designed for HTTP clients and complete HTTP request/response live cycle control.

The package exposes a simple API with multiple factory helper functions to create plugins more easily.

Installation

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

API

See godoc reference.

Examples

Create a request plugin

package main

import (
  "fmt"
  "gopkg.in/h2non/gentleman.v2"
  "gopkg.in/h2non/gentleman.v2/context"
  "gopkg.in/h2non/gentleman.v2/plugin"
  "net/url"
)

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

  // Create a request plugin to define the URL
  cli.Use(plugin.NewRequestPlugin(func(ctx *context.Context, h context.Handler) {
    u, _ := url.Parse("http://httpbin.org/headers")
    ctx.Request.URL = u
    h.Next(ctx)
  }))

  // 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 plugin implements a plugin layer for gentleman components. Exports the required interface that must be implemented by plugins.

Plugins are phase-oriented middleware function handlers encapsulated in a simple interface that will be consumed by the middleware layer in order to trigger the plugin handler.

Plugin implementors can decide to build a plugin to handle a unique middleware phase or instead handle multiple phases: request, response, error...

Index

• type Handlers
• type Layer
  • func New() *Layer
  • func (p *Layer) Disable()
  • func (p *Layer) Disabled() bool
  • func (p *Layer) Enable()
  • func (p *Layer) Exec(phase string, ctx *context.Context, h context.Handler)
  • func (p *Layer) Remove()
  • func (p *Layer) Removed() bool
  • func (p *Layer) SetHandler(phase string, handler context.HandlerFunc)
  • func (p *Layer) SetHandlers(handlers Handlers)
• type Plugin
  • func NewErrorPlugin(handler context.HandlerFunc) Plugin
  • func NewPhasePlugin(phase string, handler context.HandlerFunc) Plugin
  • func NewRequestPlugin(handler context.HandlerFunc) Plugin
  • func NewResponsePlugin(handler context.HandlerFunc) Plugin

Types

type Handlers

type Handlers map[string]context.HandlerFunc

Handlers represents a map to store middleware handler functions per phase.

type Layer

type Layer struct {

	// Handlers defines the required handlers
	Handlers Handlers

	// DefaultHandler is an optional field used to store
	// a default handler for any middleware phase.
	DefaultHandler context.HandlerFunc
	// contains filtered or unexported fields
}

Layer encapsulates an Error, Request and Response function handlers

func New

func New() *Layer

New creates a new plugin layer.

func (*Layer) Disable

func (p *Layer) Disable()

Disable will disable the current plugin

func (*Layer) Disabled

func (p *Layer) Disabled() bool

Disabled returns true if the plugin is enabled

func (*Layer) Enable

func (p *Layer) Enable()

Enable will enable the current plugin

func (*Layer) Exec

func (p *Layer) Exec(phase string, ctx *context.Context, h context.Handler)

Exec executes the plugin handler for the given middleware phase passing the given context.

func (*Layer) Remove

func (p *Layer) Remove()

Remove will remove the plugin from the middleware stack

func (*Layer) Removed

func (p *Layer) Removed() bool

Removed returns true if the plugin Was removed

func (*Layer) SetHandler

func (p *Layer) SetHandler(phase string, handler context.HandlerFunc)

SetHandler uses a new handler function for the given middleware phase.

func (*Layer) SetHandlers

func (p *Layer) SetHandlers(handlers Handlers)

SetHandlers uses a new map of handler functions.

type Plugin

type Plugin interface {
	// Enable enabled the plugin
	Enable()

	// Disable disables the plugin
	Disable()

	// Disabled returns true if the plugin is enabled
	Disabled() bool

	// Remove will remove the plugin from the middleware stack
	Remove()

	// Enabled returns true if the plugin was removed
	Removed() bool

	// Exec executes the plugin handler for a specific middleware phase.
	Exec(string, *context.Context, context.Handler)
}

Plugin interface that must be implemented by plugins

func NewErrorPlugin

func NewErrorPlugin(handler context.HandlerFunc) Plugin

NewErrorPlugin creates a new plugin layer to handle error middleware phase

func NewPhasePlugin

func NewPhasePlugin(phase string, handler context.HandlerFunc) Plugin

NewPhasePlugin creates a new plugin layer to handle a given middleware phase.

func NewRequestPlugin

func NewRequestPlugin(handler context.HandlerFunc) Plugin

NewRequestPlugin creates a new plugin layer to handle request middleware phase

func NewResponsePlugin

func NewResponsePlugin(handler context.HandlerFunc) Plugin

NewResponsePlugin creates a new plugin layer to handle response middleware phase