context

Documentation

Overview

Package gorilla/context provides utilities to manage request contexts.

A context stores global values for HTTP requests in a thread-safe manner. The original idea was posted by Brad Fitzpatrick to the go-nuts mailing list:

http://groups.google.com/group/golang-nuts/msg/e2d679d303aa5d53

Any library that needs to set request variables to be accessed by handlers can set up a namespace to store those variables. First you create a namespace:

var ns = new(context.Namespace)

...then call Set() or Get() as needed to define or retrieve request variables:

// val is nil because we haven't set any value yet.
val := ns.Get(request)

// let's set a value, then.
ns.Set(request, "foo")

// val is now "foo".
val = ns.Get(request)

You can store any type in the request context, because it accepts and returns interface{}. To enforce a given type, wrap the getter and setter to accept and return values of a specific type ("SomeType" in this example):

ns = new(context.Namespace)

// Val returns a value for this package from the request context.
func Val(request *http.Request) SomeType {
	rv := ns.Get(request)
	if rv != nil {
		return rv.(SomeType)
	}
	return nil
}

// SetVal sets a value for this package in the request context.
func SetVal(request *http.Request, val SomeType) {
	ns.Set(request, val)
}

Notice that we now perform type casting in Val(), but set the value directly in SetVal().

To access the namespace variable inside a handler, call the namespace getter function passing the current request. For the previous example we would do:

func someHandler(w http.ResponseWriter, r *http.Request) {
	val := Val(req)

	// ...
}

Make sure that the main handler clears the context after serving a request:

func handler(w http.ResponseWriter, r *http.Request) {
	defer context.DefaultContext.Clear(r)

	// ...
}

This calls Clear() from the Context instance, removing all namespaces registered for a request.

The package gorilla/mux clears the default context, so if you are using the default handler from there you don't need to clear anything: any namespaces set using the default context will be cleared at the end of a request.

Index

• Variables
• type Context
  • func (c *Context) Clear(req *http.Request)
  • func (c *Context) ClearNamespace(req *http.Request, ns Namespacer)
  • func (c *Context) Get(req *http.Request, ns Namespacer) interface{}
  • func (c *Context) Set(req *http.Request, ns Namespacer, val interface{})
• type Namespace
  • func (n *Namespace) Clear(request *http.Request)
  • func (n *Namespace) Get(request *http.Request) interface{}
  • func (n *Namespace) GetContext() *Context
  • func (n *Namespace) Set(request *http.Request, val interface{})
• type Namespacer

Variables

var DefaultContext = new(Context)

DefaultContext is the default context instance.

Types

type Context

type Context struct {
	// contains filtered or unexported fields
}

Context stores values for requests.

func (*Context) Clear

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

Clear removes all namespaces for a given request.

func (*Context) ClearNamespace

func (c *Context) ClearNamespace(req *http.Request, ns Namespacer)

ClearNamespace removes the value from a given namespace in a given request.

func (*Context) Get

func (c *Context) Get(req *http.Request, ns Namespacer) interface{}

Get returns the value for a given namespace in a given request.

func (*Context) Set

func (c *Context) Set(req *http.Request, ns Namespacer, val interface{})

Set stores a value for a given namespace in a given request.

type Namespace

type Namespace struct {
	Context *Context
}

Namespace is a namespace to store a value in the request context.

Packages can use one or more namespaces to attach variables to the request. Fist you define a namespace:

var ns = new(context.Namespace)

...then call Set() or Get() as needed to define or retrieve request variables:

// val is nil because we haven't set any value yet.
val := ns.Get(request)

// let's set a value, then.
ns.Set(request, "foo")

// val is now "foo".
val = ns.Get(request)

Each namespace can store a single value, but it can be of any type since Context accepts and returns a interface{} type.

func (*Namespace) Clear

func (n *Namespace) Clear(request *http.Request)

Clear removes this namespace from the request context.

func (*Namespace) Get

func (n *Namespace) Get(request *http.Request) interface{}

Get returns the value stored for this namespace in the request context.

func (*Namespace) GetContext

func (n *Namespace) GetContext() *Context

GetContext returns the request context this namespace is attached to.

If no context was explicitly defined, it will use DefaultContext.

func (*Namespace) Set

func (n *Namespace) Set(request *http.Request, val interface{})

Set stores a value for this namespace in the request context.

type Namespacer

type Namespacer interface {
	Set(*http.Request, interface{})
	Get(*http.Request) interface{}
	Clear(*http.Request)
}

Namespacer is the interface for context namespaces.