` directive with a width or precision above 64, or a `*` width, is left as literal
text rather than rendered.
## Dates and numbers
`ctx.L` writes a value the way the locale writes it.
```go
ctx.L(time.Now()) // Mon, 24 Aug 2026 09:05:03 +0000
ctx.L(time.Now(), "as", "date", "format", "long")
ctx.L(1234.5, "precision", 2) // 1,234.50 in en, 1.234,50 in es
```
```yaml
es:
date:
formats:
long: "%d de %B de %Y"
month_names: [~, enero, febrero, marzo, abril, mayo, junio, julio, agosto,
septiembre, octubre, noviembre, diciembre]
number:
format:
separator: ","
delimiter: "."
```
Patterns are strftime rather than Go layouts, and that is not a matter of taste. Go formats
a time by example, and the reference layout hard-codes `January`, so a Go layout can only
ever produce an English month name. A strftime pattern names the field, which leaves Muzak
free to fill it from `date.month_names` in whatever locale was asked for. It is also what the
published locale corpora are written in.
Expansion is bounded, because a locale file is input the framework did not write and `%c` and
`%x` read their patterns from it. A width is at most 64, a pattern's nesting through `%c` and
`%x` at most four levels (a directive is written out as it stands past that, where a locale
whose default format was `%c` used to recurse until the process died), and one expansion reads
at most 16,384 characters and writes at most 16 KiB, cut at a character boundary.
A format name with no pattern under it is used as the pattern itself, so what a caller passes as
`format` is read as a strftime pattern. The bounds are what make that safe to reach with a value
the caller did not write, though a name from a client is still best checked against the formats
the application offers.
A pattern beginning `go:` is handed to Go's own formatter, for the formats meant to be read
by a machine.
```yaml
en:
date:
formats:
iso: "go:2006-01-02T15:04:05Z07:00"
```
The number helpers from the same scope are on the store: `NumberWithDelimiter`,
`NumberWithPrecision`, `NumberToCurrency`, `NumberToPercentage`, `NumberToHumanSize`,
`DistanceOfTimeInWords` and `ToSentence`.
## Caching
A response reports the locale it was written in, and says so in `Vary` when the header took
part in choosing it.
```
Content-Language: es
Vary: Accept-Language, Accept-Encoding
```
Without the `Vary`, a cache in front of the service will serve one language to a client that
asked for another. It is added by default and `DisableVary` turns it off, for a service whose
cache key is already settled by something else.
The `Vary` names what actually chose the language. With `LocaleFromHeader` it names the header,
and with `LocaleFromCookie` it names `Cookie`, where before only `Accept-Language` was added and
a shared cache could be made to serve an attacker-chosen language to everyone. A source listed
after the one that decided is not read and so not named, and the path and query need nothing
because they are already part of the address. A `LocaleFromCustom` extractor reads inputs the
framework cannot know, so one that reads a header or a cookie names it in `Vary` itself.
The field is recorded on the response and merged into `Vary` when the response is written, so a
handler that sets its own `Vary` adds to it rather than erasing it.
## Leaving it out
Leave `AppOptions.I18n` unset and none of this exists. No middleware is installed, no locale
is resolved, and every message reads exactly as it does without this feature.
It goes further than configuration. The framework reaches a translation engine only through
an interface, so a binary that never mentions `muzak.dev/framework/i18n` links neither the
engine, nor the YAML parser, nor the table of plural rules. A service that answers in one
language does not carry the machinery for ninety.
```go
type Translator interface {
Translate(locale, key string, args ...any) string
Localize(locale string, value any, args ...any) string
Exists(locale, key string) bool
AvailableLocales() []string
DefaultLocale() string
}
```
Anything satisfying it can be the store, which is how translations come from a database or a
service rather than from a file.
## Running this at scale
Nothing here holds per-process state that a request can change, which is what makes it safe
on a platform that runs many requests at once on an instance it may destroy a second later.
A locale is resolved from the request, put on the request's context, and copied onto the
pooled `Context` when that is taken from the pool. It is cleared when the `Context` goes
back. Nothing writes to the store after start-up: the translations, the plural rules and
the fallback chains are all settled while the application is being built, and only read
afterwards. The tests run 64 goroutines through five locales under the race detector, half
of them naming no locale at all, and require every answer to match its own request.
### Cold start
On this machine, building an application with five locale files costs about **83
microseconds** more than building the same application without translations, and about
**69 kilobytes**. The rest of a cold start is the framework and the runtime.
```
BenchmarkColdStartWithoutI18n 1.007 ms 6.90 MB
BenchmarkColdStart 1.090 ms 6.97 MB
BenchmarkStoreOnly 0.048 ms 0.07 MB
```
Locale files are parsed once, when the store is built, and the locale the framework ships
is parsed once per process and shared by every store after that. A warm request that
translates a message with nothing to interpolate allocates nothing at all.
### Embed the locale files
Use `FS` rather than `Dir` anywhere the filesystem is not yours. A container built from
scratch has no locale directory, and an instance that starts without one will serve every
request in the default language rather than failing, which is the kind of fault that is
noticed a week later by a customer.
```go
//go:embed locales
var locales embed.FS
```
### Time zones need a database
`Timezone()` resolves a name against the zone database, and a Go binary does not carry one
unless it is asked to. On a scratch or distroless image there is no `/usr/share/zoneinfo`
either, so the rule refuses every value including the correct ones, and nothing says why.
Either carry the database, at a cost of about 450 kilobytes:
```go
import _ "time/tzdata"
```
or run on an image that has one. Check at start-up either way, so that a missing database
stops the process rather than every request:
```go
if !validate.TimezoneDataAvailable() {
log.Fatal("no time zone database: import _ \"time/tzdata\" or use an image that has one")
}
```
### Caches in front of the service
A response says which language it is in and, when the header decided it, that the header
decided it.
```
Content-Language: es
Vary: Accept-Language, Accept-Encoding
```
Without the `Vary`, a shared cache will hand one language to a client that asked for
another. It is written by default; `DisableVary` turns it off for a service whose cache key
is already settled some other way.
## One thing deliberately left out
`errors.format`, and the full messages built from it, have no counterpart here.
The idea is to join an attribute name to a message to make one sentence, as "Email is
required". Muzak reports `field`, `location` and `issue` as separate members of the
envelope and never concatenates them, so there is nothing for a format to join. A client
that wants the sentence builds it from the three, in whatever order its own language puts
them, which is the part a fixed format gets wrong outside English.
Everything else is here: scopes, default chains including keys that name other keys, bulk
lookup, fallbacks, swappable and chained backends, and the exception handlers.
## Where to go next
- [Validation](/docs/fundamentals/validation) for the rules whose messages these are.
- [Error handling](/docs/getting-started/error-handling) for the envelope they arrive in.
- [Middleware](/docs/getting-started/middleware) for where the locale is resolved in the chain.
--------------------------------------------------------------------------------
title: "Headers"
description: "Bind request headers into typed fields, read them directly, and set response headers that a cache and a client can rely on."
version: "0.3.0"
last_updated: "2026-10-10T06:43:18.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/headers"
--------------------------------------------------------------------------------
# Headers
A header is bound like any other parameter. Tag a field with `header:"Name"` and it is read
from the request, converted to the field's type, and documented.
```go
type ClientHeaders struct {
// Host is the authority the client addressed, which is what absolute URLs
// in the response are built from.
Host string `header:"Host" doc:"The authority the request was addressed to"`
// SaveData is the client's data saver preference. It is the string "on"
// when set, not a boolean, so it is bound as one.
SaveData string `header:"Save-Data" default:"off" doc:"Set to on by a client asking for a smaller payload"`
// Traceparent carries the caller's trace context, echoed back so a client
// can correlate its span with this response.
Traceparent string `header:"traceparent" doc:"W3C trace context of the calling span"`
// Tags filter the feed. The header may be repeated or written as a
// comma-separated list, and every value is bound in the order it arrived.
Tags []string `header:"X-Tag" doc:"Restrict the feed to these tags; may be repeated"`
}
```
Names are matched case-insensitively, as HTTP requires, so `traceparent` and `Traceparent`
name the same header.
A header is optional unless the field says `required:"true"`, and a `default` supplies the
value when the client sends nothing.
```go
type PagingHeaders struct {
APIVersion string `header:"X-API-Version" required:"true" doc:"The API version this client was written against"`
PageSize int `header:"X-Page-Size" default:"50"`
}
```
## Repeated headers
Declare a slice, and every value arrives in the order it was sent. A header bound to a slice
is split on its commas as well as across its lines, because RFC 9110 says a list written as
several lines and one written as a comma-separated line mean the same thing. The spaces around
each element are dropped, an empty element is skipped, and a comma inside a quoted string, such
as an entity tag, stays part of its element.
```bash
curl 'http://localhost:8080/feed' -H 'X-Tag: go' -H 'X-Tag: http'
curl 'http://localhost:8080/feed' -H 'X-Tag: go, http'
```
```go
in.Tags // []string{"go", "http"}, either way
```
A `[]string` header whose values contain commas therefore gets several elements; declare a
`string` field to read the line whole. A non-slice header sent on more than one line is a
`422`, `must be given only once`, rather than one of its values being chosen, since a proxy in
front may have read a different one.
## Headers that are not plain text
A header whose format is not one Go already parses gets a type of its own. Implementing
`encoding.TextUnmarshaler` is all it takes.
```go [schemas/feed.go]
// HTTPDate is a time carried in the format HTTP dates use.
//
// It exists because If-Modified-Since is not RFC 3339, which is what a bare
// time.Time parses.
type HTTPDate struct {
time.Time
}
// UnmarshalText parses an HTTP date, as RFC 9110 defines it.
func (d *HTTPDate) UnmarshalText(text []byte) error {
parsed, err := http.ParseTime(string(text))
if err != nil {
return muzak.NewHTTPError(http.StatusUnprocessableEntity,
"must be an HTTP date, such as Wed, 21 Oct 2026 07:28:00 GMT")
}
d.Time = parsed
return nil
}
```
```go
type ClientHeaders struct {
IfModifiedSince HTTPDate `header:"If-Modified-Since" doc:"Answer 304 when nothing changed since this time"`
}
```
An `*HTTPError` returned from the method is the issue the client sees, so phrase its message to
read after the field name. Any other error reads `is not in the expected format`, because a
parser's own error is no fit for a client:
```json
{ "field": "If-Modified-Since", "location": "header",
"issue": "must be an HTTP date, such as Wed, 21 Oct 2026 07:28:00 GMT" }
```
## Validating a header
Rules bind to the field, not to the location, so a header is checked exactly as a query
parameter is and its failure is reported against the header name the client sent.
```go
func (in *FeedIn) Validate(v *muzak.Validation) {
v.String(&in.SaveData).Trim().Lower().OneOf("on", "off")
v.String(&in.Traceparent).Matches(`^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$`).
Message("must be a W3C trace context, such as 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01")
v.Slice(&in.Tags).MaxItems(5).Each(validate.String().MaxLen(24))
}
```
Transforms run before the checks, which is what lets `Save-Data` be compared against a
single spelling in the handler afterwards.
## Reading a header directly
```go
ctx.Header("X-Request-Id") // first value, or "" when absent
ctx.Request().Header.Values("X-Tag") // every value, through net/http
```
Prefer binding. A bound header is typed, documented, validated and reported the same way
every other parameter is; a header read by hand is none of those things.
## Setting response headers
```go
func Feed(ctx *muzak.Context, in schemas.FeedIn) (schemas.FeedOut, error) {
// The caller's trace context is echoed so its span and this response can be
// tied together, and the request identifier is what ties it to our log.
if in.Traceparent != "" {
ctx.SetHeader("traceparent", in.Traceparent)
}
// The response varies by all three, so caches must be told. This adds to
// whatever the framework recorded for the response, such as Origin.
ctx.SetHeader("Vary", "Save-Data, X-Tag, Cookie")
ctx.SetHeader("Last-Modified", feedUpdatedAt.UTC().Format(http.TimeFormat))
// ...
}
```
Echoing `traceparent` only hands the caller's value back. Tracing itself is
`AppOptions.Tracing`, which parses the header, continues the caller's trace and needs no field
for it; see [Observability](/docs/fundamentals/observability).
`SetHeader` replaces any value already present. `AddHeader` appends, which is what repeated
headers require:
```go
ctx.AddHeader("Vary", "Accept-Encoding")
ctx.AddHeader("Link", `; rel="next"`)
```
Headers must be set before the handler returns. Once the response has begun, `net/http`
ignores further changes, which is the same rule that governs
[middleware](/docs/getting-started/middleware).
## Conditional responses
```go
func Feed(ctx *muzak.Context, in schemas.FeedIn) (schemas.FeedOut, error) {
// A conditional request is answered without a body when nothing changed.
// The header was parsed into a time by the binder, so this is a comparison
// rather than a parse that could fail here.
if !in.IfModifiedSince.IsZero() && !feedUpdatedAt.After(in.IfModifiedSince.Time) {
ctx.SetStatus(http.StatusNotModified)
return schemas.FeedOut{}, nil
}
// ...
}
```
`304` writes no body at all, whatever the handler returned. Document the outcome so it
appears in the generated reference, with the model that says the response is empty:
```go
r.Get("/feed", handlers.Feed,
muzak.WithResponseModel[muzak.Empty](http.StatusNotModified, "The feed has not changed since If-Modified-Since"))
```
`WithResponseDoc` would have described that status as the error envelope, which is right
for an outcome a handler reports by returning an error and wrong for this one. See
[Response Models](/docs/techniques/response-models).
## Headers Muzak sets for you
| Header | Set by | Value |
|---|---|---|
| `X-Request-Id` | `RequestID` | The identifier assigned to the request |
| `X-Content-Type-Options` | `SecurityHeaders` | `nosniff` |
| `X-Frame-Options` | `SecurityHeaders` | `DENY` |
| `Referrer-Policy` | `SecurityHeaders` | `strict-origin-when-cross-origin` |
| `Strict-Transport-Security` | `SecurityHeaders` | `max-age=31536000`, on a response to a request that arrived over TLS, not for localhost or an address |
| `Content-Type`, `Content-Length` | the response encoder | For the body it wrote |
| `Allow` | the router | On an automatic `OPTIONS` and on a `405` |
| `Vary` | `Compress`, the CORS policy, `Locale`, versioning, sessions | `Accept-Encoding`; `Origin` (and the preflight request headers on `OPTIONS`) under a named-origin policy; the header or cookie that chose the language; the version header or `Accept`; `Cookie` when the handler read its session. A handler's own `Vary` adds to these |
| `Cache-Control` | the router, file mounts and sessions | `private, no-cache` behind a guard or a request-scoped provider, or when the handler read its session, unless the handler set one, and on a response carrying the session cookie in place of any value that would let a shared cache keep it. `no-store` on an error |
| `Retry-After`, `RateLimit-*` | the rate limiter | On a refusal, and on every counted request |
`SecurityHeaders` never overwrites a value already set, so a handler or a later middleware
can opt out per response.
```go
// This one page is allowed to be framed by the parent site.
ctx.SetHeader("X-Frame-Options", "SAMEORIGIN")
```
Turn the whole set off with `AppOptions.DisableSecurityHeaders` if something in front of
the service sets them instead.
## Forwarding headers
`X-Forwarded-For` and its relatives are not believed by default, because a header any
client can write is an identity any client can claim. Naming the proxy is what makes it
believable. See [Behind a Proxy](/docs/deployment/behind-a-proxy).
## Where to go next
[Cookies](/docs/techniques/cookies) covers the other half of what a browser
sends, and [Compression](/docs/techniques/compression) covers the `Vary` header
that goes with it.
--------------------------------------------------------------------------------
title: "Cookies"
description: "Bind cookies into typed fields, set them on a response, and choose the attributes that decide whether a session is safe."
version: "0.3.0"
last_updated: "2026-10-10T06:43:18.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/cookies"
--------------------------------------------------------------------------------
# Cookies
A cookie is bound like any other parameter.
```go [schemas/feed.go]
// SessionCookies groups the cookies the browser sends back.
type SessionCookies struct {
// SessionID identifies the signed-in reader and must be present.
SessionID string `cookie:"session_id" required:"true" doc:"The reader's session"`
// The trackers are declared so they are documented and so a reader can be
// told what is being read, not because the feed needs them.
FatebookTracker string `cookie:"fatebook_tracker" doc:"Third party analytics cookie, if the reader accepted one"`
GoogallTracker string `cookie:"googall_tracker" doc:"Third party analytics cookie, if the reader accepted one"`
}
```
Embed that group into any input that needs it:
```go
type FeedIn struct {
ClientHeaders
SessionCookies
Limit int `query:"limit" default:"20" doc:"How many entries to return"`
}
```
A cookie is optional unless the field says `required:"true"`. A missing required cookie is
a `422` naming it:
```json
{ "field": "session_id", "location": "cookie", "issue": "is required" }
```
Cookies are converted by the same setters every other parameter uses, so a cookie holding a
number or a UUID can be bound as one.
```go
type PreferenceCookies struct {
Theme string `cookie:"theme" default:"system"`
PageSize int `cookie:"page_size" default:"25"`
DeviceID uuid.UUID `cookie:"device_id"`
}
```
Validate them the way you validate anything else:
```go
func (in *FeedIn) Validate(v *muzak.Validation) {
v.String(&in.SessionID).Trim().MinLen(4).MaxLen(64)
v.String(&in.Theme).OneOf("system", "light", "dark")
}
```
## Reading one directly
```go
cookie, err := ctx.Cookie("theme")
if errors.Is(err, http.ErrNoCookie) {
// nothing was sent under that name
}
```
That is what a provider reading a cookie for several routes does, because it runs before
binding and serves every route that declares it:
```go [core/dependencies.go]
// Theme is the reader's display preference, read once for every route that
// needs it.
type Theme string
func GetTheme(ctx *muzak.Context) (Theme, error) {
if cookie, err := ctx.Cookie("theme"); err == nil && cookie.Value == "dark" {
return "dark", nil
}
return "light", nil
}
```
The session of `AppOptions.Sessions` is not read this way. Its cookie carries the session
encrypted, or an identifier into a store, and neither means anything to a handler: read the
session through `ctx.Session()`, as the `GetCaller` provider in
[Dependencies](/docs/getting-started/dependencies) does.
## Setting a cookie
Muzak writes the cookie of `AppOptions.Sessions` itself, as described below. Every other
cookie is set with `SetCookie`, here an identifier for a session an application keeps by hand:
```go
session := uuid.NewV4().String()
ctx.SetCookie(&http.Cookie{
Name: "session_id",
Value: session,
Path: "/",
// HttpOnly keeps the session out of reach of scripts, and SameSite keeps
// it off cross-site requests. Secure belongs here too once this is served
// over TLS, which is why it is named rather than omitted.
HttpOnly: true,
SameSite: http.SameSiteLaxMode,
Secure: false,
MaxAge: 3600,
})
```
`SetCookie` adds a `Set-Cookie` header for the cookie as given. Muzak does not modify it:
the attributes are the caller's to choose, and choosing them is the whole security
decision.
| Attribute | Why it matters |
|---|---|
| `HttpOnly` | Keeps the value out of reach of scripts, so a cross-site scripting bug cannot read the session |
| `Secure` | Refuses to send the cookie over plain HTTP. Set it wherever the service is served over TLS |
| `SameSite` | `Lax` stops the cookie riding along on cross-site requests, which is most of what CSRF needs |
| `Path` | Narrows where the cookie is sent. `/` is right for a session, narrower is better for anything else |
| `MaxAge` | Bounds how long the credential is useful. A session with no expiry is a credential with no expiry |
A session cookie is exactly the kind of ambient authority a cross-origin WebSocket
handshake can borrow, which is why the origin check in
[WebSockets](/docs/realtime/websockets) exists and why `AppOptions.CORS` cannot
substitute for it.
A session identifier set by hand, as above, is a credential you then store, look up and expire
yourself. `AppOptions.Sessions` does that for you: the session lives in a cookie it
encrypts, or in a store the cookie points into, named `__Host-session` and sent `HttpOnly`,
`Secure` and `SameSite=Lax` by default. See [Sessions](/docs/security/sessions). It requires
`AppOptions.CrossOriginProtection`, which refuses a state-changing request a browser sends from
another origin, including a form posted from a sibling subdomain, which `SameSite` lets through
because it is the same site. See
[Cross-Origin Requests](/docs/security/cross-origin-requests).
## Clearing a cookie
Send it back with an expiry in the past and the same `Path`, so the browser drops it.
```go
ctx.SetCookie(&http.Cookie{
Name: "session_id",
Value: "",
Path: "/",
HttpOnly: true,
SameSite: http.SameSiteLaxMode,
MaxAge: -1,
})
```
A session of `AppOptions.Sessions` is not cleared by hand. Signing out calls
`ctx.Session().Destroy()`, which removes the cookie the same way and, with a server-side store,
deletes the entry too, so a copy of the cookie taken earlier is worthless. See
[Sessions](/docs/security/sessions).
## Several cookies on one response
`SetCookie` appends rather than replacing, so more than one is fine.
```go
ctx.SetCookie(&http.Cookie{Name: "session_id", Value: session, Path: "/", HttpOnly: true})
ctx.SetCookie(&http.Cookie{Name: "theme", Value: in.Theme, Path: "/", MaxAge: 31536000})
```
## Cookies in logs
`cookie` and `set-cookie` are in `muzak.DefaultRedactedKeys`, so an attribute under either
key is replaced with `[redacted]` before a record is written. The access log records no
headers at all. See [Logging](/docs/fundamentals/logging).
## Cookies in tests
The test client keeps a cookie jar, so a sign-in followed by a call that needs the session
works the way it would in a browser.
```go
func TestLoginThenLogout(t *testing.T) {
client := testclient.New(t, buildApp())
form := url.Values{"username": {"muzak"}, "password": {"correct-horse-battery"}}
client.Post("/login/", testclient.Body(
"application/x-www-form-urlencoded", strings.NewReader(form.Encode()))).
AssertStatus(http.StatusOK)
// The jar carries the __Host-session cookie set above, so the sign-out
// ends that session, and its response removes the cookie.
res := client.Post("/logout/")
res.AssertStatus(http.StatusOK)
if len(res.Cookies) != 1 || res.Cookies[0].MaxAge >= 0 {
t.Errorf("want the session cookie removed, got %v", res.Cookies)
}
}
```
The application listens on a loopback address, which the jar treats as a secure origin as
browsers do, so the `Secure` session cookie is sent back over the test's plain HTTP.
`testclient.WithoutCookies()` disables the jar when each request should be independent, and
`testclient.Cookie(c)` sends one cookie on a single request.
## Where to go next
[Sessions](/docs/security/sessions) covers a session cookie Muzak encrypts and expires for
you, [Authentication](/docs/security/authentication) covers verifying who sent a
request, and [Forms and HTML](/docs/techniques/forms-and-html) covers the sign-in
form that sets one.
--------------------------------------------------------------------------------
title: "JSON"
description: "How request bodies are decoded and responses encoded, which struct tags matter, and why the defaults are strict rather than forgiving."
version: "0.3.0"
last_updated: "2026-10-10T06:42:33.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/json"
--------------------------------------------------------------------------------
# JSON
Muzak reads and writes JSON with `encoding/json/v2`. The defaults are strict, because a
request that is nearly right is a bug somewhere, and finding it in a `422` beats finding it
in a support ticket.
## Decoding a request
A field with no location tag is a member of the JSON body.
```go
type ItemCreateIn struct {
ID string `json:"id" doc:"The identifier to create the item under"`
Name string `json:"name" doc:"The item's display name"`
Async bool `json:"async,omitzero" doc:"Queue the work instead of doing it inline"`
}
```
What the decoder refuses:
| Refused | Why |
|---|---|
| An unknown member | A client's typo becomes an immediate `422` instead of a value that silently disappears |
| A duplicate member | Two values for one field means the client and the server disagree about which one won |
| Invalid UTF-8 | A string that is not text is not a string |
| A member of the wrong type | `"age": "42"` is not `"age": 42`. A value of the right kind that does not fit, `300` for an `int8` or `1.5` for an `int`, is described as a parameter of the same type would be |
| A member naming a located field | A path, query, header or cookie field is never a body member, so naming one is an unknown member, `422` |
| An empty body, when the route binds one | Reported as `{"field": "", "location": "body", "issue": "is required"}` |
| A media type that is not JSON | `415`, unless the type is `application/json` or ends in `+json` |
| A body with no `Content-Type` | `415`. Accepting an untyped body let any page drive a JSON route cross-site without a CORS preflight, by posting an untyped `Blob`. A request with no body and no `Content-Type` is unaffected |
```json
{
"error": {
"code": "validation_error",
"message": "The request could not be validated.",
"status": 422,
"details": [
{ "field": "nmae", "location": "body", "issue": "is not a field this endpoint accepts" },
{ "field": "age", "location": "body", "issue": "has the wrong type, a string is not accepted here" }
]
},
"request_id": "0611f4b2-2f0a-4b57-9c1a-6e6a2e2f9b31"
}
```
The issue follows the field's type, with the same wording and translation keys a parameter
uses: `300` for an `int8` reads `must be between -128 and 127`, and a time that does not parse
reads `is not in the expected format`. Only a value of a kind the field cannot hold at all, a
string for a number, reads `has the wrong type`. The `field` is the member's full path,
`addr.zip` for a member of an object and `items[1].zip` for one inside an array, as a
validation failure names it. Every one of these messages, `is not a field this endpoint
accepts` and `is not valid JSON` included, can be translated.
The Go type behind a failure is deliberately dropped from the message. Naming server-side
types in a response tells a client more about the implementation than it needs to know.
A body type `encoding/json/v2` cannot decode into, whatever a request sends, is a build error
naming the field or type at fault: an embedded struct tagged `json:",omitzero"`, a `format:`
option, two fields claiming one name, a channel, function, complex or non-empty interface
field, or the `string` option on a field that is not a number. Such a type used to build, and
every request that reached it got a `422` blaming the client, with nothing logged. A failure of
the same kind that can only show up while a request is decoded, such as an embedded pointer to
an unexported struct, is a `500` with the reason logged. Fix the tag or the type the error
names, or tag the field `json:"-"`.
A self-referential collection type, such as `type Tree map[string]Tree`, is accepted as a body
field and described once. Registering one used to hang or overflow the stack. As a query, header,
cookie or form parameter it is refused with an error naming the field.
### Accepting unknown members
```go
r.Post("/webhooks/stripe", handlers.StripeWebhook, muzak.AllowUnknownFields())
```
Reach for it where forward compatibility with a client that sends extra members matters
more than catching typos, which is what a third-party webhook receiver looks like. It is a
shared option, so a whole router can carry it. Duplicate members and invalid UTF-8 stay
rejected either way.
### A body next to a path parameter
```go
type ItemRenameIn struct {
ID string `path:"item_id" doc:"The item to rename"`
Name string `json:"name" doc:"The item's new display name"`
}
```
The body can only ever reach `Name`. When an input has any located field, the body is decoded
into a struct of the body members alone, built when the route is registered, and those are
copied into the input. A request carrying `{"ID": "somebody-elses-item"}` cannot overwrite the
path parameter, and the `ID` member is an unknown member like any other: a `422`, rather than a
value silently dropped, or ignored under `AllowUnknownFields`.
## Encoding a response
The handler's return value is the body, serialized as it stands.
```go
type ItemOut struct {
ID string `json:"id" doc:"The item's identifier"`
Name string `json:"name" doc:"The item's display name"`
Owner string `json:"owner,omitzero" doc:"The user the item belongs to"`
}
```
```json
{"id":"foo","name":"Foo"}
```
`Content-Type: application/json; charset=utf-8` and `Content-Length` are set for you. The
body is encoded fully into a pooled buffer before anything is written, so a failure part
way through encoding still produces a clean error response instead of a truncated body.
### The tags that matter
| Tag | Effect |
|---|---|
| `json:"name"` | The member name. Without a tag, the Go field name is used |
| `json:"name,omitzero"` | Omit the member when the value is the zero value of its type |
| `json:"-"` | Never encoded, and never a body member on the way in. On a field with a location tag it only keeps the field out of the body and the schema; its header or query value, default and required check still apply |
| `doc:"..."` | The member's description in the generated schema |
| `default:"..."` | The value used when a parameter, or a top-level member of the body, is absent, and its default in the generated schema, written as the JSON type of the member (`10`, not `"10"`) |
`omitzero` is what keeps a response clean without a pointer:
```go
Owner string `json:"owner,omitzero"`
```
```go [handlers/feed.go]
if trimmed {
// The client asked for less, so the summary is left out. The field is
// omitzero, so it disappears from the response entirely.
entry.Summary = ""
}
```
It does not decide what a request must contain. The decoder accepts a body that leaves any
member out, so the generated schema lists a **request** member as required only when a
`Required()` rule refuses a body without it (and it has no `default`). The response side keeps
the shape: a member that is not a pointer and not `omitzero` or `omitempty` is always written.
See [OpenAPI](/docs/fundamentals/openapi#request-bodies).
## Types on the wire
| Go type | JSON |
|---|---|
| `time.Time` | An RFC 3339 string, documented as `"format": "date-time"` |
| `uuid.UUID` | A string, documented as `"format": "uuid"` |
| `time.Duration` | a string such as `"1500ms"`, both ways, documented as a string with a `pattern` |
| a type implementing `encoding.TextMarshaler` and `encoding.TextUnmarshaler` | a string, both ways |
| a map | an object |
| a slice | an array |
| a pointer | the value, or `null` |
| an interface | whatever it holds, documented as accepting any JSON value |
A type that converts to and from text is a string everywhere: the binder parses it with
`UnmarshalText` in a parameter, the encoder writes it with `MarshalText` in a body, and the
schema calls it a string rather than describing the Go struct behind it.
```go
type Currency string
type PriceOut struct {
Amount int64 `json:"amount_minor"`
Currency Currency `json:"currency"`
}
```
## Response models are not storage models
::code-group
```go [core/store.go]
// Item is one stored item. It is the store's own type, deliberately separate
// from the response models in the schemas package: a field added here does not
// become visible to clients until a handler puts it on a response type.
type Item struct {
ID string
Name string
}
```
```go [handlers/items.go]
func ListItems(ctx *muzak.Context, _ muzak.Empty) (schemas.ItemListOut, error) {
store := muzak.From[*core.ItemStore](ctx)
settings := muzak.From[core.Settings](ctx)
stored := store.List()
items := make([]schemas.ItemOut, 0, len(stored))
for _, item := range stored {
items = append(items, schemas.ItemOut{ID: item.ID, Name: item.Name})
}
return schemas.ItemListOut{Items: items, Limit: settings.ItemsPerUser}, nil
}
```
::
Constructing the output is more typing than returning the stored record. In exchange, a
column added to that record tomorrow cannot appear in a response, because it is not part of
the response type, and the compiler is what tells you rather than a bug report.
## Nesting
Named structs become named components in the document and are referenced by name, so a type
used by several operations is described once.
```go
type FeedEntry struct {
ID string `json:"id"`
URL string `json:"url"`
Title string `json:"title"`
Tags []string `json:"tags"`
Summary string `json:"summary,omitzero"`
}
type FeedOut struct {
Reader string `json:"reader"`
Trimmed bool `json:"trimmed"`
Tracked bool `json:"tracked"`
Entries []FeedEntry `json:"entries"`
UpdatedAt time.Time `json:"updated_at"`
}
```
Embedding promotes members the way JSON encoding does, so a shared group of fields is
declared once and appears inline on every model that embeds it.
## When the body is not JSON
- Return `muzak.HTML` for a page. See
[Forms and HTML](/docs/techniques/forms-and-html).
- Return `muzak.Empty` with `muzak.Status(http.StatusNoContent)` for no body at all.
- Return `muzak.Bytes`, `muzak.Stream` or `muzak.FileResponse` for a file, an image or a
download, and `muzak.Redirect` to send the client elsewhere. See
[Files, Streams and Redirects](/docs/techniques/files-streams-redirects).
- Take `ctx.ResponseWriter()` for anything else Muzak should not encode. See
[Responses](/docs/getting-started/responses).
- Reach for [Server-Sent Events](/docs/realtime/server-sent-events) for a body
that never ends.
## Deterministic output for the document
`Document.Marshal` renders the OpenAPI document with map keys in sorted order, so the
output is byte-for-byte reproducible. That is what lets a generated document be committed
and diffed. Ordinary responses are not sorted; a Go struct already has a field order, and
that order is what goes out.
## Where to go next
[Validation](/docs/fundamentals/validation) covers checking a decoded body, and
[Compression](/docs/techniques/compression) covers making a large one smaller.
--------------------------------------------------------------------------------
title: "Forms and HTML"
description: "Bind a form body into a typed input, and return an HTML document from the same application that serves the API."
version: "0.3.0"
last_updated: "2026-10-10T06:43:18.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/forms-and-html"
--------------------------------------------------------------------------------
# Forms and HTML
A field tagged `form:"name"` is bound from a form body, converted by the same setters that
convert a query parameter. A route that binds form values and no files at all is not a
special kind of route: it validates, documents and fails exactly like any other.
## Binding a form
```go [schemas/login.go]
// LoginIn is the sign-in form.
//
// The two fields carry no location tag beyond `form`, so this route reads a
// form body rather than JSON and accepts both encodings a browser can produce:
// application/x-www-form-urlencoded, which a plain HTML form posts, and
// multipart/form-data, which one with an enctype does.
type LoginIn struct {
Username string `form:"username" doc:"The account to sign in to"`
Password string `form:"password" doc:"The account's password"`
// Next is where to send the browser afterwards. A form value is required
// like the body is, so an optional one says so.
Next string `form:"next" required:"false" doc:"Where to redirect after signing in"`
}
```
A form value is body content, so it is **required by default**, unlike a query parameter.
Mark an optional one `required:"false"` or give it a `default`.
```go
type SearchForm struct {
Query string `form:"q"`
Page int `form:"page" default:"1"`
Safe bool `form:"safe" default:"true"`
}
```
## What a form route accepts
| The input binds | Accepted media types |
|---|---|
| `form` fields only | `application/x-www-form-urlencoded` and `multipart/form-data` |
| any `file` field | `multipart/form-data` only, because urlencoded cannot carry a file |
That is why a plain HTML form with no `enctype` posts to a form route without being told
to.
An input that binds `form` or `file` fields cannot also declare JSON members. A field with
no location tag on such an input is a build error telling you to tag it with `form` or move
it to the path, query, header or cookie.
## Validating a form
```go [schemas/login.go]
// Validate bounds the credentials before any comparison is attempted.
//
// The rules are deliberately shape-only. A password that is too short is worth
// rejecting outright, but nothing here may hint at whether the account exists;
// that answer belongs to the handler, which gives the same one either way.
func (in *LoginIn) Validate(v *muzak.Validation) {
v.String(&in.Username).Trim().Lower().MinLen(2).MaxLen(32)
v.String(&in.Password).MinLen(8).MaxLen(128)
}
```
Failures are reported with `"location": "body"`, because a form value is body content.
## The handler
::code-group
```go [handlers/login.go]
// Login establishes a session from a submitted form.
//
// By the time this runs the form has been read, the username trimmed and
// lower-cased and both lengths checked, so the handler is left with the one
// decision that is actually its own.
func Login(ctx *muzak.Context, in schemas.LoginIn) (schemas.LoginOut, error) {
expected, known := accounts[in.Username]
// The comparison runs even for an unknown account, and the same answer is
// given either way. Returning "no such user" would turn this endpoint into
// a way to enumerate accounts, and returning early would let its timing do
// the same thing more quietly.
matches := subtle.ConstantTimeCompare([]byte(expected), []byte(in.Password)) == 1
if !known || !matches {
return schemas.LoginOut{}, muzak.Unauthorized("the username or password is incorrect")
}
session := ctx.Session()
// Regenerating comes first, before anything that says who the user is, so
// a session someone else planted in the browser is worthless at the moment
// it would have become valuable.
if err := session.Regenerate(); err != nil {
return schemas.LoginOut{}, err
}
if err := session.Set("user", in.Username); err != nil {
return schemas.LoginOut{}, err
}
return schemas.LoginOut{
Username: in.Username,
Next: in.Next,
}, nil
}
// Logout ends the session: the cookie is removed from the browser.
func Logout(ctx *muzak.Context, _ muzak.Empty) (muzak.Empty, error) {
ctx.Session().Destroy()
return muzak.Empty{}, nil
}
```
```go [schemas/login.go]
// LoginOut reports who signed in. The session travels in its cookie,
// encrypted and out of reach of scripts, and is deliberately not repeated
// in the body, where any script on the page could read it.
type LoginOut struct {
Username string `json:"username"`
Next string `json:"next,omitzero"`
}
```
```go [routers/login.go]
func Auth() *muzak.Router {
r := muzak.NewRouter(muzak.WithTags("auth"))
r.Get("/login", handlers.LoginForm,
muzak.Summary("Serve the sign-in form"))
r.Post("/login/", handlers.Login,
muzak.Summary("Exchange a username and password for a session"),
muzak.WithResponseDoc(http.StatusUnauthorized, "The username or password is incorrect"),
// Stricter than the rest of the application, because guessing a
// password is the one request worth making a hundred times a minute.
muzak.RateLimit(muzak.Quota{Name: "login", Window: time.Minute, Limit: 5}))
r.Post("/logout/", handlers.Logout,
muzak.Summary("End the session"))
return r
}
```
```go [cmd/main.go]
app := muzak.New(muzak.AppOptions{
// Sessions, kept in a cookie encrypted under the configured secrets.
Sessions: &muzak.SessionOptions{Secrets: settings.SessionSecrets},
// A session cookie rides along on requests other sites make, so a
// state-changing request from another origin is refused. Sessions
// cannot be configured without it.
CrossOriginProtection: &muzak.CrossOriginOptions{},
})
```
::
The rate limit on a sign-in route is not optional in practice. See
[Rate Limiting](/docs/techniques/rate-limiting) for why the count belongs before
the guards.
The cookie the session travels in is named `__Host-session` and is sent `HttpOnly`, `Secure`
and `SameSite=Lax` without being asked; see [Sessions](/docs/security/sessions). A form is the
request another site can make a browser send, which is why sessions require
`AppOptions.CrossOriginProtection`: a form posted from another origin is refused with `403`
before the handler runs. See [Cross-Origin Requests](/docs/security/cross-origin-requests).
## Returning HTML
A handler returning `muzak.HTML` bypasses JSON encoding entirely: the string is written
verbatim under `text/html`, and the generated document describes the response as
`text/html` rather than as a JSON schema.
```go [handlers/login.go]
// LoginForm serves the page that posts to Login.
//
// It is a plain form with no enctype, so the browser posts it as
// application/x-www-form-urlencoded. The route accepts that without being told
// to, because it binds form values and no files.
func LoginForm(ctx *muzak.Context, _ muzak.Empty) (muzak.HTML, error) {
return muzak.HTML(`
`), nil
}
```
Everything else about the route is unchanged: status, headers, cookies and errors work
exactly as they do for a JSON route.
### Escaping
The value is written as given. Muzak does not escape it, because it cannot tell markup the
handler meant from text it did not. Anything a client supplied has to be escaped by the
handler.
```go
func Greeting(ctx *muzak.Context, in GreetIn) (muzak.HTML, error) {
return muzak.HTML("Hello, " + html.EscapeString(in.Name) + "
"), nil
}
```
For anything larger than a fragment, use `html/template`, which escapes by construction:
```go
var page = template.Must(template.ParseFiles("templates/profile.html"))
func Profile(ctx *muzak.Context, in ProfileIn) (muzak.HTML, error) {
var buf strings.Builder
if err := page.Execute(&buf, in); err != nil {
return "", err
}
return muzak.HTML(buf.String()), nil
}
```
Parse the templates once and publish the set with `muzak.WithSingleton` or
`muzak.Singleton` rather than parsing per request. See
[Dependencies](/docs/getting-started/dependencies).
## Redirecting after a post
```go
func Login(ctx *muzak.Context, in schemas.LoginIn) (muzak.Empty, error) {
// ... establish the session ...
ctx.SetHeader("Location", in.Next)
ctx.SetStatus(http.StatusSeeOther)
return muzak.Empty{}, nil
}
```
`Next` came from the client, so treat it as input: validate it against a set of known
destinations, or require it to be a relative path, before putting it in a `Location`
header. A handler that returns `muzak.Redirect{To: in.Next}` has the second check made for it:
a target that is not a path on this origin is refused with a `500` and never sent, and a
redirect answering a `POST` is a `303` by default. See
[Files, Streams and Redirects](/docs/techniques/files-streams-redirects).
## Body limits
What bounds a form body depends on what the route binds:
| The input binds | Bounded by | Default |
|---|---|---|
| a `file` field | `MaxUploadSize` | 32 MiB |
| `form` fields only, urlencoded | `MaxBodySize` | 1 MiB |
| `form` fields only, multipart | `MaxBodySize` | 1 MiB |
A login or sign-up form that binds only `form:` values used to take its `multipart/form-data`
body under the 32 MiB upload limit, so `net/http` held up to 20 MiB of text values (about 49 MiB
of heap per request in flight) before any rule could run, and a file sent to it, which nothing
reads, was spooled to disk first. A form-only route that legitimately receives more than
`MaxBodySize` as multipart must raise `MaxBodySize` for it:
```go
r.Post("/import", handlers.Import, muzak.MaxBodySize(8<<20))
```
A body that declares a `Content-Length` over the limit is refused before any of it is read. A
route that declares a `file:` field keeps `MaxUploadSize`, declared once on the router that
holds those routes:
```go
r := muzak.NewRouter(
muzak.WithTags("uploads"),
muzak.MaxUploadSize(32<<20),
muzak.MaxFileSize(10<<20),
)
```
A malformed form body is answered with a `422` and is not written to the error log: the parse
error quoted the bad part header whole, so a 1 MiB request wrote a 5 MB log line.
## Testing a form route
```go
func TestLogin(t *testing.T) {
client := testclient.New(t, buildApp())
form := url.Values{"username": {"muzak"}, "password": {"correct-horse-battery"}}
res := client.Post("/login/", testclient.Body(
"application/x-www-form-urlencoded", strings.NewReader(form.Encode())))
res.AssertStatus(http.StatusOK)
isSession := func(c *http.Cookie) bool { return c.Name == "__Host-session" }
if !slices.ContainsFunc(res.Cookies, isSession) {
t.Error("want the session cookie")
}
}
```
## Where to go next
[File Uploads](/docs/techniques/file-uploads) covers the other half of a
multipart body, and [Sessions](/docs/security/sessions) covers the session a
sign-in establishes.
--------------------------------------------------------------------------------
title: "File Uploads"
description: "Bind an uploaded file into a typed field, choose between bytes in memory and a handle to the content, and bound what a client can send."
version: "0.3.0"
last_updated: "2026-10-10T06:42:33.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/file-uploads"
--------------------------------------------------------------------------------
# File Uploads
A field tagged `file:"name"` is bound from the part the client sent under that name, and
its Go type decides what the handler is handed.
| Field type | What the handler gets |
|---|---|
| `[]byte` | The content read straight into memory |
| `muzak.File` | The metadata, with the content left where the parser put it |
| `[]muzak.File` | Every file sent under the name |
| `[][]byte` | The content of every file sent under the name |
```go [schemas/uploads.go]
// FileBytesIn binds one upload straight into memory, which suits a file small
// enough that holding all of it at once is not a decision worth thinking
// about.
type FileBytesIn struct {
File []byte `file:"file" doc:"A file read as bytes"`
}
// UploadFileIn binds one upload alongside a form value, which is what an HTML
// form with a file input and a text input sends.
type UploadFileIn struct {
File muzak.File `file:"file" doc:"A file read as an upload"`
Note string `form:"note" doc:"An optional note filed with the upload" required:"false"`
}
// MultiUploadIn binds every file sent under one name.
type MultiUploadIn struct {
Files []muzak.File `file:"files" doc:"One or more files"`
}
```
A file is body content, so it is **required by default**. Mark an optional one
`required:"false"`.
## Handlers
```go [handlers/uploads.go]
// FileSize reports the size of a file read into memory. Binding it as []byte is
// what makes that the whole handler.
func FileSize(ctx *muzak.Context, in schemas.FileBytesIn) (schemas.FileOut, error) {
return schemas.FileOut{FileSize: len(in.File)}, nil
}
// UploadFile reports what a client sent with one file. Nothing is read here:
// muzak.File carries the metadata and leaves the content where the parser put
// it, so a handler that only needs the name never touches the bytes.
func UploadFile(ctx *muzak.Context, in schemas.UploadFileIn) (schemas.UploadFileOut, error) {
return schemas.UploadFileOut{
Filename: in.File.Filename,
ContentType: in.File.ContentType,
Size: in.File.Size,
Note: in.Note,
}, nil
}
// UploadFiles reports every file sent under one name.
func UploadFiles(ctx *muzak.Context, in schemas.MultiUploadIn) (schemas.MultiUploadOut, error) {
out := schemas.MultiUploadOut{Filenames: make([]string, len(in.Files))}
for i, file := range in.Files {
out.Filenames[i] = file.Filename
out.TotalSize += file.Size
}
return out, nil
}
```
## Working with `muzak.File`
```go
type File struct {
// Filename is the name the client reported for the file. It is arbitrary
// client-supplied text and must never be used as a path, a database key or
// anything else with meaning on the server without being checked first.
Filename string
// ContentType is the media type declared for the part, which is likewise
// what the client claimed rather than what the bytes contain.
ContentType string
// Size is the number of bytes the file holds.
Size int64
}
```
| Method | What it does |
|---|---|
| `Open()` | A reader over the content, positioned at the start. The caller owns and must close it. Opening more than once is allowed, and each reader has its own position |
| `Bytes()` | The whole file in memory, as a fresh slice that stays valid after the request ends |
| `Save(path)` | Copies the file to a path, creating or truncating it, and reports the bytes written |
| `Header()` | The MIME headers of the part, for the occasional client that sends more than a filename and a content type |
| `Present()` | Whether a file was uploaded at all. Only ever false for a field marked `required:"false"` |
`Open` and `Bytes` report `muzak.ErrNoFile` when nothing was uploaded.
```go
func StoreAvatar(ctx *muzak.Context, in AvatarIn) (AvatarOut, error) {
user := muzak.From[core.CurrentUser](ctx)
source, err := in.Avatar.Open()
if err != nil {
return AvatarOut{}, err
}
defer source.Close()
// The destination is built from a directory the server controls and a name
// the server generates. in.Avatar.Filename is never part of a path.
name := uuid.NewV4().String() + extensionFor(in.Avatar.ContentType)
destination := filepath.Join(storageDir, user.Username, name)
written, err := in.Avatar.Save(destination)
if err != nil {
return AvatarOut{}, err
}
return AvatarOut{Name: name, Size: written}, nil
}
```
## Lifetime
A part larger than 10 mebibytes spills to a temporary file while the body is parsed, and
every temporary file is removed once the handler returns. `Open` and `Bytes` are therefore
only valid while the handler runs: anything that must outlive the request has to be copied
out of it first, with `Save` or otherwise.
The removal happens at the end of **every** request, whoever parsed the form. A guard or a
handler that read the form through `ctx.Request()` parsed it on a copy of the request that
`net/http`'s own cleanup never saw, and every such upload stayed on disk.
That threshold is deliberately well below the default upload limit, so a handful of
concurrent large uploads cannot be turned into memory pressure.
## Nothing the client sends is trusted
`Filename` and `ContentType` are text the client chose. A client may send
`../../etc/passwd`, a name that means something to the local filesystem, or a
`Content-Type` that has nothing to do with the bytes behind it.
- Build a destination from a directory the server controls and a name the server generates.
- Sniff the content if the type matters, rather than believing the declaration.
- Echo the filename back if you like, but never route on it.
- Serve a stored upload back with `muzak.FileResponse`, which takes its type from the
extension and never from the content. See
[Files, Streams and Redirects](/docs/techniques/files-streams-redirects) for what a browser
does with a file whose type a client chose.
## Limits
Two limits bound what a route accepts, and both are declared rather than remembered.
```go [routers/uploads.go]
// Uploads returns the router for the endpoints that accept files.
//
// The two limits are declared once for the whole router, so a route added here
// later cannot forget them: MaxUploadSize bounds what the server will read at
// all, and MaxFileSize bounds any single file inside it.
func Uploads() *muzak.Router {
r := muzak.NewRouter(
muzak.WithTags("uploads"),
muzak.MaxUploadSize(32<<20),
muzak.MaxFileSize(10<<20),
)
r.Get("/upload", handlers.UploadForm,
muzak.Summary("Serve a form that posts files"))
r.Post("/files/", handlers.FileSize,
muzak.Summary("Report the size of a file read as bytes"))
r.Post("/uploadfile/", handlers.UploadFile,
muzak.Summary("Report what was sent with one file"))
r.Post("/uploadfiles/", handlers.UploadFiles,
muzak.Summary("Report what was sent with several files"))
return r
}
```
| Limit | Applies to | Default | Behaviour when exceeded |
|---|---|---|---|
| `MaxUploadSize` | The whole form body of a route that declares a `file` field | `DefaultMaxUploadSize`, 32 MiB | `413`: from the declared `Content-Length` before any of it is read, or while the body is being read, so the server never buffers more than the limit |
| `MaxFileSize` | Any single file in it | unset, so each file is bounded only by the upload limit | `413` before the handler runs |
Both are settable application-wide through `AppOptions.MaxUploadSize` and
`AppOptions.MaxFileSize`, and both are shared options, so a router or a single route can
narrow them. A route that declares a `file` field uses `MaxUploadSize` in place of
`MaxBodySize`, because an upload is expected to be larger than a JSON document and the two
limits should not have to be traded off against each other.
A route that binds only `form` values, and no file, is bounded by `MaxBodySize` for its
urlencoded **and** its multipart body: it has nothing to spool to disk, and a file sent to it,
which nothing reads, is not worth 32 MiB. See
[Forms and HTML](/docs/techniques/forms-and-html#body-limits).
The refusal names the field rather than the client's filename, which is text the client
chose and would otherwise be echoed straight back:
```json
{
"error": {
"code": "payload_too_large",
"message": "a file uploaded as \"file\" exceeds the 10485760 byte limit for a single file on this route",
"status": 413
},
"request_id": "0611f4b2-2f0a-4b57-9c1a-6e6a2e2f9b31"
}
```
## A form that posts them
```go [handlers/uploads.go]
// UploadForm serves the page that posts to UploadFiles. Returning muzak.HTML
// is what bypasses JSON encoding; the document is written as it stands.
func UploadForm(ctx *muzak.Context, _ muzak.Empty) (muzak.HTML, error) {
return muzak.HTML(`
`), nil
}
```
A route that binds any file accepts `multipart/form-data` only, which is why the form
above carries an `enctype`. A route binding form values and no files also accepts
`application/x-www-form-urlencoded`. See
[Forms and HTML](/docs/techniques/forms-and-html).
## Validating an upload
Form values alongside a file validate like anything else, and a rule on the file itself is
a `Value` rule.
```go
func (in *UploadFileIn) Validate(v *muzak.Validation) {
v.String(&in.Note).Trim().MaxLen(280)
v.Value(&in.File).Must(func(f muzak.File) error {
switch f.ContentType {
case "image/png", "image/jpeg", "image/webp":
return nil
default:
return errors.New("must be a PNG, JPEG or WebP image")
}
})
}
```
A declared content type is a hint, not proof. Where it matters, read the first bytes and
check them.
## Testing an upload
```go
func TestUploadFile(t *testing.T) {
client := testclient.New(t, buildApp())
var body bytes.Buffer
form := multipart.NewWriter(&body)
part, err := form.CreateFormFile("file", "notes.txt")
if err != nil {
t.Fatalf("CreateFormFile = %v", err)
}
if _, err := part.Write([]byte("hello")); err != nil {
t.Fatalf("Write = %v", err)
}
if err := form.Close(); err != nil {
t.Fatalf("Close = %v", err)
}
res := client.Post("/uploadfile/", testclient.Body(form.FormDataContentType(), &body))
res.AssertStatus(http.StatusOK)
res.AssertJSON(`{"filename":"notes.txt","content_type":"application/octet-stream","size":5,"note":""}`)
}
```
## Where to go next
[Forms and HTML](/docs/techniques/forms-and-html) covers the rest of a multipart
body, and [Static Files and Frontends](/docs/techniques/static-files) covers
serving files back out.
--------------------------------------------------------------------------------
title: "Static Files and Frontends"
description: "Serve a built frontend and a directory of assets from the same binary as the API, with routes always matched first."
version: "0.3.0"
last_updated: "2026-10-10T11:11:46.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/static-files"
--------------------------------------------------------------------------------
# Static Files and Frontends
Two mounts, one machinery. `Router.Frontend` serves the output of a frontend build and
resolves a path with no file behind it; `Router.Static` serves a directory and lets a miss
stay a miss.
```go [cmd/main.go]
// Assets that belong to no particular route. A static mount serves what it
// finds and nothing else, so a miss here stays a miss rather than being
// answered with the application document by the frontend below.
app.Static("/static", muzak.StaticOptions{Dir: "static"})
// The built frontend is served last: every route above is matched first, so
// mounting at the root cannot shadow the API.
app.Frontend("/", muzak.FrontendOptions{Dir: "dist"})
```
Nothing is rendered on the server and nothing is built here. Both serve files that already
exist, which is what `npm run build` and its equivalents produce.
## Routes win
A request is matched against every registered route first and reaches a mount only when
none of them answered, so mounting a frontend at `/` cannot shadow an API. Middleware still
applies, and so does what the router the mount was registered on would run before a route's
handler: its **rate limit**, then the **security requirements** it declared with `WithSecurity`
when they name a verifying scheme (one built by `JWTBearer` or `APIKeyVerifier`), then its
**guards**, then every `Needs` and `Singleton` provider it declares. An error from any of them is
rendered exactly as it would be for a route, which is what lets a frontend sit behind the same
authentication and the same budget as everything else. A router declared `Public()` exempts its
mounts from a verifying scheme named above it, while the guards they inherit still run; see
[Authentication](/docs/security/authentication).
```go
ui := muzak.NewRouter(muzak.WithDependencies(core.RequireSession))
ui.Frontend("/", muzak.FrontendOptions{Dir: "dist"})
app.Include(ui)
```
A mount used to run only the guards it inherited, so a router authenticated with `Needs(...)`
served its files to anyone, and no quota counted a file request. To keep assets public, put them
on a router without those options. To keep a mount outside a quota, use `SkipRateLimit()`.
A mount that inherits any guard or provider sends `Cache-Control: private, no-cache` on every
response, replacing one the file would have carried, so a cache shared between clients keeps
none of them.
Mounting under a prefix works the way everything else does, through the router the mount is
registered on:
```go
ui := muzak.NewRouter()
ui.Frontend("/", muzak.FrontendOptions{Dir: "dist"})
app.Include(ui, muzak.WithPrefix("/app"))
```
## Serving a frontend
```go
app.Frontend("/", muzak.FrontendOptions{Dir: "dist"})
```
A request for a path with no file behind it falls back to one, resolved from what the build
actually produced:
1. A `404.html` in the frontend's root is served with `404`.
2. Failing that, an `index.html` is served with `200`, but only for a `GET` or `HEAD` that
asks for HTML, which is what a browser navigation does.
That second rule is what a client-side router needs in order to take over. The restriction
to navigations is what keeps a missing script or stylesheet answering `404`, because
handing those an HTML document only turns a missing file into a confusing parse error
somewhere further from the cause.
A directory is served by its `index.html` with or without a trailing slash, but a file only
without one. `/app.js/` names a directory that is not there, so it is a path with no file behind
it like any other, rather than a second URL for the file against which every relative reference
in it resolves somewhere else.
| Option | Effect |
|---|---|
| `Dir` | The directory holding the build, or the subdirectory within `FS` when both are set |
| `FS` | Serve from an `io/fs.FS` rather than from disk |
| `Fallback` | Name the file served with `200` for a navigation, instead of resolving it |
| `NotFound` | Name the file served with `404`. It takes precedence over `Fallback` and applies to any `GET` or `HEAD` |
| `NoFallback` | Serve a plain `404` for anything with no file behind it |
| `SkipCheck` | Do not verify the directory when the application is built, for one something else fills in later |
| `AllowDotfiles` | Serve files and directories whose name begins with a dot |
Since the answer depends on `Accept` when there is a fallback and no `NotFound` page, every
response of such a mount carries `Vary: Accept`, so a cache does not hand one to the other.
## Shipping the frontend inside the binary
```go [cmd/main.go]
//go:embed all:dist
var assets embed.FS
func main() {
app := muzak.New(muzak.AppOptions{Title: "Awesome API"})
app.Include(routers.Items())
app.Frontend("/", muzak.FrontendOptions{FS: assets, Dir: "dist"})
log.Fatal(app.RunSignals())
}
```
Setting both reads `Dir` as a subdirectory of `FS`, which is what the directory embed above
produces. The deployment is then one file.
Use `all:dist` rather than `dist`, or the embed skips files whose names begin with `.` or
`_`, which is exactly what several build tools emit.
## Serving assets
```go
app.Static("/static", muzak.StaticOptions{Dir: "static"})
```
`Static` is the same machinery without the part that makes a frontend work: nothing stands
in for a path with no file behind it, so a miss is a `404` and stays one.
| Option | Effect |
|---|---|
| `Dir` | The directory holding the files, or the subdirectory within `FS` |
| `FS` | Serve from an `io/fs.FS`, which is what an `embed.FS` of assets looks like |
| `Index` | Serve a directory with the `index.html` inside it, as a web server does for a site of pages |
| `SkipCheck` | Do not verify the directory when the application is built |
| `AllowDotfiles` | Serve files and directories whose name begins with a dot |
| `AllowActiveContent` | Serve HTML, SVG and other XML as ordinary documents rather than sandboxed |
`Index` is off by default, because a mount of scripts and stylesheets has no index and
asking for a directory is a mistake worth reporting.
Reach for `Static` to publish assets, and for `Frontend` to serve an application whose
routing happens in the browser.
Two neighbours cover what neither does. A single file a handler chooses, such as an export a
user asked for, is a route that returns `muzak.FileResponse`, served with ranges and
conditional requests and typed by its extension as a mount's files are; see
[Files, Streams and Redirects](/docs/techniques/files-streams-redirects). A handler written for
`net/http` rather than a directory, such as pprof or a metrics endpoint, is served with
`Router.Mount`, behind the same rate limit, guards and providers as a route; see
[Mounting net/http Handlers](/docs/techniques/mounting-handlers).
## What both refuse
| A request that... | ...gets |
|---|---|
| asks for a directory | never a listing. A `Static` mount answers its `index.html` only when `Index` asked for it |
| names a file followed by a slash (`/app.js/`) | a miss, as any path with no file behind it: `404`, or from a `Frontend` the 404 page or the `index.html` fallback for a navigation |
| names a file or directory beginning with a dot, anywhere in the path | `404`, with no fallback offered in its place |
| follows a symbolic link out of the mounted directory | refused |
| reaches the directory of a mount beneath this one, by any name | `404` |
| uses a method other than `GET` or `HEAD` on a file that exists | `405`, rather than the file |
| arrives before a `SkipCheck` directory exists | `500`, with the reason logged |
| names a file that vanishes, or cannot be read, after it was found | `404` or `500`, rendered by the error renderer like any other failure, problem details included, and the request counts as failed |
A directory that does not exist is reported when the application is built rather than on
the first request, unless `SkipCheck` asked otherwise. Two mounts at one path are a build
error: a second `Static` or `Frontend` at a path used to lose to the first without a word,
guards included.
### Dotfiles
A path with any segment starting with `.` (`/.env`, `/.git/config`) answers `404`, as though
the file were not there, and the fallback page is not offered in its place. A build output or a
deployment directory is where a `.env`, a `.git` directory, an `.htpasswd` or an editor's swap
file ends up by accident, and serving one publishes credentials and source history to anyone who
guesses the name, which every scanner does. A leading `/.well-known/` is the one exception,
because that is where a site publishes files meant to be found. Set `AllowDotfiles` for a
directory whose dotfiles are all meant to be public.
On Windows a path segment shaped like an 8.3 short name, such as `/ENV~1`, is refused whatever
the options say, because the filesystem opens the long name it stands for without any check
having seen that name.
### What a file is served as
A file's type comes from its extension and **never from its content**, so a file with no
extension, or an unknown one, is `application/octet-stream`. Sniffing let an upload stored
without an extension be served as `text/html`, and an `.svg` served inline ran a client's markup
as script on the API's own origin.
A `Static` mount serves HTML, SVG, XHTML and other XML under `Content-Security-Policy: sandbox`,
so a browser that opens one directly shows it in an isolated origin with scripts, forms and
plugins turned off. An image referenced from a page is not affected. Set `AllowActiveContent`
for a static site whose scripts must run, such as a site of pages served with `Index`. A
`Frontend` mount does not sandbox, because its documents are the application itself, and a
single page application belongs there.
A file larger than 8 MiB from a filesystem whose files cannot seek is streamed, with its size as
`Content-Length` when known and `Last-Modified`, and without range support. Smaller ones are
buffered, so range and conditional requests keep working for them.
### Symbolic links, and mounts inside mounts
The promise that a symbolic link cannot lead out of the directory is kept by `Dir` and by the
`FS` of an `os.Root`, and **not** by `os.DirFS`, which follows a link wherever it points, so a
link planted in a directory served through it serves the file it names. To serve a directory on
disk, set `Dir`, or pass `os.OpenRoot(...).FS()`.
A link that stays inside the directory is followed and its target served by the mount that owns
the directory. A deployment step that links files into a served directory (`cp -l`, `rsync -H`,
a build cache) therefore publishes them under the new name, dotfiles included, unless the link
leads into the directory of a mount beneath.
When mounts nest, the most specific one answers, and **a directory that has a mount of its own is
reachable only through that mount**, under any name. Suppose a guarded mount at `/admin` serves
`site/admin` beside a public mount at `/` over `site`. A request that reaches the inner
directory through the outer mount gets `404`, whether the path differs in case (`/ADMIN/x`, on
a case-insensitive filesystem), uses `\` as a separator, goes through a symbolic link, or
reaches the directory by a mount path that differs from the directory's name (a guarded mount
at `/x` over `site/staff`, beside a public mount at `/` over `site`, no longer serves the same
files at `/staff/...`). The fallback page is not offered in its place.
The outer mount compares each directory a path passes through with the directory of every mount
beneath it **by file identity**, so the answer is exact on every platform and for every folding
rule (a ligature, a sharp s spelled out, a composed or decomposed accent), with no table to keep,
and hard links and bind mounts are covered because only the directory's identity matters. Where
both directories are given as `Dir` the relationship is worked out when the application is
built. A mount served from an `os.DirFS` is compared against every mount beneath it, since its
path cannot be read back, and one served from an `embed.FS` has no second name to defend
against.
A request the inner mount already answers is unaffected, and so is every mount with no mount
beneath it. To publish the same files at two paths, mount them at both.
## A single binary, front to back
```
awesome-api/
|-- cmd/
| `-- main.go
|-- dist/ what the frontend build wrote
| |-- index.html
| |-- 404.html
| `-- assets/
|-- static/ assets that belong to no route
| `-- logo.svg
|-- routers/
|-- handlers/
|-- schemas/
`-- core/
```
```go [cmd/main.go]
app.Include(routers.Users())
app.Include(routers.Items())
app.Static("/static", muzak.StaticOptions{Dir: "static"})
app.Frontend("/", muzak.FrontendOptions{Dir: "dist"})
```
`GET /users/` reaches the API. `GET /static/logo.svg` reaches the asset. `GET /dashboard`
reaches no route and no file, so `index.html` is served with `200` and the browser's router
takes it from there. `GET /assets/app-4f2a.js` with nothing behind it answers `404`, so a
stale hashed asset fails loudly instead of returning HTML.
## Where to go next
[Compression](/docs/techniques/compression) covers making those assets smaller,
and [Server Configuration](/docs/deployment/server-configuration) covers
deploying the binary that holds them.
--------------------------------------------------------------------------------
title: "Compression"
description: "Negotiate gzip or deflate in one line, leave alone what compressing would not help, and know the one case where compression and secrecy interact badly."
version: "0.3.0"
last_updated: "2026-10-10T06:42:33.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/compression"
--------------------------------------------------------------------------------
# Compression
```go
app.Use(muzak.Compress(muzak.CompressionOptions{}))
```
That is the whole installation. The middleware negotiates an encoding from
`Accept-Encoding`, compresses the bodies worth compressing, and records `Vary` on every
response either way.
Install it with `App.Use`, which puts it inside the built-in chain, so it already has a
request identifier and is already covered by panic recovery.
## What is negotiated
gzip is preferred over deflate, and an explicit refusal such as `gzip;q=0` is honoured. A
client that asks for neither gets an uncompressed body.
`deflate` is answered in the **zlib** format, which is what RFC 9110 defines the coding to be:
zlib around DEFLATE. The bare DEFLATE stream sent before was refused by strict decoders. A
client that decodes it as raw DEFLATE, which was only ever a lenient guess, should decode zlib;
every conforming client already does.
A quality is read only between 0 and 1. `q=NaN`, `q=Inf` and `q=1e9` used to parse as valid,
so an infinity outranked every honest range and NaN made the ordering meaningless. Now NaN is
unreadable (one, as before), anything above one is one, and a negative value is a refusal.
`Vary: Accept-Encoding` is set on every response whether or not it was compressed, so a
cache cannot hand a compressed body to a client that cannot read it.
## What is left alone
| A response that... | ...is not compressed |
|---|---|
| is smaller than `MinSize` | a body that already fits in one packet cannot arrive sooner by shrinking |
| carries a media type that is not text-like | an image, a video or an archive is already compressed |
| the handler encoded itself | a `Content-Encoding` is already set |
| carries no body | there is nothing to compress |
| is a range | a compressed range is not the range that was asked for |
| is an event stream | holding events in a compressor's window until something forces them out is the one thing a stream cannot survive |
`muzak.DefaultCompressionMinSize` is 1400 bytes, a little under one ethernet MTU. A
response that already fits in a single packet cannot be made to arrive sooner by shrinking
it, and compressing it spends CPU on both ends to save nothing.
## Entity tags and ranges
A compressed response is a different representation from the one the handler described, and
its validators are adjusted to say so.
A strong `ETag` is weakened, `"v1"` to `W/"v1"`, on a compressed `200` and on a `304` answering a
client that negotiated an encoding. A cache can then use the `304` to refresh the response it
stored under the weak tag, which a strong tag in the `304` would not let it do. The weak tag still
corresponds to a stored response that was not compressed, because tags correspond by weak
comparison.
The tag need not be one the handler set. `muzak.AutoETag()` gives a route a strong tag computed
from its body and answers a client that already holds the body with `304`. The two compose:
`Compress` weakens the tag of a body it compresses, and `AutoETag` compares `If-None-Match`
weakly, so the weakened tag a client stored still earns the `304`. See
[Files, Streams and Redirects](/docs/techniques/files-streams-redirects).
`If-Match` is compared strongly, so a weak tag in it never matches, and a client that read a
compressed response would have every conditional write refused with `412`. The `W/` is
therefore taken off the tags of an incoming `If-Match` before the handler sees it. A handler
that compares as RFC 9110 asks gets the right answer. One that issues weak tags of its own and
compares `If-Match` by string equality, which RFC 9110 does not allow, now sees their strong
form, and should compare the opaque tag instead.
A compressed response does not advertise `Accept-Ranges`, since no range of the bytes it
carries can be asked for. A `Range` request is answered from the uncompressed content,
uncompressed. When an encoding was negotiated, a `Range` whose `If-Range` carries a date or a
weak tag is answered with the whole content instead. A date cannot say whether the client holds
the compressed bytes or the uncompressed ones, and a client appending a range of one to the
other ends up with neither; a weak tag never matches `If-Range` at all. A `Range` with no
`If-Range`, or with a strong tag, is still answered with an uncompressed range. A client that
resumes a download through `Compress` sends a strong `ETag` in `If-Range`, or asks for no
encoding along with its `Range`, as Go's client and most download tools already do.
## Options
```go
app.Use(muzak.Compress(muzak.CompressionOptions{
Level: muzak.CompressionBest,
MinSize: 2048,
ContentTypes: []string{"text/", "application/json", "+json", "image/svg+xml"},
}))
```
| Field | Default | Effect |
|---|---|---|
| `Level` | `CompressionDefault` | How hard the compressor works |
| `MinSize` | `DefaultCompressionMinSize` | The smallest body worth compressing. A response whose length is not known in advance is buffered up to this size before the decision is made |
| `ContentTypes` | a built-in list of text-like types | Which media types are compressed |
| Level | For |
|---|---|
| `CompressionDefault` | Balances speed against size, which is the right choice until a measurement says otherwise |
| `CompressionFastest` | A service that is CPU bound, or serving large bodies to a fast network |
| `CompressionBest` | A service whose clients are on slow or metered connections |
There are three levels rather than an integer because the underlying range has invalid
values in it and there is nothing useful to do with a level of 42 at run time.
An entry in `ContentTypes` is matched as a prefix, so `text/` covers every text type, and
an entry beginning with `+` matches a structured syntax suffix, so `+json` covers
`application/problem+json`.
## What it is worth
On the framework's own example application, compression takes 91% off the OpenAPI document
and 68% off the documentation page. A JSON listing of any size behaves much the same. A
small response, an image and an event stream are all untouched, which is the point of the
exclusions above.
## Compression and secrecy
Compression and secrecy interact badly, and it is worth knowing where.
When a response mixes a secret with something the client controls, its compressed length
leaks how much the two have in common. That is what the BREACH attack recovers a token
from, over many requests. Muzak's own responses do not mix the two, but a handler that
reflects a query parameter back alongside a CSRF token does.
Where that is possible, either leave compression off for the route or stop reflecting the
input.
## Ordering with your own middleware
Middleware installed first is outermost, so a middleware that reports a duration sees the
time spent compressing only if it is installed before the compressor.
```go [cmd/main.go]
// ProcessTime is outermost of the two, so the duration it reports includes the
// time spent compressing.
app.Use(core.ProcessTime())
app.Use(muzak.Compress(muzak.CompressionOptions{}))
```
Anything that wraps the response writer needs to implement `Unwrap() http.ResponseWriter`,
or it will break flushing and hijacking for everything inside it. See
[Middleware](/docs/getting-started/middleware). `Compress` implements `Hijack` itself, so a
handler beneath it that takes the connection over through `http.ResponseController` gets the
connection with nothing written onto it afterwards: no held header, no flushed bytes, and no
compressor closed onto a socket that has stopped speaking HTTP.
The compressor reports a failed flush: it carries `FlushError`, so `http.ResponseController`
can tell a stream that its client has gone, where a bare `Flush()` returned nothing whatever
became of the bytes underneath. A panic below `Compress` is answered with a `500` and not an
empty `200`; its deferred finish used to send the pending header while the panic unwound, so
recovery could no longer write its error.
## Checking it
```bash
curl -s -H 'Accept-Encoding: gzip' -o /dev/null -D - http://localhost:8080/openapi.json
```
```
HTTP/1.1 200 OK
Content-Type: application/json
Content-Encoding: gzip
Vary: Accept-Encoding
```
```go
func TestOpenAPIIsCompressed(t *testing.T) {
client := testclient.New(t, buildApp())
res := client.Get("/openapi.json", testclient.Header("Accept-Encoding", "gzip"))
res.AssertStatus(http.StatusOK)
res.AssertHeader("Vary", "Accept-Encoding")
}
```
## Where to go next
[Static Files and Frontends](/docs/techniques/static-files) covers the assets
this makes smaller, and
[Server-Sent Events](/docs/realtime/server-sent-events) covers the one response
kind compression skips on purpose.
--------------------------------------------------------------------------------
title: "Rate Limiting"
description: "A policy of several quotas counted together, a storage you choose, a tracker that decides whose budget is spent, and defaults that fail closed."
version: "0.3.0"
last_updated: "2026-10-10T06:43:18.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/rate-limiting"
--------------------------------------------------------------------------------
# Rate Limiting
Rate limiting is built in and off until a policy names a quota. 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, and a storage that stops answering
stops traffic rather than stopping the limit.
## A policy is several quotas
```go
type Quota struct {
Name string // the namespace its counters live under, reported to clients
Window time.Duration // how long one counting period lasts
Limit int // how many requests are allowed within one window
}
```
One number cannot tell a burst from sustained abuse. Three requests a second is generous
for a person clicking and impossible for a script; a hundred a minute is the reverse. A
policy that means "quick but not tireless" needs both.
::code-group
```go [core/ratelimit.go]
// RateLimitPolicy is the application-wide budget every route inherits.
//
// Three windows rather than one, because a single number cannot tell a person
// clicking from a script that never stops. The quotas are counted longest
// window first, so a client that overruns the short window has already accrued
// against the long one.
func RateLimitPolicy() muzak.RateLimitOptions {
return muzak.RateLimitOptions{
Tracker: UserOrIPTracker,
Quotas: []muzak.Quota{
{Name: "short", Window: time.Second, Limit: 3},
{Name: "medium", Window: 10 * time.Second, Limit: 20},
{Name: "long", Window: time.Minute, Limit: 100},
},
}
}
```
```go [cmd/main.go]
app := muzak.New(muzak.AppOptions{Title: settings.AppName, Addr: settings.Addr},
muzak.WithDependencies(core.GetQueryToken),
// The application-wide budget, counted before the guard above runs so that
// a request the guard rejects still costs the client something.
muzak.WithRateLimit(core.RateLimitPolicy()),
)
```
::
The quotas are counted longest window first, whatever order they are declared in, and the first
to refuse a request ends the count. A request refused by the short quota has already been
counted against the long one, so pausing between bursts launders nothing. A request the long
quota refuses is not counted against the shorter ones, whose budget it would only waste, and
`Retry-After` is the wait of the quota that refused. `RateLimit-Policy` still lists the quotas
as they were declared.
A window is **fixed**, not sliding. A client's counter starts with its first request and ends
`Window` later, and the next request opens a new one, so a client can spend a whole `Limit` at the
end of one window and another at the start of the next: up to twice `Limit` in a span of
`Window`. The short quota in the policy above is what bounds that.
A quota's `Name` is the namespace its counters are stored under, so two quotas that share a
name share a budget and must agree on their window and limit. The application refuses to
build when they do not. It must be a valid HTTP token, because it is reported to clients.
## What is counted
A route counts against the policy it inherits. So does everything else that answers a request on
the application's behalf:
- A `Frontend` or `Static` mount applies the rate limit of the router it was registered on,
ahead of its guards, so a file request costs budget like any other. Use `SkipRateLimit()` to
keep a mount outside a quota.
- A handler served with `Router.Mount` is counted the same way, against the policy of its
routers and of the options given to `Mount`. See
[Mounting net/http Handlers](/docs/techniques/mounting-handlers).
- A tool call made through an `App.MCP` endpoint is served in-process by the route it calls, so
it is counted against that route's policy, under the calling client's address, as a request
to the route would be. The message that carries it is counted against the endpoint's policy as
well. See [MCP Tools](/docs/techniques/mcp-tools).
- The documentation page and `/openapi.json` are counted in the same budget as the routes. Once
the docs ran the application's guards but not its limit, `/openapi.json` was a place to guess
the application's token as fast as a client could send. Exempt it by passing
`muzak.SkipRateLimit()` to `muzak.New`, or serve no documentation.
- `OPTIONS` and `405` answers are **not** counted. They are answered from the route table alone,
as `net/http.ServeMux` does, so they skip a route's guards and limit. Middleware installed with
`App.Use` still covers them: put a limit there when the existence of a path is itself a secret.
- The health endpoints of `AppOptions.Health` are **not** counted either. A probe is answered
ahead of routing and of `App.Use` middleware, and runs no guard, provider or rate limit, since
a probe that a quota refused would take the instance out of rotation. See
[Health Checks](/docs/deployment/health-checks).
## Narrowing it
```go
// A health check: exempt. A monitor polling every second is the one client that
// should never be told to slow down.
r.Get("/healthz", handlers.Health, muzak.SkipRateLimit())
// A login route: stricter. Guessing a password is the one request worth making
// a hundred times a minute.
r.Post("/login/", handlers.Login,
muzak.RateLimit(muzak.Quota{Name: "login", Window: time.Minute, Limit: 5}))
```
`RateLimit` replaces the quotas and keeps the storage and tracker it inherits, which is the
common case. `WithRateLimit` layers the whole options struct field by field on top of what
an enclosing scope declared, so a route can change one thing without restating the rest.
The quotas given **replace** those inherited rather than adding to them, so a route that
wants both restates the ones it is keeping.
An exemption cannot be undone by a narrower scope: once a router is exempt, every route
beneath it is.
## When the count happens
By default, **before** the route's guards and dependencies. That is the half that matters
for brute force: a request a guard rejects is still counted, so failed sign-ins cost the
attacker their budget rather than being free. It also means a client past its limit is
refused before anything expensive runs on its behalf.
`AfterDependencies` moves the count after them, which is what a tracker keying on a
resolved identity needs, and gives the other half up.
```go [routers/items.go]
r := muzak.NewRouter(muzak.WithTags("items"),
// This is the one router whose routes resolve a caller, so it is the one
// router where the budget is worth spending per caller rather than per
// address. Deferring the count is what lets the tracker see the resolved
// user; the quotas themselves are inherited unchanged.
muzak.WithRateLimit(muzak.RateLimitOptions{AfterDependencies: true}))
```
Leave it off on a login route. A request rejected by a guard never reaches a limiter that
defers, so a route that defers does not limit failed authentication at all, which is
exactly the traffic a login route needs to limit.
## Limits that vary per caller
A `Quota` is fixed when the application is built, and the same name may not carry two
policies anywhere in it. That is right for a policy the application owns, and it cannot
express one its customers do: a plan, a negotiated ceiling, a tier read from a database.
`Resolver` supplies quotas per request.
```go [core/ratelimit.go]
// The plan was resolved by a dependency, so the count has to happen after
// them. It is read from whatever the dependency already fetched rather than
// from the database, because this runs on every request.
func PlanQuotas(ctx *muzak.Context) ([]muzak.Quota, error) {
plan, ok := muzak.TryFrom[Plan](ctx)
if !ok {
// Nothing resolved, nothing enforced. An unauthenticated request
// reaching this route is limited by the static quotas, if any.
return nil, nil
}
return plan.Quotas, nil
}
```
```go [cmd/main.go]
muzak.WithRateLimit(muzak.RateLimitOptions{
AfterDependencies: true,
Tracker: core.UserOrIPTracker,
Resolver: core.PlanQuotas,
// A floor everyone shares, whatever their plan says.
Quotas: []muzak.Quota{{Name: "burst", Window: time.Second, Limit: 20}},
})
```
Resolved quotas are counted **alongside** the static ones, under their own names, in the
same storage. A route can therefore carry both a floor everyone shares and a ceiling that
varies, and `RateLimit-Policy` describes the union.
Setting a resolver turns limiting on for the route even with no static quota, because
what is enforced becomes a run time question. Returning nothing enforces nothing.
A quota built at run time is not validated when the application is built, so one that breaks
the rules a static quota follows fails the request with a `500` rather than being counted. Both
paths share one check: a name that is not a valid token (a colon in `plan:x` for client `y`
collides with `plan` for client `x:y` in the storage key recommended below, and a NUL does the
same in the in-process storage), a zero window or limit, and a name repeated within one policy or
repeating a static one. A repeated name used to count every request once per copy
against one counter, so a limit of two refused the second request.
Nothing compares a resolver's names against the ones declared statically beyond that, so a name
used in both places must mean the same thing in both.
## Whose budget is spent
`RateLimitTracker` is `func(ctx *muzak.Context) (string, error)`. It defaults to
`muzak.IPTracker`, which keys on the address `Context.ClientIP` resolves.
```go [core/ratelimit.go]
// UserOrIPTracker spends a request from the caller's budget when there is a
// caller, and from the address's otherwise.
//
// The identity is read with TryFrom rather than From, because most routes here
// resolve no user at all and an absent dependency is a legitimate state for
// this tracker rather than a programming error. Keys from the two sources are
// prefixed differently so that a username can never collide with an address.
func UserOrIPTracker(ctx *muzak.Context) (string, error) {
if user, ok := muzak.TryFrom[CurrentUser](ctx); ok {
return "user:" + user.Username, nil
}
return muzak.IPTracker(ctx)
}
```
A tracker that requires a credential can insist on one. Returning an error abandons the
request, and the error becomes the response exactly as one returned from a handler would:
```go
func APIKeyTracker(ctx *muzak.Context) (string, error) {
key := ctx.Header("X-API-Key")
if key == "" {
return "", muzak.Unauthorized("an API key is required")
}
return "apikey:" + key, nil
}
```
Two rules: the key must not be empty, and keys from different sources must be prefixed
differently, so that a user identifier and an address can never collide into one budget.
### Addresses that are cheap to change
`IPTracker` counts an IPv4 address exactly, under a key such as `ip:192.0.2.7`. An IPv6 address
is counted by its **/56**, under a key such as `ip:2001:db8:1::/56`, because a client is
delegated a whole range of IPv6 addresses and would otherwise get a fresh budget from every
address in it. A /56 is what providers delegate to one home or small site (RFC 6177). Keying on
the /64 still handed one subscriber 256 budgets: rotating the low bits of the fourth group of an
address, all inside their own /56, turned a limit of 5 a minute into more than a thousand.
The prefix is the one the per-client connection caps count, and one setting chooses both:
`ClientIPOptions.ConnectionIPv6Prefix`, defaulting to 56, with `ConnectionIPv4Prefix` at 32. Any
length from 32 to 128 is accepted.
```go
muzak.AppOptions{
ClientIP: muzak.ClientIPOptions{ConnectionIPv6Prefix: 48},
}
```
- Where sites are delegated a /48, or the deployment is hostile to begin with, set 48.
- Where many unrelated users share one /56 (a campus, or a carrier that gives each device a
/64), set 64 to keep the old grouping. That also loosens the connection caps to match.
- For one route only, `IPPrefixTracker` chooses its own lengths: 0 to 32 for IPv4 and 0 to 128
for IPv6.
```go
muzak.RateLimitOptions{Tracker: muzak.IPPrefixTracker(32, 64)}
```
That keeps IPv4 addresses exact while collapsing an IPv6 source down to the allocation it
actually came from. It panics if either length is out of range for its family, which is a
mistake worth catching where the tracker is built rather than on the first request.
`IPPrefixTracker(32, 128)` counts every IPv6 address on its own, which is only safe where
something in front has already bounded them.
A counter kept in a shared storage under an IPv6 client's old `ip:2001:db8:1:2::/64` key is not
carried over, so IPv6 clients start with a full budget once after the upgrade. IPv4 keys are
spelled as before.
The address itself is only as trustworthy as the deployment makes it. A zone on an address
(`fe80::1%eth0`) is dropped before a key is made, so one client cannot mint a key per zone
suffix. See [Behind a Proxy](/docs/deployment/behind-a-proxy).
## Where the counters live
```go
type RateLimitStorage interface {
Increment(ctx context.Context, quota, key string, window time.Duration) (count int, reset time.Duration, err error)
}
```
That is the whole of what the limiter needs from the outside world.
### The default, in memory
An application that names no storage gets one that counts in the process that serves the
requests. It is the right answer for a single process and the wrong answer for several:
counters held in one process are not shared with the next, so a limit of a hundred a minute
becomes a hundred a minute per process.
The table is bounded in two directions, because it is keyed by something the client
influences and an unbounded one would be a memory leak with a name. Expired counters are
swept, a full table evicts the counter closest to expiring from the **quota the new counter
belongs to**, and a tracker key the client chose the length of is hashed rather than truncated,
so two clients cannot be merged into one budget. Only a quota holding no counter at all takes
its first from the quota holding the most.
Eviction used to be global, so flooding one quota with new keys, which is easy from one IPv6
range with a tracker that counts every address, evicted and so reset a per-account login limit.
0.2.8 took the counter from the quota holding the most, which held only while the flooded quota
was the largest: a client could mint keys under a smaller quota keyed on something it chooses,
such as an API key counted before any guard, and each key evicted the client's own spent counter
in a larger per-address quota. Now a flood can only evict its own quota's counters. A full table
therefore keeps each quota at the size it had when it filled, and a quota whose traffic grows
afterwards gains room only as counters expire, so size `MaxEntries` for the keys the
application really sees. A count saturates at the top of an `int` instead of
wrapping under every limit, and a window near 292 years no longer makes `RateLimit-Reset`
negative: seconds clamp to what a 32-bit int holds.
```go
muzak.WithRateLimit(muzak.RateLimitOptions{
Storage: muzak.NewMemoryRateLimitStorage(muzak.MemoryRateLimitOptions{
MaxEntries: 10_000,
SweepInterval: 30 * time.Second,
}),
Quotas: []muzak.Quota{{Name: "default", Window: time.Minute, Limit: 60}},
})
```
`DefaultRateLimitMaxEntries` is 100000 and `DefaultRateLimitSweepInterval` is one minute.
Naming a storage explicitly is only necessary to change those bounds.
It implements `muzak.Lifecycle`, so it is started and stopped with the application, and
stopping releases every counter it holds: a key is derived from whatever the tracker read,
an address, a user identifier or an API key, and none of that should outlive the server
that was counting it.
`Len()` reports how many counters it holds, which is what a metric or a test asking whether
anything is accumulating wants.
### A shared storage
Anything running more than once wants counters the processes share. The interface is three
arguments wide so that whatever you already run can satisfy it.
```go [core/redisratelimit.go]
// Increment counts one request against a quota for one client.
//
// The increment and the expiry happen in one round trip, so that two requests
// arriving together cannot both create the window.
func (s *RedisRateLimitStorage) Increment(
ctx context.Context, quota, key string, window time.Duration,
) (int, time.Duration, error) {
// The script runs INCR, then PEXPIRE when the counter is new, then PTTL.
res, err := s.script.Run(ctx, s.client,
[]string{"ratelimit:" + quota + ":" + key},
window.Milliseconds()).Result()
if err != nil {
return 0, 0, err
}
values := res.([]any)
count := int(values[0].(int64))
reset := time.Duration(values[1].(int64)) * time.Millisecond
return count, reset, nil
}
```
```go
muzak.WithRateLimit(muzak.RateLimitOptions{
Storage: core.NewRedisRateLimitStorage(settings.RedisAddr),
Quotas: core.RateLimitPolicy().Quotas,
})
```
Two rules an implementation must follow:
- The count includes the request being counted, so the first request in a window returns
one.
- The window is how long a **newly created** counter should live. Never extend the life of
a counter that already exists, because a limit whose window restarts on every request is
a limit that never resets.
The key is opaque and may contain any bytes. It is derived from client-supplied data and
must never be logged, because it routinely carries an API key or a user identifier.
If the implementation also satisfies `muzak.Lifecycle`, the application starts it before
serving and stops it after draining, so a pool or a sweeper needs no separate registration.
`Increment` **must return when its context ends**. The limiter cancels the context after
`RateLimitOptions.StorageTimeout`, which is `muzak.DefaultRateLimitStorageTimeout` (2 seconds)
unless it says otherwise. Every client library's context-taking call does return, so passing
`ctx` through is all it takes.
## When the storage cannot answer
By default the request is refused with `503` and `Retry-After: 5`, because a limiter that
cannot count is a limiter that is not enforcing anything, and an attacker who can reach the
storage can choose the moment it stops answering. The `Retry-After` is set even with
`DisableHeaders`, so a refused client does not retry at once against a store trying to
recover.
```go
muzak.RateLimitOptions{FailOpen: true}
```
That trades the guarantee for availability: a storage outage lets traffic through unmetered
instead of turning into an outage of its own. The failure is logged either way, without the
key.
A store that stops **answering** is a different failure from one that returns an error. A call
that hangs never produces an error for `FailOpen` to act on, and used to hold every request that
reached it until its client gave up. `StorageTimeout` bounds each call: one that outlives it has
its context cancelled and counts as a storage failure, which is a `503` with `Retry-After: 5`, or
an unmetered request with `FailOpen`. A negative value removes the bound. The process-local
storage is called without a deadline.
```go
muzak.RateLimitOptions{StorageTimeout: 500 * time.Millisecond}
```
With `FailOpen`, only the failing quota goes unmetered. The others in the policy still decide, so
a request over the limit of a quota that answered is refused, and a store that fails for some
counters only, one shard of a cluster for instance, does not stop every other limit of the route
from holding. When no quota was counted at all, no `RateLimit` headers are sent.
## What a client sees
Every counted request carries headers describing the budget, because a client that can see
its own budget is a client that can stay inside it.
| Header | Reports |
|---|---|
| `RateLimit-Limit` | The quota closest to being spent |
| `RateLimit-Remaining` | How many requests are left in that quota's current window |
| `RateLimit-Reset` | How many seconds until that window starts again |
| `RateLimit-Policy` | Every quota the route enforces, as `limit;w=seconds` entries |
| `Retry-After` | On a `429`, the wait of the quota that refused; on a storage `503`, five seconds |
`RateLimit-Policy` is fixed for a route, so one response teaches a client the whole policy.
```
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 3
RateLimit-Remaining: 0
RateLimit-Reset: 1
RateLimit-Policy: 3;w=1, 20;w=10, 100;w=60
Retry-After: 1
```
```json
{
"error": {
"code": "too_many_requests",
"message": "the \"short\" rate limit of 3 requests per 1 seconds has been exceeded; retry in 1 seconds",
"status": 429
},
"request_id": "0611f4b2-2f0a-4b57-9c1a-6e6a2e2f9b31"
}
```
`Retry-After` is set even when `DisableHeaders` turns the `RateLimit` headers off. Refusing
a client without telling it when to come back is what produces a client that comes back
immediately, forever.
## Limiting a connected peer
`ReadLimit` bounds what one WebSocket message costs and `MaxConnections` bounds how many
peers there are, but neither bounds a peer that stays inside both and simply never pauses.
`WSOptions.MessageLimits` applies the same quotas, storage and tracker to messages, counted in
the same order as a request's: longest window first, stopping at the first quota that refuses.
```go
r.WS("/items/{item_id}/ws", handlers.ItemSocket,
muzak.WithWebSocket(muzak.WSOptions{
MessageLimits: []muzak.Quota{
{Name: "ws-messages", Window: time.Second, Limit: 10},
},
}))
```
A peer that goes over is closed with `1008 Policy Violation` rather than left connected and
ignored, because a message silently dropped is a protocol nobody can debug. The budget
belongs to the client rather than the connection, so opening a second one does not buy a
second budget. Pings, pongs and empty fragments are not messages, but a connection that sends
more than 65536 of them in a minute is closed with `1008` whatever else it does, so a peer
cannot dodge the message count by never completing a message.
Give those quotas names of their own unless a shared budget with the HTTP routes is what
you want, since both live in one namespace. A route marked `SkipRateLimit` counts no
messages either.
## Options reference
| Field | Default | Effect |
|---|---|---|
| `Quotas` | none, so nothing is limited | The limits enforced, all of them, for every request, counted longest window first until one refuses |
| `Storage` | a bounded in-process table | Where the counters live |
| `Tracker` | `IPTracker` | Whose budget a request is spent from |
| `Resolver` | none | Supplies quotas per request, counted alongside `Quotas` |
| `FailOpen` | off | Serve a request the storage could not count |
| `DisableHeaders` | off | Stop setting the `RateLimit` headers |
| `AfterDependencies` | off | Count after the guards and providers rather than before |
| `StorageTimeout` | `DefaultRateLimitStorageTimeout`, 2 seconds | Bounds one storage call. A call that outlives it counts as a storage failure. Negative removes the bound |
## Where to go next
[Behind a Proxy](/docs/deployment/behind-a-proxy) covers which address a request
is attributed to, and [WebSockets](/docs/realtime/websockets) covers the other
bounds a connected peer runs into.
--------------------------------------------------------------------------------
title: "Response Models"
description: "The handler's return type describes the success response. Every other status code a route answers is declared at registration, with a schema of its own."
version: "0.3.0"
last_updated: "2026-10-10T06:42:33.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/response-models"
--------------------------------------------------------------------------------
# Response Models
A handler has one return type, and that type describes one outcome: the one where nothing
went wrong. A route that answers `201` with the thing it just created, `400` with a
complaint about the request and `409` with a conflict report is describing three different
shapes, and only the first of them is in the signature.
`Status`, `WithResponseDoc` and `WithResponseModel` are how the other two reach the
document. None of them changes anything at run time. The success body is still enforced by
the compiler; these describe what the route already does for everything else.
## The status a success is written with
```go
r.Post("/users/", handlers.CreateUser, muzak.Status(http.StatusCreated))
```
`Status` is the code written when the handler returns without an error. It defaults to
`200`, and it is part of the route because it never varies: a creating route creates every
time it succeeds.
A status that depends on what happened is decided in the handler instead.
```go
func CreateItem(ctx *muzak.Context, in schemas.ItemCreateIn) (schemas.ItemOut, error) {
if in.Async {
ctx.SetStatus(http.StatusAccepted)
}
return schemas.ItemOut{ID: in.ID}, nil
}
```
The two never compete: `SetStatus` wins when both are used, and the document describes the
declared one. Declaring the run-time alternative is what the rest of this page is for.
## A schema per status code
`WithResponseModel[T]` documents one status code and the model its body carries. The type
argument is written exactly as a handler's `Out` type would be.
::code-group
```go [schemas/users.go]
type UserOut struct {
ID int `json:"id"`
Username string `json:"username" doc:"The name the account signs in with"`
}
// ErrorOut is this service's own error body, which is not Muzak's envelope.
type ErrorOut struct {
Message string `json:"message" doc:"What went wrong"`
Code string `json:"code" doc:"A machine-readable classifier"`
}
```
```go [routers/users.go]
r.Post("/users/", handlers.CreateUser,
muzak.Status(http.StatusCreated),
muzak.WithResponseModel[schemas.ErrorOut](http.StatusBadRequest, "The request was malformed"),
muzak.WithResponseModel[schemas.ErrorOut](http.StatusInternalServerError, ""),
)
```
::
Each model is described once in the components section and referenced from every operation
that names it, with the same `doc` tags, the same treatment of embedded structs and
pointers, and the same well-known types a return type gets. Nothing about it is a second
class of schema.
A type that is also a request body is the one exception to "described once". A response keeps
its shape, since a member that is not a pointer and not `omitempty` is always written, while a
request lists a member as required only when a `Required()` rule refuses a body without it, and
says `additionalProperties: false`, which a response never does. So a type used both ways always
gets two schemas: the component keeps its shape for the response, and the request refers to a
copy named for it with `Input` after (`Item` and `ItemInput`). See
[OpenAPI](/docs/fundamentals/openapi#request-bodies).
An empty description falls back to the status code's standard reason phrase, so the last
line above reads as *Internal Server Error* in the document and in any page rendering it.
## When the envelope is already right
A handler that reports a failure by returning an error produces Muzak's own error
response. There is no model to choose, only an outcome to name.
```go
r.Get("/items/{item_id}", handlers.ReadItem,
muzak.WithResponseDoc(http.StatusNotFound, "The item does not exist"))
```
`WithResponseDoc` documents that status as `ErrorResponse`, the shape
[Error Handling](/docs/getting-started/error-handling) covers, because that is what the
route actually answers with. Reach for `WithResponseModel` when the body is something
else: a legacy error shape kept for older clients, a partial result, or a body the handler
writes itself.
Its description may be left empty too, so `WithResponseDoc(http.StatusNotFound, "")` is
documented as *Not Found*.
## No body, and bodies that are not JSON
A response model follows the same rules as a return type, including the types that are not
JSON at all.
| Model | What is documented |
|---|---|
| a named struct | `application/json`, referencing the component |
| `muzak.Empty` | the status code, with no content |
| `muzak.HTML` | `text/html` carrying a string |
| `muzak.Bytes`, `muzak.Stream` or `muzak.FileResponse` | a binary string (`format: binary`) under `application/octet-stream` |
| `muzak.Redirect` | the status code with no content, and a required `Location` header |
```go
r.Get("/feed", handlers.Feed,
muzak.WithResponseModel[muzak.Empty](http.StatusNotModified, "The feed has not changed"))
```
A route whose handler returns `Bytes`, `Stream` or `FileResponse` documents its success the
same way, and `muzak.Produces("image/png", "image/webp")` names the media types that response
is sent with in place of `application/octet-stream`. `Produces` describes the route's own
success and nothing declared beside it, and is a build error on a route that answers with
anything else, JSON included. See
[Files, Streams and Redirects](/docs/techniques/files-streams-redirects).
## Declaring one for a whole router
`WithResponseModel` and `WithResponseDoc` are both router options as well as route
options, so an outcome every route shares is declared once.
```go
api := muzak.NewRouter(
muzak.WithResponseModel[schemas.ErrorOut](http.StatusUnauthorized, "No usable credential was presented"))
api.Get("/items/{item_id}", handlers.ReadItem,
muzak.WithResponseModel[schemas.ItemGoneOut](http.StatusGone, "The item was deleted"))
```
Every route beneath the router carries the `401`, and the same works at the point of
inclusion: `app.Include(api, muzak.WithResponseModel[schemas.ErrorOut](418, "I'm a teapot"))`.
Declarations are applied outermost first, and the last one for a status code wins, so a
route replaces what it inherited by declaring the same code again. That also means a
declaration naming the status the route *succeeds* with replaces the response derived from
the return type, which is deliberate for a route that writes its own body and a mistake
otherwise.
A code outside `100` to `599` is not a status code, and fails the build rather than
becoming a response nobody could receive.
## What ends up in the document
For the creating route above:
```json
"responses": {
"201": {
"description": "Created",
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/UserOut"}}}
},
"400": {
"description": "The request was malformed",
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorOut"}}}
},
"422": {
"description": "The request could not be validated.",
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}
},
"500": {
"description": "Internal Server Error",
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorOut"}}}
},
"default": {
"description": "An unexpected error occurred.",
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}
}
}
```
The `422` is added for you on every route that binds anything, since a request that fails
validation never reaches the handler, and a `default` carrying the error envelope closes
the list. Declaring `422` yourself replaces it, like any other code.
The [documentation dashboard](/docs/fundamentals/openapi), if the application serves one,
renders each of them as its own panel, with an example and an expandable schema per media
type, so a client author can read the failure shapes without leaving the page.
## Keep it honest
All of this is description. Nothing verifies at run time that a `404` really carries the
model declared for it, so a declaration is a promise the handler has to keep. Document the
outcomes the route already produces, and let the return type keep speaking for the one the
compiler can check.
## Where to go next
[Responses](/docs/getting-started/responses) covers the return type itself, headers,
cookies and writing the response yourself.
[Error Handling](/docs/getting-started/error-handling) covers the envelope
`WithResponseDoc` describes, and [OpenAPI](/docs/fundamentals/openapi) covers the rest of
the generated document.
--------------------------------------------------------------------------------
title: "Files, Streams and Redirects"
description: "Return bytes, a stream, a file or a redirect instead of JSON, with the document describing each, and let AutoETag answer a client that already has the body with 304."
version: "0.3.0"
last_updated: "2026-10-10T06:35:14.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/files-streams-redirects"
--------------------------------------------------------------------------------
# Files, Streams and Redirects
A handler's return type is encoded as JSON unless it is one of the types that say otherwise.
Muzak recognises them when the route is registered, writes each the way it needs to be
written, and describes each in the OpenAPI document as what it actually sends.
| Return | Sends | Documented as |
|---|---|---|
| `muzak.HTML` | a page, under `text/html` | `text/html` |
| `muzak.Bytes` | a body already in memory, under the media type it names | binary content of the types `Produces` lists |
| `muzak.Stream` | a body read as it is sent, closed on every path | the same |
| `muzak.FileResponse` | one file from an `fs.FS`, with ranges and conditional requests | the same |
| `muzak.Redirect` | a `Location` and no body | the redirect status and a `Location` header |
Everything else about the route is unchanged: guards, providers, the rate limit, errors and
the access log work exactly as they do for a JSON route.
## Bytes
```go
r.Get("/reports/{id}.csv", func(ctx *muzak.Context, in ReportIn) (muzak.Bytes, error) {
csv, err := reports.Render(ctx.Context(), in.ID)
if err != nil {
return muzak.Bytes{}, err
}
return muzak.Bytes{
ContentType: "text/csv; charset=utf-8",
Data: csv,
Filename: "report-" + in.ID + ".csv",
Download: true,
}, nil
}, muzak.Produces("text/csv"))
```
The body is written as given, with a `Content-Length`. The status follows `muzak.Status` and
`ctx.SetStatus` as it does for JSON, and `204` and `304` send no body at all.
`ContentType` is the media type the body is sent as. Left empty it is
`application/octet-stream`, which a browser saves rather than renders. It must be a media type
as RFC 9110 spells it, a type and a subtype with optional parameters; anything else, a line
break or any other control character included, fails the request with a `500` and the cause is
logged, rather than reaching the header. Every one of these responses carries
`X-Content-Type-Options: nosniff`, even with the security headers turned off, so a browser
believes the type it is given instead of guessing from the bytes.
`Filename` and `Download` build the `Content-Disposition` header for you; see
[Offering a download](#offering-a-download).
An error renderer may answer with `Bytes` too, which is how an application sends its failures
in a format of its own.
## Stream
For a body too large to hold, or one produced as it is sent:
```go
r.Get("/exports/{id}", func(ctx *muzak.Context, in ExportIn) (muzak.Stream, error) {
object, err := bucket.Open(ctx.Context(), in.ID)
if err != nil {
return muzak.Stream{}, muzak.NotFound("").Wrap(err)
}
return muzak.Stream{
ContentType: "application/zip",
Body: object,
Length: object.Size(),
}, nil
}, muzak.Produces("application/zip"))
```
`Length` is sent as `Content-Length`, so a client can show progress and tell a truncated body
from a complete one. Zero or less means it is not known, and the body is sent chunked.
**Muzak owns `Body` from the moment the handler returns it.** When it is an `io.Closer` it is
closed exactly once, on every path:
| The request... | ...and the body is |
|---|---|
| is answered | copied, then closed |
| is a `HEAD` | closed without being read |
| answers `204` or `304` | closed without being read |
| failed in the handler, which returned an error beside the stream | closed without being read, and the error rendered |
| failed while the body was read | closed, and the connection aborted |
| lost its client part way | closed, and the connection aborted |
| panicked while the body was read | closed, and the panic recovered |
Do not close it yourself. The copy goes through a pooled 32 KiB buffer, so a server streaming
many bodies does not allocate one per response. A `Stream` with no `Body` fails with a `500`;
return `Bytes` for a body that is empty.
Once the header is sent the response cannot become an error, so a body that fails part way,
ends before the `Length` it declared or runs past it, is logged and the connection aborted:
the client sees a failed transfer rather than a body that ends cleanly and looks complete.
The body is held to its `Length` by Muzak itself, so this holds under
[Compression](/docs/techniques/compression) too, which takes the `Content-Length` off.
The route's `Acquire` releases run before the header is sent, so that a commit that fails can
still answer with an error, and therefore before `Body` is read at all. A `Body` must not read
from anything an `Acquire` provider handed out, such as rows of the request's `Transaction`,
which by then has been committed or rolled back. It opens what it reads itself, and closes it
in its own `Close`. See [Dependencies](/docs/getting-started/dependencies).
Muzak cannot interrupt a `Read` that blocks. A body whose `Read` can wait, such as an
`io.Pipe` fed by a goroutine, should end when `ctx.Context()` is done; a body from an outbound
request made with that context already does.
```go
reader, writer := io.Pipe()
// The goroutine keeps the request's context, never ctx itself: the Context is
// pooled and handed to another request once the handler returns.
requestCtx := ctx.Context()
go func() {
// CloseWithError ends the copy with the producer's failure, and a write
// after the response is closed fails, which is what stops this goroutine
// when the client goes away.
writer.CloseWithError(export.WriteCSV(requestCtx, writer))
}()
return muzak.Stream{ContentType: "text/csv", Body: reader}, nil
```
For a sequence of events rather than one body, use
[Server-Sent Events](/docs/realtime/server-sent-events), which keeps the typed contract.
## Serving a file
```go
var uploads, _ = os.OpenRoot("/var/lib/app/uploads")
r.Get("/files/{name...}", func(ctx *muzak.Context, in FileIn) (muzak.FileResponse, error) {
return muzak.FileResponse{FS: uploads.FS(), Name: in.Name, Download: true}, nil
})
```
The file is served with `http.ServeContent`, so a `Range` request is answered with the ranges
asked for, and `If-Modified-Since`, `If-Unmodified-Since` and `If-Range` are answered from the
file's modification time. A `HEAD` request gets the headers and no body, and the file is
always closed. A `FileResponse` with no `FS` fails with a `500`.
For a whole directory of assets rather than one file a handler chose, mount it with
`Router.Static` instead; see [Static Files and Frontends](/docs/techniques/static-files).
### The name is checked before anything is opened
`Name` is very often what a client asked for, so it is checked first, and a name that fails is
answered `404`, exactly as a file that is not there would be, without the filesystem being asked
to open it.
| A name that... | ...is refused because |
|---|---|
| leaves the filesystem (`../secret`, `/etc/passwd`, `a//b`, a trailing `/`) | `fs.ValidPath` refuses it |
| names a dotfile or anything inside a dot directory (`.env`, `.git/config`, `.well-known/x`) | a deployment directory is where those end up by accident |
| holds a backslash, NUL or any other control character | a filesystem may read it as a separator or the end of the name |
| on Windows, names a drive or a stream (`C:x`, `file.txt:$DATA`) | it opens something other than what it spells |
| on Windows, names a device (`CON`, `nul.txt`, `COM1`, `LPT1`) | Windows opens the device whatever the extension |
| on Windows, ends a segment with a dot or a space (`secret.txt.`) | Windows drops it, so the name opens another file |
| on Windows, is shaped like an 8.3 short name (`GIT~1`) | it opens the long name it abbreviates, which no check has seen |
A directory, a device, a pipe and anything else that is not a regular file is answered `404` as
well: a link to `/dev/zero` would otherwise be read for as long as the client cared to wait. A
file that does not exist logs nothing. Any other failure to open it, a permission or a link the
root refused to follow, is a `404` to the client and logged for you.
### Symbolic links
The check covers the name and nothing else. **`os.DirFS` follows a symbolic link wherever it
points**, so a link planted inside the directory serves whatever file it names. Serve a
directory on disk through the `FS` of an `os.Root`, opened with `os.OpenRoot`, which refuses
to leave it. An `embed.FS` has no links.
### What a file is served as
The type comes from the extension, with the same table `Router.Static` uses, and never from the
content, so a file with no extension is `application/octet-stream`. Set `ContentType` to name
one yourself; it is checked as `Bytes.ContentType` is.
An HTML, SVG or other XML file is sent under `Content-Security-Policy: sandbox`, so a file a
client uploaded cannot run script as your application when it is opened directly. Set
`AllowActiveContent` for a file that is part of your site.
A file from a filesystem whose files cannot seek, such as a zip archive, is buffered up to
8 MiB so ranges keep working, and streamed without them past that.
The status follows `muzak.Status` and `ctx.SetStatus`. `200` is answered by
`http.ServeContent`; `204` and `304` send no body; any other status, a custom `404` page say,
sends the whole file without reading the range or conditional headers. When
`http.ServeContent` answers a range it cannot serve with `416`, it clears `Cache-Control`; a
response that carries a session cookie is kept private regardless.
## Offering a download
`Bytes`, `Stream` and `FileResponse` share two fields:
| Fields | Header |
|---|---|
| neither | none |
| `Filename: "notes.txt"` | `Content-Disposition: inline; filename="notes.txt"` |
| `Download: true` | `attachment`, with the file's own name for a `FileResponse` |
| both | `attachment; filename="..."` |
Never build the header by hand from a name a client chose. The filename is cleaned before it is
sent: control characters (CR, LF and NUL among them), double quotes, the Unicode controls that
reorder text (which would let `invoice` + U+202E + `fdp.exe` display as `invoiceexe.pdf`), and
line and paragraph separators are removed; a slash or a backslash becomes `_`; and the name is
cut to 255 bytes. A name with characters outside ASCII is sent twice, as RFC 6266 asks: an ASCII
stand-in in `filename` and the name in full in `filename*`, encoded as RFC 8187 describes.
```http
Content-Disposition: attachment; filename="r_sum_ _.pdf"; filename*=UTF-8''r%C3%A9sum%C3%A9%20%E2%82%AC.pdf
```
## Redirects
```go
r.Post("/login", func(ctx *muzak.Context, in LoginIn) (muzak.Redirect, error) {
if err := accounts.SignIn(ctx, in); err != nil {
return muzak.Redirect{}, err
}
return muzak.Redirect{To: "/dashboard"}, nil
})
```
A redirect is sent with a `Location` and no body. Its status is `Redirect.Status` when set,
otherwise the route's own when that is a redirect status, and otherwise `302 Found` for `GET`
and `HEAD` and `303 See Other` for every other method. After a form is posted, `303` is the one
status every client follows with a `GET`, which is what keeps a refresh from posting the form
again; for a `GET`, `302` is the conventional "look over there".
| Status | Use it for | The client repeats |
|---|---|---|
| `301` | a move that is permanent | as a `GET` |
| `302` | a move that is not | as a `GET` |
| `303` | "the answer is over there", after a `POST` | as a `GET` |
| `307` | a temporary move that must keep the method and body | the same request |
| `308` | a permanent move that must keep the method and body | the same request |
Any other `Status` fails the request with a `500` and a logged cause, and declaring a status
that is not a redirect on a route returning `Redirect` is a build error.
### Open redirects are refused
A redirect to a place a client named is how a phishing link borrows your domain:
`https://api.example.com/login?next=//evil.com` looks like yours until the browser lands on
`evil.com`. So by default a `Redirect` only goes to a path on your own origin, and the check
is made on every response:
| A target that... | ...is |
|---|---|
| begins with exactly one `/` (`/dashboard`, `/items/42?tab=history#top`) | sent |
| begins with `//` or `/\` (`//evil.com`, `/\evil.com`) | refused: a browser reads it as another host |
| holds a backslash, a space, a tab or a line break anywhere | refused: a browser strips or rewrites them before it reads the URL |
| holds any other control character, or a character outside ASCII | refused: percent-encode it, as `url.URL.String` does |
| holds a `%` that does not begin an escape (`/50%off`) | refused: write it `%25` |
| decodes, once or up to three times, to `//` or `/\` (`/%2F/evil.com`, `/%252F%252Fevil.com`) | refused: a proxy or a framework that decodes again reads another host |
| has a path that decodes to a control character (`/%0d%0aSet-Cookie:x`) | refused |
| reaches `//` once dot segments are resolved (`/.//evil.com`, `/%2e%2e//evil.com`) | refused |
| is relative without a leading `/` (`evil.com`, `../x`) | refused |
| uses a scheme other than `http` or `https` (`javascript:`, `data:`) | refused |
| is an absolute URL to a host nothing lists | refused |
| is empty, or longer than 8 KiB | refused |
A query and a fragment may hold anything a URI may, so `/login?next=%2F%2Fevil.com` is fine: it
is your own login page that has to check `next` before it follows it.
A refusal fails the request with a `500`, and the log names the reason but not the target, which
may carry a token in its query.
### Absolute URLs
An absolute `http` or `https` URL is sent only when its host is listed with `RedirectHosts`, on
the route, a router above it or the application:
```go
app := muzak.New(opts, muzak.RedirectHosts("accounts.example.com", "localhost:5173"))
```
A listed host is compared without regard to case, and must otherwise be exactly the one listed:
| Target | With `RedirectHosts("accounts.example.com")` |
|---|---|
| `https://accounts.example.com/cb` | sent |
| `https://ACCOUNTS.example.com/cb` | sent |
| `https://accounts.example.com:443/cb` | sent: the scheme's default port |
| `https://accounts.example.com:8443/cb` | refused: another port is another service |
| `https://accounts.example.com./cb` | refused: a name with a trailing dot is not the name listed |
| `https://accounts.example.com.evil.com/` | refused |
| `https://sub.accounts.example.com/` | refused: there are no wildcards |
| `https://accounts.example.com@evil.com/` | refused: user information disguises the real host |
| `https://accounts%2Eexample.com/` | refused: a host is never percent-encoded |
| `https:accounts.example.com` | refused: an absolute URL names its host after `//` |
An entry is a host name or an IP address with an optional port, an IPv6 address in brackets.
An entry without a port admits the scheme's default port only, written or not; one with a port
admits that port only. Anything else, a scheme, a path, user information, a wildcard or a
trailing dot, is a build error, reported for each route that can answer with a `Redirect`. A
list is read only by such routes, so a mistake in one declared on the application is not
reported until a route returns `Redirect`. Lists add up: a route may send a client to any host
it or a router above it lists.
For a target your handler built from its own configuration rather than from the request, such as
an identity provider's authorization endpoint, set `External`:
```go
return muzak.Redirect{To: oauth.AuthCodeURL(state), External: true}, nil
```
`External` vouches for the host and nothing else: the target must still be a well-formed `http`
or `https` URL with a host and no user information. **Never set it for a URL taken from the
request.**
An error renderer may answer with a `Redirect` too, which is how a missing session sends a
browser to the login page. It is checked the same way, against the hosts of the route that
failed, and only a route that itself returns `Redirect` reads its hosts. A path on your own
origin is always fine; a renderer sending a client to another host sets `External` for the URL
it built.
## Entity tags
```go
app := muzak.New(opts, muzak.AutoETag())
```
`AutoETag` tags a response with an entity tag computed from its body, and answers a request
that already holds that body with `304 Not Modified`, so the client keeps its copy and the
bytes are not sent again. It is a shared option: declare it on the application (`muzak.New` or
`app.Options`), a router, an `Include` or a single route. Once on, it stays on for everything
beneath: a tag only ever saves sending a body the client already has, so there is nothing a
route below gains by turning it back off.
It applies to a `GET` or `HEAD` answered `200` with a body Muzak holds in full: JSON, `HTML` and
`Bytes`. The tag is strong, the first 128 bits of the body's SHA-256 in unpadded base64url,
quoted, so it changes whenever a byte of the body does and only then. JSON is encoded with map
keys sorted on a tagged route, so the same value always produces the same tag. A handler that
sets its own `ETag` keeps it, and the request is answered against that one.
```http
GET /items/42 HTTP/1.1
If-None-Match: "q1Hs3cWc9mJfV8x1Zr0b2A"
HTTP/1.1 304 Not Modified
ETag: "q1Hs3cWc9mJfV8x1Zr0b2A"
```
`If-None-Match` is compared weakly, as RFC 9110 requires, so `W/"..."` matches too, and `*`
matches any body. It is read as a list, in a single pass, so a tag holding a comma is found
where it is; a field that is not a well-formed list is ignored and the full response sent,
because a full response is always correct and a 304 sent on a misreading is not.
The `304` keeps what RFC 9110 asks for, `ETag`, `Cache-Control`, `Content-Location`, `Date`,
`Expires` and `Vary`, and drops what describes the body it does not send: `Content-Type`,
`Content-Length`, `Content-Encoding`, `Content-Language`, `Content-Disposition`,
`Last-Modified` and the rest. Headers about the exchange rather than the body, such as
`Set-Cookie`, the CORS answer and the request identifier, are kept.
It composes with what surrounds it:
- **Compression** weakens the tag of a body it compresses, `"v1"` to `W/"v1"`, and of the
`304` it answers for one, so a cache can use the `304` to refresh what it stored. The weak tag
the client sends back still matches. See [Compression](/docs/techniques/compression).
- **A guarded route** keeps `Cache-Control: private, no-cache` on its `304`, so a shared cache
never stores it. A guard still runs first, so a client it refuses is refused whatever tag it
holds, and a different user with someone else's tag is sent their own body.
- **A `Stream`** has no body to hash until it is sent, and **a `FileResponse`** is answered by
`http.ServeContent`, which reads the conditional headers itself, so neither is tagged.
- **Anything else** is left alone: a `POST`, a `201`, an error, a redirect.
The body is hashed on every tagged request, which costs time linear in its size: the `304`
saves the bytes and the client's work, not the handler's. A route that does not declare it pays
nothing, not even a look at the request's headers.
## In the document
`Bytes`, `Stream` and `FileResponse` are described as binary content, under
`application/octet-stream` unless the route lists its types with `Produces`:
```go
r.Get("/avatars/{id}", handlers.Avatar, muzak.Produces("image/png", "image/webp"))
```
```json
"200": {
"description": "OK",
"content": {
"image/png": {"schema": {"type": "string", "format": "binary", "contentMediaType": "image/png"}},
"image/webp": {"schema": {"type": "string", "format": "binary", "contentMediaType": "image/webp"}}
}
}
```
`format: binary` is what client generators read as "a file, not text to parse", and
`contentMediaType` says the same thing in JSON Schema's terms. A range such as `image/*` is
accepted and carries no `contentMediaType`. `Produces` only describes: the type a response is
sent with is the one the value names. It is a route option, declared on the route it describes.
Using it on a route returning anything else, JSON included, giving it no types, or giving it
something that is not a media type is a build error.
A `Redirect` is described with its status, no content and a `Location` header:
```json
"303": {
"description": "See Other",
"headers": {
"Location": {
"description": "Where the client is sent: a path on this origin, or an absolute URL to a host the route allows.",
"required": true,
"schema": {"type": "string", "format": "uri-reference"}
}
}
}
```
`WithResponseModel[muzak.Bytes]` (or `Stream`, or `FileResponse`) describes another status as
binary content under `application/octet-stream`, and `WithResponseModel[muzak.Redirect]`
describes one as a redirect with its `Location`; see
[Response Models](/docs/techniques/response-models). Returning a pointer to any of these types
is a build error, since it would be encoded as JSON. [OpenAPI](/docs/fundamentals/openapi)
covers the rest of the document.
## Limits
- **`Bytes` and `Stream` are sent under the type you name, unsandboxed.** Only a
`FileResponse` adds `Content-Security-Policy: sandbox` to HTML, SVG and XML. A `Bytes` or
`Stream` sent as `text/html` is a page of your origin, so never send a body a client wrote
that way; send it as `text/plain` or `application/octet-stream`, or as a download.
- **A file a client uploaded is served under its real type.** An uploaded `.js` or `.css`
file is sent as JavaScript or CSS, which a page of your origin may then load, and a
`Content-Security-Policy` of `script-src 'self'` does not stop it, since the file is your
origin's. Serve uploads from another origin, or set `ContentType` to
`application/octet-stream`, which `nosniff` keeps a browser from running as a script or
applying as a stylesheet. `Download` alone is not enough: it changes what a browser does
with the file opened directly, and nothing about a page that loads it.
[Safe Defaults](/docs/security/safe-defaults) lists the headers every response carries,
`nosniff` among them.
## Where to go next
[Responses](/docs/getting-started/responses) covers the return type, status codes and headers,
[Static Files and Frontends](/docs/techniques/static-files) covers mounting a whole directory,
[Compression](/docs/techniques/compression) covers how compressed bodies and entity tags
interact, and [Typed Endpoints](/docs/techniques/typed-endpoints) covers how a Go caller
receives `Bytes`, `Stream` and `Redirect` back as themselves.
--------------------------------------------------------------------------------
title: "Problem Details"
description: "Render every error as an RFC 9457 problem, application/problem+json, with the same codes, details, translations and leak guarantees as the default envelope, and a document that says so."
version: "0.3.0"
last_updated: "2026-10-10T06:32:04.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/problem-details"
--------------------------------------------------------------------------------
# Problem Details
RFC 9457, "Problem Details for HTTP APIs", is the standard shape for an error body, and the
one an API gateway, a client generator or another team's service may already expect. Muzak's
default envelope stays the default; one option switches the whole application to problems.
```go [cmd/main.go]
app := muzak.New(muzak.AppOptions{
Title: settings.AppName,
// Every error is answered as application/problem+json, and the OpenAPI
// document describes every error response that way.
ProblemDetails: &muzak.ProblemOptions{TypeBase: "https://errors.example.com/"},
})
```
```json
{
"type": "https://errors.example.com/validation_error",
"title": "Unprocessable Entity",
"status": 422,
"detail": "The request could not be validated.",
"instance": "urn:uuid:0611f4b2-2f0a-7b57-9c1a-6e6a2e2f9b31",
"code": "validation_error",
"errors": [
{ "field": "name", "location": "body", "issue": "is required" },
{ "field": "limit", "location": "query", "issue": "must be a valid integer" }
],
"request_id": "0611f4b2-2f0a-7b57-9c1a-6e6a2e2f9b31"
}
```
## The members
| Member | Carries |
|---|---|
| `type` | `TypeBase` followed by the error code, path-escaped; `about:blank` when no base is set |
| `title` | the status's reason phrase, such as `Not Found`, translated where the application translates it |
| `status` | the HTTP status |
| `detail` | the message the default envelope would carry, held to the same rule |
| `instance` | `urn:uuid:` followed by the request identifier |
| `code` | the stable classifier, such as `not_found` (extension) |
| `errors` | every field that failed, as the envelope's `details` (extension, omitted when empty) |
| `request_id` | the identifier that joins the response to the server's log (extension) |
The Go type is `muzak.Problem`, and the media type `muzak.ProblemContentType`.
`instance` names the occurrence by its request identifier rather than by the request's path. A
path can hold personal data, an email address or a name, that a problem report forwarded to a
ticket or a log aggregator should not repeat. Every identifier Muzak assigns is a UUID, so the
member is a URN of the registered `uuid` namespace; an application that assigns identifiers of its
own that are not UUIDs gets no `instance`.
`code`, `errors` and `request_id` are what the default envelope carries, so a client moving from
one format to the other loses nothing. Branch on `code`, or on `type` when a base is set; never on
`title` or `detail`, which are text for people and are translated.
## TypeBase
```go
muzak.ProblemOptions{TypeBase: "https://errors.example.com/"} // https://errors.example.com/not_found
muzak.ProblemOptions{TypeBase: "urn:example:errors:"} // urn:example:errors:not_found
muzak.ProblemOptions{} // about:blank
```
The code is appended as it is, so the base ends in whatever separates the two. A code with a
character a path segment cannot carry, as one set with `WithCode("card declined")` might, is
escaped: `card%20declined`. The RFC recommends serving documentation at each type URI; Muzak does
not, so publish it there if you name a base that resolves.
Left empty, every problem's type is `about:blank`, which the RFC defines as a problem described by
its status alone, and the title is then the status's reason phrase, as the RFC asks.
A base that is not an absolute URI, or that carries a query, a fragment, whitespace or a
character outside ASCII, is a build error: a client would resolve a relative one against wherever
it read the response, and a code appended after a `?` or `#` would land in the wrong part.
## The same promises as the envelope
The problem renderer decides nothing on its own. It asks `DefaultErrorRenderer` and reshapes what
that decided, so everything [Error Handling](/docs/getting-started/error-handling) says about the
envelope holds for a problem too:
- The same status and code for every error, and the same details for a validation failure.
- A server-side fault, a plain `error`, a `StatusCoder` at `500` or above, or a panic, is
answered with the fixed sentence `The server could not complete the request.` while the cause
is logged and never sent. An `*HTTPError` keeps the message it was written with, at any status.
- The headers set before the error was rendered are kept: `Allow` on a `405`, `Retry-After` on a
`429`, `WWW-Authenticate` on a `401`, `Vary`, `Set-Cookie`. The body's own headers are reset and
the response is sent with `Cache-Control: no-store`.
Every error the application produces is a problem, not only those a route returns: a refused host,
a rate limit, a guard on a mounted handler, an unknown path, a method the documentation does not
answer, the `405` of a health endpoint, and a panic in middleware installed with `App.Use`, which
used to be answered with the fixed envelope whatever the renderer was. So is the `500` an
application that failed to build answers every request with, and the fixed `500` that stands in
when an error renderer's body cannot be encoded; neither has a request to translate for, so both
are in English.
The same goes for the features that refuse a request before any route runs. A state-changing
request a browser sends from another origin is refused by
[Cross-Origin Requests](/docs/security/cross-origin-requests) with a `403` problem whose code is
`cross_origin_request`, and a [session](/docs/security/sessions) that cannot be saved fails its
request through the renderer, as a handler's error would.
## Translation
`detail` is translated exactly as the envelope's `message` is (see
[Internationalization](/docs/fundamentals/internationalization)). `title` is looked up at
`muzak.status.`, falling back to the English phrase net/http knows the status by:
```yaml [locales/es.yml]
es:
muzak:
status:
404: "No encontrado"
422: "Entidad no procesable"
http:
404: "No se encontro el recurso solicitado."
```
The shipped locale carries the English titles of every status the framework classifies, and a test
keeps them equal to `http.StatusText`, so turning a store on changes no English title. The machine
members, `type`, `code` and `status`, are never translated.
## The document
With `ProblemDetails` set, every error response the [OpenAPI](/docs/fundamentals/openapi)
document describes, the `422` of a route that binds input, the `429` of a rate-limited one, the
`503` of a route with a `Timeout`, each `WithResponseDoc` and the `default`, is
`application/problem+json` with a `$ref` to the `Problem` component, and the `ErrorResponse`
component is no longer emitted. A response declared with `WithResponseModel` keeps its own model.
## Composing with a renderer of your own
`muzak.ProblemDetails(opts)` is the renderer itself, so an application with errors of its own to
render can delegate the rest to it:
```go
problems := muzak.ProblemDetails(muzak.ProblemOptions{TypeBase: "https://errors.example.com/"})
app := muzak.New(muzak.AppOptions{
ProblemDetails: &muzak.ProblemOptions{TypeBase: "https://errors.example.com/"},
ErrorRenderer: func(ctx *muzak.Context, err error) (int, any) {
var declined *billing.DeclinedError
if errors.As(err, &declined) {
ctx.SetHeader("Content-Type", muzak.ProblemContentType)
return http.StatusPaymentRequired, DeclinedProblem{ /* ... */ }
}
return problems(ctx, err)
},
})
```
When `ErrorRenderer` is set, it is used, and `ProblemDetails` still tells the document that errors
are problems. Set both, as above: installing `muzak.ProblemDetails` through `ErrorRenderer` alone
renders problems but leaves the document describing the envelope.
## Limits
A few answers are written by net/http's file serving rather than by the renderer, and are plain
text whatever the format:
- The `416` that `http.ServeContent` sends for a range a file cannot satisfy, on a static file
or frontend mount and for a `FileResponse`.
- The `404` or `500` a static file or frontend mount sends when a file it found cannot be opened
or read a moment later, for instance because it was deleted in between. The cause is logged.
## Where to go next
[Error Handling](/docs/getting-started/error-handling) covers which errors describe themselves and
which stay opaque, and [OpenAPI](/docs/fundamentals/openapi) what else the document says about a
route.
--------------------------------------------------------------------------------
title: "Mounting net/http Handlers"
description: "Serve pprof, a metrics handler, a connect-go service or a legacy application beside your routes, behind the same guards, rate limit and middleware."
version: "0.3.0"
last_updated: "2026-10-10T06:32:47.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/mounting-handlers"
--------------------------------------------------------------------------------
# Mounting net/http Handlers
Not everything an application serves is a typed route. Profiling, metrics, an RPC service
generated by another tool, or the application you are migrating away from are all plain
`http.Handler`s. `Router.Mount` serves one at a prefix, for the prefix itself and everything
beneath it, for every method.
::code-group
```go [cmd/main.go]
app := muzak.New(muzak.AppOptions{Title: settings.AppName})
// Operators only: the same guard every admin route uses.
app.Mount("/metrics", promhttp.Handler(), muzak.Needs(auth.RequireOperator))
// net/http/pprof reads the full path, /debug/pprof/heap say, to choose a
// profile, so it is mounted at the path it was written for, without
// StripPrefix.
pprofMux := http.NewServeMux()
pprofMux.HandleFunc("/debug/pprof/", pprof.Index)
pprofMux.HandleFunc("/debug/pprof/cmdline", pprof.Cmdline)
pprofMux.HandleFunc("/debug/pprof/profile", pprof.Profile)
pprofMux.HandleFunc("/debug/pprof/symbol", pprof.Symbol)
pprofMux.HandleFunc("/debug/pprof/trace", pprof.Trace)
app.Mount("/debug/pprof", pprofMux, muzak.Needs(auth.RequireOperator))
// Whatever no route answers yet.
app.Mount("/", legacy.Handler())
```
```go [internal/auth/guards.go]
// RequireOperator admits a request carrying the operator token, and nothing
// else. It is a provider rather than a guard so that a route can read the
// operator it resolved; a mount runs it for its verdict.
func RequireOperator(ctx *muzak.Context) (Operator, error) {
token, ok := muzak.BearerToken(ctx)
if !ok || !muzak.SecureCompare(token, settings.OperatorToken) {
return Operator{}, muzak.Unauthorized("")
}
return Operator{Name: "ops"}, nil
}
```
::
The prefix is relative to the router the mount is registered on, under whatever prefixes that
router is included with, exactly as a route's path is. A single trailing slash is ignored, so
`"/debug/pprof/"` and `"/debug/pprof"` are one mount, and `"/"` mounts at the root of the router.
## What wins
The most specific answer wins, as it does everywhere in the routing tree.
| Request | Answered by |
|---|---|
| A path a route is registered at, with a method the route registers | the route |
| `HEAD` on a path with a `GET` route | the route, as without the mount |
| A path a route is registered at, with any other method, `OPTIONS` included | the mount |
| A path beneath the prefix that no route has | the mount |
| A path beneath a longer mount inside this one | the longer mount |
| A path beneath a `Frontend` or `Static` mounted inside this one | the file mount |
That is what a migration needs. With the legacy application mounted at `/` and `GET /users`
moved to a route, `GET /users` is answered by the route and `POST /users` still reaches the legacy
handler, until it moves too. Beneath a mount no `405` is ever answered, since the mount takes
every method the routes there do not.
```go
app.Get("/users", handlers.ListUsers) // migrated
app.Mount("/", legacy.Handler()) // POST /users, /orders, ... still here
```
These are build errors, all reported by one `Build`:
- two mounts at one prefix, including `"/x"` and `"/x/"`;
- a mount at the prefix of a `Frontend` or `Static` mount;
- a mount at the documentation's own path, since the documentation is answered ahead of routing;
- a route whose wildcard sits directly beneath the prefix, such as `"/legacy/{rest...}"` beside
a mount at `/legacy`, because the two would answer exactly the same paths;
- a prefix that does not begin with `/`, or that holds a parameter or wildcard (including one
inherited from `WithPrefix("/{tenant}")`), an empty segment, a `.` or `..` segment, or a
character a request carries only percent-encoded;
- a nil handler;
- a `Timeout` given to `Mount`, described [below](#what-it-does-not-do).
[Health Checks](/docs/deployment/health-checks) are answered ahead of routing, so a handler
mounted at the root leaves `/livez` and `/readyz` to them. A health path beneath any other mount,
or a health path of `/` beside a handler mounted at the root, would take a path the mount was
given, and is a build error too.
## It runs inside the application
A mounted handler is not a side door. Everything a route runs inside, it runs inside:
- the [middleware](/docs/getting-started/middleware) installed with `App.Use`, the CORS policy,
the cross-origin protection, the security headers, request identification, the access log and
panic recovery;
- before it runs, the **rate limit**, the **guards** and the **providers** of every router it is
registered under and of the options given to `Mount`, in the order a route runs them. A refusal
is rendered by the error renderer exactly as a route's is;
- a security requirement it inherits that names a verifying scheme, such as one built by
`JWTBearer` or `APIKeyVerifier`, ahead of the guards, exactly as for a route. `Public()` given to
the mount exempts it. See [Authentication](/docs/security/authentication).
The mount is counted by its routers' [rate limit](/docs/techniques/rate-limiting) as a route of
theirs is: a quota shared with routes is spent by the mount too, and every spelling of the path
that reaches it counts against the one quota. `SkipRateLimit()` given to `Mount` leaves it out.
A provider's value is not handed on, since the handler has no `*muzak.Context` to read it from; a
provider runs for its verdict. A mount behind any guard, request-scoped provider or verifying
security scheme answers with `Cache-Control: private, no-cache` unless the handler sets a
`Cache-Control` of its own, so a shared cache does not hand one client's metrics to another.
`App.Override` and `testclient.Override` reach the providers given to `Mount` as they reach a
route's, and a provider given to it with a nil function is a build error.
A provider declared with `Acquire` is released once the handler returns, and is told the request
succeeded, whatever status the handler wrote: the handler decided what to answer, so nothing
failed on the framework's account. A panic releases it with the failure, and a release that fails
is handled as a handler's failure would be, which aborts a response already started. A `Frontend`
or `Static` mounted beneath the prefix releases what it acquired once the file is served. So a
`Transaction` declared on a router commits behind a mounted handler that answered `500`; declare
it on the routers whose routes need it rather than on one a mount sits under. See
[Dependencies](/docs/getting-started/dependencies).
The handler receives the **original** `*http.Request` (with [StripPrefix](#stripprefix), a
shallow copy of it carrying the shorter path), never the pooled `muzak.Context`. Its context
carries the framework's values:
```go
func handler(w http.ResponseWriter, r *http.Request) {
id, _ := muzak.RequestIDFromContext(r.Context()) // same as X-Request-Id
route, _ := muzak.RouteFromContext(r.Context()) // the mount prefix, "/metrics"
}
```
The access log records the prefix as the request's route, so a mount is one time series rather
than one per path, and so do [tracing and the request observer](/docs/fundamentals/observability).
Since a mount answers whatever method a client sends, a method no standard defines is recorded
there as `_OTHER`, so a client cannot mint a span name or a metric series per request.
A panic in the handler is recovered as a route's is: before anything was written it becomes the
standard `500`, with the stack in the log and nothing of it in the response; after the response
started, the connection is aborted so a client cannot mistake a truncated body for a complete one.
`http.ErrAbortHandler` still aborts. The writer flushes and hijacks, so a streaming or WebSocket
endpoint of the legacy application keeps working.
## Body limits
A mounted handler reads its own body, and the body is still bounded by the `MaxBodySize` the
mount inherits (one mebibyte by default). A body that declares a length over it is refused with
`413` before the handler runs; one of unknown length is read through `http.MaxBytesReader`, so the
read that goes over fails with `*http.MaxBytesError` and the handler answers as it would.
```go
app.Mount("/upload", legacyUploads, muzak.MaxBodySize(64<<20))
// A client-streaming RPC is one long body. Remove the limit, and bound the
// messages in the RPC framework instead.
app.Mount("/rpc", connectHandler, muzak.MaxBodySize(-1))
```
On a mount, unlike a route, a negative `MaxBodySize` given to `Mount` removes the limit.
`MaxUploadSize` plays no part, since nothing tells a mount which bodies are uploads, so a mount
that accepts files is given a `MaxBodySize` large enough for them, as above.
A multipart form the handler parses has its temporary files removed when it returns or panics, as
a route's are, with or without `StripPrefix`.
## StripPrefix
`muzak.StripPrefix()` gives the handler paths relative to the mount, the way
`http.StripPrefix` does, so a handler written to be served at the root can be served beneath a
prefix unchanged.
```go
// The old application was written to be served at the root.
app.Mount("/legacy", legacy.Handler(), muzak.StripPrefix())
```
| Request | Path the handler sees |
|---|---|
| `/legacy/users` | `/users` |
| `/legacy` | `/` |
| `/legacy/` | `/` |
| `/legacy/a%2Fb` | `/a/b`, escaped `/a%2Fb` |
| `/%6Cegacy/users` | `/users` |
Two differences from `http.StripPrefix` are deliberate. The prefix itself becomes `/` rather than
the empty path, which a `ServeMux` would answer with a redirect to the root of the **site**. And
the prefix is removed segment by segment from the escaped path, so a prefix the client spelled
with escapes is stripped too, and what remains keeps its own. The handler is given a shallow copy
of the request carrying the new URL; `RequestURI`, the context and everything else are the
original request's.
A handler that redirects to an absolute path of its own, as `ServeMux` does to add a trailing
slash, writes a `Location` relative to the root of the site rather than to the mount; serve such
a handler without `StripPrefix`, at the path it expects. The same goes for a handler that reads
the full path to decide what to serve, as `net/http/pprof` does, which is why the example at the
top of this page mounts it without `StripPrefix`. `StripPrefix` given to `NewRouter`, `Include` or
`App.Options` is a build error rather than an option that silently does nothing.
## What the guards cover
The router never normalises a path: no case folding, no collapsing of `//`, no resolving of `.`
or `..`. A request reaches the mount only through the tree's exact match of the prefix, segment
by segment, with a percent-escape decoded only where it does not encode a `/`. For a mount at
`/admin`:
| Spelling | Reaches the mount |
|---|---|
| `/admin`, `/admin/`, `/admin/x`, `/admin//x` | yes, and runs its guards |
| `/%61dmin/x`, `/adm%69n` | yes, and runs its guards |
| `/admin/./x`, `/admin/../x` | yes, and runs its guards |
| `//admin/x`, `/ADMIN/x`, `/Admin` | no |
| `/./admin/x`, `/x/../admin/x`, `/%2e/admin/x` | no |
| `/admin%2Fx`, `/admin;x`, `/admin%00`, `/admin\x` | no |
So whatever the mounted handler serves has passed its guards: the framework's tests send every
spelling above as a raw request line through a real server and check it. What the handler then
does with the path it is given is its own affair. A handler that cleans, decodes or case-folds
paths, a file server on a case-insensitive disk say, may serve for `/admin/../x` something that a
guarded route beside the mount was meant to protect. Give such a handler guards that cover
everything it can serve, and do not rely on the guards of a route the request did not reach. The
same warning applies to a `{name...}` wildcard route; see [Routers](/docs/getting-started/routers).
A spelling of a path beneath a `Frontend` or `Static` that a case-insensitive filesystem would
open, such as `/APP/x` beneath a frontend at `/app`, is refused with `404` rather than handed to a
less specific mount, exactly as it is refused rather than handed to a less specific frontend.
## What it does not do
Mounts are not described in the OpenAPI document, which describes the routes Muzak can see
into, and an [MCP endpoint](/docs/techniques/mcp-tools) never offers one as a tool. Options that
describe or bind a route, such as `WithTags` or `CaptureBody`, have no effect on a mount. A mount
answers every API version when versioning is on, because it has no version of its own to choose
by. `Mount` panics once the application has been built, as registering a route does.
A [Timeout](/docs/techniques/timeouts) is not applied to a mounted handler, which writes its own
response and may be streaming one. One inherited from a router is left out, as it is for an event
stream, and one given to `Mount` is a build error rather than a bound nothing enforces. Give the
handler a deadline of its own, with `http.TimeoutHandler` for one.
## Where to go next
[Static Files and Frontends](/docs/techniques/static-files) covers the file mounts a handler
mount sits beside, and [Rate Limiting](/docs/techniques/rate-limiting) the budget it shares with
routes. [Allowed Hosts and HTTPS](/docs/security/hosts-and-https) covers the checks that run
ahead of every mount.
--------------------------------------------------------------------------------
title: "Background Tasks"
description: "Run work the client should not wait for after the response is written, on a bounded pool that a shutdown drains before it stops the components the work uses."
version: "0.3.0"
last_updated: "2026-10-10T06:32:04.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/background-tasks"
--------------------------------------------------------------------------------
# Background Tasks
Some work belongs to a request without belonging to its response: the welcome email after a
sign-up, an audit record, a cache to warm. The client should not wait for it, and a bare
`go func()` is the wrong tool, because nothing bounds how many there are, nothing waits for
them at shutdown, and the one that captured the `*muzak.Context` reads another request's
values a moment later. `Context.AfterResponse` registers the work instead.
::code-group
```go [handlers/users.go]
func SignUp(ctx *muzak.Context, in schemas.SignUpIn) (schemas.UserOut, error) {
user, err := users.Create(ctx.Context(), in)
if err != nil {
return schemas.UserOut{}, err
}
// Copied out before registering: the task never sees ctx.
log := ctx.Logger()
email := user.Email
if err := ctx.AfterResponse(func(bg context.Context) {
if err := mailer.SendWelcome(bg, email); err != nil {
log.ErrorContext(bg, "welcome email failed", "error", err)
}
}); err != nil {
// The queue is full or the server is shutting down. The user exists
// either way; the email is what is lost, so say so.
log.Warn("welcome email not queued", "error", err)
}
return schemas.UserOut{ID: user.ID, Email: user.Email}, nil
}
```
```go [cmd/main.go]
app := muzak.New(muzak.AppOptions{
Title: "Awesome API",
Background: muzak.BackgroundOptions{
Workers: 8, // tasks running at once
Queue: 256, // tasks waiting for a worker
},
})
```
::
## When a task runs
**Only when the handler succeeds.** A task runs when the handler returned a nil error without
panicking. A request that fails drops every task it registered, whether its handler returned
an error, a guard or the binder refused it, or something panicked, including a value that
panicked while its response was being encoded. A task registered by a guard or a provider
follows the same rule: it runs if the route's handler then succeeds.
**After the response.** Tasks are handed to the workers once the response has been passed to
`net/http`, so the response never waits for them. They are handed over before the middleware
installed with `App.Use` has unwound, and a task can begin before the last byte has reached the
client.
**Whatever happens to the response afterwards.** Once the handler has returned nil, its own
work is done: a client that leaves before reading the response does not cancel the email
that was promised to it, and neither does a response value whose `MarshalJSON` returns an
error. A value that panics while it is encoded is the exception, because something panicked.
**Unless the route's releases were told it failed.** On a route with an
[`Acquire`](/docs/getting-started/dependencies) provider, a value that fails to encode is
reported to each `Release` as a failure, as an error of the handler's own would be. The work
the tasks were to follow has been undone, a `Transaction` rolled back, so the tasks are dropped
with it. The tasks follow what the releases were told.
**In no particular order.** The tasks of one request run concurrently with each other and with
everyone else's. A task that has to follow another should be one task.
## What a task receives
| | Kept | Not kept |
|---|---|---|
| Request identifier (`RequestIDFromContext`) | yes | |
| Locale (`LocaleFromContext`) | yes | |
| Anything middleware stored in the context | yes | |
| The request's cancellation | | the request ending does not end the task |
| A route's `Timeout` deadline | | |
| The `*muzak.Context` | | never |
The context is cancelled when the shutdown deadline is reached, with a cause that says so,
which is worth logging when a task gives up:
```go
if err := export.Run(bg); err != nil {
log.ErrorContext(bg, "export abandoned", "error", err, "cause", context.Cause(bg))
// cause="muzak: the shutdown deadline passed before this background task finished"
}
```
A task that honours it is the difference between a shutdown that finishes on time and one
that has to abandon the task.
The `*muzak.Context` is pooled and belongs to another request by the time the task runs, so the
task never receives it; copy out what it needs before registering it. `ctx.Logger()` returns a
logger that carries the request's method, path and identifier (and its trace when tracing is
on) and holds nothing of the pooled Context, so it is the one value always worth capturing.
## Bounds
| Field | Default | Bounds |
|---|---|---|
| `Workers` | 4 | How many tasks run at once |
| `Queue` | 64 | How many registered tasks may wait for a worker |
A task counts against `Queue` from the moment it is registered, while its request is still
being served, so a request that succeeds never finds the queue full at the moment its tasks are
handed over. A registration past the bound returns `muzak.ErrBackgroundQueueFull` at once: the
handler is never blocked waiting for room, and no goroutine is started to hold the task. What
to do then is the handler's decision: do the work before returning, drop it with a log line,
or fail the request.
The same rule has a cost: a slow request holds the place its task took until the request ends.
Many slow requests that each registered a task early can fill the queue while no worker is
busy, and later registrations are refused until they finish. Register a task as late in the
handler as you can, once the work it follows is done, and size `Queue` for the requests in
flight as well as for the tasks waiting.
There is no unbounded setting, on purpose: a queue without a cap is a backlog anyone who can
send requests can grow. A negative value is a build error and zero takes the default.
No goroutine exists while there is nothing to run. A worker is started when a task is handed
over and fewer than `Workers` are running, and exits as soon as the queue is empty, so an
application that never registers a task never runs one, and a request that registers none pays
nothing for the feature.
A panic in a task is recovered and logged with the request identifier and the stack, and the
worker carries on with the next task.
```
14:32:07.913 ERROR [Server] muzak: recovered from a panic in a background task panic="assignment to entry in nil map" request_id=0192a7c1 stack=...
```
## Shutdown
A shutdown runs the tasks it already accepted, in an order that keeps them working:
1. Readiness reports unavailable, and the server keeps serving through `DrainDelay` (see
[Health Checks](/docs/deployment/health-checks)). Tasks registered meanwhile are accepted as
usual.
2. The listeners close. From here on `AfterResponse` returns
`muzak.ErrBackgroundShuttingDown`, while requests in flight are drained; the tasks they
registered earlier are still handed over when they finish.
3. The queued and running tasks are waited for.
4. The [lifecycle components](/docs/getting-started/lifecycle) are stopped, so a task can still
use the database pool it needs.
All of it shares `ShutdownTimeout`. When the deadline passes during step 3, the tasks still
waiting for a worker are dropped, the running ones have their context cancelled and are given
100 milliseconds to return, and the components are stopped anyway. Both are logged:
```
14:32:56.903 WARN [Server] Shutdown deadline reached; dropped 12 queued background tasks that had not started
14:32:57.004 WARN [Server] 1 background task still running after the shutdown deadline and its grace period; stopping lifecycle components anyway
```
Size the pool with that in mind: `Workers` should get through a full `Queue` within
`ShutdownTimeout`. A negative `ShutdownTimeout` waits for the tasks without limit.
## Where it is refused
| Called from | Result |
|---|---|
| A handler, guard or provider of an ordinary route | Registered |
| An event stream or WebSocket handler | An error: the response ends only when the handler returns, so do the work then |
| A guard or provider of the documentation, a static file or frontend mount, or a handler given to `Mount` | An error: no route is being served |
| A goroutine after the handler returned | An error, if the Context has been released; and a data race either way |
| `AfterResponse(nil)` | An error |
An application served by hand through `App.ServeHTTP` runs its tasks the same way, but nothing
drains them, since no `Shutdown` is involved.
## Testing
The [test client](/docs/fundamentals/testing) serves the application through the same server
and shuts it down the same way when the test ends, so the test's cleanup waits for the tasks
its requests registered. A test that wants to see a task's effect before then waits for it on a
channel the task closes.
## Where to go next
[Lifecycle](/docs/getting-started/lifecycle) covers the components a task uses,
[Health Checks](/docs/deployment/health-checks) the readiness drop and drain delay that begin a
shutdown, and [Timeouts](/docs/techniques/timeouts) the deadline a task does not inherit.
--------------------------------------------------------------------------------
title: "Timeouts"
description: "Give a route, or every route of a router, a deadline its guards, providers and handler share, answered with a 503 when it passes and never enforced by a second goroutine."
version: "0.3.0"
last_updated: "2026-10-10T06:32:04.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/timeouts"
--------------------------------------------------------------------------------
# Timeouts
`muzak.Timeout` gives a route a deadline for answering a request.
```go [routers/reports.go]
r := muzak.NewRouter(muzak.WithPrefix("/reports"), muzak.Timeout(5*time.Second))
r.Get("/{id}", handlers.GetReport) // 5s, from the router
r.Post("/export", handlers.Export, muzak.Timeout(30*time.Second)) // 30s, its own
r.Get("/live", handlers.LiveTotals, muzak.Timeout(-1)) // none
```
It is a `SharedOption`, so it goes on a route, on a router, at the point a router is
included, or on `New` for the whole application. The narrower declaration wins, whether it
is shorter or longer, a negative value removes an inherited deadline, and zero leaves the
inherited one as it is.
## A cooperative deadline
The deadline is set on the request's context, `ctx.Context()`, after a rate limit counted
before the dependencies and before anything the route itself runs: the security schemes it
enforces, the body `CaptureBody` keeps, its dependencies and the binding of its input.
Guards, providers, the handler and everything they pass the context to see it:
```go
func GetReport(ctx *muzak.Context, in schemas.ReportParams) (schemas.ReportOut, error) {
// The query gives up when the route's deadline passes, and its error
// comes back here.
rows, err := db.QueryContext(ctx.Context(), reportQuery, in.ID)
if err != nil {
return schemas.ReportOut{}, err
}
defer rows.Close()
// ...
}
```
Nothing that does not watch the context is interrupted. There is no second goroutine running
the handler while the first one writes a 503, which is how timeout middleware usually works
and why it usually races: the handler keeps running, keeps the request's resources, and can
still write into a response that was already answered. A Muzak handler always finishes on its
own goroutine, with its `*muzak.Context` to itself.
## What the client receives
| The route | The client gets |
|---|---|
| Fails with an error caused by the deadline, before the response started | `503` with `Retry-After: 1`, through the application's error renderer |
| Fails with an error that carries its own status, `muzak.GatewayTimeout(...)` say | That status |
| Fails because of the deadline after the response started | An aborted connection, as for any failure once a response has started |
| Ignores the deadline and returns successfully | Its success, however late |
| Fails because the client left, or a shorter deadline of the handler's own passed | What that error renders as, not a 503 |
An error is caused by the deadline when `errors.Is` reports it as `context.DeadlineExceeded`
and the deadline that passed is the route's own. That second condition is what keeps a client
that disconnected, or a `context.WithTimeout` the handler set for one call, from being reported
as the route running out of time. The cause is logged; the client is told only that the request
took longer than the operation allows:
```json
{
"error": {
"code": "service_unavailable",
"message": "the request took longer than this operation allows; try again shortly",
"status": 503
},
"request_id": "0192a7c1-..."
}
```
**A success is sent, however late.** A handler that ignores its context and returns a value has
done its work, and throwing the result away would only make the client repeat it. The deadline
is a budget the handler is asked to respect, not one the framework can enforce without the
second goroutine it refuses to start.
The exception is work that was undone underneath the handler. A request's `Transaction` is
rolled back by `database/sql` the moment the deadline passes, so a handler that carries on and
succeeds has nothing left to commit, and is answered with the 503 rather than a success whose
writes were thrown away. See [Dependencies](/docs/getting-started/dependencies).
**503, not 504.** A `504 Gateway Timeout` says a gateway's upstream did not answer, which sends
whoever reads it to look at a proxy. A `503` with a `Retry-After` says this server could not
answer in time, and when to try again. A route with a deadline documents the 503 in the
OpenAPI document, unless it declares a 503 of its own with `WithResponseDoc`.
## Event streams and WebSockets
A stream lasts as long as its connection, so a deadline on it would be a deadline on the
conversation. `Timeout` declared directly on an `SSE` or `WS` route is a build error that names
the option that bounds a stream instead:
```
muzak: SSE GET /events: Timeout cannot be declared on a route whose response lasts as long as its connection; bound it with SSEOptions.MaxLifetime instead
```
A deadline inherited from a router is not applied to the streams beneath it, so a router can
carry both, and `Timeout(-1)` is always allowed. See
[Server-Sent Events](/docs/realtime/server-sent-events#ending-a-stream-on-purpose) and
[WebSockets](/docs/realtime/websockets#ending-a-connection-on-purpose).
## Mounted handlers
A handler served with `Router.Mount` writes its own response and may be streaming one, so it is
treated the same way. A `Timeout` given to `Mount` is a build error:
```
muzak: mount at "/legacy": Timeout cannot be declared on a mount, whose handler writes its own response; give the handler a deadline of its own, with http.TimeoutHandler for one
```
and one inherited from a router is not applied to the mounted handler. See
[Mounting Handlers](/docs/techniques/mounting-handlers).
## Next to the server's timeouts
`Timeout` is not `WriteTimeout`. The server's `WriteTimeout` still bounds how long a response
may take to write and closes the connection when it passes, so a route deadline longer than
`WriteTimeout` is cut short by it, with no 503. Keep route deadlines below it, or raise it for
the routes' sake. See [Server Configuration](/docs/deployment/server-configuration#timeouts).
A background task registered with `AfterResponse` does not inherit the deadline: it keeps the
request's values but not its cancellation. See
[Background Tasks](/docs/techniques/background-tasks).
## Cost
A route without a deadline pays nothing for the option existing: no context, no timer, no
copy of the request. A route with one pays for one context with a timer and one shallow copy of
the `*http.Request`, whatever the size of its body.
## Where to go next
[Dependencies](/docs/getting-started/dependencies) covers the providers that run under the
deadline, and [Error Handling](/docs/getting-started/error-handling) the renderer the 503 goes
through.
--------------------------------------------------------------------------------
title: "HTTP Client"
description: "An outbound client that refuses private and metadata addresses at the moment of connecting, bounds every wait and every body, retries only what is safe to send twice, and carries the request id along."
version: "0.3.0"
last_updated: "2026-10-10T07:19:43.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/http-client"
--------------------------------------------------------------------------------
# HTTP Client
An application that fetches a URL someone else chose, a webhook target, an avatar, an
import link, is one request away from fetching `http://169.254.169.254/` on its own
behalf. `muzak.NewClient` builds the client to make those calls with: a `net/http` client
with the decisions that make it safe already made.
```go
client := muzak.NewClient(muzak.ClientOptions{})
defer client.Close()
```
The zero options are the strict ones. Loopback, private, link-local and metadata addresses
are refused, at most five redirects are followed and never from https down to http, at
most ten mebibytes of a response are read, a call gives up after thirty seconds, and a
request is retried only when sending it twice is harmless.
## Making a request
`Client.Do` takes an ordinary `*http.Request` and behaves as `http.Client.Do` does, except
where safety calls for something else. The helpers decode JSON for the common case.
::code-group
```go [core/clients.go]
// Upstream is the client every handler calls other services with. One client
// for the whole application, because it holds the pool of open connections.
var Upstream = muzak.NewClient(muzak.ClientOptions{})
// UpstreamLifecycle releases the client's idle connections on shutdown.
var UpstreamLifecycle = muzak.NewLifecycle("upstream", nil,
func(context.Context) error { return Upstream.Close() })
```
```go [routers/previews.go]
type PreviewIn struct {
URL string `query:"url"`
}
func (in *PreviewIn) Validate(v *muzak.Validation) {
// A syntax check, not a safety one: whether the address may be fetched
// is decided by the client, at the moment it connects.
v.String(&in.URL).Required().HTTPS()
}
type PageMeta struct {
Title string `json:"title"`
}
func Preview(ctx *muzak.Context, in PreviewIn) (PageMeta, error) {
meta, err := core.Upstream.GetJSON[PageMeta](ctx.Context(), in.URL)
var refused *muzak.AddressRefusedError
if errors.As(err, &refused) {
return PageMeta{}, muzak.BadRequest("that address cannot be fetched")
}
return meta, err
}
```
```go [cmd/main.go]
app := muzak.New(muzak.AppOptions{Title: settings.AppName},
muzak.WithLifecycle(core.UpstreamLifecycle),
)
```
::
Passing `ctx.Context()` matters twice over: the call ends when the request it serves ends,
and the request id the `RequestID` middleware assigned goes along in `X-Request-Id`, with
the trace context when the application traces requests (see
[Propagation](#propagation)).
Any other error from `Do` is safe to return from a handler as it is, and renders as an
opaque 500. Its message names the method and the origin, `GET https://api.example.com`,
and never the path or the query string, which is where URLs carry their secrets.
## What is refused
Every address the client is about to connect to is checked, on the socket, at the moment of
connecting. It is not checked when the URL is read, because that is not the address that
matters: a name can resolve somewhere else by the time it is fetched.
| Refused | Ranges | Opened by |
|---|---|---|
| Loopback and unspecified | `127.0.0.0/8`, `0.0.0.0/8`, `::1`, `::` | `AllowPrivateNetworks` |
| Private | `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7`, local-use NAT64 `64:ff9b:1::/48` | `AllowPrivateNetworks` |
| Link-local IPv6 | `fe80::/10` | `AllowPrivateNetworks` |
| Shared and reserved | CGNAT `100.64.0.0/10`, benchmarking `198.18.0.0/15` and `2001:2::/48`, `240.0.0.0/4`, broadcast, multicast, IETF assignments `192.0.0.0/24`, the old 6to4 relays `192.88.99.0/24` | `AllowPrivateNetworks` |
| Documentation | `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32`, `3fff::/20` | `AllowPrivateNetworks` |
| Everything outside IPv6 global unicast | anything not in `2000::/3`, plus Teredo, ORCHID, discard-only | `AllowPrivateNetworks` |
| Cloud metadata | all of IPv4 link-local `169.254.0.0/16`, `168.63.129.16` (Azure), `100.100.100.200` (Alibaba), `192.0.0.192` (Oracle), `fd00:ec2::254` and `fd00:ec2::23` (AWS), `fd20:ce::254` (Google) | only an `AllowedNetworks` entry |
An IPv6 address that delivers to an IPv4 one is judged by both, so `[::ffff:127.0.0.1]`,
`[64:ff9b::7f00:1]` (NAT64), `[2002:7f00:1::]` (6to4), `[::ffff:0:7f00:1]` (the
IPv4-translated form of SIIT) and `[::127.0.0.1]` are refused with the address they reach. The local-use NAT64 block `64:ff9b:1::/48` belongs to a network's own
translator, which places the IPv4 address in one of several layouts the client cannot see.
It is refused as a private range is, and an address in it is read in every layout a
translator may use, so a metadata service or a network in `DeniedNetworks` stays refused
through it even with `AllowPrivateNetworks` set.
A host that browsers and the C resolver read as an IPv4 address and Go reads as a name is
refused whatever it points at: `127.1`, `0177.0.0.1`, `0x7f.0.0.1`, `2130706433`. A check
and a fetch that disagree about what a host is are how request forgery filters are usually
got around, so the client does not guess. `localhost` and every name under it are refused
with loopback.
A refusal is an `*muzak.AddressRefusedError` naming the host, the address and what it is.
Nothing was sent, and it is never retried.
### Names, rebinding and redirects
The check runs in the dialer, which is the one place every connection is opened, so:
- a name that resolves to a private address is refused when it is dialled;
- a name that resolves to a public address and then, the second time it is asked, to the
metadata service, which is what DNS rebinding is, is refused on the second connection;
- a name that resolves to several addresses is connected only to the ones that pass, in the
resolver's order;
- a redirect, however many hops in, meets the same check, and so does every retry.
### Calling your own services
Service-to-service calls inside one network are what `AllowPrivateNetworks` is for. It never
opens a metadata service, which holds the credentials of the machine the client runs on.
```go
// Calls to the inventory service, inside the cluster. Only that subnet.
inventory := muzak.NewClient(muzak.ClientOptions{
AllowedNetworks: []netip.Prefix{netip.MustParsePrefix("10.20.0.0/16")},
})
// Calls to any internal service, but never to the database subnet.
internal := muzak.NewClient(muzak.ClientOptions{
AllowPrivateNetworks: true,
DeniedNetworks: []netip.Prefix{netip.MustParsePrefix("10.30.0.0/16")},
})
```
`DeniedNetworks` wins over everything, `AllowedNetworks` over everything else. Keep a
strict client for URLs that came from outside and a relaxed one for your own configuration,
rather than one relaxed client for both. A prefix that is not valid panics in `NewClient`,
because a list with a hole in it does not mean what it says.
### Behind an egress proxy
The client never reads `HTTP_PROXY`. A proxy decides where requests go, and an environment
variable is a setting anything that can set one controls. Name it instead:
```go
egress, _ := url.Parse("http://egress.internal:3128")
client := muzak.NewClient(muzak.ClientOptions{Proxy: egress})
```
The proxy is connected to without the address checks, and is trusted to apply its own: it is
the proxy that resolves the names it is asked for. The client still refuses what it can
judge without resolving anything, a refused address written literally, a localhost name, a
name ending in a number, and a name outside ASCII, which `net/http` would map before the
proxy saw it. A proxy that enforces no egress policy of its own reopens every request
forgery the client otherwise closes.
## Bounds
| Bound | Default | Field |
|---|---|---|
| The whole call: every attempt, redirect and wait, and reading the body | 30 seconds | `Timeout` |
| Resolving and connecting | 10 seconds, shared between a name's addresses | `DialTimeout` |
| TLS handshake | 10 seconds | `TLSHandshakeTimeout` |
| Waiting for the response header | 20 seconds | `ResponseHeaderTimeout` |
| Response body | 10 MiB, counted after decompression | `MaxResponseBytes` |
| Response header | 1 MiB | not configurable |
| Redirects | 5 | `MaxRedirects` |
| Attempts | 3, the first included | `MaxAttempts` |
| Addresses tried for one name | 16 | not configurable |
| TLS | 1.2 or later; a lower `MinVersion` is raised | `TLSConfig` |
A negative timeout removes that bound and leaves the request's context in charge. The body
limit cannot be removed, only raised. A response that declares a `Content-Length` over the
limit is refused by `Do` with `muzak.ErrResponseTooLarge` before any of it is read; one that
declares none, or is compressed, fails with the same error on the read that passes it, so
a gzip body that expands a thousandfold stops at the limit.
`Timeout` keeps running after `Do` returns, until the body is closed or read to its end.
Close every body, as with `net/http`.
## Redirects
A redirect is followed only to an address the client would have connected to directly,
never from https to plain http, and at most `MaxRedirects` times. `MaxRedirects: -1`
follows none and hands back the redirect itself, `Location` and all.
When a redirect leaves the origin the request was sent to, `Authorization`, `Cookie`,
`Proxy-Authorization` and every header in `SensitiveHeaders` are removed, and so is the
`Referer` net/http would otherwise add. An origin is the scheme, host and port together,
so a subdomain, another port and an upgrade from http to https all count as leaving it,
which is stricter than `net/http`. Once one hop has left, the headers stay off for the rest
of the chain, so a host passed through cannot send the request back to the origin, with
the credentials, at a path of its choosing.
```go
client := muzak.NewClient(muzak.ClientOptions{
SensitiveHeaders: []string{"X-Api-Key"},
})
```
The headers are what is removed, not the body. A `307` or `308` asks for the same request
again, body included, and the client follows it to another origin as `net/http` does, so a
request body goes wherever such a redirect points, as long as the address passes. For a call
whose body must reach one origin and no other, set `MaxRedirects: -1` and judge the redirect
yourself.
## Retries
A request is retried only when sending it twice is harmless: `GET`, `HEAD`, `OPTIONS`,
`PUT` and `DELETE`, and any request carrying an `Idempotency-Key` header (or
`X-Idempotency-Key`, which `net/http`'s own transport also honours). It is retried
after a connection that failed or broke, and after `429`, `502`, `503` and `504`. When the
attempts run out, the last response is returned as it is, for the caller to read.
What is never retried: a `POST` or `PATCH` without an idempotency key, a request whose body
cannot be read twice (it has no `GetBody`, which `http.NewRequest` sets for a
`bytes.Reader`, `bytes.Buffer` or `strings.Reader`), a refused address, a refused redirect,
an open circuit, a certificate that does not verify, a TLS alert, a name that does not
exist, and a call whose context has ended.
```go
req, _ := http.NewRequestWithContext(ctx.Context(), http.MethodPost, chargesURL, bytes.NewReader(body))
req.Header.Set("Content-Type", "application/json")
// The payment provider deduplicates on this key, so a retry cannot charge twice.
req.Header.Set("Idempotency-Key", order.ID)
charge, err := client.DoJSON[Charge](req)
```
The wait between attempts is random, between zero and a ceiling that starts at
`RetryBaseDelay` (100 ms) and doubles up to `RetryMaxDelay` (2 s). Drawing the whole wait
at random is what keeps a thousand clients that failed together from retrying together.
### Retry-After
A `Retry-After` header, in seconds or as an HTTP date, is a floor on the wait. One that asks
for longer than `MaxRetryAfter` (10 s) is not waited out: the response is returned, since
retrying sooner than the server asked is what it asked not to have. A wait that would
outlast the call's deadline is not slept either; the response is returned at once rather
than after the deadline has been spent sleeping. A date in the past means now, and a number
too large to represent is treated as a very long wait rather than wrapping into a negative
one.
### The retry budget
Retries are what turn an upstream's bad minute into its bad hour: every failing request
becomes three, and the load that made it fail triples. The client keeps a bucket of retry
tokens. Every response that is not a server error earns a tenth of one, every retry spends
one, and a retry with no token to spend is not made. It starts with ten and holds at most
ten.
```go
client := muzak.NewClient(muzak.ClientOptions{
RetryBudget: muzak.RetryBudget{Ratio: 0.2, Burst: 20},
})
```
`MaxAttempts: 1` turns retrying off altogether.
## Circuit breaker
A host that is down answers slowly or not at all, and every caller waiting on it holds a
goroutine and a connection for as long as the timeout allows. The breaker is off until it is
given a threshold:
```go
client := muzak.NewClient(muzak.ClientOptions{
CircuitBreaker: muzak.CircuitBreakerOptions{Threshold: 5, Cooldown: 30 * time.Second},
})
```
After `Threshold` failures in a row to one host, a connection error, a timeout or a `5xx`,
requests to that host fail at once with `muzak.ErrCircuitOpen` for `Cooldown`. Then one
request is let through: success closes the circuit, failure opens it for another cooldown,
and every other request is refused while that one is out. A caller cancelling its own
request is not a failure; a deadline passing is, since a host that hangs is the one a
breaker is most for.
A host is a scheme, a name and a port, and each step of a redirect counts against the host
it reached. Only failing hosts are remembered, at most `MaxHosts` (1024) of them, the least
recently used forgotten first, so calling ten thousand hosts cannot grow the table.
## Propagation
Every request is passed through `ClientOptions.Propagate` once before it is sent. The
default, `muzak.DefaultPropagate`, copies the request id from the context into
`X-Request-Id`, so that the logs of two services can be joined on it, and leaves a header
the caller set alone. An id that holds a control character or is longer than 256 bytes is
left out rather than failing the call. When the application traces requests, it also writes
the W3C `traceparent` and `tracestate` of the current span with `muzak.InjectTraceContext`,
so the service called records its work as part of the same trace; a `traceparent` the
caller set is left alone, and a request that is not traced sends none. See
[Observability](/docs/fundamentals/observability).
```go
client := muzak.NewClient(muzak.ClientOptions{
Propagate: func(ctx context.Context, h http.Header) {
muzak.DefaultPropagate(ctx, h)
h.Set("X-Tenant", tenantFrom(ctx))
},
})
```
A function that does nothing turns propagation off. Whatever a propagator adds is checked
like any other header. On a call made with a typed endpoint's `Call`, a propagator may fill a
header the input binds and left empty, but one that changes a header the input set refuses
the call; see [Typed Endpoints](/docs/techniques/typed-endpoints).
`DefaultPropagate` adds its headers to every request, whoever the URL names. Neither header
is a secret, but both let the receiver join its records to yours, and a `traceparent` says
whether you are sampling. A client that fetches URLs from outside, a webhook target or an
avatar, should not hand them to whoever chose the URL: give that client a `Propagate` that
adds nothing, and keep the default for the clients that call your own services.
```go
// Fetches URLs users supply. Nothing about our own requests goes with them.
fetcher := muzak.NewClient(muzak.ClientOptions{
Propagate: func(context.Context, http.Header) {},
})
```
## Headers
A header value holding a carriage return, a line feed or a NUL is refused before anything
is sent, and so is a header name that is not a token. That is how a value that came from
outside, a forwarded token or an identifier, would otherwise write a header of its own. The
error names the header and never repeats its value.
## JSON
| Method | Sends | Returns |
|---|---|---|
| `client.GetJSON[T](ctx, url)` | `GET` with `Accept: application/json` | the decoded `T` |
| `client.PostJSON[T](ctx, url, body)` | `POST` of `body` as JSON | the decoded `T`; never retried |
| `client.DoJSON[T](req)` | your request, `Accept` added if missing | the decoded `T` |
A status that is not `2xx` is an `*muzak.RemoteError` carrying the status, the header and
the first 64 KiB of the body. When the body is the error envelope a Muzak application writes,
the default one or a problem details document, its `Code`, `Message`, `Details` and
`RequestID` are filled in, and `Code` is what to branch on. The body is read as an envelope
only under a JSON media type, whole or not at all, keeping at most a hundred details, so a
truncated or malformed body leaves those fields empty rather than half filled. Its message is
the method, origin and status, `muzak: GET https://api.example.com answered with status 404
(not_found)`, naming the code only when it is a plain identifier of at most 64 bytes, and
never the body or the message, which are the other server's text. Handle it with
`errors.As` and the `StatusCode` or `Code`, not by matching the message.
```go
item, err := client.GetJSON[Item](ctx.Context(), itemURL)
var remote *muzak.RemoteError
if errors.As(err, &remote) && remote.Code == "not_found" {
return Item{}, muzak.NotFound("no such item upstream")
}
```
A success not labelled as JSON is refused rather than
guessed at, which is how an HTML error page from a proxy announces itself. `204` and `HEAD`
decode to the zero `T`. Members `T` does not have are ignored, as a client reading another
service's answers should; duplicate members and invalid UTF-8 are refused.
## Errors
| Error | Test with | Meaning |
|---|---|---|
| `*muzak.AddressRefusedError` | `errors.As` | The address is one the policy refuses. Nothing was sent |
| `muzak.ErrResponseTooLarge` | `errors.Is` | The body passed `MaxResponseBytes` |
| `muzak.ErrCircuitOpen` | `errors.Is` | The host's circuit is open. Nothing was sent |
| `*muzak.RemoteError` | `errors.As` | A JSON helper, or a typed endpoint's `Call`, got a status that is not `2xx` |
| `context.DeadlineExceeded` | `errors.Is` | `Timeout`, or the context's own deadline, passed |
| `context.Canceled` | `errors.Is` | The context was cancelled |
## Shutting down
`Close` releases the idle connections and does not stop the client: a request made
afterwards opens a connection again, which is what lets a `Lifecycle`'s `Stop` call it while
a late request is still finishing.
## Testing code that calls out
A test server from `httptest` listens on `127.0.0.1`, which a strict client refuses. Build
the client the code under test uses from options the test can set:
```go
func TestPreview(t *testing.T) {
upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write([]byte(`{"title":"Plumbus"}`))
}))
defer upstream.Close()
client := muzak.NewClient(muzak.ClientOptions{AllowPrivateNetworks: true})
defer client.Close()
meta, err := client.GetJSON[PageMeta](t.Context(), upstream.URL)
// ...
}
```
Keep `AllowPrivateNetworks` out of the production configuration of a client that fetches
URLs from outside, and test the refusal too: a URL of `http://127.0.0.1/` must come back as
an `*muzak.AddressRefusedError`. [Testing](/docs/fundamentals/testing) covers testing the
application's own routes.
The same applies to a JWT bearer scheme's key set, which is fetched through a client built
here with the strict defaults. An identity provider on a private network, or a test server,
needs `JWKSOptions.Client` set to a client with `AllowPrivateNetworks` or an
`AllowedNetworks` entry; see [Authentication](/docs/security/authentication).
## Limits
- A NAT64 translator configured with a prefix of the network's own choosing, outside
`64:ff9b::/96` and `64:ff9b:1::/48`, is invisible to the client: its addresses look like
any public IPv6 address. If your network has one, list that prefix in `DeniedNetworks`.
- A `307` or `308` that leaves the origin is followed with the request body, as described
under [Redirects](#redirects).
- `DefaultPropagate` sends the request id and the trace context to any URL, as described
under [Propagation](#propagation).
## Options reference
| Field | Default | Effect |
|---|---|---|
| `AllowPrivateNetworks` | off | Connect to loopback, private and the other special-purpose ranges. Never opens metadata |
| `AllowedNetworks` | none | Prefixes reachable whatever else says, metadata included |
| `DeniedNetworks` | none | Prefixes never reachable, whatever else says |
| `Proxy` | none, and never from the environment | Send every request through this http, https or socks5 proxy, trusted to enforce egress |
| `TLSConfig` | system roots, TLS 1.2 minimum | Cloned; a lower `MinVersion` is raised to 1.2 |
| `Timeout` | `DefaultClientTimeout`, 30 seconds | The whole call, body included. Negative removes it |
| `DialTimeout` | `DefaultClientDialTimeout`, 10 seconds | Resolving and connecting. Negative removes it |
| `TLSHandshakeTimeout` | `DefaultClientTLSHandshakeTimeout`, 10 seconds | Negative removes it |
| `ResponseHeaderTimeout` | `DefaultClientResponseHeaderTimeout`, 20 seconds | Negative removes it |
| `MaxResponseBytes` | `DefaultClientMaxResponseBytes`, 10 MiB | Decompressed body size |
| `MaxRedirects` | `DefaultClientMaxRedirects`, 5 | Negative returns redirects unfollowed |
| `SensitiveHeaders` | none beyond the three built in | Dropped when a redirect leaves the origin |
| `MaxAttempts` | `DefaultClientMaxAttempts`, 3 | 1 turns retrying off |
| `RetryBaseDelay`, `RetryMaxDelay` | 100 ms, 2 s | The doubling ceiling of the random wait |
| `MaxRetryAfter` | `DefaultClientMaxRetryAfter`, 10 seconds | Longest `Retry-After` waited out |
| `RetryBudget` | `Ratio` 0.1, `Burst` 10 | Retries earned per success and banked |
| `CircuitBreaker` | off | `Threshold`, `Cooldown` (30 s), `MaxHosts` (1024) |
| `Propagate` | `DefaultPropagate` | Adds headers from the context to every request: the request id, and the trace context when tracing is on |
| `BaseURL` | none | The root a typed endpoint's `Call` sends to. An absolute http or https URL with no query, fragment or user information, or `NewClient` panics. `Do` and the JSON helpers never read it |
`NewClient` panics on options that cannot mean what they say: an invalid prefix in
`AllowedNetworks` or `DeniedNetworks`, a `Proxy` with no host or a scheme no proxy speaks, and
a `BaseURL` that is not a base.
## Where to go next
[Typed Endpoints](/docs/techniques/typed-endpoints) covers calling another Muzak service with
the server's own types through this client,
[Safe Defaults](/docs/security/safe-defaults) lists every other default and how to relax it,
[Lifecycle](/docs/getting-started/lifecycle) covers closing the client on shutdown,
[Logging](/docs/fundamentals/logging) covers the request id the client carries along, and
[Observability](/docs/fundamentals/observability) covers the trace it continues.
--------------------------------------------------------------------------------
title: "Typed Endpoints"
description: "Declare an operation once, in a package the service and its Go callers share, and let the compiler hold both sides to it. A call writes its input as the exact request the binder reads back."
version: "0.3.0"
last_updated: "2026-10-10T06:35:15.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/typed-endpoints"
--------------------------------------------------------------------------------
# Typed Endpoints
When one Go service calls another, the request and the response are described twice: once
by the handler that serves them, and once by the code that builds the URL, sets the headers
and decodes the answer. The two drift. A query parameter is renamed on one side, a field
moves from the body to a header, and the first thing that notices is production.
`muzak.NewEndpoint` declares an operation once, as a value: its method, its path template,
the route options that describe it, and its `In` and `Out` types. The service implements it
with `Router.Implement`, its callers call it with `Endpoint.Call`, and both sides are typed
by the same declaration.
::code-group
```go [userapi/userapi.go]
// Package userapi is imported by the users service and by everything that
// calls it. It holds the shapes and the endpoints, and nothing else.
package userapi
type GetUserIn struct {
ID string `path:"id"`
Expand []string `query:"expand"`
Tenant string `header:"X-Tenant"`
}
type User struct {
ID string `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
}
var GetUser = muzak.NewEndpoint[GetUserIn, User](http.MethodGet, "/users/{id}",
muzak.Summary("Fetch a user"),
muzak.WithTags("users"))
```
```go [users/routers/users.go]
func NewRouter() *muzak.Router {
r := muzak.NewRouter()
r.Implement(userapi.GetUser, handlers.GetUser)
return r
}
```
```go [orders/core/clients.go]
var Users = muzak.NewClient(muzak.ClientOptions{
AllowPrivateNetworks: true,
BaseURL: settings.UsersURL, // "http://users.internal:8080"
})
```
```go [orders/handlers/orders.go]
func GetOrder(ctx *muzak.Context, in OrderIn) (OrderOut, error) {
user, err := userapi.GetUser.Call(ctx.Context(), core.Users,
userapi.GetUserIn{ID: in.UserID, Tenant: in.Tenant})
if err != nil {
return OrderOut{}, err
}
return OrderOut{Customer: user.Name}, nil
}
```
::
## Implementing an endpoint
`Router.Implement` registers the handler exactly as `Router.Handle` with the endpoint's
method and path would: the same route, the same binding, the same document. The endpoint's
own route options apply first and the ones given to `Implement` after them, so a guard, a
rate limit or a timeout that belongs to this deployment is added where the endpoint is
implemented, and the summary and tags that belong to the operation travel with it.
```go
r.Implement(userapi.GetUser, handlers.GetUser,
muzak.WithDependencies(core.RequireServiceToken),
muzak.Timeout(2*time.Second))
```
The path is relative to wherever the endpoint is implemented. A router included under
`WithPrefix("/v1")` serves it at `/v1/users/{id}`, and its callers put `/v1` at the end of
their `BaseURL`.
### What the compiler catches
The handler's types are the endpoint's. Every one of these is a compile error rather than a
route that disagrees with its callers:
```go
// The handler takes another input type.
r.Implement(userapi.GetUser, func(ctx *muzak.Context, in OtherIn) (userapi.User, error) { ... })
// in call to r.Implement, type func(ctx *muzak.Context, in OtherIn) (userapi.User, error)
// does not match inferred type muzak.Handler[userapi.GetUserIn, userapi.User]
// The handler returns another output type.
r.Implement(userapi.GetUser, func(ctx *muzak.Context, in userapi.GetUserIn) (Profile, error) { ... })
// in call to r.Implement, type func(...) (Profile, error) does not match inferred type
// muzak.Handler[userapi.GetUserIn, userapi.User]
// A caller passes the wrong input.
userapi.GetUser.Call(ctx, users, OtherIn{ID: "42"})
// cannot use OtherIn{...} as userapi.GetUserIn value in argument to userapi.GetUser.Call
// A caller expects the wrong output.
var p Profile
p, err = userapi.GetUser.Call(ctx, users, userapi.GetUserIn{ID: "42"})
// cannot use 1st function result (value of struct type userapi.User) as Profile value
// An endpoint converted to another pair of types.
other := muzak.Endpoint[OtherIn, userapi.User](userapi.GetUser)
// cannot convert userapi.GetUser (variable of struct type muzak.Endpoint[userapi.GetUserIn,
// userapi.User]) to type muzak.Endpoint[OtherIn, userapi.User]
```
The last one is closed on purpose. Every `Endpoint[In, Out]` would otherwise share one
underlying struct type, and Go allows a conversion between two such types, which would hand
an endpoint compiled for one input type to a call passing another.
### Mistakes in the declaration
An endpoint is usually a package-level variable, and a panic while packages initialise stops
the program before it can say which declaration was wrong. So `NewEndpoint` checks the
method and the path when it is called, by the rules the router holds a route to, and records
what it finds. A mistake is a build error of the application that implements the endpoint,
joined with every other, and the error every call returns.
The input type is checked when the endpoint is implemented, as any route's is, and again on
the first call, for what writing it as a request needs. A type the server binds but a call
cannot write, such as one with `UnmarshalText` and no `MarshalText`, fails every call with
an error saying what to change. A panic while that plan is compiled, such as a `Validate`
method that panics on the zero input, is the panic of every call alike, never of the first
call only.
## Calling an endpoint
`Endpoint.Call` sends the input to the endpoint at the client's `BaseURL` and returns what
the handler answered, decoded into `Out`.
```go
user, err := userapi.GetUser.Call(ctx.Context(), core.Users, userapi.GetUserIn{ID: "42"})
```
The client is an ordinary `muzak.NewClient`, with everything that comes with one: address
checks at the moment of connecting, bounded waits and bodies, retries only for what is safe
to send twice, a circuit breaker if you turn one on, and the request id carried along. A
service calling its own network sets `AllowPrivateNetworks`, or names its subnets in
`AllowedNetworks`.
`ClientOptions.BaseURL` is the root of the service, such as `http://users.internal:8080` or
`https://api.example.com/v1`. It lives on the client because a client is built per service:
it holds that service's connection pool and circuit breaker. It must be an absolute http or
https URL with a host and nothing after its path; a query, a fragment or user information
panics in `NewClient`, because each would be sent with every call. `Client.Do` and the JSON
helpers take absolute URLs and never read it.
### How the input is written
A call writes its input as the exact inverse of binding. The plan it follows is compiled, on
the first call, from the binder's own plan for the same type, so the two cannot disagree
about which field comes from where.
| Location | How a value is written |
|---|---|
| `path` | Escaped segment by segment; a trailing `{name...}` parameter may hold `/` |
| `query` | Once, or once per entry for a list, with every byte escaped |
| `header` | As it is; a list is one line of entries separated by `, ` |
| `cookie` | As it is, quoted when it holds a space or a comma |
| JSON body | The body members alone, never a located field or a `Dep` |
| `form`, `file` | `multipart/form-data`, a value or a `[]byte` file per part |
Numbers are written in the decimal grammar the binder reads, the shortest that reads back as
the same value. A `time.Duration` is written as `1500ms`, and a `time.Time`, a `uuid.UUID`
or any type that reads itself with `UnmarshalText` writes itself with `MarshalText`.
An input that decodes its body itself, with an `UnmarshalJSON` of its own, is still written
from its body members alone. Its located fields are left out of the body, so an
`Authorization` or a session cookie it binds goes in its header or cookie and never into a
body that may be logged and kept.
An input that binds a header net/http writes itself, or that frames the request, cannot be
called: `Host`, `Content-Length`, `Transfer-Encoding`, `Connection`, `Keep-Alive`,
`Proxy-Connection`, `TE`, `Trailer`, `Upgrade`, `Accept-Encoding`, and `Cookie`, which is
what the `cookie` tag is for. `Content-Type` may be bound by an input that has no body. A
`User-Agent` or an `Accept` the input binds and leaves out arrives absent, rather than as
the one net/http or the call would otherwise write.
Headers `ClientOptions.Propagate` adds, the request id and the trace context with the
default, are added after the input is written. A field bound to one of them that the input
leaves out, a nil pointer or an empty list, receives the propagated value. A header the
input did set and `Propagate` changes refuses the call with `ErrCallRefused`, since the
server would not read the input's value: a `Propagate` of your own should leave a header
that is already set alone, as `muzak.DefaultPropagate` does. A non-pointer field is always
set, even when it is empty.
A form is always sent as multipart, which every method can carry, and a `[]byte` file is a
part named after its field. A `muzak.File` field is what a handler receives and holds no
content a caller could set, so an input with one cannot be called: declare the field
`[]byte`, or `[][]byte` for several files.
### Values a request cannot carry
Some values have no request that carries them unchanged. They are refused before anything
is sent, with an error that wraps `muzak.ErrCallRefused` and names the field and the
reason, never the value, which may be a credential.
| Value | Why it is refused |
|---|---|
| An empty path parameter | The router never matches an empty segment |
| `.` or `..` as a path segment | Clients and proxies resolve them as steps through the path |
| `/` in a path parameter that is not a trailing `{name...}` | Muzak keeps `%2F` inside its segment, but some proxies decode it and route elsewhere, and others refuse it |
| An empty segment in a `{name...}` value | Proxies merge `//` and drop a trailing `/` |
| A header with a control character | A line break would end the header and write another |
| A header with a space or tab at either end | Every HTTP parser drops them |
| A header list entry that is empty, or holds a comma or an unbalanced quote | The server would read it as the edge of another entry |
| An empty `User-Agent` | net/http leaves an empty one out, so it would arrive absent |
| A cookie with a control character, `"`, `;`, `\` or a byte outside ASCII | The cookie parser drops it, and net/http would drop it with only a log line |
| A list of more than one value in a path parameter or a cookie | Each carries exactly one |
| A number that is not finite | The binder reads only decimal numbers |
| A body string that is not UTF-8 | The JSON decoder refuses it |
| A body member with a `default` that its json tag's `omitzero` or `omitempty` leaves out | The server would read the default in its place |
| A header given to `CallHeader` that the input binds or a call writes itself, or a value with a line break or a space at either end | Two values would compete, or the value would arrive altered |
```go
_, err := api.GetFile.Call(ctx, client, api.FileIn{Name: in.Name})
if errors.Is(err, muzak.ErrCallRefused) {
// The caller's input was at fault, not the upstream.
return Out{}, muzak.BadRequest("that is not a file name")
}
```
One value is not refused, because the client cannot see it: a path parameter that spells a
static route beside it. With `/users/me` and `/users/{id}` registered, a call with `ID: "me"`
reaches `/users/me`, as a browser would.
### Absent values
A nil pointer and an empty list are not sent, because a request has no way to spell them, so
the server reads them as absent: nil, or the default the field's tag declares. A zero value
that is not a pointer is sent, so a default never replaces a zero that was written on
purpose.
```go
type ListIn struct {
Limit int `query:"limit" default:"50"` // Limit: 0 arrives as 0
Cursor *string `query:"cursor"` // Cursor: nil arrives as nil
}
```
A body member is the one place a zero can be left out: a json tag with `omitzero` or
`omitempty` drops it from the body, and the server would then read the member's default.
So a body member that has a `default` and that its tag would leave out is refused with
`ErrCallRefused` rather than replaced by the default. Send a value the tag keeps, or a nil
pointer, or an empty list, when the default is what you mean.
```go
type CreateIn struct {
Name string `json:"name"`
Limit int `json:"limit,omitzero" default:"10"` // Limit: 0 is refused
}
```
A pointer is read for what it points at, so a non-nil pointer to a nil pointer, or to an
empty list, arrives as nil too. JSON has no nil slice or map either: a body member holding
one arrives empty rather than nil, and so does an output's.
### What comes back
| `Out` | What `Call` returns |
|---|---|
| A JSON type | The body, decoded with encoding/json/v2; members `Out` lacks are ignored, and a `204` is the zero value |
| `muzak.Bytes` | The body, its `Content-Type`, and the file name and `Download` of its `Content-Disposition` |
| `muzak.Stream` | The body unread, as an `io.ReadCloser` you must close, with the same header fields and `Length` when the server declared one |
| `muzak.Redirect` | The redirect itself, `To` and `Status`, which is not followed |
| `muzak.HTML` | The document |
| `muzak.Empty` | Nothing |
| `muzak.FileResponse` | Cannot be called: declare the endpoint with `muzak.Stream` |
A redirect is returned rather than followed because following it would answer with another
endpoint's output. Every body is bounded by `ClientOptions.MaxResponseBytes`. A success that
is not labelled as JSON, where `Out` is a JSON type, is an error rather than a guess, which
is how an HTML page from a proxy in the way announces itself.
The file name a server offers in `Content-Disposition` is that server's, and is cleaned as a
name Muzak sends is: a `/` or a `\` becomes `_`, and control characters, line breaks, double
quotes and the Unicode controls that make a name display other than it is are removed. A
name of `../../etc/passwd` arrives as `.._.._etc_passwd`, one name and never a path.
A `Stream` a handler receives from a call can be returned as its own, which passes the body on
without holding it; Muzak closes it once it is sent.
```go
func Download(ctx *muzak.Context, in DownloadIn) (muzak.Stream, error) {
return storageapi.Export.Call(ctx.Context(), core.Storage, storageapi.ExportIn{ID: in.ID})
}
```
### Errors
A status outside 2xx is a `*muzak.RemoteError`. Besides the status, the header and the start
of the body, it carries what the service's error envelope says, read from the default shape
or from problem details:
| Field | From the default envelope | From problem details |
|---|---|---|
| `Code` | `error.code` | `code` |
| `Message` | `error.message` | `detail`, or `title` |
| `Details` | `error.details` | `errors` |
| `RequestID` | `request_id` | `request_id` |
```go
user, err := userapi.GetUser.Call(ctx.Context(), core.Users, in)
var remote *muzak.RemoteError
if errors.As(err, &remote) && remote.Code == muzak.CodeNotFound {
return Out{}, muzak.NotFound("no such customer")
}
```
The body is another server's, so nothing about it is trusted. It is read only under a JSON
media type, kept to 64 KiB, decoded whole or not at all, and at most a hundred details are
kept. `RemoteError.Error()` names the method, the origin and the status, and the code when
it is a plain identifier of at most 64 bytes (letters, digits and `_ - . :`), so a hostile
body cannot write a line of its own into a log:
```
muzak: GET https://users.internal:8080 answered with status 404 (not_found)
```
Branch on `StatusCode` or `Code`, never on that message. `Message` and the issues in
`Details` are the remote server's text: do not hand them to your own clients as they are.
`Client.DoJSON`, `GetJSON` and `PostJSON` fill the same fields.
A failure to reach the service is returned as `Client.Do` returns it: an
`*muzak.AddressRefusedError`, a timeout, an open circuit, or the context's error.
## Call options
`muzak.CallHeader` adds a header the input does not bind, such as the `Authorization` a
guard reads, or the `Idempotency-Key` that makes a POST safe to retry.
```go
item, err := api.CreateItem.Call(ctx.Context(), client, in,
muzak.CallHeader("Authorization", "Bearer "+token),
muzak.CallHeader("Idempotency-Key", key))
```
A header the input binds is set through its field, and naming it here is refused, as are
`Host`, `Content-Length`, `Content-Type` and the other headers a call writes itself. A
`Cookie` given here is sent after the input's own cookies, so a cookie of the same name
cannot replace one the input binds. Headers every call needs, such as a tenant taken from the
context, belong in `ClientOptions.Propagate`.
`muzak.ValidateFirst` checks the input before it is sent, as the server checks it once it is
bound: required parameters, form fields and files, and the rules of an input that implements
`Validatable`. A failure is the `*muzak.ValidationError` the server would have answered `422`
with, and nothing is sent.
```go
_, err := api.CreateItem.Call(ctx.Context(), client, in, muzak.ValidateFirst())
```
It is off unless asked for, because the server is the authority on what it accepts. A
client built from an older version of the shared package holds that version's rules and
would refuse what the server now accepts, and a rule that reads a `Dep` reads its zero value
on the client. Turn it on where a round trip is worth saving and both sides ship together.
## What a call guarantees
The promise is tested as a property. For inputs covering every location, every scalar kind,
pointers, lists, embedded structs, types with their own text form, dependencies and
wildcards, with values full of `%`, `/`, `?`, `#`, spaces, Unicode and attempts at line
breaks, a call against a real server either delivers to the handler an input equal to the
one sent, or is refused with `ErrCallRefused` and never reaches the handler. Nothing in a
value can add a header, a cookie or a query parameter of its own. The property is fuzzed with
arbitrary bytes in every location.
The same encoder writes the arguments of an MCP tool call as the request its route reads, so
a route that can be served as a tool is held to the same rules; see
[MCP Tools](/docs/techniques/mcp-tools).
## Testing a call
A call is an ordinary HTTP request, so a test serves the application with `httptest` and
points a client at it. The test server listens on loopback, which a client refuses unless it
is told otherwise, so the client sets `AllowPrivateNetworks`:
```go
func TestGetUser(t *testing.T) {
server := httptest.NewServer(buildApp())
defer server.Close()
users := muzak.NewClient(muzak.ClientOptions{
AllowPrivateNetworks: true,
BaseURL: server.URL,
})
defer users.Close()
user, err := userapi.GetUser.Call(t.Context(), users, userapi.GetUserIn{ID: "42"})
if err != nil {
t.Fatal(err)
}
if user.ID != "42" {
t.Fatalf("got %q", user.ID)
}
}
```
For the server side alone, `testclient` is quicker; see [Testing](/docs/fundamentals/testing).
## Limits
- A path parameter that spells a static route beside it reaches that route, as described
above, since the client cannot see the server's other routes.
- A non-pointer header or cookie field is sent even when it is empty, so the server reads an
empty value rather than an absent one. Use a pointer for a value that may be absent.
- A `time.Time` arrives with the same instant and offset, in a fixed zone, not in the named
`Location` it was sent from.
- `ClientOptions.BaseURL` is not checked for dot or empty segments in its path. It is
operator configuration, and is sent as it is written.
- A `307` or `308` is followed with the body, to another origin too, as `Client.Do` follows
one for any request; credentials are dropped once a redirect leaves the origin, the body
is not. With `AllowPrivateNetworks` that origin may be another internal service, so name
the networks a client may reach in `AllowedNetworks` where that matters.
## Where to go next
[HTTP Client](/docs/techniques/http-client) covers the client a call is made with,
[Request Data](/docs/getting-started/request-data) the tags an input is bound by,
[Files, Streams and Redirects](/docs/techniques/files-streams-redirects) the outputs that
are not JSON, and [Error Handling](/docs/getting-started/error-handling) the envelope a
`RemoteError` reads. [TypeScript](/docs/fundamentals/typescript) generates the same API's
types for a frontend from the OpenAPI document.
--------------------------------------------------------------------------------
title: "MCP Tools"
description: "Serve a Model Context Protocol endpoint and let an MCP client call chosen routes as tools, each call served by the route itself with its security, guards, rate limits and validation intact."
version: "0.3.0"
last_updated: "2026-10-10T09:01:29.000Z"
source: "https://muzak.dev/docs/0.3.0/techniques/mcp-tools"
--------------------------------------------------------------------------------
# MCP Tools
`App.MCP` serves a [Model Context Protocol](https://modelcontextprotocol.io) endpoint. An MCP
client, such as a desktop assistant, an IDE agent or a model behind your own orchestration,
connects to it, lists the tools it offers and calls them. Each tool is a route you already have, described from
the OpenAPI document and called through the whole application, so a model gets exactly the
operations you chose, under exactly the rules an HTTP client gets them under.
::code-group
```go [main.go]
app := muzak.New(muzak.AppOptions{
Title: "Shop API",
Version: "2.1.0",
SecuritySchemes: map[string]muzak.SecurityScheme{
"oidc": muzak.JWTBearer(muzak.JWTOptions{
Issuers: []string{"https://login.example.com/"},
Audience: "https://api.example.com/mcp",
Algorithms: []string{"RS256"},
JWKS: muzak.JWKSOptions{URL: "https://login.example.com/.well-known/jwks.json"},
// Clients that know only the endpoint's URL discover the
// authorization server through this document.
ResourceMetadata: &muzak.ResourceMetadata{Resource: "https://api.example.com/mcp"},
}),
},
})
// The endpoint is a route like any other: its security, guards and rate limit
// apply to every message. Nothing is a tool until it is chosen.
app.MCP("/mcp", muzak.MCPOptions{
Tags: []string{"agent"},
Instructions: "Use get_order to look an order up before cancelling it.",
}, muzak.WithSecurity(muzak.Require("oidc")))
app.Include(routers.Orders(), muzak.WithPrefix("/v1"))
```
```go [routers/orders.go]
func Orders() *muzak.Router {
r := muzak.NewRouter(muzak.WithSecurity(muzak.Require("oidc")))
// Chosen by its tag.
r.Get("/orders/{id}", handlers.GetOrder,
muzak.WithTags("agent"),
muzak.OperationID("get_order"),
muzak.Title("Get Order"),
muzak.Summary("Fetch one order"))
// Chosen explicitly, whatever its tags.
r.Post("/orders/{id}/cancel", handlers.CancelOrder,
muzak.MCPTool(),
muzak.OperationID("cancel_order"),
muzak.Summary("Cancel an order that has not shipped"))
// Not a tool: an HTTP client can call it, a model cannot.
r.Delete("/orders/{id}", handlers.DeleteOrder)
return r
}
```
::
## Choosing tools
Nothing is exposed by default. A route becomes a tool in any of three ways, and they add up:
| Chosen by | How |
|---|---|
| The route | `muzak.MCPTool()` among its options |
| A tag | `MCPOptions.Tags` names one of the route's tags, its own or a router's |
| A rule | `MCPOptions.Include` returns true for the `*muzak.Route` |
`Include` is called once per route when the application is built, and only for routes that
can be tools; it cannot take back a route a tag or `MCPTool` chose, so a policy with exceptions
is written in `Include` alone.
Some things are never tools, however eagerly they are chosen: WebSocket and event stream
routes, `Hidden` routes, the endpoint itself, a method OpenAPI has no place for, and everything
that is not a route at all, `Mount`, `Static`, `Frontend`, the documentation and the health
endpoints. `MCPTool` is a route option, so it cannot be given to `Mount`, `Static` or
`Frontend` at all: it does not compile there. On a route that cannot be a tool, a WebSocket or
event stream route, a `Hidden` one, the endpoint itself or one whose method OpenAPI has no
place for, it is a build error naming the route, rather than an option quietly ignored.
An application without an MCP endpoint ignores `MCPTool` on every route, so a router shared by
applications with and without one can declare its tools once.
A chosen route that a tool call cannot write a request for is a build error too, naming the
route and the reason. A tool call writes its request as
[`Endpoint.Call`](/docs/techniques/typed-endpoints) does, so whatever `Call` refuses is refused
here: a `muzak.File` field (declare it `[]byte` or `[][]byte`), a header net/http writes
itself, and a route that answers with `muzak.FileResponse`. So is an input that binds a header
or cookie the endpoint forwards, such as `Authorization`, or a header a trusted proxy names the
client in, since its value comes from the client's own request and never from a model, and a
versioned route whose version is chosen by a custom extractor, which a call cannot satisfy.
Nor may an input bind any other place a credential is read from: the header, query parameter
or cookie of an API key scheme, whether the scheme verifies the key or only describes it, or
the cookie `AppOptions.Sessions` keeps the session in. Binding one is a build error naming the
route even when the endpoint does not forward it, so a model can never choose the credential a
call is made with, or present a key it read somewhere as its own.
## What a tool looks like
```json
{
"name": "get_order",
"title": "Get Order",
"description": "Fetch one order",
"inputSchema": {
"type": "object",
"properties": {
"path": {
"type": "object",
"properties": {"id": {"type": "string", "description": "The order's identifier"}},
"required": ["id"],
"additionalProperties": false
},
"query": {
"type": "object",
"properties": {"expand": {"type": "array", "items": {"type": "string"}}},
"additionalProperties": false
}
},
"required": ["path"],
"additionalProperties": false
},
"outputSchema": {"type": "object", "properties": {"id": {"type": "string"}, "total": {"type": "integer"}}, "required": ["id", "total"]},
"annotations": {"readOnlyHint": true}
}
```
| Member | Comes from |
|---|---|
| `name` | The operation id, with every character other than an ASCII letter, a digit, `_` or `-` replaced by `_`, cut to 64; two routes that end up with one name are a build error, so set `muzak.OperationID` to choose |
| `title` | `muzak.Title` |
| `description` | `muzak.Summary` and `muzak.Description` |
| `inputSchema` | The operation's parameters and request body in the OpenAPI document |
| `outputSchema` | The success response's JSON schema |
| `annotations` | The method: `GET`, `HEAD` and `OPTIONS` are read-only, `DELETE` destructive and idempotent, `PUT` idempotent |
The input is grouped by where the route reads it: `path`, `query`, `header` and `cookie` hold
the parameters by the names a request uses, `body` holds the JSON body, and `form` holds the
fields of a form, files as standard base64. Grouping is what keeps a path parameter and a body
member of the same name apart, and it is the shape the request takes. Every schema is the
document's own, with the same required members and the same rules, and every reference is
resolved within the tool: inlined, or written once under `$defs` for a type that contains
itself.
## Calling a tool
A call is the route's own request. The arguments are decoded into the route's input type by
the binder's own rules, defaults included, written as a request by the encoder
[`Endpoint.Call`](/docs/techniques/typed-endpoints) uses, and served in-process by the whole
application: middleware, the host allowlist, the security gate, guards, providers, the rate
limit, binding, validation and releases all run, and nothing is skipped because the caller is
a model.
Because the request is written by the rules `Call` writes one by, an argument `Call` would
refuse is refused here, as an error result. The one a model is likely to meet is a body member
with a `default` tag whose `json` tag carries `omitzero` or `omitempty`: set to its zero value,
it would be left out of the body and arrive as the default, so it is refused rather than
quietly replaced. Leaving the member out is how a call asks for the default.
The request a call writes is held to the smaller of two limits: the route's own body limit
(`MaxBodySize`, or `MaxUploadSize` for a route that takes files) and the endpoint's
`MaxBodySize`, which the arguments arrived under. Written out as a body, a few bytes of
arguments, such as a list of empty strings or empty objects, can be many times their size, so
arguments that would exceed the limit get an error result with status 413, and the route does
not run.
The request carries over from the MCP request only what has to:
| Carried | Why |
|---|---|
| `Authorization`, and `ForwardHeaders` and `ForwardCookies` | The client's credentials, unchanged |
| The client's address, TLS state and the headers a trusted proxy names it in | Rate limits, client IP and the HTTPS redirect see the real client |
| The request identifier | One `request_id` in both access log lines and in the tool's error envelope |
| The trace | The call's span is a child of the MCP request's |
| Cancellation and deadline | A client that disconnects stops the call; no other value of the MCP request's context is |
| `User-Agent`, `Accept-Language` | Unless the input binds them itself |
Nothing else is: no `Origin`, no session, no cookie the options do not name. A call reaches its
own route and no other. An argument that spells the path of another route, a static sibling of
a parameter or anything under a wildcard, is refused before the other route runs. Only routes
are refused beforehand: `App.Use` middleware and the documentation answer ahead of routing, so
when a wildcard argument spells a path one of them answers, that answer runs, and only then is
the result refused. A health endpoint's path cannot be spelled at all, since a route that
answers it is a build error.
The route's answer becomes the result:
| The route answered | The result |
|---|---|
| JSON | The JSON as text, and as `structuredContent` (an object before 2026-07-28, any value from it) |
| Text or HTML | Text |
| An image or audio | An image or audio item, in base64 |
| A redirect | The `Location` as text; it is not followed |
| No body | An empty `content` |
| Any status from 400 | `isError: true` with the error envelope as text |
| Anything else, or more than `MaxResultSize` | `isError: true` saying why |
Only the status, the body, its `Content-Type` and a redirect's `Location` make the result. The
route's other response headers, `Set-Cookie` included, are not returned to the MCP client: a
session in the cookie store that a tool changes is not kept, and `Retry-After` and
`WWW-Authenticate` do not reach the client either.
A failure of the call, arguments that do not fit, a 401 from the route, a validation error, a
handler's panic, is a result with `isError` set, carrying the error envelope your error
renderer wrote for clients, so a model reads it and can try again. Only a malformed message,
an unknown tool or arguments that are not an object are JSON-RPC errors.
## Authorization
Protect the endpoint with the same scheme as the routes. An unauthenticated client then gets
the 401 whose `WWW-Authenticate` names the `resource_metadata` document, which is how an MCP
client finds the authorization server and starts the OAuth flow:
```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp"
```
Set `Audience` and `ResourceMetadata.Resource` to the endpoint's URL, so a token issued for it
is accepted here and nowhere else. The token reaches the routes of this application, unchanged,
and no other service: a route that calls another service presents that service its own
credential, never the client's.
Only the endpoint can challenge a client. A route's 401 or 403 becomes an error result, not an
HTTP challenge, so a tool call never sends a client to sign in or to get a token with more
scopes. Protect the endpoint itself with the scopes its tools need, so that a client is
challenged for them when it connects:
```go
app.MCP("/mcp", muzak.MCPOptions{Tags: []string{"agent"}},
muzak.WithSecurity(muzak.Require("oidc", "orders:read", "orders:write")))
```
An API key a call does not carry cannot authenticate it. A call's query string is written from
its arguments alone, and an input may not bind the key's parameter, so a key read from the
query string never reaches the route; nor does one read from a header or cookie that
`ForwardHeaders` or `ForwardCookies` does not name. A route that only such a key admits fails
closed: every call of it is an error result with status 401.
A session is bound to the principal that opened it: the issuer, subject and scheme of a
bearer token, or the identifier and scheme of an API key. A client presenting another
principal's session identifier is told it does not exist. A session opened without a
credential the endpoint verified is bound to nobody, so any principal may use it, and JWTs
without a `sub` from one issuer and scheme share an owner. Sessions grant nothing in any case:
every message is authenticated by the endpoint's security and every call by its route's.
## Protocol support
| Revision | How it is served |
|---|---|
| 2026-07-28 | Stateless: every request carries its revision, no session, `server/discover` |
| 2025-11-25 | Session opened with `initialize` |
| 2025-06-18 | Session opened with `initialize` |
| 2025-03-26 | Session opened with `initialize`; no titles, structured content or output schemas, and no batches |
`initialize` answers the revision a client asks for when it is one of the session revisions,
and 2025-11-25 otherwise. A 2026-07-28 client may send any request first and is told the
revisions with `-32022` if its own is not one of them.
| Request | Answer |
|---|---|
| `POST` with a request | `200` and `application/json` |
| `POST` with a notification or a response | `202`, no body |
| `POST` without a session a session revision needs | `400` |
| `POST` or `DELETE` with an unknown or expired session | `404`; the client opens another |
| `DELETE` | `204`, the session ends |
| `GET` | `405`; no stream from the server is offered |
| An `Origin` that is not allowed | `403` |
| A body that is not `application/json`, or an `Accept` without it | `415`, `406` |
| An `MCP-Protocol-Version` other than the session's | `400` |
| An `Mcp-Method`, or on `tools/call` an `Mcp-Name`, that does not match the body or is sent twice | `400` with `-32020`; 2026-07-28 requires both, and a session revision, which may leave them out, is held to them when it sends them |
| A body larger than the endpoint's `MaxBodySize` | `413` |
| A batch | `400` with `-32600`, for every revision |
Messages are read strictly: the JSON-RPC 2.0 envelope and nothing else, `jsonrpc` exactly
`"2.0"`, an id that is a string or a number and never null, params that are an object, no
member twice, nested at most 128 deep, and no larger than the endpoint's `MaxBodySize`.
## Browser clients and the Origin check
Only a browser sends `Origin`, and the check exists for one attack: DNS rebinding, where a
page served from the attacker's name is made to resolve to your server and sends that name as
`Origin` and `Host` alike. The endpoint's own origin therefore counts only when its `Host` is
one the application vouches for: listed in `AppOptions.AllowedHosts`, or `localhost` or an
address. Any other origin needs `MCPOptions.AllowedOrigins` or `AllowOriginFunc`, and `"*"` is
refused. A browser client also needs [CORS](/docs/security/cors), with `Mcp-Session-Id` among
the exposed headers:
```go
muzak.AppOptions{
AllowedHosts: []string{"api.example.com"},
CORS: muzak.CORSOptions{
AllowedOrigins: []string{"https://inspector.example.com"},
AllowedHeaders: []string{"Content-Type", "Authorization", muzak.HeaderMCPSessionID, muzak.HeaderMCPProtocolVersion, muzak.HeaderMCPMethod, muzak.HeaderMCPName},
ExposedHeaders: []string{muzak.HeaderMCPSessionID},
},
}
```
A server run on a developer's machine binds to `127.0.0.1`, not to every interface.
## Bounds
| Option | Default | Bound |
|---|---|---|
| `MaxResultSize` | 1 MiB | At most 64 MiB; a larger answer is an error result and stops the route |
| The endpoint's `MaxBodySize` | The application's, 1 MiB unless set | Bounds each message, and the request a call writes, which is also held to the route's own `MaxBodySize`, or `MaxUploadSize` for a route that takes files; arguments that would exceed the smaller are an error result with status 413 |
| `PageSize` | 100 tools | At most 1000 |
| `MaxSessions` | 10,000 | At most 1,000,000; the session idle longest is evicted |
| `SessionIdleTimeout` | 24 hours | |
| `ListTTL` | 5 minutes | How long a 2026-07-28 client may cache the list |
Anyone the endpoint admits can open sessions, and there is no cap for each principal: a flood
of `initialize` evicts the sessions idle longest, whose clients are told `404` and initialize
again. Guard the endpoint or give it a rate limit, so that one client cannot push everyone
else's sessions out. In the same way, `tools/list` shows every tool to whoever the endpoint
admits, whether or not the tool's own route would admit them, and does so even with
`DisableDocs`.
`tools/list` cursors are opaque and authenticated, so a client can neither forge nor alter one,
and one from before a restart is refused. A 2026-07-28 listing is marked private to caches
when the endpoint is guarded. A tool call counts once against the endpoint's rate limit and
once against its route's, both for the same client, so a model calling a route through the
endpoint spends the same budget an HTTP client does; see
[Rate Limiting](/docs/techniques/rate-limiting).
## Limits
- **Batches are refused for every revision**, 2025-03-26 included, which allowed them. A client
sends each message in a request of its own.
- **Sessions live in memory.** A deployment of several instances serving the session revisions
(2025-03-26 to 2025-11-25) needs sticky routing, so that each client keeps reaching the
instance that opened its session; a client of another instance is told `404` and opens a new
one. 2026-07-28 clients are stateless and need nothing.
- **A route that binds `User-Agent` to a non-pointer string** cannot be called unless the model
supplies a value: a call refuses to send an empty `User-Agent`. Bind it to a `*string` when it
is optional.
- **An optional header or cookie bound to a non-pointer string** is sent empty when the model
leaves it out, as `Endpoint.Call` sends it. Bind it to a pointer when an empty value and an
absent one mean different things to the route.
## Testing
```go
func TestAgentCanReadAnOrder(t *testing.T) {
client := testclient.New(t, testApp(t), testclient.WithHeader("Authorization", "Bearer "+testToken(t)))
accept := testclient.Header("Accept", "application/json, text/event-stream")
res := client.Post("/mcp", accept, testclient.RawJSON(`{"jsonrpc":"2.0","id":1,"method":"initialize",
"params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}`))
res.AssertStatus(http.StatusOK)
session := testclient.Header(muzak.HeaderMCPSessionID, res.Header.Get(muzak.HeaderMCPSessionID))
res = client.Post("/mcp", accept, session, testclient.RawJSON(`{"jsonrpc":"2.0","id":2,"method":"tools/call",
"params":{"name":"get_order","arguments":{"path":{"id":"42"}}}}`))
res.AssertStatus(http.StatusOK)
}
```
## Where to go next
[Authentication](/docs/security/authentication) covers the schemes the endpoint and its tools
are protected by and the protected resource metadata a client signs in through,
[OpenAPI](/docs/fundamentals/openapi) covers the operation ids and schemas a tool is described
with, and [Typed Endpoints](/docs/techniques/typed-endpoints) covers the encoder a call is
written by.
--------------------------------------------------------------------------------
title: "WebSockets"
description: "A WebSocket route registered like any other, with the input bound and the guards run before a single byte is upgraded, and every direction a peer controls bounded."
version: "0.3.0"
last_updated: "2026-10-10T06:43:18.000Z"
source: "https://muzak.dev/docs/0.3.0/realtime/websockets"
--------------------------------------------------------------------------------
# WebSockets
`Router.WS` registers a WebSocket route. The protocol is implemented in the framework
rather than delegated to a library: RFC 6455 framing, masking, UTF-8 validation and the
close handshake, with every rule the specification lays down enforced and every violation
answered with the status it calls for.
::code-group
```go [routers/items.go]
// A WebSocket route is declared like any other: the input is bound from the
// handshake, the dependency resolves before the upgrade, and the handler owns
// the connection until it returns.
r.WS("/items/{item_id}/ws", handlers.ItemSocket,
muzak.Summary("Talk to an item over a WebSocket"),
muzak.Needs(core.GetCaller),
muzak.WithWebSocket(muzak.WSOptions{
ReadLimit: 64 << 10,
MaxLifetime: 8 * time.Hour,
MessageLimits: []muzak.Quota{
{Name: "ws-messages", Window: time.Second, Limit: 10},
},
}))
```
```go [schemas/items.go]
// WSItemIn is the input of the item's WebSocket route.
//
// A handshake carries no body, so every field comes from the path, the query
// string, a header or a cookie. The pointer makes the query parameter optional:
// it stays nil when the client did not send one, which is how an absent value is
// told from a zero one.
type WSItemIn struct {
ItemID string `path:"item_id" doc:"The item being talked about"`
Q *int `query:"q" doc:"An optional number echoed back with each reply"`
// Caller is filled by the route's provider before the handshake
// completes; it is never read from the request.
Caller muzak.Dep[core.Caller]
}
```
```go [handlers/items.go]
// ItemSocket answers a WebSocket conversation about one item.
//
// The handshake has already succeeded by the time this runs: the input is
// bound, the guards have passed and the dependency is resolved, so what is left
// is the conversation itself. Returning ends it, and Muzak closes the
// connection; returning nil closes it normally.
func ItemSocket(ctx *muzak.Context, in schemas.WSItemIn, conn *muzak.WSConn) error {
caller := in.Caller.Get()
for {
message, err := conn.ReadText(ctx.Context())
if err != nil {
// The peer closed, or the connection was lost. Either way there is
// nothing left to say.
return nil
}
if err := conn.WriteText(ctx.Context(), "hello, "+caller.Username); err != nil {
return err
}
if in.Q != nil {
if err := conn.WriteText(ctx.Context(), fmt.Sprintf("q is %d", *in.Q)); err != nil {
return err
}
}
if err := conn.WriteText(ctx.Context(),
fmt.Sprintf("you said %q, about item %s", message, in.ItemID)); err != nil {
return err
}
}
}
```
::
## The handshake is an ordinary GET
Everything that applies to a route applies here. Middleware runs, guards run, dependencies
resolve, and the input struct is bound and validated **before a single byte is upgraded**.
A request that fails any of that is answered with the usual JSON error and never becomes a
connection at all, which is the difference between a rejection a client can read and a
socket that closes a moment after it opened.
One thing is judged **before** the guards: a request that asks to upgrade has its origin and the
connection limits checked first. A cross-origin handshake, or one arriving at a full server, used
to be answered `403` or `503` only after the session dependency had run with the visitor's
cookie, so a refused handshake still cost a store lookup and whatever side effect it has. A plain
`GET` that does not ask to upgrade still reaches the guards first, so a client without
credentials still gets `401`. So does an HTTP/2 `GET`, which is answered `426` after the guards:
a WebSocket handshake is not carried over HTTP/2.
A room is reserved for the connection under the register's lock **before** the `101` is written.
It used to be recorded after the response had told the peer it was connected, so a client that
dialled again as soon as it read the response could be admitted past the connection limits.
```bash
curl -i 'http://localhost:8080/items/plumbus/ws'
```
```json
{
"error": {
"code": "unauthorized",
"message": "sign in, or pass a token query parameter",
"status": 401
},
"request_id": "0611f4b2-2f0a-4b57-9c1a-6e6a2e2f9b31"
}
```
Because a handshake carries no body, an input type with a body field is a registration
error rather than a request that mysteriously never arrives.
### Where a browser can put a credential
A browser cannot set headers on a WebSocket handshake, so the two places a credential can
arrive are the session cookie the browser attaches itself and a query parameter the page puts
in the URL. A provider covering both is what makes the route usable from either.
```go [core/dependencies.go]
// Caller is who is on the other end of a WebSocket route.
type Caller struct {
Username string
FromToken bool
}
// GetCaller resolves the caller from the session a sign-in stored, or from a
// token query parameter.
func GetCaller(ctx *muzak.Context) (Caller, error) {
if user, ok := muzak.SessionGet[string](ctx.Session(), "user"); ok {
return Caller{Username: user}, nil
}
if token := ctx.Query("token"); token != "" {
user, err := tokens.Verify(ctx.Context(), token)
if err != nil {
return Caller{}, muzak.Unauthorized("the token is not valid")
}
return Caller{Username: user, FromToken: true}, nil
}
return Caller{}, muzak.Unauthorized("sign in, or pass a token query parameter")
}
```
`ctx.Session()` needs `AppOptions.Sessions`, and reads the visitor's session during the
handshake, as it would on any route. A WebSocket route only reads it: the `101` has gone out
before the handler runs, so no cookie can follow, and a change made to the session on such a
route is not saved and is logged as a warning. See [Sessions](/docs/security/sessions) and
[Dependencies](/docs/getting-started/dependencies).
A cookie is ambient authority a browser attaches without being asked, which is exactly why
the origin check below cannot be turned off casually.
## Reading and writing
Reading and writing are message oriented. A message split across several frames is
reassembled and delivered once, whole. Control frames that arrive in between are handled
without interrupting it: a ping is answered automatically, and a close is answered and then
reported as a `*WSCloseError`.
| Call | What it does |
|---|---|
| `Read(ctx)` | The next message, as a type and a payload |
| `ReadText(ctx)` | The next message as text. A binary message is refused with `1003` |
| `ReadBinary(ctx)` | The next message as bytes. A text message is refused with `1003` |
| `ReadJSON(ctx, &v)` | Decodes a text message with the same strictness a request body gets |
| `Write(ctx, typ, payload)` | One message, as a single frame |
| `WriteText(ctx, s)` | A text message. Invalid UTF-8 is refused before anything reaches the wire |
| `WriteBinary(ctx, b)` | A binary message |
| `WriteJSON(ctx, v)` | Encodes as JSON and sends it as text |
| `Ping(ctx)` | Sends a ping and returns once it is on the wire |
| `Close(status, reason)` | Closes with a status and a reason |
| `Subprotocol()` | The subprotocol negotiated during the handshake, or `""` |
```go
type Command struct {
Action string `json:"action"`
Target string `json:"target"`
}
func Control(ctx *muzak.Context, in ControlIn, conn *muzak.WSConn) error {
for {
var command Command
if err := conn.ReadJSON(ctx.Context(), &command); err != nil {
return nil
}
if err := conn.WriteJSON(ctx.Context(), handle(command)); err != nil {
return err
}
}
}
```
`ReadJSON` decodes with the same rules a request body is decoded with: unknown members,
duplicate members and invalid UTF-8 are all rejected. A message that does not decode closes
the connection with `1007`, because a peer sending malformed JSON on a JSON connection is
not going to be understood by carrying on.
The slice `Read` returns belongs to the caller and is not reused, so it may be kept. The
payload passed to `Write` is not retained, so the caller may reuse it as soon as `Write`
returns.
### Concurrency
Writes are serialized, so any number of goroutines may write to one connection and each
message goes out intact. A broadcast from many goroutines cannot interleave two messages.
Reads are serialized too, but a second reader is rarely what is wanted: the messages of one
connection arrive in order and one loop should consume them.
```go
func Room(ctx *muzak.Context, in RoomIn, conn *muzak.WSConn) error {
hub := muzak.From[*core.Hub](ctx)
updates := hub.Subscribe(ctx.Context(), in.Room)
go func() {
for update := range updates {
// Safe from another goroutine: writes are serialized.
_ = conn.WriteJSON(ctx.Context(), update)
}
}()
for {
message, err := conn.ReadText(ctx.Context())
if err != nil {
return nil
}
hub.Publish(in.Room, message)
}
}
```
### A deadline on a read
`ReadTimeout` bounds one message once it has begun, and deliberately not the wait between
messages. A handler that wants its peer to say something within a given time gives each read a
deadline of its own:
```go
func Conversation(ctx *muzak.Context, in ConversationIn, conn *muzak.WSConn) error {
for {
// A peer that says nothing for five minutes is done with.
readCtx, cancel := context.WithTimeout(ctx.Context(), 5*time.Minute)
message, err := conn.ReadText(readCtx)
cancel()
if err != nil {
return err
}
if err := conn.WriteText(ctx.Context(), "you said "+message); err != nil {
return err
}
}
}
```
A read that its context ends ends the connection, and the peer is told why. A deadline that
passed closes with `1008` and the reason "no message arrived within the time allowed", the
status the read timeout and keepalive use, and a cancellation closes with `1001`. The read
returns the context's error once the close frame is out and the peer has answered it, or after
`CloseGracePeriod` (250 ms by default) at the most; set it negative if a read must return the
moment its deadline passes. Returning that error, as above, is not treated as a failure.
A write whose context had already ended when it got the connection sends nothing of the message
and closes with `1001`. One that its context interrupts part way through a frame ends the
connection with no close frame, so the peer sees `1006`, because a close frame would be read as
more of the frame. On a `WSDial` connection a cancelled read closes the transport, and no close
frame can follow.
## Ending a connection
The connection is closed when the handler returns, so a handler owns its connection for as
long as it runs and never has to arrange the teardown itself.
| The handler returns | The peer gets |
|---|---|
| `nil` | `1000 Normal Closure` |
| a `*WSCloseError` | the status and reason it carries |
| an error a read or write returned because its context ended, or `ctx.Context().Err()` once it has ended | already told (`1008` for a read deadline, `1001` otherwise); a connection still open is closed with `1001`. Logged at debug, not as a failure |
| anything else, a deadline from elsewhere included | `1011 Internal Error`, with the reason logged and nothing disclosed |
```go
if !allowed(caller, in.Room) {
return &muzak.WSCloseError{Status: muzak.WSStatusPolicyViolation, Reason: "not a member of this room"}
}
```
Calling `Close` yourself is only necessary to choose a status other than normal closure or
to end the connection from another goroutine. It is safe to call more than once and from
more than one goroutine; only the first call sends anything. The reason is truncated to the
123 bytes a close frame can carry, on a rune boundary.
A value the route's providers acquired with `Acquire` lives as long as the connection. Its
release runs as soon as the handler returns, before the connection is closed, and is handed
what the handler returned, so a `Transaction` held for the conversation commits only when the
handler returned nil. A release that fails a connection which had not failed closes it with
`1011`, as a handler's error would. See [Dependencies](/docs/getting-started/dependencies).
With tracing on, the request's span lasts as long as the connection and ends when it does, and a
handler that fails (the `1011` row above) marks it an error, while a connection its context ended
does not. `AppOptions.Observer` is told about the connection once, after it has ended. See
[Observability](/docs/fundamentals/observability).
### Telling a goodbye from a violation
Every read and every write returns a `*WSCloseError` once the connection is finished, which
is why the loops above end on any error.
A peer that is still sending when the server refuses the connection reads the close status
instead of a reset. A message over the read limit is answered with a close frame `1009`, but a
client that kept sending, a message still streaming in, often saw the connection reset (`1006`)
and never read it: the server closed the socket with unread data in its receive buffer, which
makes the kernel send a reset and drop the close frame in flight. The same happened after every
close the server started on finding a fault, `1002`, `1003`, `1007` and `1008` included. Once the
close frame is out, the server now stops sending (a half-close, or the `close_notify` alert on
TLS), keeps reading and dropping what arrives until the peer's close frame, the end of its stream,
`CloseGracePeriod` or 1 MiB, whichever is first, and only then closes the transport. Nothing read
is kept, a peer that answers the close frame promptly is not made to wait, and one that never
stops is cut off at the grace period as before. A close the handler starts with `Close` gets the
same half-close. In a test that sends a message over the limit and keeps sending, the `1009`
reached the client in 0 of 50 runs before and 50 of 50 after.
The status reaches the peer even when two closers race. A second `Close` (a shutdown, a
keepalive timeout, a returning handler) used to tear the transport down under the first one's
close frame, so the peer saw `1006`. It now waits for that frame, and a peer's own close is
echoed even when another goroutine is writing at that moment. A close reason that is not valid
UTF-8, one an application forwarded from elsewhere, is repaired before it is sent, with invalid
bytes written as U+FFFD, so the peer reads the status instead of failing the connection.
```go
message, err := conn.ReadText(ctx.Context())
if err != nil {
if status, ok := muzak.WSCloseStatus(err); ok && status == muzak.WSStatusNormalClosure {
return nil
}
return err
}
```
`WSCloseError.Unwrap` exposes the transport failure behind an abnormal closure, so
`errors.Is` can test for `io.EOF` or a network error.
The codes RFC 6455 defines are exported as `muzak.WSStatus` constants, from
`WSStatusNormalClosure` (1000) to `WSStatusTLSHandshake` (1015). Three of them describe a
local observation rather than something a peer said: `WSStatusNoStatusReceived`,
`WSStatusAbnormalClosure` and `WSStatusTLSHandshake` are reported by Muzak but never
written to the wire, and passing one to `Close` closes without a status code. Codes from
4000 to 4999 are free for an application to define.
## What a hostile peer cannot do
A WebSocket is the longest-lived thing an unauthenticated stranger can ask a server for, so
every direction a peer controls is bounded, and each bound stops something specific.
| A peer that... | ...is stopped by |
|---|---|
| sends a message larger than the limit | refused with `1009` before any of the payload is buffered. The check cannot overflow: one byte followed by a continuation frame declaring `0x7FFFFFFFFFFFFFFF` used to wrap negative and pass, and the peer could stream as much as it liked into one message. Such a frame is refused from its header alone |
| declares a huge payload and sends none of it | a frame is taken a chunk at a time, so six bytes of header cannot buy an allocation the size of the limit |
| dribbles a message out a byte at a time | closed once `ReadTimeout` passes with the message unfinished. Waiting *between* messages stays unbounded |
| fragments a message endlessly, or floods pings | closed once too many frames arrive without one completing, which no size limit would ever catch. More than 65536 pings, pongs and empty fragments in a minute closes the connection with `1008` |
| connects and goes silent, or is dropped by a network that told nobody | keepalive, on by default: a ping every 30 seconds, closed when nothing at all arrives within `PongTimeout` of a ping. Bytes of a message still arriving count as an answer |
| answers every ping and says nothing, for as long as it likes | `MaxLifetime`, when the route sets one |
| stops reading what it asked for | writes give up after `WriteTimeout` rather than pinning a goroutine |
| opens connections without end | `MaxConnections` per application, then `503` with `Retry-After` |
| opens many from one address | `MaxConnectionsPerIP`, so one client cannot take every slot the process has. 16 addresses (one IPv6 /52) fill the defaults |
| opens one from another origin | refused outright. The origin is read strictly, and `AllowedHosts` closes DNS rebinding |
| withholds its close frame after the handler returned | the slot is held until the socket is actually closed, so it cannot hold sockets the limits say nobody may |
| sends a body with the handshake | refused, because what went unread would be taken for frames the moment it was upgraded |
| asks for an extension | none is negotiated, so no peer can make the server hold decompression state |
| never pauses, within every limit above | `MessageLimits`, closed with `1008` |
Nothing a peer sends is echoed into a response header: only a subprotocol the route itself
offered can be answered with, and a route offering one that is not a token is refused when
the application is built.
None of the defaults bounds how long a connection lasts. A peer that answers every ping and
sends nothing is alive as far as a keepalive can tell, and with `MaxLifetime` unset nothing
ends it. `MaxConnections` divided by `MaxConnectionsPerIP` is how many addresses can hold every
slot: 1024 / 64 = 16 with the defaults, which is sixteen IPv4 addresses, or a single IPv6 /52
at the default /56 grouping. Every other handshake is then refused with `503` until they let
go. A route that clients you do not control can open is worth more than the defaults:
- **Put it behind a guard that authenticates the client** where it can be, which ties a
connection to someone rather than to an address.
- **Set `MaxLifetime`, to minutes rather than hours**, so that every slot turns over. A client
that reconnects on going away, as a browser application usually does, carries on.
- **Count IPv6 clients by their /48** with `ClientIPOptions.ConnectionIPv6Prefix: 48`, which
makes each of those addresses cost a whole site's allocation.
[Server-Sent Events](/docs/realtime/server-sent-events#what-a-stream-bounds) works through the
same arithmetic for event streams, which share the per-address grouping.
## Options
```go
app.Include(chat, muzak.WithWebSocket(muzak.WSOptions{
ReadLimit: 64 << 10,
PingInterval: 30 * time.Second,
AllowedOrigins: []string{"https://app.example.com"},
}))
```
| Field | Default | Bounds |
|---|---|---|
| `ReadLimit` | 1 MiB | The largest message accepted. There is deliberately no way to remove it |
| `ReadTimeout` | 30s | How long one message may take to arrive once it has begun |
| `WriteTimeout` | 10s | How long one message may take to reach the peer |
| `MaxConnections` | 1024 | Connections the application holds at once. Application-level only |
| `MaxConnectionsPerIP` | 64 | Connections one address holds at once. Application-level only |
| `CloseGracePeriod` | 250ms | How long a closing connection waits for the peer's close frame, and how long a `WSDial` client waits for the server to hang up |
| `PingInterval` | 30s | Keepalive: ping this often and close when the peer stops answering. Negative turns it off |
| `PongTimeout` | 10s | How long a keepalive ping waits. Negative means the default, and it means nothing once keepalive is off |
| `MaxLifetime` | none | The longest a connection stays open. Negative removes a bound a wider scope set |
| `MessageLimits` | none | Quotas bounding how fast a peer may send |
| `Subprotocols` | none | The subprotocols the route can speak |
| `AllowedOrigins` | none | Browser origins allowed in addition to the server's own |
| `AllowedHosts` | none | The `Host` values that make an origin the server's own |
| `AllowOriginFunc` | none | A dynamic origin decision, consulted only for origins not already allowed |
| `InsecureSkipOriginCheck` | off | Accept a handshake from any origin |
| `EnforceOriginCheck` | off | Turn the origin check back on beneath a scope that set `InsecureSkipOriginCheck` |
Options can be set application-wide through `AppOptions.WebSocket` and narrowed for a
router or a route with `WithWebSocket`. Layering works field by field, so a route that
raises only the read limit keeps the application's origin policy.
`MaxConnections` and `MaxConnectionsPerIP` may only be set on the application: the resource
they protect is the process, not a route, so a router or a route that sets either is
refused when the application is built.
### Keepalive
Keepalive is **on by default**: a ping every 30 seconds (`DefaultWSPingInterval`), and the
connection is closed when nothing has arrived from the peer within 10
(`DefaultWSPongTimeout`). A peer that connects and goes silent, or whose network dropped without
a word, used to hold a connection slot for as long as it liked; only the per-address and global
caps bounded it. A browser answers pings without being asked, so nothing needs to change for
one. A negative `PingInterval` turns keepalive off, and a negative `PongTimeout` means the
default, since it used to be read as zero and the first ping closed every connection whose peer
could not answer instantly.
```go
muzak.WSOptions{PingInterval: -1} // no keepalive on this route
```
A pong is consumed by a read like any other frame, so a connection is closed for an unanswered
ping **only when the handler was reading during it**. The rule is what makes the default safe: a
handler that only ever writes, or one busy with a message, is left alone, which also stops
keepalive closing a healthy peer of a handler that does not read. It also means a handler that
only writes is never closed by keepalive, and should ping by hand with `Ping` if it wants that.
The pong check uses the monotonic clock, so a wall-clock step cannot close a healthy connection.
Anything that arrives from the peer after a ping answers it as well as a pong would, since what
is being asked is whether the peer is still there. A peer part way through one large frame
cannot send its pong until the frame is finished, and used to be closed with `1008` while its
bytes were still coming in: with the defaults, any 1 MiB message sent at under about 100 KB/s
was closed ten seconds in, although `ReadTimeout` allowed thirty. Every frame header and every
read that brings payload now counts as hearing from the peer, so only a peer from which nothing
at all has arrived for a pong timeout is closed. One that stalls part way through a frame is
still closed by the keepalive, and by `ReadTimeout` in any case.
### Ending a connection on purpose
Keepalive closes a peer that stops answering. It cannot close one that answers every ping and
never says anything, which costs that peer a TCP connection and holds a slot, a goroutine and a
file descriptor here until the server stops. `MaxLifetime` is the bound for that. It is unset by
default, which leaves connections unbounded, and worth setting on any route a client you do not
control can open:
```go
muzak.WSOptions{MaxLifetime: 2 * time.Hour}
```
When the lifetime has passed the connection is closed with `1001 Going Away`, the status of a
server that is done with a connection rather than one that failed. The handler sees it as the
close it reads, and the connection's slot is released once the transport is closed. A client
that reconnects on going away, as a browser application usually does, carries on. A negative
value removes a bound a wider scope set.
## The origin check
A cross-origin handshake is refused by default, and no CORS policy changes that.
A WebSocket handshake is not subject to the same-origin policy and is never preflighted,
which is what makes cross-site hijacking possible in the first place: without the check,
any page on the internet could open an authenticated connection to your server from a
visitor's browser, cookies and all. `AppOptions.CORS` has no bearing on it, for exactly that
reason. Nor does `AppOptions.CrossOriginProtection`: a handshake is a `GET`, which it never
refuses, so this check is what keeps another site's page from opening a connection with your
visitor's cookies. See [Cross-Origin Requests](/docs/security/cross-origin-requests).
```go
muzak.WSOptions{AllowedOrigins: []string{"https://app.example.com"}}
```
The server's own origin is always allowed. The single entry `"*"` allows any origin.
An origin is read strictly: a scheme and a host with nothing after it, compared as a browser
serializes it. `http://attacker@host`, `http://host/path`, `http://host?x` and `//host` used to
pass as the server's own origin, because the host was taken out of any value a lenient URL parse
could find one in. A value carrying credentials, a path, a query or a fragment is not the
server's own origin however its host reads, and a handshake with more than one `Origin` header is
refused with `400`. Values listed in `AllowedOrigins`, and the ones `AllowOriginFunc` sees, are
compared as they arrived, without regard to case. A browser sends neither shape; a non-browser
client that sent a decorated `Origin` must send a bare `scheme://host[:port]` or none at all.
The lists themselves are checked when the application is built, the same way the CORS list is.
An `AllowedOrigins` entry that can never equal what a browser sends, such as
`https://app.example.com/`, `https://app.example.com/ws`, `https://app.example.com:443` or
`https://*.example.com`, is a build error naming the route and the spelling to use, and so is
`"null"`: it is the origin a sandboxed iframe sends, so any page can present it, and listing it
would let every page open a connection with the visitor's cookies. The single entry `"*"` still
allows any origin, and wildcard subdomains belong in `AllowOriginFunc`. An `AllowedHosts` entry
with a scheme, a path, credentials or a pattern can never equal a `Host` header and is refused too.
### DNS rebinding
The server's own origin is any whose host is the request's `Host`, which is whatever the client
wrote there. That is enough for a browser that reached the server by its name, and it is not for
one that was pointed at it by somebody else's: in a DNS-rebinding attack a page served from the
attacker's name, made to resolve to your server, sends that name as both `Origin` and `Host`, and
reads as same-origin. `AllowedHosts` lists the names the route answers to:
```go
muzak.WSOptions{AllowedHosts: []string{"app.example.com", "app.example.com:8443"}}
```
When it is set, a handshake counts as same-origin only if its `Host` is listed, compared without
regard to case and with any port written as the client wrote it. Any other `Host` is refused with
`403` unless `AllowedOrigins` or `AllowOriginFunc` names the origin. A handshake with no `Origin`
is not affected, since only a browser sends one. Unset, the rule is what it was, so nothing
changes until it is set; it is worth setting for a server on a loopback or private address, where
such a page is a real threat.
The option bounds the WebSocket handshake only. A plain HTTP route is not protected against
rebinding by it. `AppOptions.AllowedHosts` holds every request to the application's own names,
handshakes included: a request for any other host is answered `421` before a route, a guard or
the origin check runs. See [Hosts and HTTPS](/docs/security/hosts-and-https).
```go
muzak.WSOptions{
AllowOriginFunc: func(r *http.Request, origin string) bool {
return strings.HasSuffix(origin, ".example.com")
},
}
```
It runs on every handshake an earlier rule did not already allow, so it must be cheap and
free of side effects.
Options layer field by field, so an application's `AllowOriginFunc` stays in force for a route
that only lists origins of its own, and a scope that says nothing keeps a wider scope's
`InsecureSkipOriginCheck`. A router or route that does need the check, such as one
authenticated by a cookie in an application that otherwise authenticates by token, sets
`EnforceOriginCheck: true`. A scope beneath it can set `InsecureSkipOriginCheck` again, and the
narrowest scope that set either wins. A scope that sets both keeps the check.
```go
// Every route takes a token the client presents explicitly...
app := muzak.New(muzak.AppOptions{
WebSocket: muzak.WSOptions{InsecureSkipOriginCheck: true},
})
// ...except this one, which a browser authenticates with its session cookie.
r.WS("/account/ws", handlers.AccountSocket,
muzak.WithWebSocket(muzak.WSOptions{EnforceOriginCheck: true}))
```
`InsecureSkipOriginCheck` accepts a handshake from anywhere. It is safe only for a
connection that carries no ambient authority: one authenticated by a token the client has
to present explicitly, never by a cookie, since a browser attaches cookies to a
cross-origin handshake without being asked.
## Subprotocols
```go
muzak.WSOptions{Subprotocols: []string{"graphql-transport-ws", "graphql-ws"}}
```
The client's own list is in preference order, so the first of its choices that appears here
is the one negotiated. A client asking for something else is answered without the header,
which tells it to give up. Read the result with `conn.Subprotocol()`.
## Shutdown
Open connections are tracked, so a graceful shutdown tells every peer it is going away with
`1001` and waits for the handlers, and for connections that are still closing. `net/http` cannot
do that on its own: a hijacked connection is no longer one it knows about. The handler's context
ends with its connection, so a handler waiting on it does not outlive its peer or the server's
close at shutdown.
The goodbye comes after readiness has turned unavailable and `ServerOptions.DrainDelay` has
passed, during which connections stay open and new handshakes are still served. It is sent as
the listeners close, alongside the drain of ordinary requests, and the background tasks and
lifecycle components are dealt with only once the handlers have returned. Shutdown shares one
deadline with everything else; see [Lifecycle](/docs/getting-started/lifecycle#shutdown).
## Documentation
A WebSocket route appears in the OpenAPI document with its parameters and a
`101 Switching Protocols` response, because that is what OpenAPI can say about a handshake.
The conversation itself continues off the document. What a handshake is refused with is listed
too: `426` and `422`, `400` for a malformed handshake, `403` for a foreign origin (left out for a
route that skips the check) and `503` for a draining or full server. A status a route declared
with `WithResponseDoc` keeps its own description.
## Testing
`muzak.WSDial` is the client half of the same engine, which is what lets a route be tested
over a real connection rather than against a second implementation. The test client wraps
it:
```go
func TestItemSocket(t *testing.T) {
client := testclient.New(t, buildApp())
// A token tokens.Verify accepts for the user jessica.
conn := client.WS("/items/plumbus/ws", testclient.Query("token", jessicasToken))
if err := conn.WriteText(t.Context(), "hello"); err != nil {
t.Fatalf("WriteText = %v", err)
}
reply, err := conn.ReadText(t.Context())
if err != nil {
t.Fatalf("ReadText = %v", err)
}
if reply != "hello, jessica" {
t.Errorf("reply = %q", reply)
}
}
func TestItemSocketNeedsCredential(t *testing.T) {
client := testclient.New(t, buildApp())
_, response := client.TryWS("/items/plumbus/ws")
response.AssertStatus(http.StatusUnauthorized)
}
```
Outside a test, dial directly:
```go
conn, _, err := muzak.WSDial(ctx, "ws://"+app.Addr()+"/items/plumbus/ws", muzak.WSDialOptions{})
if err != nil {
return err
}
defer conn.Close(muzak.WSStatusNormalClosure, "")
```
The URL may use `ws`, `wss`, `http` or `https`. The response is returned alongside the
connection so a caller can read the handshake headers, and on failure the status and body
the server refused with. `WSDial` never follows a redirect, because following one would
send the handshake's headers to whatever host the answer named.
A `101` that names an extension is refused, because the client never offers one and RFC 6455
section 4.1 says a response that negotiates one it did not ask for fails the connection. It used
to read on with frames whose meaning the server had changed. `WSDial` connections apply
`ReadTimeout` and `WriteTimeout`, which they did not before: the transport `net/http` hands back
is not a `net.Conn`, so no deadline was ever set and a server that stopped reading held the
client forever. The frame-size check that let a message slip past the read limit is fixed on the
client too.
A `WSDial` connection waits, up to `CloseGracePeriod`, for the server to close TCP first, as
RFC 6455 section 7.1.1 asks, so that the server rather than every client holds the `TIME_WAIT`
state a closed connection leaves behind. It reads on to the end of the stream, so `Close` returns
once the server has hung up, or after the grace period at the most. It used to hang up the
moment its close frame was out, and `WSDialOptions.CloseGracePeriod` did nothing.
## Where to go next
[Server-Sent Events](/docs/realtime/server-sent-events) covers the simpler half
of what a WebSocket is usually reached for, and
[Rate Limiting](/docs/techniques/rate-limiting) covers the quotas
`MessageLimits` reuses.
--------------------------------------------------------------------------------
title: "Server-Sent Events"
description: "A typed event stream registered like any other route, read natively by a browser's EventSource, with the schema of one event in the generated document."
version: "0.3.0"
last_updated: "2026-10-10T06:43:18.000Z"
source: "https://muzak.dev/docs/0.3.0/realtime/server-sent-events"
--------------------------------------------------------------------------------
# Server-Sent Events
`Router.SSE` registers a route whose response is a stream rather than a body. It is the
other half of what a WebSocket is usually reached for, and the simpler half: the server
sends, the client listens, and a browser reads it natively with `EventSource`, reconnecting
on its own when a stream drops.
::code-group
```go [routers/items.go]
// An event stream route is declared like any other and answers 200 rather than
// upgrading: the guards run and the input binds before a byte of the stream is
// written, and the handler owns the stream until it returns.
r.SSE("/items/stream", handlers.StreamItems,
muzak.Summary("Follow every change to the items"),
muzak.WithSSE(muzak.SSEOptions{
// A stream that says nothing for long enough is closed by proxies that
// believe it to be idle, so a comment goes out instead.
KeepAlive: 15 * time.Second,
// A browser reconnects on its own when a stream ends, and this is how
// soon.
Retry: 2 * time.Second,
}))
```
```go [handlers/items.go]
func StreamItems(ctx *muzak.Context, _ muzak.Empty, stream *muzak.SSEStream[schemas.ItemOut]) error {
store := muzak.From[*core.ItemStore](ctx)
updates := store.Watch(stream.Context())
for {
select {
case <-stream.Context().Done():
// The client went away or the server is shutting down. Either way
// the conversation is over, and it is not a failure.
return nil
case change := <-updates:
item := schemas.ItemOut{ID: change.Item.ID, Name: change.Item.Name}
if err := stream.Send(item); err != nil {
return err
}
}
}
}
```
::
The type parameter is the contract: nothing but an `ItemOut` can be sent, and the generated
document describes the stream with that type, in the same way a handler's return type
describes an ordinary response.
```bash
curl -N 'http://localhost:8080/items/stream'
```
```
retry: 2000
event: item_update
id: 1
data: {"id":"plumbus","name":"Plumbus"}
event: item_update
id: 2
data: {"id":"fleeb","name":"Fleeb"}
```
The `retry` field is sent once, before anything else, because `SSEOptions.Retry` was set
on the route above: a client that loses the stream on the very first event already knows
how long to wait. The response carries `Content-Type: text/event-stream; charset=utf-8`,
`Cache-Control: no-cache, no-transform` and `X-Accel-Buffering: no`. The type is set whatever
a middleware set before it, because a stream served under any other type, such as the
`application/json` a middleware may give every response in advance, is one `EventSource`
refuses to read. The other two are left alone when something already set them.
## An ordinary route
Middleware runs, guards run, dependencies resolve, and the input is bound and validated
**before a byte of the stream is written**. A request that fails any of that is answered
with the usual JSON error and never becomes a stream at all.
The response header is written before the handler is called, which is what lets a client
see the stream open immediately. Anything that decides whether to serve a stream at all
therefore belongs in a guard or a dependency, where there is still a response to say it in.
## The stream
Nothing on `SSEStream` takes a context, unlike `WSConn`, because a stream belongs to one
request.
| Call | What it does |
|---|---|
| `Send(data)` | One event carrying `data`, encoded as JSON into its data field |
| `SendEvent(event)` | One event described in full |
| `Comment(text)` | A comment line, which no client acts on and every client accepts |
| `Context()` | The context governing every send |
| `LastEventID()` | The identifier the client last saw |
| `Err()` | The error that ended the stream, or nil while it is usable |
`stream.Context()` is derived from the request's own and is cancelled when the client
disconnects, when the request ends, or when the server begins shutting down. That makes it
the one thing a handler has to watch, and every send after it reports
`muzak.ErrSSEStreamEnded`, so a handler that only sends ends on its own.
```go
for update := range updates {
if err := stream.Send(update); err != nil {
return err
}
}
```
A handler that returns `ErrSSEStreamEnded` is treated as a stream that finished rather than
one that failed, so a client going away is not logged as an error. Test for it with
`errors.Is`; the reason the stream ended is wrapped inside.
Tracing draws the same line. With tracing on, the request's span ends when the stream does, and
it is marked an error only when the handler fails, not when the client goes away.
`AppOptions.Observer` is told about the stream once, after it has ended. See
[Observability](/docs/fundamentals/observability).
A value the route's providers acquired with `Acquire` lives as long as the stream. Its release
runs as soon as the handler returns and is handed what the handler returned, so a `Transaction`
held for the stream commits only when the handler returns nil: a stream the client left ends
with `ErrSSEStreamEnded`, and is rolled back. A release that fails is logged as the stream's
failure. See [Dependencies](/docs/getting-started/dependencies).
Writes are serialized, so any number of goroutines may write to one stream and each event
goes out whole.
A stream is single use. The first failure ends it, and every later send reports that same
error rather than writing into a response nobody is reading. Sends that report a mistake
instead, such as an event name carrying a line break, leave the stream usable.
A stream never writes into a response it has handed back. A send still encoding when the handler
returned held the write lock, and the stream used to give up after `WriteTimeout` and return the
response anyway, which crashed the process or could write one client's event into the next
request on the connection.
## Events with more than data
```go
type SSEEvent[Out any] struct {
Name string // the type a browser dispatches it under
ID string // what a reconnect resumes from
Retry time.Duration // how long to wait before reconnecting
Comment string // text no client acts on
Data *Out // the value, encoded as JSON
Text string // a payload written as it stands
EmptyData bool // a data field even with no payload
}
```
```go [handlers/items.go]
// sendChange writes one change as an event a browser can listen for by name
// and resume from by identifier.
func sendChange(stream *muzak.SSEStream[schemas.ItemOut], change core.Change) error {
item := schemas.ItemOut{ID: change.Item.ID, Name: change.Item.Name}
return stream.SendEvent(muzak.SSEEvent[schemas.ItemOut]{
Name: "item_update",
ID: strconv.Itoa(change.Seq),
Data: &item,
})
}
```
```js
const source = new EventSource("/items/stream")
source.addEventListener("item_update", (event) => {
const item = JSON.parse(event.data)
// ...
})
```
`Data` is a pointer so that an event carrying nothing can be told from one carrying a zero
value, and it cannot be combined with `Text`. An event setting both is refused.
A client dispatches an event only when it has a data field, which it has when it carries
`Data`, a `Text` that is not empty, or `EmptyData`. An event without one is still written, and
a browser and `SSEReader` alike apply its `ID` and `Retry`, but neither hands it to the
application, `Name` included. The zero value is the extreme case: a blank line that no client
acts on. `EmptyData` writes a data field with nothing in it, which is dispatched as an event
whose data is the empty string. That is how a stream of text sends an empty message, as in
`SSEEvent{Text: line, EmptyData: true}` for a log line that may be blank, and how an event that
is only a name, such as a tick, is dispatched at all.
`Retry` is whole milliseconds, and a positive delay shorter than a millisecond is written as 1,
where it used to be truncated to 0 and told a client to reconnect at once.
`Name` and `ID` may not contain a line break. An event stream is a sequence of lines, so a
break in one of those fields would end it and let whatever followed be read as fields of
its own, which on a stream carrying one client's input to another is event forgery. Such a
send is refused rather than repaired, and the stream stays usable.
### Payloads that are not JSON
`Text` writes a payload as it stands, for a log line or for the sentinel some completion
APIs end with. A stream whose events are all text declares `muzak.Empty` as its model, and
the generated document then says there is no schema rather than describing one that does
not exist.
```go [handlers/chat.go]
// StreamChat answers a prompt one token at a time, which is the shape every
// chat completion API streams in.
func StreamChat(ctx *muzak.Context, in schemas.ChatIn, stream *muzak.SSEStream[muzak.Empty]) error {
for word := range strings.SplitSeq(in.Text, " ") {
select {
case <-stream.Context().Done():
// The client closed the tab, or the server is shutting down. There
// is no one left to answer.
return nil
case <-time.After(tokenDelay):
}
if err := stream.SendEvent(muzak.SSEEvent[muzak.Empty]{Name: "token", Text: word}); err != nil {
return err
}
}
// The sentinel some clients expect at the end of a completion. It is text
// rather than a value, which is what Text is for.
return stream.SendEvent(muzak.SSEEvent[muzak.Empty]{Name: "done", Text: "[DONE]"})
}
```
A payload spanning several lines is written as several data lines and arrives whole, which
is both what the format asks for and what stops a value from ending its own field.
## A stream reached by POST
A stream is not tied to `GET`. `Router.SSEHandle` registers one for any method, which is
what a protocol that streams its answer to a posted document needs, and there the input
binds a request body like any other route.
::code-group
```go [routers/chat.go]
r.SSEHandle(http.MethodPost, "/chat/stream", handlers.StreamChat,
muzak.Summary("Answer a prompt one token at a time"),
muzak.WithSSE(muzak.SSEOptions{
// A completion is never quiet for long, so the keepalive is only there
// for the pause before the first token.
KeepAlive: 10 * time.Second,
}))
```
```go [schemas/chat.go]
// ChatIn is the prompt a chat stream answers.
//
// It is an ordinary JSON body: an event stream reached by POST binds and
// validates one exactly as any other route does.
type ChatIn struct {
Text string `json:"text" doc:"The prompt to answer, one token at a time"`
}
// Validate bounds the prompt, and is applied before a byte of the stream is
// written.
func (in *ChatIn) Validate(v *muzak.Validation) {
v.String(&in.Text).Trim().Required().MinLen(1).MaxLen(280)
}
```
::
```bash
curl -N -X POST 'http://localhost:8080/chat/stream' \
-H 'Content-Type: application/json' -d '{"text":"what is a plumbus"}'
```
An input that binds nothing from the body leaves it to the handler, which reads it from
`ctx.Request().Body` even though the stream's header has already gone out, over HTTP/1.1 as over
HTTP/2. It is read under `ServerOptions.ReadTimeout`, as any route's body is, so a client that
declares a body and sends half of it cannot hold the handler for longer than that. Read it
before sending the first event, because a client may send the whole body before it reads any of
the response. Until the body has been read to its end, net/http cannot watch the connection for
the client going away, so a disconnect is noticed when a write fails rather than at once, which
with the keepalive on takes a couple of its intervals.
## Resuming a dropped stream
A browser remembers the last identifier it saw and sends it back in `Last-Event-ID` when it
reconnects. `stream.LastEventID()` reads it, and that is what turns a dropped connection
into a stream that picks up where it left off rather than one that starts again.
```go [handlers/items.go]
func StreamItems(ctx *muzak.Context, _ muzak.Empty, stream *muzak.SSEStream[schemas.ItemOut]) error {
store := muzak.From[*core.ItemStore](ctx)
// A browser sends back the identifier of the last event it saw when its
// EventSource reconnects. The value is the client's, so one that is not a
// number is treated as no value at all rather than as an error.
seen := 0
if last := stream.LastEventID(); last != "" {
if parsed, err := strconv.Atoi(last); err == nil {
seen = parsed
}
}
// Subscribing before the backlog is read is what stops a change made in
// between from falling through the gap between the two.
updates := store.Watch(stream.Context())
for _, change := range store.Since(seen) {
if err := sendChange(stream, change); err != nil {
return err
}
seen = change.Seq
}
for {
select {
case <-stream.Context().Done():
return nil
case change := <-updates:
if change.Seq <= seen {
// Already sent from the backlog above.
continue
}
if err := sendChange(stream, change); err != nil {
return err
}
seen = change.Seq
}
}
}
```
`LastEventID` is a value the client controls, so treat it as input rather than as a cursor
to be trusted.
## What a stream bounds
A stream costs a connection and a goroutine for as long as a client cares to hold it.
| A client that... | ...is stopped by |
|---|---|
| stops reading a stream that keeps writing | `WriteTimeout`, once the socket buffers between them are full: a write gives up rather than pinning a goroutine and a full buffer. A stream sending only keepalives never fills them |
| opens streams without end | `MaxStreams` per application, then `503` with `Retry-After` |
| opens many from one address | `MaxStreamsPerIP`, so one client cannot take every slot the process has. 16 addresses (one IPv6 /52) fill the defaults |
| holds a stream open for hours | the listener's own timeouts are cleared for it and replaced with a deadline that exists only while a write is in progress, so a healthy stream is never cut off and an unhealthy one still is |
| holds a stream open and reads nothing at all | `MaxLifetime`, when the route sets one. Nothing else can tell it from a listener, because the write timeout bounds one write and a keepalive is a few bytes that never fill a socket buffer |
| sends a `Last-Event-ID` a handler echoes | a name or identifier with a line break in it is refused |
| reads through a buffering proxy | `Cache-Control: no-cache, no-transform`, `X-Accel-Buffering: no`, and a keepalive comment every `KeepAlive` |
None of the defaults bounds how long a stream lasts, and on a route anyone can open that leaves
the whole budget to whoever takes it first. A client that reads nothing is never ended by
`WriteTimeout`, and with `MaxLifetime` unset nothing else ends it. `MaxStreams` divided by
`MaxStreamsPerIP` is how many addresses fill the process: 1024 / 64 = 16 with the defaults,
which is sixteen IPv4 addresses, or sixteen IPv6 /56 prefixes, a single /52. Each opens 64
streams and reads none of them, and every other stream is refused with `503` until they let go.
A route that clients you do not control can open is worth more than the defaults:
- **Put it behind a guard that authenticates the client** where it can be. That is the only
thing that ties a stream to someone rather than to an address.
- **Raise `MaxStreams` and lower `MaxStreamsPerIP`**, so that the one divided by the other is
larger than the number of addresses an abuser can be expected to have. `MaxStreams` can go as
far as the file descriptor limit allows. How low `MaxStreamsPerIP` can go depends on who
shares an address: one browser needs a stream per open tab, while an office or a carrier's NAT
puts many users behind one.
- **Count IPv6 clients by their /48** with `ClientIPOptions.ConnectionIPv6Prefix: 48`, which
makes each of those addresses cost a whole site's allocation.
- **Set `MaxLifetime`, to minutes rather than hours**, so that a stream whose client has stopped
listening is reclaimed and every slot turns over. A browser reconnects and resumes on its own,
so a legitimate client loses nothing. `MaxLifetime` alone does not stop a client that
reconnects as soon as its stream ends, which is what the settings above are for.
```go
app := muzak.New(muzak.AppOptions{
ClientIP: muzak.ClientIPOptions{ConnectionIPv6Prefix: 48},
SSE: muzak.SSEOptions{
MaxStreams: 8192,
MaxStreamsPerIP: 8,
MaxLifetime: 15 * time.Minute,
},
})
```
Clearing the listener's read and write deadlines matters more than it sounds. A stream is a
response that does not end, so it would otherwise die at `ServerOptions.WriteTimeout`
however healthy it was, and the read deadline would cancel the request, and with it the
stream, at `ServerOptions.ReadTimeout` and blame the client. The read deadline is cleared once
nothing is left of the request body to read. That is as the stream opens, unless the body was
left to the handler: then it is cleared when the handler has read the body to its end, so that
body is read under `ReadTimeout` as any route's is.
The stream's own deadline is armed **around each write** and taken off afterwards. It used to be
armed before every event and never removed. On HTTP/2 that deadline is a timer that resets the
stream when it fires, so with the default 10 second `WriteTimeout` and 15 second keepalive every
idle stream died before its first keepalive, and browsers reconnected in a loop. Now a graceful
shutdown or a handler's return ends an idle stream cleanly rather than aborting it, since an
interrupt is applied only to a write that is in flight.
### Ending a stream on purpose
`SSEOptions.MaxLifetime` is unset by default, which leaves a stream open for as long as its
handler runs and its client keeps the connection. It is worth setting on any route a client you do
not control can open. When it has passed, the stream writes a closing comment and ends the way a
finished response does. A browser's `EventSource` reconnects on its own, sending the identifier of
the last event it saw in `Last-Event-ID`, so a handler that resumes from `stream.LastEventID()`
loses nothing.
```go
muzak.WithSSE(muzak.SSEOptions{MaxLifetime: 30 * time.Minute})
```
The handler is told the way it is told of a disconnect, through `stream.Context()` and the
`ErrSSEStreamEnded` every later send reports, and the stream's slot is released when the handler
returns. A stream is not cut mid-event: the ceiling is applied between events. Nothing is written
after the closing comment, where a keepalive already waiting for the write lock could go out
behind it. A negative value removes a bound a wider scope set. A client that does not reconnect on
its own, a script using `SSEDial` for instance, must be written to.
## Options
| Field | Default | Effect |
|---|---|---|
| `KeepAlive` | 15s | How often a comment is written to a stream that has sent nothing. A negative value turns it off |
| `WriteTimeout` | 10s | How long one event may take to reach the client. It bounds a stalled write, not a stream's age. Negative removes it |
| `MaxLifetime` | none | The longest a stream stays open. Negative removes a bound a wider scope set |
| `Retry` | unset | The reconnection delay advertised at the start of every stream |
| `MaxStreams` | 1024 | Streams the application serves at once. Application-level only |
| `MaxStreamsPerIP` | 64 | Streams one address holds at once, counting an IPv6 client by its /56. Application-level only |
Set them application-wide through `AppOptions.SSE` and narrow them for a router or a route
with `WithSSE`. Layering works field by field, so a route that only lengthens the keepalive
keeps the application's write timeout.
`MaxStreams` and `MaxStreamsPerIP` may only be set on the application: the resource they
protect is the process, not a route, so a router or a route that sets either is refused when
the application is built.
The keepalive exists because a proxy that sees an idle connection for long enough closes
it, and because a silent stream is indistinguishable from a dead one. A keepalive arrives every
interval, measured from the last write. It used to wait on fixed ticks and skip a tick whose last
write was younger than the interval; its own write lands a hair after its tick, so the tick after
it always skipped, and a keepalive asked for every 15 seconds arrived at 15, 45 and 60, twice the
silence a proxy idle timeout was meant to be kept off with. This was seen behind Cloud Run. The
keepalive clock is monotonic, so a wall-clock step cannot starve it.
A stream whose response cannot carry write deadlines is still served, but its `WriteTimeout` is
not enforced. Middleware that wraps the response writer, forwards `Flush` and has no
`Unwrap() http.ResponseWriter` method hides the connection's deadlines, and the first stream on
each route logs a warning naming which writer stopped the chain. Give the wrapper an `Unwrap`.
## What does not apply
**Compression leaves an event stream alone.** Holding events in a compressor's window until
something forces them out is the one thing a stream cannot survive.
**The origin check a WebSocket needs has no counterpart here.** An `EventSource` is subject
to the same-origin policy and to CORS like any other request, so `AppOptions.CORS` already
governs it. See [CORS](/docs/security/cors).
**Nothing a handler fails with is disclosed.** The response header went out before the
handler ran, so a failure ends the stream and the reason goes to the log.
## Shutdown
Open streams are tracked, so a graceful shutdown ends every one of them and waits for the
handlers, instead of waiting out its whole deadline once per stream. An idle stream ends
cleanly. Streams are ended once readiness has turned unavailable and `ServerOptions.DrainDelay`
has passed, as the listeners close and ordinary requests drain, and the background tasks and
lifecycle components are dealt with only after the handlers have returned. See
[Lifecycle](/docs/getting-started/lifecycle#shutdown). A shutdown can also arrive while a stream is still opening: it is decided under the lock,
and the header is written as an armed write a shutdown can stop, so an interrupt landing in that
window is not lost.
## Documentation
An SSE route is documented with a `200` response carrying `text/event-stream`, whose schema
describes the data field of a single event. OpenAPI 3.1 has no way to say "many of these,
one after another", and one event's data is the only part a client has to be able to
decode. A stream whose model is `muzak.Empty` is documented with no schema at all. The `503` a
draining or full server answers with is documented too, and a status a route declared with
`WithResponseDoc` keeps its own description.
## Testing
```go
func TestStreamItems(t *testing.T) {
client := testclient.New(t, buildApp())
stream := client.SSE("/items/stream")
client.Post("/items/", testclient.JSON(map[string]string{"id": "plumbus", "name": "Plumbus"})).
AssertStatus(http.StatusCreated)
item := stream.Decode[schemas.ItemOut]()
if item.ID != "plumbus" {
t.Errorf("id = %q, want plumbus", item.ID)
}
}
```
`muzak.SSEDial` is the reading half of the same engine, so a route is tested over a real
connection rather than against a second implementation:
```go
reader, _, err := muzak.SSEDial(ctx, "http://"+app.Addr()+"/items/stream", muzak.SSEDialOptions{})
if err != nil {
return err
}
defer reader.Close()
for {
message, err := reader.Next(ctx)
if errors.Is(err, muzak.ErrSSEStreamEnded) {
return nil
}
if err != nil {
return err
}
item, err := message.Decode[schemas.ItemOut]()
if err != nil {
return err
}
_ = item
}
```
A response that is not `200` with a `text/event-stream` body is refused rather than parsed,
because a stream reader that quietly accepts an HTML error page reports "no events" for what
is actually a failure. `SSEDialOptions` carries the method, body, headers, a `LastEventID`
to resume from, a read limit, a read timeout, a handshake timeout and `KeepComments` for seeing
the keepalives.
`reader.Close` may be called from another goroutine, and releases a `Next` that is waiting. Once a
reader has been closed, or a read cancelled or timed out, `Next` reports `ErrSSEStreamEnded` even
for an event that had already arrived and was waiting in the buffer.
A few things `SSEDial` does not do, on purpose:
- **It does not follow redirects.** A `3xx` is refused and the response returned with the error.
Dial the `Location` yourself if it is trusted. It used to send custom headers such as
`X-Api-Key` to another host, and `Authorization` over an https-to-http downgrade.
- **Opening a stream is bounded.** It removes the supplied client's `Timeout` so that it does not
cut the stream short, and used to put nothing in its place, so a server that accepted the request
and never answered held the call for as long as a context without a deadline lasts.
`SSEDialOptions.HandshakeTimeout` now bounds it, defaulting to the `Timeout` of the supplied
`HTTPClient` when it has one and otherwise to `muzak.DefaultSSEHandshakeTimeout` (30 seconds); a
negative value removes the bound. It ends when the stream is open and says nothing about how
long the stream lasts or idles. A server that takes longer than 30 seconds to send response
headers needs it set higher, or negative.
- **`SSEReader.Retry` is capped at an hour and accepts digits only.** A `retry:` field was parsed
with `ParseInt` and multiplied into a duration, so a server sending `9223372036855` made
`Retry()` negative, and a client that sleeps for it reconnected in a tight loop. A value with a
sign, a space or an exponent is now ignored as the format requires, and a value beyond an hour is
reported as an hour.
- **`SSEReader.LastEventID` moves only when an event completes.** An `id` is held in a buffer, as
the HTML specification keeps it, and becomes the last event ID when the blank line that ends its
event arrives, whether or not the event carried data. An event the stream cut off part way, by
dropping, by running past the read timeout or by exceeding the read limit, leaves it where it
was, so a reconnect that passes it to `SSEDialOptions.LastEventID` asks for that event again
rather than for the one after it.
## Where to go next
[WebSockets](/docs/realtime/websockets) covers the two-way half, and
[Testing](/docs/fundamentals/testing) covers asserting on a stream.
--------------------------------------------------------------------------------
title: "Safe Defaults"
description: "Every default in Muzak is the conservative one. This is the full list, what each one stops, and how to relax it deliberately."
version: "0.3.0"
last_updated: "2026-10-10T06:43:18.000Z"
source: "https://muzak.dev/docs/0.3.0/security/safe-defaults"
--------------------------------------------------------------------------------
# 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
| Area | Default | Relax it with |
|---|---|---|
| Listener timeouts | All four are non-zero. An `http.Server` left at its zero values holds a connection open forever, which is all a slow-loris client needs. Over HTTP/2, `WriteTimeout` also closes a connection whose socket accepts no bytes for that long | `ServerOptions`, a negative value to disable one |
| Request bodies | Capped at 1 MiB. A body that declares a `Content-Length` over the limit is refused before any of it is read | `AppOptions.MaxBodySize`, `MaxBodySize(n)` |
| Form bodies | A route that declares a `file` field is capped at 32 MiB. A route that binds only `form` values is capped at 1 MiB, urlencoded or multipart | `AppOptions.MaxUploadSize`, `MaxUploadSize(n)`, `MaxBodySize(n)` |
| Request headers | The header block is capped at 64 KiB | `ServerOptions.MaxHeaderBytes` |
| JSON bodies | A body with no `Content-Type` is refused with `415`, so a page cannot drive a JSON route cross-site without a CORS preflight | not relaxable |
| Unknown JSON members | Rejected. A client's typo becomes an immediate `422` instead of a silently dropped value. A member naming a path, query, header or cookie field is unknown too | `AllowUnknownFields()` |
| Duplicate members, invalid UTF-8 | Rejected by `encoding/json/v2` | not relaxable |
| Located fields | A `path`, `query`, `header`, `cookie`, `form` or `file` tag the binder cannot reach is a build error, so a request cannot set it from the JSON body | not relaxable |
| Numbers | `NaN` and infinity are refused in a parameter and by `validate.Number` | not relaxable |
| Number parameters | JSON's decimal grammar only: hexadecimal, `1_000`, `.5` and a leading `+` are refused, so a proxy reading the number by JSON's rules sees the value the handler does | not relaxable |
| URL rules | `URL()`, `HTTPS()` and `URLWithSchemes()` require a hostname, so `http://:8080/`, which an HTTP client dials as the local machine, is refused | not relaxable |
| Scalar parameters sent twice | A query, header or form parameter that holds one value is refused with `422` when sent more than once, rather than one of its values being chosen | declare a slice to accept a list |
| Cross-origin requests | Denied. No CORS header is emitted until a policy is configured, and a wildcard origin with credentials is refused outright. Every response under a named-origin policy carries `Vary: Origin` | `AppOptions.CORS` |
| Cross-site request forgery | Refused once `AppOptions.CrossOriginProtection` is set: a request a browser sends from another origin with any method but GET, HEAD and OPTIONS is answered `403` before any middleware, guard or handler runs, with no token to manage. See [Cross-Origin Requests](/docs/security/cross-origin-requests) | `TrustedOrigins`, `InsecureBypassPatterns` |
| Sessions | Off until configured. Once on, the cookie is HttpOnly, Secure, SameSite=Lax and named `__Host-session`, its contents are encrypted and authenticated, and `CrossOriginProtection` is required beside it, so a cookie a browser attaches on its own cannot be ridden from another site. See [Sessions](/docs/security/sessions) | `SessionOptions.SameSite`, `AllowInsecure`, `Name` |
| Cross-origin WebSocket handshakes | Refused. A handshake is not subject to the same-origin policy and is never preflighted, so CORS cannot cover it. The origin is read strictly, and a handshake with more than one `Origin` is refused | `WSOptions.AllowedOrigins` |
| WebSocket and DNS rebinding | The server's own origin is any whose host is the request's `Host`, until a route lists the names it answers to in `WSOptions.AllowedHosts`. `AppOptions.AllowedHosts` goes further: a request for any other host, a handshake included, is refused with `421` before it reaches a route | `WSOptions.AllowedHosts`, `AppOptions.AllowedHosts` |
| WebSocket messages | Capped at 1 MiB, refused with `1009` before any of the payload is buffered, read a chunk at a time. The length check cannot overflow | `WSOptions.ReadLimit` |
| WebSocket message time | One message has 30 seconds to arrive once it has begun, and a bounded number of frames to arrive in. Idle connections are left alone | `WSOptions.ReadTimeout` |
| WebSocket keepalive | On: a ping every 30 seconds, closed when nothing at all arrived for 10 seconds after a ping, whenever the handler was reading during it | `WSOptions.PingInterval`, `PongTimeout`, a negative `PingInterval` to disable |
| WebSocket connections | 1024 per application and 64 per address, then `503` with a `Retry-After`. A slot is held until the socket is actually closed. 16 addresses (one IPv6 /52) whose peers answer every ping and send nothing hold every slot unless `MaxLifetime` is set | `WSOptions.MaxConnections`, `MaxConnectionsPerIP` |
| WebSocket and event stream age | Unbounded, until a route sets one | `WSOptions.MaxLifetime`, `SSEOptions.MaxLifetime` |
| WebSocket extensions | None negotiated, so no peer can ask the server to hold compression state on its behalf | not relaxable |
| Event stream writes | Given up on after 10 seconds, so a client that stops reading a stream that keeps writing cannot pin a goroutine and a full socket buffer once the buffers between them fill. A stream that sends only keepalives never fills them, and is never ended by this | `SSEOptions.WriteTimeout` |
| Event streams | 1024 per application and 64 per address, with a keepalive comment every 15 seconds. 16 addresses (one IPv6 /52) that read nothing hold every slot unless `MaxLifetime` is set | `SSEOptions.MaxStreams`, `MaxStreamsPerIP`, `KeepAlive` |
| Per-address counts | An IPv4 client is counted exactly and an IPv6 client by its /56, for the connection caps and the rate limit alike | `ClientIPOptions.ConnectionIPv6Prefix`, `ConnectionIPv4Prefix` |
| Event fields | A name or identifier carrying a line break is refused, because it would end its own field and let what follows be read as events of its own | not relaxable |
| Panics | Logged with a full stack trace, its value cut to 4 KiB, and answered with a generic `500`. Nothing derived from the panic reaches the client | not relaxable |
| A failure after the response started | Logged once and the connection aborted, so a truncated export cannot look complete | not relaxable |
| Errors | An error that does not describe itself becomes an opaque `500` with the real cause logged and never transmitted. A `StatusCoder` renders only its own message, below `500` | `AppOptions.ErrorRenderer` |
| Error responses | Drop the headers set for the response they replace, and are sent `Cache-Control: no-store`, so an error is never served as HTML or cached publicly | `AppOptions.ErrorRenderer` |
| Guarded responses | A route or file mount behind a guard, a request-scoped provider or a verifying security scheme, and any response whose request read its session, is sent `Cache-Control: private, no-cache`, so a CDN cannot hand one user's response to another (an event stream and a WebSocket keep their own). A verifying scheme adds `Vary` on the header its credential arrives in, and a session `Vary: Cookie`. A response carrying the session cookie stays private whatever sets `Cache-Control` after it | set `Cache-Control` in the handler, except on a response that carries the session cookie |
| Request identifiers | Not trusted from the client, because an attacker-controlled identifier is an attacker-controlled log field | `AppOptions.TrustRequestIDHeader` |
| Trace context | Off until a `Tracer` is named. A span is named after the route template, never the path, which carries identifiers, and `traceparent` and `tracestate` are read strictly. A valid `traceparent` is continued by default, so a service the internet reaches should believe only its proxy's. See [Observability](/docs/fundamentals/observability) | `TracingOptions.Parent` |
| Forwarding headers | Not believed. `X-Forwarded-For` is read only for a request that arrived from a proxy named in `TrustedProxies`, and from the right | `AppOptions.ClientIP` |
| Host header | Not checked until the application lists the hosts it serves; then a request for any other is answered `421` before anything else runs, and an HTTPS redirect only ever names a listed host. See [Allowed Hosts and HTTPS](/docs/security/hosts-and-https) | `AppOptions.AllowedHosts`, `AppOptions.RedirectHTTPS` |
| Rate limiting | Off until a policy names a quota. Once one exists, counters are bounded in number and in key length, a full table makes room within the quota being counted (only a quota holding no counter takes one from the largest), a storage that stops answering is cut off after 2 seconds, and a storage that fails refuses traffic | `AppOptions.RateLimit`, `FailOpen`, `StorageTimeout` |
| Secrets in logs | Any attribute key that contains a term such as `authorization`, `token`, `api-key`, `password`, `session`, `jwt` or `dsn` is redacted, and so is every value inside a matching group and every matching entry of a logged `http.Header`, `url.Values` or string map | `LoggerOptions.RedactKeys` |
| Log records | One line each. Control characters, C1 controls, bidirectional controls and invalid UTF-8 are escaped, so a request path cannot forge a line or drive a terminal | not relaxable |
| Token comparison | Constant-time, over hashed inputs, so neither the contents nor the length of a secret leaks through timing | `muzak.SecureCompare` |
| Security headers | `X-Content-Type-Options`, `X-Frame-Options` and a referrer policy on every response, and `Strict-Transport-Security` on a response over TLS (not for localhost or an address). No `Content-Security-Policy`: a page sets its own | `AppOptions.DisableSecurityHeaders` |
| Documentation UI | Not served at all until `AppOptions.DocsUI` names one. A page that is configured is embedded in the binary, fetches nothing from a third party, is served under a content security policy that hashes its own inline script and permits no network access beyond this origin, runs the application's guards and providers, and counts against its rate limit | `AppOptions.DocsUI`, `AppOptions.DisableDocs` |
| Static files | A dotfile answers `404`, a file's type comes from its extension and never its content, HTML and SVG are sent under `Content-Security-Policy: sandbox`, a symbolic link cannot leave the directory, and a directory with a mount of its own is reachable only through it | `AllowDotfiles`, `AllowActiveContent` |
| File mounts | Run the rate limit, the guards and every provider of the router they were registered on | `SkipRateLimit()`, a router without them |
| Files and byte bodies | `Bytes`, `Stream` and `FileResponse` are sent with `X-Content-Type-Options: nosniff`. A `FileResponse` takes its type from the file's extension, never its content, refuses a dotfile, and sends HTML, SVG and XML sandboxed. See [Files, Streams and Redirects](/docs/techniques/files-streams-redirects) | `FileResponse.AllowActiveContent` |
| Redirects | `muzak.Redirect` accepts only a path on this origin. `//`, `/\`, control characters and a path that decodes or resolves to another host are refused, and an absolute URL is sent only to a host the route lists | `RedirectHosts(...)`, `Redirect.External` |
| Outbound requests | `muzak.NewClient` refuses loopback, private, link-local and cloud metadata addresses at the moment it connects, so a name that resolves to one, DNS rebinding and a redirect all meet the same check. Every call is bounded (30 seconds, a 10 MiB body, five redirects, never from https to http), and only a request that is safe to send twice is retried. See [HTTP Client](/docs/techniques/http-client) | `ClientOptions.AllowPrivateNetworks`, `AllowedNetworks`, `DeniedNetworks` |
| Configuration | A `required` setting refuses an empty value, and a value read by a `secret` field is hidden from every other field that reads the same variable | drop `required`, or give it a `default` |
| Validation | Automatic for any model that declares rules. There is no option to remember, so a model cannot be left unvalidated by forgetting one. A report holds at most 100 failures and follows nested models 32 levels deep, and `Unique()` is linear in the size of the collection | `SkipValidation()` |
| Versioning | Off until a type is named. Once on, a route that declares no version answers nothing rather than being served unversioned, so a resource is opted into being version-independent deliberately. A header sent on several lines names no version | `AppOptions.Versioning`, `WithVersion`, `VersionNeutral` |
| Late configuration | `Use`, `Include`, route and mount registration after the application was built panic, so a guard added late cannot be dropped silently | not relaxable |
## 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](/docs/techniques/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.
```go
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.
```go
// 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](/docs/deployment/behind-a-proxy).
- **`CORS`** if a browser on another origin calls the API. See [CORS](/docs/security/cors).
- **`CrossOriginProtection`** if a browser sends the service cookies, which sessions require
anyway. See [Cross-Origin Requests](/docs/security/cross-origin-requests) and
[Sessions](/docs/security/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](/docs/security/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](/docs/realtime/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](/docs/techniques/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](/docs/deployment/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](/docs/security/authentication) covers proving who a caller is,
and [Behind a Proxy](/docs/deployment/behind-a-proxy) covers the one default that
is wrong in the other direction behind a load balancer.
--------------------------------------------------------------------------------
title: "Authentication"
description: "Security schemes that enforce what they document, JWT bearer tokens verified against a key set, API keys compared in constant time, and the guards, providers and sessions for everything else."
version: "0.3.0"
last_updated: "2026-10-10T06:44:46.000Z"
source: "https://muzak.dev/docs/0.3.0/security/authentication"
--------------------------------------------------------------------------------
# Authentication
Authentication in Muzak is declared once. A **verifying security scheme** is written into the
OpenAPI document like any other scheme, and a route that names it in `WithSecurity` refuses a
request without a valid credential before any guard, provider or handler runs. The document
and the behaviour are one declaration, so they cannot drift apart.
Two verifying schemes ship with the framework: `muzak.JWTBearer` for bearer tokens issued by
an identity provider, and `muzak.APIKeyVerifier` for API keys. Anything they do not cover, a
browser session, a signed webhook, a credential checked against your own database, is a
**guard** or a **provider**, exactly as before.
| You need | Use |
|---|---|
| Tokens from an OAuth or OpenID Connect provider | `muzak.JWTBearer` with `JWKS` |
| Tokens you sign yourself | `muzak.JWTBearer` with `Keys` |
| API keys for partners or services | `muzak.APIKeyVerifier` |
| One shared secret for an internal route | `muzak.RequireBearerToken` or `muzak.RequireHeaderToken` |
| A browser session | `AppOptions.Sessions` and a provider that reads `ctx.Session()` |
| A signature over the request body | `muzak.CaptureBody` and a guard |
## JWT bearer tokens
```go
app := muzak.New(muzak.AppOptions{
Title: "Orders API",
SecuritySchemes: map[string]muzak.SecurityScheme{
"oidc": muzak.JWTBearer(muzak.JWTOptions{
Issuers: []string{"https://login.example.com/"},
Audience: "https://api.example.com",
Algorithms: []string{"RS256"},
JWKS: muzak.JWKSOptions{
URL: "https://login.example.com/.well-known/jwks.json",
},
}),
},
})
orders := muzak.NewRouter(muzak.WithSecurity(muzak.Require("oidc", "orders:read")))
orders.Get("/orders", handlers.ListOrders)
orders.Get("/orders/health", handlers.Health, muzak.Public())
app.Include(orders, muzak.WithPrefix("/v1"))
```
A request to `/v1/orders` without `Authorization: Bearer ` is answered with `401` before
`ListOrders` runs. A valid token that does not grant `orders:read` is answered with `403`.
`/v1/orders/health` is open, because `Public()` exempts it.
The issuers, the audience and the algorithms are required. There is no default that accepts
whatever a token says: a scheme that leaves one out is a build error.
Every key of a scheme is trusted for every issuer it lists, so a token signed with one
issuer's key may name another listed issuer as its own. List several issuers in one scheme
only when they share their keys, as the spellings of one identity provider's issuer do. Two
identity providers are two schemes, offered as alternatives:
`muzak.WithSecurity(muzak.Require("workforce"), muzak.Require("customers"))`.
| Option | What it decides |
|---|---|
| `Issuers` | The `iss` values accepted, compared exactly |
| `Audience` | The value `aud` must contain, as a string or one entry of an array |
| `Algorithms` | The allowlist of JWS algorithms; `none` is never accepted |
| `Keys` | Keys configured in the application, each optionally with a `kid` |
| `JWKS` | A key set fetched from the issuer and kept fresh |
| `Leeway` | Clock skew allowed on `exp`, `nbf` and `iat`; 60 seconds by default, at most 5 minutes |
| `AllowNoExpiry` | Accept a token without `exp`; off by default |
| `Types` | Accepted `typ` values; `JWT` and `at+jwt` by default |
| `MaxTokenBytes` | Longest token read; 8 KiB by default, at most 64 KiB |
| `Realm` | The realm the `WWW-Authenticate` challenge names; `api` by default |
| `ResourceMetadata` | Publish RFC 9728 metadata; off by default |
### Reading the claims
The verified claims are a `*muzak.Claims`, available as a `Dep`, through `muzak.From` and
through `muzak.TryFrom`.
::code-group
```go [schemas/orders.go]
type ListOrdersIn struct {
Limit int `query:"limit" default:"20"`
Claims muzak.Dep[*muzak.Claims]
}
```
```go [handlers/orders.go]
func ListOrders(ctx *muzak.Context, in schemas.ListOrdersIn) ([]schemas.Order, error) {
claims := in.Claims.Get()
return store.OrdersOf(ctx.Context(), claims.Subject, in.Limit)
}
```
::
`Claims` holds the registered claims Muzak checked: `Issuer`, `Subject`, `Audience`,
`ExpiresAt`, `NotBefore`, `IssuedAt`, `ID`, the `Scopes` granted by `scope` or `scp`, and
the `KeyID` and `Algorithm` of the header. `Raw` is the payload as it was signed.
A `Dep[*muzak.Claims]` is checked when the application is built: every way into the route must
go through a JWT scheme. A route that also admits an API key, or anonymous requests, reads the
claims with `muzak.TryFrom[*muzak.Claims](ctx)` instead, and the build error says so. See
[Dependencies](/docs/getting-started/dependencies) for `Dep`, `From` and `TryFrom`.
### Custom claims
`muzak.ClaimsAs` decodes the payload into a type of your own, once per request and type.
```go
type TenantClaims struct {
Tenant string `json:"tid"`
Roles []string `json:"roles"`
}
tenant, err := muzak.ClaimsAs[TenantClaims](ctx)
if err != nil {
return Out{}, err // a 401, with the reason logged
}
```
To hand them to a handler as a dependency, wrap the call in a provider:
```go
muzak.Needs(func(ctx *muzak.Context) (TenantClaims, error) {
return muzak.ClaimsAs[TenantClaims](ctx)
})
```
### What a token has to be
A token is accepted only when every one of these holds. A token that fails any of them gets
the same `401`, and nothing says which check failed.
- **Its shape.** A JWS compact serialization of three segments, no longer than
`MaxTokenBytes`, each segment in strict base64url: no padding, no `+` or `/`, no whitespace,
and no non-zero trailing bits, so that each token has exactly one spelling.
- **Its header.** A JSON object no deeper than four levels and no larger than 2 KiB, without a
repeated member, naming an algorithm on the allowlist. A `typ`, when present, is one of
`Types`. A token carrying `crit`, `jku`, `jwk`, `x5u`, `x5c`, `enc` or `zip`, or a `cty` of
`JWT`, is refused.
- **Its signature.** Checked with a key of the algorithm's own kind. A token naming a `kid` is
checked only against keys with that `kid`, and one naming none only against keys that have
none. ECDSA signatures are the raw `r||s` form of exactly the curve's width.
- **Its claims.** A JSON object no deeper than sixteen levels, without a repeated member. `iss`
is one of `Issuers`, `aud` contains `Audience`, `exp` is in the future, and `nbf` and `iat`
are not, each within the leeway. Dates are JSON numbers, fractional or not, between 0 and the
end of the year 9999.
The payload is read only after the signature has verified.
### Keys and algorithms
A key is used only by algorithms of its own kind. This is what defeats the classic
algorithm-confusion attack, where a token signed with HS256 uses the server's RSA public key as
its HMAC secret: an RSA key is never an HMAC secret, whatever the token says.
| Algorithms | Key |
|---|---|
| `HS256`, `HS384`, `HS512` | `Secret`, at least as long as the hash: 32, 48 or 64 bytes |
| `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512` | `*rsa.PublicKey` of at least 2048 bits |
| `ES256`, `ES384`, `ES512` | `*ecdsa.PublicKey` on P-256, P-384 or P-521 respectively |
| `EdDSA`, `Ed25519` | `ed25519.PublicKey` |
```go
muzak.JWTBearer(muzak.JWTOptions{
Issuers: []string{"orders-service"},
Audience: "orders-api",
Algorithms: []string{"HS256"},
Keys: []muzak.JWTKey{
{ID: "2026-10", Secret: settings.SigningKey},
{ID: "2026-07", Secret: settings.PreviousSigningKey},
},
})
```
A short RSA key, a private key passed where the public one belongs, an ECDSA key on a curve no
allowed algorithm uses, a point that is not on its curve and an HMAC secret shorter than its
hash are all build errors. `JWTKey.Algorithm` pins a key to one algorithm, which is how a
32-byte secret is used for HS256 while HS512 is allowed for another key.
### Key sets
With `JWKS.URL` set, the scheme fetches the issuer's JSON Web Key Set and keeps it.
| `JWKSOptions` | Default | Bound |
|---|---|---|
| `Client` | `muzak.NewClient` with public addresses only | An `*http.Client` is accepted too |
| `MaxBytes` | 1 MiB | The document is refused past it |
| `MaxKeys` | 32 | At most 1024; a document with more is refused whole |
| `Timeout` | 10 seconds | Per fetch |
| `MinRefreshInterval` | 30 seconds | Least time between two fetches |
| `MinCacheTTL`, `MaxCacheTTL` | 5 minutes, 24 hours | Bounds on the response's `max-age` |
- **Fetched over https.** Plain http is accepted only for a loopback address, in a test. The
same holds for every URL a redirect leads to: a set that arrives over plain http from
anywhere else is refused, so a redirect down to http cannot replace the keys.
- **Through the SSRF-safe client.** The default client refuses private, loopback and link-local
addresses. An identity provider on a private network, such as a Keycloak beside the service,
needs `muzak.NewClient(muzak.ClientOptions{AllowPrivateNetworks: true})`, or `AllowedNetworks`
naming its subnet. See [HTTP Client](/docs/techniques/http-client). The size limit and the
timeout apply whichever client you pass.
- **Cached as the issuer says.** `Cache-Control: max-age` decides how long a set is kept, held
within `MinCacheTTL` and `MaxCacheTTL`; a response without one is kept for an hour.
- **Refreshed in the background.** The set is a lifecycle component named `jwks `. It
is fetched as the application starts, without holding the start up, and again in the last
tenth of each copy's life, so a token rarely waits for it.
- **Fetched by the first request that needs one.** A token that arrives while no set is held
(in a test without the lifecycle, or before the first background fetch has finished) starts
a fetch, and that request waits for it up to `Timeout`, whatever its own deadline, so that
its client leaving does not fail the fetch for everyone else. A request waiting for a fetch
another one started stops waiting when its own context ends.
- **Rotation without a flood.** A token naming a `kid` the set does not hold makes it fetched
again, at most once per `MinRefreshInterval` however many such tokens arrive, and every
request waiting for the same fetch shares it. A token with a random `kid` costs the issuer
nothing.
- **The last good set is kept.** A fetch that fails, answers with an error, sends something that
is not a key set or sends one that is too large keeps the set already in use, and the failure
is logged. There is no age past which the last good set is dropped, however long fetches keep
failing, so watch the log for them. Until a first fetch has succeeded, a token is answered
with `503`, which is the server's failure and not the client's.
- **Strict keys.** Only `RSA`, `EC` and `OKP` keys are read: a symmetric `oct` key in a public
set is a secret anyone can read and is never used. A key must be meant for signatures (`use`
absent or `sig`, `key_ops` absent or allowing `verify`), its `alg`, when present, must be
allowed and fit the key, an EC point must be on its curve, an RSA modulus must be 2048 to 8192
bits, and a key carrying private members is refused. A key that fails is skipped without
costing the rest of the set.
### Scopes
The scopes `Require` names are checked against what the token grants: the space-separated
`scope` claim, an `scp` claim that is an array or such a string, or both.
```go
r.Post("/orders", handlers.CreateOrder,
muzak.WithSecurity(muzak.Require("oidc", "orders:write")))
```
A valid token without the scope is answered with `403` and an `insufficient_scope` challenge
naming the scopes required.
## API keys
```go
"partners": muzak.APIKeyVerifier(muzak.APIKeyOptions{
Name: "X-API-Key",
Keys: []muzak.APIKey{
{ID: "acme", Key: settings.AcmeKey, Scopes: []string{"orders:read"}},
{ID: "globex", Key: settings.GlobexKey},
},
}),
```
`In` is `header` by default, or `query` or `cookie`, matching `APIKeyHeader`, `APIKeyQuery`
and `APIKeyCookie` in the document. The verified caller is a `*muzak.APIKeyPrincipal` with an
`ID`, the `Scheme` that verified it and the `Scopes` it grants.
- **Constant time.** Keys are held as SHA-256 digests, and a request's key is hashed and
compared with every one of them without stopping at a match, so neither which key matched,
nor how much of one did, nor how long one is shows in the response time.
- **No ambiguity.** A request that sends the key twice, in two headers, parameters or cookies,
is refused.
- **Never logged.** Neither the key nor its digest reaches a log or a response.
- **Checked at build.** A key under 16 bytes or over 1024 (the most read from a request), two
principals sharing a key and two keys sharing an ID are build errors.
A key in a query string is written to logs and browser history along with the URL, so prefer a
header. A key in a cookie is an ambient credential: the browser attaches it to a request
another site makes it send, as it does a session cookie. Pair a cookie key with
[cross-origin protection](/docs/security/cross-origin-requests), which refuses a
state-changing request a browser sends from another origin.
A key set too large to list, or one stored in a database, is resolved with `Lookup`, which
runs only for a key no static key matched:
```go
Lookup: func(ctx *muzak.Context, key string) (*muzak.APIKeyPrincipal, error) {
digest := sha256.Sum256([]byte(key))
client, err := store.ClientByKeyDigest(ctx.Context(), digest[:])
if errors.Is(err, store.ErrNotFound) {
return nil, nil // 401
}
if err != nil {
return nil, err // 503, logged
}
return &muzak.APIKeyPrincipal{ID: client.Name, Scopes: client.Scopes}, nil
},
```
Store keys as digests, as above, so a leaked table is not a leaked set of keys. A lookup error is
logged, so it must not quote the key.
## Combining schemes
`WithSecurity` takes alternatives, and a `SecurityRequirement` names schemes that are needed
together. Muzak enforces both exactly as the document describes them.
```go
// A token, or a partner key.
muzak.WithSecurity(muzak.Require("oidc"), muzak.Require("partners"))
// A token and a partner key together.
muzak.WithSecurity(muzak.SecurityRequirement{"oidc": nil, "partners": nil})
// A token when there is one, anonymous otherwise.
muzak.WithSecurity(muzak.Require("oidc"), muzak.SecurityRequirement{})
```
The first requirement a request meets admits it, and its principals reach the route. A request
that presents a credential is judged by it even where anonymous requests are admitted: an
expired token is refused rather than quietly served as nobody, so the client learns it needs a
new one.
A route may name a verifying scheme and a descriptive one in **one** requirement: the verifying
one is enforced, and the guard that checks the other refuses on its own. Alternatives that mix
the two are a build error, because a request that satisfies a described alternative cannot be
told from one that satisfies nothing.
A declaration replaces the one above it instead of adding to it, as it does in the document,
since alternatives and combinations cannot be told apart once they are merged. That cuts both
ways. A route's `WithSecurity` replaces its router's, and an inner router's `Public()`, or its
own `WithSecurity` naming only descriptive schemes, replaces a verifying requirement given
where it is included: the routes beneath it are then no longer enforced. Declare the
requirement on the innermost router that needs it, or check the security list of each
operation in the document.
## What is covered
| Request | Enforced |
|---|---|
| The route itself | Yes |
| `HEAD` answered by a `GET` route | Yes, it is that route |
| `OPTIONS` and `405` from the route table | Nothing runs; they disclose only the methods |
| `Router.Mount`, `Router.Static`, `Router.Frontend` beneath the router | Yes, they inherit its declaration |
| `/openapi.json` and `/docs` | Yes, for a declaration on `muzak.New` itself |
| A route or mount with `Public()` | No |
The gate runs after the rate limit is counted, so a client guessing tokens spends its budget,
before a body `CaptureBody` keeps is read, so a request without a valid credential cannot make
the server buffer one, and before every guard and provider, so neither ever sees an
unauthenticated request. A response behind a verifying scheme carries
`Cache-Control: private, no-cache` unless the handler sets its own, and `Vary: Authorization`
(or the API key's header, or `Cookie`).
Like guards declared on `muzak.New`, a requirement declared there, as in
`muzak.New(opts, muzak.WithSecurity(muzak.Require("oidc")))`, covers `/openapi.json` and
`/docs`. Guarded documentation is sent `Cache-Control: private, no-cache` and counts against the
application's rate limit. To publish the documentation while the API stays private, declare the
requirement where the routers are included instead, or set `AppOptions.DisableDocs` to serve
neither. See [OpenAPI](/docs/fundamentals/openapi#guarding-the-documentation).
## Refusals
| Situation | Status | Challenge |
|---|---|---|
| No credential | `401` | `Bearer realm="api"` |
| A credential that is not valid | `401` | `Bearer realm="api", error="invalid_token"` |
| A valid credential without a required scope | `403` | `Bearer realm="api", error="insufficient_scope", scope="orders:write"` |
| No key set fetched yet, or a lookup failed | `503` | none |
The body is the standard error envelope with its standard sentence, `Authentication is
required.` or `You do not have access to this resource.`, rendered by the configured error
renderer, so `AppOptions.ProblemDetails` applies. It never quotes the token, and never says
whether the signature, the issuer, the audience or the expiry was wrong. An API key scheme
names no challenge, since there is no standard one for it.
## Protected resource metadata
An OAuth client that knows only an API's URL, an MCP client among them, discovers where to get a
token from the API's RFC 9728 metadata. `ResourceMetadata` publishes it:
```go
muzak.JWTBearer(muzak.JWTOptions{
// ...
ResourceMetadata: &muzak.ResourceMetadata{
Resource: "https://api.example.com",
ScopesSupported: []string{"orders:read", "orders:write"},
},
})
```
```http
GET /.well-known/oauth-protected-resource
{
"resource": "https://api.example.com",
"authorization_servers": ["https://login.example.com/"],
"scopes_supported": ["orders:read", "orders:write"],
"bearer_methods_supported": ["header"]
}
```
The document is public, whatever `WithSecurity` the application declares, and left out of the
OpenAPI document. The application's own guards still run for it, as they do for every route, so
an application-wide guard keeps clients from reading it; declare such a guard on an included
router instead. `AuthorizationServers` defaults to the scheme's issuers. A resource with a path,
`https://api.example.com/v1`, is described at `/.well-known/oauth-protected-resource/v1`, as the
RFC places it (`muzak.ProtectedResourcePath` followed by the resource's path). Every challenge
then names it:
```http
WWW-Authenticate: Bearer realm="api", error="invalid_token", resource_metadata="https://api.example.com/.well-known/oauth-protected-resource"
```
It is off by default. The path is the one in `Resource`, served by this application as it
stands, so an application behind a proxy that strips or adds a prefix must make the public URL
and the served path agree. This is the document an MCP client reads to find where to sign in;
see [MCP Tools](/docs/techniques/mcp-tools).
## Shared secrets
For an internal service, a webhook receiver or an admin subtree, the credential is one secret
both sides know. Two guards ship with the framework.
```go
// An Authorization: Bearer header.
muzak.RequireBearerToken(settings.AdminToken)
// Any named header, such as an internal service token or a webhook
// signing key.
muzak.RequireHeaderToken("X-Token", settings.AdminToken)
```
```go [cmd/main.go]
app.Include(routers.Admin(),
muzak.WithPrefix("/admin"),
muzak.WithTags("admin"),
muzak.WithDependencies(muzak.RequireHeaderToken("X-Token", settings.AdminToken)),
)
```
Both compare in constant time, and `RequireBearerToken` answers a missing credential with a
`WWW-Authenticate` header so a client knows which scheme to use. They are guards, so the
document does not know about them unless you declare a descriptive scheme too; see
[Documenting a guard](#documenting-a-guard).
A provider of your own reads a bearer credential with `muzak.BearerToken(ctx)`, which reports
whether a well-formed one was present and matches the scheme name case-insensitively, as RFC
9110 requires.
## Comparing secrets
```go
if !muzak.SecureCompare(given, expected) {
return muzak.Unauthorized("")
}
```
Comparing a credential with `==` leaks its contents: the comparison returns as soon as two
bytes differ, so an attacker who can time the response can recover the secret one byte at a
time. `SecureCompare` hashes both inputs first and compares the digests, which also keeps the
length of the expected secret from leaking.
Use it for tokens, API keys and signatures. It is **not** a password verification function. A
password must be checked against a slow, memory-hard hash such as the one
`golang.org/x/crypto/argon2` provides.
## Resolving a user
A verified token says who the caller is. Your application usually wants its own record of them,
which is a provider that reads the claims:
```go
func GetCurrentUser(ctx *muzak.Context) (CurrentUser, error) {
claims := muzak.From[*muzak.Claims](ctx)
users := muzak.From[*core.UserStore](ctx)
user, err := users.BySubject(ctx.Context(), claims.Subject)
if err != nil {
return CurrentUser{}, muzak.Unauthorized("").Wrap(err)
}
return CurrentUser{Username: user.Username}, nil
}
```
```go
r.Get("/users/me", handlers.CurrentUser,
muzak.WithSecurity(muzak.Require("oidc")),
muzak.Needs(core.GetCurrentUser))
```
The provider runs after the gate, so the claims are always there. `Wrap` records the real cause
in the log and keeps it out of the response. See
[Dependencies](/docs/getting-started/dependencies#providers).
## Signing in with a session
A browser flow exchanges credentials for a session once, then presents the session cookie
with every request. `AppOptions.Sessions` keeps the session, encrypted in the cookie or in a
store, and requires `AppOptions.CrossOriginProtection` beside it; see
[Sessions](/docs/security/sessions) and
[Cross-Origin Requests](/docs/security/cross-origin-requests). The sign-in handler checks the
password and records who signed in:
::code-group
```go [handlers/login.go]
func Login(ctx *muzak.Context, in schemas.LoginIn) (schemas.LoginOut, error) {
expected, known := accounts[in.Username]
// The comparison runs even for an unknown account, and the same answer is
// given either way, so the endpoint is not an account enumerator.
matches := subtle.ConstantTimeCompare([]byte(expected), []byte(in.Password)) == 1
if !known || !matches {
return schemas.LoginOut{}, muzak.Unauthorized("the username or password is incorrect")
}
// A new session first, so a session someone planted in the browser is
// worth nothing at the moment it would have become valuable.
session := ctx.Session()
if err := session.Regenerate(); err != nil {
return schemas.LoginOut{}, err
}
if err := session.Set("user", in.Username); err != nil {
return schemas.LoginOut{}, err
}
return schemas.LoginOut{Username: in.Username}, nil
}
```
```go [routers/login.go]
r.Post("/login/", handlers.Login,
muzak.WithResponseDoc(http.StatusUnauthorized, "The username or password is incorrect"),
// Counted before the handler, so a wrong password costs the same budget
// as a right one.
muzak.RateLimit(muzak.Quota{Name: "login", Window: time.Minute, Limit: 5}))
```
::
Four things matter on a sign-in route, all visible above:
- **The same answer either way.** Telling an unknown account from a wrong password turns the
endpoint into an account enumerator.
- **The same timing either way.** Returning early on an unknown account says the same thing
more quietly, which is why the comparison runs regardless.
- **A rate limit counted before the guards.** A request a guard refuses is still counted, so
failed sign-ins cost the attacker their budget. `RateLimitOptions.AfterDependencies` would
give that up, which is why a sign-in route never uses it.
- **A password checked against a slow hash.** The example compares plain values because there
is nothing to protect in it. A real one stores an argon2 or bcrypt digest.
Resolve the caller on the way back in with a provider:
```go
func GetCurrentUser(ctx *muzak.Context) (CurrentUser, error) {
username, ok := muzak.SessionGet[string](ctx.Session(), "user")
if !ok {
return CurrentUser{}, muzak.Unauthorized("sign in first")
}
return CurrentUser{Username: username}, nil
}
```
## Credentials on a WebSocket
A browser cannot set headers on a WebSocket handshake or an `EventSource`, so a JWT scheme,
which reads `Authorization`, only covers clients that are not browsers. A browser's WebSocket
authenticates with the session cookie it attaches itself, or a short-lived ticket in the query,
resolved by a provider:
```go
func GetTicket(ctx *muzak.Context) (Ticket, error) {
if user, ok := muzak.SessionGet[string](ctx.Session(), "user"); ok {
return Ticket{User: user}, nil
}
if t := ctx.Query("ticket"); t != "" {
return tickets.Redeem(ctx.Context(), t) // single use, short-lived
}
return Ticket{}, muzak.Unauthorized("a session or a ticket is required")
}
```
A cookie is ambient authority a browser attaches without being asked, which is why a
cross-origin handshake is refused by default. A token in a query string ends up in access logs
and browser history; Muzak's own access log records no query strings for that reason. See
[WebSockets](/docs/realtime/websockets).
A credential is judged once, when the connection or the stream opens. A WebSocket or an event
stream that stays open outlives the token that admitted it: nothing closes it when the token's
`exp` passes. Set `WSOptions.MaxLifetime` or `SSEOptions.MaxLifetime` to something near the
lifetime of your tokens, and the client reconnects with a fresh one.
## Verifying a signature over the body
A signed *request* is verified from its bytes. Declare `muzak.CaptureBody()` and the bytes are
kept for the request. They are read after the rate limit is counted and after a verifying
scheme has admitted the request, and before the guards and providers run, so the guard below
refuses an unsigned request before anything decodes it.
```go
r.Post("/webhooks/stripe", handlers.Stripe,
muzak.CaptureBody(),
muzak.Needs(core.VerifyStripeSignature))
```
```go
func VerifyStripeSignature(ctx *muzak.Context) (Verified, error) {
body, ok := ctx.RawBody()
if !ok {
return Verified{}, muzak.NewHTTPError(
http.StatusInternalServerError, "this route does not capture its body")
}
expected := hmac.New(sha256.New, secret)
expected.Write(body)
if !hmac.Equal(expected.Sum(nil), presented) {
return Verified{}, muzak.Unauthorized("the signature does not match")
}
return Verified{}, nil
}
```
**Verify the original, never a re-encoding of it.** Marshalling the bound input back to JSON
produces a different document, and a signature over it never matches.
## Documenting a guard
A guard is a function that Muzak can run and cannot read, so a route protected by one is
documented with a descriptive scheme, which says what the guard checks and enforces nothing:
```go
app := muzak.New(muzak.AppOptions{
SecuritySchemes: map[string]muzak.SecurityScheme{
"admin": muzak.APIKeyHeader("X-Token"), // descriptive
},
})
admin := muzak.NewRouter(
muzak.WithSecurity(muzak.Require("admin")),
muzak.WithDependencies(muzak.RequireHeaderToken("X-Token", settings.AdminToken)),
)
```
`BearerAuth`, `BasicAuth`, `HTTPAuth`, `APIKeyHeader`, `APIKeyQuery`, `APIKeyCookie`, `OAuth2` and
`OpenIDConnect` are descriptive, and behave exactly as they always have. `JWTBearer` and
`APIKeyVerifier` appear in `components.securitySchemes` exactly as `BearerAuth("JWT")` and the
matching `APIKey...` constructor do, so switching a route from a descriptive scheme and a guard
to a verifying scheme changes nothing in the document. See
[OpenAPI](/docs/fundamentals/openapi#declaring-how-a-route-authenticates).
## Testing
A test signs its own tokens with a key the test configures. An HMAC secret is the shortest path:
```go
func testApp(t *testing.T) *muzak.App {
secret := bytes.Repeat([]byte("k"), 32)
return buildApp(muzak.JWTBearer(muzak.JWTOptions{
Issuers: []string{"test"},
Audience: "orders-api",
Algorithms: []string{"HS256"},
Keys: []muzak.JWTKey{{Secret: secret}},
}))
}
```
```go
func TestListOrdersNeedsAToken(t *testing.T) {
client := testclient.New(t, testApp(t))
res := client.Get("/v1/orders")
res.AssertStatus(http.StatusUnauthorized)
res.AssertErrorCode(muzak.CodeUnauthorized)
}
```
`App.Override` replaces providers, and a verifying scheme is not one: like a guard, it keeps
refusing in a test exactly as it does for a client, so a test that wants to be let in presents a
credential. A suite whose every request needs one gives it to the client once:
```go
client := testclient.New(t, testApp(t),
testclient.WithHeader("Authorization", "Bearer "+signTestToken(t)))
```
## Where to go next
[Authorization](/docs/security/authorization) covers what a verified caller is allowed to do,
[Sessions](/docs/security/sessions) covers the session a browser signs in to,
[HTTP Client](/docs/techniques/http-client) covers reaching an identity provider on a private
network, and [MCP Tools](/docs/techniques/mcp-tools) covers serving routes to an MCP client that
signs in through the protected resource metadata.
--------------------------------------------------------------------------------
title: "Authorization"
description: "Deciding what an authenticated caller may do, with guards that cover a subtree, checks that need the resolved identity, and ownership checks in the handler."
version: "0.3.0"
last_updated: "2026-10-10T06:43:18.000Z"
source: "https://muzak.dev/docs/0.3.0/security/authorization"
--------------------------------------------------------------------------------
# Authorization
Authentication answers "who is this". Authorization answers "may they do this". In Muzak
the second is a guard, a provider, or a check in the handler, depending on what the answer
depends on.
| The decision depends on | Put it in |
|---|---|
| The route alone | A guard on the router, declared where it is included |
| The caller's identity or role | A guard or provider that reads the resolved caller |
| The specific record being touched | The handler, after the record is loaded |
## Authorizing a whole subtree
The clearest place for a subtree decision is where the subtree is mounted.
```go [cmd/main.go]
// The admin router is written without a prefix or a guard. Both are applied
// here, which is what keeps that router reusable and puts the security decision
// somewhere a reviewer will find it.
app.Include(routers.Admin(),
muzak.WithPrefix("/admin"),
muzak.WithTags("admin"),
muzak.WithDependencies(core.GetTokenHeader(settings)),
muzak.WithResponseDoc(http.StatusForbidden, "The caller is not an administrator"),
)
```
Guards run in declaration order, outermost first: those declared on the application run
before those declared at the include, which run before the route's own. The first guard to
return an error stops the chain and produces the response.
```go [cmd/main.go]
app := muzak.New(muzak.AppOptions{Title: settings.AppName},
// Runs for every route in the application, including the admin subtree.
muzak.WithDependencies(core.GetQueryToken),
)
```
## Authorizing on a role
Every guard on a request runs before any provider does, whatever scope each was declared
on. A guard therefore cannot read a value a provider produced: `muzak.From` would panic
and `muzak.TryFrom` would report that nothing was resolved.
That is not a limitation to work around. A role check is part of resolving the caller, so
it belongs in the provider, and the result is a type that only exists when the check
passed.
::code-group
```go [core/authorization.go]
// Admin is a caller who has been shown to hold the admin role.
//
// Having one is proof of the check, because the only thing that produces one is
// the provider below.
type Admin struct {
Username string
}
// GetAdmin resolves the caller and insists they are an administrator.
func GetAdmin(ctx *muzak.Context) (Admin, error) {
user, err := GetCurrentUser(ctx)
if err != nil {
return Admin{}, err
}
if !slices.Contains(user.Roles, "admin") {
return Admin{}, muzak.Forbidden("this action requires the admin role")
}
return Admin{Username: user.Username}, nil
}
```
```go [routers/admin.go]
func Admin() *muzak.Router {
r := muzak.NewRouter(muzak.Needs(core.GetAdmin))
r.Post("/", handlers.AdminAction,
muzak.Status(http.StatusCreated),
muzak.Summary("Admin action"),
muzak.Description("Performs a privileged action. Requires the admin role."))
return r
}
```
```go [handlers/admin.go]
func AdminAction(ctx *muzak.Context, in schemas.AdminActionIn) (schemas.AdminActionOut, error) {
// Reaching this line is proof of the check.
admin := muzak.From[core.Admin](ctx)
return schemas.AdminActionOut{Name: in.Name, Message: "acted on by " + admin.Username}, nil
}
```
::
`Needs` on a router applies to every route beneath it, so the whole subtree is covered by
one line.
A check declared **outside** cannot be removed by a declaration of the same type inside. Every
provider along a route's chain runs, outermost first, so an `app.Include(admin, muzak.Needs(RequireAdmin))`
keeps rejecting non-admins even when the admin router, or a route in it, declares
`Needs(CurrentUser)` of the same type. Until 0.2.8 the nearer declaration silently replaced the
outer one, and the outer authorization never ran. `muzak.From` still returns the innermost value.
The same chain, guards and providers alike, protects the files a `Frontend` or `Static` mount
serves and the handler a `Mount` serves: each runs the rate limit, the verifying security
schemes, the guards and every inherited provider of the router it was registered on. Put assets
meant to be public on a router without those options.
When a check does not need the caller's identity, a guard is the simpler tool, and it can
read anything on the request directly:
```go
// RequireMaintenanceWindow refuses a destructive route outside the window it is
// allowed to run in. It reads nothing a provider produced, so a guard is enough.
func RequireMaintenanceWindow(ctx *muzak.Context) error {
if !inMaintenanceWindow(time.Now()) {
return muzak.Forbidden("this action is only available during the maintenance window")
}
return nil
}
```
## Authorizing on a scope
When the caller is proved by a verifying security scheme, a JWT bearer token or an API key
the application checks itself, the scopes a route needs are part of its requirement, and
they are checked before anything of the route runs:
```go [cmd/main.go]
app.Include(routers.Admin(),
muzak.WithPrefix("/admin"),
// A token without the admin scope is refused with 403 before any guard,
// provider or handler beneath this router runs.
muzak.WithSecurity(muzak.Require("oidc", "admin")),
)
```
A credential that is missing or invalid is answered `401`, and one that is valid but lacks a
scope `403`, whose bearer challenge says `insufficient_scope`. The verified caller reaches the route as a
`*muzak.Claims` or a `*muzak.APIKeyPrincipal`, so a provider that decides on a role, as
`GetAdmin` does above, can start from it rather than from a header. See
[Authentication](/docs/security/authentication) for declaring the scheme.
## 401 against 403
| Status | Means |
|---|---|
| `401 Unauthorized` | No usable credential was presented, or the one presented could not be verified |
| `403 Forbidden` | The credential was understood, and it is not enough |
The distinction matters to a client: a `401` says "sign in", a `403` says "signing in again
will not help". Muzak classifies them as `unauthorized` and `forbidden`, which is the
`code` a client should branch on rather than the status.
Where the status alone is too coarse, add a classifier of your own:
```go
return muzak.Forbidden("this workspace is on the free plan").
WithCode("plan_upgrade_required")
```
## Authorizing a specific record
Ownership is not knowable until the record is loaded, so it belongs in the handler.
```go [handlers/items.go]
func UpdateItem(ctx *muzak.Context, in schemas.ItemUpdateIn) (schemas.ItemOut, error) {
store := muzak.From[*core.ItemStore](ctx)
user := muzak.From[core.CurrentUser](ctx)
item, err := store.Get(in.ID)
if err != nil {
return schemas.ItemOut{}, asHTTPError(err)
}
if item.Owner != user.Username {
// The same answer a missing item gets. Telling a caller that an item
// exists but is not theirs turns the endpoint into a way to enumerate
// other people's identifiers.
return schemas.ItemOut{}, muzak.NotFound("Item not found")
}
updated, err := store.Rename(in.ID, in.Name)
if err != nil {
return schemas.ItemOut{}, asHTTPError(err)
}
return schemas.ItemOut{ID: updated.ID, Name: updated.Name, Owner: user.Username}, nil
}
```
Answering `404` rather than `403` for someone else's record is a deliberate choice: a `403`
confirms the record exists. Use it where the existence of the record is not itself a
secret, and `404` where it is.
## Authorization and the response body
The strongest guarantee here is not a check at all. The handler's return type is the
response model, so a field a caller must not see cannot be returned by accident: it is not
part of the type.
```go
// The store's own type. Adding a field here changes nothing a client can see.
type Item struct {
ID string
Name string
Owner string
InternalNote string
}
// What a client receives. Owner is present only where the route resolves the
// caller, and InternalNote has no way to be written at all.
type ItemOut struct {
ID string `json:"id"`
Name string `json:"name"`
Owner string `json:"owner,omitzero"`
}
```
Where two audiences need two shapes, write two output types and two routes rather than one
type with a filtering step.
## Ordering, once more
For every request:
1. Middleware. The allowed-hosts check, the HTTPS redirect, the CORS policy and the
cross-origin check, each when it is configured, run in front of anything installed with
`App.Use`; a health probe is answered before all of them.
2. The rate limit count, unless the policy defers it.
3. The route's `Timeout` deadline starts, when it has one.
4. The verifying security schemes the route's `WithSecurity` names.
5. The body a `CaptureBody` route keeps is read.
6. Guards, outermost first.
7. Providers, in declaration order.
8. The rate limit count, if the policy deferred it.
9. `Dep` fields are filled, then binding.
10. Validation.
11. The handler.
Guards running before validation is what keeps an unauthenticated caller from learning your
schema by sending it garbage, and a verifying scheme judged before the body is read is what
keeps a caller without a valid credential from making the server buffer one.
Rate limiting running before the guards is what makes a rejected request still cost the
caller something. See [Rate Limiting](/docs/techniques/rate-limiting), and
[Dependencies](/docs/getting-started/dependencies#the-order-things-run-in) for what follows the
handler.
## Hiding an endpoint is not authorizing it
```go
r.Get("/healthz", handlers.Health, muzak.Hidden(), muzak.SkipRateLimit())
```
`Hidden` leaves a route fully routable and merely absent from the document. It is right for
a health check or an internal endpoint whose existence is uninteresting; it is not a
substitute for a guard. The probes a platform sends need no route of your own:
`AppOptions.Health` answers them ahead of routing, unauthenticated by design and out of the
document, and says no more than whether the service is up unless `ReportChecks` asks for the
name of each check. See [Health Checks](/docs/deployment/health-checks).
Nor is a guard a way to hide that a path exists. `OPTIONS` and `405` answers come from the route
table alone, as `net/http.ServeMux` answers them, so they skip a route's security schemes,
guards and rate limit:
an unauthenticated client learns which paths exist and which methods they take, and never a
route's data. Middleware installed with `App.Use` still covers them, so put a guard or a limit
there when the existence of a path is itself a secret.
Percent-encoding cannot route a request around a guard either. Static segments are compared
percent-decoded, so `GET /users/%61dmin` reaches the guarded `/users/admin` and is not answered
by a public `/users/{id}` with `id` set to `admin`.
## Testing an authorization rule
```go
func TestAdminActionRequiresTheRole(t *testing.T) {
client := testclient.New(t, buildApp(), authorizedAs("editor"))
res := client.Post("/admin/", testclient.JSON(map[string]string{"name": "plumbus"}))
res.AssertStatus(http.StatusForbidden)
res.AssertErrorCode(muzak.CodeForbidden)
}
func TestUpdatingSomebodyElsesItem(t *testing.T) {
client := testclient.New(t, buildApp(), authorizedAs("morty"))
res := client.Put("/items/ricks-portal-gun", testclient.JSON(map[string]string{"name": "mine now"}))
res.AssertStatus(http.StatusNotFound)
}
```
A test per rule is cheap here, because the client exercises the whole chain: middleware,
guards, providers, binding and the handler.
## Where to go next
[Authentication](/docs/security/authentication) covers producing the identity
these rules read, and [Safe Defaults](/docs/security/safe-defaults) covers what
the framework refuses without being asked.
--------------------------------------------------------------------------------
title: "CORS"
description: "A cross-origin policy that denies everything until it is written down, refuses the one combination browsers reject anyway, and does not cover a WebSocket handshake."
version: "0.3.0"
last_updated: "2026-10-10T09:01:29.000Z"
source: "https://muzak.dev/docs/0.3.0/security/cors"
--------------------------------------------------------------------------------
# CORS
Cross-origin resource sharing is configured rather than installed. The zero value denies
every cross-origin request, and no CORS middleware is installed at all until a policy names
an origin or supplies a decision function.
That is the only safe default. A permissive policy set by accident hands any web page on
the internet the ability to read authenticated responses from the browser of anyone
visiting it.
## Configuring it
```go
app := muzak.New(muzak.AppOptions{
Title: "Awesome API",
CORS: muzak.CORSOptions{
AllowedOrigins: []string{"https://app.example.com", "https://admin.example.com"},
AllowedMethods: []string{"GET", "POST", "PATCH", "DELETE"},
AllowedHeaders: []string{"Content-Type", "Authorization", "X-Request-Id"},
ExposedHeaders: []string{"X-Request-Id", "RateLimit-Remaining"},
AllowCredentials: true,
MaxAge: 10 * time.Minute,
},
})
```
| Field | Default | Effect |
|---|---|---|
| `AllowedOrigins` | none | The exact origins permitted, each written `scheme://host[:port]` in lower case, with no path and no default port. The single entry `"*"` allows any. A pattern and `"null"` are build errors |
| `AllowOriginFunc` | none | A dynamic decision, consulted only for an origin `AllowedOrigins` did not already allow |
| `AllowedMethods` | `GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS` | The methods a cross-origin request may use |
| `AllowedHeaders` | `Content-Type, Authorization, X-Request-Id` | The request headers a client may send |
| `ExposedHeaders` | none | The response headers a client may read. Browsers expose only a small safelist otherwise |
| `AllowCredentials` | off | Permits cookies and `Authorization` headers on cross-origin requests |
| `MaxAge` | 10 minutes | How long a browser may cache the preflight result. Browsers cap it regardless |
Origins are matched exactly, scheme and port included. `https://app.example.com` and
`https://app.example.com:8443` are two different origins, and so are the `http` and `https`
spellings of the same host.
Because an entry is compared byte for byte with the `Origin` header a browser writes, an entry
spelled any other way would allow nobody, so it is refused when the application is built, with
the spelling to use instead:
- a trailing slash, as in `https://app.example.com/`, or any other path, query or fragment
- upper case in the scheme or host, as in `HTTPS://App.example.com`
- the scheme's default port, as in `https://app.example.com:443` or `http://app.example.com:80`
- a pattern such as `*.example.com`, which belongs in `AllowOriginFunc`
- an entry with no scheme, such as `app.example.com`
`"null"` is refused for the opposite reason: it matches far more than it appears to. It is the
origin a sandboxed iframe, a page loaded from a `file:` URL and a request redirected across
origins all send, so any page can arrange to present it, and listing it would let every one of
them read the response. Every entry that fails is reported together, joined with the other
build errors.
## The combination that is refused
A wildcard origin combined with credentials is refused as a configuration error rather than
served.
```go
// This does not start. muzak.ErrCORSWildcardCredentials is reported when the
// application is built.
muzak.CORSOptions{
AllowedOrigins: []string{"*"},
AllowCredentials: true,
}
```
Browsers reject that pairing anyway, so accepting it here would only hide the mistake until
it reached a browser and then look like a bug in the framework.
## Deciding dynamically
```go
muzak.CORSOptions{
AllowOriginFunc: func(origin string) bool {
return strings.HasPrefix(origin, "https://") && strings.HasSuffix(origin, ".example.com")
},
AllowCredentials: true,
}
```
It is consulted only when `AllowedOrigins` does not already allow the origin, and it runs on
every cross-origin request, so it must be cheap and free of side effects.
Be careful with suffix matching. `strings.HasSuffix(origin, "example.com")` without the dot
also matches `https://notexample.com`. Prefer an exact list, or parse the origin and compare
the host.
## Exposing response headers
A browser lets a script read only a small safelist of response headers unless the policy
says otherwise. If your clients read the request identifier or the rate limit budget, name
those headers:
```go
ExposedHeaders: []string{
muzak.HeaderRequestID,
muzak.HeaderRateLimitLimit,
muzak.HeaderRateLimitRemaining,
muzak.HeaderRateLimitReset,
},
```
A browser-based MCP client, such as an inspector served from another origin, sends headers
of its own (the session and protocol version, and on the 2026-07-28 revision the method and
tool name) and has to read the session identifier `initialize` answers with, which a browser
hides from it unless the policy exposes it:
```go
AllowedHeaders: []string{"Content-Type", "Authorization",
muzak.HeaderMCPSessionID, muzak.HeaderMCPProtocolVersion,
muzak.HeaderMCPMethod, muzak.HeaderMCPName},
ExposedHeaders: []string{muzak.HeaderMCPSessionID},
```
The endpoint also checks the `Origin` itself, against `MCPOptions.AllowedOrigins`, so such a
client's origin is listed in both places. See [MCP Tools](/docs/techniques/mcp-tools).
## Where CORS sits in the chain
CORS runs **before** any middleware installed with `App.Use`, and in front of the documentation
routes and the router, so it covers the API, `/openapi.json` and any documentation page alike.
```
RequestID -> tracing and Observer* -> SecurityHeaders -> Recovery -> health probes* -> Locale*
-> AccessLog -> AllowedHosts and RedirectHTTPS* -> CORS -> cross-origin check*
-> your middleware -> /docs and /openapi.json -> routes and mounts
```
The pieces marked `*` are there only when they are configured: `AppOptions.Tracing` or
`Observer`, `Health`, `I18n`, `AllowedHosts` or `RedirectHTTPS`, and `CrossOriginProtection`.
A health probe, and a request that `AllowedHosts` refuses or `RedirectHTTPS` redirects, are
answered before the policy runs and carry no CORS headers. The cross-origin check runs inside
it, so a refusal sent to an origin the policy allows carries the headers that let the page read
why.
The order matters for a browser. A preflight carries no credentials, so an authenticating
middleware that ran in front of the policy refused every preflight, and its own `401` or `429`
carried no `Access-Control-Allow-Origin`, which a browser reports as a network error rather than
the status. Now a preflight is answered by the policy and never reaches a `Use` middleware, and a
response such a middleware writes itself carries the policy's headers for an allowed origin and
none for a denied one. A middleware that relied on seeing an `OPTIONS` preflight, to log it or to
answer CORS itself, no longer does when `AppOptions.CORS` names origins. Without a policy nothing
changes.
A preflight `OPTIONS` is answered by the CORS middleware. Routes also answer `OPTIONS`
automatically with an `Allow` header when nothing else does, which is a different mechanism
for a different question: `Allow` says which methods a path serves, and the CORS headers say
which a cross-origin caller may use.
### Caches
Under a policy that names origins, every response carries `Vary: Origin`, whether or not the
origin was allowed. It used to be added only when the origin was allowed, so a shared cache could
serve the allowed origin a response without CORS headers. Preflight responses also vary on
`Access-Control-Request-Method` and `Access-Control-Request-Headers`. These are recorded on the
response and merged into `Vary` when it is written, so a handler that sets its own `Vary` adds to
them rather than erasing them.
A wildcard policy sends `Access-Control-Allow-Origin: *`, and `Access-Control-Expose-Headers`
when it names any, on every response, including one to a request with no `Origin`. Its answer
is then the same whatever the request says, which is why it needs no `Vary: Origin`. Before
0.2.9 those headers went only to a request carrying an `Origin`, so a browser or shared cache
that kept the answer to a plain navigation, a `Static` or `Frontend` file with its
`Last-Modified` above all, handed it to a later cross-origin fetch, which the browser refused.
A policy that cannot be served is reported with the other build errors, where it used to be
recorded after the start-up log had reported the routes registered, so every request was answered
with a bare `500` and the log named no reason.
## What CORS does not cover
**A WebSocket handshake.** It is not subject to the same-origin policy and is never
preflighted, which is what makes cross-site hijacking possible in the first place.
`AppOptions.CORS` has no bearing on it. The separate check is
`WSOptions.AllowedOrigins`, and a cross-origin handshake is refused until it names one. See
[WebSockets](/docs/realtime/websockets).
**An event stream** is covered, because an `EventSource` is an ordinary request subject to
the same-origin policy and to CORS like any other. See
[Server-Sent Events](/docs/realtime/server-sent-events).
**A server-to-server client.** CORS is a browser mechanism. `curl`, a Go client and a
mobile app ignore it entirely, so it is not an access control: it decides what a *browser*
will let a page read, and nothing more. Authorization is a
[guard or a provider](/docs/security/authorization).
**Cross-site request forgery.** CORS decides what a page may read, not what it may send. A
form a page elsewhere submits, or a fetch it makes without a preflight, still reaches the
handler with the user's cookies attached; only the answer is withheld. Refusing that request
is `AppOptions.CrossOriginProtection`, which refuses a state-changing request a browser says
came from another origin, and which sessions require. An origin CORS allows to read is not
thereby allowed to change state: a frontend on another origin is listed in
`CrossOriginOptions.TrustedOrigins` as well. See
[Cross-Origin Requests](/docs/security/cross-origin-requests) and
[Sessions](/docs/security/sessions).
## Testing it
```go
func TestCORSAllowsTheApp(t *testing.T) {
client := testclient.New(t, buildApp())
res := client.Options("/items/",
testclient.Header("Origin", "https://app.example.com"),
testclient.Header("Access-Control-Request-Method", "POST"))
res.AssertHeader("Access-Control-Allow-Origin", "https://app.example.com")
}
func TestCORSDeniesAnyoneElse(t *testing.T) {
client := testclient.New(t, buildApp())
res := client.Get("/items/", testclient.Header("Origin", "https://evil.example"))
if got := res.Header.Get("Access-Control-Allow-Origin"); got != "" {
t.Errorf("Access-Control-Allow-Origin = %q, want no header at all", got)
}
}
```
## Where to go next
[Safe Defaults](/docs/security/safe-defaults) covers the rest of what is denied
until it is configured, and [TLS](/docs/security/tls) covers serving the origins
above over HTTPS.
--------------------------------------------------------------------------------
title: "TLS"
description: "Serve HTTPS from a certificate pair or a tls.Config, and know what changes in the rest of the application once you do."
version: "0.3.0"
last_updated: "2026-10-10T06:43:18.000Z"
source: "https://muzak.dev/docs/0.3.0/security/tls"
--------------------------------------------------------------------------------
# TLS
`App.Run` serves TLS whenever `ServerOptions` supplies a certificate pair or a
`*tls.Config`. `ServerOptions` is embedded in `AppOptions`, so both are set inline.
## From a certificate on disk
::code-group
```go [cmd/main.go]
app := muzak.New(muzak.AppOptions{
Title: "Awesome API",
Version: "1.0.0",
Addr: ":8443",
CertFile: settings.TLSCertFile,
KeyFile: settings.TLSKeyFile,
})
log.Fatal(app.RunSignals())
```
```bash [.env]
ADDR=:8443
TLS_CERT_FILE=/etc/ssl/certs/api.example.com.pem
TLS_KEY_FILE=/etc/ssl/private/api.example.com.key
```
```go [core/config.go]
type Settings struct {
Addr string `env:"ADDR" default:":8080"`
TLSCertFile string `env:"TLS_CERT_FILE"`
TLSKeyFile string `env:"TLS_KEY_FILE"`
}
```
::
Leaving both empty serves plain HTTP, which is what a development run and a deployment
behind a TLS-terminating proxy both want.
Set **both or neither**. A certificate without a key, or a key without a certificate, is a build
error. With only one of `CertFile` and `KeyFile` set, the server used to come up in plaintext on
the port its operator believed was HTTPS, with nothing said:
```
muzak: ServerOptions.CertFile is set without ServerOptions.KeyFile; set both to serve HTTPS, or neither
```
## From a tls.Config
A `*tls.Config` covers everything a certificate pair cannot: several certificates, client
certificates, a pinned minimum version, or a certificate that comes from somewhere other
than a file.
```go
app := muzak.New(muzak.AppOptions{
Title: "Awesome API",
Addr: ":8443",
TLSConfig: &tls.Config{
MinVersion: tls.VersionTLS13,
Certificates: []tls.Certificate{cert},
},
})
```
### Mutual TLS
```go
pool := x509.NewCertPool()
pool.AppendCertsFromPEM(caPEM)
app := muzak.New(muzak.AppOptions{
Title: "Internal API",
Addr: ":8443",
TLSConfig: &tls.Config{
MinVersion: tls.VersionTLS13,
Certificates: []tls.Certificate{serverCert},
ClientCAs: pool,
ClientAuth: tls.RequireAndVerifyClientCert,
},
})
```
The verified client certificate is on the request, so a provider can turn it into an
identity like any other credential:
```go
func GetClientIdentity(ctx *muzak.Context) (ClientIdentity, error) {
state := ctx.Request().TLS
if state == nil || len(state.PeerCertificates) == 0 {
return ClientIdentity{}, muzak.Unauthorized("a client certificate is required")
}
return ClientIdentity{CommonName: state.PeerCertificates[0].Subject.CommonName}, nil
}
```
### A certificate that renews itself
`GetCertificate` is consulted per handshake, which is what an ACME client or a certificate
that rotates on disk needs.
```go
app := muzak.New(muzak.AppOptions{
Title: "Awesome API",
Addr: ":8443",
TLSConfig: &tls.Config{
MinVersion: tls.VersionTLS13,
GetCertificate: certificates.Current,
},
})
```
Whatever keeps `certificates` up to date is a resource with a start and a stop, so give it
a `muzak.Lifecycle` and publish it. See
[Lifecycle](/docs/getting-started/lifecycle).
## What changes once you serve HTTPS
**Cookies.** Set `Secure: true` on every cookie, so a browser refuses to send it over plain
HTTP.
```go
ctx.SetCookie(&http.Cookie{
Name: "theme",
Value: theme,
Path: "/",
HttpOnly: true,
SameSite: http.SameSiteLaxMode,
Secure: true,
MaxAge: 3600,
})
```
A session needs no cookie of your own: `AppOptions.Sessions` writes one that is Secure,
HttpOnly and SameSite=Lax by default, under a `__Host-` name a browser accepts only from a
secure origin. See [Sessions](/docs/security/sessions).
**Origins.** The `https` and `http` spellings of a host are different origins. Update
`CORSOptions.AllowedOrigins` and `WSOptions.AllowedOrigins` accordingly.
**WebSocket URLs.** A page served over `https` must dial `wss`, not `ws`.
**The `Servers` list.** Point the generated document at the address clients actually use:
```go
Servers: []muzak.Server{
{URL: "https://api.example.com", Description: "production"},
},
```
## Terminating TLS somewhere else
A load balancer, an ingress controller or a reverse proxy commonly holds the certificate
and speaks plain HTTP to the service behind it. Muzak then serves HTTP, and three things
need saying explicitly:
- **Name the proxy** in `ClientIPOptions.TrustedProxies`, or every request is attributed to
the proxy's address rather than the client's. See
[Behind a Proxy](/docs/deployment/behind-a-proxy).
- **Keep cookies `Secure`** anyway. The browser leg of the connection is the one that
matters, and it is HTTPS.
- **Redirect plain HTTP** with `AppOptions.RedirectHTTPS`, if the proxy forwards it rather
than redirecting itself. It believes the scheme a named proxy reports in
`X-Forwarded-Proto`, answers `301` for GET and HEAD and `308` otherwise, and only ever
names a host that `AppOptions.AllowedHosts` admitted or `RedirectHTTPSOptions.Host` gives.
See [Allowed Hosts and HTTPS](/docs/security/hosts-and-https).
## HTTP/2 without TLS
Over TLS, HTTP/2 is negotiated as usual. A platform that speaks HTTP/2 to the container in the
clear, such as Cloud Run with an `h2c` container port, needs `ServerOptions.UnencryptedHTTP2`,
which accepts HTTP/2 without TLS, sent with prior knowledge, on the same port as HTTP/1:
```go
app := muzak.New(muzak.AppOptions{
Title: "Awesome API",
ServerOptions: muzak.ServerOptions{UnencryptedHTTP2: true},
})
```
Leave it off anywhere the proxy speaks HTTP/1, and never for a server reachable directly from an
untrusted network. A WebSocket handshake is not carried over HTTP/2 and is answered `426`. What
was measured on Cloud Run, and why a request is cancelled the moment its client leaves over `h2c`
but not over HTTP/1, is on [Running on Cloud Run](/docs/deployment/cloud-run).
## Strict transport security
Muzak's `SecurityHeaders` middleware sets `X-Content-Type-Options`, `X-Frame-Options` and a
referrer policy on every response. A response to a request that arrived over TLS also gets
`Strict-Transport-Security: max-age=31536000`, which tells the browser to use HTTPS for this
host for a year, so that a visitor's next request cannot be downgraded to plain HTTP on the way.
It commits only the host that has just answered over TLS. It leaves out `includeSubDomains` and
`preload`, which commit hosts this application may not serve and are hard to take back, and it is
not sent for `localhost`, a `.localhost` name or an IP address, so a development server with a
local certificate does not pin every other server on the developer's machine to HTTPS. A browser
ignores it over plain HTTP, so it is not sent there, and behind a proxy that terminates TLS the
request Muzak sees is plain, so the proxy is the place to set it. A value the handler sets
replaces it.
To add `includeSubDomains` once every subdomain is on HTTPS, set the header yourself. `Set`
replaces the default:
```go
func HSTS(maxAge time.Duration) muzak.Middleware {
value := "max-age=" + strconv.Itoa(int(maxAge.Seconds())) + "; includeSubDomains"
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.TLS != nil {
w.Header().Set("Strict-Transport-Security", value)
}
next.ServeHTTP(w, r)
})
}
}
```
```go
app.Use(HSTS(365 * 24 * time.Hour))
```
The `r.TLS != nil` check keeps the header off a plain-HTTP response, where it means nothing
and where a redirect, which `AppOptions.RedirectHTTPS` sends, is the more useful answer. Behind
a terminating proxy the check has to read whatever header the proxy sets instead.
A host that also serves plain HTTP on another port, or may stop serving HTTPS, takes the header
off instead, because a browser pins the whole host along with it. Remove it in middleware
installed with `App.Use`, which runs after `SecurityHeaders` has set it, or send `max-age=0`:
```go
app.Use(func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// This host also serves plain HTTP on another port, which a pinned
// browser could no longer reach.
w.Header().Del("Strict-Transport-Security")
next.ServeHTTP(w, r)
})
})
```
## Development certificates
```bash
go run filippo.io/mkcert@latest -install
go run filippo.io/mkcert@latest localhost 127.0.0.1
```
```bash [.env]
ADDR=:8443
TLS_CERT_FILE=./localhost+1.pem
TLS_KEY_FILE=./localhost+1-key.pem
```
Tests need none of this. The test client serves the application on a loopback port in plain
HTTP, whatever TLS is configured, so there is nothing to encrypt. See
[Testing](/docs/fundamentals/testing).
## Where to go next
[Behind a Proxy](/docs/deployment/behind-a-proxy) covers running with TLS
terminated in front of you, and
[Server Configuration](/docs/deployment/server-configuration) covers the rest of
the listener.
--------------------------------------------------------------------------------
title: "Allowed Hosts and HTTPS"
description: "Refuse requests for hosts the application does not serve, and redirect plain HTTP to https without ever naming a host a client chose."
version: "0.3.0"
last_updated: "2026-10-10T06:32:48.000Z"
source: "https://muzak.dev/docs/0.3.0/security/hosts-and-https"
--------------------------------------------------------------------------------
# Allowed Hosts and HTTPS
The `Host` header is whatever the client wrote. An application that builds a password reset
link from it, keys a cache on it, names it in a redirect, or listens on an address a DNS
rebinding page can reach, is trusting a value anyone can set. `AppOptions.AllowedHosts` is the
list of hosts the application answers to, and everything else is refused before any of the
application runs.
::code-group
```go [cmd/main.go]
app := muzak.New(muzak.AppOptions{
Title: settings.AppName,
// The names this service answers to. A request for any other host is
// refused with 421 before a route, a mount or the documentation sees it.
AllowedHosts: settings.AllowedHosts,
// Plain HTTP is redirected to https on one of the names above.
RedirectHTTPS: &muzak.RedirectHTTPSOptions{},
ClientIP: muzak.ClientIPOptions{TrustedProxies: settings.TrustedProxies},
})
```
```go [core/config.go]
type Settings struct {
// AllowedHosts lists the Host header values this service answers to. A
// leading "*." allows every subdomain; an entry without a port allows
// any port.
AllowedHosts []string `env:"ALLOWED_HOSTS"`
}
```
```bash [.env]
ALLOWED_HOSTS=example.com,*.example.com,localhost:8080
```
::
## How a host is matched
| Entry | Admits | Refuses |
|---|---|---|
| `example.com` | `example.com`, `EXAMPLE.COM`, `example.com.`, `example.com:8080` | `www.example.com`, `example.com.evil.com`, `example.com@evil.com` |
| `*.example.com` | `api.example.com`, `a.b.example.com:443` | `example.com`, `aexample.com`, `.example.com` |
| `api.example.com:8443` | `api.example.com:8443` | `api.example.com`, `api.example.com:443` |
| `[::1]` | `[::1]`, `[0:0::1]:8080` | `::1`, `[::1%25lo0]` |
| `127.0.0.1` | `127.0.0.1`, `127.0.0.1:5000` | `127.1`, `2130706433`, `[::ffff:127.0.0.1]` |
| `xn--bcher-kva.de` | `xn--bcher-kva.de`, `XN--BCHER-KVA.DE` | the same name in UTF-8 |
- Case is ignored for **ASCII letters only**. A letter outside ASCII that Unicode folds to an
ASCII one, the Kelvin sign to `k` or the long s to `s`, is never taken for it.
- One trailing dot on the request's host, the fully qualified spelling, is ignored.
- An entry without a port allows any port. An entry with a port allows that port only, so a
request that names no port matches only an entry that names none. A request whose `Host` ends
in an empty port, as in `example.com:`, names none.
- A leading `*.` allows every subdomain, of one label or more, and **not** the domain itself.
List the domain too when it is served.
- An IPv6 address is written in brackets and compared in its canonical form, so every spelling of
one address matches. A zone is never accepted.
- An internationalized name is written in its punycode (`xn--`) form, which is what a client
sends.
- `X-Forwarded-Host`, `Forwarded: host=` and every other forwarding header are ignored, from any
peer. Behind a proxy, list the `Host` the proxy passes on.
An entry that can never match is a build error, with every bad entry reported at once: an empty
one, or one with a scheme, a path, credentials, a query or fragment, whitespace, a `*` anywhere
but a leading `*.`, a bare IPv6 address, a trailing colon with no port after it, a port of `0` or
over `65535`, a wildcard in front of an address, a character outside ASCII, or anything else that
is not a host name or an address. Surrounding whitespace is ignored, since a list read from the
environment is usually split at commas.
Unset, the default, no check is made and nothing is installed, so it costs nothing.
## The refusal
A request for a host that is not listed is answered **421 Misdirected Request** through the error
renderer, so it carries the error envelope (or a problem, with
[Problem Details](/docs/techniques/problem-details) on), the request identifier, the security
headers and `Cache-Control: no-store`:
```json
{
"error": {
"code": "misdirected_request",
"message": "This server does not serve the requested host.",
"status": 421
},
"request_id": "0611f4b2-2f0a-7b57-9c1a-6e6a2e2f9b31"
}
```
The host is not echoed. It is logged at warn level, on every refused request, quoted with every
byte that is not printable ASCII escaped, so a header crafted to forge a log line records as inert
text, and the access log records the `421`. A scanner that sends foreign hosts all day therefore
writes a warning per request; filter the message in your log pipeline if that is noise to you.
421 rather than 400 because RFC 9110 defines it for exactly this: a request "directed at a server
that is unable or unwilling to produce an authoritative response for the target URI". It is also
the status an HTTP/2 or HTTP/3 client acts on. A browser that reused one connection for two hosts
its certificate covers retries on a connection of its own when told 421, where a 400 would end the
request as the client's fault.
The check runs before anything else of the application: before the CORS policy, the cross-origin
protection, the middleware installed with `App.Use`, routing, mounts, frontends and the
documentation. It runs inside request identification, the security headers, the locale and the
access log, so a refusal is recorded like any other response and translated like any other error.
The message is translatable at `muzak.http.421`.
The one thing answered ahead of it is a [health probe](/docs/deployment/health-checks). A platform
probes a replica by its own address, with whatever `Host` that makes and over plain HTTP, so the
health endpoints answer for any host and are never redirected; otherwise every probe would be
refused and every replica taken out of rotation. They say only whether the process is up and
ready, unless `HealthOptions.ReportChecks` adds the name and outcome of each check, which any
page that reaches the port through DNS rebinding can then read too. Leave `ReportChecks` off
where the port is reachable from outside the platform.
Two things net/http settles before the application sees the request:
- A request with an absolute target, `GET http://evil.com/ HTTP/1.1`, has its host taken from
the target rather than the `Host` header, as RFC 9112 requires, and that is the host checked.
- A request with two `Host` headers, or a `Host` holding a byte no host carries, such as one
outside ASCII or the `@` of `example.com@evil.com`, is refused by net/http with `400` before any
handler runs. The allowlist refuses the same values for a request that reaches `ServeHTTP` some
other way.
An HTTP/1.0 request with no `Host` at all reaches the application with an empty host, which no
entry matches, so it is refused with `421`.
The two host lists of a [WebSocket](/docs/realtime/websockets) are separate. A WebSocket route's
own `WSOptions.AllowedHosts` still decides which handshakes count as same-origin, and is not filled
in from `AppOptions.AllowedHosts`; with `AppOptions.AllowedHosts` set, a handshake for any host it
does not list never reaches the route at all.
## Redirecting plain HTTP
```go
app := muzak.New(muzak.AppOptions{
AllowedHosts: []string{"example.com", "www.example.com"},
RedirectHTTPS: &muzak.RedirectHTTPSOptions{},
})
```
A request that arrived over plain HTTP is answered with a redirect to the same host, path and
query over https:
| Method | Status | Why |
|---|---|---|
| `GET`, `HEAD` | `301 Moved Permanently` | Understood by every client, and kept by a browser, so the next navigation goes to https without a plaintext round trip. |
| everything else | `308 Permanent Redirect` | Keeps the method and the body, which a client following a 301 for a `POST` may turn into a `GET` without one. |
The redirect has no body and sends no `Strict-Transport-Security`; `SecurityHeaders` sends that
on responses served over TLS, which is where a browser honours it. A redirect is a convenience for
navigation: the body of a request that was redirected has already crossed the network in the
clear, and HSTS is what keeps a returning browser from sending it at all.
### Which host it names
A redirect is only as trustworthy as the host it names, so it never names one the application has
not vouched for:
- With `AllowedHosts` set, the request's own host is kept, once the allowlist has admitted it,
lowercased and without the trailing dot. A host the allowlist refuses is refused, never
redirected.
- `RedirectHTTPSOptions.Host` names one canonical host every redirect is sent to instead, which
also lets the redirect be used without an allowlist.
- With neither, enabling the redirect is a **build error**: a forged `Host` would otherwise make
it a redirect to anywhere.
The port the request named is never kept, because it is the one plain HTTP was served on. Set
`Port` when https is served somewhere other than `443`:
```go
muzak.RedirectHTTPSOptions{Port: 8443} // https://example.com:8443/...
muzak.RedirectHTTPSOptions{Host: "www.example.com"} // https://www.example.com/...
muzak.RedirectHTTPSOptions{Host: "www.example.com:8443"} // https://www.example.com:8443/...
```
`Host` is written as an `AllowedHosts` entry is, without a wildcard, since a redirect needs one
host to send the client to. A port of `0` or `443` is left out of the URL. A `Host` that names a
port while `Port` is set too, a wildcard `Host`, and a `Port` outside `0` to `65535` are build
errors.
### The path and query
The path and query are copied with every byte that is not plainly allowed in them
percent-encoded: a control character, a space, a backslash, a quote or a byte outside ASCII never
reaches the `Location` header, an escape the client wrote is kept as written, and a stray `%`
becomes `%25`. A path that does not begin with `/`, the `*` of `OPTIONS *` say, is redirected to
the root. Because the `Location` always names its host, a path beginning `//evil.com` or `/\evil.com`
is a path on the vouched host and nothing else.
### Behind a proxy
Behind a proxy that terminates TLS, every request arrives as plain HTTP, and only the proxy knows
what the client used. A request counts as https when the peer that sent it is a proxy named in
`ClientIPOptions.TrustedProxies` and that proxy says so:
| `ClientIPOptions.Header` | The scheme is read from |
|---|---|
| unset, `X-Forwarded-For`, `X-Real-IP`, anything else | `X-Forwarded-Proto` |
| `Forwarded` | the `proto` parameter of `Forwarded` |
Only the value the trusted proxy itself wrote is read, which is the last one: the last
comma-separated value of the last `X-Forwarded-Proto` line, or the `proto` of the last `Forwarded`
entry. An earlier value may have come from the client through a proxy that appends rather than
replaces, and a client that could claim https would have its plain request served, and kept by a
cache, as though it were secure. From a peer that is not trusted, the header is ignored whatever
it says. Responses whose treatment depended on the header carry it in `Vary`.
The proxy has to set the header. One that does not, or a server listening on a Unix socket, where
no peer address can be trusted, sees every request as plain and redirects every one of them. A
chain of proxies has to pass the edge's value through rather than write its own hop's scheme.
### What is never redirected
A request for an ACME HTTP-01 challenge, `/.well-known/acme-challenge/` followed by one token of
base64url characters, is served over plain HTTP, because a certificate authority validates a host
that has no certificate yet. Nothing that only begins like one is exempt: a second segment, a `..`
or an encoded slash is redirected like any other path.
The health endpoints are not redirected either, for the reason given
[above](#the-refusal): a platform probes them over plain HTTP.
## Checking it works
```bash
curl -si http://localhost:8080/ -H 'Host: evil.com' # 421
curl -si http://localhost:8080/a?b=1 -H 'Host: example.com' # 301 to https://example.com/a?b=1
curl -si http://localhost:8080/a -H 'Host: example.com' \
-H 'X-Forwarded-Proto: https' # 301 unless the peer is a trusted proxy
```
## Where to go next
[Behind a Proxy](/docs/deployment/behind-a-proxy) covers naming the proxy whose headers are
believed, [TLS](/docs/security/tls) serving https directly, and
[Health Checks](/docs/deployment/health-checks) the probes that are answered ahead of both
checks.
--------------------------------------------------------------------------------
title: "Sessions"
description: "Encrypted cookie sessions or server-side stores, read only when a handler asks, written once when the request succeeds, and regenerated on sign-in so a planted session is worth nothing."
version: "0.3.0"
last_updated: "2026-10-10T11:11:46.000Z"
source: "https://muzak.dev/docs/0.3.0/security/sessions"
--------------------------------------------------------------------------------
# Sessions
A session is what a browser carries between requests once a user has signed in: a few values,
usually just who the user is, that the server can trust because the client cannot forge them.
`AppOptions.Sessions` turns them on, and `ctx.Session()` returns the request's session.
Sessions are opt-in. An application that leaves the option unset pays nothing for it, and one
that sets it still pays nothing on a request whose handler, guards and providers never call
`ctx.Session()`: no cookie is parsed, nothing is decrypted, no store is asked and nothing is
written.
## Configuring them
::code-group
```go [cmd/main.go]
app := muzak.New(muzak.AppOptions{
Title: settings.AppName,
// Sessions, kept in a cookie encrypted under the configured secrets.
Sessions: &muzak.SessionOptions{Secrets: settings.SessionSecrets},
// Required with sessions; see "Cross-origin protection is required" below.
CrossOriginProtection: &muzak.CrossOriginOptions{},
})
```
```go [core/config.go]
type Settings struct {
// SessionSecrets are the keys the session cookie is encrypted under, as a
// comma-separated list: the first encrypts and every one decrypts, which
// is how a key is rotated. Each must be at least 32 random bytes.
SessionSecrets []string `env:"SESSION_SECRETS" secret:"true"`
}
```
::
Generate a secret with `openssl rand -base64 32` and keep it out of the source. Nothing else
needs setting: every default below is the safe one.
The example application gives `SESSION_SECRETS` a default, so that it runs as it is. A
deployment that keeps that default has sessions anyone who has read the source can forge: set
your own before you deploy it.
| Field | Default | Effect |
|---|---|---|
| `Secrets` | none | The keys the cookie store encrypts with, each at least 32 bytes (`muzak.MinSessionSecretLength`). The first encrypts, all decrypt. Required by the cookie store, unused by a server-side store |
| `Store` | the encrypted cookie | A `SessionStore` that keeps sessions on the server; the cookie then carries only a random identifier |
| `Name` | `__Host-session` | The cookie's name; see [The cookie](#the-cookie) |
| `Path` | `/` | The cookie's path. A narrower one is not a security boundary, and gives up the `__Host-` prefix |
| `Domain` | none | Sends the cookie to every subdomain too, and gives up the `__Host-` prefix |
| `SameSite` | `Lax` | `Strict` also withholds the cookie from links followed from other sites; `None` needs Secure |
| `AllowInsecure` | off | Sends the cookie without Secure, for development on a host other than localhost |
| `IdleTimeout` | 2 hours | Ends a session that has not been used for this long |
| `MaxLifetime` | 24 hours | Ends a session this long after it began, however busy |
| `MaxSize` | what fits in a cookie, or 16 KiB with a store | The largest encoded session; a change past it fails where it is made |
| `StoreTimeout` | 2 seconds | Bounds each call to a `SessionStore` |
Everything that cannot be served as written is a build error, reported with the others: no
secret or a short one, a negative duration or size, an idle timeout longer than the lifetime, a
`MaxSize` larger than a cookie can carry, a `Path` that does not begin with `/`,
`SameSite=None` without Secure, `http.SameSiteDefaultMode` (which leaves the choice to each
browser), a name that is not a token, a `__Host-` or `__Secure-` name whose attributes a browser
would refuse, and a name, path and domain so long that the cookie has room for less than 256
bytes of session. No secret is ever quoted in the message.
## Signing in
The example application signs in with a form posted to `/login/`, and signs out at `/logout/`:
::code-group
```go [handlers/login.go]
func Login(ctx *muzak.Context, in schemas.LoginIn) (schemas.LoginOut, error) {
expected, known := accounts[in.Username]
matches := subtle.ConstantTimeCompare([]byte(expected), []byte(in.Password)) == 1
if !known || !matches {
return schemas.LoginOut{}, muzak.Unauthorized("the username or password is incorrect")
}
session := ctx.Session()
// Regenerating comes first, before anything that says who the user is.
if err := session.Regenerate(); err != nil {
return schemas.LoginOut{}, err
}
if err := session.Set("user", in.Username); err != nil {
return schemas.LoginOut{}, err
}
return schemas.LoginOut{Username: in.Username, Next: in.Next}, nil
}
```
```go [routers/login.go]
r.Post("/login/", handlers.Login,
muzak.Summary("Exchange a username and password for a session"),
muzak.WithResponseDoc(http.StatusUnauthorized, "The username or password is incorrect"),
muzak.RateLimit(muzak.Quota{Name: "login", Window: time.Minute, Limit: 5}))
r.Post("/logout/", handlers.Logout,
muzak.Summary("End the session"))
```
::
### Always regenerate on sign-in
**Call `Regenerate` on every sign-in, before you set anything that says who the user is.**
Without it, session fixation works: an attacker gets a session of their own, plants it in the
victim's browser (through a sibling subdomain when the cookie names a `Domain`, through a page
served over plain HTTP on the same host when it is not Secure, or through a cross-site scripting
bug), and waits. When the victim signs in, the session the attacker already holds becomes the
victim's signed-in session. `Regenerate` gives the values a new session, a new identifier with
the old one deleted from a server-side store, and a new ciphertext and lifetime with the cookie
store, so whatever the attacker holds is worthless at the moment it would have become valuable.
The default `__Host-` cookie closes the first two routes; regenerating closes all of them. Call
it whenever the privilege a session carries changes, such as stepping up to an administrator, as
well.
The session is not repeated in the response body. A credential in a body is one any script on
the page can read, which is exactly what the cookie's `HttpOnly` attribute exists to prevent.
## Reading and writing values
A session holds string keys and JSON values. `Set` encodes a value, and `muzak.SessionGet`
decodes one into the type asked for:
```go
func Profile(ctx *muzak.Context, _ muzak.Empty) (ProfileOut, error) {
user, ok := muzak.SessionGet[string](ctx.Session(), "user")
if !ok {
return ProfileOut{}, muzak.Unauthorized("sign in first")
}
return loadProfile(ctx.Context(), user)
}
```
| Call | Does |
|---|---|
| `muzak.SessionGet[T](s, key)` | The value under `key` decoded as `T`, and whether there was one. A value that does not decode as `T`, because an earlier release stored something else there, reads as absent |
| `s.Has(key)` | Whether there is a value, without decoding it |
| `s.Set(key, value)` | Stores `value` as JSON. Fails for an empty key, one that is not UTF-8, a value JSON cannot encode, a session that would grow past `MaxSize` (`muzak.ErrSessionTooLarge`) and a session whose store could not be read; the session is left as it was |
| `s.Delete(key)` | Removes one value |
| `s.Clear()` | Removes every value. An emptied session is removed from the browser rather than written empty |
| `s.IsNew()` | Whether the request came without a valid session, or its session has been destroyed since, which is how a handler tells an anonymous visitor |
| `s.Err()` | Why a server-side store could not be read; see [Server-side stores](#server-side-stores) |
Keep a session small: an identifier and a preference or two. It travels with every request,
and with the cookie store it is the cookie. A change that would make it too large is refused
where it is made rather than silently truncated on the way to the browser, so the error reaches
the code that caused it.
A `*Session`, like the `*muzak.Context` it came from, is not safe for concurrent use and must not
be used once the handler has returned. A session kept past its request refuses every change.
## Signing out
```go
func Logout(ctx *muzak.Context, _ muzak.Empty) (muzak.Empty, error) {
ctx.Session().Destroy()
return muzak.Empty{}, nil
}
```
`Destroy` removes every value, removes the cookie from the browser and, with a server-side
store, deletes the session's entry, so a copy of the cookie taken earlier is worthless too. A
value set afterwards in the same request begins a new session under a new identifier.
The cookie store cannot revoke. Its session is the cookie, so a copy taken before `Destroy` ran,
by malware or from a shared machine, stays valid until its idle timeout or lifetime ends it, and
nothing the server holds can say otherwise. An application that must end a session everywhere,
at sign-out, on a password change or when an account is suspended, wants a server-side store.
## When the session is written
The session is written at most once per request, at one point: after the handler has returned,
after every [dependency release](/docs/getting-started/dependencies) has run, and before the
response is written. A transaction that fails to commit therefore takes the session change with
it. What is written, and when:
- **Only a request that succeeded.** A handler that returns an error, one that answers with a
status of 400 or above, one that panics and one whose release fails write nothing, so a half
finished request never leaves a half changed session.
- **Only a session that changed, or is due for renewal.** Reading a session writes nothing. A
session in use is renewed once a tenth of its idle timeout has passed since it was written, so
a busy user's cookie is rewritten every twelve minutes at the default, not on every request.
- **Never a session the request did not touch.**
- **Once.** The response never carries two cookies for one session.
`Save` writes the session immediately, for a change that must be kept whatever happens next,
such as a count of failed sign-in attempts or a message for the next page:
```go
attempts, _ := muzak.SessionGet[int](s, "attempts")
_ = s.Set("attempts", attempts+1)
if err := s.Save(); err != nil {
return LoginOut{}, err
}
return LoginOut{}, muzak.Unauthorized("the username or password is incorrect")
```
A change made after `Save` is written when the request ends, if it succeeds, and replaces what
`Save` wrote.
A handler that writes its response itself, through `ctx.ResponseWriter()` or by returning a
`muzak.Stream`, has its session written as the status line goes out, if that status is below
400, because a cookie cannot follow the first byte. A change made after that is not saved. An
[event stream](/docs/realtime/server-sent-events) and a [WebSocket](/docs/realtime/websockets)
begin their response before their handler runs, so a session changed there is not saved either;
read the session in a guard and change it in an ordinary route. Either way the lost change is
logged once as a warning naming the route, unless the response it would have gone out with had
a status of 400 or above, which discards a change on purpose. `Save` after the response has
started returns an error.
A response that carries the session cookie is marked `Cache-Control: private, no-cache`,
replacing a policy that would let a shared cache keep it, since a cache that stored it would hand
one user's session to the next. A `Cache-Control` that already says `private` or `no-store` is
left alone. This holds whatever sets `Cache-Control` after the cookie: a handler that sets a
public policy after `Save`, an error renderer that lets an error be cached, or the file server
dropping the header from a range it cannot serve (see
[Files, Streams and Redirects](/docs/techniques/files-streams-redirects)). The response is made
private again as its header goes out, and an event stream's `no-transform` is kept when it is.
A response from a handler that read the session varies on `Cookie` and is marked the same way
unless the handler set a `Cache-Control` of its own. An event stream and a WebSocket keep their
own `Cache-Control` when a guard or provider reads the session.
## The cookie
```
Set-Cookie: __Host-session=AUYbFNGP...; Path=/; Max-Age=7200; HttpOnly; Secure; SameSite=Lax
```
- **`HttpOnly`** keeps it from scripts, so a cross-site scripting bug cannot read it.
- **`Secure`** keeps it off plain HTTP, where anyone on the network can read it. Browsers accept
a Secure cookie from `http://localhost`, so development needs nothing; `AllowInsecure` exists
for another host over plain HTTP, and cannot be combined with `SameSite=None` or a prefixed
name.
- **`SameSite=Lax`** keeps it off requests other sites start, except a top-level navigation by
`GET`. It does not keep it off a request from a sibling subdomain, which is the same site;
that is what [cross-origin protection](/docs/security/cross-origin-requests) is for.
- **The `__Host-` prefix** is the one most applications never think about. A browser accepts a
cookie with that name only from a secure origin, only with `Path=/` and only without a
`Domain`. A sibling subdomain, which can otherwise set a cookie for the whole domain, and a
page served over plain HTTP on the same host, which can otherwise set a cookie of the same
name, can set neither. That is what stops an attacker from planting a session of their choosing
in the user's browser, or shadowing the real one with their own.
- **`Max-Age`** is how long the session has left, the idle timeout or what remains of the
lifetime. It only tells the browser when to drop the cookie: the timeouts themselves are kept
inside the encrypted or stored session, never taken from the cookie, which the client controls.
Setting `Domain`, or a `Path` other than `/`, gives up the `__Host-` prefix and the default name
becomes `__Secure-session`; setting `AllowInsecure` gives up both prefixes and it becomes
`session`. A name you choose is
checked against the same rules, without regard to case, as browsers check them.
## The encrypted cookie store
With no `Store`, the session is the cookie: its values and its two timestamps, encrypted and
authenticated with AES-256-GCM and encoded as unpadded base64url.
- Each secret is reduced to a key with HKDF-SHA256 when the application is built.
- Each cookie draws a fresh random 192-bit nonce, from which HKDF derives an AES-256 key and a
GCM nonce used for that cookie alone. AES-GCM with a random 96-bit nonce under one key is good
for about 2^32 messages before a repeated nonce becomes a concern, and a repeated nonce lets an
attacker forge cookies; a busy application renewing sessions could get there. A key per cookie
removes the limit.
- The cookie's name, the format's version and a label naming the purpose are bound as additional
data, so a cookie cannot be decrypted under another name, by another use of the same secrets
or as another version of the format. A cookie lifted from one application's `__Host-session` and
presented to another as `__Host-admin` is refused, even with the same secrets.
A cookie that was tampered with anywhere, truncated, extended, spelled differently, encrypted
under a secret no longer listed, or past its idle timeout or lifetime reads as no session: the
request proceeds signed out, and nothing is logged of the cookie or its contents. It is never an
error page, because a client can send any cookie it likes and an error would only tell it which
of them were interesting.
### Rotating a secret
1. Put the new secret first and keep the old one after it. New cookies are encrypted under the
new one; existing cookies still open under the old one.
2. Wait for `MaxLifetime` to pass, 24 hours by default. No cookie encrypted under the old secret
can still be valid.
3. Remove the old secret.
Decrypting tries each secret in turn, so keep the list short. To invalidate every session at
once, after a leak say, replace the secrets rather than adding to them.
### How much fits
The cookie must stay within 4096 bytes, name and attributes included, which is the most every
browser is sure to keep: one past it is dropped by some of them without a word. With the default
name that leaves a little under 3 KB of encoded JSON. `MaxSize` defaults to that, and a larger
value is a build error. An application that needs more wants a server-side store.
## Server-side stores
```go
app := muzak.New(muzak.AppOptions{
Sessions: &muzak.SessionOptions{
Store: muzak.NewMemorySessionStore(muzak.MemorySessionOptions{MaxEntries: 50_000}),
},
CrossOriginProtection: &muzak.CrossOriginOptions{},
})
```
With a `Store`, the cookie carries only a random 256-bit identifier, and the store holds the
session under the SHA-256 digest of that identifier, never the identifier itself. A backup or a
dump of the store therefore holds no cookie anyone could present, and since nobody can choose a
digest, how long a lookup takes says nothing about which identifiers exist. An identifier a
client sends that the store does not know is never adopted: the session the request begins gets
an identifier of the application's own. A cookie that cannot be an identifier this application
issued is not looked up at all.
`MemorySessionStore` keeps sessions in the process. It is for tests and for an application that
runs as one process: sessions are not shared with a second replica, and a restart signs everyone
out. It holds at most `MaxEntries` sessions (10,000 by default), discards the least recently used
when full, which signs that user out, and discards an entry once its time has passed, a few at a
time as it is used, so it starts no goroutine. Every operation is constant time.
### Writing a store
```go
type SessionStore interface {
Load(ctx context.Context, key string) (data []byte, found bool, err error)
Create(ctx context.Context, key string, data []byte, ttl time.Duration) error
Update(ctx context.Context, key string, data []byte, ttl time.Duration) (found bool, err error)
Delete(ctx context.Context, key string) error
}
```
The data is opaque, and carries its own timestamps, which are checked against the idle timeout
and the lifetime whatever the store returns. The TTL is how long the store may keep the entry.
There is no single `Save`, and that is deliberate. A request that read a session just before the
user signed out in another tab would otherwise write the session back as it finished, and the
sign-out would not stick. `Create` saves a new session, and `Update` saves only over one that
still exists, reporting `false` otherwise. Against Redis that is `SET` with `NX` and with `XX`;
against SQL, an `INSERT` and an `UPDATE` whose row count is checked:
```go
func (s *RedisSessions) Create(ctx context.Context, key string, data []byte, ttl time.Duration) error {
ok, err := s.client.SetNX(ctx, "session:"+key, data, ttl).Result()
if err == nil && !ok {
err = errors.New("session key already exists")
}
return err
}
func (s *RedisSessions) Update(ctx context.Context, key string, data []byte, ttl time.Duration) (bool, error) {
return s.client.SetXX(ctx, "session:"+key, data, ttl).Result()
}
```
Every call must return when its context ends; each is bounded by `StoreTimeout`, and the writes
are not cancelled by a client hanging up, so a sign-out is not abandoned half way. A store that
also implements `Lifecycle` is started with the application and stopped after it drains.
A store that cannot be read does not sign the user out and then save over their session. The
request proceeds with an empty session that refuses every change, `s.Err()` reports
`muzak.ErrSessionUnavailable` wrapping the store's error, and the failure is logged without the
identifier. `Destroy` still works: the cookie is removed and the deletion attempted. A handler
that would rather fail than serve such a request signed out checks for it:
```go
if err := ctx.Session().Err(); err != nil {
return Out{}, err
}
```
A store that fails a write fails the request with a `500`, as a release that fails would, and
the work registered with `AfterResponse` does not run. A sign-out whose deletion fails still
removes the browser's cookie, and still answers `500`, so the user knows the session may outlive
it.
## Timeouts
The idle timeout and the lifetime are both kept inside the session, as the time it began and the
time it was last written, and both are checked every time it is read.
- **`IdleTimeout`**, 2 hours by default, ends a session that has not been used for that long.
Because a session in use is only rewritten every tenth of the timeout, it lapses between nine
tenths of the timeout and the whole of it after its last use.
- **`MaxLifetime`**, 24 hours by default, ends a session that long after it began, however busy.
It is what bounds a stolen cookie that its thief keeps alive. `Regenerate` starts it again.
A session that has expired reads as no session, and the session the request begins replaces it.
## Two requests, one session
Two requests carrying the same session each get a copy, and whichever writes last decides what is
kept, its cookie or its entry in the store. Neither ever writes half of one: a store must keep
whole records, and `MemorySessionStore` does. With a server-side store, a request that finishes
after another destroyed or regenerated the session finds it gone and writes nothing, neither the
entry nor a cookie that would overwrite the browser's newer one, so a sign-out in one tab is not
undone by a request from another (with the one exception under [Limits](#limits)):
- **What it read goes too.** A `Save` that finds the session gone leaves it new and empty, so a
value set later in the same request begins a new session holding nothing the ended one held.
- **`Regenerate` checks first.** Regenerating creates a new entry rather than updating the old
one, which would not show that the old one was gone, so the old entry is looked up before it is
replaced. When another request has ended the session, nothing is written and the request
succeeds without a session; when the store cannot answer, the request fails with `500`.
## Cross-origin protection is required
A session cookie is an ambient credential: the browser attaches it to a request whichever page
made it. `SameSite=Lax` keeps it off a form another site posts, but not off one posted from a
sibling subdomain, and `SameSite=None` keeps it off nothing. Sessions are therefore a build error
without `AppOptions.CrossOriginProtection`:
```
muzak: AppOptions.Sessions is set without AppOptions.CrossOriginProtection; a session cookie is
sent with requests other pages make, so state-changing requests must be checked for where they
came from. Set CrossOriginProtection: &muzak.CrossOriginOptions{}, ...
```
It is one line, it needs no token in any form, and it refuses nothing a same-origin page does.
See [Cross-Origin Requests](/docs/security/cross-origin-requests).
## What a hostile client cannot do
| Attempt | What happens |
|---|---|
| Edit, truncate or extend the cookie | Authenticated encryption refuses it; the request is anonymous |
| Present a cookie from another application or another cookie name | The name is bound into the encryption; refused |
| Keep using a cookie past its timeout, or set a longer `Max-Age` | The times are inside the authenticated session and checked on every read |
| Plant a session before the victim signs in | `Regenerate` replaces it; `__Host-` stops subdomains and plain HTTP from planting one |
| Invent an identifier for a server-side store | Never adopted; a new session gets the application's own identifier |
| Read a stolen store dump for cookies | The store holds digests of identifiers, not identifiers |
| Flood the server with sessions | Nothing is stored for a visitor until a handler sets a value; the memory store is bounded and evicts the least recently used |
| Send a huge cookie | Refused unread past 4096 bytes; every check is linear in the cookie |
| Get a session cached and served to others | A response carrying the cookie is `private`, and one that read the session varies on `Cookie` |
| Forge a request from another site | Refused by cross-origin protection before anything runs |
## Limits
- **One store, one application.** A server-side store holds each session under the digest of
its identifier and nothing else: neither the application nor the cookie's name is part of the
key. Two applications given one store, or two configurations with different cookie names,
accept each other's sessions. Give each its own store, or its own key prefix in a store you
write (the `"session:"` in the Redis example above is where it goes).
- **`Regenerate` leaves a short race.** The old entry is looked up before it is replaced, and a
sign-out that lands between the lookup and the replacement is undone. The window is as long as
one call to the store.
- **A client that hangs up during a load is logged at debug level.** Loading runs under the
request's context, so a client that disconnects while the store is being read ends the load;
that is logged at debug level, as a stream its client ended is, while a load that fails or
outruns `StoreTimeout` is logged at error level as "the session store could not be read".
## Testing
The test client's cookie jar plays the browser, and treats the loopback address it serves on as
secure, as browsers treat localhost, so the default Secure `__Host-` cookie works unchanged:
```go
func TestSignIn(t *testing.T) {
client := testclient.New(t, buildApp())
// /me is served by the Profile handler above.
client.Get("/me").AssertStatus(http.StatusUnauthorized)
client.Post("/login/", testclient.Body("application/x-www-form-urlencoded",
strings.NewReader("username=rick&password=wubbalubbadubdub"))).
AssertStatus(http.StatusOK)
client.Get("/me").AssertStatus(http.StatusOK)
client.Post("/logout/").AssertStatus(http.StatusOK)
client.Get("/me").AssertStatus(http.StatusUnauthorized)
}
```
## Where to go next
[Cross-Origin Requests](/docs/security/cross-origin-requests) covers the protection sessions
require, [Authentication](/docs/security/authentication) covers proving who a caller is in the
first place, [Dependencies](/docs/getting-started/dependencies) covers the releases a session is
written after, and [Cookies](/docs/techniques/cookies) covers cookies of your own.
--------------------------------------------------------------------------------
title: "Cross-Origin Requests"
description: "Refuse state-changing requests a browser sends from another origin, the shape of cross-site request forgery, with no tokens, rendered through your error format, and required wherever sessions are."
version: "0.3.0"
last_updated: "2026-10-10T11:11:46.000Z"
source: "https://muzak.dev/docs/0.3.0/security/cross-origin-requests"
--------------------------------------------------------------------------------
# Cross-Origin Requests
A browser attaches cookies to a request whichever page made it. A page on another site can
submit a form to your application, or make a fetch, and the browser sends the user's session
cookie with it: the request arrives authenticated, and nothing in the cookie says the user did not
ask for it. That is cross-site request forgery, and a session alone cannot tell the difference.
`AppOptions.CrossOriginProtection` can. It refuses a request other than `GET`, `HEAD` or
`OPTIONS` that a browser says came from another origin, with `403`, before anything of the
application runs. It is net/http's own `http.CrossOriginProtection`, which reads the headers every
browser has sent since 2023, so there is no token to put in a form, no cookie to pair it with and
nothing to forget on one route.
## Turning it on
```go
app := muzak.New(muzak.AppOptions{
Title: settings.AppName,
Sessions: &muzak.SessionOptions{Secrets: settings.SessionSecrets},
CrossOriginProtection: &muzak.CrossOriginOptions{},
})
```
The zero value is the whole protection, and it refuses nothing a page on your own origin does.
Sessions cannot be configured without it: a session cookie is exactly the ambient credential
forgery exploits, so that combination is a build error rather than a warning nobody reads. An
application that authenticates with cookies of its own wants it just as much, and that includes
an API key that `APIKeyVerifier` reads from a cookie (see
[Authentication](/docs/security/authentication)): the browser attaches it to a forged request as
readily as a session.
| Field | Default | Effect |
|---|---|---|
| `TrustedOrigins` | none | Origins allowed to send state-changing requests from elsewhere, such as your frontend on another origin |
| `InsecureBypassPatterns` | none | `ServeMux` patterns exempt from the check, such as a webhook that verifies a signature |
## What is refused
A browser says where a request came from in `Sec-Fetch-Site`. A browser too old to send it is
judged by whether its `Origin` names the host the request was sent to.
| Request | `Sec-Fetch-Site` | `Origin` | Outcome |
|---|---|---|---|
| `GET`, `HEAD`, `OPTIONS` | anything | anything | Allowed: these must never change state |
| A form or fetch from your own pages | `same-origin` | your origin | Allowed |
| Typed into the address bar, a bookmark | `none` | none | Allowed |
| From a sibling subdomain | `same-site` | `https://other.example.com` | **Refused**: same site is not same origin |
| From another site | `cross-site` | `https://evil.test` | **Refused** |
| From another site, `Origin` withheld | `cross-site` | none | **Refused** |
| An old browser, from another site | none | `https://evil.test` | **Refused** |
| An old browser, a sandboxed frame | none | `null` | **Refused** |
| An old browser, from your own pages | none | your host | Allowed |
| curl, a mobile app, another server | none | none | Allowed: no browser attached a credential for it |
| From a trusted origin | `cross-site` or `same-site` | a `TrustedOrigins` entry | Allowed |
| Matching a bypass pattern | anything | anything | Allowed |
A `same-site` request is refused deliberately. `SameSite=Lax` cookies are sent with it, so a
compromised or user-content subdomain is exactly where a forgery against the main application
comes from.
A form served by your own application, as in [Forms and HTML](/docs/techniques/forms-and-html),
posts as `same-origin` and passes, with no token in it.
## Trusted origins
```go
CrossOriginProtection: &muzak.CrossOriginOptions{
TrustedOrigins: []string{"https://app.example.com", "http://localhost:5173"},
},
```
An entry is compared exactly with the `Origin` header, which a browser writes as
`scheme://host[:port]` in lower case without the scheme's default port. Entries are checked with
the same rules as [CORS origins](/docs/security/cors), and one that could never match is a build
error naming the spelling to use: a trailing slash or other path, upper case, a default port such
as `:443`, or no scheme. A host outside ASCII is refused too, since a browser sends its punycode
(`xn--`) spelling. A pattern such as `https://*.example.com` and `*` are refused, since this
list matches whole origins only, and `null` is refused outright, because a sandboxed frame or a
`file:` page sends it, so any page can.
## Bypass patterns
```go
CrossOriginProtection: &muzak.CrossOriginOptions{
InsecureBypassPatterns: []string{
"POST /webhooks/{provider}", // verified by its signature, not a cookie
"POST /payments/return", // a payment provider posts its form here
},
},
```
A bypassed route accepts a forged request from any page, so list only one that authenticates the
request some other way, or that carries nothing worth forging. Patterns use
[`http.ServeMux`](https://pkg.go.dev/net/http#hdr-Patterns) syntax and match a request only as
`ServeMux` would match it directly: a path it would first clean or redirect, such as
`/webhooks/../items`, is checked as usual. A pattern `ServeMux` refuses, two that conflict, and
one whose method is `GET`, `HEAD` or `OPTIONS`, which are never refused and so bypass nothing, are
build errors.
**A pattern that ends in `/` matches everything beneath it**, as it does in `ServeMux`.
`"POST /webhooks/"` exempts every path under `/webhooks/`, so such a pattern is warned of when the
application is built; end it in `{$}`, as `"POST /webhooks/{$}"`, to match that one path. A
pattern whose path is `/` alone, such as `"POST /"`, with or without a method or a host, is a
build error, since it would turn the protection off for everything rather than exempt a route.
Name each path in full, or end the pattern with `{$}`, as in `"POST /webhooks/{$}"`, to match
that one path alone.
## The refusal
A refusal is rendered by the application's error renderer like any other error:
```json
{
"error": {
"code": "cross_origin_request",
"message": "Cross-origin requests that change state are not accepted.",
"status": 403
},
"request_id": "01a122b9-5eaf-7b37-93ff-ee7cc407d0a4"
}
```
With [problem details](/docs/techniques/problem-details) it is a `Problem` whose `code` is
`cross_origin_request` and whose type is `cross_origin_request`, or `about:blank` when
no `TypeBase` is set. The code is `muzak.CodeCrossOriginRequest`, the message is
translatable at `muzak.security.cross_origin`, and the response carries
`Vary: Origin, Sec-Fetch-Site` and `Cache-Control: no-store`. Each refusal is logged at warn level
with the method, the path, the request identifier and the two headers it was decided by, cut to a
bounded length and escaped, so a forged header cannot forge a log line.
## Where it sits in the chain
```
RequestID -> tracing and Observer -> SecurityHeaders -> Recovery -> health probes
-> Locale -> AccessLog -> AllowedHosts and RedirectHTTPS -> CORS -> cross-origin check
-> your middleware -> /docs and /openapi.json -> routes and mounts
```
Tracing, the observer, health probes, `AllowedHosts` and `RedirectHTTPS` are in the chain only
when they are configured. The check runs before anything that belongs to the application: no
middleware installed with `Use`, no guard, provider, binder or handler, no mounted handler and no
documentation sees a refused request. It runs inside CORS, so a refusal sent to an origin CORS
allows carries the `Access-Control-Allow-Origin` that lets the page's script read why it was
refused. It runs inside the access log, so a refusal is logged as a response like any other.
Health probes are answered before it, and are `GET`s in any case.
## With CORS
CORS and this check answer different questions. CORS decides which origins may **read** a
response; this decides which may **change state**. An origin CORS allows is not trusted here by
that alone, because letting another origin read your API and letting it act as your users are
different decisions. A frontend served from its own origin, calling your API with credentials,
is listed in both:
```go
CORS: muzak.CORSOptions{
AllowedOrigins: []string{"https://app.example.com"},
AllowCredentials: true,
},
CrossOriginProtection: &muzak.CrossOriginOptions{
TrustedOrigins: []string{"https://app.example.com"},
},
```
A preflight is an `OPTIONS`, so it always passes this check and is answered by CORS. The request
it announced is then checked as any other.
## With WebSockets
A WebSocket handshake is a `GET`, so this check never refuses one. Cross-site WebSocket hijacking
is the WebSocket check's to stop: `WSOptions.AllowedOrigins` refuses a handshake from another
origin until it is listed. See [The origin check](/docs/realtime/websockets#the-origin-check).
## Safe methods must stay safe
`GET`, `HEAD` and `OPTIONS` are never refused, because a page on another site can trigger them
by a link or an image without any script at all, and refusing them would break navigation. That
only protects you if those methods change nothing. A `GET /logout` or a `GET /delete?id=7` is a
forgery waiting to happen, whatever this check does. Put every state change behind `POST`,
`PUT`, `PATCH` or `DELETE`.
## Behind a proxy, and over plain HTTP
Browsers send `Sec-Fetch-Site` only to a secure origin: `https`, or `localhost`. Over plain HTTP
to any other host, and from a browser older than 2023, the check falls back to comparing the
host in `Origin` with the request's `Host`. Two consequences follow:
- A proxy that rewrites `Host`, to an internal name say, makes that fallback refuse your own
pages. Pass the original `Host` through, which is also what
[`AllowedHosts`](/docs/security/hosts-and-https) needs.
- The fallback cannot see the scheme, so a request from `http://example.com` to
`https://example.com` is let through by a browser that sends no `Sec-Fetch-Site`. Every current
browser sends it over https, and `Strict-Transport-Security`, which `SecurityHeaders` sends over
TLS, keeps the plain HTTP page from existing in the first place.
## Testing
```go
func TestFormsFromOtherSitesAreRefused(t *testing.T) {
client := testclient.New(t, buildApp())
client.Post("/logout/",
testclient.Header("Origin", "https://evil.test"),
testclient.Header("Sec-Fetch-Site", "cross-site"),
).AssertStatus(http.StatusForbidden).AssertErrorCode(muzak.CodeCrossOriginRequest)
// The test client sends neither header, like any non-browser client.
client.Post("/logout/").AssertStatus(http.StatusOK)
}
```
## Where to go next
[Sessions](/docs/security/sessions) covers the cookie this protects, [CORS](/docs/security/cors)
covers reading responses from another origin,
[Problem Details](/docs/techniques/problem-details) covers the error format a refusal can take,
and [Safe Defaults](/docs/security/safe-defaults) covers the rest of what is denied until it is
configured.
--------------------------------------------------------------------------------
title: "Server Configuration"
description: "The listener, its timeouts, the run methods, and a shutdown that drains requests before it releases the resources they were using."
version: "0.3.0"
last_updated: "2026-10-10T06:43:18.000Z"
source: "https://muzak.dev/docs/0.3.0/deployment/server-configuration"
--------------------------------------------------------------------------------
# Server Configuration
`AppOptions` embeds `ServerOptions`, so the listener is configured in the same literal as
everything else.
```go [cmd/main.go]
app := muzak.New(muzak.AppOptions{
Title: "Awesome API",
Version: "1.0.0",
Addr: settings.Addr,
ReadHeaderTimeout: 5 * time.Second,
ReadTimeout: 30 * time.Second,
WriteTimeout: 30 * time.Second,
IdleTimeout: 120 * time.Second,
ShutdownTimeout: 15 * time.Second,
MaxHeaderBytes: 64 << 10,
})
```
Every one of those already has that value by default. They are written out here to show
what they are, not because they need setting.
## Timeouts
| Field | Default | Bounds |
|---|---|---|
| `ReadHeaderTimeout` | 5s | How long a client may take to send the request headers |
| `ReadTimeout` | 30s | How long a client may take to send the headers and body together |
| `WriteTimeout` | 30s | How long a handler may take to write its response |
| `IdleTimeout` | 120s | How long a keep-alive connection may sit unused before it is closed |
| `ShutdownTimeout` | 15s | The one deadline for the whole shutdown: the drain delay, the drain, the background tasks and the lifecycle `Stop`s together |
| `DrainDelay` | 0 | How long a shutdown keeps serving, with readiness reporting unavailable, before the listeners close. It counts against `ShutdownTimeout` |
| `MaxHeaderBytes` | 64 KiB | The size of the request header block |
Every timeout is non-zero on purpose. An `http.Server` left with the standard library's
zero values holds a connection open indefinitely, which is all a slow-loris client needs to
exhaust the connection budget.
Setting one to a negative number disables it, which should be reserved for a server behind
a proxy that enforces its own.
These bound a connection, not the work a route does. A deadline that a route's guards,
providers and handler share, answered with a `503` when it passes, is `muzak.Timeout`; see
[Timeouts](/docs/techniques/timeouts).
**`MaxHeaderBytes` is 64 KiB**, `muzak.DefaultMaxHeaderBytes`, where the default used to be 1
MiB. A client that never finishes a header block holds everything it has sent for as long as
`ReadHeaderTimeout` allows, and with no cap on connections as a whole a megabyte each adds up. An
ordinary request, with its cookies and a token, needs a small fraction of the new limit. Set
`ServerOptions.MaxHeaderBytes` for a deployment that sends larger headers.
**Over HTTP/2, `WriteTimeout` also bounds how long the connection's socket may accept no bytes
at all.** A write deadline on one HTTP/2 stream cannot interrupt a frame already being written,
so a client that granted a large flow-control window and then stopped reading the socket kept
every stream on its connection open past every timeout, event streams included, and a shutdown
ran to its full timeout. The same client over HTTP/1 was cut in under a second. The server sets
`http.HTTP2Config.WriteByteTimeout` from `WriteTimeout`, so a connection whose socket accepts no
bytes for that long is closed, and a disabled `WriteTimeout` disables it too.
**`ReadHeaderTimeout` does not apply to HTTP/2.** `net/http` reads an HTTP/2 header block under
the connection's own timeouts, so a client that never finishes one is held until `IdleTimeout`
(2 minutes by default), not for 5 seconds.
A declared `Content-Length` over a route's body limit is refused before any of the body is read,
whatever `ReadTimeout` is; see [Request Data](/docs/getting-started/request-data#body-size-limits).
WebSocket routes and event streams manage their own deadlines. A stream is a response that
does not end, so the listener's write deadline is cleared for it and replaced with a
deadline that exists only while a write is in progress; the read deadline goes too, once the
request body has been read, since it would cancel the request and blame the client. See
[Server-Sent Events](/docs/realtime/server-sent-events).
## TLS and HTTP/2 options
| Field | Effect |
|---|---|
| `TLSConfig` | Serve HTTPS from a `*tls.Config` |
| `CertFile`, `KeyFile` | Serve HTTPS from a certificate and key on disk. Setting only one of them is a build error |
| `UnencryptedHTTP2` | Also accept HTTP/2 without TLS, sent with prior knowledge, on the same port as HTTP/1 |
`UnencryptedHTTP2` is for a server behind a platform that speaks HTTP/2 to the container in the
clear, such as Cloud Run with an `h2c` port, where a request is cancelled the moment its client
leaves. Over HTTP/1 the platform's proxy keeps the connection to the container open and a handler
runs on. Leave it off anywhere the proxy speaks HTTP/1, and never for a server reachable directly
from an untrusted network. A WebSocket handshake is not carried over HTTP/2 and is answered
`426`. See [Running on Cloud Run](/docs/deployment/cloud-run) and [TLS](/docs/security/tls).
## The listen address
```go
Addr: ":8080" // the default
Addr: "127.0.0.1:8080" // loopback only
Addr: ":0" // any free port, which is what a test wants
```
`app.Addr()` reports the address actually being listened on, which is how a test that asked
for `:0` discovers the port it was given. It returns an empty string before the server has
started.
`app.Config()` returns the fully defaulted options the application was built with, which is
the reliable way to read a value after `New` has filled in the blanks.
## Running
| Method | Stops when |
|---|---|
| `Run()` | The server fails, or `Shutdown` is called from elsewhere |
| `RunContext(ctx)` | `ctx` is cancelled, or the server fails |
| `RunSignals()` | `SIGINT` or `SIGTERM` arrives, or the server fails |
```go [cmd/main.go]
if err := app.RunSignals(); err != nil {
log.Fatal(err)
}
```
`RunSignals` is what a `main` function usually wants: `SIGINT` and `SIGTERM` are what a
terminal, a container runtime and an init system all send to ask a process to stop.
All three build the application first, so a configuration error is reported before any
socket is opened, then start the lifecycle components, then listen. A shutdown asked for
returns nil, because stopping on request is the expected outcome rather than a failure.
An `App` is run by one run method at a time. A second call while one is running, starting or
shutting down returns an error at once and touches nothing the first one uses. Once a run has
returned, the application may be run again. To serve a second address, build a second `App`.
```
14:32:07.482 INFO [Server] Starting Muzak application...
14:32:07.483 INFO [Server] Starting 2 lifecycle components in parallel: item-store, ml-model
14:32:07.501 INFO [Server] Started "item-store" (18ms)
14:32:07.512 INFO [Server] Started "ml-model" (29ms)
14:32:07.513 INFO [Server] All lifecycle components ready (29ms total)
14:32:07.514 INFO [Server] Listening on :8080
```
`RunContext` is the one to reach for when something else decides the process should stop:
```go
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()
if err := app.RunContext(ctx); err != nil {
log.Fatal(err)
}
```
## Shutting down
```go
if err := app.Shutdown(context.Background()); err != nil {
log.Printf("shutdown: %v", err)
}
```
The sequence is the one that matters:
1. Readiness turns unready. With [health checks](/docs/deployment/health-checks) enabled,
the readiness endpoint answers `503` from this moment, while every request is still
served, so a load balancer that probes it stops sending traffic.
2. The server keeps serving for `ServerOptions.DrainDelay`, zero by default, which is the
time that load balancer needs to notice. Set it instead of a `sleep` in a `preStop` hook.
3. The server stops accepting new connections and drains its in-flight requests, giving up
at the deadline and closing whatever remains. At the same time, open WebSocket
connections are closed with `1001 Going Away` and open event streams are ended. Both are
tracked by the application precisely so this can happen: a hijacked connection is no
longer one `net/http` knows about, and a streaming handler would otherwise make the drain
wait out its whole deadline once per stream. From the moment the listeners close,
`Context.AfterResponse` refuses a new task with `ErrBackgroundShuttingDown`, even from a
request still being drained.
4. The [background tasks](/docs/techniques/background-tasks) that handlers registered with
`Context.AfterResponse` are run to the end. At the deadline the ones still queued are
dropped and the ones running have their context cancelled.
5. The lifecycle components are stopped, with what remains of the deadline, or one second if
everything before used all of it.
`ShutdownTimeout` is **one deadline for the whole shutdown**, counted from the call, and the
drain delay comes out of it rather than being added to it; a `DrainDelay` that leaves no time
to drain, or a negative one, is a build error. The WebSocket, event stream and HTTP drains used
to take a full timeout each, and `Stop` had no deadline and could run under live handlers. When
the deadline passes, every connection still open is closed, hijacked ones included, and handlers
get a further 100 milliseconds to notice and return. `Shutdown` returns within
`ShutdownTimeout` plus about one second, unless a component's `Stop` ignores its context, and
`Run` returns once `Shutdown` has finished, after which the application may be run again. Make
`Stop` honour its context, or raise `ShutdownTimeout`.
Components stay usable until the very end, because pulling a database connection out from
under a request that is still running, or a background task that is still sending an email,
would turn an orderly shutdown into a burst of errors.
`Shutdown` is safe to call more than once and from more than one goroutine; only the first
call does the work. The context argument can cut the wait short; pass `context.Background()`
to use the configured timeout alone.
Called when no run is in progress, `Shutdown` returns nil and is kept for the next run, which
returns nil at once without serving, as `ListenAndServe` returns `ErrServerClosed` after
`Shutdown`. That is what makes `go app.Run()` followed by `app.Shutdown(ctx)` reliable, even
when the goroutine has not reached `Run` yet. Only that next run is stopped, so a `Shutdown`
made after a run has already returned stops the next one too, and code that runs the
application again should not shut it down twice in between.
```
14:32:41.902 INFO [Server] Shutting down, waiting for in-flight requests...
14:32:41.903 INFO [Server] Closed 3 websocket connections
14:32:41.911 INFO [Server] Stopping 2 lifecycle components
14:32:41.913 INFO [Server] Stopped "ml-model" (2ms)
14:32:41.918 INFO [Server] Stopped "item-store" (5ms)
14:32:41.918 INFO [Server] Stopped
```
Give the orchestrator more grace than `ShutdownTimeout`, or it kills the process part way
through the drain. The default of 15 seconds is longer than some platforms allow, so this
is a setting to check rather than inherit (Cloud Run has [a page of its own](/docs/deployment/cloud-run)):
| Platform | Grace after `SIGTERM` | Where it is set |
|---|---|---|
| Cloud Run | about 10s | fixed, so `ShutdownTimeout` must come down |
| Kubernetes | 30s | `terminationGracePeriodSeconds` |
| ECS | 30s | `stopTimeout` |
Leave room after the drain for anything the application flushes on the way out. A service
that publishes to a message broker has to get its buffered messages away once the last
request is answered, and that time comes out of the same grace period.
## Serving it yourself
`App` implements `http.Handler`, so it can be mounted inside a server you build.
```go
if err := app.Build(); err != nil {
return err
}
if err := app.StartLifecycle(ctx); err != nil {
return err
}
defer app.StopLifecycle(context.Background())
server := &http.Server{
Addr: ":8080",
Handler: app,
ReadHeaderTimeout: 5 * time.Second,
}
return server.ListenAndServe()
```
Three things become yours when you do that: the timeouts, which Muzak would otherwise have
set for you, the lifecycle, which nothing else will start, and the shutdown sequence above,
which `App.Shutdown` alone runs. Without it, readiness reports unavailable only once
`StopLifecycle` is called, there is no `DrainDelay`, and tasks registered with
`Context.AfterResponse` still run but nothing waits for them before the components stop.
A build failure is reported
as a `500` for every request with the reason logged once, which is why `Build` is worth
calling first. The `500` is the default error envelope, or a problem under
`AppOptions.ProblemDetails`, in fixed English: a custom `ErrorRenderer` and the translations
are not used for it.
The same shape mounts the application under a path in a larger server:
```go
mux := http.NewServeMux()
mux.Handle("/api/", http.StripPrefix("/api", app))
```
Mounting under a prefix with `muzak.WithPrefix` is usually better, because the generated
document then carries the real paths. Behind `http.StripPrefix`, a lookup path that does not
begin with `/` matches nothing: the router used to drop the first byte of one, so a request for
`/apiXadmin/panel` was served as `/admin/panel`, and a firewall or cache keyed on the URL saw a
different path from the one the application routed on.
## A base context
```go
app := muzak.New(muzak.AppOptions{
Title: "Awesome API",
BaseContext: func(l net.Listener) context.Context {
return context.WithValue(context.Background(), tenantKey{}, tenant)
},
})
```
Every request context derives from what this returns. When it is nil, requests derive from
`context.Background`.
## Checking the configuration before deploying
```go
func TestAppBuilds(t *testing.T) {
if err := buildApp().Build(); err != nil {
t.Fatalf("Build = %v", err)
}
}
```
`Build` reports every problem at once: duplicate routes, unbindable input types, path
parameters no field binds or declared twice, duplicate operation identifiers, malformed
prefixes, a `MaxConnections` set anywhere but the application, a missing static directory, two
mounts at one path, a CORS origin that could never match or is `"null"`, a body type the JSON
decoder refuses, a certificate without its key, a `Dep` field no provider fills, sessions
without cross-origin protection, a health path a route already answers, and a `DrainDelay`
that leaves no time to drain. One test keeps all of them out of a deployment.
Configuration calls made after the first build (`Use`, `Options`, `Include`, route and mount
registration) panic, naming the call. See [Routers](/docs/getting-started/routers#options-applied-after-creation).
## In production
A short list of things worth deciding before the first deployment:
```go
app := muzak.New(muzak.AppOptions{
Title: settings.AppName,
Version: buildVersion,
Addr: settings.Addr,
// A generated client should point at the real host.
Servers: []muzak.Server{{URL: "https://api.example.com", Description: "production"}},
// Behind a load balancer, or every request is attributed to the balancer.
ClientIP: muzak.ClientIPOptions{TrustedProxies: settings.TrustedProxies},
// Liveness at /livez and readiness at /readyz, access-logged at debug level
// so a platform probing every second does not drown out real traffic.
Health: muzak.HealthOptions{Enabled: true},
// Keep serving, with readiness down, while the load balancer notices.
DrainDelay: 5 * time.Second,
})
```
- **Logging** picks JSON on its own when the output is not a terminal, so a container gets
parseable logs with no configuration. Force it with
`LoggerOptions{Format: muzak.LogFormatJSON}` if something in between confuses the
detection.
- **A rate limit policy**, with a shared storage if the service runs more than once. See
[Rate Limiting](/docs/techniques/rate-limiting).
- **A `MaxLifetime`** on the WebSocket and event stream routes a client you do not control can
open, so a peer that answers every ping and says nothing cannot hold a slot until the server
stops. See [WebSockets](/docs/realtime/websockets#ending-a-connection-on-purpose) and
[Server-Sent Events](/docs/realtime/server-sent-events#ending-a-stream-on-purpose).
- **`AppOptions.AllowedHosts`**, the names the service answers to. A request for any other
host, a WebSocket handshake included, is refused with `421` before anything else runs,
which also stops a DNS-rebinding page aimed at a server on a loopback or private address.
`WSOptions.AllowedHosts` is the narrower check, for one route's WebSocket handshakes
alone. See [Allowed Hosts and HTTPS](/docs/security/hosts-and-https).
- **`Cache-Control`** on anything public served from behind a guard, which is otherwise sent
`private, no-cache`.
- **`DisableDocs`** if the deployment must not describe itself, which stops the document
as well as any page. Leaving `DocsUI` unset already means no page is served; this is
for the document too. It is worth generating in CI either way, so a breaking change
shows up in a diff. See [OpenAPI](/docs/fundamentals/openapi).
- **Health checks** for the platform to probe. `AppOptions.Health` answers `/livez` and
`/readyz` ahead of routing, out of the document and clear of `App.Use` middleware, guards
and the rate limit, and
readiness reports unavailable as soon as a shutdown begins. A readiness check such as a
database ping goes in `HealthOptions.Checks`. See
[Health Checks](/docs/deployment/health-checks).
## Building the binary
```bash
go build -o awesome-api ./cmd
```
```dockerfile [Dockerfile]
FROM golang:1.27 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /out/awesome-api ./cmd
FROM gcr.io/distroless/static-debian12
COPY --from=build /out/awesome-api /awesome-api
EXPOSE 8080
ENTRYPOINT ["/awesome-api"]
```
Muzak has no third-party dependencies, so `CGO_ENABLED=0` and a static base image are
enough. A frontend embedded with `//go:embed` travels inside the same binary, so the image
holds one file. See [Static Files and Frontends](/docs/techniques/static-files).
Make sure the runtime forwards `SIGTERM` to the process rather than to a shell wrapper, or
`RunSignals` never sees it and the drain never happens.
## Where to go next
[Behind a Proxy](/docs/deployment/behind-a-proxy) covers what changes when
something sits in front of the service, and
[Lifecycle](/docs/getting-started/lifecycle) covers the components start-up and
shutdown are sequencing.
--------------------------------------------------------------------------------
title: "Behind a Proxy"
description: "Which address a request is attributed to, why no forwarding header is believed until a proxy is named, and what else changes with a load balancer in front."
version: "0.3.0"
last_updated: "2026-10-10T06:40:18.000Z"
source: "https://muzak.dev/docs/0.3.0/deployment/behind-a-proxy"
--------------------------------------------------------------------------------
# Behind a Proxy
Muzak attributes a request to the peer that opened the connection, and ignores every
forwarding header. That is the only safe default: a forwarding header is a request header
like any other, and a server that believes one without knowing who wrote it lets any client
claim any address it likes.
Behind a proxy the default is wrong in the other direction, since every request then appears
to come from the proxy. Naming the proxy is what makes the header believable.
## Naming the proxy
::code-group
```go [cmd/main.go]
app := muzak.New(muzak.AppOptions{
Title: settings.AppName,
Addr: settings.Addr,
// Which address a request is attributed to. Nothing is believed from a
// header until the proxy that wrote it is named here.
ClientIP: muzak.ClientIPOptions{TrustedProxies: settings.TrustedProxies},
})
```
```go [core/config.go]
type Settings struct {
// TrustedProxies lists the proxies whose X-Forwarded-For header is
// believed, as a comma-separated list of addresses or CIDR prefixes. It is
// empty by default, so every request is attributed to the peer that made
// it: a forwarding header is written by whatever sent the request, and
// believing one from an unknown sender hands every client the ability to
// choose which budget it spends.
TrustedProxies []string `env:"TRUSTED_PROXIES"`
}
```
```bash [.env]
# Proxies whose X-Forwarded-For header is believed, as a comma-separated list of
# addresses or CIDR prefixes. Leave it empty when nothing sits in front of this
# service.
TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12
```
::
Entries are plain addresses (`10.1.2.3`) or CIDR prefixes (`10.0.0.0/8`), and both address
families are accepted. An entry that cannot be parsed is reported when the application is
built, rather than quietly widening or narrowing the policy. A prefix written in the
IPv4-in-IPv6 form, such as `::ffff:10.0.0.0/104`, means the IPv4 prefix it wraps (`10.0.0.0/8`).
It used to parse and then match nothing, leaving the proxy it named untrusted without a message.
The header is consulted **only** for a request whose peer is trusted. A request arriving
directly from the internet with an `X-Forwarded-For` of its own choosing is attributed to
the address it actually came from.
## How the header is read
The walk goes **right to left** through the forwarding header, which is the only direction that
cannot be lied to. Each hop appends the address it saw, so the rightmost entries were written by
the proxies nearest this server, and the leftmost by whoever sent the request, who may have
invented them. Each trusted hop is stepped over, and the first entry that is not a trusted proxy is
the client. If every hop was trusted, the leftmost entry is as close to the client as this server
can see.
- A request arriving from an untrusted peer is attributed to that peer, whatever the header says.
- An entry that cannot be read (an obfuscated identifier, a mangled address) stops the walk: it
hides whatever is to its left, so the nearest hop that was understood is the most that can be
claimed. A port after an address, and the brackets IPv6 needs when there is one, are tolerated.
- At most 64 entries are read, so a header of ten thousand addresses is not parsed in full on the
way to deciding who sent it.
- The address is normalised: an IPv4-in-IPv6 address is the IPv4 it carries, and an IPv6 **zone**
(`fe80::1%eth0`) is dropped. A zoned address was never inside a trusted prefix, so a trusted
proxy that reported itself with a zone was taken for the client, and one client could mint any
number of keys by appending `%a`, `%b` and so on to its own address.
## A header other than X-Forwarded-For
```go
muzak.ClientIPOptions{
TrustedProxies: []string{"10.0.0.0/8"},
Header: "CF-Connecting-IP",
}
```
`DefaultForwardedHeader` is `X-Forwarded-For`. Set `Header` to whatever your proxy actually
writes, such as `CF-Connecting-IP` or `X-Real-IP`.
### The standard `Forwarded` header
```go
muzak.ClientIPOptions{
TrustedProxies: []string{"10.0.0.0/8"},
Header: "Forwarded",
}
```
`Forwarded` is read as RFC 7239 defines it: the address is the `for` parameter of each entry, as
in `for=203.0.113.9;proto=https` or `for="[2001:db8::1]:443"`, and the other parameters are
skipped. Parameter names in any case, quoted strings, several entries and several header lines are
all read, and the walk is the same right-to-left one, under the same trust rule, as for
`X-Forwarded-For`. An entry whose `for` is `unknown` or an obfuscated identifier such as `_hidden`,
or that has no `for` at all, stops the walk at the nearest trusted hop. A comma or semicolon
inside a quoted parameter is data, so a proxy that quotes a client's `Host` into its own entry
cannot be talked into a client's `for`.
Before 0.2.9 the header was accepted but its entries could not be read, so every client behind
the proxy resolved to the proxy and shared one budget.
## Reading the address
```go
ctx.ClientIP() // the address as a string, normalised
ctx.ClientAddr() // the same as a net/netip.Addr, for comparing against a prefix
```
```go
addr := ctx.ClientAddr()
if !addr.IsValid() {
// The connection has no address that can be parsed, which happens on a
// listener that is not addressed by IP, such as a Unix socket.
}
if office.Contains(addr) {
// ...
}
```
The result is normalised, so an address written in IPv4-in-IPv6 form and the same address
written plainly are one value rather than two. That is what stops a client from being
counted twice, or from evading a count, by rewriting its own address.
`ClientIP` returns the empty string when the connection has no parsable address. Code that
keys on the result has to handle that, which is what `muzak.IPTracker` does by refusing the
request rather than counting every such request under one shared key.
## What depends on getting this right
| Feature | Uses the client address for |
|---|---|
| Rate limiting | `IPTracker` and `IPPrefixTracker` key the budget on it |
| WebSockets | `MaxConnectionsPerIP` bounds one client's share of the process |
| Server-sent events | `MaxStreamsPerIP` does the same for streams |
| IPv6 grouping | `ConnectionIPv6Prefix` (a /56 by default) decides how many addresses count as one client, for the connection caps and for `IPTracker` |
| Anything you write | Deny lists, audit logs, geo decisions |
With an untrusted proxy in front and nothing named in `TrustedProxies`, every request
carries the proxy's address, so the whole world shares one rate limit budget and one
connection allowance. With a *wrongly* trusted header, any client picks its own budget by
writing a header. Both failure modes are why this is configuration rather than a guess.
## Rate limiting behind a proxy
Once the address is right, the tracker follows. The default `IPTracker` counts an IPv4 address
exactly and an IPv6 address by its **/56**, the block a provider delegates to one home or small
site, so a client that rotates addresses inside its own range still spends one budget.
```go
muzak.WithRateLimit(muzak.RateLimitOptions{
Quotas: []muzak.Quota{
{Name: "short", Window: time.Second, Limit: 3},
{Name: "long", Window: time.Minute, Limit: 100},
},
})
```
`ClientIPOptions.ConnectionIPv6Prefix` changes the prefix for the tracker and for the
per-client connection caps together. Set 64 where many unrelated users share one /56, which also
loosens the connection caps, or 48 where sites are delegated a /48. For one route,
`IPPrefixTracker(32, 64)` keeps IPv4 exact and collapses IPv6 to the length you give it. A proxy
that already bounds per-address traffic can set `Tracker: IPPrefixTracker(32, 128)` to count every
IPv6 address on its own. See [Rate Limiting](/docs/techniques/rate-limiting).
A service running more than once needs a storage the processes share, or a limit of a
hundred a minute becomes a hundred a minute per process.
## TLS terminated in front
Common, and it changes four things:
- The service speaks plain HTTP, so `CertFile`, `KeyFile` and `TLSConfig` stay empty.
- Cookies still need `Secure: true`, because the browser leg of the connection is HTTPS and
that is the leg the attribute governs.
- `SecurityHeaders` sends `Strict-Transport-Security` only when `r.TLS != nil`, so behind a
proxy that terminates TLS it is not sent: the request Muzak sees is not the encrypted one.
Set it at the proxy, or in middleware gated on whatever header the proxy writes.
- `AppOptions.RedirectHTTPS` cannot see the client's scheme either, so it believes the
`X-Forwarded-Proto` of a proxy that `TrustedProxies` names (or the `proto` of `Forwarded`,
when that is `ClientIPOptions.Header`) and ignores the claim from any other peer.
`AppOptions.AllowedHosts` never reads `X-Forwarded-Host`, so list the `Host` the proxy
passes on.
See [TLS](/docs/security/tls) and [Allowed Hosts and HTTPS](/docs/security/hosts-and-https).
## Streaming through a proxy
An event stream is the request most likely to be broken by something in the middle. Muzak
sets `Cache-Control: no-cache, no-transform` and `X-Accel-Buffering: no`, and writes a
keepalive comment every `SSEOptions.KeepAlive`, so a proxy does not close a connection it
believes to be idle.
Check the proxy's own settings too. `proxy_buffering off` and a read timeout longer than
the keepalive are what nginx needs; the equivalents exist elsewhere. A WebSocket needs the
proxy configured to upgrade the connection at all.
A keepalive arrives every interval since 0.2.8. Before, it could arrive at 15, 45 and 60 seconds
when asked for every 15, twice the silence an idle timeout was meant to be kept off with. And a
stream that a proxy would otherwise hold open for as long as its client keeps reading can be given
a `MaxLifetime`, so a client that reads nothing is not held until the server stops. See
[Server-Sent Events](/docs/realtime/server-sent-events#ending-a-stream-on-purpose).
For one platform's measured behaviour, including the address its proxy presents and what changes
between HTTP/1 and `h2c`, see [Running on Cloud Run](/docs/deployment/cloud-run).
## Request identifiers
Muzak generates an identifier per request and ignores an inbound `X-Request-Id`, because
an attacker-controlled identifier is an attacker-controlled log field.
Where a trusted proxy assigns the identifier and you want the two logs to agree, accept it:
```go
app := muzak.New(muzak.AppOptions{
Title: "Awesome API",
TrustRequestIDHeader: true,
})
```
An inbound value is honoured only if it parses as a UUID, so it can never carry newlines or
control characters into a log line. Turn it on only where nothing untrusted can reach the
service directly, since the header would otherwise come straight from the client.
## Trace context
With tracing on, a request's `traceparent` is the same question asked of a trace: by default
any valid one is continued, sampling decision included, so a client can attach its requests
to another trace or have every one of them sampled. For a service the internet reaches, set
`TracingOptions.Parent` to `muzak.TraceParentFromTrustedProxies`, which continues a trace
only for a connection from an address in `ClientIPOptions.TrustedProxies`:
```go
app := muzak.New(muzak.AppOptions{
Title: "Awesome API",
ClientIP: muzak.ClientIPOptions{TrustedProxies: settings.TrustedProxies},
Tracing: muzak.TracingOptions{
Tracer: exporter,
Parent: muzak.TraceParentFromTrustedProxies,
},
})
```
That is only as good as the proxy. One that passes a client's `traceparent` on unchanged, as
many load balancers do, passes the client's choice on with it, so the proxy has to replace or
remove the header; where it cannot, use `muzak.TraceParentIgnore`, which always starts a new
trace. See [Observability](/docs/fundamentals/observability).
## Body limits in two places
The proxy has its own body limit, and so does Muzak. Set the proxy's at or above the
route's, or a large upload is refused with the proxy's error page rather than the
application's `413` and its error envelope. See
[File Uploads](/docs/techniques/file-uploads).
Muzak refuses a body whose declared `Content-Length` is over the route's limit before it reads
any of it. A proxy that holds the whole request until it is complete, as Cloud Run does over
HTTP/1, still takes the upload first: the early refusal cannot spare bytes a proxy has already
buffered.
## Checking it works
```bash
curl -s http://localhost:8080/whoami -H 'X-Forwarded-For: 203.0.113.9'
```
```go
type WhoAmIOut struct {
ClientIP string `json:"client_ip"`
}
r.Get("/whoami", func(ctx *muzak.Context, _ muzak.Empty) (WhoAmIOut, error) {
return WhoAmIOut{ClientIP: ctx.ClientIP()}, nil
}, muzak.Hidden())
```
Called directly, that answers with your own address whatever the header says. Called
through a proxy named in `TrustedProxies`, it answers with what the proxy reported. Those
two results are the whole configuration, and they are worth checking once per deployment.
Remove the route afterwards, or leave it `Hidden` and behind a guard.
## Where to go next
[Server Configuration](/docs/deployment/server-configuration) covers the listener
itself, and [Rate Limiting](/docs/techniques/rate-limiting) covers the feature
that depends on this most.
--------------------------------------------------------------------------------
title: "Running on Cloud Run"
description: "What was measured on Cloud Run rather than read from its documentation - the address its proxy presents, HTTP/1 against h2c, timeouts, streams and rollouts - and what was not established."
version: "0.3.0"
last_updated: "2026-10-10T06:43:18.000Z"
source: "https://muzak.dev/docs/0.3.0/deployment/cloud-run"
--------------------------------------------------------------------------------
# Running on Cloud Run
What follows was measured, not read from documentation. A test application built from the
framework was deployed to Cloud Run (us-central1, private services, minimum instances 0) on
2026-09-29, once on an HTTP/1 container port and once on an `h2c` container port, and driven from
outside with real clients. Each statement names what was observed. Where something was not
established, it says so, and the last section lists what.
## Client addresses: trust the proxy or every client is one client
The address the application sees as the peer is a link-local one, `169.254.169.126`, for every
request. It is Cloud Run's proxy, not the client. With the default `ClientIPOptions`, which trusts
no proxy, `Context.ClientIP()` is therefore that address for every user, and everything keyed on
it (a rate limit, `MaxConnectionsPerIP`, `MaxStreamsPerIP`) treats all users as one. Set the
range:
```go
muzak.AppOptions{
ClientIP: muzak.ClientIPOptions{TrustedProxies: []string{"169.254.0.0/16"}},
}
```
With it set, `ClientIP()` was the caller's real address on every request, including ones that
arrived with a spoofed `X-Forwarded-For` of one, two or three invented addresses in front of the
real one: the proxy appends the real address last, and the framework reads from the right, so the
invented ones were ignored. `Forwarded: for="..."` carries the real address too.
See [Behind a Proxy](/docs/deployment/behind-a-proxy) for how the header is read and what else
depends on the address.
## HTTP/1 or h2c on the container port
Cloud Run speaks HTTP/1 to the container unless the port is named `h2c`. The two behaved
differently in ways that matter:
| | HTTP/1 port | `h2c` port |
|---|---|---|
| Request body | held by the platform until it is complete; over 32 MiB it is refused by the platform with an HTML 413 before the application sees it | streamed; 33 MiB reached the handler and was answered by it |
| Body over the route's `MaxBodySize`, declared in `Content-Length` | refused by the framework in 390 ms for 64 KiB bodies, but a large declared body is held by the platform first: with `Expect: 100-continue` the platform answered `100 Continue` itself within 50 ms and then waited for the whole body, so the framework's early refusal could not spare the upload | refused by the framework after 196 KB had arrived, in 394 ms |
| Client leaves mid-request | the handler kept running: still running 45 seconds after the client disconnected | the handler's context was cancelled 400 ms after |
| WebSocket | works | the platform refused the handshake with 502 ("protocol error") |
So: serve an API that has no WebSocket routes on an `h2c` port, and set
`ServerOptions.UnencryptedHTTP2` so the server accepts it. Keep WebSocket routes on an HTTP/1
port, which means a separate service if one application needs both.
```go
muzak.AppOptions{
ServerOptions: muzak.ServerOptions{UnencryptedHTTP2: true},
}
```
`UnencryptedHTTP2` accepts HTTP/2 without TLS, sent with prior knowledge, on the same port as
HTTP/1. Leave it off anywhere the proxy speaks HTTP/1, and never for a server reachable directly
from an untrusted network. A WebSocket handshake is not carried over HTTP/2 and is answered `426`.
`App.Run` and `App.RunSignals` could not serve h2c before it existed.
On an HTTP/1 port, do work that should stop when its client leaves in steps that check a deadline
of their own, since the handler's context is not cancelled by the disconnect.
## Timeouts
The framework's default `WriteTimeout` is 30 seconds and Cloud Run's request timeout is longer
(300 seconds by default, up to 3,600). A non-streaming handler that runs past 30 seconds is ended
by the server, and the client saw a 503 from the platform after 60 seconds in the test. Raise
`ServerOptions.WriteTimeout` for a route that takes that long, or stream. WebSocket and
event-stream routes lift the deadline themselves.
`WriteTimeout` bounds the connection, not the work. A route that should give up on its own,
and tell the client so with a `503` and `Retry-After` rather than leave the answer to the
platform, takes a `muzak.Timeout` shorter than `WriteTimeout`: its guards, providers and handler
see the deadline on the request's context. See [Timeouts](/docs/techniques/timeouts).
## Streams
- **Event streams** arrived incrementally through the platform: a producer sending every 500 ms
was received at gaps of 495 to 506 ms, so nothing buffers them.
- **Keepalive** comments keep an idle stream open. The test found the keepalive arriving at 15, 45
and 60 seconds when asked for every 15, a bug fixed in 0.2.8 (it skipped a tick whenever
its own previous write had landed just after the one before). After the fix it arrives every
interval.
- **`MaxLifetime`** ended a stream cleanly after 20 seconds, and a reconnect with `Last-Event-ID`
resumed from the next event on the same instance.
- **WebSockets** on the HTTP/1 port survived 100 seconds with no application traffic, with the
default keepalive (a ping every 30 seconds) and for a handler that only reads. A message over
the read limit ended the connection; the client saw the connection lost (1006) more often than
the 1009 the server sends. That was a fault in the server, fixed in 0.2.8: it closed the
socket with the client's data still unread, which makes the kernel reset the connection and drop
the close frame in flight. It now keeps reading until the peer answers or the grace period ends,
and in a local test the `1009` reached the client in 50 of 50 runs, where it had reached it in 0
of 50. That was not re-measured on Cloud Run.
## Deployments
A connection open when a new revision starts serving is not closed by the rollout: a WebSocket and
an event stream were both still open five minutes after the new revision took over. They are
closed when Cloud Run scales the old instance in, and then the framework sends its going-away
close (1001) or ends the stream cleanly. A connection that must not outlive a deploy should be
given a `MaxLifetime`.
## Not established
- **Limits across several instances.** The framework's in-memory rate limiter counts per
instance. The test asked for several by allowing one request at a time per instance, but Cloud
Run served all twenty concurrent requests from one instance within the ten seconds of the test,
so the budget across instances was not measured. A limit that must hold across instances needs a
store they share. See [Rate Limiting](/docs/techniques/rate-limiting).
- **Cloud Run's second generation execution environment, and regions other than us-central1,**
were not compared.
## Where to go next
[Server Configuration](/docs/deployment/server-configuration) covers the timeouts and the
shutdown deadline (Cloud Run allows about ten seconds after `SIGTERM`, so `ShutdownTimeout` has to
come down), and [Behind a Proxy](/docs/deployment/behind-a-proxy) covers the address a request is
attributed to.
--------------------------------------------------------------------------------
title: "Health Checks"
description: "Liveness and readiness endpoints a platform can probe, readiness checks that a flood of probes cannot turn into a flood of pings, and a shutdown that takes the instance out of rotation before it closes the socket."
version: "0.3.0"
last_updated: "2026-10-10T06:32:04.000Z"
source: "https://muzak.dev/docs/0.3.0/deployment/health-checks"
--------------------------------------------------------------------------------
# Health Checks
A platform asks a running service two different questions. **Liveness** asks whether the
process should be restarted, and the only honest answer is whether it still serves at all.
**Readiness** asks whether it should be sent traffic right now, which depends on its
database, its cache and on whether it is starting up or shutting down. Muzak answers both
once `AppOptions.Health` is enabled.
```go [cmd/main.go]
app := muzak.New(muzak.AppOptions{
Title: "Awesome API",
Health: muzak.HealthOptions{
Enabled: true,
Checks: []muzak.HealthCheck{
{Name: "database", Check: db.PingContext},
{Name: "cache", Check: func(ctx context.Context) error {
return redisClient.Ping(ctx).Err()
}},
},
},
// Keep serving for five seconds after readiness drops, so the load
// balancer has time to notice before the socket closes.
DrainDelay: 5 * time.Second,
})
```
The zero value of `HealthOptions` serves nothing and costs nothing: no route, no middleware,
no goroutine. Setting a field such as `Checks` without `Enabled` is a build error rather than
configuration that silently does nothing.
## The two endpoints
| Path | Answers | When |
|---|---|---|
| `/livez` | `200 {"status":"ok"}` | Whenever the process is serving at all |
| `/readyz` | `503 {"status":"unavailable"}` | Until the lifecycle components have started |
| `/readyz` | `200 {"status":"ok"}` | Once they have, and every check passes |
| `/readyz` | `503 {"status":"unavailable"}` | When a check fails, and from the moment a shutdown begins |
Both take `GET` and `HEAD` and answer anything else with `405` and `Allow: GET, HEAD`, rendered
by the application's error renderer like any other 405. Both are sent with
`Cache-Control: no-store`, so no cache between the platform and the process can answer a probe
with a stale result.
Liveness never runs a check. A database that is down is a reason to stop sending traffic,
not a reason to restart every replica at once, which is what a liveness probe that pinged the
database would do.
The paths move with `LivenessPath` and `ReadinessPath`:
```go
Health: muzak.HealthOptions{
Enabled: true,
LivenessPath: "/_/alive",
ReadinessPath: "/_/ready",
},
```
A path is matched exactly, so `/readyz/` is not the readiness endpoint. It has to be absolute,
in its clean form, and made of letters, digits and `-._~/`, which a probe never has to encode.
The two paths must differ. A path a route, a mount or the documentation already answers is a
build error, because the health endpoint is answered first and would take that path from it
without a word. A frontend or a handler mounted at `/` is the exception: it answers only what
nothing else does, as it does for every route. Its root is its own, though, so a health path
of `/` beside one is a build error too.
## Answered ahead of the application
The health endpoints are answered right after the request identifier, tracing and the request
observer, the security headers and panic recovery, and before everything else:
- **No middleware installed with `App.Use`.** An authenticating middleware that refuses a probe
takes every replica out of rotation.
- **No guard, provider or rate limit**, including those given to `New`. A probe carries no
credentials, and a platform probing every few seconds is the one client that must never be
told to slow down.
- **No CORS policy, host allowlist or redirect to HTTPS.** No browser has any business reading
a probe, and a probe is sent to the pod's own address over plain HTTP, which `AllowedHosts`
and `RedirectHTTPS` would refuse or redirect.
- **Not in the OpenAPI document.** The endpoints are for the platform, not for API clients.
Tracing and the request observer are outside them, so with
[`Tracing` or `Observer`](/docs/fundamentals/observability) configured every probe is
observed, with an empty route, and a sampled one gets a server span named after its method
alone. A readiness `503` counts as a server error there, as any `5xx` does. A `Sampler` sees the
request, so it can decline to record the probes' traces.
Since nothing authenticates a probe, the endpoints say very little. The body is `{"status":"ok"}` or
`{"status":"unavailable"}` and nothing else; the error a check returned is written to the log,
never to the response. A service whose readiness endpoint is reachable only from inside the
platform can ask for the name of each check with `ReportChecks`:
```go
Health: muzak.HealthOptions{
Enabled: true,
ReportChecks: true,
Checks: checks,
},
```
```json
{"status":"unavailable","checks":{"database":"fail","cache":"ok"}}
```
It is off by default because the names of a service's dependencies, and which of them is down
right now, are worth something to an attacker probing an unauthenticated endpoint. Since the
host allowlist does not apply to the health paths, a web page that points its own name at the
service's address (DNS rebinding) can read the body from a browser on the same network as
well. Turn `ReportChecks` on only where the port is reachable from the platform alone.
## Readiness checks
```go
type HealthCheck struct {
// Name identifies the check in logs and, with ReportChecks, in the body.
Name string
// Check returns nil when the dependency is usable.
Check func(ctx context.Context) error
// Timeout bounds one run, defaulting to one second.
Timeout time.Duration
}
```
A `Check` with the signature `func(context.Context) error` fits most clients as they are:
`(*sql.DB).PingContext` is one. A name is required, unique, at most 64 characters, and made of
letters, digits, `-`, `.` and `_`, so it never needs escaping in a log line or a body.
The checks run concurrently, each under its own timeout, so readiness takes as long as the
slowest check rather than the sum. Keep `Timeout` below the probe's own timeout (Kubernetes
defaults `timeoutSeconds` to 1), so a slow dependency is reported as a `503` rather than as a
probe that never got an answer.
### What a flood of probes costs
| Bound | Default | Field |
|---|---|---|
| Runs of the checks | One per interval, however many probes arrive | `CacheInterval`, 1s |
| Probes arriving during a run | Wait for that run; none starts another | |
| Length of one run | The longest check's timeout | `HealthCheck.Timeout`, 1s |
| Goroutines per check | One, ever | |
The combined result is reused for `CacheInterval`. Probes that arrive while the checks are
running wait for that run instead of starting their own, so three thousand probes at once run
each check exactly once. A negative `CacheInterval` runs the checks for every probe that does
not find a run already in progress: concurrent probes still share a run, but the rate is no
longer bounded.
A check that ignores its context and never returns is the case that matters. The probe is
answered at the check's timeout with a `503`, and the check is not started again while its
goroutine is still running: every later probe reports it as failing at once, so a hung
dependency costs one goroutine, not one per probe. A check that panics is recovered and counts
as a failure, and a check that answers after its timeout counts as failed even if it returned
nil.
### What is logged
A check that starts failing is logged at warn level with its error, once. While it keeps
failing it is logged at debug level only, and when it passes again that is logged at info
level, so the log grows with changes of state rather than with the rate of probes.
```
14:32:41.902 WARN [Server] muzak: a readiness check failed; readiness reports unavailable check=database error="dial tcp 10.0.0.5:5432: connect: connection refused"
14:33:02.117 INFO [Server] muzak: a readiness check passes again check=database
```
The error is the check's own text, cut to a bounded length, and may name a host or a user.
Nothing is redacted out of it, since the log is where an operator needs to read it, but it never
reaches a response.
Probes are recorded in the access log at debug level whatever their status, since a platform
probing every few seconds would otherwise outnumber real traffic and a `503` during start-up is
expected rather than an error. Change the level with `AccessLogLevel`, or leave a path out
entirely with `AccessLogOptions.SkipPaths`.
## Start-up and shutdown
Readiness follows the lifecycle. It answers `503` until `StartLifecycle` has succeeded, which
the run methods and the test client do before the socket opens, and again once a shutdown
begins.
**Readiness drops before anything else happens.** The first thing `Shutdown` does is report
unavailable, before any listener closes or any connection is touched, so a load balancer
probing it stops sending traffic while requests in flight still finish. Liveness keeps
answering `200` throughout: a process draining its requests is alive, and restarting it would
cut the drain short.
**`DrainDelay` keeps serving while the load balancer catches up.** A load balancer learns about
a shutdown on its next probe, and Kubernetes removes a terminating pod from its Service while it
sends `SIGTERM`, not before. Requests sent in that gap would find the socket closed. With
`DrainDelay` set, the shutdown waits that long with readiness down and the listeners still
accepting, before it closes them:
```
14:32:41.902 INFO [Server] Shutting down, waiting for in-flight requests...
14:32:41.902 INFO [Server] Readiness now reports unavailable; waiting 5s before closing the listeners
14:32:46.903 INFO [Server] Stopping 2 lifecycle components
14:32:46.910 INFO [Server] Stopped
```
The delay counts against `ShutdownTimeout` rather than being added to it, because the
platform's grace period counts it too. A `DrainDelay` that is not shorter than
`ShutdownTimeout` would leave no time to drain, and is a build error; so is a negative one. The
default of zero closes the listeners at once. The delay applies whether or not health is
enabled, since a platform that removes endpoints on its own clock needs it either way, and it
replaces the `sleep` a `preStop` hook would otherwise hold.
An application run again after a shutdown reports `503` until its components have started once
more, and does not reuse a readiness result from the previous run.
The whole sequence, in order:
1. Readiness reports unavailable.
2. The server keeps serving through `DrainDelay`.
3. The listeners close and requests in flight are drained, while WebSockets are told the
server is going away and event streams are ended.
4. The [background tasks](/docs/techniques/background-tasks) those requests registered are
waited for.
5. The lifecycle components are stopped.
The [test client](/docs/fundamentals/testing) shuts an application down the same way when a
test ends, so a `DrainDelay` in the configuration a test builds delays the end of that test by
as much. Leave it out of the configuration tests use.
## Kubernetes
```yaml
livenessProbe:
httpGet: {path: /livez, port: 8080}
periodSeconds: 10
readinessProbe:
httpGet: {path: /readyz, port: 8080}
periodSeconds: 5
timeoutSeconds: 2
terminationGracePeriodSeconds: 30
```
```go
ShutdownTimeout: 25 * time.Second, // below terminationGracePeriodSeconds
DrainDelay: 5 * time.Second, // at least one readiness period
```
## Serving it yourself
An application served through `App.ServeHTTP` in a server you built answers the health
endpoints the same way, but nothing starts its lifecycle for it, so readiness answers `503`
until you call `StartLifecycle`, and again after `StopLifecycle`. `DrainDelay` belongs to
`Shutdown`, which such a server does not use.
## Where to go next
[Server Configuration](/docs/deployment/server-configuration#shutting-down) covers
`ShutdownTimeout` and the rest of the shutdown, [Lifecycle](/docs/getting-started/lifecycle) the components readiness
waits for, and [Background Tasks](/docs/techniques/background-tasks) the work a shutdown drains
after its requests.