Reloading at the REPL

Let’s start with yet another basic, "Hello World" application.

With that in place, evaluate (reset! server (start)); this will create the server and start it, storing the running system map back into the server atom.

You can now use your favorite HTTP client (such as HTTPIe) to access the /hello route:

So far, so good. You can also see that Pedestal’s default set of interceptors has added a number of security-related headers to the response.

Now we’re ready to make a change. Let’s change the response body to be Hello, Clojure World!. We can change the hello-handler function, reload the namespace, and:

That’s strange. It’s as if the code change wasn’t picked up. We can verify that the code change is, in fact, live by evaluating (hello-handler nil) at the REPL:

What’s happened here is that the value of the org.example.hello/hello-handler Var has changed; it now holds a new Clojure function, one that says "Hello, Clojure World!". However, the routes and start functions captured the value of hello-handler at the time they executed.

We could say ugh, fine and just adapt to a cycle where you reload your REPL code and then restart the server object, but that’s slow and error-prone. We want a fast feedback cycle where that is not necessary, and that goal is entirely achievable.

The first step is to stop the service by evaluating (swap! server http/stop).

Next, change the routes function:

Notice that backtick character before hello-handler. That’s Clojure’s syntax quote; like a single quote, it keeps hello-handler from being evaluated, but unlike single quote, the symbol is namespace qualified. It’s the equivalent of 'org.example.hello/hello-handler.

To understand what’s going on here, we must consider a key stage in Pedestal: route expansion. Route expansion is a step during service startup where the provided routes are converted from one of a number of specifications (such as the table format used here) into an executable format. Part of expansion is a rule that says that a handler that’s a symbol is replaced with the evaluation of that symbol. That’s when org.example.hello/hello-handler is converted from a symbol to function.

Notice that we also no longer have to specify a :route-name; with a handler symbol, a default route name is generated that’s a keyword version of the symbol.

Now, change the function to return "Hello, Programming World!", reload the namespace, and get the /hello URL again:

What gives? Where’s our reloading?

Because of the back-ticked symbol, the evaluation of hello-handler occurred later than in the original code, not inside the routes definition, but somewhere inside the call to api:create-server[] …​ but that evaluation and expansion still only happens once, and so there’s still a capture.

We need the route to always reflect the live version of the hello-handler function, and that means we have to avoid capture, not just of the hello-handler function, but of the entire route specification.

Fortunately, Pedestal supports this use case - a route is normally a data structure, but it can also be a zero-arguments function that returns an expanded route specification.

Stop the service and make these changes:

Reload and restart the server, and check that we are getting the original behavior:

Now, change the message to Hello, JVM World!, reload the namespace, then reload the URL:

Success! The route function is being evaluated on every incoming request.

Still, we’re not quite done. Let’s say we want to be less formal, and respond on the path /hi instead of /hello. We can change the routes:

But this still doesn’t live-reload as we’d expect:

There’s still one more capture: the anonymous function is capturing the value of the routes set. The anonymous function has a lifecycle that starts when the start function is executed, and the routes set’s value is captured at that point in time. In order for route changes to load, we have to ensure that the anonymous route function always returns the current value of routes.

Change the route back to /hello and modify the start function:

Stop and restart the server, and verify that /hello still works.

Now, update the route back to /hi, reload the namespace, and check:

Done! You can now add, remove, or otherwise change your routes, update interceptors, add constraints …​ wherever your development takes you, and those changes will be re-evaluated and re-loaded on each request.

It’s not very desirable to have to keep two separate start functions, one for production, and one for REPL oriented development …​ especially given how badly throughput will be affected if the local REPL version leaks through to production.

So to simplify things, the startup code can be changed to use the api:routes-from[ns=io.pedestal.http.route] macro:

routes-from is aware of the Pedestal execution mode. By default, routes-from operates in production mode, so (route/routes-from routes) evaluates to just routes - no deferred evaluation, no rebuild of the routing table on each request, which is just what we want in production.

However, in local development mode, (route/routes-from routes) expands (approximately) to #(expand-routes (deref (var routes))) …​ the same code we used above, to delay route evaluation.

Further, in local development mode, Pedestal will write a formatted routing table to the console at startup, and at any later time that the routing table changes:

This output is especially useful to know the correct route name to pass to api:url-for[ns=io.pedestal.http.route] (to generate application URLs included in responses) or api:response-for[ns=io.pedestal.test] (used in your unit tests).

Running code with a long-lived and stateful service creates its own challenges when coding live at the REPL; in this guide we’ve explained how capturing interferes with live reloading, and provided the necessary steps to keep your REPL flowing as you develop your application.

Just remember …​ you want to make sure your production application doesn’t use these reloading techniques if you want to meet your SLAs (service level agreements)!