context

README

context

gorilla/context is a general purpose registry for global request variables.

Read the full documentation here: http://www.gorillatoolkit.org/pkg/context

Documentation

Overview

Package context stores values shared during a request lifetime.

For example, a router can set variables extracted from the URL and later application handlers can access those values, or it can be used to store sessions values to be saved at the end of a request. There are several others common uses.

The idea was posted by Brad Fitzpatrick to the go-nuts mailing list:

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

Here's the basic usage: first define the keys that you will need. The key type is interface{} so a key can be of any type that supports equality. Here we define a key using a custom int type to avoid name collisions:

package foo

import (
	"github.com/gorilla/context"
)

type key int

const MyKey key = 0

Then set a variable. Variables are bound to an http.Request object, so you need a request instance to set a value:

context.Set(r, MyKey, "bar")

The application can later access the variable using the same key you provided:

func MyHandler(w http.ResponseWriter, r *http.Request) {
	// val is "bar".
	val := context.Get(r, foo.MyKey)

	// returns ("bar", true)
	val, ok := context.GetOk(r, foo.MyKey)
	// ...
}

And that's all about the basic usage. We discuss some other ideas below.

Any type can be stored in the context. To enforce a given type, make the key private and wrap Get() and Set() to accept and return values of a specific type:

type key int

const mykey key = 0

// GetMyKey returns a value for this package from the request values.
func GetMyKey(r *http.Request) SomeType {
	if rv := context.Get(r, mykey); rv != nil {
		return rv.(SomeType)
	}
	return nil
}

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

Variables must be cleared at the end of a request, to remove all values that were stored. This can be done in an http.Handler, after a request was served. Just call Clear() passing the request:

context.Clear(r)

...or use ClearHandler(), which conveniently wraps an http.Handler to clear variables at the end of a request lifetime.

The Routers from the packages gorilla/mux and gorilla/pat call Clear() so if you are using either of them you don't need to clear the context manually.

Index

• func Clear(r *http.Request)
• func ClearHandler(h http.Handler) http.Handler
• func Delete(r *http.Request, key interface{})
• func Get(r *http.Request, key interface{}) interface{}
• func GetAll(r *http.Request) map[interface{}]interface{}
• func GetAllOk(r *http.Request) (map[interface{}]interface{}, bool)
• func GetOk(r *http.Request, key interface{}) (interface{}, bool)
• func Purge(maxAge int) int
• func Set(r *http.Request, key, val interface{})

Functions

func Clear

func Clear(r *http.Request)

Clear removes all values stored for a given request.

This is usually called by a handler wrapper to clean up request variables at the end of a request lifetime. See ClearHandler().

func ClearHandler

func ClearHandler(h http.Handler) http.Handler

ClearHandler wraps an http.Handler and clears request values at the end of a request lifetime.

func Delete

func Delete(r *http.Request, key interface{})

Delete removes a value stored for a given key in a given request.

func Get

func Get(r *http.Request, key interface{}) interface{}

Get returns a value stored for a given key in a given request.

func GetAll

func GetAll(r *http.Request) map[interface{}]interface{}

GetAll returns all stored values for the request as a map. Nil is returned for invalid requests.

func GetAllOk

func GetAllOk(r *http.Request) (map[interface{}]interface{}, bool)

GetAllOk returns all stored values for the request as a map and a boolean value that indicates if the request was registered.

func GetOk

func GetOk(r *http.Request, key interface{}) (interface{}, bool)

GetOk returns stored value and presence state like multi-value return of map access.

func Purge

func Purge(maxAge int) int

Purge removes request data stored for longer than maxAge, in seconds. It returns the amount of requests removed.

If maxAge <= 0, all request data is removed.

This is only used for sanity check: in case context cleaning was not properly set some request data can be kept forever, consuming an increasing amount of memory. In case this is detected, Purge() must be called periodically until the problem is fixed.

func Set

func Set(r *http.Request, key, val interface{})

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