Initial importv0.1.0

1 files changed, 73 insertions, 0 deletions

diff --git a/R/conditions.R b/R/conditions.R
new file mode 100644
index 0000000..1eebe5b
--- /dev/null
+++ b/R/conditions.R
@@ -0,0 +1,73 @@
+#' Conditions signalled by cepis
+#'
+#' @description
+#' Every failure raised by this package is a classed condition inheriting
+#' from `cepis_error`, so one handler catches all of them:
+#'
+#' ```r
+#' tryCatch(
+#'   cep_lookup(cep_from_form),
+#'   cepis_not_found = function(e) NULL,
+#'   cepis_error = function(e) reschedule()
+#' )
+#' ```
+#'
+#' Below `cepis_error` the split is by **the decision you have to make**, not
+#' by the HTTP status that caused it:
+#'
+#' | class | when | does retrying help? |
+#' | --- | --- | --- |
+#' | `cepis_invalid_cep` | not 8 digits | no |
+#' | `cepis_not_found` | well-formed, not in the database | no |
+#' | `cepis_rate_limited` | 429 | yes, later |
+#' | `cepis_server_error` | 5xx | yes, later |
+#' | `cepis_network_error` | DNS, connection, timeout, TLS | yes, later |
+#' | `cepis_invalid_response` | unintelligible response | probably not |
+#'
+#' That split is why `cepis_not_found` is not "the HTTP 404 condition": it is
+#' also signalled with no request made at all, when the CEP is malformed
+#' before it ever leaves the machine.
+#'
+#' Each condition carries the fields a caller needs to act on it:
+#' `cepis_rate_limited` has `retry_after` (seconds the server asked for, or
+#' `NULL`), `cepis_server_error` has `status`, `cepis_network_error` has
+#' `url`, and `cepis_invalid_cep` has `value`, the input as it arrived.
+#'
+#' `cepis_invalid_response` almost always means something between you and the
+#' API is answering instead of it — a captive Wi-Fi portal, a corporate
+#' proxy, an HTML error page. Useful as a diagnosis: the problem is not in
+#' your code.
+#'
+#' @name cepis_conditions
+NULL
+
+cepis_condition <- function(class, message, ...) {
+  structure(
+    list(message = message, call = NULL, ...),
+    class = c(class, "cepis_error", "error", "condition")
+  )
+}
+
+invalid_cep_error <- function(message, value = NULL) {
+  cepis_condition("cepis_invalid_cep", message, value = value)
+}
+
+not_found_error <- function(message, cep = NULL) {
+  cepis_condition("cepis_not_found", message, cep = cep)
+}
+
+rate_limited_error <- function(message, retry_after = NULL) {
+  cepis_condition("cepis_rate_limited", message, retry_after = retry_after)
+}
+
+server_error <- function(message, status) {
+  cepis_condition("cepis_server_error", message, status = status)
+}
+
+network_error <- function(message, url) {
+  cepis_condition("cepis_network_error", message, url = url)
+}
+
+invalid_response_error <- function(message) {
+  cepis_condition("cepis_invalid_response", message)
+}