githttp-fs 1.5.1

A git-backed content management database served over HTTP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

// githttp-fs
//
// Git-based Content Management System
// Copyright: 2026, Valerian Saliou <valerian@valeriansaliou.name>
// License: Mozilla Public License v2.0 (MPL v2.0)

//! The single application error type and its mapping to HTTP responses.
//!
//! Every fallible function in the codebase returns `Result<_, AppError>`,
//! and `AppError` implements axum's `IntoResponse`. That combination lets
//! handlers be written as plain `?`-propagating functions: any error that
//! bubbles up is automatically converted into a JSON error body with the
//! right status code, in one place, with consistent shape
//! (`{ "error": "<message>" }`).
//!
//! Design notes:
//!
//! - Variants are grouped by *HTTP semantics*, not by origin: "thing does
//!   not exist" variants map to 404, "caller sent something invalid" map to
//!   400, and infrastructure failures (git, io, task join) map to 500.
//! - `InvalidUtf8` gets its own 422: the request was well-formed, but the
//!   stored blob cannot be represented in a JSON string, which is an
//!   entity-level problem rather than a syntax one.
//! - The `#[from]` conversions on `Git` and `Io` are what make `?` work
//!   directly on `git2` and `std::fs` calls throughout `git.rs`.
//! - Only 5xx responses are logged. 4xx responses are the *caller's*
//!   mistake and would just generate noise at error level; the message is
//!   already returned to them in the body.

use axum::{
    http::StatusCode,
    response::{IntoResponse, Response},
    Json,
};
use serde_json::json;

#[derive(Debug, thiserror::Error)]
pub enum AppError {
    #[error("file not found: {path}")]
    FileNotFound { path: String },

    #[error("commit not found: {sha}")]
    CommitNotFound { sha: String },

    #[error("tenant not found: {tenant_id}")]
    TenantNotFound { tenant_id: String },

    #[error("invalid tenant id: {tenant_id}")]
    InvalidTenant { tenant_id: String },

    #[error("invalid path: {reason}")]
    InvalidPath { reason: String },

    #[error("invalid operation: {reason}")]
    InvalidOperation { reason: String },

    #[error("file content is not valid UTF-8 at path: {path}")]
    InvalidUtf8 { path: String },

    #[error("git error: {0}")]
    Git(#[from] git2::Error),

    #[error("io error: {0}")]
    Io(#[from] std::io::Error),

    #[error("background task failed: {0}")]
    TaskFailed(String),
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        // The single source of truth for error → status-code mapping. Adding
        // a new variant forces a decision here (the match is exhaustive).
        let status = match &self {
            AppError::FileNotFound { .. }
            | AppError::CommitNotFound { .. }
            | AppError::TenantNotFound { .. } => StatusCode::NOT_FOUND,

            AppError::InvalidTenant { .. }
            | AppError::InvalidPath { .. }
            | AppError::InvalidOperation { .. } => StatusCode::BAD_REQUEST,

            AppError::InvalidUtf8 { .. } => StatusCode::UNPROCESSABLE_ENTITY,

            AppError::Git(_) | AppError::Io(_) | AppError::TaskFailed(_) => {
                StatusCode::INTERNAL_SERVER_ERROR
            }
        };

        // 5xx means *we* failed — log it so operators see it. 4xx means the
        // caller failed — the message in the response body is enough.
        if status.is_server_error() {
            tracing::error!("server error response: {}", self);
        }

        let body = Json(json!({ "error": self.to_string() }));

        (status, body).into_response()
    }
}