ring

Ring

Ring is a Clojure HTTP server abstraction. It defines a small, composable model built around plain Clojure maps and functions. A Ring application is a Clojure function that takes a request map and returns a response map (or calls async callbacks). Middleware wraps handlers with additional behavior. Adapters bridge Ring to real HTTP servers.

Quick Decision: What do you need?

Task	Go to
Understand request/response maps, the Ring spec, handlers, middleware structure, async handlers, StreamableResponseBody	request-response.md
Parse query params, form params, multipart/file uploads, keyword params, nested params	middleware-params.md
Sessions, cookies, flash messages, session stores (memory, cookie)	middleware-session.md
Serve static files/resources, set Content-Type, Content-Length, HEAD, 304 Not Modified	middleware-serving.md
Start a Jetty server, configure SSL, threading, async mode, Unix sockets	jetty-adapter.md
WebSocket upgrade responses, Listener/Socket protocols, sending/receiving messages, map-based listeners	websockets.md
ring.util.response, ring.util.request, ring.util.async, codec, MIME types	util.md
Development tools: wrap-lint, wrap-reload, wrap-stacktrace, request dump	ring-devel.md
Common mistakes: middleware ordering, lazy bodies, async pitfalls, session key management	anti-patterns.md

Core Mental Model

• A handler is (fn [request] response) — or (fn [request respond raise] ...) for async.
• A middleware is (fn [handler] new-handler) — it wraps a handler with extra behavior.
• An adapter bridges a real HTTP server (Jetty, etc.) to Ring handlers.
• Request and response are plain Clojure maps. The spec defines their required and optional keys.
• Middleware composes with ->: (-> handler wrap-params wrap-session) applies outermost-last (i.e. wrap-session sees the request first).
• WebSocket upgrade is signaled by returning #:ring.websocket{:listener ...} from a handler instead of a normal response map.

Dependency Quick Reference

;; ring-core — request/response maps, middleware, util
[ring/ring-core "1.13.0"]

;; ring-jetty-adapter — embedded Jetty server
[ring/ring-jetty-adapter "1.13.0"]

;; ring-core-protocols — StreamableResponseBody protocol only
[ring/ring-core-protocols "1.13.0"]

;; ring-websocket-protocols — Listener/Socket protocols only
[ring/ring-websocket-protocols "1.13.0"]

;; ring-devel — lint, reload, stacktrace (development only)
[ring/ring-devel "1.13.0"]

;; ring-servlet / ring-jakarta-servlet — servlet bridge utilities
[ring/ring-servlet "1.13.0"]
[ring/ring-jakarta-servlet "1.13.0"]