Merge branch 'master' into ordering

Author: ikitommi

CHANGELOG.md

@@ -1,20 +1,22 @@
-## 0.23.0-SNAPSHOT
+## 0.23.0 (1.9.2016)
 
 * Ring-swagger 0.21.0
   * **BREAKING**: new signature for dispatching custom JSON Schema transformations, old signature will break (nicely at compile-time), see [Readme](https://github.com/metosin/ring-swagger/blob/master/README.md) for details.
   * Support for collections in query parameters. E.g. `:query-params [x :- [Long]]` & url `?x=1&x=2&x=3` should result in `x` being `[1 2 3]`.
 * **BREAKING**: `:validation-errors :error-handler`, `:validation-errors :catch-core-errors?`
   and `:exceptions :exception-handler` options have been removed.
-  * These have been replaced with general `:exceptions :handler` options.
+  * These have been replaced with general `:exceptions :handlers` options.
+  * Fails nicely at compile-time
   * **BREAKING**: New handler use different arity than old handler functions.
+    * new arguments: Exception, ex-info and request.
 * Move `context` from `compojure.api.sweet` to `compojure.api.legacy`. Use `context*` instead.
 * Updated deps:
 
 ```clojure
 [metosin/ring-swagger "0.21.0-SNAPSHOT"] is available but we use "0.20.4"
 [compojure "1.4.0"] is available but we use "1.3.4"
 [prismatic/schema "0.4.4"] is available but we use "0.4.3"
-[metosin/ring-http-response "0.6.4"] is available but we use "0.6.3"
+[metosin/ring-http-response "0.6.5"] is available but we use "0.6.3"
 [metosin/schema-tools "0.5.2"] is available but we use "0.5.1"
 [metosin/ring-swagger-ui "2.1.2"] is available but we use "2.1.5-M2"
 [peridot "0.4.1"] is available but we use "0.4.0"

README.md

@@ -138,8 +138,7 @@ lein new compojure-api my-api +clojure-test
 There is prepackaged middleware `compojure.api.middleware/api-middleware` for common web api usage. It's a enhanced version of `compojure.handler/api` adding the following:
 
 - catching slingshotted http-errors (`ring.middleware.http-response/catch-response`)
-- catching model validation errors (`ring.swagger.middleware/catch-validation-errors`)
-- catching unhandler exceptions (`compojure.api.middleware/wrap-exceptions`)
+- catching unhandled exceptions (`compojure.api.middleware/wrap-exceptions`)
 - support for different protocols via `ring.middleware.format-params/wrap-restful-params` and `ring.middleware.format-response/wrap-restful-response`
     - default supported protocols are: `:json-kw`, `:yaml-kw`, `:edn`, `:transit-json` and `:transit-msgpack`
     - enabled protocol support is also published into Swagger docs via `ring.swagger.middleware/wrap-swagger-data`.
@@ -433,6 +432,38 @@ the `:components` restucturing with letk-syntax.
 
 To see this in action, try `lein run` and navigate to Components api group.
 
+## Exception handling
+
+All exceptions should be handled gracefully. Compojure-api ships with customizable exception handling with good
+defaults. Customization is done via `api` options - delegating to `compojure.api.middleware/wrap-exceptions`, which
+does the real work. It catches all thrown exceptions and selects a custom handler based on the thrown exception
+`ex-data` or Slingshot value of key `:type`. If an exception doesn't have ex-data (e.g. legacy Java Exceptions),
+`:compojure.api.exception/default` type is used. Exception handlers are 3-arity functions, getting the exception,
+ex-data and request as arguments. Below are the default type definitions and default handling:
+
+| type                                          | what                                | default
+|-----------------------------------------------|-------------------------------------|---------
+|`:compojure.api.exception/request-parsing`     | Input data de-serialization errors. | 400 + error in body
+|`:compojure.api.exception/request-validation`  | Request Schema coercion errors.     | 400 + schema error in body
+|`:compojure.api.exception/response-validation` | Response Schema coercion errors.    | 500 + schema error in body
+|`:compojure.api.exception/default`             | Everything else.                    | 500 + print stacktrace + safe message
+
+example to override the default case + add a custom exception type + handler for it:
+
+```clojure
+(defn custom-handler [^Exception e data request]
+  (internal-server-error {:message (.getMessage e)}))
+
+(defn calm-handler [^Exception e data request]
+  (enhance-your-calm {:message (.getMessage e), :data data}))
+
+(defapi
+  {:exceptions {:handlers {:compojure.api.exception/default custom-handler
+                           ::calm calm-handler}}}
+  (GET* "/bang" [] (throw (RuntimeException. "kosh")))
+  (GET* "/calm" [] (throw (ex-info "fail" {:type ::calm, :oil "snake"}))))
+```
+
 ## Schemas
 
 Compojure-api uses the [Schema](https://github.com/Prismatic/schema) to describe data models, backed up by

project.clj

@@ -1,4 +1,4 @@
-(defproject metosin/compojure-api "0.23.0-SNAPSHOT"
+(defproject metosin/compojure-api "0.23.0"
   :description "Compojure Api"
   :url "https://github.com/metosin/compojure-api"
   :license {:name "Eclipse Public License"
@@ -11,8 +11,8 @@
                  [compojure "1.4.0"]
                  [prismatic/schema "0.4.4"]
                  [org.tobereplaced/lettercase "1.0.0"]
-                 [metosin/ring-http-response "0.6.4"]
-                 [metosin/ring-swagger "0.21.0-SNAPSHOT"]
+                 [metosin/ring-http-response "0.6.5"]
+                 [metosin/ring-swagger "0.21.0"]
                  [metosin/schema-tools "0.5.2"]
                  [metosin/ring-middleware-format "0.6.0"]
                  [backtick "0.3.3"]

src/compojure/api/exception.clj

@@ -15,7 +15,7 @@
 
    Error response only contains class of the Exception so that it won't accidentally
    expose secret details."
-  [^Exception e data request]
+  [^Exception e _ _]
   (.printStackTrace e)
   (internal-server-error {:type "unknown-exception"
                           :class (.getName (.getClass e))}))
@@ -33,22 +33,22 @@
 
 (defn response-validation-handler
   "Creates error response based on Schema error."
-  [_ data request]
+  [_ data _]
   (internal-server-error {:errors (stringify-error (su/error-val data))}))
 
 (defn request-validation-handler
   "Creates error response based on Schema error."
-  [_ data request]
+  [_ data _]
   (bad-request {:errors (stringify-error (su/error-val data))}))
 
 (defn schema-error-handler
   "Creates error response based on Schema error."
-  [ex data request]
+  [_ data _]
   ; FIXME: Why error is not wrapped to ErrorContainer here?
   (bad-request {:errors (stringify-error (:error data))}))
 
 (defn request-parsing-handler
-  [^Exception ex data request]
+  [^Exception ex _ _]
   (let [cause (.getCause ex)]
     (bad-request {:type (cond
                           (instance? JsonParseException cause) "json-parse-exception"