Developing at the REPL

Exploring your application at the REPL is fundamental to Clojure development. In the context of Pedestal applications, we often want to interrogate the routing system and invoke interceptors (or handlers) in isolation. These explorations often form the basis for more robust automated tests, which will be covered in the unit-testing.adoc guide.

After reading this guide, you will be able to perform the following tasks at the REPL:

This guide assumes you have a working REPL in your Pedestal application. If you generated your application using the {repo_root}/tree/master/service-template[pedestal-service Leiningen template], this might be as simple as running lein repl at the command line. Perhaps your editor or IDE provides a facility for launching a REPL for your project. A great resource for understanding and configuring your REPL environment can be found at Lambda Island’s Ultimate Guide to Clojure REPLs.

include::partial$getting-help.adoc

In this guide, we will develop a few simple utility functions that simplify interacting with your Pedestal application from the REPL. For the sake of having a consistent baseline setup, we’ll use a clean project for this guide. Generate a new Pedestal service using the following command:

The default project template creates two files: server.clj and service.clj. We’re now ready to begin exploring the Pedestal application. Ladies and gentlemen, start your REPLs!

The first thing we’ll want to do from the REPL is to control the HTTP server. By default, your REPL should start in the pedrepl.server namespace. The Leiningen template generates a useful function named run-dev which will configure and start the HTTP server in development mode, preventing the HTTP server thread from being joined and locking up your REPL.

In development mode, routes are reloaded when the service.clj is re-required.

At the REPL, invoke the run-dev function to start the server:

Now fire up a browser and navigate to http://localhost:8080 to see the default, "Hello, World!" message.

Within service.clj, update the home-page handler to respond with "Hello Pedestal User". Re-require/reload the service.clj, and when you reload http://localhost:8080 you’ll see the change immediately.

In dev-mode, you should never have to restart the server - changes are picked up as soon as they’re required/reloaded.

Should you ever need to stop the server, you can do so with the following invocation:

Now that we’re able to control the HTTP server, we’ll want some additional amenities. Next we’re going to add some route introspection utilities. Pedestal ships with all of the raw materials we need. Our job is simply to package these tools together into more convenient forms adapted to our specific needs.

Pedestal supports a few different route definition formats. Version 0.5.0 saw the advent of a new table format which is now the default generated by the pedestal-service Leiningen template. Let’s add a reference to the table format namespace from server.clj. Your namespace declaration should now look like this:

With that reference in place, we can add a new utility to print our application’s routes at the REPL:

Try this new function out at the REPL:

This simple output lists the HTTP method, relative path, and handler function for each one of our routes. This is a great start, but as our application grows we may want to find a route by name. Let’s add another utility to do just that:

Let’s test our new function:

This function returns a map describing the home page route in greater detail than print-routes. Besides the :path and :method keys, we’re given access to the list of :interceptors that will be invoked when this route is requested. It’s not uncommon for Pedestal services to have quite a few interceptors, so the raw output from named-route can get a little unwieldy. Let’s see if we can produce some friendlier output.

Interceptors are central to Pedestal applications. Not only do they provide the same pre- and post-processing of requests that Ring middleware does, but they also provide the main functionality behind every request. Everything in Pedestal is an interceptor, created by a single protocol - IntoInterceptor. When a route is compiled in Pedestal, it’s compiled with the full list of interceptors that run for that endpoint. It is often useful to see all interceptors that get run for a single endpoint. You can do that by looking through the route description or programmatically at the repl. Below is one way you might inspect and format that information.

Let’s use our new utility to print the ::service/home-page route information.

This call produces the following output:

Of course, this is a completely arbitrary representation of your route definition. Your own needs and aesthetic sensibilities should inform the structure of your application’s output.

It’s not even necessary to start a server to see responses of your Pedestal service.

Pedestal ships with a api:response-for[ns=io.pedestal.test] function that will return the response of an endpoint, exactly how it’s passed to the Servlet/Chain-Provider.

Let’s jump into the REPL:

You can also use the same response-for function to test against a live server. Assuming you still have a running server from above (e.g. (def serv (run-dev))), You can do the following:

One of Pedestal’s benefits is that its routing table is bidirectional. Not only does Pedestal use the route definition to recognize routes based on request data, but it can also generate URLs to known route handlers. Let’s take a closer look at both of these capabilities in turn.

In this guide we learned how to explore our Pedestal application from the REPL. Some of these explorations may serve as the basis for unit tests. Head over to the unit-testing.adoc guide to learn how to test the complete interceptor chain for a given route and much more.

Alternatively, you may want to learn to manage your applications stateful components (like the HTTP server) more effectively. Check out the guide on Integrating Pedestal with Component to learn how easy it can be to incorporate Stuart Sierra’s Reloaded workflow into your Pedestal development, and read Reloading at the REPL for a non-component take on how to make live changes without restarting.