Chapter 6. Introduction to Pedestal

"A conceptual framework is a 'frame that works' to put those concepts into practice."

- Paul Hughes

Microservices are implemented using a particular technology stack, which serves a single-bounded context and provides services around it. The services exposed for the external world must be scalable and support direct messaging as well as asynchronous requests. Pedestal (http://pedestal.io/) is one such Clojure framework that fits in well to create reliable and scalable services for microservice-based applications. It also fits in well with the Clojure stack of the Helping Hands application. In this chapter, you will:

• Learn about the basic concepts of Pedestal
• Learn how to define Pedestal routes and interceptors
• Learn how to handle errors with Pedestal interceptors
• Learn how to publish operational metrics with Pedestal
• Learn how to use Server-sent Events and Web Sockets with Pedestal

Pedestal concepts

Pedestal is an API-first Clojure framework that provides a set of libraries to build reliable and highly concurrent services that are dynamic in nature. It is an extensible framework that is data-driven and implemented using protocols (https://clojure.org/reference/protocols) to reduce the coupling between its components. It favors data over functions and functions over macros. It allows for the creation of data-driven routes and handlers that can apply a different behavior at runtime based on incoming requests. This makes it possible to create highly flexible and dynamic services that are well suited for microservice-based applications. It also supports the building of scalable asynchronous services using server-sent events (SSE) and WebSockets:

The Pedestal architecture is based on two main concepts, Interceptors and Context Map, and two secondary concepts, Chain Providers and Network Connectors. All the core logic of the Pedestal framework has been implemented as Interceptors...

Creating a Pedestal service

Pedestal provides a Leiningen (https://leiningen.org/) template named pedestal-service to create a new project with the required dependencies and directory layout for a Pedestal service. To create a new project using the template, use the lein command with the template name and a project name as shown here:

# Create a new project 'pedestal-play' with template 'pedestal-service'
% lein new pedestal-service pedestal-play
Retrieving pedestal-service/lein-template/0.5.3/lein-template-0.5.3.pom from clojars
Retrieving pedestal-service/lein-template/0.5.3/lein-template-0.5.3.jar from clojars
Generating a pedestal-service application called pedestal-play.

The lein command will create a new directory with the specified project name and add all the required dependencies to the project.clj file. It will also initialize the server.clj and service.clj files with the code template for a sample Pedestal service. The created project directory tree should look like the one shown...

Using server-sent events (SSE) 

Server-sent events (SSE) (https://www.w3.org/TR/eventsource/) is a standard that enables efficient server-to-client streaming using a two-part implementation. The first part is the EventSource API that is implemented at the client side to initiate the SSE connection with the server, and the second part is the push protocol that defines the event stream data format that is used for the server-to-client communication.

The EventSource API of SSE is defined as a part of the HTML5 standard by W3C (https://en.wikipedia.org/wiki/World_Wide_Web_Consortium) and is now supported by all the modern web browsers:

SSEs are primarily used to push real-time notifications, updates, and continuous data streams from server to client once an initial connection has been established by the client. Generally, the notifications and updates are pulled by the client by sending a request to the APIs or polling (https://en.wikipedia.org/wiki/Polling_(computer_science)) the server for updates...

Using WebSockets

WebSockets is a communications protocol (https://en.wikipedia.org/wiki/Communication_protocol) that provides full-duplex (https://en.wikipedia.org/wiki/Duplex_(telecommunications)#FULL-DUPLEX) communication channels over a single TCP connection between client and server. It allows clients to send messages to the server and receive server events over the same TCP connection without polling. Compared to Server-Sent Events (SSE) (https://www.w3.org/TR/eventsource/), WebSockets support full-duplex communication between client and server instead of a one-way push. Also, SSEs are implemented over HTTP, which is an entirely different TCP protocol compared to WebSocket. Although both protocols are different, they both depend on the TCP layer. 

Note

RFC 6455 (https://tools.ietf.org/html/rfc6455) states that WebSocket is designed to work over HTTP ports 80 and 443 as well as to support HTTP proxies and intermediaries, thus making it compatible with the HTTP protocol. To achieve compatibility...

Summary

In this chapter, we learned about the concepts of the Pedestal framework and how to use them to create APIs. We also learned how to log useful information for debugging and monitoring the runtime state of the application using JMX metrics. We also looked at various web server plugins that can be used with Pedestal. Finally, we looked at how Pedestal can be used for SSEs and WebSockets for client-server interaction.

In the next chapter, we will take a look at a Datomic database that will be used for persistence by the microservices of the Helping Hands application. Datomic is written in Clojure and fits in well with the Helping Hands application, which requires transactions and temporal queries.