Using Pedestal With Component

After reading this guide you will be able to:

This guide is for users who are familiar with:

If you are new to Pedestal, you may want to go back to the hello-world.adoc guide.

If you’re new to Component, you should definitely check it out first.

partial$getting-help.adoc

In this guide, we’re going to step through creating a Pedestal service using Component. We’ll start off by creating a Pedestal component and wire it into a Component system map. We’ll then proceed to testing our service.

We’ll limit our component’s responsibilities to lifecycle management of the Pedestal HTTP server and provider. We’ll also expose the Pedestal service function (:io.pedestal.http/service-fn) upon component initialization as a convenience for testing.

Route or interceptor management will not be a component responsibility because the management of routes/interceptors is more of an application-specific concern. This may be familiar to you if you studied the way the Pedestal lein template lays out a Pedestal service - routes, interceptors and configuration is kept separate from service plumbing.

Finally, Pedestal service configuration, captured via a reference:service-map.adoc, will be a component dependency.

Now that we have a better idea of what we want our component to do, let’s go build it!

The first step is to create a project directory to contain the project sources, then create a deps.edn file, to capture the dependencies of our application.

Next, create a src directory, and a pedestal.clj file within it:

Let’s start implementing the component:

We’ll first implement the start method. It will contain our component initialization code.

If you’ve read some of the other guides, this implementation should look somewhat familiar. It’s a combination of the server-specific code used in the Hello World guide.

Now let’s implement the stop method. It will contain our component teardown code.

Now that we’ve got our component, we need a way to create and initialize an instance of it. Let’s tackle that next:

Our component constructor is just a wrapper around the map-specific record constructor created by defrecord. The defrecord macro creates a number of constructors and any of them could be used here.

Now that we’ve got our Pedestal component, let’s proceed to wiring it into a full-fledged system.

Create a routes.clj file. This file will contain our routes and handlers.

The respond-hello handler returns a simple static response. It may look familiar since it made its first appearance in the hello-world.adoc guide.

Finally, let’s implement the routes.

We’ll implement a single route, GET /greet, using Pedestal’s tabular routing syntax.

Now that we’ve got our Pedestal Component and routes, we can wire them up in a Component system map.

Create a system.clj file. This file will contain our system map and system constructor.

Let’s create a system initialization function named system.

The next step sets up the use of the component.repl library.

The set-init function stores a function that is used to start (or restart) the system. When start or reset is invoked, this function is passed the old system (or nil if there is no old system), and the function returns the new, but unstarted, system.

We’ll use clj tool to run our example. This should be familiar to you if you read through the Hello World guide.

From the project’s root directory, fire up a repl, and start the system.

You can now interact with the started service.

Let’s stop the system.

Our service is no longer available.

Let’s start it again!

It’s available again.

The Component design pattern ensures that the system is in the correct state no matter how many times we do this.

Let’s move on to testing our new service. Recall that our service contains one route, GET /greet. We’d like to verify that it returns the proper greeting. Before we can jump in and do that, though, we need to create some helpers. Some are just useful in general, while others are specific to our component implementation. Don’t worry, you won’t have to write too much code. Let’s do it!

First create a system_test.clj file in the src directory.

The system-test namespace requires all the dependencies necessary for testing.

Now let’s get to those helpers.

The url-for helper allows us to refer to routes by route-name. This is very useful, and is almost always adapted into new projects.

We need to expand the routes before invoking Pedestal’s api:url-for-routes[ns=io.pedestal.http.route] function.

The end result is that url-for is a function

The service-fn helper extracts the Pedestal ::http/service-fn from the started system. This helper allows us to keep focus on our tests rather than test initialization.

The with-system macro allows us to start/stop systems between test executions. We’ll model its design on macros like with-open and with-redefs so that its shape and usage is familiar.

Now that we’ve got our helpers implemented, let’s move on to our test. Create a test named greeting-test.

Now let’s restart the repl and run our tests.

That’s it! You now know the fundamentals necessary for implementing and testing your Component-based Pedestal services.

For reference, here are the complete contents of all the files.

At the beginning of this guide, we set out to create a Pedestal component, demonstrate its usage as well as how to test it without starting the http server. In the process, we also introduced a few general purpose test helpers.

Keep in mind that Pedestal services are highly configurable. It’s important to separate that configuration from the core component implementation. By limiting our component’s responsibilities to http server and Pedestal provider life cycle support, we can use it in a wide variety of Pedestal implementations.