context

README

gentleman/context

Package context implements a simple request-aware HTTP context used by plugins and exposed by the middleware layer, designed to share polymorphic data across plugins in the middleware call chain.

It is built on top of the standard built-in context package in Go.

gentleman's context also implements a valid stdlid context.Context interface: https://golang.org/pkg/context/#Context

Installation

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

API

See godoc reference.

License

MIT - Tomas Aparicio

Documentation

Overview

Package context implements a request-aware HTTP context used by plugins and exposed by the middleware layer, designed to share polymorfic data types across plugins in the middleware call chain.

It is built on top of the standard built-in context package in Go: https://golang.org/pkg/context

gentleman's Context implements the stdlib `context.Context` interface: https://golang.org/pkg/context/#Context

Index

• Variables
• type Context
  • func New() *Context
  • func (c *Context) Clear()
  • func (c *Context) Clone() *Context
  • func (c *Context) CopyTo(newCtx *Context)
  • func (c *Context) Deadline() (deadline time.Time, ok bool)
  • func (c *Context) Delete(key interface{})
  • func (c *Context) Done() <-chan struct{}
  • func (c *Context) Err() error
  • func (c *Context) Get(key interface{}) interface{}
  • func (c *Context) GetAll() Store
  • func (c *Context) GetInt(key interface{}) (int, bool)
  • func (c *Context) GetOk(key interface{}) (interface{}, bool)
  • func (c *Context) GetString(key interface{}) string
  • func (c *Context) Root() *Context
  • func (c *Context) Set(key interface{}, value interface{})
  • func (c *Context) SetCancelContext(ctx context.Context) *Context
  • func (c *Context) SetRequest(req *http.Request)
  • func (c *Context) UseParent(ctx *Context)
  • func (c *Context) Value(key interface{}) interface{}
• type Handler
  • func NewHandler(fn HandlerCtx) Handler
• type HandlerCtx
• type HandlerFunc
• type Store

Variables

var Key interface{} = "$gentleman"

Key stores the key identifier for the built-in context

Types

type Context

type Context struct {
	// Stores the last error for the current Context
	Error error

	// Flag if the HTTP transaction was explicitly stopped in some phase
	Stopped bool

	// Context can inherit behavior and data from another Context
	Parent *Context

	// Reference to the http.Client used in the current HTTP transaction
	Client *http.Client

	// Reference to the http.Request used in the current HTTP transaction
	Request *http.Request

	// Reference to the http.Response used in the current HTTP transaction
	Response *http.Response
}

Context encapsulates required domain-specific HTTP entities to share data and entities for HTTP transactions in a middleware chain

func New

func New() *Context

New creates an empty default Context

func (*Context) Clear

func (c *Context) Clear()

Clear clears all stored values in the current request’s context. Parent context store will not be cleaned.

func (*Context) Clone

func (c *Context) Clone() *Context

Clone returns a clone of the current context.

func (*Context) CopyTo

func (c *Context) CopyTo(newCtx *Context)

CopyTo copies the current context store into a new Context.

func (*Context) Deadline

func (c *Context) Deadline() (deadline time.Time, ok bool)

Deadline returns the time when work done on behalf of this context should be canceled. Deadline returns ok==false when no deadline is set. Successive calls to Deadline return the same results.

func (*Context) Delete

func (c *Context) Delete(key interface{})

Delete deletes a stored value from a request’s context

func (*Context) Done

func (c *Context) Done() <-chan struct{}

Done returns a channel that's closed when work done on behalf of this context should be canceled. Done may return nil if this context can never be canceled. Successive calls to Done return the same value.

WithCancel arranges for Done to be closed when cancel is called; WithDeadline arranges for Done to be closed when the deadline expires; WithTimeout arranges for Done to be closed when the timeout elapses.

Done is provided for use in select statements:

// Stream generates values with DoSomething and sends them to out
// until DoSomething returns an error or ctx.Done is closed.
func Stream(ctx context.Context, out chan<- Value) error {
	for {
		v, err := DoSomething(ctx)
		if err != nil {
			return err
		}
		select {
		case <-ctx.Done():
			return ctx.Err()
		case out <- v:
		}
	}
}

See https://blog.golang.org/pipelines for more examples of how to use a Done channel for cancelation.

func (*Context) Err

func (c *Context) Err() error

Err returns a non-nil error value after Done is closed. Err returns Canceled if the context was canceled or DeadlineExceeded if the context's deadline passed. No other values for Err are defined. After Done is closed, successive calls to Err return the same value.

func (*Context) Get

func (c *Context) Get(key interface{}) interface{}

Get gets a value by key in the current or parent context

func (*Context) GetAll

func (c *Context) GetAll() Store

GetAll returns all stored context values for a request. Will always return a valid map. Returns an empty map for requests context data previously set

func (*Context) GetInt

func (c *Context) GetInt(key interface{}) (int, bool)

GetInt gets an int context value from req. Returns an empty string if key not found in the request context, or the value does not evaluate to a string

func (*Context) GetOk

func (c *Context) GetOk(key interface{}) (interface{}, bool)

GetOk gets a context value from req. Returns (nil, false) if key not found in the request context.

func (*Context) GetString

func (c *Context) GetString(key interface{}) string

GetString gets a string context value from req. Returns an empty string if key not found in the request context, or the value does not evaluate to a string

func (*Context) Root

func (c *Context) Root() *Context

Root returns the root Context looking in the parent contexts recursively. If the current context has no parent context, it will return the Context itself.

func (*Context) Set

func (c *Context) Set(key interface{}, value interface{})

Set sets a value on the current store

func (*Context) SetCancelContext

func (c *Context) SetCancelContext(ctx context.Context) *Context

SetCancelContext This will set an external context.Context as a parent to this context so cancellations can be propagated quickly and reduce resource usage.

func (*Context) SetRequest

func (c *Context) SetRequest(req *http.Request)

SetRequest replaces the context http.Request

func (*Context) UseParent

func (c *Context) UseParent(ctx *Context)

UseParent uses a new parent Context

func (*Context) Value

func (c *Context) Value(key interface{}) interface{}

Value returns the value associated with this context for key, or nil if no value is associated with key. Successive calls to Value with the same key returns the same result.

Use context values only for request-scoped data that transits processes and API boundaries, not for passing optional parameters to functions.

A key identifies a specific value in a Context. Functions that wish to store values in Context typically allocate a key in a global variable then use that key as the argument to context.WithValue and Context.Value. A key can be any type that supports equality; packages should define keys as an unexported type to avoid collisions.

Packages that define a Context key should provide type-safe accessors for the values stored using that key:

// Package user defines a User type that's stored in Contexts.
package user

import "context"

// User is the type of value stored in the Contexts.
type User struct {...}

// key is an unexported type for keys defined in this package.
// This prevents collisions with keys defined in other packages.
type key int

// userKey is the key for user.User values in Contexts. It is
// unexported; clients use user.NewContext and user.FromContext
// instead of using this key directly.
var userKey key = 0

// NewContext returns a new Context that carries value u.
func NewContext(ctx context.Context, u *User) context.Context {
	return context.WithValue(ctx, userKey, u)
}

// FromContext returns the User value stored in ctx, if any.
func FromContext(ctx context.Context) (*User, bool) {
	u, ok := ctx.Value(userKey).(*User)
	return u, ok
}

type Handler

type Handler interface {
	// Next handler invokes the next plugin in the middleware
	// call chain with the given Context
	Next(*Context)

	// Stop handler stops the current middleware call chain
	// with the given Context
	Stop(*Context)

	// Error handler reports an error and stops the middleware
	// call chain with the given Context
	Error(*Context, error)
}

Handler exposes a simple interface providing control flow capabilities to middleware functions

func NewHandler

func NewHandler(fn HandlerCtx) Handler

NewHandler creates a new Handler based on a given HandlerCtx function

type HandlerCtx

type HandlerCtx func(*Context)

HandlerCtx represents a Context only function handler

type HandlerFunc

type HandlerFunc func(*Context, Handler)

HandlerFunc represents a middleware function handler interface

type Store

type Store map[interface{}]interface{}

Store represents the map store for context store.