Asynchronous Web Applications with Async Servlet Support

Asynchronous request handling: A design where the request does not have to occupy a worker thread for the entire lifetime of slow I/O or long-lived connection work.

Async web handling is useful, but it is also widely misunderstood. It does not magically make code faster. It helps when the main problem is waiting: waiting on upstream APIs, waiting on sockets, waiting on streaming clients, or keeping many connections open at once. If the bottleneck is CPU work, async alone will not save you.

This matters in Clojure because the ecosystem gives you several different async shapes: servlet async support on container-based servers, event-loop servers such as http-kit and Aleph, and orchestration tools such as core.async. They are related, but they are not the same thing.

What Async Is Trying to Fix

A simple synchronous handler is easy to reason about, but it ties a worker thread to the whole request.

That becomes expensive when the handler spends most of its time waiting on:

• upstream HTTP services
• databases over slow networks
• queue acknowledgements
• websocket or streaming connections
• large fan-out workflows

If the server has to keep one thread parked per slow request, throughput falls and queueing rises.

Servlet Async Support Is One Model, Not the Whole Story

In a servlet container such as Jetty or Tomcat, async support means the request can be suspended while work continues elsewhere, then resumed when the response is ready. That is different from plain blocking servlet handling, where the container thread remains occupied for the whole request.

In the broader Clojure ecosystem, you will also see:

• Ring async handlers with respond and raise callbacks
• http-kit channel-oriented server APIs
• Aleph handlers that return deferred or stream-based responses
• core.async used as an orchestration tool inside a request workflow

Those models solve overlapping problems, but they do not make the same trade-offs.

The practical question is less “is this async?” and more “which execution context is doing the waiting, and what else is competing for it?”

Compare the Main Runtime Shapes Clearly

It helps to separate three common models:

• classic blocking Ring handler: simplest control flow, one worker thread stays busy for the full request
• servlet async or callback-style Ring handler: request thread can be released while later work completes elsewhere
• event-loop or deferred model: long-lived I/O and large connection counts are handled with tighter control over blocking and continuation

None of these models is universally best. A straightforward CRUD application behind a database often does well with ordinary blocking handlers and disciplined timeouts. A streaming or fan-out-heavy service often needs a more deliberate async shape.

Async Helps Only When You Avoid Blocking the Wrong Thread

This is the most important practical rule.

If a handler uses an async API but still performs blocking work on the request thread, the benefits shrink quickly. Moving slow I/O behind an async-looking wrapper does not change the cost if the same small pool is still blocked underneath.

 1(defn handler
 2  ([request]
 3   {:status 200
 4    :body "ok"})
 5  ([request respond raise]
 6   (future
 7     (try
 8       (let [result (fetch-upstream-data request)]
 9         (respond {:status 200
10                   :body result}))
11       (catch Exception ex
12         (raise ex))))))

The point of this shape is not the syntax. The point is that response delivery is decoupled from the original request thread.

Timeout Budgets and Cancellation Need Ownership

Async request handling makes it easier to hide the fact that no one owns timeout policy. That is dangerous.

For each slow dependency, decide:

• how long the caller is willing to wait
• which layer applies the timeout
• whether work should be cancelled, abandoned, or allowed to finish in the background
• what response shape the client receives on timeout

Without those rules, async systems often look healthy until load rises and abandoned work keeps piling up behind the scenes.

Where Async Really Pays Off

Async handling is strongest when you have:

• high connection concurrency
• long-lived streaming or websocket sessions
• upstream calls whose latency is significant relative to the actual business logic
• backpressure-sensitive pipelines

It is weaker when the request mostly performs CPU-heavy transformation or large in-memory computation. In those cases, explicit parallelism, background job design, or workload isolation may matter more than async request plumbing.

An easy mistake is treating every slow request as an async candidate. Some requests are slow because they are doing too much coordination, too many remote calls, or too much work before the first byte of the response. Fixing the request path often matters more than changing the server model.

core.async Is Not the Entire Web Stack

core.async is very useful for coordinating workflows, fan-in and fan-out, throttling, or backpressure-aware internal pipelines. It is less useful as a reason by itself to make every request path asynchronous.

One of the most common mistakes in Clojure web code is mixing up these layers:

• request lifecycle management
• internal asynchronous orchestration
• long-running background jobs

They interact, but they are not interchangeable.

core.async is at its best when it makes pressure visible:

• bounded channels instead of invisible queues
• explicit fan-in or fan-out stages
• handoff points where work can be throttled
• well-defined ownership of retries or timeouts

It is much weaker when used merely to make straightforward request logic look more sophisticated.

When a Background Job Is the Better Answer

Some workloads should leave the request lifecycle entirely:

• report generation
• large import or export jobs
• expensive reconciliation tasks
• fan-out notifications that do not need synchronous completion

In those cases, a better design is often:

1. validate and accept the request
2. enqueue durable work
3. return an acknowledgement or job handle
4. let another component own retries, progress, and completion

That is often cleaner than keeping an HTTP request open while pretending the work is still interactive.

Failure Modes to Watch

Blocking Inside go Blocks

go blocks are for parking channel operations, not arbitrary blocking I/O. If you place JDBC calls, remote HTTP calls, or file reads directly inside them, you can create confusing bottlenecks fast.

Ignoring Backpressure

Async systems often fail through overload rather than obvious crashes. A service that accepts work faster than downstream systems can consume it needs explicit queueing, shedding, timeouts, or concurrency limits.

Losing Error Ownership

Once the control flow becomes asynchronous, exception paths and logging boundaries become easier to duplicate or lose. Decide clearly which layer owns:

• timeout policy
• retries
• structured error responses
• logging

Practical Heuristics

Use async request handling when the system is mostly waiting, not when it is mostly computing. Keep blocking code out of the most constrained execution contexts. Make timeout budgets explicit, and be honest about when work should move into a background job instead of staying in the HTTP lifecycle.

Ready to Test Your Knowledge?