Fix #5 add more info on conditions

Author: thomasp85

NAMESPACE

@@ -39,6 +39,17 @@ S3method(roxy_tag_parse,roxy_tag_trace)
 export(Break)
 export(Next)
 export(Plumber)
+export(abort_bad_request)
+export(abort_conflict)
+export(abort_forbidden)
+export(abort_gone)
+export(abort_http_problem)
+export(abort_internal_error)
+export(abort_method_not_allowed)
+export(abort_not_acceptable)
+export(abort_not_found)
+export(abort_status)
+export(abort_unauthorized)
 export(api)
 export(api_add_route)
 export(api_any)
@@ -106,6 +117,7 @@ export(parse_rds)
 export(parse_text)
 export(parse_tsv)
 export(parse_yaml)
+export(random_key)
 export(register_parser)
 export(register_serializer)
 export(show_registered_parsers)
@@ -118,6 +130,18 @@ importFrom(jsonlite,write_json)
 importFrom(ragg,agg_jpeg)
 importFrom(ragg,agg_png)
 importFrom(ragg,agg_tiff)
+importFrom(reqres,abort_bad_request)
+importFrom(reqres,abort_conflict)
+importFrom(reqres,abort_forbidden)
+importFrom(reqres,abort_gone)
+importFrom(reqres,abort_http_problem)
+importFrom(reqres,abort_internal_error)
+importFrom(reqres,abort_method_not_allowed)
+importFrom(reqres,abort_not_acceptable)
+importFrom(reqres,abort_not_found)
+importFrom(reqres,abort_status)
+importFrom(reqres,abort_unauthorized)
+importFrom(reqres,random_key)
 importFrom(routr,Route)
 importFrom(routr,RouteStack)
 importFrom(routr,openapi_route)

R/api.R

@@ -129,7 +129,7 @@ is_plumber_api <- function(x) inherits(x, "Plumber")
 api_parse <- function(api, ...) {
   locations <- dots_to_plumber_files(..., prefer_yml = FALSE)
   for (loc in locations) {
-    api$parse_file(file)
+    api$parse_file(loc)
   }
   api
 }

R/api_handlers.R

@@ -180,6 +180,27 @@ handle_constructor <- function(method, header = FALSE) {
 #' be set to the response body (overwritting what was already there) and
 #' handling is then allowed to continue
 #'
+#' ## Handler conditions
+#' Like any function in R, a handler may need to signal that something happened,
+#' either by throwing an error or warning or by emitting a message. You can use
+#' [stop()], [warning()], and [message()] as you are used to. For all of them,
+#' the condition message will end up in the log. Further, for `stop()` any
+#' further handling of the request will end and a `500 Internal Error` response
+#' is returned. To take more control over problems you can use the
+#' [`abort_*()`][abort_status] family of conditions from reqres. Like `stop()`
+#' they will halt any further processing, but they also allow control over what
+#' kind of response is sent back, what kind of information about the issue is
+#' communicated to the client, and what kind of information is logged
+#' internally. The response they send back (except for `abort_status()`) all
+#' adhere to the HTTP Problem spec defined in
+#' [RFC 9457](https://datatracker.ietf.org/doc/html/rfc9457).
+#'
+#' While it may feel like a good idea to send a detailed error message back to
+#' the client it is often better to only inform the client of what they need to
+#' change to solve the issue. Too much information about internal implementation
+#' details can be a security risk and forwarding internal errors to a client can
+#' help inform the client about how the server has been implemented.
+#'
 #' @param api A plumber2 api object to add the handler to
 #' @param path A string giving the path the handler responds to. See Details
 #' @param handler A handler function to call when a request is matched to the

R/api_session_cookie.R

@@ -40,3 +40,7 @@ api_session_cookie <- function(
   )
   api
 }
+
+#' @export
+#' @importFrom reqres random_key
+reqres::random_key

R/conditions.R

@@ -0,0 +1,33 @@
+#' @export
+#' @importFrom reqres abort_status
+reqres::abort_status
+#' @export
+#' @importFrom reqres abort_http_problem
+reqres::abort_http_problem
+#' @export
+#' @importFrom reqres abort_bad_request
+reqres::abort_bad_request
+#' @export
+#' @importFrom reqres abort_conflict
+reqres::abort_conflict
+#' @export
+#' @importFrom reqres abort_forbidden
+reqres::abort_forbidden
+#' @export
+#' @importFrom reqres abort_gone
+reqres::abort_gone
+#' @export
+#' @importFrom reqres abort_internal_error
+reqres::abort_internal_error
+#' @export
+#' @importFrom reqres abort_method_not_allowed
+reqres::abort_method_not_allowed
+#' @export
+#' @importFrom reqres abort_not_acceptable
+reqres::abort_not_acceptable
+#' @export
+#' @importFrom reqres abort_not_found
+reqres::abort_not_found
+#' @export
+#' @importFrom reqres abort_unauthorized
+reqres::abort_unauthorized

man/api_request_handlers.Rd

@@ -7,7 +7,7 @@ function() {
 #* Generate a friendly error
 #* @get /friendly
 function() {
-  reqres::abort_bad_request(
+  abort_bad_request(
     "Your request could not be parsed"
   )
 }

man/reexports.Rd

@@ -5,7 +5,7 @@
 #* @serializer png
 function(query) {
   if (query$pts > 1000 & query$pts < 1){
-    reqres::abort_bad_request("pts must be between 1 and 1,000")
+    abort_bad_request("pts must be between 1 and 1,000")
   }
   plot(1:pts)
 }

vignettes/files/apis/04-05-error.R

@@ -30,7 +30,7 @@ function(request) {
   hm <- digest::hmac(secret, request$body, algo="sha1")
   hm <- paste0("sha1=", hm)
   if (!identical(hm, request$HTTP_X_HUB_SIGNATURE)) {
-    reqres::abort_bad_request("invalid GitHub signature.")
+    abort_bad_request("invalid GitHub signature.")
   }
 
   # Install new package