From 4e3d5ccac99b24934c972e088cd7eb02bb95df06 Mon Sep 17 00:00:00 2001
From: Owen Jacobson <owen@grimoire.ca>
Date: Tue, 17 Jun 2025 02:11:45 -0400
Subject: Handlers are _named operations_, which can be exposed via routes.

Each domain module that exposes handlers does so through a `handlers` child module, ideally as a top-level symbol that can be plugged directly into Axum's `MethodRouter`. Modules could make exceptions to this - kill the doctrinaire inside yourself, after all - but none of the API modules that actually exist need such exceptions, and consistency is useful.

The related details of request types, URL types, response types, errors, &c &c are then organized into modules under `handlers`, along with their respective tests.
---
 src/setup/handlers/mod.rs        |  3 ++
 src/setup/handlers/setup/mod.rs  | 55 ++++++++++++++++++++++++
 src/setup/handlers/setup/test.rs | 93 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 151 insertions(+)
 create mode 100644 src/setup/handlers/mod.rs
 create mode 100644 src/setup/handlers/setup/mod.rs
 create mode 100644 src/setup/handlers/setup/test.rs

(limited to 'src/setup/handlers')

diff --git a/src/setup/handlers/mod.rs b/src/setup/handlers/mod.rs
new file mode 100644
index 0000000..3d4a4e6
--- /dev/null
+++ b/src/setup/handlers/mod.rs
@@ -0,0 +1,3 @@
+mod setup;
+
+pub use setup::handler as setup;
diff --git a/src/setup/handlers/setup/mod.rs b/src/setup/handlers/setup/mod.rs
new file mode 100644
index 0000000..cbb3072
--- /dev/null
+++ b/src/setup/handlers/setup/mod.rs
@@ -0,0 +1,55 @@
+use axum::{
+    extract::{Json, State},
+    http::StatusCode,
+    response::{IntoResponse, Response},
+};
+
+use crate::{
+    app::App,
+    clock::RequestedAt,
+    error::Internal,
+    name::Name,
+    setup::app,
+    token::extract::IdentityCookie,
+    user::{Password, User},
+};
+
+#[cfg(test)]
+mod test;
+
+pub async fn handler(
+    State(app): State<App>,
+    RequestedAt(setup_at): RequestedAt,
+    identity: IdentityCookie,
+    Json(request): Json<Request>,
+) -> Result<(IdentityCookie, Json<User>), Error> {
+    let (user, secret) = app
+        .setup()
+        .initial(&request.name, &request.password, &setup_at)
+        .await
+        .map_err(Error)?;
+    let identity = identity.set(secret);
+    Ok((identity, Json(user)))
+}
+
+#[derive(serde::Deserialize)]
+pub struct Request {
+    pub name: Name,
+    pub password: Password,
+}
+
+#[derive(Debug)]
+pub struct Error(pub app::Error);
+
+impl IntoResponse for Error {
+    fn into_response(self) -> Response {
+        let Self(error) = self;
+        match error {
+            app::Error::InvalidName(_) => {
+                (StatusCode::BAD_REQUEST, error.to_string()).into_response()
+            }
+            app::Error::SetupCompleted => (StatusCode::CONFLICT, error.to_string()).into_response(),
+            other => Internal::from(other).into_response(),
+        }
+    }
+}
diff --git a/src/setup/handlers/setup/test.rs b/src/setup/handlers/setup/test.rs
new file mode 100644
index 0000000..8243ac3
--- /dev/null
+++ b/src/setup/handlers/setup/test.rs
@@ -0,0 +1,93 @@
+use axum::extract::{Json, State};
+
+use crate::{setup::app, test::fixtures};
+
+#[tokio::test]
+async fn fresh_instance() {
+    // Set up the environment
+
+    let app = fixtures::scratch_app().await;
+
+    // Call the endpoint
+    let identity = fixtures::cookie::not_logged_in();
+    let (name, password) = fixtures::user::propose();
+    let request = super::Request {
+        name: name.clone(),
+        password: password.clone(),
+    };
+    let (identity, Json(response)) =
+        super::handler(State(app.clone()), fixtures::now(), identity, Json(request))
+            .await
+            .expect("setup in a fresh app succeeds");
+
+    // Verify the response
+
+    assert_eq!(name, response.name);
+
+    // Verify that the issued token is valid
+
+    let secret = identity
+        .secret()
+        .expect("newly-issued identity has a token secret");
+    let (_, login) = app
+        .tokens()
+        .validate(&secret, &fixtures::now())
+        .await
+        .expect("newly-issued identity cookie is valid");
+    assert_eq!(response, login);
+
+    // Verify that the given credentials can log in
+
+    let (login, _) = app
+        .tokens()
+        .login(&name, &password, &fixtures::now())
+        .await
+        .expect("credentials given on signup are valid");
+    assert_eq!(response, login);
+}
+
+#[tokio::test]
+async fn login_exists() {
+    // Set up the environment
+
+    let app = fixtures::scratch_app().await;
+    fixtures::user::create(&app, &fixtures::now()).await;
+
+    // Call the endpoint
+    let identity = fixtures::cookie::not_logged_in();
+    let (name, password) = fixtures::user::propose();
+    let request = super::Request { name, password };
+    let super::Error(error) =
+        super::handler(State(app.clone()), fixtures::now(), identity, Json(request))
+            .await
+            .expect_err("setup in a populated app fails");
+
+    // Verify the response
+
+    assert!(matches!(error, app::Error::SetupCompleted));
+}
+
+#[tokio::test]
+async fn invalid_name() {
+    // Set up the environment
+
+    let app = fixtures::scratch_app().await;
+
+    // Call the endpoint
+
+    let name = fixtures::user::propose_invalid_name();
+    let password = fixtures::user::propose_password();
+    let identity = fixtures::cookie::not_logged_in();
+    let request = super::Request {
+        name: name.clone(),
+        password: password.clone(),
+    };
+    let super::Error(error) =
+        super::handler(State(app.clone()), fixtures::now(), identity, Json(request))
+            .await
+            .expect_err("setup with an invalid name fails");
+
+    // Verify the response
+
+    assert!(matches!(error, app::Error::InvalidName(error_name) if name == error_name));
+}
-- 
cgit v1.2.3