Refactored the argument resolvers out to their own namespace.
Added an injection argument provider
Updated dependencies to Pedestal 0.5.1.
Added support for :route-name metadata.
Improvements to documentation.
A major pivot to change Rook to be a way of generating Pedestal routing tables.
Improvements to the initial example provided in the manual.
Updated a number of dependencies to latest.
lein with-profile +1.6 spec now runs tests under 1.6 and
lein spec under 1.7
Custom endpoint coercions for request parameters.
Relaxed restrictions on :format with io.aviso.rook.schema/with-data-type.
Added significant amounts of Prismatic Schema to the structures and functions in
Added io.aviso.rook/resolve-argument, which is used to access argument values using the same resolution logic
as when invoking endpoint functions.
Rolled back Clojure compatibility to 1.6.
More Swagger fixes:
- Change "otherProperties" to "additionalProperties"
type: 'object' for object schemas
- Dig down through nested schemas to find the data type mapping (much like description extraction in 0.1.32)
- New function io.aviso.rook.schema/with-data-type is used to annotate the type and format for a schema where this
can't be normally deduced, such as when using schema.core/pred.
- New function io.aviso.rook.schema/with-usage-description allows a description of how a schema is being used, distinct
from the schemas own description.
- Metadata on endpoint function parameters is now evaluated, as was already done with namespace metadata
- Schemas created via schema.core/maybe now include
"x-nullable": true in their definition.
Small improvements to how documentation is extracted from nested schemas (as part of the Swagger support).
(s/maybe (rs/with-description "The frobinator's unique id." s/Str)) will now find that
description, where previously it did not.
Update to latest dependencies, including Ring 1.4.0.
Updated Clojure dependency to 1.7.0.
Rook can now handle coercion, even when the schema has been decorated with a description via
Description strings extracted from :doc or :documentation metadata are now re-indented before being emitted
into the Swagger API description. Previously, lines after the first were indented (typically) two extra characters
and some Markdown extensions would have trouble parsing the result properly.
Adds support for :* in an endpoint's route metadata. :* matches one or more path terms; the matched portion of the URI
is available as the endpoint argument
Improvements to the generation of Swagger API descriptions:
- Descriptions of properties of schemas are now captured
- :description meta data on path variables is now captured
- Header arguments are now identified and documented
Added the :lazy option to io.aviso.rook.server/construct-handler.
Added support for schema.core/enum keys when generating Swagger API documentation.
It is now possible, and encouraged, to apply schema validation to the :query-params, :form-params, and/or :body-params
individually. Previously only :params could be validated and coerced.
When the necessary metadata (:query-schema, :form-schema, :body-schema, :schema) is present, then:
- The corresponding request key is extracted (:query-params, :form-params, etc.)
- String keys are converted to keywords, recursively (applies to :form-params and :query-params)
- Prismatic Schema is used to coerce and validate
- The result is stored back into the request under the same key
- The :params key is rebuilt from the merge of the :query-params, :form-params, and :body-params keys
Swagger 2.0 support has been completely rewritten. In progress.
The io.aviso.rook.client namespace has been removed with no replacement.
Rook is now focused on dispatch of incoming requests to endpoints; a hard look at the async features have found them to
be problematic on several fronts, and not providing any measurable performance improvement; they have been removed.
io.aviso.rook.server has a new function, wrap-with-exception-catching, which catches exceptions, reports them
(using io.aviso/tracker), and returns a 500 failure response.
The construct-handler function has been enhanced with new options to enable exception catching, and to provide
the standard Rook middleware.
In addition, there has been a general refresh of dependencies to latest.
When there is an exception creating the handler, io.aviso.rook.server now replaces the handler with one that returns
a 500 response that includes the error message from the exception.
Previously, a handler that handler creator that threw an exception would prevent the server from starting up (in production mode), or
cause a Jetty exception on each request (in development mode).
Straightened out some conflicts and missing dependencies.
Big improvements to the documentation, especially the description of mapping namespaces.
- In the options map passed to server/construct-handler, :log is no longer implied by :debug,
they are entirely separate now.
- Failure response bodies are now more uniform, and generated by new function io.aviso.rook.utils/failure-response.
- When using wrap-with-timeout, there is now a :timeout-control-ch key added to the request, allowing
the timeout to be triggered early or canceled entirely.
- Beefed up the logging of requests and responses inside io.aviso.rook.server.
- Removed the io.aviso.rook.jetty-async-adapter namespace; use Jet instead.
- The dependency on Ring was switched from ring to ring/ring-core; you may need to add ring/ring-jetty-adapter
in to your project.
- Rewritten io.aviso.rook.dispatcher; simplified, and adds the ability to define
argument resolvers for each namespace.
- Consolidated the documentation for namespace specifications and options in a single place.
- Attempting to use Swagger without the necessary dependencies will now be a failure (a
descriptive exception will be thrown).
- Lots of other progress on making the Swagger support usable.
- Improvements to response validation, especially when exceptions occur during validation
- io.aviso.rook.client has changed in minor, but incompatible ways (see below)
- Removed the quotes from around the request URI when logging the request method and URI
- Added a sample implementation of a io.aviso.rook.client request handler, based on clj-http
- The response clauses used with the io.aviso.rook.client/then macro have changed structure, and now resemble
similar clauses elsewhere (such as clojure.core.async's alt!).
The io.aviso.rook.client namespace has simplified slightly, and changed slightly, but this
may affect existing code.
First off, the way the
to function creates the :uri key has changed, it no longer includes
the a leading slash. This will affect handlers.
Prior releases also did some logging of the Ring request before it is passed to the request handler,
and the Ring response received through the channel. This no longer occurs -- if this behavior is
desired, it can be built into the request handler.
In addition, the Ring response is now passed through unchanged; prior releases would remove
the Content-Length and Content-Type headers (for obscure reasons that no longer make sense).
- Further improvements to making swagger optional.
- The "async loopback" support has been removed.
- The example used in the manual has been extensively revised.
- It is now possible to have multiple endpoint functions that match a single route; this is used
for versioning and/or content negotiation.
- Dependencies have been updated.
- swagger is now an optional dependency, and is only required if the :swagger option is enabled
- Namespace paths can now be a simple string, as an alternative to a vector. E.g.
(rook/namespace-handler ["users" 'org.example.resources.users]).
- The convention name for PUT :id has been renamed from
update is still supported, but will be removed in a subsequent release.
- Improvements to the io.aviso.rook.client/then macro.
- Removed support for the :path-spec metadata.
- The :context-pathvec option was renamed to :context.
- The way synchronous handlers are wrapped into asynchronous handlers is now pluggable.
- As usual, keeping up with dependencies.
edit convention names for endpoint functions were removed.
- The convention name for PUT :id has changed from
change (to avoid future conflict with Clojure 1.7).
- The :route-spec metadata key has been renamed to just :route.
- A new and very alpha integration with ring-swagger has been introduced.
A critical bug related to dispatch and route parameters has been identified and fixed.
This release addresses a few minor issues related to reporting errors.
Importantly, when using response validation, any 5xx error responses
(usually indicating a failure inside the response handler function, or downstream from the function) are passed through unchanged.
This release updates a few dependencies, and adds additional debugging inside the io.aviso.rook.dispatcher namespace:
- With debug enabled, there is a message identifying how each incoming request is matched to a function
- With trace enabled, there is a message (at startup) identifying the merged metadata for each endpoint function
The merged metadata is the merge of the function's metadata with the containing namespace's. An attempt is made to eliminate common keys (such as :doc, :line, etc.) so that it's just the custom metadata provided on the function itself (or inherited from the namespace).
This extra debugging is very handy for diagnosing issues such as "is it invoking my handler?" or "why is my middleware not getting invoked?".
No issues were closed in this release.
This release significantly revamped argument resolvers, including making the list of argument resolvers extensible using options to the namespace-handler, and via :arg-resolvers metadata on functions and namespaces.
Middleware for namespaces is no longer simple Ring middleware; the middleware is passed both the handler to wrap and the merged metadata for the endpoint function. This encourages the middleware to only wrap handlers for which it applies, leading to improved runtime efficiency. A new function, compose-middleware makes it easy to string together several middleware expressions, similar to how -> is used for Ring middleware.
In addition, it is now possible to add metadata defining response status code and corresponding body schemas; this is useful in development to ensure that your endpoint functions are returning the values you expect.
No issues were closed for this release.
The major change in this release is the introduction of a new dispatcher system that scales larger and operates more efficiently than Compojure; in fact Compojure and Clout are no longer dependencies of Rook.
Documentation for Rook has been greatly expanded and moved out of the project.
We've also gone a long way towards improved efficiency; there's a new and improved system for matching endpoint function arguments to a resolver that provides the value for the argument. This is now done computed once, when building the dispatcher, rather than computed by a search every time a endpoint function is invoked.
Expect some more changes in 0.1.11 that close the final loops in dynamic argument resolution, as well as making the argument resolution more extensible.
This release refines the async support in Ring considerably; it replaces the odd 'return
false' behavior for asynchronous handlers with the more traditional 'return
nil' (to close the result channel).
Synchronous handlers are now explicitly invoked in a new
thread block; previously they may have been executed inside a
go block thread.
There's new middleware for supporting Ring sessions in a fully async pipeline.
All endpoint function arguments are resolved uniformly via the
:arg-resolvers list; this includes previously hard-coded arguments such as
The default list of argument resolvers now includes the ability to resolve Ring request headers, for example: An argument named
content-type will map to the
"content-type" Ring request header.
Endpoint function arguments may now be destructured maps; as long as the
:as keyword is there (to provide a name for argument resolution). This is useful for extracting a large number of values from the Ring request
A default argument resolver for
params* will resolve to the same as
params, but with the map keys Clojurized (underscores replaced with dashes).
A default argument resolver for
resource-uri has been added; this is typically used to supply a
Location header in a response.
Schema cooercion now understands converting strings to booleans, instants, and UUIDs. Schema validation reporting is better, but still a work in progress. Validation has been simplified; there's no longer any attempt to 'shave' the parameters to match the schema, so you will often need to add a mapping of
s/Any to prevent spurious failures (from arbitrary query parameters, for example).
Note: there have been a number of refactorings; a few functions have been renamed, and in some places, key/value varargs have been replaced with a simple map.
- namespace-middleware --> wrap-namespace
- arg-resolver-middleware --> wrap-with-arg-resolvers
This release introduces a significant new feature: Asynchronous request processing using core.async. At its core is the definition of an asynchronous handler (or middleware), which accepts a Ring request map and returns its response inside a channel; asynchronous handlers are typically implemented using
Resources within the same server will often need to cooperate; Rook supports this via the asynchronous loopback, which is a way for one resource to send a request to another resource using core.async conventions (and without involving HTTP or HTTPs).
There's also support for leveraging Jetty continuations so that all request handling is fully non-blocking, end-to-end.
- Validation of incoming request parameters using Prismatic Schema
io.aviso.rook.client namespace to streamline cooperation between resources via the asynchronous loopback
- Metadata from the containing namespace is merged into metadata for individual endpoint functions