Documentation
¶
Overview ¶
Package rewrite provides pre-routing URL rewrite middleware for celeris, matching the request path against ordered regular-expression rules.
Construct the middleware with New and a Config, then register it via celeris.Server.Pre so rewriting happens before route lookup. Each Rule has a Pattern (a Go regexp) and a Replacement that supports capture-group substitution ($1, $2, ...). Rules are evaluated in order and the first match wins.
A rule rewrites silently or redirects depending on RedirectCode. When zero (the default), the path is rewritten in place via celeris.Context.SetPath and downstream handlers see the new path. When set to a redirect status (301, 302, 303, 307, 308), the middleware sends an HTTP redirect preserving the scheme, host, and query string. RedirectCode may be set on Config as the default or overridden per Rule. A rule can be scoped with Methods and Host; both default to matching everything. Use Config.Skip or Config.SkipPaths to bypass requests.
New compiles patterns once via regexp.MustCompile and panics on an empty Rules slice, an invalid pattern, or an invalid non-zero RedirectCode.
server.Pre(rewrite.New(rewrite.Config{
Rules: []rewrite.Rule{
{Pattern: `^/api/v1/(.*)$`, Replacement: "/api/v2/$1"},
},
}))
In redirect mode the redirect URL is built from the request's Host and Scheme headers; validate the Host header upstream (or use silent rewrite) to avoid open redirects.
Documentation ¶
Full guides and examples: https://goceleris.dev/docs/middleware-routing-helpers
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New(config ...Config) celeris.HandlerFunc
New creates a rewrite middleware with the given config. Rules are compiled into regular expressions at init time and evaluated in the order provided. The first matching regex wins and subsequent rules are not checked.
Panics if Rules is empty or contains an invalid regex pattern (via regexp.MustCompile).
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/rewrite"
)
func main() {
// Silent rewrite: /old is rewritten to /new before route lookup.
// s := celeris.New()
// s.Pre(rewrite.New(rewrite.Config{...}))
_ = rewrite.New(rewrite.Config{
Rules: []rewrite.Rule{
{Pattern: "^/old$", Replacement: "/new"},
},
})
}
Output:
Example (CaptureGroups) ¶
package main
import (
"github.com/goceleris/celeris/middleware/rewrite"
)
func main() {
// Capture groups: extract user ID and rewrite to an API path.
_ = rewrite.New(rewrite.Config{
Rules: []rewrite.Rule{
{Pattern: `^/users/(\d+)/posts$`, Replacement: "/api/v2/users/$1/posts"},
},
})
}
Output:
Example (Conditional) ¶
package main
import (
"github.com/goceleris/celeris/middleware/rewrite"
)
func main() {
// Method-restricted rewriting: only rewrite GET and HEAD requests.
_ = rewrite.New(rewrite.Config{
Rules: []rewrite.Rule{
{
Pattern: "^/api/v1/(.*)$",
Replacement: "/api/v2/$1",
Methods: []string{"GET", "HEAD"},
},
},
})
}
Output:
Example (Redirect) ¶
package main
import (
"github.com/goceleris/celeris/middleware/rewrite"
)
func main() {
// Redirect mode: send a 301 redirect instead of a silent rewrite.
_ = rewrite.New(rewrite.Config{
Rules: []rewrite.Rule{
{Pattern: "^/old$", Replacement: "/new"},
},
RedirectCode: 301,
})
}
Output:
Types ¶
type Config ¶
type Config struct {
// Skip defines a function to skip this middleware for certain requests.
Skip func(c *celeris.Context) bool
// SkipPaths lists paths to skip (exact match).
SkipPaths []string
// Rules defines the rewrite rules. First match wins.
// Rules are evaluated in the order provided (not sorted).
Rules []Rule
// RedirectCode controls the rewrite behavior:
// - 0 (default): silent rewrite via SetPath (path is modified in-place)
// - 301, 302, 303, 307, 308: sends an HTTP redirect response
RedirectCode int
}
Config defines the rewrite middleware configuration.
type Rule ¶
type Rule struct {
// Pattern is a Go regular expression matched against the request path.
// Use ^ and $ anchors for exact path matching.
Pattern string
// Replacement is the replacement string with capture group support ($1, $2).
Replacement string
// RedirectCode overrides [Config].RedirectCode for this rule.
// When non-zero, this rule sends an HTTP redirect instead of a silent rewrite.
// When zero (default), the config-level RedirectCode is used.
RedirectCode int
// Methods restricts this rule to specific HTTP methods.
// When empty, the rule matches all methods.
// Example: []string{"GET", "HEAD"} — only rewrite GET and HEAD requests.
Methods []string
// Host restricts this rule to a specific Host header value.
// When empty, the rule matches all hosts. Supports exact match only.
Host string
}
Rule defines a single rewrite rule.
Source Files