From c38d877b94c6ac5df2de4c9c939ae683d733e8b8 Mon Sep 17 00:00:00 2001 From: Owen Jacobson Date: Mon, 23 Jun 2025 22:45:18 -0400 Subject: Organize the developer docs into a "Pilcrow for Developers" book. The audience for this is developers looking to make changes to Pilcrow, either on the server, on the included client, or via its data model. Most of the material here is drawn from existing documents, but organized somewhat more coherently. I've left some space for client documentation, though no such documents exist yet. --- docs/developer/server/errors.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 docs/developer/server/errors.md (limited to 'docs/developer/server/errors.md') diff --git a/docs/developer/server/errors.md b/docs/developer/server/errors.md new file mode 100644 index 0000000..e5cdafb --- /dev/null +++ b/docs/developer/server/errors.md @@ -0,0 +1,9 @@ +# Errors + +In general, errors are reported back up as Rust values with full Rust semantics, and are converted to HTTP errors at the last moment (generally via `IntoResponse` implementations on internal error types). + +## Errors and HTTP responses + +Handlers must make sure that the errors returned to clients over HTTP do not leak information about the server unintentionally. For example, errors due to misconfigured permissions should not cause Pilcrow to start informing clients of the specific filesystem path Pilcrow is configured to look for its database at: that information is not useful to most users, and may be used to attack the service or mislead the operator. To that end, handlers, middleware, response types, and other HTTP-facing components are very explicit about what errors correspond to what responses. + +The fallback option, universally, is `crate::error::Internal`, which captures the underlying error and forwards it to standard error, but does not pass it along to HTTP clients. Every intended error is also part of Pilcrow's API documentation. -- cgit v1.2.3