Documentation
¶
Overview ¶
Package etag provides ETag generation and conditional-response middleware for celeris.
New returns middleware that buffers the response body of GET and HEAD requests, computes an ETag validator, and sets the ETag header. When a request carries a matching If-None-Match header, it returns 304 Not Modified with no body. Other methods and non-2xx or empty responses pass through untouched. If the downstream handler already set an ETag header, that tag is reused rather than recomputed.
By default the validator is a CRC-32 (IEEE) checksum of the body, emitted as a weak tag (W/"xxxxxxxx"). Configure behavior through Config:
- Strong: emit strong tags ("xxxxxxxx") instead of weak.
- HashFunc: supply a custom hash; it returns the opaque-tag, and the quotes and optional W/ prefix are added automatically.
- Skip / SkipPaths: bypass buffering for dynamic conditions or for exact paths (e.g. large downloads, streaming endpoints).
Because the body is buffered to compute the tag, etag should run INSIDE compression middleware so the validator is computed on the uncompressed body.
Documentation ¶
Full guides and examples: https://goceleris.dev/docs/middleware-content
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New(config ...Config) celeris.HandlerFunc
New creates an ETag middleware with the given config.
Composition: when a downstream handler or middleware (e.g. middleware/static) already sets an "etag" response header, this middleware reuses that tag instead of computing its own. The body hash is only computed when no ETag is present. This means etag(static(...)) emits exactly one ETag header — the mtime/size form static computed — and no double tagging occurs.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/etag"
)
func main() {
// Weak ETags (default) -- suitable for responses that may be
// content-negotiated or transfer-encoded.
// s := celeris.New()
// s.Use(etag.New())
_ = etag.New()
}
Output:
Example (HashFunc) ¶
package main
import (
"crypto/sha256"
"encoding/hex"
"github.com/goceleris/celeris/middleware/etag"
)
func main() {
// Use SHA-256 (truncated) instead of the default CRC-32.
_ = etag.New(etag.Config{
HashFunc: func(body []byte) string {
h := sha256.Sum256(body)
return hex.EncodeToString(h[:16])
},
})
}
Output:
Example (Skip) ¶
package main
import (
"strings"
"github.com/goceleris/celeris"
"github.com/goceleris/celeris/middleware/etag"
)
func main() {
// Dynamically skip ETag for server-sent event streams.
_ = etag.New(etag.Config{
Skip: func(c *celeris.Context) bool {
return strings.HasPrefix(c.Path(), "/events")
},
})
}
Output:
Example (SkipPaths) ¶
package main
import (
"github.com/goceleris/celeris/middleware/etag"
)
func main() {
// Skip ETag computation for large-payload endpoints.
_ = etag.New(etag.Config{
SkipPaths: []string{"/download", "/export", "/stream"},
})
}
Output:
Example (Strong) ¶
package main
import (
"github.com/goceleris/celeris/middleware/etag"
)
func main() {
// Strong ETags -- byte-for-byte identical guarantee.
_ = etag.New(etag.Config{Strong: true})
}
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
// Strong controls whether ETags use the strong format "xxxxxxxx".
// When false (default), weak ETags are used: W/"xxxxxxxx".
// Weak ETags are recommended for responses that may be content-negotiated
// or transfer-encoded.
Strong bool
// HashFunc computes a custom ETag from the response body.
// When set, the returned string is used as the opaque-tag (without quotes
// or W/ prefix -- those are added automatically based on the Strong setting).
// Default: CRC-32 IEEE hex.
HashFunc func(body []byte) string
}
Config defines the ETag middleware configuration.
Source Files