Liking cljdoc? Tell your friends :D

Using Pedestal With Component

Component is a popular and non-intrusive library for organizing Clojure logic; it makes it easy to define components, as maps or Clojure records, and organize them, with intra-component dependencies, into a system map.

It’s not uncommon for Pedestal to be setup to operate as a component with a Component system.

What You Will Learn

After reading this guide you will be able to:

  • Create a Component-based service using Pedestal.

  • Test your service using Pedestal’s test helpers.

Guide Assumptions

This guide is for users who are familiar with:

  • Clojure

  • Pedestal

  • Clojure’s CLI tooling

  • Component

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.

Where We Are Going

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.

Before We Begin

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!

Initial Project

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.

deps.edn
link:example$component/deps.edn[role=include]

A Simple Pedestal Component

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

src/pedestal.clj
link:example$component/src/pedestal.clj[role=include]
1Create a pedestal namespace to house the Pedestal component.
2We need to require com.stuartsierra.component namespace to make the start and stop Lifecycle methods available.
3We need to require the io.pedestal.http namespace for server creation, starting and stopping.

Let’s start implementing the component:

link:example$component/src/pedestal.clj[role=include]
1Create a Pedestal record. This record will contain a service-map field, whose value will be supplied from another component, and a server field, managed by the Pedestal component, which is the server created from the service map.
2Include the component/Lifecycle protocol since we’ll be implementing its methods next.

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

link:example$component/src/pedestal.clj[role=include]
1If the service is already running (because you mistakenly invoked component/start-system on an already started system), let it keep running[1].
2Update the service field of the Pedestal component with the newly created, and optionally started, service.
3api:create-server[] returns a server map, which can be started via api:start[].
4In test mode, don’t start the server (the HTTP part), but we’ll still be able to feed requests into the interceptor pipeline.

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.adoc guide.

Before we go on, remember the test? function? It’s idiomatic in Pedestal services to include an :env key in the service map to communicate the environment of the service. This currently does not affect the behavior of the service, but it’s a useful marker. Our component will leverage this idiom and will not start/stop the server if the service is configured for the test environment. The implementation is included below.

link:example$component/src/pedestal.clj[role=include]

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

link:example$component/src/pedestal.clj[role=include]
1Like start, stop will be idempotent. If the component has been initialized and we’re not working with the test environment, we’ll pass the initialized service map to the stop function.
2Return the component with the service field set to nil. You can’t use dissoc here since it would return a plain map, breaking the component by converting it from a Pedestal record to a plain Clojure map.

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

link:example$component/src/pedestal.clj[role=include]

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.

It’s common to create a simple wrapper function, as shown here; quite often, components grow to need additional setup and initialization which can occur in this kind of creation function.

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

Wiring it up

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

src/routes.clj
link:example$component/src/routes.clj[role=include]

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.

link:example$component/src/routes.clj[role=include]

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

In this simple example, we use def, as the routes are entirely static. In many applications, some parts of the routes would be more dynamic, and routes would be a function with arguments.

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.

src/system.clj
link:example$component/src/system.clj[role=include]
1Require com.stuartsierra.component. It will be used to create the Component system map.
2Require component.repl for its system management functions. You would normally do this in a dev namespace.
3Require io.pedestal.http for the server start and stop functions.
4Require pedestal for the Pedestal component.
5Require routes for the application routes.

Let’s create a system initialization function named system.

link:example$component/src/system.clj[role=include]
1It will take the system environment as a single parameter. We’ll use keywords like :prod or :test for this.
2The system map will contain a :service-map key whose value is a Pedestal service map. This is still a component, even though it is purely data.
3The service map’s :env key will map to our environment keyword.
4We’ll configure the service map with our app-specific routes.
5The system map will contain a :pedestal key whose value is an uninitialized Pedestal component.
6The Pedestal component depends on the service map, so we will capture that dependency with component/using.

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

link:example$component/src/system.clj[role=include]

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.

Running It

We’ll use clj tool to run our example. This should be familiar to you if you read through the hello-world.adoc.

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

> clj
Clojure 1.11.1
user=> (require 'system)
nil
user=> (require '[com.stuartsierra.component.repl :as crepl])
nil
user=> (crepl/start)
[main] INFO org.eclipse.jetty.util.log - Logging initialized @43694ms to org.eclipse.jetty.util.log.Slf4jLog
[main] INFO org.eclipse.jetty.server.Server - jetty-9.4.52.v20230823; built: 2023-08-23T19:29:37.669Z; git: abdcda73818a1a2c705da276edb0bf6581e7997e; jvm 11.0.19+7-LTS
[main] INFO org.eclipse.jetty.server.handler.ContextHandler - Started o.e.j.s.ServletContextHandler@b1078f2{/,null,AVAILABLE}
[main] INFO org.eclipse.jetty.server.AbstractConnector - Started ServerConnector@70ab102c{HTTP/1.1, (http/1.1, h2c)}{localhost:8890}
[main] INFO org.eclipse.jetty.server.Server - Started @43830ms
:ok
user=>

You can now interact with the started service.

> curl -i http://localhost:8890/greet
HTTP/1.1 200 OK
Date: Tue, 17 Oct 2023 22:22:25 GMT
Strict-Transport-Security: max-age=31536000; includeSubdomains
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Content-Security-Policy: object-src 'none'; script-src 'unsafe-inline' 'unsafe-eval' 'strict-dynamic' https: http:;
Content-Type: text/plain
Transfer-Encoding: chunked

Hello, world!%
>

Let’s stop the system.

user=> (crepl/stop)
[main] INFO org.eclipse.jetty.server.AbstractConnector - Stopped ServerConnector@49b7eb3{HTTP/1.1,[http/1.1, h2c]}{localhost:8890}
[main] INFO org.eclipse.jetty.server.handler.ContextHandler - Stopped o.e.j.s.ServletContextHandler@17c4dcc6{/,null,UNAVAILABLE}
:ok

Our service is no longer available.

$ curl -i http://localhost:8890/greet
curl: (7) Failed to connect to localhost port 8890: Connection refused

Let’s start it again!

user=> (crepl/start)
[main] INFO org.eclipse.jetty.server.Server - jetty-9.4.52.v20230823; built: 2023-08-23T19:29:37.669Z; git: abdcda73818a1a2c705da276edb0bf6581e7997e; jvm 11.0.19+7-LTS
[main] INFO org.eclipse.jetty.server.handler.ContextHandler - Started o.e.j.s.ServletContextHandler@185d151b{/,null,AVAILABLE}
[main] INFO org.eclipse.jetty.server.AbstractConnector - Started ServerConnector@5dce3e{HTTP/1.1, (http/1.1, h2c)}{localhost:8890}
[main] INFO org.eclipse.jetty.server.Server - Started @150674ms
:ok
user=>

It’s available again.

> curl -i http://localhost:8890/greet
HTTP/1.1 200 OK
Date: Tue, 17 Oct 2023 22:23:22 GMT
Strict-Transport-Security: max-age=31536000; includeSubdomains
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Content-Security-Policy: object-src 'none'; script-src 'unsafe-inline' 'unsafe-eval' 'strict-dynamic' https: http:;
Content-Type: text/plain
Transfer-Encoding: chunked

Hello, world!%
>

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

Testing

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.

test/system_test.clj
link:example$component/test/system_test.clj[role=include]

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.

link:example$component/test/system_test.clj[role=include]

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.

link:example$component/test/system_test.clj[role=include]

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.

link:example$component/test/system_test.clj[role=include]

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

link:example$component/test/system_test.clj[role=include]
1sut (for system under test) will be bound to the started system by with-system. Notice how :test is passed as the system environment key; this ensures that the server does not start, and no HTTP port is bound.
2Use the service-fn helper to extract the Pedestal service function from the started system.
3Use Pedestal’s response-for test helper to make a test request to the :greet route. Use the url-for helper to refer to the route by name.
4We should get back a '200' status.
5We should get back a response body of 'Hello, world!'

Now let’s restart run the tests from the command line:

> clj -X:test

Running tests in #{"test"}

Testing system-test
[main] INFO io.pedestal.http - {:msg "GET /greet", :line 90}

Ran 1 tests containing 2 assertions.
0 failures, 0 errors.
>

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

The Whole Shebang

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

src/pedestal.clj
link:example$component/src/pedestal.clj[role=include]

link:example$component/src/pedestal.clj[role=include]

link:example$component/src/pedestal.clj[role=include]
link:example$component/src/pedestal.clj[role=include]
link:example$component/src/pedestal.clj[role=include]

link:example$component/src/pedestal.clj[role=include]
src/routes.clj
link:example$component/src/routes.clj[role=include]

link:example$component/src/routes.clj[role=include]
src/system.clj
link:example$component/src/system.clj[role=include]

link:example$component/src/system.clj[role=include]

link:example$component/src/system.clj[role=include]
test/system_test.clj
link:example$component/test/system_test.clj[role=include]

link:example$component/test/system_test.clj[role=include]

link:example$component/test/system_test.clj[role=include]

link:example$component/test/system_test.clj[role=include]

link:example$component/test/system_test.clj[role=include]
deps.edn
link:example$component/deps.edn[role=include]

The Path So Far

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.


1. This is useful for REPL-driven development, where mistakes happen. Without it, you may end up with a "zombie" Pedestal component and Jetty service keeping the port bound.

Can you improve this documentation?Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close