Documentation ¶
Index ¶
- Variables
- func Go()
- func IdentifyUsersWith(ui UserIdentifier)
- func JsonBroker(r *Request, status int, body interface{}, data *RouteData) (int, string)
- func SetApp(g gdgt)
- func XmlBroker(r *Request, status int, body interface{}, data *RouteData) (int, string)
- type AnonymousUser
- type App
- func (a *App) Accept(mimes ...string) *contentType
- func (a *App) HandleFunc(mount string, handler http.HandlerFunc) *route
- func (a *App) Handler() http.HandlerFunc
- func (a *App) Prefixed(prefix string, nested ...*route) *route
- func (a *App) Register(clist ...Controller)
- func (a *App) Resource(controllerName string, nested ...*route) *route
- func (a *App) Routes(rtes ...*route)
- func (a *App) SetIndex(controllerName string) *route
- type Broker
- type Controller
- type DefaultController
- func (c *DefaultController) Create(r *Request) (int, interface{})
- func (c *DefaultController) Destroy(r *Request) (int, interface{})
- func (c *DefaultController) Filter(verbs []string, filter Filter)
- func (c *DefaultController) IdPattern() string
- func (c *DefaultController) Index(r *Request) (int, interface{})
- func (c *DefaultController) Plural() string
- func (c *DefaultController) Show(r *Request) (int, interface{})
- func (c *DefaultController) Update(r *Request) (int, interface{})
- type Filter
- type ListRoutes
- type Request
- type Response
- type RouteData
- type User
- type UserIdentifier
Constants ¶
This section is empty.
Variables ¶
var ( SetDebugWith = func(r *Request) bool { return false } RequestLogger = func(r *Request, status, contentLength int) string { return fmt.Sprintf(`[%s] "%s %s %s" %d %d`, time.Now().Format(time.RFC822), r.Method, r.URL.Path, r.Proto, status, contentLength) } )
SetDebugWith by default is a function that always returns false, no matter what request is passed to it.
Functions ¶
func IdentifyUsersWith ¶
func IdentifyUsersWith(ui UserIdentifier)
IdentifyUsersWith allows Gadget applications to register a UserIdentifier function to be called when processing each incoming request. The return value of the UserIdentifier will be set on the Request object if not nil; AnonymousUser will be used otherwise.
func JsonBroker ¶
JsonBroker attempts to transform an interface{} value into a JSON string.
Types ¶
type AnonymousUser ¶
type AnonymousUser struct { }
AnonymousUser is the default User type if the UserIdentifier registered by the application returns nil or if there is no UserIdentifier.
func (*AnonymousUser) Authenticated ¶
func (u *AnonymousUser) Authenticated() bool
Authenticated for AnonymousUser will always return false.
type App ¶
type App struct { Brokers map[string]Broker Controllers map[string]Controller // contains filtered or unexported fields }
App provides core Gadget functionality.
func (*App) Accept ¶
Accept registers MIME type strings with the App. Via can be called on its return value to associated those MIME types with a Broker.
func (*App) HandleFunc ¶
func (a *App) HandleFunc(mount string, handler http.HandlerFunc) *route
HandleFunc mounts an http.HandlerFunc at the specified URL.
func (*App) Handler ¶
func (a *App) Handler() http.HandlerFunc
Handler returns a func encapsulating the Gadget router (and corresponding controllers that can be used in a call to http.HandleFunc. Handler must be invoked only after Routes has been called and all Controllers have been registered.
In theory, Gadget users will not ever have to call Handler, as Gadget will set up http.HandleFunc to use its return value.
func (*App) Prefixed ¶
Prefixed mounts routes at a URL path that is not necessarily a controller name.
func (*App) Register ¶
func (a *App) Register(clist ...Controller)
Register notifies Gadget that you want to use a type as a Controller. It takes a variable number of arguments, all of which must be pointers to struct types that embed DefaultController. It will panic if the name of the Controller is not in the form <resource name>Controller or if a struct value is passed instead of a pointer.
Register makes naive assumptions about the name of your Controller; firstly, that it is English; secondly that it is in singular number; and thirdly, that it can be pluralized simply by appending the letter "s". Thus, "WidgetController" will be available to the Resource function for routes as "widgets", but "EntryController" as "entrys", unless you define the Plural method on the Controller to return something more correct.
func (*App) Resource ¶
Resource creates a route to the specified controller and optionally creates additional routes nested under it.
type Broker ¶
Broker functions transform an interface{} value into a string for the body of a response
type Controller ¶
type Controller interface { Index(r *Request) (int, interface{}) Show(r *Request) (int, interface{}) Create(r *Request) (int, interface{}) Update(r *Request) (int, interface{}) Destroy(r *Request) (int, interface{}) Filter(verbs []string, filter Filter) IdPattern() string Plural() string // contains filtered or unexported methods }
Controller is the interface that defines how Gadget applications respond to HTTP requests at a given URL with a particular HTTP verb. Controllers have five primary methods for handling requests. For a Controller mounted at /foo, requests are routed to methods as follows:
GET /foo Index POST /foo Create GET /foo/<idPattern> Show PUT /foo/<idPattern> Update DELETE /foo/<idPattern> Destroy
Each of these methods takes a *gadget.Request as its only argument and returns an HTTP status code as an int and an interface{} value as the body. The interface{} value is then cast to a string, serialized, used as a template context, etc. according to the application's broker configuration.
Any other exported method with a signature of (*gadget.Request) (int, interface{}) will also be routable. For example, if the controller mounted above at /foo defines a method AllTheThings(r *gadget.Request) (int, interface{}), Gadget will route any request for /foo/all-the-things, regardless of verb, to that method.
Controller also requires two methods that enable users to customize routing options to this controller, IdPattern and Plural. The final exported method of the Controller interface is Filter, which allows for abstracting common patterns from multiple Controller methods. All three of these methods are documented in the fallback implementations provided by DefaultController.
Applications must inform Gadget of the existence of Controller types using the Register function.
type DefaultController ¶
type DefaultController struct {
// contains filtered or unexported fields
}
DefaultController satisfies the Controller interface, and because Controller includes unexported methods, must be embedded in any other type that implements Controller. The fallback implementations provided by DefaultController and the interactions of other Gadget machinery therewith can be summarized as follows:
- Index, Show, Create, Update, and Destroy methods all return a 404 with an empty string for the body
- The return value of IdPattern for use in routes is `\d+`
- The return value of Plural is "", which Register takes to mean "just add an 's'"
func (*DefaultController) Create ¶
func (c *DefaultController) Create(r *Request) (int, interface{})
Create implements a default return value of is (404, "").
func (*DefaultController) Destroy ¶
func (c *DefaultController) Destroy(r *Request) (int, interface{})
Destroy implements a default return value of is (404, "").
func (*DefaultController) Filter ¶
func (c *DefaultController) Filter(verbs []string, filter Filter)
Filter applies a Filter func to the Controller methods named in the string slice verbs. The strings in the slice should be the lowercased name of the default method, or for additional methods, the hyphenated string that appears in routes.
If any Filter returns non-zero number for the HTTP status, the body of the Controller method will never be executed and the response cycle will begin with the Filter.
c := &PostController{} c.Filter([]string{"create", "update", "destroy"}, func(r *gadget.Request) (int, interface{}) { if !r.User.Authenticated() { return 403, "Verboten" } } gadget.Register(c)
func (*DefaultController) IdPattern ¶
func (c *DefaultController) IdPattern() string
IdPattern returns a string that will be used in a regular expression to match a unique identifier for a resource in a URL. The matched value is then added to gadget.Request.UrlParams.
func (*DefaultController) Index ¶
func (c *DefaultController) Index(r *Request) (int, interface{})
Index implements a default return value of is (404, "").
func (*DefaultController) Plural ¶
func (c *DefaultController) Plural() string
Plural returns a string to be used as the plural form of the first word in the name of the Controller type. Note that this value needs to be the entire plural form of the word, not an ending.
func (*DefaultController) Show ¶
func (c *DefaultController) Show(r *Request) (int, interface{})
Show implements a default return value of is (404, "").
func (*DefaultController) Update ¶
func (c *DefaultController) Update(r *Request) (int, interface{})
Update implements a default return value of is (404, "").
type Filter ¶
Filter is simply a function with the same signature as a controller method minus the receiver. They are used in calls to Controller.Filter.
type ListRoutes ¶
ListRoutes provides a command to print out all routes registered with an application.
func (*ListRoutes) Desc ¶
func (c *ListRoutes) Desc() string
func (*ListRoutes) Run ¶
func (c *ListRoutes) Run()
Run prints all the routes registered with the application.
func (*ListRoutes) SetFlags ¶
func (c *ListRoutes) SetFlags()
type Request ¶
type Request struct { *http.Request Params map[string]interface{} Path string UrlParams map[string]string User User }
Request wraps an *http.Request and adds some Gadget-derived conveniences. The Params map contains either POST data, GET query parameters, or the body of the request deserialized as JSON if the request sends an Accept header of application/json. The UrlParams map contains any resource ids plucked from the URL by the router. The User is either an AnonymousUser or an object returned by the UserIdentifier that the application as registered with IdentifyUsersWith.
func (*Request) ContentType ¶
ContentType is sort of a dishonest method -- it returns the value of an Accept header if present, and falls back to Content-Type.
type Response ¶
type Response struct { Body interface{} Cookies []*http.Cookie Headers http.Header // contains filtered or unexported fields }
Response provides a wrapper around the interface{} value you would normally return for the response body in a Controller method, but gives you the ability to write headers and cookies to accompany the response.
func NewResponse ¶
func NewResponse(body interface{}) *Response
NewResponse returns a pointer to a Response with its Body and Headers values initialized.
type RouteData ¶
type RouteData struct {
ControllerName, Action, Verb string
}
RouteData provides context about the where the current request is being executed.
type User ¶
type User interface {
Authenticated() bool
}
User is the interface that wraps Gadget's pluggable authentication mechanism. Any type that provides an Authenticated method satisfies it.
type UserIdentifier ¶
UserIdentifier is a function type that returns a User type or nil based on a Request.