Documentation ¶
Overview ¶
__WARNING: WORK IN PROGRESS__
Forgery is a minimal and flexible golang web application framework, providing a robust set of features for building single and multi-page, web applications.
Note: This project started out as a clone of the superb Node.js library [Express](http://expressjs.com/).
Index ¶
- Constants
- Variables
- func Decode(value string) (string, error)
- func Encode(value string) string
- func Sign(v string, s string) string
- func StringSliceReverse(in []string) (out []string)
- func Unsign(v string, s string) string
- type Renderer
- type Request
- func (this *Request) Accepted() []string
- func (this *Request) AcceptedCharsets() []string
- func (this *Request) AcceptedLanguages() []string
- func (this *Request) Accepts(t string) bool
- func (this *Request) AcceptsCharset(c string) bool
- func (this *Request) AcceptsLanguage(l string) bool
- func (this *Request) Cookie(n string, i ...interface{}) string
- func (this *Request) Fresh() bool
- func (this *Request) Get(f string) string
- func (this *Request) Is(t string) bool
- func (this *Request) Param(n string) string
- func (this *Request) SetApplication(app *Server)
- func (this *Request) SetResponse(res *Response)
- func (this *Request) SignedCookie(n string, i ...interface{}) string
- func (this *Request) Stale() bool
- func (this *Request) Subdomains() []string
- type Response
- func (this *Response) Attachment(f ...string)
- func (this *Response) ClearCookie(n string, o ...*http.Cookie)
- func (this *Response) Clone() *Response
- func (this *Response) ContentType(t string)
- func (this *Response) Cookie(n string, i interface{}, o ...*http.Cookie)
- func (this *Response) Download(path string, f ...string)
- func (this *Response) Etag(body string) string
- func (this *Response) Format(opt map[string]func())
- func (this *Response) Get(f string) string
- func (this *Response) Json(i interface{}, s ...int)
- func (this *Response) Jsonp(i interface{}, s ...int)
- func (this *Response) Links(link string, rel string)
- func (this *Response) Location(uri string)
- func (this *Response) Redirect(uri string, s ...int)
- func (this *Response) Render(view string, i ...interface{})
- func (this *Response) Send(b interface{}, s ...int)
- func (this *Response) Sendfile(filename string, opt ...interface{})
- func (this *Response) Set(f string, v string)
- func (this *Response) SetApplication(app *Server)
- func (this *Response) SetNext(next func())
- func (this *Response) SetRequest(req *Request)
- func (this *Response) SignedCookie(n string, i interface{}, o ...*http.Cookie)
- func (this *Response) Status(c int)
- func (this *Response) Vary(field string)
- type Route
- type Router
- type Server
- func (this *Server) All(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Checkout(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Configure(i ...interface{})
- func (this *Server) Copy(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Delete(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Disable(n string)
- func (this *Server) Disabled(n string) bool
- func (this *Server) Enable(n string)
- func (this *Server) Enabled(n string) bool
- func (this *Server) Engine(ext string, fn Renderer)
- func (this *Server) Get(path string, fn ...func(*Request, *Response, func())) string
- func (this *Server) Head(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Lock(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Merge(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Mkactivity(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Mkcol(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Move(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Msearch(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Notify(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Options(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Param(p string, fn func(*Request, *Response, func()))
- func (this *Server) Patch(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Path() string
- func (this *Server) Post(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Propfind(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Proppatch(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Put(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Render(view string, i ...interface{}) (string, error)
- func (this *Server) Report(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Set(n string, v ...string) string
- func (this *Server) Subscribe(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Trace(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Unlock(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Unsubscribe(path string, fn ...func(*Request, *Response, func()))
- func (this *Server) Verb(verb string, path string, funcs ...func(*Request, *Response, func()))
Constants ¶
const ( TRUE = "true" FALSE = "false" )
Variables ¶
var ErrorHandler = stackr.ErrorHandler
Convenience attribute for accessing "stackr.ErrorHandler".
var Favicon = stackr.Favicon
Convenience attribute for accessing "stackr.Favicon".
var Logger = stackr.Logger
Convenience attribute for accessing "stackr.Logger".
var MethodOverride = stackr.MethodOverride
Convenience attribute for accessing "stackr.MethodOverride".
var ResponseTime = stackr.ResponseTime
Convenience attribute for accessing "stackr.ResponseTime".
var Static = stackr.Static
Convenience attribute for accessing "stackr.Static".
Functions ¶
func StringSliceReverse ¶
Reverses a slice of strings.
Types ¶
type Request ¶
type Request struct { // The stackr.Request type. *stackr.Request // Return the remote address, or when "trust proxy" is enabled - the upstream address. Ip string // When "trust proxy" is `true`, parse the "X-Forwarded-For" ip address list and return a slice, // otherwise an empty slice is returned. For example if the value were "client, proxy1, proxy2" // you would receive the slice {"client", "proxy1", "proxy2"} where "proxy2" is the furthest down-stream. Ips []string // Returns the request URL pathname. Path string // Check if the request was issued with the "X-Requested-With" header field set to "XMLHttpRequest" (jQuery etc). Xhr bool // Return the protocol string "http" or "https" when requested with TLS. // When the "trust proxy" setting is enabled the "X-Forwarded-Proto" header field will be trusted. // If you're running behind a reverse proxy that supplies https for you this may be enabled. Protocol string // Check if a TLS connection is established. This is a short-hand for: "https" == req.Protocol Secure bool // This property is a slice containing properties mapped to the named route "parameters". // For example if you have the route "/user/:name", then the "name" property is available // to you as req.params["name"]. This object defaults to {}. Params map[string]string // The currently matched Route containing several properties such as the // route's original path string, the regexp generated, and so on. Route *Route // contains filtered or unexported fields }
A Request represents an HTTP request received by the server.
func (*Request) Accepted ¶
Return an slice of Accepted media types ordered from highest quality to lowest.
func (*Request) AcceptedCharsets ¶
Return an slice of Accepted charsets ordered from highest quality to lowest.
func (*Request) AcceptedLanguages ¶
Return an slice of Accepted languages ordered from highest quality to lowest.
func (*Request) Accepts ¶
Check if the given type is acceptable, returning true or false - in which case you should respond with 406 "Not Acceptable".
func (*Request) AcceptsCharset ¶
Check if the given "charset" is acceptable.
func (*Request) AcceptsLanguage ¶
Check if the given "lang" is acceptable.
func (*Request) Fresh ¶
WARNING: Not complete! Check if the request is fresh - aka Last-Modified and/or the ETag still match, indicating that the resource is "fresh".
func (*Request) Is ¶
Check if the incoming request contains the "Content-Type" header field, and it matches the give mime "type".
func (*Request) Param ¶
Return the value of param "name" when present. Lookup is performed in the following order:
* Params * Body * Query
Direct access to req.body, req.params, and req.query should be favored for clarity - unless you truly accept input from each object.
func (*Request) SetApplication ¶
Set the Application this Request will use.
func (*Request) SetResponse ¶
Set the Response this Response will use.
func (*Request) SignedCookie ¶
Contains the signed cookies sent by the user-agent, unsigned and ready for use. Signed cookies are accessed by a different function to show developer intent, otherwise a malicious attack could be placed on `req.Cookie` values which are easy to spoof. Note that signing a cookie does not mean it is "hidden" nor encrypted, this simply prevents tampering as the secret used to sign is private.
func (*Request) Stale ¶
Check if the request is stale - aka Last-Modified and/or the ETag do not match, indicating that the resource is "stale".
func (*Request) Subdomains ¶
Return subdomains as a slice of strings.
type Response ¶
type Response struct { // The stackr.Response. *stackr.Response // Assign the charset. Defaults to "utf-8". Charset string // Response local variables are scoped to the request, thus only available // to the view(s) rendered during that request / response cycle, if any. // Otherwise this API is identical to app.Locals. Locals map[string]string // contains filtered or unexported fields }
Response represents the response from an HTTP request.
func (*Response) Attachment ¶
Sets the Content-Disposition header field to "attachment". If a filename is given then the Content-Type will be automatically set based on the extname via res.Type(), and the Content-Disposition's "filename=" parameter will be set.
res.Attachment(); // Content-Disposition: attachment
res.Attachment('path/to/logo.png'); // Content-Disposition: attachment; filename="logo.png" // Content-Type: image/png
func (*Response) ClearCookie ¶
Clear cookie "name". The "path" option defaults to "/".
func (*Response) ContentType ¶
Sets the Content-Type to the mime lookup of type, or when "/" is present the Content-Type is simply set to this literal value.
Examples:
res.type('.html'); res.type('html'); res.type('json'); res.type('application/json'); res.type('png');
func (*Response) Cookie ¶
Set cookie "name" to "value", where "value" may be a string or interface converted to JSON. The "path" option defaults to "/".
Set cookie `name` to `val`, with the given `options`.
Options:
- `maxAge` max-age in milliseconds, converted to `expires`
- `signed` sign the cookie
- `path` defaults to "/"
Examples:
// "Remember Me" for 15 minutes res.Cookie("rememberme", "1", &httpCookie{ expires: new Date(Date.now() + 900000), httpOnly: true }); // save as above res.Cookie("rememberme", "1", &httpCookie{ maxAge: 900000, httpOnly: true })
func (*Response) Download ¶
Transfer the file at path as an "attachment", typically browsers will prompt the user for download. The Content-Disposition "filename=" parameter, aka the one that will appear in the browser dialog is set to path by default, however you may provide an override filename.
func (*Response) Format ¶
Performs content-negotiation on the request Accept header field when present. This method uses "req.Accepted", a slice of acceptable types ordered by their quality values, otherwise the first callback is invoked. When no match is performed the server responds with 406 "Not Acceptable", or invokes the "default" callback.
func (*Response) Json ¶
Send a JSON response. This method is identical to res.Send() when an object or slice is passed, however it may be used for explicit JSON conversion of non-objects (null, undefined, etc), though these are technically not valid JSON.
res.Json(null) res.Json(map[string]string{"user": "ric"}) res.Json(map[string]string{"error": "msg"}, 500)
func (*Response) Jsonp ¶
Send a JSON response with JSONP support. This method is identical to "res.Json()" however opts-in to JSONP callback support.
func (*Response) Links ¶
Use the given "link", "rel" to populate the "Link" response header field. If the filed is already set the given "link", "rel" will be appended.
func (*Response) Redirect ¶
Redirect to the given "url" with optional "status" code defaulting to 302 "Found".
func (*Response) Send ¶
Send a response. This method performs a myriad of useful tasks for simple non-streaming responses such as automatically assigning the Content-Length unless previously defined and providing automatic HEAD and HTTP cache freshness support.
res.Send([]byte{114, 105, 99}]); res.Send(map[string]string{"some": "json"}); res.Send("some html"); res.Send("Sorry, we cannot find that!", 404); res.Send(map[string]string{"error": "msg"}, 500); res.Send(200);
func (*Response) Sendfile ¶
Transfer the file at the given path. Automatically defaults the Content-Type response header field based on the filename's extension.
func (*Response) SetApplication ¶
Set the Application this Response will use.
func (*Response) SetNext ¶
func (this *Response) SetNext(next func())
Set the Next function this Response will use.
func (*Response) SetRequest ¶
Set the Request this Response will use.
func (*Response) SignedCookie ¶
type Route ¶
type Route struct { // HTTP Method Method string // URL Path Path string // The regex used to match the route. Regex *regexp.Regexp // Slice of functions Callbacks []func(*Request, *Response, func()) // The slice of param names to return from the path. ParamNames []string // Enable case-sensitive routes CaseSensitive bool // Enable strict matching for trailing slashes Strict bool }
func (*Route) CompileRegex ¶
Parse the given path to return a regex and slice of param names.
Path: /foo/:param1/bar/:param2/baz => ^/foo/(.*)/bar/(.*)/baz$ => [":param1", :param2]
type Router ¶
type Router struct { // Holds the route mappings this Router will use. Routes []*Route // Params that trigger functions ParamFuncs map[string]func(*Request, *Response, func()) // Enable case-sensitive routes CaseSensitive bool // Enable strict matching for trailing slashes Strict bool }
func (*Router) AddParamFunc ¶
Add a "param" function to the Router.
type Server ¶
type Server struct { // A stackr.Server type *stackr.Server // Application local variables are provided to all templates rendered within the application. // This is useful for providing helper functions to templates, as well as app-level data. Locals map[string]string // The Router middleware function. Router *Router // contains filtered or unexported fields }
func CreateServer ¶
func CreateServer() *Server
Create a new stackr server.
* "env" Environment mode, defaults to $GO_ENV or "development" * "trust proxy" Enables reverse proxy support, disabled by default * "jsonp callback name" Changes the default callback name of "?callback=" * "json spaces" JSON response spaces for formatting, defaults to 2 in development, 0 in production * "case sensitive routing" Enable case sensitivity, disabled by default, treating "/Foo" and "/foo" as the same * "strict routing" Enable strict routing, by default "/foo" and "/foo/" are treated the same by the router * X "view cache" Enables view template compilation caching, enabled in production by default * "view engine" The default engine extension to use when omitted * "views" The view directory path, defaulting to "./views"
func (*Server) All ¶
This method functions just like the app.Verb(verb, ...) method, however it matches all HTTP verbs.
func (*Server) Checkout ¶
The method provides the routing functionality for CHECKOUT requests to the given "path".
func (*Server) Configure ¶
func (this *Server) Configure(i ...interface{})
Configure callback for zero or more envs, when no `env` is specified that callback will be invoked for all environments. Any combination can be used multiple times, in any order desired.
Examples:
app.Configure(func() { // executed for all envs }) app.Configure("stage", func() { // executed staging env }) app.Configure("stage", "production", func() { // executed for stage and production })
Note:
These callbacks are invoked immediately, and are effectively sugar for the following:
var env = os.Getenv("GO_ENV")
switch (env) { case 'development': ... case 'stage': ... case 'production': ... }
func (*Server) Copy ¶
The method provides the routing functionality for COPY requests to the given "path".
func (*Server) Delete ¶
The method provides the routing functionality for DELETE requests to the given "path".
func (*Server) Get ¶
Get setting "name" value. or; Provides the routing functionality for GET requests to the given "path".
func (*Server) Head ¶
The method provides the routing functionality for HEAD requests to the given "path".
func (*Server) Lock ¶
The method provides the routing functionality for LOCK requests to the given "path".
func (*Server) Merge ¶
The method provides the routing functionality for MERGE requests to the given "path".
func (*Server) Mkactivity ¶
The method provides the routing functionality for MKACTIVITY requests to the given "path".
func (*Server) Mkcol ¶
The method provides the routing functionality for MKCOL requests to the given "path".
func (*Server) Move ¶
The method provides the routing functionality for MOVE requests to the given "path".
func (*Server) Msearch ¶
The method provides the routing functionality for M-SEARCH requests to the given "path".
func (*Server) Notify ¶
The method provides the routing functionality for NOTIFY requests to the given "path".
func (*Server) Options ¶
The method provides the routing functionality for OPTIONS requests to the given "path".
func (*Server) Param ¶
Map logic to route parameters. For example when ":user" is present in a route path you may map user loading logic to automatically provide req.Map["user"] to the route, or perform validations on the parameter input.
func (*Server) Patch ¶
The method provides the routing functionality for PATCH requests to the given "path".
func (*Server) Post ¶
The method provides the routing functionality for POST requests to the given "path".
func (*Server) Propfind ¶
The method provides the routing functionality for PROPFIND requests to the given "path".
func (*Server) Proppatch ¶
The method provides the routing functionality for PROPPATCH requests to the given "path".
func (*Server) Put ¶
The method provides the routing functionality for PUT requests to the given "path".
func (*Server) Render ¶
Render a "view" responding with the rendered string. This is the app-level variant of "res.render()", and otherwise behaves the same way.
func (*Server) Report ¶
The method provides the routing functionality for REPORT requests to the given "path".
func (*Server) Subscribe ¶
The method provides the routing functionality for SUBSCRIBE requests to the given "path".
func (*Server) Trace ¶
The method provides the routing functionality for TRACE requests to the given "path".
func (*Server) Unlock ¶
The method provides the routing functionality for UNLOCK requests to the given "path".
func (*Server) Unsubscribe ¶
The method provides the routing functionality for UNSUBSCRIBE requests to the given "path".
func (*Server) Verb ¶
The method provides the routing functionality in Forgery, where "verb" is one of the HTTP verbs, such as app.Verb("post", ...). Multiple callbacks may be given, all are treated equally, and behave just like middleware, with the one exception that these callbacks may invoke next('route') to bypass the remaining route callback(s). This mechanism can be used to perform pre-conditions on a route then pass control to subsequent routes when there is no reason to proceed with the route matched.