buffalo

package module
v0.7.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 13, 2017 License: MIT Imports: 37 Imported by: 0

README

Buffalo GoDoc Build Status Code Climate Go Report Card

Buffalo is Go web framework. Yeah, I hate the word "framework" too! Buffalo is different though. Buffalo doesn't want to re-invent wheels like routing and templating. Buffalo is glue that wraps all of the best packages available and makes them all play nicely together.

Buffalo is "idiomatic", for whatever that is worth. The purpose of a framework is not to bend you to its will, but to rather get out of your way and make your job of building your application easy. That is the goal of Buffalo.

If you were to look through the Buffalo code base you'd find little code, just enough to assemble the amazing packages that others have written into one coherent system.

I ❤ web dev in go again - Brian Ketelsen

Documentation

Please visit http://gobuffalo.io for the latest documentation, examples, and more.

Installation

$ go get -u github.com/gobuffalo/buffalo/buffalo

Generating a new Project

Buffalo aims to make building new web applications in Go as simple as possible, and what could be more simple than a new application generator?

$ buffalo new <name>

That will generate a whole new Buffalo application that is ready to go. It'll even run go get for you to make sure you have all of the necessary dependencies needed to run your application.

To see a list of available flags for the new command, just check out its help.

$ buffalo help new

Running your application

Buffalo is Go "standards" compliant, that means you can just build your binary and run it. It's that simple.

Running your application in Development

One of the downsides to Go development is the lack of code "reloading". This means as you change your code you need to manually stop your application, rebuild it, and then restart it. Buffalo finds this is annoying, and wants to make life better for you.

$ buffalo dev

The dev command will watch your .go and .html files by default and rebuild, and restart, your binary for you so you don't have to worry about such things. Just run the dev command and start coding.

Testing your application

Just like running your application, Buffalo doesn't stop you from using the standard Go tools for testing. Buffalo does ship with a test command that will run all of your tests will conveniently skipping that pesky old ./vendor directory!

$ buffalo test

Shoulders of Giants

Buffalo would not be possible if not for all of the great projects it depends on. Please see SHOULDERS.md to see a list of them.

Templating

github.com/gobuffalo/velvet - This templating package was chosen over the standard Go html/template package for a variety of reasons. The biggest of which is that it is significantly more flexible and easier to work with. It also has the added factor of being familiar to those who have worked with "Handlebars" or "Mustache" templates before.

Routing

github.com/gorilla/mux - This router was chosen because of its stability and flexibility. There might be faster routers out there, but this one is definitely the most powerful!

Task Runner (Optional)

github.com/markbates/grift - If you're familiar with Rake tasks from Ruby, you'll be right at home using Grift. This package was chosen to allow for the easy running of simple, and common, tasks that most web applications need. Think things like seeding a database, or taking in a CSV file and generating database records. Buffalo ships with an example routes task that prints off the defined routes and the function that handles those requests.

Models/ORM (Optional)

github.com/markbates/pop - Accessing databases is nothing new in web applications. Pop, and its command line tool, Soda, were chosen because they strike a nice balance between simplifying common tasks, being idiomatic, and giving you the flexibility you need to built your app. Pop, and Soda, share the same core philosphies as Buffalo, so they were a natural choice.

Sessions, Cookies, Websockets, and more...

github.com/gorilla - The Gorilla toolkit is a great set of packages designed to improve upon the standard libary for a variety of web related packages. With these high quality packages Buffalo is able to keep its "core" code to a minimum and focus on its goal of glueing them all together to make your life better.

Benchmarks

Oh, yeah, everyone wants benchmarks! What would a web framework be without its benchmarks? Well, guess what? I'm not giving you any! That's right. This is Go! I assure you that it is plenty fast enough for you. If you want benchmarks you can either a) checkout any benchmarks that the GIANTS Buffalo is built upon have published, or b) run your own. I have no interest in playing the benchmark game, and neither should you.

Contributors

  • Mark Bates
  • Antonio Pagano
  • Brian Downs
  • Cody Oss
  • arif emre
  • Mark Lussier
  • Kenny Grant

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var MethodOverride http.HandlerFunc

MethodOverride can be be overridden to a user specified function that can be used to change the HTTP Request Method. var MethodOverride = MethodOverrideFunc

View Source 
var RequestLogger = RequestLoggerFunc

RequestLogger can be be overridden to a user specified function that can be used to log the request.

Functions

func MethodOverrideFunc 

func MethodOverrideFunc(res http.ResponseWriter, req *http.Request)

MethodOverrideFunc is the default implementation for the 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 `Automatic` Buffalo, unless an alternative is defined in the Options.

func NotFoundHandler added in v0.7.1 

func NotFoundHandler(status int, err error, c Context) error

NotFoundHandler is the default ErrorHandler for 404 responses. In development mode it attempts to return useful debugging information. In production it defaults to use the http.NotFound handler.

Types

type App 

type App struct {
	Options
	// Middleware returns the current MiddlewareStack for the App/Group.
	Middleware    *MiddlewareStack
	ErrorHandlers ErrorHandlers
	// 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!

func Automatic 

func Automatic(opts Options) *App

Automatic returns a new instance of App with sane defaults, some not so sane defaults, and a few bits and pieces to make your life that much easier. You'll want to use this almost all of the time to build your applications.

https://www.youtube.com/watch?v=BKbOplYmjZM

func New 

func New(opts Options) *App

New returns a new instance of App, without any frills or thrills. Most people will want to use Automatic which adds some sane, and useful, defaults.

func (*App) ANY 

func (a *App) ANY(p string, h Handler)

ANY accepts a request across any HTTP method for the specified path and routes it to the specified Handler.

func (*App) DELETE 

func (a *App) DELETE(p string, h Handler) RouteInfo

DELETE maps an HTTP "DELETE" request to the path and the specified handler.

func (*App) GET 

func (a *App) GET(p string, h Handler) RouteInfo

GET maps an HTTP "GET" request to the path and the specified handler.

func (*App) Group 

func (a *App) Group(path string) *App

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)

func (*App) HEAD 

func (a *App) HEAD(p string, h Handler) RouteInfo

HEAD maps an HTTP "HEAD" request to the path and the specified handler.

func (*App) OPTIONS 

func (a *App) OPTIONS(p string, h Handler) RouteInfo

OPTIONS maps an HTTP "OPTIONS" request to the path and the specified handler.

func (*App) PATCH 

func (a *App) PATCH(p string, h Handler) RouteInfo

PATCH maps an HTTP "PATCH" request to the path and the specified handler.

func (*App) POST 

func (a *App) POST(p string, h Handler) RouteInfo

POST maps an HTTP "POST" request to the path and the specified handler.

func (*App) PUT 

func (a *App) PUT(p string, h Handler) RouteInfo

PUT maps an HTTP "PUT" request to the path and the specified handler.

func (*App) Resource added in v0.4.3 

func (a *App) Resource(p string, r Resource) *App

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 (*App) Routes 

func (a *App) Routes() RouteList

Routes returns a list of all of the routes defined in this application.

func (*App) ServeFiles 

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"))

func (*App) ServeHTTP 

func (a *App) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*App) Use 

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 added in v0.4.3 

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(200, render.String("hello")
}

// This will fulfill the Resource interface, despite only having
// one of the functions defined.
&UsersResource{&BaseResource{})

func (*BaseResource) Create added in v0.4.3 

func (v *BaseResource) Create(c Context) error

Create default implementation. Returns a 404

func (*BaseResource) Destroy added in v0.4.3 

func (v *BaseResource) Destroy(c Context) error

Destroy default implementation. Returns a 404

func (*BaseResource) Edit added in v0.4.3 

func (v *BaseResource) Edit(c Context) error

Edit default implementation. Returns a 404

func (*BaseResource) List added in v0.4.3 

func (v *BaseResource) List(c Context) error

List default implementation. Returns a 404

func (*BaseResource) New added in v0.4.3 

func (v *BaseResource) New(c Context) error

New default implementation. Returns a 404

func (*BaseResource) Show added in v0.4.3 

func (v *BaseResource) Show(c Context) error

Show default implementation. Returns a 404

func (*BaseResource) Update added in v0.4.3 

func (v *BaseResource) Update(c Context) error

Update default implementation. Returns a 404

type Context 

type Context interface {
	Response() http.ResponseWriter
	Request() *http.Request
	Session() *Session
	Params() ParamValues
	Param(string) string
	ParamInt(string) (int, error)
	Set(string, interface{})
	Get(string) interface{}
	LogField(string, interface{})
	LogFields(map[string]interface{})
	Logger() Logger
	Bind(interface{}) error
	Render(int, render.Renderer) error
	Error(int, error) error
	Websocket() (*websocket.Conn, error)
	Redirect(int, string, ...interface{}) error
	Data() map[string]interface{}
}

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 DefaultContext 

type DefaultContext struct {
	// contains filtered or unexported fields
}

DefaultContext is, as its name implies, a default implementation of the Context interface.

func (*DefaultContext) Bind 

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". The default binder is "http://www.gorillatoolkit.org/pkg/schema".

func (*DefaultContext) Data 

func (d *DefaultContext) Data() map[string]interface{}

Data contains all the values set through Get/Set.

func (*DefaultContext) Error 

func (d *DefaultContext) Error(status int, err error) error

func (*DefaultContext) Get 

func (d *DefaultContext) Get(key string) interface{}

Get a value that was previous set onto the Context.

func (*DefaultContext) LogField 

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 (*DefaultContext) LogFields 

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 (*DefaultContext) Logger 

func (d *DefaultContext) Logger() Logger

Logger returns the Logger for this context.

func (*DefaultContext) Param 

func (d *DefaultContext) Param(key string) string

Param returns a param, either named or query string, based on the key.

func (*DefaultContext) ParamInt 

func (d *DefaultContext) ParamInt(key string) (int, error)

ParamInt tries to convert the requested parameter to an int. It will return an error if there is a problem.

func (*DefaultContext) Params 

func (d *DefaultContext) Params() ParamValues

Params returns all of the parameters for the request, including both named params and query string parameters. These parameters are automatically available in templates as "{{.params}}".

func (*DefaultContext) Redirect 

func (d *DefaultContext) Redirect(status int, url string, args ...interface{}) error

Redirect a request with the given status to the given URL.

func (*DefaultContext) Render 

func (d *DefaultContext) Render(status int, rr render.Renderer) error

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 (*DefaultContext) Request 

func (d *DefaultContext) Request() *http.Request

Request returns the original Request.

func (*DefaultContext) Response 

func (d *DefaultContext) Response() http.ResponseWriter

Response returns the original Response for the request.

func (*DefaultContext) Session 

func (d *DefaultContext) Session() *Session

Session for the associated Request.

func (*DefaultContext) Set 

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 (*DefaultContext) Websocket 

func (d *DefaultContext) Websocket() (*websocket.Conn, error)

Websocket returns an upgraded github.com/gorilla/websocket.Conn that can then be used to work with websockets easily.

type ErrorHandler added in v0.7.1 

type ErrorHandler func(int, error, Context) error

ErrorHandler interface for handling an error for a specific status code.

type ErrorHandlers added in v0.7.1 

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[500] = func(status int, err error, c buffalo.Context) error {
	res := c.Response()
	res.WriteHeader(status)
	res.Write([]byte(err.Error()))
	return nil
}

func (ErrorHandlers) Get added in v0.7.1 

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 Handler 

type Handler func(Context) error

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(200, render.String("Hello World!"))
}

func (c Context) error {
	return c.Redirect(301, "http://github.com/gobuffalo/buffalo")
}

func (c Context) error {
	return c.Error(422, errors.New("oops!!"))
}

func RequestLoggerFunc 

func RequestLoggerFunc(h Handler) Handler

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.

func WrapHandler 

func WrapHandler(h http.Handler) Handler

WrapHandler wraps a standard http.Handler and transforms it into a buffalo.Handler.

func WrapHandlerFunc 

func WrapHandlerFunc(h http.HandlerFunc) Handler

WrapHandlerFunc wraps a standard http.HandlerFunc and transforms it into a buffalo.Handler.

type Logger 

type Logger interface {
	WithField(string, interface{}) Logger
	WithFields(map[string]interface{}) Logger
	Debugf(string, ...interface{})
	Infof(string, ...interface{})
	Printf(string, ...interface{})
	Warnf(string, ...interface{})
	Errorf(string, ...interface{})
	Fatalf(string, ...interface{})
	Debug(...interface{})
	Info(...interface{})
	Warn(...interface{})
	Error(...interface{})
	Fatal(...interface{})
	Panic(...interface{})
}

Logger interface is used throughout Buffalo apps to log a whole manner of things.

func NewLogger 

func NewLogger(level string) Logger

NewLogger based on the specified log level. This logger will log to the STDOUT in a human readable, but parseable form. 

Example: time="2016-12-01T21:02:07-05:00" level=info duration=225.283µs human_size="106 B" method=GET path="/" render=199.79µs request_id=2265736089 size=106 status=200

type MiddlewareFunc 

type MiddlewareFunc func(Handler) Handler

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 

type MiddlewareStack struct {
	// contains filtered or unexported fields
}

MiddlewareStack manages the middleware stack for an App/Group.

func (*MiddlewareStack) Clear 

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 (*MiddlewareStack) Replace added in v0.5.0 

func (ms *MiddlewareStack) Replace(mw1 MiddlewareFunc, mw2 MiddlewareFunc)

Replace a piece of middleware with another piece of middleware. Great for testing.

func (*MiddlewareStack) Skip 

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 middleare, but skipping it for things the home page, the login page, etc... 

a.Middleware.Skip(Authorization, HomeHandler, LoginHandler, RegistrationHandler)

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 ur 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)

func (*MiddlewareStack) Use 

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 

type Options struct {
	// Env is the "environment" in which the App is running. Default is "development".
	Env string
	// LogLevel defaults to "debug".
	LogLevel string
	// Logger to be used with the application. A default one is provided.
	Logger Logger
	// LogDir is the path to the directory for storing the JSON log files from the
	// default Logger
	LogDir         string
	MethodOverride http.HandlerFunc
	// 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
	// SessionName is the name of the session cookie that is set. This defaults
	// to "_buffalo_session".
	SessionName string
	// Host that this application will be available at. Default is "http://127.0.0.1:[$PORT|3000]".
	Host string
	// contains filtered or unexported fields
}

Options are used to configure and define how your application should run.

func NewOptions 

func NewOptions() Options

NewOptions returns a new Options instance with sensible defaults

type ParamValues 

type ParamValues interface {
	Get(string) string
}

ParamValues will most commonly be url.Values, but isn't it great that you set your own? :)

type Resource added in v0.4.3 

type Resource interface {
	List(Context) error
	Show(Context) error
	New(Context) error
	Create(Context) error
	Edit(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 ur 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 RouteInfo added in v0.7.1 

type RouteInfo struct {
	Method      string     `json:"method"`
	Path        string     `json:"path"`
	HandlerName string     `json:"handler"`
	MuxRoute    *mux.Route `json:"-"`
	Handler     Handler    `json:"-"`
}

RouteInfo provides information about the underlying route that was built.

type RouteList 

type RouteList []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.

func (RouteList) Len 

func (a RouteList) Len() int

func (RouteList) Less 

func (a RouteList) Less(i, j int) bool

func (RouteList) Swap 

func (a RouteList) Swap(i, j int)

type Session 

type Session struct {
	Session *sessions.Session
	// contains filtered or unexported fields
}

Session wraps the "github.com/gorilla/sessions" API in something a little cleaner and a bit more useable.

func (*Session) Delete 

func (s *Session) Delete(name interface{})

Delete a value from the current session.

func (*Session) Get 

func (s *Session) Get(name interface{}) interface{}

Get a value from the current session.

func (*Session) Save 

func (s *Session) Save() error

Save the current session.

func (*Session) Set 

func (s *Session) Set(name, value interface{})

Set a value onto the current session. If a value with that name already exists it will be overridden with the new value.

Source Files

View all Source files

Directories

Path Synopsis
cmd
cmd/generate
examples
hello-world
hello-world/actions
hello-world/grifts
html-crud
html-crud/actions
html-crud/grifts
html-crud/models
html-resource
html-resource/actions
html-resource/grifts
html-resource/models
json-crud
json-crud/actions
json-crud/grifts
json-crud/models
json-resource
json-resource/actions
json-resource/grifts
json-resource/models
simple_hello
websockets
websockets/actions
websockets/grifts
resolvers

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.