example-web-service.md

Simple Web Service Example

This example demonstrates how to create a simple set of web services which both depend upon a hit counter service for generating content. When run, this code will attach two endpoints, /bert and /ernie which will generate a simple block of HTML that displays seperate hit counters for each service.

All code needed to execute this example is located in examples/ring_app. The Clojure code is contained in the example_services.clj file.

And now, a few quick housekeeping items before we get to the code...

Launching trapperkeeper and running the app

To start up trapperkeeper and launch the sample application, use the following lein command while in the trapperkeeper-webserver-jetty7 home directory:

lein trampoline run --config examples/ring_app/config.ini \
                    --bootstrap-config examples/ring_app/bootstrap.cfg

Once trapperkeeper is running, point your browser to either http://localhost:8080/ernie or http://localhost:8080/bert to see the ring handlers and hit counter in action.

As you can see from the command line there are two configuration files needed to launch trapperkeeper.

The bootstrap.cfg file

The bootstrap config file contains a list of services that trapperkeeper will load up and make available. They are listed as fully-qualified Clojure namespaces and service names. For this example the bootstrap.cfg looks like this:

puppetlabs.trapperkeeper.services.webserver.jetty7-service/jetty7-service
examples.ring-app.example-services/count-service
examples.ring-app.example-services/bert-service
examples.ring-app.example-services/ernie-service

This configuration indicates the jetty7 WebserverService is to be loaded, as well as the three new services defined in the example_services.clj file.

The config.ini configuration file

For the application configuration, a file called config.ini provides the most minimal configuration of the webserver-service, which is simply the port the service will be listening on and also a logging-config key which contains a path to a logback config file which defines the logging configuration.

[global]
# Points to a logback config file
logging-config = examples/ring_app/logback.xml

[webserver]
# Port to listen on for clear-text HTTP.
port = 8080

Debug mode

There is a debugging statement inside the count-service which displays the state of the counter when it is to be incremented. To turn on debugging logging pass in the --debug option on the command line, like so:

lein trampoline run --config examples/ring_app/config.ini \
                    --bootstrap-config examples/ring_app/bootstrap.cfg \
                    --debug

When run you will see debug output any time you hit the hit-counting endpoint. This is the equivalent of setting the logback root logger to DEBUG instead of INFO, and will override whatever log level the root logger is set to.

Defining the Services

And now, without further ado, let's look at some code!

Define the hit count service

First we will need to define the hit counter service, which will later be used by the web services to show users which visitor number they are. It is entirely expressed with this code:

(def ^{:private true} hit-count (atom {}))

(defn- inc-and-get
  "Increments the hit count for the provided endpoint and returns the new hit count."
  [endpoint]
  {:pre [(string? endpoint)]
   :post [(integer? %) (> % 0)]}

  (let [new-hit-counts (swap! hit-count #(assoc % endpoint (cond (contains? % endpoint)
                                                             (inc (% endpoint)) :else 1)))]

    (log/debug "Incrementing hit count for" endpoint "from"
               (dec (new-hit-counts endpoint)) "to" (new-hit-counts endpoint))

    (new-hit-counts endpoint)))

(defprotocol CountService
  (inc-and-get [this endpoint]))

(defservice count-service
  "This is a simple service which simply keeps a counter. It contains one function, inc-and-get, which
   increments the count and returns it."
  ;; Here we specify the service's protocol
  CountService
  ;; This vector declares the service's dependencies on other services and their functions,
  []
  ;; Implement the `init` function from the `Lifecycle` protocol to
  ;; initialize state:
  (init [this context]
    (assoc context :hit-counts (atom {})))
  ;; Implement the inc-and-get function.
  (inc-and-get [this endpoint]
    (inc-and-get* ((service-context this) :hit-counts) endpoint)))

The defservice macro is used to define a trapperkeeper service and it is located in the puppetlabs._trapperkeeper_.core namespace.

For more info on how the defservice macro works, see the defservice section of the trapperkeeper docs

The inc-and-get function will keep a tally of hit counts for a provided endpoint. It is later exported with the last form in the service definition which is a map of this service's function names to the actual functions which do all the work.

Define the bert service

The bert-service is a more interesting service which utilizes the webserver service to create HTTP responses to requests made to specific endpoints, and is defined here:

(defn- success-response
  "Return a ring response map containing a HTTP response code of 200 (OK) and HTML which displays the hitcount on this
   endpoint as well as all the data provided by Ring."
  [hit-count req]
  {:status 200
   :body (str "<h1>Hello from http://" (:server-name req) ":" (:server-port req) (:uri req) "</h1>"
              (if (:debug? req) "<h3>DEBUGGING ENABLED!</h3>" "")
              "<p>You are visitor number " hit-count ".</p>"
              "<pre>" (pprint-to-string req) "</pre>")})

(defn- ring-handler
  "Executes the inc-and-get command and passes it into success-reponse which generates a ring response."
  [inc-and-get endpoint req]
  (success-response (inc-and-get endpoint) req))

(defservice bert-service
  "This is the bert web service. The Clojure web application library, Ring, is used to create simple
   responses to an endpoint. It depends on the count-service above to use as a primitive hit counter.
   See https://github.com/ring-clojure/ring for documentation on Ring."

  ;; This service needs functionality from the webserver service, and the count service.
  [[:WebserverService add-ring-handler]
   [:CountService inc-and-get]]

  ;; Implement the `init` lifecycle function to register the ring handler
  (init [this context]
    (let [endpoint "/bert"]
      (add-ring-handler (partial ring-handler inc-and-get endpoint) endpoint))
    context)

  (stop [this context]
    (log/info "Bert service shutting down")
    context))

The general structure of this service is similar to the hit count service.

Since this service requires the use of functionality from other services, the dependency list contains two dependent services and the functions that are required from each. The element containing [:WebserverService add-ring-handler] states that the add-ring-handler function from the :WebserverService is needed by this service. And, of course, we also need to pull in the inc-and-get function from the hit count service previously defined. This is accomplished by the [:CountService inc-and-get] dependency list item.

Ring handlers

In the body of the service definition is a call to the add-ring-handler function. This function takes two parameters, the first being a ring handler which is, essentially, a function which takes a request data map as a single parameter and returns a map containing different parts of an HTTP response. The second parameter to add-ring-handler is the base endpoint that the handler is attached to.

In this example, a partial function is created from the ring-handler function which is passed an endpoint to operate on and the inc-and-get function from the hit count service which generates the hit count.

See https://github.com/ring-clojure/ring for further documentation on the Ring API.

Define the ernie service

The ernie service is very similar to the bert service, but also leverages another bit of built-in trapperkeeper functionality: the :ConfigService.

This service can be specified as a dependency, and provides functions that can be used to retrieve user-specified configuration values. In this case, we've added an [example] section to the config.ini file, and specified a setting ernie-url-prefix that can be used to control the URL prefix where the ernie-service will be available in the web server.

The config service also provides a top-level config setting named :debug, which is a boolean that reflects whether or not the user launched trapperkeeper in debug mode. In the ernie-service we use a simple ring middleware function to inject that value into the ring request map, so that it can be checked by the ring handler.

(defn debug-middleware
  "Ring middleware to add the :debug configuration value to the request map."
  [app debug?]
  (fn [req]
    (app (assoc req :debug? debug?))))

(defservice ernie-service
  "This is the ernie service which operates on the /ernie endpoint. It is essentially identical to the bert service."
  [[:WebserverService add-ring-handler]
   [:CountService inc-and-get]
   [:ConfigService get-in-config]]

  (init [this context]
    (let [endpoint (get-in-config [:example :ernie-url-prefix])
          ring-handler (-> (partial ring-handler inc-and-get endpoint)
                           (debug-middleware (get-in-config [:debug])))]
      (add-ring-handler ring-handler endpoint))
    context)

  (stop [this context]
    (log/info "Ernie service shutting down")
    context))

This means that you can change the URL of the ernie-service simply by editing the configuration file.

Logging

At startup, trapperkeeper will configure the logging system based on a logback configuration file. This means that your services can all just dive run it and call the logging functions available in clojure.tools.logging without worrying about configuration.

The logback.xml file

A minimal logback.xml file is provided in this example to demonstrate how to configure logging in trapperkeeper.

<configuration scan="true">
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d %-5p [%c{2}] %m%n</pattern>
        </encoder>
    </appender>

    <root level="info">
        <appender-ref ref="STDOUT" />
    </root>
</configuration>

See http://logback.qos.ch/manual/configuration.html for documentation on how to configure logback.