Documentation on go-bananas

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

Install

go-bananas requires Go 1.26 or newer.

go get github.com/mikehelmick/go-bananas@latest

A minimal server

The snippet below renders an HTML page through the render package and serves it with the graceful server. Templates are loaded from any fs.FS — an embed.FS in production.

package main

import (
	"context"
	"embed"
	"net/http"

	"github.com/gorilla/mux"
	"github.com/mikehelmick/go-bananas/middleware"
	"github.com/mikehelmick/go-bananas/render"
	"github.com/mikehelmick/go-bananas/server"
	"github.com/mikehelmick/go-bananas/webctx"
)

//go:embed templates static
var assets embed.FS

func main() {
	ctx := context.Background()

	h, err := render.New(assets, render.WithDevMode(true))
	if err != nil {
		panic(err)
	}

	r := mux.NewRouter()
	r.Use(middleware.Recovery(h))
	r.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
		m := webctx.TemplateMapFromContext(req.Context())
		m.Title("Home")
		h.RenderHTML(w, "home", m)
	})

	// Serve the embedded static assets the renderer's SRI tags point at.
	static := middleware.ConfigureStaticAssets(true)
	r.PathPrefix("/static/").Handler(static(http.FileServerFS(assets)))

	srv, err := server.New("8080")
	if err != nil {
		panic(err)
	}
	_ = srv.ServeHTTPHandler(ctx, r)
}

With a templates/home.html containing:

The middleware chain

Mon, 01 Jan 0001 00:00:00 +0000

Every middleware constructor returns a gorilla/mux.MiddlewareFunc, so you register them with router.Use. Most ordering is flexible, but a few have prerequisites (noted below and in each function’s GoDoc).

Recommended order

r := mux.NewRouter()
r.Use(middleware.Recovery(h)) // outermost: catch panics
r.Use(middleware.PopulateRequestID(h)) // assign a request id
r.Use(middleware.PopulateTraceID()) // extract upstream trace id
r.Use(middleware.PopulateLogger(logging.DefaultLogger())) // request-scoped logger
r.Use(middleware.LogRequests()) // one Info line per request
r.Use(middleware.SecureHeaders(devMode, middleware.ServerTypeHTML))
r.Use(middleware.ProcessNonce()) // per-request CSP nonce
r.Use(middleware.ContentSecurityPolicy(
	"default-src 'self'; script-src 'self' 'nonce-{{nonce}}'; object-src 'none'"))
r.Use(middleware.GzipResponse())
r.Use(middleware.RequireSession(store, nil, h)) // load/save the session
r.Use(middleware.CheckSessionIdleNoAuth(30*time.Minute, onIdle))
r.Use(middleware.HandleCSRF(h)) // after RequireSession
r.Use(middleware.PopulateTemplateVariables(middleware.TemplateConfig{
	ServerName: "go-bananas",
	DevMode: devMode,
}))
r.Use(middleware.InjectCurrentPath())
r.Use(middleware.ProcessLocale(locales)) // i18n — see the i18n guide

Don’t forget the static assets the renderer’s SRI tags point at — serve them with cache headers via ConfigureStaticAssets:

Rendering & templates

Mon, 01 Jan 0001 00:00:00 +0000

The render package loads templates from an fs.FS and renders HTML, JSON, and CSV. It buffers output before writing, so a template error never produces a partial response.

Constructing a renderer

r, err := render.New(fsys,
	render.WithDevMode(devMode), // reload templates each render; show real errors
	render.WithBuildID(buildID), // cache-busting query string on assets
	render.WithLogger(logger), // *slog.Logger for render-time errors
	render.WithFuncs(template.FuncMap{ // add or override template functions
		"greeting": func() string { return "hi" },
	}),
)

Templates are discovered by walking the FS: files ending in .html become HTML templates and .txt files become text templates. Each template is referenced by its {{ define "name" }}.

Sessions, flash & CSRF

Mon, 01 Jan 0001 00:00:00 +0000

Sessions

go-bananas uses gorilla/sessions for storage. The cookiestore package provides a secure-cookie store whose HMAC and encryption keys are hot-reloadable: they come from an EntropyFunc consulted on every request, so keys can be rotated (or sourced from a secret/key manager) without a restart.

store := cookiestore.New(entropy, &sessions.Options{
	Path: "/",
	MaxAge: 3600,
	HttpOnly: true,
	Secure: true,
})

Install RequireSession to load and save the session per request:

r.Use(middleware.RequireSession(store, nil, h))

Read and write typed values through the session package (CSRFToken, LastActivity, Nonce, Region, and Flash), all of which are nil-safe.

Authenticator & OIDC

Mon, 01 Jan 0001 00:00:00 +0000

go-bananas has exactly one authentication seam — the Authenticator interface — and no dependency on any identity provider. You implement it; the framework gates routes with it.

type Authenticator interface {
	// Authenticate returns the principal, or (nil, nil) for an anonymous request.
	// A non-nil error results in a 500.
	Authenticate(r *http.Request) (principal any, err error)
}

Gate routes with RequireAuthenticated:

me := r.NewRoute().Subrouter()
me.Use(middleware.RequireAuthenticated(myAuth, h))
me.HandleFunc("/me", profile)

On success the principal is stored on the context; retrieve it anywhere with webctx.PrincipalFromContext(ctx). An anonymous request gets a 401; an error gets a 500.

Secrets & keys

Mon, 01 Jan 0001 00:00:00 +0000

The secrets and keys packages abstract secret storage and key management behind small interfaces. The core ships dependency-free providers; cloud providers are opt-in sub-packages that self-register, so their SDKs are only compiled into binaries that import them.

Selecting a provider

Providers register themselves by name. Choose one with Config.Type and construct it with SecretManagerFor / KeyManagerFor:

sm, err := secrets.SecretManagerFor(ctx, &secrets.Config{Type: "FILESYSTEM",
	FilesystemRoot: "/var/run/secrets"})

km, err := keys.KeyManagerFor(ctx, &keys.Config{Type: "FILESYSTEM",
	FilesystemRoot: "/var/run/keys"})

The core registers FILESYSTEM and IN_MEMORY for secrets, and FILESYSTEM for keys — all with zero external dependencies.

HTTP server

Mon, 01 Jan 0001 00:00:00 +0000

The server package wraps the standard library with graceful shutdown. The listener is bound at construction, so the address is available immediately, but serving does not begin until you call ServeHTTP/ServeHTTPHandler — which block until the context is cancelled.

srv, err := server.New("8080") // empty string lets the OS choose a port
if err != nil {
	return err
}
log.Printf("listening on %s", srv.Addr())

ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer cancel()

// Blocks until ctx is cancelled, then shuts down with a 5s grace period.
return srv.ServeHTTPHandler(ctx, handler)

ServeHTTPHandler builds an http.Server with a sensible ReadHeaderTimeout. If you need full control (custom timeouts, TLS config, an observability wrapper around the handler), build your own *http.Server and call ServeHTTP instead:

Cache & logging

Mon, 01 Jan 0001 00:00:00 +0000

Cache

The cache package is a generic, thread-safe, in-memory cache where every entry expires after the same duration. A background goroutine purges expired entries; call Stop when you are done.

c, err := cache.New[string](time.Minute)
if err != nil {
	return err
}
defer c.Stop()

c.Set("greeting", "hello")
if v, ok := c.Lookup("greeting"); ok {
	fmt.Println(v)
}

WriteThruLookup computes a missing value and caches it, coalescing concurrent callers so the (possibly expensive) lookup runs at most once:

Internationalization

Mon, 01 Jan 0001 00:00:00 +0000

The i18n package loads gettext translations and resolves the best locale per request. It implements the middleware.LocaleProvider seam, so wiring it up makes ProcessLocale — and the renderer’s t/tDefault template functions — work end to end.

Layout and loading

One top-level directory per locale, each containing a default.po:

locales/
├── en/default.po
├── es/default.po
└── pt_BR/default.po

Embed and load it:

//go:embed locales
var localesFS embed.FS

sub, _ := fs.Sub(localesFS, "locales")
locales, err := i18n.Load(sub) // options: WithDefaultLocale, WithReloading
if err != nil { /* handle */ }

r.Use(middleware.ProcessLocale(locales))

ProcessLocale resolves the locale from the ?lang= query parameter, then the Accept-Language header (full q-list matching via x/text/language, with region fallback — pt-br finds pt_BR). It stores the translator on the context and populates locale, textLanguage, and textDirection (RTL-aware) on the template map.

Forms

Mon, 01 Jan 0001 00:00:00 +0000

The form package implements the server-side-rendering form loop: decode a POST into a struct, validate it, and — when the input is invalid — re-render the same page with the user’s values preserved and per-field error messages shown inline.

The struct with dual tags

A form is an ordinary struct carrying two sets of tags. The form tags drive binding (gorilla/schema) and the validate tags drive validation (go-playground/validator). Errors come back keyed by the form-tag name, so the same name identifies a field in your HTML, your binding, and your errors.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

go-bananas has no central config package, and that is a deliberate choice. Each package that needs environment configuration exposes its own small Config struct with env tags, and your application composes the ones it uses into a single struct that sethvargo/go-envconfig processes in one pass. A package owns the env vars it understands; your app decides which packages to assemble.

Per-package Config structs

Several packages already follow this pattern — for example secrets.Config and keys.Config — and this release adds logging.Config: