Documentation
¶
Overview ¶
Package cors provides Cross-Origin Resource Sharing (CORS) middleware for Celeris.
Call New with an optional Config to create a middleware handler. With no arguments, all origins are allowed (AllowOrigins: ["*"]). Pass a Config to restrict origins, enable credentials, set MaxAge, and more.
Key Config fields:
- AllowOrigins: static origin list; supports subdomain wildcards ("https://*.example.com").
- AllowOriginsFunc: custom callback to validate an origin string.
- AllowOriginRequestFunc: like AllowOriginsFunc but receives the full request context.
- AllowCredentials: set true to emit Access-Control-Allow-Credentials.
- MirrorRequestHeaders: reflect Access-Control-Request-Headers back on preflight.
- AllowPrivateNetwork: emit Access-Control-Allow-Private-Network on preflight.
- Skip / SkipPaths: bypass CORS processing for selected requests or paths.
AllowOriginsFunc and AllowOriginRequestFunc cannot be combined with a wildcard ("*") AllowOrigins entry. Using AllowCredentials with "*" panics at New. Subdomain wildcards with AllowCredentials also panic unless UnsafeAllowCredentialsWithWildcard is set.
Documentation ¶
Full guides and examples: https://goceleris.dev/docs/middleware-security
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New(config ...Config) celeris.HandlerFunc
New creates a CORS middleware with the given config.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/cors"
)
func main() {
// Zero-config: allows all origins (wildcard *).
_ = cors.New()
}
Output:
Example (Customize) ¶
package main
import (
"github.com/goceleris/celeris/middleware/cors"
)
func main() {
// Start from a zero Config and customize.
_ = cors.New(cors.Config{
AllowOrigins: []string{"https://example.com"},
})
}
Output:
Example (DynamicOrigin) ¶
package main
import (
"github.com/goceleris/celeris/middleware/cors"
)
func main() {
// Dynamic origin validation based on request context.
_ = cors.New(cors.Config{
AllowOrigins: []string{"https://static.example.com"},
AllowOriginsFunc: func(origin string) bool {
// Check a database or config for allowed origins.
return origin == "https://dynamic.example.com"
},
})
}
Output:
Example (Restricted) ¶
package main
import (
"github.com/goceleris/celeris/middleware/cors"
)
func main() {
// Restrict to specific origins with credentials.
_ = cors.New(cors.Config{
AllowOrigins: []string{"https://example.com"},
AllowCredentials: true,
MaxAge: 3600,
})
}
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 on c.Path()).
// Requests matching these paths bypass CORS processing entirely.
SkipPaths []string
// AllowOrigins lists allowed origins. Default: ["*"].
AllowOrigins []string
// AllowOriginsFunc is a custom function to validate origins.
// Called after static and wildcard origin checks.
// Cannot be used with wildcard "*" AllowOrigins.
//
// The middleware validates that the incoming Origin header looks like a
// serialized origin (has scheme + host, no path/query/fragment/userinfo)
// before passing it to this function. Malformed origins are rejected.
AllowOriginsFunc func(origin string) bool
// AllowOriginRequestFunc validates origins with access to the full request context.
// Called after AllowOriginsFunc. Useful for tenant-based or header-dependent
// origin decisions. Cannot be used with wildcard "*" AllowOrigins.
//
// The same serialized-origin validation applies as for AllowOriginsFunc.
AllowOriginRequestFunc func(c *celeris.Context, origin string) bool
// AllowMethods lists allowed HTTP methods.
// Default: [GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS].
AllowMethods []string
// AllowHeaders lists allowed request headers.
// Default: [Origin, Content-Type, Accept, Authorization].
AllowHeaders []string
// MirrorRequestHeaders, when true, causes the middleware to reflect
// the Access-Control-Request-Headers value back in preflight responses
// instead of using a fixed AllowHeaders list. This is useful when the
// full set of request headers is not known ahead of time. When false
// (the default), the AllowHeaders list is used.
MirrorRequestHeaders bool
// ExposeHeaders lists headers the browser can access.
ExposeHeaders []string
// AllowCredentials indicates whether credentials are allowed.
AllowCredentials bool
// UnsafeAllowCredentialsWithWildcard suppresses the panic that fires when
// AllowCredentials is true and an AllowOrigins entry contains a wildcard
// (e.g. "https://*.example.com"). This combination is spec-compliant
// (the browser receives the echoed origin, not "*"), but it widens the
// credential scope to any matching subdomain. Set this only if you fully
// understand the security implications.
UnsafeAllowCredentialsWithWildcard bool
// AllowPrivateNetwork enables the Private Network Access spec.
// When true, preflight responses include Access-Control-Allow-Private-Network.
AllowPrivateNetwork bool
// MaxAge is the preflight cache duration in seconds. Default: 0 (no cache).
MaxAge int
}
Config defines the CORS middleware configuration.
Source Files
Click to show internal directories.
Click to hide internal directories.