# 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.1.1, 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.1.1.

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.1.1/llms-full.txt.

## Getting Started

- [Introduction](https://muzak.dev/docs/0.1.1/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.1.1/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.1.1/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.1.1/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, and what happens when the client sends something else.
- [Responses](https://muzak.dev/docs/0.1.1/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.1.1/getting-started/dependencies): Guards that validate a request, providers that hand a typed value to a handler, and singletons that publish a resource to the whole application.
- [Error Handling](https://muzak.dev/docs/0.1.1/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.1.1/getting-started/middleware): The chain that is already installed, the two you can add, how to write your own, and the one thing that fails quietly in Go.
- [Lifecycle](https://muzak.dev/docs/0.1.1/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.

## Fundamentals

- [Configuration](https://muzak.dev/docs/0.1.1/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.1.1/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.1.1/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.1.1/fundamentals/logging): Structured logging that is readable in development and parseable in production, with scopes, request identifiers and secrets redacted by key.
- [OpenAPI](https://muzak.dev/docs/0.1.1/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.
- [Testing](https://muzak.dev/docs/0.1.1/fundamentals/testing): Serve an application in-process over an in-memory network and exercise middleware, routing, binding, dependencies and error rendering together.

## Techniques

- [Headers](https://muzak.dev/docs/0.1.1/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.1.1/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.1.1/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.1.1/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.1.1/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.1.1/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.1.1/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.1.1/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.1.1/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.

## Real-time

- [WebSockets](https://muzak.dev/docs/0.1.1/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.1.1/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.1.1/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.1.1/security/authentication): Shared-secret guards, bearer tokens, sessions and per-user identity, resolved before the handler runs and compared in constant time.
- [Authorization](https://muzak.dev/docs/0.1.1/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.1.1/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.1.1/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.

## Deployment

- [Server Configuration](https://muzak.dev/docs/0.1.1/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.1.1/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.