Ring Clojure Documentation

Ring provides several specialized libraries depending on your needs:

• ring/ring: A meta-package containing all relevant dependencies.
• ring/ring-core: Core functions and middleware for Ring handlers, requests, and responses.
• org.ring-clojure/ring-core-protocols: Protocols necessary for building Ring responses.
• org.ring-clojure/ring-websocket-protocols: Protocols necessary for WebSockets.
• ring/ring-devel: Functions for developing and debugging Ring applications.
• ring/ring-servlet: Construct legacy Java Servlets (≤ 4.0) from Ring handlers.
• org.ring-clojure/ring-jakarta-servlet: Construct Jakarta Servlets (≥ 5.0) from Ring handlers.
• ring/ring-jetty-adapter: An adapter that uses an embedded Jetty web server.

An asynchronous handler takes three arguments: a request map, a respond callback function (which takes a response map), and a raise callback function (which takes an exception). The return value is ignored.

A single function can support both synchronous and asynchronous arities.

;; Asynchronous arity
(fn [request respond raise]
  (respond response))

(fn [request respond raise]
  (raise exception))

;; Dual-purpose arity
(fn
  ([request]
    response)
  ([request respond raise]
    (respond response)))

A synchronous Ring handler is a Clojure function that takes a single argument, a request map, and returns a response map.

(fn [request] response)

If an adapter supports both synchronous and asynchronous handlers, use the :async? option to specify the mode.

(run-adapter handler {:async? true})

To promote an HTTP request to a websocket, a handler can return a websocket response map instead of a standard HTTP response map. This can be done in both synchronous and asynchronous handlers.

;; Synchronous
(fn [request]
  #:ring.websocket{:listener websocket-listener})

;; Asynchronous
(fn [request respond raise]
  (respond #:ring.websocket{:listener websocket-listener}))

Adapters are side-effectful functions that start an HTTP server. They take a handler and a map of options. The adapter parses incoming HTTP requests into request maps and passes them to the handler, then uses the returned response map to send an HTTP response to the client.

(run-adapter handler options)

A websocket listener handles lifecycle and message events. It must implement the following methods:

• on-open [listener socket]: Called when the websocket is successfully opened.
• on-message [listener socket message]: Called when a text or binary message is received. message is a java.lang.CharSequence or java.nio.ByteBuffer.
• on-pong [listener socket data]: Called when a pong frame is received.
• on-error [listener socket throwable]: Called when an error occurs.
• on-close [listener socket code reason]: Called when the websocket is closed. Guaranteed to be called if on-open was called.

A socket object represents the active connection and provides methods to interact with the client:

• -open? [socket]: Returns truthy if the socket is connected.
• -send [socket message]: Sends a text (CharSequence) or binary (ByteBuffer) message.
• -ping [socket data]: Sends a ping frame.
• -pong [socket data]: Sends an unsolicited pong frame.
• -close [socket code reason]: Closes the connection with a code and reason.