Safe Defaults

Muzak starts from settings that are safe rather than permissive. Each of them can be relaxed; none of them is relaxed by omission.

The list

The one deliberate exception

Rate limiting is off until a quota is declared. There is no limit that is right for every application, and a default one would be a number nobody chose refusing traffic nobody expected.

What is safe by default is what happens once a policy exists: the counters are bounded, the address is not taken from a header anyone can write, an IPv6 client cannot multiply its budget by rotating addresses inside its own range, and a storage that stops answering stops traffic rather than stopping the limit. See Rate Limiting.

One more thing is unbounded until a route says otherwise, and it is worth saying: how long a WebSocket or an event stream may stay open. Keepalive closes a peer that stops answering, and the write timeout bounds one write, but a peer that answers every ping and says nothing, or a client that reads nothing while comments trickle in, costs a connection, a goroutine and a file descriptor until the server stops, and nothing but a ceiling on age can tell it from one that is listening. MaxLifetime puts that decision in your hands, and it is left unset because there is no age that is right for every stream.

The defaults as constants

Every one of them is exported, so a deployment can read them rather than guess.

muzak.DefaultMaxBodySize          // 1 << 20
muzak.DefaultMaxUploadSize        // 32 << 20
muzak.DefaultMaxHeaderBytes       // 64 << 10

muzak.DefaultReadHeaderTimeout    // 5s
muzak.DefaultReadTimeout          // 30s
muzak.DefaultWriteTimeout         // 30s
muzak.DefaultIdleTimeout          // 120s
muzak.DefaultShutdownTimeout      // 15s

muzak.DefaultWSReadLimit          // 1 << 20
muzak.DefaultWSReadTimeout        // 30s
muzak.DefaultWSWriteTimeout       // 10s
muzak.DefaultWSMaxConnections     // 1024
muzak.DefaultWSMaxConnectionsPerIP // 64
muzak.DefaultWSCloseGracePeriod   // 250ms
muzak.DefaultWSPingInterval       // 30s
muzak.DefaultWSPongTimeout        // 10s

muzak.DefaultSSEKeepAlive         // 15s
muzak.DefaultSSEWriteTimeout      // 10s
muzak.DefaultSSEMaxStreams        // 1024
muzak.DefaultSSEMaxStreamsPerIP   // 64
muzak.DefaultSSEHandshakeTimeout  // 30s, for SSEDial

muzak.DefaultConnectionIPv6Prefix // 56
muzak.DefaultConnectionIPv4Prefix // 32

muzak.DefaultRateLimitMaxEntries  // 100000
muzak.DefaultRateLimitSweepInterval // 1m
muzak.DefaultRateLimitStorageTimeout // 2s

muzak.MaxValidationDetails        // 100
muzak.MaxNestedDepth              // 32

muzak.DefaultCompressionMinSize   // 1400
muzak.DefaultForwardedHeader      // "X-Forwarded-For"

Things the type system does rather than a default

Some of what would be a runtime setting elsewhere is not a setting here at all.

A response cannot leak a field it does not declare. The handler's return type is the response model. There is no filtering pass to configure and no response_model to forget, because a field that is not on Out has no way to be written.

// Adding a column to this changes nothing a client can see.
type Item struct {
    ID           string
    Name         string
    InternalNote string
}

// Only these three members exist on the wire.
type ItemOut struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}

A crafted body cannot reach a located field. When an input mixes a path parameter with body members, the body is decoded into a struct of the body members alone, so a member naming a located field is an unknown member, refused with 422, rather than a value that reaches it or is silently dropped.

Two concurrent requests cannot see each other's dependencies. Resolved values live on the request's Context and are cleared when it returns to the pool. There is a test for exactly that, run under the race detector.

A misconfiguration is a build error, not a surprise. Duplicate routes, unbindable input types, path parameters no field binds or declared twice, a static route that could never match, duplicate operation identifiers, malformed prefixes, a wildcard CORS origin combined with credentials, a CORS or WebSocket origin that could never match or is "null", a WebSocket AllowedHosts entry no Host header can equal, a MaxConnections set on a route, a missing static directory, two mounts at one path, a location tag the binder cannot reach, a body type the JSON decoder refuses, a Nested that would validate nothing, a certificate without its key, a security scheme, category or title that cannot be described, alternatives that mix a verifying security scheme with a descriptive one, a Dep field no provider fills, sessions without cross-origin protection or with a secret under 32 bytes, an HTTPS redirect with no host it may name, an AllowedHosts entry that can never match, a Timeout on an event stream or WebSocket route, a health path a route already answers, and an OpenAPI document that cannot be encoded as JSON: all reported together when the application is built, before a socket is opened.

A deployment checklist

Things worth deciding explicitly, because the safe default may not be the correct one for your deployment:

• ClientIP.TrustedProxies if anything sits in front of the service, or every request is attributed to the proxy. See Behind a Proxy.
• CORS if a browser on another origin calls the API. See CORS.
• CrossOriginProtection if a browser sends the service cookies, which sessions require anyway. See Cross-Origin Requests and Sessions.
• AppOptions.AllowedHosts, so a request with a forged Host header, a WebSocket handshake included, is refused with 421, and RedirectHTTPS if plain HTTP reaches the service. See Allowed Hosts and HTTPS.
• WSOptions.AllowedOrigins if a browser opens WebSocket connections, and a host list if the server is on a loopback or private address: AppOptions.AllowedHosts for every request, or WSOptions.AllowedHosts for one route's handshakes alone.
• MaxLifetime, in minutes rather than hours, on every WebSocket and event stream route a client you do not control can open. Without it, 16 addresses can hold every slot of either.
• SSEOptions.MaxStreams against MaxStreamsPerIP, since the one divided by the other is how many addresses fill every stream slot, and ClientIPOptions.ConnectionIPv6Prefix: 48 so that an IPv6 client counts by its site's allocation, for streams and WebSocket connections alike. See Server-Sent Events.
• A rate limit policy, and a shared storage if the service runs more than once.
• Secure: true on every cookie once the service is served over TLS. See Cookies.
• DisableDocs if the deployment must not describe itself, or a guard declared where the routers are included, rather than on New, if only the API is private.
• ServerOptions.UnencryptedHTTP2 on a platform that speaks h2c to the container, and a TrustedProxies range for it. See Running on Cloud Run.
• Cache-Control in a handler that serves public data from behind a guard.
• Required() on every JSON body member a client must send, since the decoder accepts a body that leaves any member out and the generated document follows the rules you declare.
• A Servers list in the OpenAPI options, so a generated client points at the right host.

Where to go next

Authentication covers proving who a caller is, and Behind a Proxy covers the one default that is wrong in the other direction behind a load balancer.