Skip to content
Go web framework with a natural feel
Go HTML
Branch: master
Clone or download
flowonyx and zpatrick Add syntax highlighting to README.md
You may prefer to not have syntax highlighting, but if you do like it, this is a very simple way to add it on Github.
Latest commit f42d3a4 Oct 3, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Update main.go Apr 26, 2018
testing add parser tests Sep 12, 2016
LICENSE add license Sep 6, 2016
README.md Add syntax highlighting to README.md Oct 3, 2018
app.go remove log decorator. fix up readme. working on ResponseFunc usage in… Sep 8, 2016
app_test.go add some context tests Sep 12, 2016
context.go add more to swagger example Apr 10, 2017
context_test.go add some context tests Sep 12, 2016
decorators.go remove session decorator Jul 12, 2017
error.go add cache to template parser. handle write errors in response Sep 26, 2016
json.go add log decorator. remove session from api example Oct 3, 2016
parser.go add log decorator. remove session from api example Oct 3, 2016
parser_test.go add parser tests Sep 12, 2016
response.go
route.go add Handlers type Oct 4, 2016
router.go update router for go-cache May 29, 2018
router_test.go add concurrent router test. update formatting Dec 6, 2017
test_helpers.go read -> record Aug 30, 2018
utilities.go add CORS utilities Nov 14, 2016

README.md

Fireball

MIT License Go Report Card Go Doc

Overview

Fireball is a package for Go web applications. The primary goal of this package is to make routing, response writing, and error handling as easy as possible for developers, so they can focus more on their application logic, and less on repeated patterns.

Installation

To install this package, run:

go get github.com/zpatrick/fireball

Getting Started

The following snipped shows a simple "Hello, World" application using Fireball:

package main

import (
  "github.com/zpatrick/fireball"
  "net/http"
)

func index(c *fireball.Context) (fireball.Response, error) {
  return fireball.NewResponse(200, []byte("Hello, World!"), nil), nil
}

func main() {
  indexRoute := &fireball.Route{
    Path: "/",
    Handlers: fireball.Handlers{
      "GET": index,
    },
  }

  routes := []*fireball.Route{indexRoute}
  app := fireball.NewApp(routes)
  http.ListenAndServe(":8000", app)
}

This will run a new webserver at localhost:8000

Handlers

Handlers perform the business logic associated with requests. Handlers take a Context object and returns either a Response or an error.

HTTP Response

The HTTP Response is a simple object that implements the Response interface. When the Write call is executed, the specified Body, Status, and Headers will be written to the http.ResponseWriter.

Examples:

func Index(c *fireball.Context) (fireball.Response, error) {
    return fireball.NewResponse(200, []byte("Hello, World"), nil), nil
}
func Index(c *fireball.Context) (fireball.Response, error) {
    html := []byte("<h1>Hello, World</h1>")
    return fireball.NewResponse(200, html, fireball.HTMLHeaders), nil
}

HTTP Error

If a Handler returns a non-nil error, the Fireball Application will call its ErrorHandler function. By default (if your Application object uses the DefaultErrorHandler), the Application will check if the error implements the Response interface. If so, the the error's Write function will be called. Otherwise, a 500 with the content of err.Error() will be written.

The HTTPError is a simple object that implements both the Error and Response interfaces. When the Write is executed, the specified status, error, and headers will be written to the http.ResponseWriter.

Examples:

func Index(c *fireball.Context) (fireball.Response, error) {
    return nil, fmt.Errorf("an error occurred")
}
func Index(c *fireball.Context) (fireball.Response, error) {
    if err := do(); err != nil {
        return nil, fireball.NewError(500, err, nil)
    }
    
    ...
}

Routing

Basic Router

By default, Fireball uses the BasicRouter object to match requests to Route objects. The Route's Path field determines which URL patterns should be dispached to your Route. The Route's Handlers field maps different HTTP methods to different Handlers.

You can use :variable notation in the Path to match any string that doesn't contain a "/" character. The variables defined in the Route's Path field can be accessed using the Context object.

Example:

route := &Fireball.Route{
  Path: "/users/:userID/orders/:orderID",
  Methods: fireball.Handlers{
    "GET": printUserOrder,
  },
}

func printUserOrder(c *fireball.Context) (fireball.Response, error) {
    userID := c.PathVariables["userID"]
    orderID := c.PathVariables["orderID"]
    message := fmt.Sprintf("User %s ordered item %s", userID, orderID)
    
    return fireball.NewResponse(200, []byte(message), nil)
}

Static Routing

The built-in FileServer can be used to serve static content. The follow snippet would serve files from the static directory:

  app := fireball.NewApp(...)
  http.Handle("/", app)

  fs := http.FileServer(http.Dir("static"))
  http.Handle("/static/", http.StripPrefix("/static", fs))
  
  http.ListenAndServe(":8000", nil)

If the application workspace contained:

app/
    main.go
    static/
        hello_world.txt

A request to /static/hello_world.txt would serve the desired file.

HTML Templates

By default, Fireball uses the GlobParser to render HTML templates. This object recursively searches a given directory for template files matching the given glob pattern. The default root directory is "views", and the default glob pattern is "*.html" The name of the templates are path/from/root/directory + filename.

For example, if the filesystem contained:

views/
    index.html
    partials/
        login.html

The templates names generated would be "index.html", and "partials/login.html". The Context contains a helper function, HTML, which renders templates as HTML.

Example:

func Index(c *fireball.Context) (fireball.Response, error) {
    data := "Hello, World!"
    return c.HTML(200, "index.html", data)
}

Decorators

Decorators can be used to wrap additional logic around Handlers. Fireball has some built-in decorators:

In addition to Decorators, the Before and After functions on the Application object can be used to perform logic when the request is received and after the response has been sent.

Examples & Extras

License

This work is published under the MIT license.

Please see the LICENSE file for details.

You can’t perform that action at this time.