luciano/reitit
1
0
Fork 0
mirror of https://github.com/metosin/reitit.git synced 2025-12-20 09:31:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Ring coercion docs

Browse source
This commit is contained in:
Tommi Reiman 2017-12-15 08:20:53 +02:00
parent 1427f12c53
commit 00b6b22b6e
6 changed files with 143 additions and 184 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
doc/SUMMARY.md
View file

@ -22,7 +22,7 @@
* [Ring-router](ring/ring.md) * [Ring-router](ring/ring.md)
* [Dynamic Extensions](ring/dynamic_extensions.md) * [Dynamic Extensions](ring/dynamic_extensions.md)
* [Data-driven Middleware](ring/data_driven_middleware.md) * [Data-driven Middleware](ring/data_driven_middleware.md)
* [Pluggable Coercion](ring/coercion.md) * [Ring Coercion](ring/coercion.md)
* [Compiling Middleware](ring/compiling_middleware.md) * [Compiling Middleware](ring/compiling_middleware.md)
* [Performance](performance.md) * [Performance](performance.md)
* [FAQ](faq.md) * [FAQ](faq.md)

12
doc/coercion/coercion.md
View file

@ -12,7 +12,7 @@ By default, all wildcard and catch-all parameters are parsed as Strings:
["/:company/users/:user-id" ::user-view])) ["/:company/users/:user-id" ::user-view]))
``` ```
Match with the String `:params`: Match with the parsed `:params` as Strings:
```clj ```clj
(r/match-by-path r "/metosin/users/123") (r/match-by-path r "/metosin/users/123")
@ -36,8 +36,8 @@ To enable parameter coercion, the following things need to be done:
Reitit ships with the following coercion modules: Reitit ships with the following coercion modules:
* `reitit.coercion.schema/coercion` for [plumatic schema](https://github.com/plumatic/schema). * `reitit.coercion.schema/coercion` for [plumatic schema](https://github.com/plumatic/schema)
* `reitit.coercion.spec/coercion` for both [clojure.spec](https://clojure.org/about/spec) and [data-specs](https://github.com/metosin/spec-tools#data-specs). * `reitit.coercion.spec/coercion` for both [clojure.spec](https://clojure.org/about/spec) and [data-specs](https://github.com/metosin/spec-tools#data-specs)
Coercion can be attached to route data under `:coercion` key. There can be multiple `Coercion` implementations within a single router, normal [scoping rules](../basics/route_data.html#nested-route-data) apply. Coercion can be attached to route data under `:coercion` key. There can be multiple `Coercion` implementations within a single router, normal [scoping rules](../basics/route_data.html#nested-route-data) apply.
@ -179,7 +179,9 @@ For a full-blown http-coercion, see the [ring coercion](../ring/coercion.md).
## Thanks to ## Thanks to
Most of the thing are just polished version of the original implementations. Big thanks to: Most of the thing are just polished version of the original implementations. Thanks to:
* [compojure-api](https://clojars.org/metosin/compojure-api) for the initial `Coercion` protocol * [compojure-api](https://clojars.org/metosin/compojure-api) for the initial `Coercion` protocol
* [ring-swagger](https://github.com/metosin/ring-swagger#more-complete-example) for the syntax of the `:paramters` (and `:responses`). * [ring-swagger](https://github.com/metosin/ring-swagger#more-complete-example) for the `:parameters` and `:responses` syntax.
* [schema](https://github.com/plumatic/schema) and [schema-tools](https://github.com/metosin/schema-tools) for Schema Coercion
* [spec-tools](https://github.com/metosin/spec-tools) for Spec Coercion

2
doc/ring/README.md
View file

@ -3,5 +3,5 @@
* [Ring-router](ring.md) * [Ring-router](ring.md)
* [Dynamic Extensions](dynamic_extensions.md) * [Dynamic Extensions](dynamic_extensions.md)
* [Data-driven Middleware](data_driven_middleware.md) * [Data-driven Middleware](data_driven_middleware.md)
* [Pluggable Coercion](coercion.md) * [Ring Coercion](coercion.md)
* [Compiling Middleware](compiling_middleware.md) * [Compiling Middleware](compiling_middleware.md)

279
doc/ring/coercion.md
View file

@ -1,209 +1,168 @@
# Pluggable Coercion # Ring Coercion
Reitit provides pluggable parameter coercion via `reitit.coercion/Coercion` protocol, originally introduced in [compojure-api](https://clojars.org/metosin/compojure-api). Coercion is explained in detail [in the Coercion Guide](../coercion/coercion.md). Both request parameters (`:query`, `:body`, `:form`, `:header` and `:path`) and response `:body` can be coerced.
To enable coercion, the following things need to be done:
* Define a `reitit.coercion/Coercion` for the routes
* Define types for the parameters and/or responses
* Mount Coercion Middleware to apply to coercion
* Use the coerced parameters in a handler/middleware
## Define coercion
`reitit.coercion/Coercion` is a protocol defining how types are defined, coerced and inventoried.
Reitit ships with the following coercion modules: Reitit ships with the following coercion modules:
* `reitit.coercion.schema/coercion` for [plumatic schema](https://github.com/plumatic/schema). * `reitit.coercion.schema/coercion` for [plumatic schema](https://github.com/plumatic/schema)
* `reitit.coercion.spec/coercion` for both [clojure.spec](https://clojure.org/about/spec) and [data-specs](https://github.com/metosin/spec-tools#data-specs). * `reitit.coercion.spec/coercion` for both [clojure.spec](https://clojure.org/about/spec) and [data-specs](https://github.com/metosin/spec-tools#data-specs)
### Ring request and response coercion Coercion can be attached to route data under `:coercion` key. There can be multiple `Coercion` implementations within a single router, normal [scoping rules](../basics/route_data.html#nested-route-data) apply.
To use `Coercion` with Ring, one needs to do the following: # Defining parameters and responses
1. Define parameters and responses as data into route data, in format adopted from [ring-swagger](https://github.com/metosin/ring-swagger#more-complete-example): Below is a ring route data defining [Plumatic Schema](https://github.com/plumatic/schema) coercion. It defines schemas for `:query`, `:body` and `:path` parameters and for a successful response `:body`.
* `:parameters` map, with submaps for different parameters: `:query`, `:body`, `:form`, `:header` and `:path`. Parameters are defined in the format understood by the `Coercion`.
* `:responses` map, with response status codes as keys (or `:default` for "everything else") with maps with `:schema` and optionally `:description` as values.
2. Set a `Coercion` implementation to route data under `:coercion`
3. Mount request & response coercion middleware to the routes (can be done for all routes as the middleware are only mounted to routes which have the parameters &/ responses defined):
* `reitit.ring.coercion-middleware/coerce-request-middleware`
* `reitit.ring.coercion-middleware/coerce-response-middleware`
If the request coercion succeeds, the coerced parameters are injected into request under `:parameters`. The coerced parameters can be read under `:parameters` key in the request.
If either request or response coercion fails, an descriptive error is thrown. To turn the exceptions into http responses, one can also mount the `reitit.ring.coercion-middleware/coerce-exceptions-middleware` middleware ```clj
(require '[reitit.coercion.schema])
(require '[schema.core :as s])
(def plus-endpoint
{:coercion reitit.coercion.schema/coercion
:parameters {:query {:x s/Int}
:body {:y s/Int}
:path {:z s/Int}}
:responses {200 {:schema {:total PositiveInt}}}
:handler (fn [{:keys [parameters]}]
(let [total (+ (-> parameters :query :x)
(-> parameters :body :y)
(-> parameters :path :z))]
{:status 200
:body {:total total}}))})
```
## Coercion Middleware
Defining a coercion for a route data doesn't do anything, as it's just data. We have to attach some code to apply the actual coercion. We can use the middleware from `reitit.ring.coercion-middleware`:
* `coerce-request-middleware` for the parameter coercion
* `coerce-response-middleware` for the response coercion
* `coerce-exceptions-middleware` to turn coercion exceptions into pretty responses
### Example with Schema ### Example with Schema
```clj ```clj
(require '[reitit.ring :as ring]) (require '[reitit.ring.coercion-middleware :as mw])
(require '[reitit.ring.coercion-middleware :as coercion-middleware])
(require '[reitit.coercion.schema :as schema])
(require '[schema.core :as s])
(def app (def app
(ring/ring-handler (ring/ring-handler
(ring/router (ring/router
["/api" ["/api"
["/ping" {:post {:parameters {:body {:x s/Int, :y s/Int}} ["/ping" {:name ::ping
:responses {200 {:schema {:total (s/constrained s/Int pos?)}}} :get (fn [_]
:handler (fn [{{{:keys [x y]} :body} :parameters}]
{:status 200 {:status 200
:body {:total (+ x y)}})}}]] :body "pong"})}]
{:data {:middleware [coercion-middleware/coerce-exceptions-middleware ["/plus/:z" {:name ::plus
coercion-middleware/coerce-request-middleware :post {:coercion reitit.coercion.schema/coercion
coercion-middleware/coerce-response-middleware] :parameters {:query {:x s/Int}
:coercion schema/coercion}}))) :body {:y s/Int}
:path {:z s/Int}}
:responses {200 {:schema {:total PositiveInt}}}
:handler (fn [{:keys [parameters]}]
(let [total (+ (-> parameters :query :x)
(-> parameters :body :y)
(-> parameters :path :z))]
{:status 200
:body {:total total}}))}}]]
{:data {:middleware [mw/coerce-exceptions-middleware
mw/coerce-request-middleware
mw/coerce-response-middleware]}})))
``` ```
Valid request: Valid request:
```clj ```clj
(app (app {:request-method :post
{:request-method :post :uri "/api/plus/3"
:uri "/api/ping" :query-params {"x" "1"}
:body-params {:x 1, :y 2}}) :body-params {:y 2}})
; {:status 200 ; {:status 200, :body {:total 6}}
; :body {:total 3}}
``` ```
Invalid request: Invalid request:
```clj ```clj
(app (app {:request-method :post
{:request-method :post :uri "/api/plus/3"
:uri "/api/ping" :query-params {"x" "abba"}
:body-params {:x 1, :y "2"}}) :body-params {:y 2}})
; {:status 400, ; {:status 400,
; :body {:type :reitit.coercion/request-coercion ; :body {:schema {:x "Int", "Any" "Any"},
; :coercion :schema ; :errors {:x "(not (integer? \"abba\"))"},
; :in [:request :body-params] ; :type :reitit.coercion/request-coercion,
; :value {:x 1, :y "2"} ; :coercion :schema,
; :schema {:x "Int", :y "Int"} ; :value {:x "abba"},
; :errors {:y "(not (integer? \"2\"))"}}} ; :in [:request :query-params]}}
``` ```
### Example with data-specs Invalid response:
```clj ```clj
(require '[reitit.ring :as ring]) (app {:request-method :post
(require '[reitit.ring.coercion-middleware :as coercion-middleware]) :uri "/api/plus/3"
(require '[reitit.coercion.spec :as spec]) :query-params {"x" "1"}
:body-params {:y -10}})
(def app ; {:status 500,
(ring/ring-handler ; :body {:schema {:total "(constrained Int PositiveInt)"},
(ring/router ; :errors {:total "(not (PositiveInt -6))"},
["/api" ; :type :reitit.coercion/response-coercion,
["/ping" {:post {:parameters {:body {:x int?, :y int?}} ; :coercion :schema,
:responses {200 {:schema {:total pos-int?}}} ; :value {:total -6},
:handler (fn [{{{:keys [x y]} :body} :parameters}] ; :in [:response :body]}}
{:status 200
:body {:total (+ x y)}})}}]]
{:data {:middleware [coercion-middleware/coerce-exceptions-middleware
coercion-middleware/coerce-request-middleware
coercion-middleware/coerce-response-middleware]
:coercion spec/coercion}})))
``` ```
Valid request: ### Optimizations
The coercion middleware are [compiled againts a route](compiling_middleware,md). This enables them to compile and cache the actual coercers for the defined models ahead of time. They also unmount if a route doesn't have `:coercion` and `:parameters` or `:responses` defined.
We can query the compiled middleware chain for the routes:
```clj ```clj
(app (require '[reitit.core :as r])
{:request-method :post
:uri "/api/ping" (-> (ring/get-router app)
:body-params {:x 1, :y 2}}) (r/match-by-name ::plus)
; {:status 200 :result :post :middleware
; :body {:total 3}} (->> (mapv :name)))
; [::mw/coerce-exceptions
; ::mw/coerce-parameters
; ::mw/coerce-response]
``` ```
Invalid request: Route without coercion defined:
```clj ```clj
(app (app {:request-method :get, :uri "/api/ping"})
{:request-method :post ; {:status 200, :body "pong"}
:uri "/api/ping"
:body-params {:x 1, :y "2"}})
; {:status 400,
; :body {:type ::coercion/request-coercion
; :coercion :spec
; :in [:request :body-params]
; :value {:x 1, :y "2"}
; :spec "(spec-tools.core/spec {:spec (clojure.spec.alpha/keys :req-un [:$spec37747/x :$spec37747/y]), :type :map, :keys #{:y :x}, :keys/req #{:y :x}})"
; :problems [{:path [:y]
; :pred "clojure.core/int?"
; :val "2"
; :via [:$spec37747/y]
; :in [:y]}]}}
``` ```
### Example with clojure.spec Has no mounted middleware:
Currently, `clojure.spec` [doesn't support runtime transformations via conforming](https://dev.clojure.org/jira/browse/CLJ-2116), so one needs to wrap all specs with `spec-tools.core/spec`.
```clj ```clj
(require '[reitit.ring :as ring]) (-> (ring/get-router app)
(require '[reitit.ring.coercion-middleware :as coercion-middleware]) (r/match-by-name ::ping)
(require '[reitit.coercion.spec :as spec]) :result :get :middleware
(require '[clojure.spec.alpha :as s]) (->> (mapv :name)))
(require '[spec-tools.core :as st]) ; []
(s/def ::x (st/spec int?))
(s/def ::y (st/spec int?))
(s/def ::total int?)
(s/def ::request (s/keys :req-un [::x ::y]))
(s/def ::response (s/keys :req-un [::total]))
(def app
(ring/ring-handler
(ring/router
["/api"
["/ping" {:post {:parameters {:body ::request}
:responses {200 {:schema ::response}}
:handler (fn [{{{:keys [x y]} :body} :parameters}]
{:status 200
:body {:total (+ x y)}})}}]]
{:data {:middleware [coercion-middleware/coerce-exceptions-middleware
coercion-middleware/coerce-request-middleware
coercion-middleware/coerce-response-middleware]
:coercion spec/coercion}})))
``` ```
## Thanks to
Valid request: Most of the thing are just polished version of the original implementations. Thanks to:
```clj * [compojure-api](https://clojars.org/metosin/compojure-api) for the initial `Coercion` protocol
(app * [ring-swagger](https://github.com/metosin/ring-swagger#more-complete-example) for the `:parameters` and `:responses` syntax.
{:request-method :post * [schema](https://github.com/plumatic/schema) and [schema-tools](https://github.com/metosin/schema-tools) for Schema Coercion
:uri "/api/ping" * [spec-tools](https://github.com/metosin/spec-tools) for Spec Coercion
:body-params {:x 1, :y 2}})
; {:status 200
; :body {:total 3}}
```
Invalid request:
```clj
(app
{:request-method :post
:uri "/api/ping"
:body-params {:x 1, :y "2"}})
; {:status 400,
; :body {:type ::coercion/request-coercion
; :coercion :spec
; :in [:request :body-params]
; :value {:x 1, :y "2"}
; :spec "(spec-tools.core/spec {:spec (clojure.spec.alpha/keys :req-un [:reitit.coercion-test/x :reitit.coercion-test/y]), :type :map, :keys #{:y :x}, :keys/req #{:y :x}})"
; :problems [{:path [:y]
; :pred "clojure.core/int?"
; :val "2"
; :via [::request ::y]
; :in [:y]}]}}
```
### Custom coercion
Both Schema and Spec Coercion can be configured via options, see the source code for details.
To plug in new validation engine, see the
`reitit.coercion/Coercion` protocol.
```clj
(defprotocol Coercion
"Pluggable coercion protocol"
(-get-name [this] "Keyword name for the coercion")
(-get-apidocs [this model data] "???")
(-compile-model [this model name] "Compiles a coercion model")
(-open-model [this model] "Returns a new map model which doesn't fail on extra keys")
(-encode-error [this error] "Converts error in to a serializable format")
(-request-coercer [this type model] "Returns a `value format => value` request coercion function")
(-response-coercer [this model] "Returns a `value format => value` response coercion function"))
```

15
doc/ring/compiling_middleware.md
View file

@ -14,8 +14,8 @@ To demonstrate the two approaches, below are response coercion middleware writte
```clj ```clj
(defn wrap-coerce-response (defn wrap-coerce-response
"Pluggable response coercion middleware. "Middleware for pluggable response coercion.
Expects a :coercion of type `reitit.coercion.protocol/Coercion` Expects a :coercion of type `reitit.coercion/Coercion`
and :responses from route data, otherwise will do nothing." and :responses from route data, otherwise will do nothing."
[handler] [handler]
(fn (fn
@ -53,19 +53,18 @@ To demonstrate the two approaches, below are response coercion middleware writte
(def coerce-response-middleware (def coerce-response-middleware
"Middleware for pluggable response coercion. "Middleware for pluggable response coercion.
Expects a :coercion of type `reitit.coercion.protocol/Coercion` Expects a :coercion of type `reitit.coercion/Coercion`
and :responses from route data, otherwise does not mount." and :responses from route data, otherwise does not mount."
(middleware/create
{:name ::coerce-response {:name ::coerce-response
:compile (fn [{:keys [coercion responses opts]} _] :compile (fn [{:keys [coercion responses]} opts]
(if (and coercion responses) (if (and coercion responses)
(let [coercers (response-coercers coercion responses opts)] (let [coercers (coercion/response-coercers coercion responses opts)]
(fn [handler] (fn [handler]
(fn (fn
([request] ([request]
(coerce-response coercers request (handler request))) (coercion/coerce-response coercers request (handler request)))
([request respond raise] ([request respond raise]
(handler request #(respond (coerce-response coercers request %)) raise)))))))})) (handler request #(respond (coercion/coerce-response coercers request %)) raise)))))))})
``` ```
The latter has 50% less code, is easier to reason about and is much faster. The latter has 50% less code, is easier to reason about and is much faster.

3
perf-test/clj/reitit/bide_perf_test.clj
View file

@ -10,8 +10,7 @@
[io.pedestal.http.route.definition.table :as table] [io.pedestal.http.route.definition.table :as table]
[io.pedestal.http.route.map-tree :as map-tree] [io.pedestal.http.route.map-tree :as map-tree]
[io.pedestal.http.route.router :as pedestal] [io.pedestal.http.route.router :as pedestal]
[io.pedestal.http.route :as route] [io.pedestal.http.route :as route]))
[reitit.core :as r]))
;; ;;
;; start repl with `lein perf repl` ;; start repl with `lein perf repl`