arachne.http.dsl

User-facing DSL functions for init scripts

*context-path*

dynamic

The path prefix currently in context. If bound, will be automatically appended to the paths of endpoints declared in the context.

*context-server*

dynamic

The entity ID of the HTTP server currently in context.

context

macro

(context path & body)
Creates a context which scopes endpoint definitions (and possibly other types of definitions) to the specified path. For example,

  (context "foo/bar"
    (endpoint :get "baz" :some/handler))

is the same as:

  (endpoint :get "foo/bar/baz" :some/handler).

Concretely, this macro evaluates the body with *context-path* bound to the given path.

endpoint

(endpoint methods path component & opts)
Attach the specified component to the routing tree at a specfic location.

 Arguments are:

 - Method(s) (mandatory): either a keyword or set of keywords indicating the HTTP methods
   that this endpoint supports. The special value `:any` is also supported.
 - Path (mandatory): The URL path to which the endpoint is attached.
 - Handler Component (mandatory): A reference to the component used to actually handle HTTP
   requests. The component instance should be of a supported type for whatever server you're
   using (such as a Pedestal interceptor, an Arachne Handler component, or a Ring handler
   function).
 - Options (optional): A map (or kwargs) of additional options.

Supported options are:

 - :name - the name of the endpoint. If none is provided, one will be inferred.

Name inference proceeds as follows:

   1. If the component has an Arachne ID, that is used as the name.
   2. If the component is an Arachne handler, the fully qualified name of the backing function
      is used as the name.
   3. If either of the methods #1 or #2 above would result in a name being applied to more than
      one route (including a single `endpoint` DSL form that specifies more than one HTTP
      method), a unique name will be assigned. Specify a :name explicitly to avoid this.

Returns the entity ID of the endpoint component.

handler

(handler <arachne-id> handler <dependencies>)
Defines a HTTP request handler component that uses a simple Ring-style
request handler function.

Arguments are:

- Arachne ID (optional): An Arachne ID for the handler component
- Handler function (mandatory): A symbol naming the handler function
- Dependency map (optional): A component dependency map of {<key> <component-reference>}.
  A component reference may be an Arachne ID or entity ID.

Dependencies will be assoc'd with the specified key to the Ring request map before it is
passed to the supplied handler function.