1// Copyright 2012 The Gorilla Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5/*
6Package context stores values shared during a request lifetime.
7
8Note: gorilla/context, having been born well before `context.Context` existed,
9does not play well > with the shallow copying of the request that
10[`http.Request.WithContext`](https://golang.org/pkg/net/http/#Request.WithContext)
11(added to net/http Go 1.7 onwards) performs. You should either use *just*
12gorilla/context, or moving forward, the new `http.Request.Context()`.
13
14For example, a router can set variables extracted from the URL and later
15application handlers can access those values, or it can be used to store
16sessions values to be saved at the end of a request. There are several
17others common uses.
18
19The idea was posted by Brad Fitzpatrick to the go-nuts mailing list:
20
21	http://groups.google.com/group/golang-nuts/msg/e2d679d303aa5d53
22
23Here's the basic usage: first define the keys that you will need. The key
24type is interface{} so a key can be of any type that supports equality.
25Here we define a key using a custom int type to avoid name collisions:
26
27	package foo
28
29	import (
30		"github.com/gorilla/context"
31	)
32
33	type key int
34
35	const MyKey key = 0
36
37Then set a variable. Variables are bound to an http.Request object, so you
38need a request instance to set a value:
39
40	context.Set(r, MyKey, "bar")
41
42The application can later access the variable using the same key you provided:
43
44	func MyHandler(w http.ResponseWriter, r *http.Request) {
45		// val is "bar".
46		val := context.Get(r, foo.MyKey)
47
48		// returns ("bar", true)
49		val, ok := context.GetOk(r, foo.MyKey)
50		// ...
51	}
52
53And that's all about the basic usage. We discuss some other ideas below.
54
55Any type can be stored in the context. To enforce a given type, make the key
56private and wrap Get() and Set() to accept and return values of a specific
57type:
58
59	type key int
60
61	const mykey key = 0
62
63	// GetMyKey returns a value for this package from the request values.
64	func GetMyKey(r *http.Request) SomeType {
65		if rv := context.Get(r, mykey); rv != nil {
66			return rv.(SomeType)
67		}
68		return nil
69	}
70
71	// SetMyKey sets a value for this package in the request values.
72	func SetMyKey(r *http.Request, val SomeType) {
73		context.Set(r, mykey, val)
74	}
75
76Variables must be cleared at the end of a request, to remove all values
77that were stored. This can be done in an http.Handler, after a request was
78served. Just call Clear() passing the request:
79
80	context.Clear(r)
81
82...or use ClearHandler(), which conveniently wraps an http.Handler to clear
83variables at the end of a request lifetime.
84
85The Routers from the packages gorilla/mux and gorilla/pat call Clear()
86so if you are using either of them you don't need to clear the context manually.
87*/
88package context
89