Documentation
¶
Overview ¶
Package bodylimit provides request body size limiting middleware for celeris.
The middleware enforces a maximum request body size using a two-phase approach: first checking Content-Length (fast path), then verifying actual body bytes (catches lying or absent Content-Length). Requests exceeding the limit are rejected with 413 Request Entity Too Large.
Basic usage with the default 4 MB limit:
server.Use(bodylimit.New())
Human-readable size string:
server.Use(bodylimit.New(bodylimit.Config{
Limit: "10MB",
}))
Config.Limit accepts SI and IEC units: B, KB, MB, GB, TB, PB, EB, KiB, MiB, GiB, TiB, PiB, EiB. Fractional values are supported. When set, Limit takes precedence over MaxBytes.
LAYER OF DEFENSE — read carefully:
The DoS-grade cap lives at the engine read layer: celeris.Config.MaxRequestBodySize (default 100 MB). Bodies larger than that are rejected by the engine BEFORE any buffering happens, so the framework never holds them in memory. Set celeris.Config.MaxRequestBodySize to your real maximum at server construction time.
This middleware runs AFTER the engine has already buffered the body. Use it for per-route caps that are smaller than the server-wide MaxRequestBodySize (e.g. a /comments endpoint that should accept at most 64 KB while /uploads accepts up to MaxRequestBodySize). It is NOT a substitute for setting MaxRequestBodySize itself; a malicious client can still send up to MaxRequestBodySize before this middleware rejects them.
Enable Config.ContentLengthRequired to reject requests without Content-Length (411 Length Required), forcing clients to declare the body size up-front.
Bodyless methods (GET, HEAD, DELETE, OPTIONS, TRACE, CONNECT) are auto-skipped. Use Config.Skip or Config.SkipPaths for additional exclusions. Set Config.ErrorHandler to customize error responses.
ErrBodyTooLarge and ErrLengthRequired are exported sentinel errors usable with errors.Is for upstream error handling.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrBodyTooLarge = celeris.NewHTTPError(413, "Request Entity Too Large")
ErrBodyTooLarge is returned when the request body exceeds the configured limit.
var ErrLengthRequired = celeris.NewHTTPError(411, "Length Required")
ErrLengthRequired is returned when ContentLengthRequired is enabled and the request omits a Content-Length header.
Functions ¶
func New ¶
func New(config ...Config) celeris.HandlerFunc
New creates a body limit middleware with the given config.
Architectural note: celeris buffers the full request body before middleware executes, so this middleware cannot prevent oversized payloads from entering memory when Content-Length is absent or dishonest. The framework's own maxRequestBodySize (100 MB) provides the hard ceiling. This middleware adds an application-level limit that rejects already-buffered bodies that exceed the configured threshold.
For strict enforcement against clients that omit Content-Length, enable Config.ContentLengthRequired to reject such requests with 411 Length Required before the body check runs.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/bodylimit"
)
func main() {
// Zero-config: 4 MB limit.
_ = bodylimit.New()
}
Output:
Example (HumanReadable) ¶
package main
import (
"github.com/goceleris/celeris/middleware/bodylimit"
)
func main() {
// Human-readable size limit.
_ = bodylimit.New(bodylimit.Config{
Limit: "10MB",
})
}
Output:
Types ¶
type Config ¶
type Config struct {
// Skip defines a function to skip this middleware for certain requests.
Skip func(c *celeris.Context) bool
// Limit is a human-readable size string (e.g., "10MB", "1.5GB").
// Takes precedence over MaxBytes when set.
Limit string
// MaxBytes is the maximum allowed request body size in bytes.
// Default: 4 MB (4 * 1024 * 1024).
MaxBytes int64
// SkipPaths lists paths to skip (exact match).
SkipPaths []string
// ErrorHandler handles body-too-large errors. When non-nil, it is
// called instead of returning ErrBodyTooLarge directly.
ErrorHandler func(c *celeris.Context, err error) error
// ContentLengthRequired rejects requests that lack a Content-Length
// header with 411 Length Required. Enable this to force clients to
// declare body size up front, preventing memory exhaustion from
// unbounded streaming when the framework buffers the full body
// before middleware runs.
ContentLengthRequired bool
}
Config defines the body limit middleware configuration.
Source Files