GioJSdocs
ReleasesGitHub ↗
On this page

[[redirects]]

Redirect rules evaluated in Rust before routing, with :param and *rest captures substituted into the target.

gio.toml
[[redirects]]
from = "/blog/:slug"
to = "/posts/:slug"
status = 301

One table per rule. The same rules can also come from middleware.ts; see Middleware for how the sources combine, and Redirecting for the other ways to redirect.

Reference

KeyDefaultDescription
from (required)string-The path pattern: literal segments, :param (one segment) and a final *rest (the rest of the path, possibly empty). Must start with /.
to (required)string-The target path. It must start with one / - a redirect stays on this site, so //host and /\host, which a browser reads as another site, are refused - and may use the pattern's captures by name, in any order.
statusinteger302301 or 308 (permanent; browsers and search engines remember it), 302 or 307 (temporary). 307 and 308 keep the method and body.

Behavior

  • Rules match the canonical request path (repeated and trailing slashes collapsed, unreserved escapes decoded). The first matching rule wins.
  • The original query string is appended to the target as it was sent: /blog/hello?ref=x goes to /posts/hello?ref=x.
  • An empty *rest contributes nothing: with /old/*rest to /new/*rest, /old goes to /new.
  • Redirects run after guards and before rewrites, gio.toml rules before middleware.ts ones. A guard on the same path therefore wins.
  • The answer is the status with a Location header and an empty body, marked X-Gio-Cache: bypass. [[headers]] rules for the requested path are stamped on it.
  • Rust's own /_gio endpoints are never redirected.

Invalid rules

A rule that cannot be compiled stops startup, naming the file, the line, the rule's from and the reason - a skipped rule would leave its old URL serving. giojs-server --check-config reports the same problems under errors, all of them at once:

text
gio.toml:4: invalid [[redirects]] entry for "/old": pattern must start with '/': https://example.com/new
gio.toml:9: invalid [[redirects]] entry for "/old": redirect status must be 301, 302, 307, or 308 (got 303)
gio.toml:13: invalid [[redirects]] entry for "/a/:id": target references unknown capture 'slug'

A misspelled key (stauts) is a startup error, like everywhere in gio.toml.

Examples

Move a section

gio.toml
[[redirects]]
from = "/docs/v1/*rest"
to = "/docs/*rest"
status = 308

Reorder captures

gio.toml
[[redirects]]
from = "/u/:user/p/:post"
to = "/p/:post/by/:user"     # /u/alice/p/42 -> /p/42/by/alice

Good to know

  • Redirects to another site are not supported here: to must be a path. Redirect from a route handler or with redirect() for that.
  • No query, header or cookie conditions: 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.8*rest matches zero segments, rules match the canonical path, header rules are stamped on redirect responses, and a rule that cannot be compiled stops startup (it was skipped with a warning), a to a browser reads as another site (//host, /\host) included.
v0.1.0-beta.6Introduced.