README
¶
bow
Bow wraps a minimal amount of go libraries to quickly bootstrap a capable web project.
What’s more than net/http and html/template?
Go comes with a really solid standard library, powered with robust packages that you can directly use for your production web applications. The community is well-known to be against frameworks by definition, especially when it comes to web applications. And it is probably true to a certain degree. I am really in favour of using those packages, but in my opinion, there are still missing bits to build modern and secure web applications. I am talking about:
- A HTTP router/muxer that supports patterns.
- A fast template engine that supports partials and layouts.
- A migration system for databases.
- Middlewares to automatically apply security headers to our responses.
- A session system to store state information about users.
- Flash messages.
- An easy way to create forms with validation, with CSRF protection.
- A simple way to do translations.
So all of that to say that net/http and html/template and not sufficient to build a real web application. That’s why bow was initiated, to pack additional small and effective libraries to fill the gaps.
Getting started
Using bow cli
That is the quickest way to get you started. First, install the cli.
go install github.com/lobre/bow/cmd/bow@latest
Initialize a new project.
mkdir myproject && cd myproject
go mod init myproject
Generate all the necessary files.
bow init
Tidy your dependencies and build the project.
go mod tidy
go build
Run and check your browser at localhost:8080.
./myproject
You are now ready to start developing features!
Manually
See details
First, initialize a new project.
mkdir myproject && cd myproject
go mod init myproject
Gather the dependencies.
go get github.com/julienschmidt/httprouter
go get github.com/lobre/bow
You will then need to define a base HTML layout.
mkdir -p views/layouts
cat views/layouts/base.html
<!DOCTYPE html>
<html lang="us">
<head>
<meta charset="utf-8" />
<meta name="csrf-token" content="{{ csrf }}" />
<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
<title>{{ template "title" . }}</title>
<link href='/{{ hash "assets/style.css" }}' rel="stylesheet">
<link rel="icon" href='/{{ hash "assets/favicon.ico" }}'>
{{ block "head" . }}{{ end }}
</head>
<body>
<nav>
<a href="/">{{ "Home" }}</a>
</nav>
<main>
{{ template "main" . }}
</main>
</body>
</html>
NOTE: The folders
viewsandlayoutscannot be renamed, and the base layout should be namedbase.html.
Then, let’s create a first HTML page.
cat views/home.html
{{ define "title" }}{{ "Home" }}{{ end }}
<div>"Hello World"</div>
Now, let’s create an assets folder in which you can add your favicon and your css style which will be empty for now.
mkdir assets
cp <your_icon> assets/favicon.ico
touch assets/style.css
It is now the time to start implementing our go code! Create a main.go.
You will need a fs.FS for those just created assets and templates. It is recommended to use an embed, so that they will be contained in your final binary. Add this at the top of your main.go file.
//go:embed assets
//go:embed views
var fsys embed.FS
Bow brings a bow.Core structure that should be embedded in your own struct. I have defined this struct application here in the main.go as well.
type application struct {
*bow.Core
// your future own fields
}
Then create your main func, define an instance of this struct and configure bow.
func main() {
app := application{}
app.Core, err_ = bow.NewCore(fsys)
if err != nil {
panic(err)
}
}
We now need to define our application routes. Add this other function to your main.go.
func (app *application) routes() http.Handler {
chain := app.DynChain()
router := httprouter.New()
router.Handler(http.MethodGet, "/assets/*filepath", app.FileServer())
router.Handler(http.MethodGet, "/", chain.ThenFunc(app.home))
return app.StdChain().Then(router)
}
And also our home handler that tells to render the page named home and that will correspond to our views/home.html.
func (app *application) home(w http.ResponseWriter, r *http.Request) {
app.Views.Render(w, r, http.StatusOK, "home", nil)
}
To finish, at the end of your main.go, create an http.Server and run the app.
func main() {
app := application{}
app.Core, err_ = bow.NewCore(fsys)
if err != nil {
panic(err)
}
srv := &http.Server{
Addr: ":8080",
Handler: app.routes(),
IdleTimeout: time.Minute,
ReadTimeout: 10 * time.Second,
WriteTimeout: 30 * time.Second,
}
err := app.Run(srv)
if err != nil {
panic(err)
}
}
NOTE: Make sure to format your
main.goand auto-import the dependencies.
Build the project.
go build
Finally, run and check your browser at localhost:8080.
./myproject
You are now ready to start developing features!
Other features
The getting started guide explains how to get started as quickly as possible. However, there are 3 other features that can be enabled through bow init.
bow init -with-db: To allow having a sqlite connection with a migration system.bow init -with-session: To allow having a persistent secured session stored in a user cookie.bow init -with-translator: To allow having simple translation capabilities fromcsvfiles.
Also, feel free to explore the go documentation of bow, to better understand what it brings to the table.
Framework or not?
When you use a library, you are in charge of the application flow. You choose when and where to call the library. When you use a framework, the framework is in charge of the flow.
Following that definition, I don’t consider bow to be a web framework. It is simply a set of libraries that are carefully wrapped to provide the necessary tools required to build a robust web application. You simply embed the main bow.Core structure in your application, and you still have the freedom to organize your go code as you wish.
Dependencies
To me, having a minimal set of dependencies is key. Less code, less maintenance, fewer security issues.
The choice of those dependencies has been made carefully to include only small, strongly built and focused libraries that were not worth reimplementing.
- benbjohnson/hashfs: Append hashes to filename for better HTTP caching.
- github.com/julienschmidt/httprouter: A simple pattern muxer for net/http.
- golangcollege/sessions: Ligthweight HTTP session cookie implementation.
- goodsign/monday: Minimalist translator for month and day of week names.
- justinas/alice: Easily chain your HTTP middleware functions.
- justinas/nosurf: Middleware to prevent Cross-Site Request Foregy attacks.
- mattn/go-sqlite3: A robust sqlite3 driver.
Acknowledgement
This project has been heavily inspired by the awesome work of:
Projects
For a project using bow, check github.com/lobre/tdispo.
Documentation
¶
Index ¶
- func ApplyLayout(layout string) func(http.Handler) http.Handler
- func Format(dt time.Time, layout string, locale string) string
- func WithLayout(r *http.Request, layout string) *http.Request
- type Core
- type DB
- type Form
- func (f *Form) CustomError(field, msg string)
- func (f *Form) Error(field string) string
- func (f *Form) IsDate(fields ...string)
- func (f *Form) IsEmail(fields ...string)
- func (f *Form) IsInteger(fields ...string)
- func (f *Form) IsTime(fields ...string)
- func (f *Form) MatchesPattern(field string, pattern *regexp.Regexp)
- func (f *Form) MaxLength(field string, d int)
- func (f *Form) MinLength(field string, d int)
- func (f *Form) PermittedValues(field string, opts ...string)
- func (f *Form) Required(fields ...string)
- func (f *Form) Valid() bool
- type Option
- func WithCSP(csp map[string]string) Option
- func WithDB(dsn string) Option
- func WithDebug(debug bool) Option
- func WithFuncs(funcs template.FuncMap) Option
- func WithGlobals(fn func(*http.Request) interface{}) Option
- func WithLogger(logger *log.Logger) Option
- func WithReqFuncs(funcs ReqFuncMap) Option
- func WithSession(key string) Option
- func WithTranslator(locale string) Option
- type ReqFuncMap
- type Translator
- type Views
- func (views *Views) ClientError(w http.ResponseWriter, status int)
- func (views *Views) Funcs(funcs template.FuncMap)
- func (views *Views) Parse(fsys fs.FS) error
- func (views *Views) Render(w http.ResponseWriter, r *http.Request, status int, name string, ...)
- func (views *Views) ReqFuncs(reqFuncs ReqFuncMap)
- func (views *Views) ServerError(w http.ResponseWriter, err error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApplyLayout ¶
ApplyLayout is a middleware that applies a specific layout for the rendering of the view. It returns a function which has the correct signature to be used with alice, but it can also be used without.
Types ¶
type Core ¶
type Core struct {
Logger *log.Logger
DB *DB
Views *Views
Session *sessions.Session
// contains filtered or unexported fields
}
Core holds the core logic to configure and run a simple web app. It is meant to be embedded in a parent web app structure.
func NewCore ¶
NewCore creates a core with sane defaults. Options can be used for specific configurations.
func (*Core) DynChain ¶
DynChain returns a chain of middleware that can be applied to all dynamic routes. It injects a CSRF cookie and enable sessions.
func (*Core) FileServer ¶
FileServer returns a handler for serving filesystem files. It enforces http cache by appending hashes to filenames. A hashName function is defined in templates to gather the hashed filename of a file.
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB represents the database connection.
type Form ¶
Form validates form data against a particular set of rules. If an error occurs, it will store an error message associated with the field.
func (*Form) CustomError ¶
CustomError adds a specific error for a field.
func (*Form) MatchesPattern ¶
MatchesPattern checks that a specific field in the form matches a regular expression. If the check fails, then add the appropriate message to the form errors.
func (*Form) MaxLength ¶
MaxLength checks that a specific field in the form contains a maximum number of characters. If the check fails, then add the appropriate message to the form errors.
func (*Form) MinLength ¶
MinLength checks that a specific field in the form contains a minimum number of characters. If the check fails, then add the appropriate message to the form errors.
func (*Form) PermittedValues ¶
PermittedValues checks that a specific field in the form matches one of a set of specific permitted values. If the check fails, then add the appropriate message to the form errors.
type Option ¶
Option configures a core.
func WithCSP ¶
WithCSP is an option to set the csp rules that will be set on http responses. By default, only default-src : 'self' is defined.
func WithDebug ¶
WithDebug is an option to spit the server errors directly in http responses, instead of a generic 'Internal Server Error' message.
func WithFuncs ¶
WithFuncs is an option to configure default functions that will be injected into views.
func WithGlobals ¶
WithGlobals is an option that allows to define a function that is called at each rendering to inject data that can be retrieved using the "globals" helper template function.
func WithLogger ¶
WithLogger is an option to set the application logger.
func WithReqFuncs ¶
func WithReqFuncs(funcs ReqFuncMap) Option
WithReqFuncs is an option similar to WithFuncs, but with functions that are request-aware.
func WithSession ¶
WithSession is an option to enable cookie sessions. The key parameter is the secret you want to use to authenticate and encrypt sessions cookies, and should be 32 bytes long.
func WithTranslator ¶
WithTranslator is an option to enable and configure the translator. If the locale paramater value is "auto", the locale will be retrieved first from the "lang" cookie, then from the "Accept-Language" request header. If it cannot retrieve it, messages will be returned untranslated.
type ReqFuncMap ¶
ReqFuncMap is a dynamic version of template.FuncMap that is request-aware.
type Translator ¶
type Translator struct {
// contains filtered or unexported fields
}
Translator allows to translate a message from english to a predefined set of locales parsed from csv files. Il also deals with date and time formats.
func (*Translator) Parse ¶
func (tr *Translator) Parse(fsys fs.FS) error
Parse parses all the csv files in the translations folder and build dictionnary maps that will serve as databases for translations. The name of csv file should be a string representing a locale (e.g. en_US). When % is used in a csv translation, it will serve as a placeholder and its value won’t be altered during the translation.
func (*Translator) ReqLocale ¶
func (tr *Translator) ReqLocale(r *http.Request) string
ReqLocale tries to return the locale from the request. It tries to retrieve it first using the "lang" cookie and otherwise using the "Accept-Language" request header. If the locale is not recognized or not supported, it will return the default locale (en_US).
type Views ¶
type Views struct {
Logger *log.Logger
Debug bool // to display errors in http responses
// contains filtered or unexported fields
}
Views is an engine that will render Views from templates.
func (*Views) ClientError ¶
func (views *Views) ClientError(w http.ResponseWriter, status int)
ClientError sends a specific status code and corresponding description to the user. This should be used to send responses when there's a problem with the request that the user sent.
func (*Views) Funcs ¶
Funcs adds the elements of the argument map to the list of functions to inject into templates.
func (*Views) Parse ¶
Parse walks a filesystem from the root folder to discover and parse html files into views. Files starting with an underscore are partial views. Files in the layouts folder not starting with underscore are layouts. The rest of html files are full page views. The funcs parameter is a list of functions that is attached to views.
Views, layouts and partials will be referred to with their path, but without the root folder, and without the file extension.
Layouts will be referred to without the layouts folder neither.
Partials files are named with a leading underscore to distinguish them from regular views, but will be referred to without the underscore.
func (*Views) Render ¶
func (views *Views) Render(w http.ResponseWriter, r *http.Request, status int, name string, data interface{})
Render renders a given view or partial.
For page views, the layout can be set using the WithLayout function or using the ApplyLayout middleware. If no layout is defined, the "base" layout will be chosen. Partial views are rendered without any layout.
func (*Views) ReqFuncs ¶
func (views *Views) ReqFuncs(reqFuncs ReqFuncMap)
ReqFuncs adds the elements of the argument map to the list of request-aware functions to inject into templates.
func (*Views) ServerError ¶
func (views *Views) ServerError(w http.ResponseWriter, err error)
ServerError writes an error message and stack trace to the logger, then sends a generic 500 Internal Server Error response to the user.
Source Files
Directories