├── README.md └── src └── cognitect └── anomalies.cljc /README.md: -------------------------------------------------------------------------------- 1 | # cognitect.anomalies 2 | 3 | # Rationale 4 | 5 | Anomalies capture errors as information that is simple, actionable, 6 | generic, and extensible. 7 | 8 | * Simple: Anomalies contain only information about the error, not 9 | e.g. flow control or causality. 10 | * Actionable: the `::anom/category` aims to be a top-level 11 | partitioning of all kinds of errors, allowing many programs that need to 12 | branch during error-handling to branch *only* on this keyword. 13 | * Generic: Anomalies are represented as ordinary maps, and can be created 14 | and consumed without any special API. 15 | * Extensible: As maps are open, applications can add their own context 16 | via namespaced keywords. That said, try to do as much as possible 17 | by dispatching only via `::anom/category`. 18 | 19 | Anomalies overlap in purpose with e.g. Java exceptions and HTTP 20 | responses. The differences are instructive: 21 | 22 | Java exceptions are not simple, as they combine error information with 23 | a flow control mechanism. This is a problem in e.g. async applications 24 | and transductions. Both of these contexts need to talk about errors, 25 | but do not want to utilize exceptions' flow control by stack 26 | unwinding. 27 | 28 | HTTP responses provide useful partitioning via status codes. But since 29 | status codes appear inside a server *response* they cannot possibly 30 | cover e.g. failure to get a response at all. 31 | 32 | # The Categories 33 | 34 | The category column contains the name of an anomaly category within 35 | the `cognitect.anomalies` namespace. 36 | 37 | The retry column is "yes" if a replay of the same activity might 38 | reasonably lead to a different outcome. When a program encounters a 39 | retryable anomaly, it may be reasonable to back off and try again. 40 | 41 | The "fix" column provides an example of how a programmer or operator 42 | might fix problems in this category. 43 | 44 | The "song" column contains a Hall and Oates song. The idea that Hall 45 | and Oates are software gurus is controversial in some circles, so you 46 | can treat this as flavortext. 47 | 48 | | category | retryable? | fix | song | 49 | | ---- | ---- | --- | --- | 50 | | :unavailable | yes | make sure callee healthy | Out of Touch | 51 | | :interrupted | maybe | stop interrupting | It Doesn't Matter Anymore | 52 | | :busy | yes | backoff and retry | Wait For Me | 53 | | :incorrect | no | fix caller bug | You'll Never Learn | 54 | | :forbidden | no | fix caller creds | I Can't Go For That | 55 | | :unsupported | no | fix caller verb | Your Imagination | 56 | | :not-found | no | fix caller noun | She's Gone | 57 | | :conflict | no | coordinate with callee | Give It Up | 58 | | :fault | maybe | fix callee bug | Falling | 59 | 60 | # Using cognitect.anomalies 61 | 62 | [Leiningen](https://github.com/technomancy/leiningen) dependency information: 63 | 64 | [com.cognitect/anomalies "0.1.12"] 65 | 66 | [Maven](http://maven.apache.org/) dependency information: 67 | 68 | 69 | com.cognitect 70 | anomalies 71 | 0.1.12 72 | 73 | 74 | # Developer Information 75 | 76 | Please submit feedback via GitHub 77 | [issues](https://github.com/cognitect-labs/anomalies/issues). 78 | 79 | Please do not submit pull requests or patches. 80 | 81 | # Copyright and License 82 | 83 | Copyright (c) Cognitect, Inc. 84 | All rights reserved. 85 | 86 | Licensed under the Apache License, Version 2.0 (the "License"); 87 | you may not use this file except in compliance with the License. 88 | You may obtain a copy of the License at 89 | 90 | http://www.apache.org/licenses/LICENSE-2.0 91 | 92 | Unless required by applicable law or agreed to in writing, software 93 | distributed under the License is distributed on an "AS-IS" BASIS, 94 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 95 | See the License for the specific language governing permissions and 96 | limitations under the License. 97 | 98 | -------------------------------------------------------------------------------- /src/cognitect/anomalies.cljc: -------------------------------------------------------------------------------- 1 | ;; Copyright (c) Cognitect, Inc. 2 | ;; All rights reserved. 3 | 4 | ;; Licensed under the Apache License, Version 2.0 (the "License"); 5 | ;; you may not use this file except in compliance with the License. 6 | ;; You may obtain a copy of the License at 7 | ;; 8 | ;; http://www.apache.org/licenses/LICENSE-2.0 9 | ;; 10 | ;; Unless required by applicable law or agreed to in writing, software 11 | ;; distributed under the License is distributed on an "AS-IS" BASIS, 12 | ;; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | ;; See the License for the specific language governing permissions and 14 | ;; limitations under the License. 15 | 16 | (ns cognitect.anomalies 17 | (:require [clojure.spec.alpha :as s])) 18 | 19 | (s/def ::category #{::unavailable 20 | ::interrupted 21 | ::incorrect 22 | ::forbidden 23 | ::unsupported 24 | ::not-found 25 | ::conflict 26 | ::fault 27 | ::busy}) 28 | (s/def ::message string?) 29 | (s/def ::anomaly (s/keys :req [::category] 30 | :opt [::message])) 31 | 32 | 33 | --------------------------------------------------------------------------------