Pedestal: Clojure Server-Side Libraries for Async HTTP, SSE and WebSockets

What Pedestal solves, and who it is written for

Pedestal is a set of libraries written in Clojure, and the README states the goal plainly: to bring the language and its principles (Simplicity, Power, and Focus) to server-side development. That framing matters, because the project is not a thin wrapper over a Java HTTP server. It is an opinionated way of structuring a Clojure service.

The intended audience is a Clojure team building an HTTP service that has to do more than answer synchronous requests. The README lists asynchronous request handling, Server Sent Events and WebSockets as first-class citizens, and integrated logging, metrics and tracing. Those are the features that pull a project past a plain handler function. If your service streams events to a browser, keeps long-lived socket connections, or needs request handling that does not tie up a thread, Pedestal addresses that directly instead of leaving it to add-on libraries.

The repository layout backs this up. Top-level directories include interceptor/, route/, service/, servlet/, jetty/, http-kit/, telemetry/, log/ and error/, alongside common/ and embedded/. Each is a separate concern, which is consistent with the README's claim that Pedestal is batteries included but designed for extensibility. The samples/ directory holds around two dozen example projects, from hello-world and helloworld-metrics through server-sent-events, jetty-web-sockets, tracing-interceptor and ring-middleware.

The interceptor chain is the core mechanism

The central abstraction is the interceptor, and the repository gives it a top-level directory of its own. An interceptor is a unit of request processing with a defined place in a chain, rather than a function that wraps another function. That distinction is the whole design. Ring middleware composes by nesting, so the order of wrapping is the order of execution and the whole request passes through each layer. An interceptor chain makes the sequence explicit and gives each step a before and after position relative to the handler.

This is what makes asynchronous handling tractable. When a request can be answered later, the framework needs to know which steps have already run and which still owe work. A named chain with defined stages answers that question; nested closures do not.

The surrounding directories show the rest of the data flow. route/ handles routing, service/ assembles the service, servlet/ sits between the service and the Servlet API, and jetty/ and http-kit/ provide the actual server integrations. The README names Jetty 12 and Http-Kit as the default integrations, so the server is a choice rather than a hardcoded assumption. telemetry/, log/ and error/ cover the observability and failure paths the README advertises.

One consequence worth stating: the interceptor model is a concept you have to learn. A developer arriving from plain Ring will not be able to drop an existing handler into a Pedestal service and expect the same shape.

Installing Pedestal and standing up a first server

Pedestal is published on Clojars under the io.pedestal group. The README carries a Clojars badge for io.pedestal/pedestal.service, which is the artifact to look for when adding a dependency. The project requires Clojure 1.11 or later, works with Servlet API 5.0, and needs Java 17 or up.

The samples/ directory is the practical starting point. There is a samples/hello-world/ project, and the README points to a hello-world guide in the documentation at pedestal.io. The README does not reproduce the dependency coordinates or the server code inline, so the honest move is to follow that guide rather than invent a snippet here. What the README does give is the shape of the thing: a basic Pedestal server can be stood up in a few lines of code, and the guides show how.

To run the project's own tests, the README gives one command, executed from the tests subdirectory:

clj -X:test

That runs the test suite through the Clojure CLI. If you are evaluating Pedestal before adopting it, this is the cheapest way to see the libraries build and pass on your machine, and it exercises the same deps.edn-driven setup the repository uses.

For a real first use, the samples worth reading in order are hello-world, then json-api, then server-sent-events. The first shows the minimal service, the second shows content negotiation and response shaping, and the third shows the streaming case that motivates the whole design. The README does not document a single canonical scaffold command, so expect to copy from samples/ rather than generate a project.

Where Pedestal is the wrong choice

Pedestal asks you to accept its abstractions before you get anything back. If your service is a handful of synchronous endpoints returning JSON, the interceptor chain, the routing layer and the service assembly are overhead you will pay for on every request and every code review. A plain Ring handler on top of a small server does that job with fewer moving parts.

The version situation is the second constraint. The releases listed for this repository are 0.8.2-beta-11, 0.8.2-beta-10 and 0.8.2-beta-9, dated 2026-09-04, 2026-07-02 and 2026-06-15. The most recent line is a beta, and the README's own documentation link points at the 0.8 documentation set. A team that requires a stable, non-beta release should check what the 0.8.1 or earlier line offers before pinning 0.8.2, and should read CHANGELOG.md rather than assume the betas are drop-in.

Platform requirements are the third. Clojure 1.11 or later, Servlet API 5.0, and Java 17 or up. A service still on Java 11, or on an older Servlet container, is out of scope until it moves. That is not a defect, but it is a hard boundary and it is stated in the README.

Finally, the README does not document rollback or downgrade procedures, and the license section does not spell out what happens to a derivative work in detail. Treat both as things to resolve from the repository's own files rather than from the README alone.

Pedestal against plain Ring and Compojure

The natural alternative for a Clojure HTTP service is Ring with a routing library such as Compojure. The difference is not feature count, it is the execution model. Ring gives you a function from request map to response map, and middleware composes by wrapping. Compojure adds route matching on top of that. Both are small, well understood, and let you reason about a request as a single pass through nested functions.

Pedestal replaces that with a named chain of interceptors and an explicit service. The payoff appears when a request does not complete in one pass: async handling, Server Sent Events, and WebSockets. The README lists all three as first-class, and the samples directory contains server-sent-events, jetty-web-sockets and http2 examples to match. With Ring you can reach the same territory, but you assemble it from separate pieces and you own the coordination.

The cost is conceptual weight and a smaller pool of people who already know the model. The benefit is that streaming and long-lived connections are part of the framework's vocabulary rather than something you graft on. If your service never streams and never holds a socket open, that trade does not pay off. If it does both, Pedestal's model is the reason to pick it.

Maintenance, upgrades and the licence

The repository is not archived, and the last push was on 2026-09-04. The most recent release, 0.8.2-beta-11, carries the same date, so releases and commits are moving together. The cadence visible in the release list is roughly every two to three months across the three betas shown, which suggests continued work on the 0.8.2 line rather than a frozen branch.

The upgrade cost is the beta status. Anyone pinning 0.8.2 is tracking a pre-release line, and the README's documentation link targets the 0.8 documentation, so the docs and the code are versioned together. Read CHANGELOG.md before moving between betas; the repository keeps one at the top level. The VERSION.txt and RELEASING.md files indicate the project manages its own release process rather than relying on an external tool.

On licensing: the README states the use and distribution terms are covered by the Eclipse Public License 1.0, with the full text in epl-v10.html at the root of the distribution. Copyright is attributed to Relevance, Inc. (2013), Cognitect, Inc. (2014-2022) and Nubank NA (2023-2026). The README also states that using the software in any fashion means agreeing to be bound by the licence, and that the notice must not be removed. EPL 1.0 is a file-level copyleft licence, which is a different obligation profile from a permissive licence, but how it applies to your distribution is a question for your own counsel, not for this article.

Support runs through the #pedestal channel on Clojurians Slack, per the README, not through a paid tier.

Editorial conclusion

Adopt Pedestal if you are writing a Clojure service that needs async handling, Server Sent Events or WebSockets, and you are willing to work inside its interceptor chain rather than plain Ring middleware. Do not adopt it if you want a thin Ring handler with no framework concepts, or if you are not on Clojure 1.11 and Java 17 or later. Before committing, read the hello-world guide at pedestal.io, check which of the jetty, http-kit and servlet modules your deployment needs, and confirm that the 0.8.2 line is still in beta at the version you pin, since the most recent releases listed are 0.8.2-beta-11 and earlier betas.

Frequently asked questions

Official sources

1. Issues
2. pedestal/pedestal on GitHub
3. Project website
4. README
5. Releases