import "github.com/gobuffalo/buffalo"
Package buffalo is a Go web development eco-system, designed to make your life easier.
Buffalo helps you to generate a web project that already has everything from front-end (JavaScript, SCSS, etc.) to back-end (database, routing, etc.) already hooked up and ready to run. From there it provides easy APIs to build your web application quickly in Go.
Buffalo **isn't just a framework**, it's a holistic web development environment and project structure that **lets developers get straight to the business** of, well, building their business.
app.go buffalo.go context.go cookies.go default_context.go error_templates.go errors.go events.go flash.go grifts.go handler.go logger.go method_override.go middleware.go options.go plugins.go request_logger.go resource.go response.go route.go route_info.go route_mappings.go routenamer.go server.go session.go wrappers.go
const (
// EvtAppStart is emitted when buffalo.App#Serve is called
EvtAppStart = "buffalo:app:start"
// EvtAppStartErr is emitted when an error occurs calling buffalo.App#Serve
EvtAppStartErr = "buffalo:app:start:err"
// EvtAppStop is emitted when buffalo.App#Stop is called
EvtAppStop = "buffalo:app:stop"
// EvtAppStopErr is emitted when an error occurs calling buffalo.App#Stop
EvtAppStopErr = "buffalo:app:stop:err"
// EvtRouteStarted is emitted when a requested route is being processed
EvtRouteStarted = "buffalo:route:started"
// EvtRouteFinished is emitted when a requested route is completed
EvtRouteFinished = "buffalo:route:finished"
// EvtRouteErr is emitted when there is a problem handling processing a route
EvtRouteErr = "buffalo:route:err"
// EvtWorkerStart is emitted when buffalo.App#Serve is called and workers are started
EvtWorkerStart = "buffalo:worker:start"
// EvtWorkerStartErr is emitted when an error occurs when starting workers
EvtWorkerStartErr = "buffalo:worker:start:err"
// EvtWorkerStop is emitted when buffalo.App#Stop is called and workers are stopped
EvtWorkerStop = "buffalo:worker:stop"
// EvtWorkerStopErr is emitted when an error occurs when stopping workers
EvtWorkerStopErr = "buffalo:worker:stop:err"
// EvtFailureErr is emitted when something can't be processed at all. it is a bad thing
EvtFailureErr = "buffalo:failure:err"
)const (
// AssetsAgeVarName is the ENV variable used to specify max age when ServeFiles is used.
AssetsAgeVarName = "ASSETS_MAX_AGE"
)var RequestLogger = RequestLoggerFunc
RequestLogger can be be overridden to a user specified function that can be used to log the request.
Grifts decorates the app with tasks
LoadPlugins will add listeners for any plugins that support "events"
func MethodOverride(res http.ResponseWriter, req *http.Request)
MethodOverride is the default implementation for the Options#MethodOverride. By default it will look for a form value name `_method` and change the request method if that is present and the original request is of type "POST". This is added automatically when using `New` Buffalo, unless an alternative is defined in the Options.
WrapBuffaloHandler wraps a buffalo.Handler to standard http.Handler
func WrapBuffaloHandlerFunc(h Handler) http.HandlerFunc
WrapBuffaloHandlerFunc wraps a buffalo.Handler to standard http.HandlerFunc
type App struct {
Options
// Middleware returns the current MiddlewareStack for the App/Group.
Middleware *MiddlewareStack `json:"-"`
ErrorHandlers ErrorHandlers `json:"-"`
// Routenamer for the app. This field provides the ability to override the
// base route namer for something more specific to the app.
RouteNamer RouteNamer
// contains filtered or unexported fields
}App is where it all happens! It holds on to options, the underlying router, the middleware, and more. Without an App you can't do much!
New returns a new instance of App and adds some sane, and useful, defaults.
ANY accepts a request across any HTTP method for the specified path and routes it to the specified Handler.
DELETE maps an HTTP "DELETE" request to the path and the specified handler.
GET maps an HTTP "GET" request to the path and the specified handler.
Group creates a new `*App` that inherits from it's parent `*App`. This is useful for creating groups of end-points that need to share common functionality, like middleware.
g := a.Group("/api/v1")
g.Use(AuthorizeAPIMiddleware)
g.GET("/users, APIUsersHandler)
g.GET("/users/:user_id, APIUserShowHandler)
HEAD maps an HTTP "HEAD" request to the path and the specified handler.
Mount mounts a http.Handler (or Buffalo app) and passes through all requests to it.
func muxer() http.Handler {
f := func(res http.ResponseWriter, req *http.Request) {
fmt.Fprintf(res, "%s - %s", req.Method, req.URL.String())
}
mux := mux.NewRouter()
mux.HandleFunc("/foo", f).Methods("GET")
mux.HandleFunc("/bar", f).Methods("POST")
mux.HandleFunc("/baz/baz", f).Methods("DELETE")
return mux
}
a.Mount("/admin", muxer())
$ curl -X DELETE http://localhost:3000/admin/baz/baz
Muxer returns the underlying mux router to allow for advance configurations
OPTIONS maps an HTTP "OPTIONS" request to the path and the specified handler.
PATCH maps an HTTP "PATCH" request to the path and the specified handler.
POST maps an HTTP "POST" request to the path and the specified handler.
PUT maps an HTTP "PUT" request to the path and the specified handler.
PanicHandler recovers from panics gracefully and calls the error handling code for a 500 error.
Redirect from one URL to another URL. Only works for "GET" requests.
Resource maps an implementation of the Resource interface to the appropriate RESTful mappings. Resource returns the *App associated with this group of mappings so you can set middleware, etc... on that group, just as if you had used the a.Group functionality.
a.Resource("/users", &UsersResource{})
// Is equal to this:
ur := &UsersResource{}
g := a.Group("/users")
g.GET("/", ur.List) // GET /users => ur.List
g.GET("/new", ur.New) // GET /users/new => ur.New
g.GET("/{user_id}", ur.Show) // GET /users/{user_id} => ur.Show
g.GET("/{user_id}/edit", ur.Edit) // GET /users/{user_id}/edit => ur.Edit
g.POST("/", ur.Create) // POST /users => ur.Create
g.PUT("/{user_id}", ur.Update) PUT /users/{user_id} => ur.Update
g.DELETE("/{user_id}", ur.Destroy) DELETE /users/{user_id} => ur.Destroy
func (a *App) RouteHelpers() map[string]RouteHelperFunc
RouteHelpers returns a map of BuildPathHelper() for each route available in the app.
Routes returns a list of all of the routes defined in this application.
Serve the application at the specified address/port and listen for OS interrupt and kill signals and will attempt to stop the application gracefully. This will also start the Worker process, unless WorkerOff is enabled.
func (a *App) ServeFiles(p string, root http.FileSystem)
ServeFiles maps an path to a directory on disk to serve static files. Useful for JavaScript, images, CSS, etc...
a.ServeFiles("/assets", http.Dir("path/to/assets"))
Stop the application and attempt to gracefully shutdown
func (a *App) Use(mw ...MiddlewareFunc)
Use the specified Middleware for the App. When defined on an `*App` the specified middleware will be inherited by any `Group` calls that are made on that on the App.
type BaseResource struct{}BaseResource fills in the gaps for any Resource interface functions you don't want/need to implement.
type UsersResource struct {
Resource
}
func (ur *UsersResource) List(c Context) error {
return c.Render(http.StatusOK, render.String("hello")
}
// This will fulfill the Resource interface, despite only having
// one of the functions defined.
&UsersResource{&BaseResource{})
func (v BaseResource) Create(c Context) error
Create default implementation. Returns a 404
func (v BaseResource) Destroy(c Context) error
Destroy default implementation. Returns a 404
func (v BaseResource) List(c Context) error
List default implementation. Returns a 404
func (v BaseResource) Show(c Context) error
Show default implementation. Returns a 404
func (v BaseResource) Update(c Context) error
Update default implementation. Returns a 404
type Context interface {
context.Context
Response() http.ResponseWriter
Request() *http.Request
Session() *Session
Cookies() *Cookies
Params() ParamValues
Param(string) string
Set(string, interface{})
LogField(string, interface{})
LogFields(map[string]interface{})
Logger() Logger
Bind(interface{}) error
Render(int, render.Renderer) error
Error(int, error) error
Redirect(int, string, ...interface{}) error
Data() map[string]interface{}
Flash() *Flash
File(string) (binding.File, error)
}Context holds on to information as you pass it down through middleware, Handlers, templates, etc... It strives to make your life a happier one.
type Cookies struct {
// contains filtered or unexported fields
}Cookies allows you to easily get cookies from the request, and set cookies on the response.
Delete sets a header that tells the browser to remove the cookie with the given name.
Get returns the value of the cookie with the given name. Returns http.ErrNoCookie if there's no cookie with that name in the request.
Set a cookie on the response, which will expire after the given duration.
SetWithExpirationTime sets a cookie that will expire at a specific time. Note that the time is determined by the client's browser, so it might not expire at the expected time, for example if the client has changed the time on their computer.
SetWithPath sets a cookie path on the server in which the cookie will be available on. If set to '/', the cookie will be available within the entire domain. If set to '/foo/', the cookie will only be available within the /foo/ directory and all sub-directories such as /foo/bar/ of domain.
DefaultContext is, as its name implies, a default implementation of the Context interface.
func (d *DefaultContext) Bind(value interface{}) error
Bind the interface to the request.Body. The type of binding is dependent on the "Content-Type" for the request. If the type is "application/json" it will use "json.NewDecoder". If the type is "application/xml" it will use "xml.NewDecoder". See the github.com/gobuffalo/buffalo/binding package for more details.
func (d *DefaultContext) Cookies() *Cookies
Cookies for the associated request and response.
func (d *DefaultContext) Data() map[string]interface{}
Data contains all the values set through Get/Set.
func (d *DefaultContext) Error(status int, err error) error
File returns an uploaded file by name, or an error
func (d *DefaultContext) Flash() *Flash
Flash messages for the associated Request.
func (d *DefaultContext) LogField(key string, value interface{})
LogField adds the key/value pair onto the Logger to be printed out as part of the request logging. This allows you to easily add things like metrics (think DB times) to your request.
func (d *DefaultContext) LogFields(values map[string]interface{})
LogFields adds the key/value pairs onto the Logger to be printed out as part of the request logging. This allows you to easily add things like metrics (think DB times) to your request.
func (d *DefaultContext) Logger() Logger
Logger returns the Logger for this context.
func (d *DefaultContext) MarshalJSON() ([]byte, error)
MarshalJSON implements json marshaling for the context
func (d *DefaultContext) Param(key string) string
Param returns a param, either named or query string, based on the key.
func (d *DefaultContext) Params() ParamValues
Params returns all of the parameters for the request, including both named params and query string parameters.
func (d *DefaultContext) Redirect(status int, url string, args ...interface{}) error
Redirect a request with the given status to the given URL.
Render a status code and render.Renderer to the associated Response. The request parameters will be made available to the render.Renderer "{{.params}}". Any values set onto the Context will also automatically be made available to the render.Renderer. To render "no content" pass in a nil render.Renderer.
func (d *DefaultContext) Request() *http.Request
Request returns the original Request.
func (d *DefaultContext) Response() http.ResponseWriter
Response returns the original Response for the request.
func (d *DefaultContext) Session() *Session
Session for the associated Request.
func (d *DefaultContext) Set(key string, value interface{})
Set a value onto the Context. Any value set onto the Context will be automatically available in templates.
func (d *DefaultContext) String() string
func (d *DefaultContext) Value(key interface{}) interface{}
Value that has previously stored on the context.
ErrorHandler interface for handling an error for a specific status code.
type ErrorHandlers map[int]ErrorHandler
ErrorHandlers is used to hold a list of ErrorHandler types that can be used to handle specific status codes.
a.ErrorHandlers[http.StatusInternalServerError] = func(status int, err error, c buffalo.Context) error {
res := c.Response()
res.WriteHeader(status)
res.Write([]byte(err.Error()))
return nil
}
func (e ErrorHandlers) Default(eh ErrorHandler)
Default sets an error handler should a status code not already be mapped. This will replace the original default error handler. This is a *catch-all* handler.
func (e ErrorHandlers) Get(status int) ErrorHandler
Get a registered ErrorHandler for this status code. If no ErrorHandler has been registered, a default one will be returned.
type ErrorResponse struct {
XMLName xml.Name `json:"-" xml:"response"`
Error string `json:"error" xml:"error"`
Trace string `json:"trace" xml:"trace"`
Code int `json:"code" xml:"code,attr"`
}ErrorResponse is a used to display errors as JSON or XML
type Flash struct {
// contains filtered or unexported fields
}Flash is a struct that helps with the operations over flash messages.
Add adds a flash value for a flash key, if the key already has values the list for that value grows.
Clear removes all keys from the Flash.
Delete removes a particular key from the Flash.
Set allows to set a list of values into a particular key.
HTTPError a typed error returned by http Handlers and used for choosing error handlers
Handler is the basis for all of Buffalo. A Handler will be given a Context interface that represents the give request/response. It is the responsibility of the Handler to handle the request/response correctly. This could mean rendering a template, JSON, etc... or it could mean returning an error.
func (c Context) error {
return c.Render(http.StatusOK, render.String("Hello World!"))
}
func (c Context) error {
return c.Redirect(http.StatusMovedPermanently, "http://github.com/gobuffalo/buffalo")
}
func (c Context) error {
return c.Error(http.StatusUnprocessableEntity, fmt.Errorf("oops!!"))
}
RequestLoggerFunc is the default implementation of the RequestLogger. By default it will log a uniq "request_id", the HTTP Method of the request, the path that was requested, the duration (time) it took to process the request, the size of the response (and the "human" size), and the status code of the response.
WrapHandler wraps a standard http.Handler and transforms it into a buffalo.Handler.
func WrapHandlerFunc(h http.HandlerFunc) Handler
WrapHandlerFunc wraps a standard http.HandlerFunc and transforms it into a buffalo.Handler.
type Logger = logger.FieldLogger
Logger interface is used throughout Buffalo apps to log a whole manner of things.
type Middler interface {
Use() []MiddlewareFunc
}Middler can be implemented to specify additional middleware specific to the resource
MiddlewareFunc defines the interface for a piece of Buffalo Middleware.
func DoSomething(next Handler) Handler {
return func(c Context) error {
// do something before calling the next handler
err := next(c)
// do something after call the handler
return err
}
}
type MiddlewareStack struct {
// contains filtered or unexported fields
}MiddlewareStack manages the middleware stack for an App/Group.
func (ms *MiddlewareStack) Clear()
Clear wipes out the current middleware stack for the App/Group, any middleware previously defined will be removed leaving an empty middleware stack.
func (ms *MiddlewareStack) Remove(mws ...MiddlewareFunc)
Remove the specified Middleware(s) for the App/group. This is useful when the middleware will be skipped by the entire group.
a.Middleware.Remove(Authorization)
func (ms *MiddlewareStack) Replace(mw1 MiddlewareFunc, mw2 MiddlewareFunc)
Replace a piece of middleware with another piece of middleware. Great for testing.
func (ms *MiddlewareStack) Skip(mw MiddlewareFunc, handlers ...Handler)
Skip a specified piece of middleware the specified Handlers. This is useful for things like wrapping your application in an authorization middleware, but skipping it for things the home page, the login page, etc...
a.Middleware.Skip(Authorization, HomeHandler, LoginHandler, RegistrationHandler)
func (ms MiddlewareStack) String() string
func (ms *MiddlewareStack) Use(mw ...MiddlewareFunc)
Use the specified Middleware for the App. When defined on an `*App` the specified middleware will be inherited by any `Group` calls that are made on that on the App.
type Options struct {
Name string `json:"name"`
// Addr is the bind address provided to http.Server. Default is "127.0.0.1:3000"
// Can be set using ENV vars "ADDR" and "PORT".
Addr string `json:"addr"`
// Host that this application will be available at. Default is "http://127.0.0.1:[$PORT|3000]".
Host string `json:"host"`
// Env is the "environment" in which the App is running. Default is "development".
Env string `json:"env"`
// LogLevel defaults to "debug". Deprecated use LogLvl instead
LogLevel string `json:"log_level"`
// LogLevl defaults to logger.DebugLvl.
LogLvl logger.Level `json:"log_lvl"`
// Logger to be used with the application. A default one is provided.
Logger Logger `json:"-"`
// MethodOverride allows for changing of the request method type. See the default
// implementation at buffalo.MethodOverride
MethodOverride http.HandlerFunc `json:"-"`
// SessionStore is the `github.com/gorilla/sessions` store used to back
// the session. It defaults to use a cookie store and the ENV variable
// `SESSION_SECRET`.
SessionStore sessions.Store `json:"-"`
// SessionName is the name of the session cookie that is set. This defaults
// to "_buffalo_session".
SessionName string `json:"session_name"`
// Worker implements the Worker interface and can process tasks in the background.
// Default is "github.com/gobuffalo/worker.Simple.
Worker worker.Worker `json:"-"`
// WorkerOff tells App.Start() whether to start the Worker process or not. Default is "false".
WorkerOff bool `json:"worker_off"`
// PreHandlers are http.Handlers that are called between the http.Server
// and the buffalo Application.
PreHandlers []http.Handler `json:"-"`
// PreWare takes an http.Handler and returns and http.Handler
// and acts as a pseudo-middleware between the http.Server and
// a Buffalo application.
PreWares []PreWare `json:"-"`
// CompressFiles enables gzip compression of static files served by ServeFiles using
// gorilla's CompressHandler (https://godoc.org/github.com/gorilla/handlers#CompressHandler).
// Default is "false".
CompressFiles bool `json:"compress_files"`
Prefix string `json:"prefix"`
Context context.Context `json:"-"`
// contains filtered or unexported fields
}Options are used to configure and define how your application should run.
NewOptions returns a new Options instance with sensible defaults
ParamValues will most commonly be url.Values, but isn't it great that you set your own? :)
PreWare takes an http.Handler and returns and http.Handler and acts as a pseudo-middleware between the http.Server and a Buffalo application.
type Resource interface {
List(Context) error
Show(Context) error
Create(Context) error
Update(Context) error
Destroy(Context) error
}Resource interface allows for the easy mapping of common RESTful actions to a set of paths. See the a.Resource documentation for more details. NOTE: When skipping Resource handlers, you need to first declare your resource handler as a type of buffalo.Resource for the Skip function to properly recognize and match it.
// Works:
var cr Resource
cr = &carsResource{&buffaloBaseResource{}}
g = a.Resource("/cars", cr)
g.Use(SomeMiddleware)
g.Middleware.Skip(SomeMiddleware, cr.Show)
// Doesn't Work:
cr := &carsResource{&buffaloBaseResource{}}
g = a.Resource("/cars", cr)
g.Use(SomeMiddleware)
g.Middleware.Skip(SomeMiddleware, cr.Show)
type Response struct {
Status int
Size int
http.ResponseWriter
}Response implements the http.ResponseWriter interface and allows for the capture of the response status and size to be used for things like logging requests.
CloseNotify implements the http.CloseNotifier interface
Flush the response
Hijack implements the http.Hijacker interface to allow for things like websockets.
Write the body of the response
WriteHeader sets the status code for a response
RouteHelperFunc represents the function that takes the route and the opts and build the path
type RouteInfo struct {
Method string `json:"method"`
Path string `json:"path"`
HandlerName string `json:"handler"`
ResourceName string `json:"resourceName,omitempty"`
PathName string `json:"pathName"`
Aliases []string `json:"aliases"`
MuxRoute *mux.Route `json:"-"`
Handler Handler `json:"-"`
App *App `json:"-"`
}RouteInfo provides information about the underlying route that was built.
Alias path patterns to the this route. This is not the same as a redirect.
func (ri *RouteInfo) BuildPathHelper() RouteHelperFunc
BuildPathHelper Builds a routeHelperfunc for a particular RouteInfo
Name allows users to set custom names for the routes.
String returns a JSON representation of the RouteInfo
RouteList contains a mapping of the routes defined in the application. This listing contains, Method, Path, and the name of the Handler defined to process that route.
Lookup search a specific PathName in the RouteList and return the *RouteInfo
type RouteNamer interface {
// NameRoute receives the path and returns the name
// for the route.
NameRoute(string) string
}RouteNamer is in charge of naming a route from the path assigned, this name typically will be used if no name is assined with .Name(...).
Session wraps the "github.com/gorilla/sessions" API in something a little cleaner and a bit more useable.
Clear the current session
Delete a value from the current session.
Get a value from the current session.
GetOnce gets a value from the current session and then deletes it.
Save the current session.
Set a value onto the current session. If a value with that name already exists it will be overridden with the new value.
| Path | Synopsis |
|---|---|
| binding | |
| binding/decoders | |
| buffalo | |
| buffalo/cmd | |
| buffalo/cmd/destroy | |
| buffalo/cmd/fix | |
| buffalo/cmd/generate | |
| buffalo/cmd/plugins | |
| buffalo/cmd/plugins/internal/cache | |
| genny/actions | You can use the "packr clean" command to clean up this, and any other packr generated files. |
| genny/add | |
| genny/assets/standard | You can use the "packr clean" command to clean up this, and any other packr generated files. |
| genny/assets/webpack | You can use the "packr clean" command to clean up this, and any other packr generated files. |
| genny/build | You can use the "packr clean" command to clean up this, and any other packr generated files. |
| genny/build/_fixtures/coke | |
| genny/build/_fixtures/coke/actions | |
| genny/build/_fixtures/coke/grifts | |
| genny/build/_fixtures/coke/models | |
| genny/ci | You can use the "packr clean" command to clean up this, and any other packr generated files. |
| genny/docker | You can use the "packr clean" command to clean up this, and any other packr generated files. |
| genny/grift | |
| genny/info | |
| genny/mail | You can use the "packr clean" command to clean up this, and any other packr generated files. |
| genny/newapp/api | You can use the "packr clean" command to clean up this, and any other packr generated files. |
| genny/newapp/core | You can use the "packr clean" command to clean up this, and any other packr generated files. |
| genny/newapp/web | You can use the "packr clean" command to clean up this, and any other packr generated files. |
| genny/plugins/install | |
| genny/refresh | You can use the "packr clean" command to clean up this, and any other packr generated files. |
| genny/resource | You can use the "packr clean" command to clean up this, and any other packr generated files. |
| genny/vcs | You can use the "packr clean" command to clean up this, and any other packr generated files. |
| internal/defaults | |
| internal/fakesmtp | |
| internal/httpx | |
| internal/takeon/github.com/gobuffalo/syncx | |
| internal/takeon/github.com/markbates/errx | |
| mail/internal/mail | Package gomail provides a simple interface to compose emails and to mail them efficiently. |
| packrd | You can use the "packr2 clean" command to clean up this, and any other packr generated files. |
| plugins | |
| plugins/packrd | You can use the "packr2 clean" command to clean up this, and any other packr generated files. |
| plugins/plugcmds | |
| plugins/plugdeps | |
| render | |
| runtime | |
| servers | |
| worker |
Package buffalo imports 55 packages (graph) and is imported by 379 packages. Updated 2021-01-18. Refresh now. Tools for package owners.