gentleman.v2: gopkg.in/h2non/gentleman.v2/context Index | Files

package context

import "gopkg.in/h2non/gentleman.v2/context"

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

Package Files

context.go handler.go

Variables

var Key interface{} = "$gentleman"

Key stores the key identifier for the built-in context

type Context Uses

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 Uses

func New() *Context

New creates an empty default Context

func (*Context) Clear Uses

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 Uses

func (c *Context) Clone() *Context

Clone returns a clone of the current context.

func (*Context) CopyTo Uses

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

CopyTo copies the current context store into a new Context.

func (*Context) Deadline Uses

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 Uses

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

Delete deletes a stored value from a request’s context

func (*Context) Done Uses

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 Uses

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 Uses

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

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

func (*Context) GetAll Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

Set sets a value on the current store

func (*Context) SetRequest Uses

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

SetRequest replaces the context http.Request

func (*Context) UseParent Uses

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

UseParent uses a new parent Context

func (*Context) Value Uses

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 Uses

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 Uses

func NewHandler(fn HandlerCtx) Handler

NewHandler creates a new Handler based on a given HandlerCtx function

type HandlerCtx Uses

type HandlerCtx func(*Context)

HandlerCtx represents a Context only function handler

type HandlerFunc Uses

type HandlerFunc func(*Context, Handler)

HandlerFunc represents a middleware function handler interface

type Store Uses

type Store map[interface{}]interface{}

Store represents the map store for context store.

Package context imports 5 packages (graph) and is imported by 60 packages. Updated 2020-02-18. Refresh now. Tools for package owners.