Skip to content
Unreleased: these pages follow the main branch. The latest release is v0.5.
Server-rendered HTML

Server-rendered HTML

How pages are rendered, how a visitor’s state travels in an encrypted cookie, and how a failed form finds its way back to the page it came from.

Pages are components

A component is anything with Render(ctx context.Context, w io.Writer) error (view.Component). templ generates that method, so the core doesn’t depend on templ. view.Template adapts html/template, and view.ComponentFunc a function:

// illustrative
hello := view.ComponentFunc(func(ctx context.Context, w io.Writer) error {
	_, err := io.WriteString(w, "<p>Hello</p>")
	return err
})
return c.Render(http.StatusOK, hello)

c.Render (and web.Render) renders into a buffer with the *web.Ctx as ctx, and writes the page only when the component has finished. So a render error, such as an unknown route name in web.URL, becomes an error page, never half a page. And because the session is saved when the response starts, a CSRF token that view.CSRFField creates during the render still reaches the cookie. Helpers read the router and the session from ctx; view.Template gets no context, so pass what it needs in data.

The session is the cookie

The session middleware decrypts the cookie when a request arrives and writes it back when the response starts. The cookie holds a random ID, the CSRF token, when the session started and was last used, your values (as JSON), and the flash data. It is sealed with AES-256-GCM under a key derived from APP_KEY for every write (HKDF-SHA256, random salt), with the cookie name authenticated alongside. A cookie that doesn’t decrypt, or has expired, starts an empty session.

  • Lifetime. Expiry is checked against the times inside the cookie, so a replayed cookie can’t outlive it: SESSION_TTL (2h) idle, and SESSION_MAX_TTL (7 days) in all, restarted by Regenerate and Invalidate.
  • Writes. No cookie until something is stored; then a write when the session changes, and at most every tenth of SESSION_TTL to keep it alive.
  • Attributes. HttpOnly, SameSite=Lax, and Secure outside development and testing. A Secure cookie without SESSION_DOMAIN and with path / is named __Host-anetos_session, so a subdomain can’t plant one.
  • Key rotation. Each cookie records its key. Old keys in APP_PREVIOUS_KEYS still decrypt, and the cookie is re-encrypted with APP_KEY on its next write. Renaming the cookie, or switching Secure (which adds or drops __Host-), ends every session.

Flash data. s.Flash(key, v) is readable for the rest of this request and during the next one; saving that request drops it (Keep and Reflash extend it). Field errors and old input are stricter: view.Errors and view.Old return only what the previous request flashed, for one request.

The form round trip

    sequenceDiagram
    participant B as Browser
    participant M as Session + CSRF middleware
    participant H as web.H
    participant E as DefaultErrorHandler
    B->>M: GET /notes/new
    M-->>B: 200 form with _token (Set-Cookie)
    B->>M: POST /notes (Referer: /notes/new)
    M->>M: origin and token checks (403 on failure)
    M->>H: bind and validate
    H-->>E: validation error (your handler doesn't run)
    E-->>B: 303 to /notes/new, errors and input flashed
    B->>M: GET /notes/new
    M-->>B: 200 form with view.Errors and view.Old
  

When a request other than GET or HEAD fails validation (422, or 400 with field errors), web.DefaultErrorHandler redirects back if the request comes from a browser (Sec-Fetch-Mode: navigate, or Accept listing text/html), isn’t htmx (unless boosted), and has a session. It flashes the errors in order and the posted values, minus _method and fields whose names contain password, secret or token. The 303 goes to the Referer if it is on this site, else /: the session doesn’t track pages. JSON clients and htmx get the 422.

CSRF protection

web.CSRF checks every method except GET, HEAD, OPTIONS and TRACE in two layers. First, Go’s http.CrossOriginProtection rejects requests the browser marks as cross-site (Sec-Fetch-Site, or an Origin that isn’t this host); requests with neither header pass. Then the _token field or X-CSRF-Token header must match the session’s token, which is masked with a fresh random pad at every render so compressed pages never repeat it (BREACH). Both failures are 403. Regenerate replaces the token.

Method override, assets and htmx

  • web.MethodOverride runs globally, before routing picks a route by method: a POST with _method of PUT, PATCH or DELETE, in the query or a URL-encoded body (restored afterwards), is routed with that method. Multipart bodies aren’t read; put ?_method=PUT in the action.
  • view.NewAssets hashes every file once, at startup. assets.URL adds ?v=<hash>; the current hash is cacheable for a year, anything else revalidates (no-cache, ETag).
  • htmx is bundled (htmx.FS), so there’s no JavaScript build step. c.IsHTMX() adds Vary: HX-Request, and a layout sends the token with hx-headers and view.CSRFToken.

A frontend built by Vite

Since v0.6, a web project can also have a frontend that Vite builds (frontend/, anetos new --vite or vite:install): modules, CSS and npm packages, for the parts of a page that need more than htmx. The pages stay templ components, rendered on the server; @vite.Tags adds the entry’s scripts and stylesheets to them.

  • Built once, embedded: vite build writes hashed files and a manifest into public/build, which the binary embeds. vite.New reads the manifest at startup; per request, @vite.Tags only writes the tags it already knows.
  • Development through one address: anetos dev runs Vite and forwards /build/ to it, so the page, its modules and the hot reload’s WebSocket share the app’s origin: no CORS, and cookies work as they do in production.
  • Node at build time only: the server runs the binary; the tests run without a build. Where the app is deployed, a missing build or VITE_DEV_URL stops it at startup rather than serving pages without their scripts.

Pages in Vue, React or Svelte

Since v0.6, a page can also be a Vue, React or Svelte component that Inertia’s client renders (web/inertia). The handler stays the same kind of Go handler: it renders a page component with props instead of a templ component. The first visit is server-rendered HTML holding the page; the client’s visits after it get the page as JSON and swap the component, without reloading. Sessions, CSRF, the redirect back with errors and the flash work as they do for templ pages; the errors reach the component in its errors prop. See Pages in Vue, React or Svelte with Inertia, and Frontends for the ways to serve a frontend and how to choose.

Guarantees and trade-offs

  • Unreadable and unforgeable, as long as every instance shares APP_KEY.
  • Not revocable. Invalidate empties the session in this browser; a copied cookie works until its idle or absolute expiry.
  • About 4 KB. If the session doesn’t fit, a failed form’s input is dropped first (logged; errors stay), then the save is skipped (logged). Store IDs, not records.
  • Changes after the response starts are lost, as when streaming.
  • Kept out of shared caches: Cache-Control: private (unless you set one) and Vary: Cookie.
  • Why cookies by default: no store to run, configure or clean up, and any instance serves any request. Server-side stores, which can revoke sessions, are a setting away (SESSION_DRIVER).

Coming from another framework? This is a cookie session, always encrypted, like Rails’ default. view.CSRFField, view.Old and view.Errors do what Django’s {% csrf_token %} and form errors, Laravel’s @csrf, old() and $errors, or Rails’ form helpers do, and a token mismatch is a 403.

Related