$ show haskell-servant/servant
Servant is a Haskell library family for defining type-safe web APIs at the type level using DataKinds, TypeOperators, and type families. The core package (`servant`) provides combinators like `:>`, `:<|>`, `Capture`, `QueryParam`, `ReqBody`, and `Verb` to describe API structure. From these type-level descriptions, the ecosystem automatically derives server implementations (`servant-server`), client functions (`servant-client`, `servant-http-streams`), documentation (`servant-docs`), OpenAPI/Swagger specs (`servant-openapi3`, `servant-swagger`), and property-based tests (`servant-quickcheck`). The architecture is modular: each sub-package interprets the same API type via typeclasses (`HasServer`, `HasClient`, `HasDocs`, `HasSwagger`, `HasOpenApi`), enabling a single source of truth for the API contract. The server package provides a WAI `Application` via `serve` and `serveWithContext`, supporting custom monads, authentication (JWT, cookies, basic auth via `servant-auth`), streaming (conduit, pipes, machines), and error handling with configurable formatters. The client package generates type-safe query functions that run in a `ClientM` monad over HTTP. The ecosystem also includes foreign language bindings (`servant-foreign`), generic record-based APIs (`NamedRoutes`), and a rich set of cookbook examples covering real-world patterns like pagination, file upload, Prometheus metrics, and OpenID Connect. Key external dependencies include `warp` (server), `http-client`/`http-streams` (client), `aeson` (JSON), `jose` (JWT), `swagger2`/`openapi3` (spec generation), and `QuickCheck` (testing). The codebase is heavily tested with CI across multiple GHC versions (9.2–9.14) and uses Nix for reproducible development environments. While the type-level machinery can produce cryptic errors, the library is production-grade and widely used in the Haskell ecosystem.
The LLM identified 4 files worth highlighting for reuse:
A CPS-based streaming source type (`SourceT`) that provides a composable, effectful stream abstraction. It supports `StepT` (Stop, Error, Skip, Yield, Effect) and is used by servant's streaming endpoints and interop packages (conduit, pipes, machines). This module is self-contained and can be extracted as a standalone streaming library, demonstrating advanced monadic and continuation-passing design.
Implements an open union type (`Union`) for representing multiple possible response types in a type-safe manner. Used by `UVerb` and `MultiVerb` combinators to allow endpoints to return different status codes and content types. The module uses type-level lists and `sop-core` to provide safe injection and projection, and is reusable in any Haskell project needing extensible sum types.
Provides combinators (`MultiVerb`, `WithHeaders`, `AsUnion`) for defining endpoints that can return multiple response types with different HTTP status codes and headers. It leverages the `Union` type and type-level lists to encode the response alternatives, and includes generic derivation (`GenericAsUnion`) for ergonomic use. This module is a sophisticated example of type-level programming for API design.
Defines a set of composable predicates (e.g., `not500`, `onlyJsonObjects`, `getHeadersAreValid`) for property-based testing of entire servant APIs. Each predicate is a function that checks a property of the server's responses. The module is self-contained and demonstrates a clean pattern for building reusable test assertions that can be combined with `serverSatisfies` and `serversEqual`.