Catacumba Api Documentation

Register a callback in the context that will be called just before send the response to the client. Is a useful hook for set some additional cookies, headers or similar response transformations.

Delegate handling to the next handler in line.

This function accept an additiona parameter for pass context parameters to the next handlers, and that can be obtained with context-params function.

Returns an instance of DelegatedContext.

Check if the provided value is a DelegatedContext instance.

Reads asynchronously the body from context. This function return a promise (CompletableFuture instance).

NOTE: it can only be done once, consider using specialized body parsing handlers instead of this. This function should be considered low-level.

Get the incoming cookies.

Parse query params from request and return a maybe multivalue map.

Register a callback in the context that will be called when the connection with the client is closed.

Get the current public address as URI instance.

The default implementation uses a variety of strategies to attempt to provide the desired result most of the time. Information used includes:

• Configured public address URI (optional)
• X-Forwarded-Host header (if included in request)
• X-Forwarded-Proto or X-Forwarded-Ssl headers (if included in request)
• Absolute request URI (if included in request)
• Host header (if included in request)
• Service’s bind address and scheme (http vs. https)

Is a high order function that access a routes vector as argument and return a ratpack router type handler.

Start and ratpack webserver to serve the given handler according to the supplied options:

• :port: the port to listen on (defaults to 5050).
• :host: the host to listen on.
• :address: the ip address to listen on (defaults to localhost).
• :threads: the number of threads (default: number of cores * 2).
• :debug: start in development mode or not (default: true).
• :setup: callback for add additional entries in ratpack registry.
• :basedir: the application base directory. Used mainly for resolve relative paths and assets.
• :decorators: a list of handlers that will be chained at the first of the request pipeline.
• :public-address: force a specific public address (default: nil).
• :max-body-size: set the maximum size of the body (default: 1048576 bytes (1mb))
• :marker-file: the file name of the marker file that will be used for establish the base directory (default catacumba.marker).

Additional notes:

• The :basedir is used mainly to resolve relative paths for assets. When you set no basedir it first try to find a catacumba.marker file in the root of you classpath if it cannot find that it will run without a basedir.
• With :publicaddress you can force one specific public address, in case contrary it will be discovered using a variety of different strategies explained in the public-address function docstring.
• You can set all that parameters using environment variables or jvm system properties. For example, you can use CATACUMBA_BASEDIR environ variable or catacumba.basedir jvm system property for overwrite the :basedir parameter value.

This function does not blocks and you can execute it in a repl without problems. It uses jvm not daemon threads for avoid shutdown the jvm.

Set the outgoing cookies.

(set-cookies! ctx {:cookiename {:value "value"}})

As well as setting the value of the cookie, you can also set additional attributes:

• :domain - restrict the cookie to a specific domain
• :path - restrict the cookie to a specific path
• :secure - restrict the cookie to HTTPS URLs if true
• :http-only - restrict the cookie to HTTP if true (not accessible via e.g. JavaScript)
• :max-age - the number of seconds until the cookie expires

As you can observe is almost identical hash map structure as used in the ring especification.

Set the response http status.

Start the sse connection with the client and dispatch it in a special hanlder.