Liking cljdoc? Tell your friends :D

Introduction to bract.ring

This module provides Ring support for the Bract framework.

Starting a web server

The inducer bract.ring.inducer/start-server can start a web server using a supplied Ring handler. Include it in your inducer chain and populate the following keys in the context:

  :bract.ring/ring-handler   (fn [request])  ; a valid Ring handler
  :bract.ring/server-starter bract.ring.server/start-http-kit-server
  :bract.ring/server-options {:port 3000}

You may choose any supported server starter from the bract.ring.server namespace. You may also put the server options in the config (referred to by context key :bract.core/config) under the key "bract.ring.server.options".

Applying middleware to Ring handler

You may apply middleware to a Ring handler (required to be available under the context key :bract.ring/ring-handler) using the inducer bract.ring.inducer/apply-middlewares:

  :bract.ring/ring-handler (fn [request])  ; a valid Ring handler
  :app/inducers            [(bract.ring.inducer/apply-middlewares
                              [ring.middleware.content-type/wrap-content-type
                               ring.middleware.params/wrap-params])]

The above example applies two middlewares to the Ring handler. In practice, you would add the Ring handler to the context via an application inducer.

Applying wrapper to Ring handler

A wrapper is like a middleware (see above section) function, but with arity (fn [handler context]). There are several useful wrappers available in the bract.ring.wrapper namespace. Below is an example how you could apply wrappers to a Ring handler:

  :bract.ring/ring-handler (fn [request])  ; a valid Ring handler
  :app/inducers            [(bract.ring.inducer/apply-wrappers
                              [bract.ring.wrapper/info-endpoint-wrapper
                               bract.ring.wrapper/ping-endpoint-wrapper])]

In practice, you would add the Ring handler to the context via an application inducer.

Context keys

Context keyValue typeDescription
:bract.ring/ring-handlerarity-1 or arity-3 ring handler functionRing handler (sync or async)
:bract.ring/server-starter(fn [handler options]) -> (fn stopper [])See section Starting a web server
:bract.ring/server-stopper(fn [context (fn stopper [])]) -> contextServer stopper function
:bract.ring/server-optionsmapServer options

Provided default context

The file resources/bract/ring/context.edn (which may be referred as bract/ring/context.edn from an application) provides all wrappers from the namespace bract.ring.wrapper under the key :bract.ring/wrappers.

Config keys

Legend:

- FQFN: Fully qualified function name (string or symbol)
- FNable: Function or FQFN
- FNable-0: Zero arity function or FQFN
- FNable-1: Arity-1 function or FQFN
Config keyValue typeDescription
"bract.ring.server.options"mapServer options

Wrapper enabled check

The following config flags are looked up by respective Ring wrappers to determine whether to apply the wrapper:

Config keyValue typeDescription
"bract.ring.health.check.enabled"booleanEnable health check wrapper?
"bract.ring.info.endpoint.enabled"booleanEnable /info endpoint wrapper?
"bract.ring.ping.endpoint.enabled"booleanEnable /ping endpoint wrapper?
"bract.ring.uri.trailing.slash.enabled"booleanEnable URI trailing slash wrapper?
"bract.ring.uri.prefix.match.enabled"booleanEnable URI prefix match wrapper?
"bract.ring.params.normalize.enabled"booleanEnable Ring params normalize wrapper?
"bract.ring.unexpected.500.enabled"booleanEnable unexpected response 500 wrapper?
"bract.ring.traffic.drain.enabled"booleanEnable traffic drain wrapper?
"bract.ring.distributed.trace.enabled"booleanEnable distributed trace wrapper?
"bract.ring.traffic.log.enabled"booleanEnable traffic log wrapper?

Wrapper config

The configs related to various wrappers are listed below:

Health check wrapper

Config keyValue typeDescription
"bract.ring.health.check.uris"vector of stringURIs for health check endpoint, e.g. ["/health" "/health/"]
"bract.ring.health.body.encoder"FNable-1(fn [data]) -> Ring response body, e.g. clojure.core/pr-str
"bract.ring.health.content.type"stringRing response Content-type header, e.g. "application/edn"
"bract.ring.health.http.codes"map keyword:stringHTTP codes, e.g. {:critical 503 :degraded 500 :healthy 200}
"bract.ring.health.event.name"stringEvent name to log on successful processing

/info endpoint wrapper

Config keyValue typeDescription
"bract.ring.info.endpoint.uris"vector of stringURIs for /info endpoint, e.g. ["/info" "/info/"]
"bract.ring.info.body.encoder"FNable-1(fn [data]) -> Ring response body, e.g. clojure.core/pr-str
"bract.ring.info.content.type"stringRing response Content-type header, e.g. "application/edn"
"bract.ring.info.event.name"stringEvent name to log on successful processing

/ping endpoint wrapper

Config keyValue typeDescription
"bract.ring.ping.endpoint.uris"vector of stringURIs for /info endpoint, e.g. ["/info" "/info/"]
"bract.ring.ping.endpoint.body"Ring response bodyA valid Ring response body, e.g. "pong"
"bract.ring.ping.content.type"stringRing response Content-type header, e.g. "text/plain"
"bract.ring.ping.event.name"stringEvent name to log on successful processing

Trailing slash wrapper

Config keyValue typeDescription
"bract.ring.uri.trailing.slash.action"KeywordOperative keyword - :add or :remove

Prefix match wrapper

Config keyValue typeDescription
"bract.ring.uri.prefix.match.token"stringThe prefix string to match
"bract.ring.uri.prefix.strip.flag"booleanWhether strip the prefix from the URI, e.g. true
"bract.ring.uri.prefix.backup.flag"booleanWhether backup the original URI in the request, e.g. true
"bract.ring.uri.prefix.backup.key"keywordKey to store original URI at in request, e.g. :original-uri

Params normalize wrapper

Config keyValue typeDescription
"bract.ring.params.normalize.function"arity-1 FQFNFunction to normalize param value, e.g. clojure.core/first

Unexpected->500 wrapper

Config keyValue typeDescription
"bract.ring.unexpected.response.fn"arity-3 FQFNUnexpected response handler e.g. b.r.util/bad-response->500
"bract.ring.unexpected.exception.fn"arity-2 FQFNException handler, e.g. b.r.util/exception->500
"bract.ring.unexpected.badres.event.name"stringEvent name to log on invalid Ring response
"bract.ring.unexpected.thrown.event.name"stringEvent name to log on exception instead of Ring response

Traffic drain wrapper

Config keyValue typeDescription
"bract.ring.traffic.conn.close.flag"booleanWhether send Connection: close response header, e.g. true

Distributed trace wrapper

Config keyValue typeDescription
"bract.ring.trace.trace.id.header"stringTrace ID header, e.g. "x-trace-id"
"bract.ring.trace.parent.id.header"stringParent ID header, e.g. "x-trace-parent-id"
"bract.ring.trace.trace.id.req.flag"booleanWhether Trace ID is required, e.g. false
"bract.ring.trace.trace.id.valid.fn"arity-1 FQFNFunction to return error on invalid Trace ID, nil otherwise
"bract.ring.trace.trace.id.req.key"keywordRequest key to put trace ID under, e.g. :trace-id
"bract.ring.trace.span.id.req.key"keywordRequest key to put request ID under, e.g. :span-id
"bract.ring.trace.parent.id.req.key"keywordRequest key to put parent ID under, e.g. :parent-id

Traffic log wrapper

Config keyValue typeDescription
"bract.ring.traffic.log.options"mapKeys :request-logger, :response-logger, :exception-logger

Provided default config

The files resources/bract/ring/config.edn (which may be referred as bract/ring/context.edn from an application)

FileAvailable in application asContents
config.ednbract/ring/config.ednUseful defaults for prod
config.dev.ednbract/ring/config.dev.ednUseful defaults DEV mode

Can you improve this documentation?Edit on GitHub

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

× close