# Muzak

> Muzak is a type-safe web framework for Go, built on net/http and Go 1.27 with no third-party dependencies. A handler is an ordinary typed function: its input type is the request and its return type is the response body, both checked at compile time. Routing, request binding, validation, dependency injection, configuration, structured logging, WebSockets, server-sent events, rate limiting and OpenAPI 3.1 generation are part of the framework rather than separate modules. Install it with `go get muzak.dev/framework`.

This describes Muzak 0.3.0, which is not the current release. The current documentation is at https://muzak.dev/llms.txt, and this version's pages are at https://muzak.dev/docs/0.3.0.

Every default is the conservative one: listener timeouts are non-zero, request bodies are capped, unknown JSON members are rejected, CORS denies every cross-origin request until a policy is written, a cross-origin WebSocket handshake is refused, no forwarding header is believed until a proxy is named, and a panic becomes a generic 500 with the stack recorded only in the log.

The full text of every page is at https://muzak.dev/docs/0.3.0/llms-full.txt.
Every release, and the migration for each breaking change, is at https://muzak.dev/changelog.

## Getting Started

- [Introduction](https://muzak.dev/docs/0.3.0/getting-started/introduction): Muzak is a type-safe web framework for Go. You write plain typed functions, and the framework turns them into an HTTP API with validation, dependency injection and OpenAPI docs.
- [First Steps](https://muzak.dev/docs/0.3.0/getting-started/first-steps): Create a Muzak project, write your first route, run the server and open the generated documentation.
- [Routers](https://muzak.dev/docs/0.3.0/getting-started/routers): Register routes with typed handlers, group them into routers, and mount those routers under prefixes, tags and guards decided by the application.
- [Request Data](https://muzak.dev/docs/0.3.0/getting-started/request-data): How the input struct is filled in from the path, query string, headers, cookies, form and JSON body, which types can be bound, how to keep the body as it arrived for a signature check, and what happens when the client sends something else.
- [Responses](https://muzak.dev/docs/0.3.0/getting-started/responses): The handler's return type is the response model. How status codes, headers, cookies, HTML and empty responses are decided, and when to write the response yourself.
- [Dependencies](https://muzak.dev/docs/0.3.0/getting-started/dependencies): Guards that validate a request, providers that hand a typed value to a handler, Dep fields that declare it on the input, Acquire for values that need cleaning up, request transactions, singletons, and overrides for tests.
- [Error Handling](https://muzak.dev/docs/0.3.0/getting-started/error-handling): One error envelope for every failure, errors that carry their own status, errors that stay opaque, and how to replace the shape entirely.
- [Middleware](https://muzak.dev/docs/0.3.0/getting-started/middleware): The chain that is already installed, the two you can add, where tracing and request metrics hook in, how to write your own, and the one thing that fails quietly in Go.
- [Lifecycle](https://muzak.dev/docs/0.3.0/getting-started/lifecycle): Open a database pool, a cache client or a loaded model before traffic arrives, and release it after the server has drained.
- [Command Line](https://muzak.dev/docs/0.3.0/getting-started/command-line): Create a project, run it while you write it, and read the OpenAPI document it publishes, with the muzak command.

## Fundamentals

- [Configuration](https://muzak.dev/docs/0.3.0/fundamentals/configuration): Read settings from the environment and a dotenv file into a typed struct, with every missing or malformed variable reported together.
- [Validation](https://muzak.dev/docs/0.3.0/fundamentals/validation): Rules declared against the field itself, transforms that mutate before the checks run, cross-field conditions in ordinary Go, and constraints that reach the OpenAPI document.
- [API Versioning](https://muzak.dev/docs/0.3.0/fundamentals/versioning): Serve several versions of an API from one application, with the version read from the path, a header, the Accept header or a function of your own.
- [Logging](https://muzak.dev/docs/0.3.0/fundamentals/logging): Structured logging that is readable in development and parseable in production, with scopes, request identifiers and secrets redacted by key.
- [Observability](https://muzak.dev/docs/0.3.0/fundamentals/observability): A server span per request named after its route, W3C trace context in and out, logs joined to traces, a request metrics hook, and an OTLP exporter, all without a dependency.
- [OpenAPI](https://muzak.dev/docs/0.3.0/fundamentals/openapi): An OpenAPI 3.1 document and a self-contained documentation page, derived from the routes, the types and the validation rules you already wrote.
- [TypeScript](https://muzak.dev/docs/0.3.0/fundamentals/typescript): TypeScript declarations, and an optional fetch client, generated from the OpenAPI document, so a frontend is typed by the same models as the Go handlers.
- [API Compatibility](https://muzak.dev/docs/0.3.0/fundamentals/api-compatibility): Keep the generated OpenAPI document as a baseline, and fail a test when a change would break a client written against it.
- [Testing](https://muzak.dev/docs/0.3.0/fundamentals/testing): Serve an application in-process on a loopback port, through its own server, and exercise middleware, routing, binding, dependencies and error rendering together.
- [Internationalization](https://muzak.dev/docs/0.3.0/fundamentals/internationalization): A locale resolved once per request from the Accept-Language header or wherever else you say, with every string in the response written in it, including the ones the framework produces itself.

## Techniques

- [Headers](https://muzak.dev/docs/0.3.0/techniques/headers): Bind request headers into typed fields, read them directly, and set response headers that a cache and a client can rely on.
- [Cookies](https://muzak.dev/docs/0.3.0/techniques/cookies): Bind cookies into typed fields, set them on a response, and choose the attributes that decide whether a session is safe.
- [JSON](https://muzak.dev/docs/0.3.0/techniques/json): How request bodies are decoded and responses encoded, which struct tags matter, and why the defaults are strict rather than forgiving.
- [Forms and HTML](https://muzak.dev/docs/0.3.0/techniques/forms-and-html): Bind a form body into a typed input, and return an HTML document from the same application that serves the API.
- [File Uploads](https://muzak.dev/docs/0.3.0/techniques/file-uploads): 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.
- [Static Files and Frontends](https://muzak.dev/docs/0.3.0/techniques/static-files): Serve a built frontend and a directory of assets from the same binary as the API, with routes always matched first.
- [Compression](https://muzak.dev/docs/0.3.0/techniques/compression): 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.
- [Rate Limiting](https://muzak.dev/docs/0.3.0/techniques/rate-limiting): A policy of several quotas counted together, a storage you choose, a tracker that decides whose budget is spent, and defaults that fail closed.
- [Response Models](https://muzak.dev/docs/0.3.0/techniques/response-models): 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.
- [Files, Streams and Redirects](https://muzak.dev/docs/0.3.0/techniques/files-streams-redirects): 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.
- [Problem Details](https://muzak.dev/docs/0.3.0/techniques/problem-details): 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.
- [Mounting net/http Handlers](https://muzak.dev/docs/0.3.0/techniques/mounting-handlers): Serve pprof, a metrics handler, a connect-go service or a legacy application beside your routes, behind the same guards, rate limit and middleware.
- [Background Tasks](https://muzak.dev/docs/0.3.0/techniques/background-tasks): 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.
- [Timeouts](https://muzak.dev/docs/0.3.0/techniques/timeouts): 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.
- [HTTP Client](https://muzak.dev/docs/0.3.0/techniques/http-client): 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.
- [Typed Endpoints](https://muzak.dev/docs/0.3.0/techniques/typed-endpoints): 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.
- [MCP Tools](https://muzak.dev/docs/0.3.0/techniques/mcp-tools): 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.

## Real-time

- [WebSockets](https://muzak.dev/docs/0.3.0/realtime/websockets): 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.
- [Server-Sent Events](https://muzak.dev/docs/0.3.0/realtime/server-sent-events): 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.

## Security

- [Safe Defaults](https://muzak.dev/docs/0.3.0/security/safe-defaults): Every default in Muzak is the conservative one. This is the full list, what each one stops, and how to relax it deliberately.
- [Authentication](https://muzak.dev/docs/0.3.0/security/authentication): 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.
- [Authorization](https://muzak.dev/docs/0.3.0/security/authorization): 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.
- [CORS](https://muzak.dev/docs/0.3.0/security/cors): 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.
- [TLS](https://muzak.dev/docs/0.3.0/security/tls): Serve HTTPS from a certificate pair or a tls.Config, and know what changes in the rest of the application once you do.
- [Allowed Hosts and HTTPS](https://muzak.dev/docs/0.3.0/security/hosts-and-https): Refuse requests for hosts the application does not serve, and redirect plain HTTP to https without ever naming a host a client chose.
- [Sessions](https://muzak.dev/docs/0.3.0/security/sessions): 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.
- [Cross-Origin Requests](https://muzak.dev/docs/0.3.0/security/cross-origin-requests): 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.

## Deployment

- [Server Configuration](https://muzak.dev/docs/0.3.0/deployment/server-configuration): The listener, its timeouts, the run methods, and a shutdown that drains requests before it releases the resources they were using.
- [Behind a Proxy](https://muzak.dev/docs/0.3.0/deployment/behind-a-proxy): 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.
- [Running on Cloud Run](https://muzak.dev/docs/0.3.0/deployment/cloud-run): 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.
- [Health Checks](https://muzak.dev/docs/0.3.0/deployment/health-checks): 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.