GioJSdocs
ReleasesGitHub ↗
On this page

[[headers]]

Response headers stamped on every response to matching paths, redirects included.

gio.toml
[[headers]]
path = "/api/*rest"
[headers.headers]
cache-control = "no-store"
access-control-allow-origin = "https://app.example.com"

Each rule is a [[headers]] table with a path and a [headers.headers] table of names and values. For headers on every response, see [security.headers].

Reference

KeyDefaultDescription
path (required)string-The path pattern: literal segments, :param and a final *rest (/*rest covers the whole site, root included).
headers (required)table-Header name to value. Names and values are validated at startup.0 / false / empty: An empty value removes a default security header

Behavior

  • Header rules do not short-circuit: every rule whose path matches adds its headers. When two set the same header, the later one wins, and middleware.ts rules come after gio.toml's.
  • A rule's value replaces the response's own value for that header - one set by a route handler or getServerSideProps included - except set-cookie, which is added next to the response's cookies.
  • Rules match the path the client requested (before any rewrite), and are also stamped on the redirects that [[redirects]] and [[guards]] answer with, so security headers cover those too.
  • They win over the default security headers and the CSP, and an empty value removes such a default (x-frame-options = "") for the rule's paths. For any other header an empty value is sent as an empty header.
  • A Cache-Control from a rule replaces the one GioJS computes for pages.
  • A public/ file answered at the site root also gets the rules for its /public/... URL; the requested URL's rules win on a conflict. Rust's own /_gio endpoints get none.

Invalid rules

A rule with an invalid header name or value, or a bad pattern, stops startup with the file, line and reason - a skipped rule would leave its paths without the headers - and --check-config reports it under errors:

text
gio.toml:3: invalid [[headers]] entry for "/x": invalid header name: bad header

Examples

Let partners embed one section

gio.toml
[[headers]]
path = "/embed/*rest"
[headers.headers]
x-frame-options = ""
content-security-policy = "frame-ancestors https://partner.example.com"

Long caching for a versioned folder

gio.toml
[[headers]]
path = "/assets/v2/*rest"
[headers.headers]
cache-control = "public, max-age=31536000, immutable"

Two rules in one file

Each [headers.headers] belongs to the [[headers]] table right above it:

gio.toml
[[headers]]
path = "/admin/*rest"
[headers.headers]
x-robots-tag = "noindex"

[[headers]]
path = "/feed.xml"
[headers.headers]
content-type = "application/rss+xml; charset=utf-8"

Good to know

  • No conditions on query, cookies or methods: a rule matches on the path alone.
  • The rules are compiled once at startup; restart after editing them.

Version history

VersionChanges
v0.1.0-beta.8Rules also apply to redirect and guard responses and match the requested path rather than a rewritten one; a set-cookie rule adds its cookie instead of replacing the response's. *rest matches zero segments.
v0.1.0-beta.6Introduced.