ring-middleware

This project was originally adapted from tailrecursion's ring-proxy middleware, and is meant for use with the Trapperkeeper Jetty10 Webservice. It also contains common ring middleware between Puppet projects and helpers to be used with the middleware.

Usage

To use ring-middleware, add this project as a dependency in your leiningen project file:

Schemas

• ResponseType -- one of the two supported response types (:json, :plain) returned by many middleware.
• RingRequest -- a map containing at least a :uri, optionally a valid certificate, and any number of keyword-Any pairs.
• RingResponse -- a map with at least :status, :headers, and :body keys.

Non-Middleware Helpers

json-response

(json-response status body)

Creates a basic ring response with :status of status and a :body of body serialized to json.

plain-response

(plain-response status body)

Creates a basic ring response with :status of status and a :body of body set to UTF-8 plain text.

throw-bad-request!

(throw-bad-request! "Error Message")

Throws a :bad-request type slingshot error with the supplied message. See wrap-bad-request for middleware designed to compliment this function, also bad-request? for a function to help implement your own error handling.

throw-service-unavailable!

(throw-service-unavailable! "Error Message")

Throws a :service-unavailable type slingshot error with the supplied message. See wrap-service-unavailable for middleware designed to compliment this function, also service-unavailable? for a function to help implement your own error handling.

throw-data-invalid!

(throw-data-invalid! "Error Message")

Throws a :data-invalid type slingshot error with the supplied message. See wrap-data-errors for middleware designed to compliment this function, also data-invalid? for a function to help implement your own error handling.

bad-request?

(try+ (handler request)
  (catch bad-request? e
    (...handle a bad request...)))

Determines if the supplied slingshot error map is for a bad request.

service-unavailable?

(try+ (handler request)
  (catch service-unavailable? e
    (...handle service unavailability...)))

Determines if the supplied slingshot error map is for the service being unavailable.

data-invalid?

(try+ (handler request)
  (catch data-invalid? e
    (...handle invalid data...)))

Determines if the supplied slingshot error map is for invalid data.

schema-error?

(try+ (handler request)
  (catch schema-error? e
    (...handle schema error...)))

Determines if the supplied slingshot error map is for a schema error.

Middleware

wrap-request-logging

(wrap-request-logging handler)

Logs the :request-method and :uri at debug level, the full request at trace. At the trace level, attempts to remove sensitive auth information and replace client certificate with the client's common name.

wrap-response-logging

(wrap-response-logging handler)

Logs the response at the trace log level.

wrap-proxy

(wrap-proxy handler proxied-path remote-uri-base & [http-opts])

This function returns a ring handler that, when given a URL with a certain prefix, proxies the request to a remote URL specified by the remote-uri-base argument.

The arguments are as follows:

• handler: A ring-handler that will be used if the provided url does not begin with the proxied-path prefix
• proxied-path: The URL prefix of all requests that are to be proxied. This can be either a string or a regular expression pattern. Note that, when this is a regular expression, the entire request URI will be appended to remote-uri-base when the URI is being rewritten, whereas if this argument is a string, the proxied-path will not be included.
• remote-uri-base: The base URL that you want to proxy requests with the proxied-path prefix to
• http-opts: An optional list of options for an http client. This is used by the handler returned by wrap-proxy when it makes a proxied request to a remote URI. For a list of available options, please see the options defined for clj-http-client.

For example, the following:

(wrap-proxy handler "/hello-world" "http://localhost:9000/hello")

would return a ring handler that proxies all requests with URL prefix "/hello-world" to http://localhost:9000/hello.

The following:

(wrap-proxy handler #"^/hello-world" "http://localhost:9000/hello")

would return a ring handler that proxies all requests with a URL path matching the regex #^/hello-world" to http://localhost:9000/hello/[url-path].

Proxy Redirect Support

By default, all proxy requests using wrap-proxy will follow any redirects, including on POST and PUT requests. To allow redirects but restrict their use on POST and PUT requests, set the :force-redirects option to false in the http-opts map. To disable redirect following on proxy requests, set the :follow-redirects option to false in the http-opts map. Please not that if proxy redirect following is disabled, you may have to disable it on the client making the proxy request as well if the location returned by the redirect is relative.

SSL Support

wrap-proxy supports SSL. To add SSL support, you can set SSL options in the http-opts map as you would in a request made with clj-http-client. Simply set the :ssl-cert, :ssl-key, and :ssl-ca-cert options in the http-opts map to be paths to your .pem files.

wrap-with-certificate-cn

This middleware adds a :ssl-client-cn key to the request map if a :ssl-client-cert is present. If no client certificate is present, the key's value is set to nil. This makes for easier certificate whitelisting (using the cert whitelisting function from pl/kitchensink)

wrap-add-cache-headers

A utility middleware with the following signature:

(wrap-add-cache-headers handler)

This middleware adds Cache-Control: no-store headers to GET and PUT requests if they are handled by the handler.

wrap-add-x-frame-options-deny

A utility middleware with the following signature:

(wrap-add-x-frame-options-deny handler)

This middleware adds X-Frame-Options: DENY headers to requests if they are handled by the handler.

wrap-add-x-content-nosniff

A utility middleware with the following signature:

(wrap-add-x-content-nosniff handler)

This middleware adds X-Content-Type-Options: nosniff headers to requests if they are handled by the handler.

wrap-add-csp

A utility middleware with the following signature:

(wrap-add-csp handler csp-val)

This middleware adds Content-Security-Policy headers to requests if they are handled by the handler. The value of the header will be equivalent to the second argument passed, csp-val.

wrap-params

A utility middleware with the following signature:

(wrap-params handler & [options])

This middleware parses url-encoded parameters from the query string and form body and adds the following keys to the request map:

• :query-params - a map of parameters from the query string
• :form-params - a map of parameters from the body
• :params - a map of all types of parameter

Accepts the following options:

• :encoding - encoding to use for url-decoding. If not specified, uses the request character encoding, or "UTF-8" if no request charater encoding is set.

wrap-data-errors

(wrap-data-errors handler)

Always returns a status code of 400 to the client and logs the error message at the "error" log level. Catches and processes any exceptions thrown via slingshot/throw+ with a :type of one of:

• :request-data-invalid
• :user-data-invalid
• :data-invalid
• :service-status-version-not-found

Returns a basic ring response map with the :body set to the JSON serialized representation of the exception thrown wrapped in a map and accessible by the "error" key.

Example return body:

{
  "error": {
    "type": "user-data-invalid",
    "message": "Error Message From Thrower"
  }
}

Returns valid ResponseTypes, eg:

(wrap-data-errors handler :plain)

wrap-bad-request

(wrap-bad-request handler)

Always returns a status code of 400 to the client and logs the error message at the "error" log level. Catches and processes any exceptions thrown via slingshot/throw+ with a :type of one of:

• :bad-request

Returns a basic ring response map with the :body set to the JSON serialized representation of the exception thrown wrapped in a map and accessible by the "error" key.

Example return body:

{
  "error": {
    "type": "bad-request",
    "message": "Error Message From Thrower"
  }
}

Returns valid ResponseTypes, eg:

(wrap-bad-request handler :plain)

wrap-schema-errors

(wrap-schema-errors handler)

Always returns a status code of 500 to the client and logs an message containing the schema error, expected value, and exception type at the "error" log level.

Returns a basic ring response map with the :body as the JSON serialized representation of helpful exception information wrapped in a map and accessible by the "error" key. Always returns an error type of "application-error".

Example return body:

{
  "error": {
    "type": "application-error",
    "message": "Something unexpected happened: {:error ... :value ... :type :schema.core/error}"
  }
}

Returns valid ResponseTypes, eg:

(wrap-schema-errors handler :plain)

wrap-uncaught-errors

(wrap-uncaught-errors handler)

Always returns a status code of 500 to the client and logs a message with the serialized Exception at the "error" log level.

Returns a basic ring response map with the :body set as the JSON serialized representation of helpful exception information wrapped in a map and accessible by the "error" key. Always returns an error type of "application-error".

Example return body:

{
  "error": {
    "type": "application-error",
    "message": "Internal Server Error: <serialized Exception>"
  }
}

Returns valid ResponseTypes, eg:

(wrap-uncaught-errors handler :plain)

wrap-accepts-content-type

(wrap-accepts-content-type handler content-type)

Returns a wrapper that evaluates the accept header of the incoming request and validate that it accepts a type that this endpoint will produce.

For example, if the endpoint will accept json

(wrap-accepts-content-type handler "application/json")

If the request supplies a result with text/plain a 406 not-acceptable error will be returned

wrap-accepts-json

(wrap-accepts-json handler)

Returns a wrapper that evaluates the accept header of the incoming request and validates that it matches application/json

If it doesn't, a response with a 406 not acceptable is returned.

wrap-content-type

(wrap-content-type handler <sequence of content types>)

Ensure that the content type of the body of the incoming request matches the acceptable content types this endpoint supports. For example:

(wrap-content-type handler [json-encoding-type])

If the content type is not matched, a 415 Unsupported Media Type is returned.

wrap-content-type-json

(wrap-content-type-json handler)

Ensure that the content type of the body of the incoming request matches the a json type. If the content type is not matched, a 415 Unsupported Media Type is returned.

wrap-json-parse-exception-handler

(wrap-json-parse-exception-handler handler)

Ensure that if a JsonParseException is thrown while the handler is being executed, an appropriate error is returned. a 400 Bad Request with appropriate messaging will be returned.

Support

Please log tickets and issues at our Trapperkeeper Issue Tracker. In addition there is a #trapperkeeper channel on Freenode.