Configuration

maniflex.Config is the single struct passed to maniflex.New. Every field has a sensible default; populate only the ones that differ from those defaults.

server := maniflex.New(maniflex.Config{
    Port:        8080,
    PathPrefix:  "/api",
})

Server

PathPrefix does not affect /static, /files, or /health. Those are mounted at the router root. See Static Files for the static serving options.

HTTP timeouts

The framework owns the http.Server, and net/http gives that struct no deadlines by default. These are the ones it sets on your behalf:

ReadHeaderTimeout is the slowloris defence. Without it a client can hold a connection open forever by dribbling one header byte at a time, and enough such connections exhaust the server’s file descriptors without a single request ever reaching the pipeline. Set a negative value to disable a timeout (which is what net/http reads as “no deadline”) — only sensible behind a proxy that already bounds header reads.

ReadTimeout and WriteTimeout are deliberately left unset, because both are whole-request deadlines rather than idle deadlines:

• A ReadTimeout caps how long a client may take to upload, so a large file over a slow link is severed mid-transfer.
• A WriteTimeout covers the entire response, so any value at all would cut a long-lived stream — realtime.SSEHandler, a large download — off at that mark.

Set them when you know your request sizes and have no streaming endpoints. The header phase stays bounded by ReadHeaderTimeout either way.

Limits

An export holds its entire result set in memory until the last byte reaches the client, so concurrency multiplies the largest allocation the server makes. The per-model MaxExportRows bounds one export’s rows but not the row width nor the number in flight; this bounds the product. Requests over the limit are refused immediately with 503 EXPORT_BUSY and a Retry-After, not queued. See CSV / XLSX Export.

Database

See Database Backends for adapter construction.

File storage and encryption

Logging

Logger is used by ctx.Logger(), which adds request_id, trace_id, and service attributes per request. Route it to a JSON handler in production.

Pipeline tracing

Config.Trace enables verbose debug output of the request pipeline. All trace output is at DEBUG level through Logger, so the handler must accept DEBUG records to see anything.

cfg.Trace = maniflex.PipelineTrace{Enabled: true, Skips: true}

Enabled expands into the three standard flags unless one of those three is already set, in which case it stays out of the way and you get exactly what you named. Bodies and Skips are additive: setting one does not suppress the expansion, so the example above gives all four.

cfg.Trace = maniflex.PipelineTrace{Enabled: true, Steps: true}  // Steps only
cfg.Trace = maniflex.PipelineTrace{Bodies: true}                // Bodies only

Leave Bodies off in production.

Lifecycle

See Graceful Shutdown.

Health probe

Set HealthTimeout shorter than your probe’s timeoutSeconds so the handler can return 503 cleanly before the probe times out.

Reading from environment

maniflex.ConfigFromEnv(prefix) populates a Config from a conventional set of environment variables. Use it for twelve-factor deployments, then override individual fields in code where needed.

cfg, err := maniflex.ConfigFromEnv("")   // or "ORDERS" → ORDERS_PORT, ORDERS_DB_WRITE_URL, …
if err != nil {
    log.Fatal(err)
}
cfg.DisableAutoMigrate = true  // disable for production
server := maniflex.New(cfg)

These are the variables it reads, and the only ones — anything else on Config is set in code:

A variable that is unset leaves its field at the zero value, for ApplyDefaults to fill in. A variable that is set but unreadable is an error — PORT=808O, QUERY_TIMEOUT_MS=abc, HEALTH_CHECK_DB=ture — naming the variable and the value it could not read. Every bad variable is reported at once, so two typos take one deploy to find rather than two. Don’t discard this error: a mistyped PORT that is quietly ignored gives you a healthy-looking server listening on 8080, and nothing anywhere says why.