README

gentleman/context Build Status GoDoc API Go Report Card

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

    Constants

    This section is empty.

    Variables

    View Source
    var Key interface{} = "$gentleman"

      Key stores the key identifier for the built-in context

      Functions

      This section is empty.

      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.