Documentation
¶
Overview ¶
Package redirect provides HTTP redirect middleware for common URL normalization patterns in celeris.
Nine constructor functions cover redirect and rewrite scenarios:
Redirect Functions ¶
- HTTPSRedirect — redirects HTTP traffic to HTTPS
- WWWRedirect — redirects non-www to www subdomain
- NonWWWRedirect — redirects www to non-www host
- TrailingSlashRedirect — adds trailing slash when missing
- RemoveTrailingSlashRedirect — strips trailing slash
Combined Redirect Functions ¶
- HTTPSWWWRedirect — redirects to HTTPS + www in a single redirect
- HTTPSNonWWWRedirect — redirects to HTTPS + non-www in a single redirect
Rewrite Functions ¶
- TrailingSlashRewrite — adds trailing slash in-place (no redirect)
- RemoveTrailingSlashRewrite — strips trailing slash in-place (no redirect)
Each constructor accepts an optional Config to override the redirect status code, skip specific paths, or provide a dynamic skip function. The rewrite functions accept Config for skip logic but ignore the Code field since they do not send a redirect response.
Redirect Code (301 vs 308) ¶
The default redirect code is 301 (Moved Permanently). This is appropriate for GET requests but can cause problems for POST/PUT/DELETE: browsers and HTTP clients are allowed to change the request method to GET when following a 301 redirect (RFC 7231 §6.4.2). Set Config.Code to 308 (Permanent Redirect) to guarantee the client preserves the original request method (RFC 7538 §3). Use 307 for the temporary equivalent that also preserves the method.
Query String Preservation ¶
All redirect functions preserve the original query string. The query is appended to the redirect URL when non-empty.
Short-Circuit Behavior ¶
When a redirect occurs, the middleware returns immediately via celeris.Context.Redirect without calling c.Next(). Downstream handlers are not executed.
Empty Host ¶
If celeris.Context.Host returns an empty string (malformed request), all redirect and rewrite functions pass through to c.Next() without modification. This prevents generating malformed redirect URLs.
Root Path Handling ¶
The trailing slash variants treat the root path "/" as a no-op. "/" is never modified by TrailingSlashRedirect (already has a slash) or RemoveTrailingSlashRedirect (root must keep its slash).
Pre-Routing Middleware ¶
This middleware is designed to run via celeris.Server.Pre so that URL normalization occurs before route lookup:
server.Pre(redirect.HTTPSRedirect()) server.Pre(redirect.TrailingSlashRedirect())
Redirect Loops ¶
Be careful not to combine conflicting redirect middleware. For example, using both TrailingSlashRedirect and RemoveTrailingSlashRedirect creates an infinite redirect loop. Similarly, using both WWWRedirect and NonWWWRedirect causes a loop. The combined constructors HTTPSWWWRedirect and HTTPSNonWWWRedirect avoid the double-redirect that would occur from chaining HTTPSRedirect with WWWRedirect or NonWWWRedirect.
Reverse Proxy Interaction ¶
When running behind a TLS-terminating reverse proxy, install the proxy middleware via Server.Pre() BEFORE redirect middleware. Without it, Scheme() returns "http" (the backend transport), causing an infinite redirect loop with HTTPSRedirect.
Choosing a Constructor ¶
The package provides 9 constructors organized into three categories:
Redirect (sends 3xx response):
HTTPSRedirect, WWWRedirect, NonWWWRedirect, TrailingSlashRedirect, RemoveTrailingSlashRedirect
Combined redirect (avoids double-redirect):
HTTPSWWWRedirect, HTTPSNonWWWRedirect
Rewrite (modifies path in-place, no redirect):
TrailingSlashRewrite, RemoveTrailingSlashRewrite
Use redirect when clients should update their URLs (SEO, bookmarks). Use rewrite when normalization is internal (the client URL stays the same). Use combined constructors when both scheme and host need changing.
Skipping ¶
Use Config.Skip for dynamic skip logic or Config.SkipPaths for exact-match path exclusions. Skipped requests call c.Next() without any redirect.
Index ¶
- func HTTPSNonWWWRedirect(config ...Config) celeris.HandlerFunc
- func HTTPSRedirect(config ...Config) celeris.HandlerFunc
- func HTTPSWWWRedirect(config ...Config) celeris.HandlerFunc
- func NonWWWRedirect(config ...Config) celeris.HandlerFunc
- func RemoveTrailingSlashRedirect(config ...Config) celeris.HandlerFunc
- func RemoveTrailingSlashRewrite(config ...Config) celeris.HandlerFunc
- func TrailingSlashRedirect(config ...Config) celeris.HandlerFunc
- func TrailingSlashRewrite(config ...Config) celeris.HandlerFunc
- func WWWRedirect(config ...Config) celeris.HandlerFunc
- type Config
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HTTPSNonWWWRedirect ¶
func HTTPSNonWWWRedirect(config ...Config) celeris.HandlerFunc
HTTPSNonWWWRedirect redirects HTTP requests to HTTPS and www to non-www in a single redirect. Requests that are already on HTTPS without www pass through to the next handler.
The default status code is 301 (Moved Permanently). Note that 301 allows browsers to change the request method (e.g., POST becomes GET). Use Config{Code: 308} to preserve the original method.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/redirect"
)
func main() {
// Redirect to HTTPS + non-www in a single redirect.
_ = redirect.HTTPSNonWWWRedirect()
}
Output:
func HTTPSRedirect ¶
func HTTPSRedirect(config ...Config) celeris.HandlerFunc
HTTPSRedirect redirects HTTP requests to HTTPS. HTTPS requests pass through to the next handler. The redirect URL preserves the original host, path, and query string.
The default status code is 301 (Moved Permanently). Note that 301 allows browsers to change the request method (e.g., POST becomes GET). Use Config{Code: 308} to preserve the original method.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/redirect"
)
func main() {
// Redirect all HTTP traffic to HTTPS.
_ = redirect.HTTPSRedirect()
}
Output:
Example (Permanent) ¶
package main
import (
"github.com/goceleris/celeris/middleware/redirect"
)
func main() {
// Use 308 Permanent Redirect to preserve request method.
_ = redirect.HTTPSRedirect(redirect.Config{Code: 308})
}
Output:
Example (SkipPaths) ¶
package main
import (
"github.com/goceleris/celeris/middleware/redirect"
)
func main() {
// Skip HTTPS redirect for health check and readiness probe endpoints.
_ = redirect.HTTPSRedirect(redirect.Config{
SkipPaths: []string{"/health", "/healthz", "/ready"},
})
}
Output:
func HTTPSWWWRedirect ¶
func HTTPSWWWRedirect(config ...Config) celeris.HandlerFunc
HTTPSWWWRedirect redirects HTTP requests to HTTPS and non-www to www in a single redirect. Requests that are already on HTTPS with www pass through to the next handler.
The default status code is 301 (Moved Permanently). Note that 301 allows browsers to change the request method (e.g., POST becomes GET). Use Config{Code: 308} to preserve the original method.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/redirect"
)
func main() {
// Redirect to HTTPS + www in a single redirect.
_ = redirect.HTTPSWWWRedirect()
}
Output:
func NonWWWRedirect ¶
func NonWWWRedirect(config ...Config) celeris.HandlerFunc
NonWWWRedirect redirects www requests to the non-www host. Requests without the www prefix pass through to the next handler. The redirect URL preserves the original scheme, path, and query string.
The default status code is 301 (Moved Permanently). Note that 301 allows browsers to change the request method (e.g., POST becomes GET). Use Config{Code: 308} to preserve the original method.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/redirect"
)
func main() {
// Redirect www to non-www host.
_ = redirect.NonWWWRedirect()
}
Output:
func RemoveTrailingSlashRedirect ¶
func RemoveTrailingSlashRedirect(config ...Config) celeris.HandlerFunc
RemoveTrailingSlashRedirect strips a trailing slash from the request path. The root path "/" and paths without a trailing slash pass through to the next handler.
The default status code is 301 (Moved Permanently). Note that 301 allows browsers to change the request method (e.g., POST becomes GET). Use Config{Code: 308} to preserve the original method.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/redirect"
)
func main() {
// Strip the trailing slash from paths.
_ = redirect.RemoveTrailingSlashRedirect()
}
Output:
func RemoveTrailingSlashRewrite ¶
func RemoveTrailingSlashRewrite(config ...Config) celeris.HandlerFunc
RemoveTrailingSlashRewrite strips a trailing slash from the request path in-place. Unlike RemoveTrailingSlashRedirect, this does not send a redirect response -- the request is processed with the modified path.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/redirect"
)
func main() {
// Strip trailing slash in-place without sending a redirect.
_ = redirect.RemoveTrailingSlashRewrite()
}
Output:
func TrailingSlashRedirect ¶
func TrailingSlashRedirect(config ...Config) celeris.HandlerFunc
TrailingSlashRedirect adds a trailing slash to the request path when missing. The root path "/" and paths already ending with "/" pass through to the next handler.
The default status code is 301 (Moved Permanently). Note that 301 allows browsers to change the request method (e.g., POST becomes GET). Use Config{Code: 308} to preserve the original method.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/redirect"
)
func main() {
// Add a trailing slash to paths that are missing one.
_ = redirect.TrailingSlashRedirect()
}
Output:
func TrailingSlashRewrite ¶
func TrailingSlashRewrite(config ...Config) celeris.HandlerFunc
TrailingSlashRewrite adds a trailing slash to the request path in-place. Unlike TrailingSlashRedirect, this does not send a redirect response -- the request is processed with the modified path.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/redirect"
)
func main() {
// Add trailing slash in-place without sending a redirect.
_ = redirect.TrailingSlashRewrite()
}
Output:
func WWWRedirect ¶
func WWWRedirect(config ...Config) celeris.HandlerFunc
WWWRedirect redirects non-www requests to the www subdomain. Requests already on the www subdomain pass through to the next handler. The redirect URL preserves the original scheme, path, and query string.
The default status code is 301 (Moved Permanently). Note that 301 allows browsers to change the request method (e.g., POST becomes GET). Use Config{Code: 308} to preserve the original method.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/redirect"
)
func main() {
// Redirect non-www to www subdomain.
_ = redirect.WWWRedirect()
}
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
// Code is the HTTP redirect status code. Must be 301, 302, 303, 307, or 308.
// Default: 301 (Moved Permanently).
Code int
}
Config defines the redirect middleware configuration.
Source Files