about summary refs log tree commit diff
path: root/src/response.rs
diff options
context:
space:
mode:
authorAlexander_Kabui <alexanderkabua@gmail.com>2026-10-03 20:25:37 +0300
committerAlexander_Kabui <alexanderkabua@gmail.com>2026-10-03 20:25:37 +0300
commitfd0d45b98ec1136aeb84fc28fa647df9023abf75 (patch)
tree05748707d319deb9668a194a90c3724a69c4f328 /src/response.rs
parent5ecc6b70e8a6ce2ba91f7808295a7d7672481d58 (diff)
downloadgenenetwork4-fd0d45b98ec1136aeb84fc28fa647df9023abf75.tar.gz
Add foundation structure: config layering, response envelope, routes modules.
* src/config.rs: New module. Layered configuration,
  defaults -> GN4_CONF -> GN4_SECRETS -> environment, mirroring
  GeneNetwork3's SQL_URI convention so the two services can share
  configuration. Missing config files are ignored.
* src/response.rs: New module. The descriptive success envelope
  (data + next actions) from the foundation design note
  (topics/gn4/gn4-api-foundation.gmi). Not yet adopted by existing
  endpoints; that is a deliberate wire-format change to agree on
  before it ships.
* src/routes/mod.rs, species.rs, groups.rs: Move the species and
  groups handlers out of lib.rs into one module per domain, per the
  foundation structure. Handlers are pub; lib.rs just registers them.
* src/lib.rs (app): Register the moved routes. hello_world and
  version predate the domain split and stay as top-level utility
  routes.
* src/db.rs (sql_uri): Resolve through config::Config instead of
  reading the environment directly.
* src/main.rs: Bind the port from config::Config.
Diffstat (limited to 'src/response.rs')
-rw-r--r--src/response.rs68
1 files changed, 68 insertions, 0 deletions
diff --git a/src/response.rs b/src/response.rs
new file mode 100644
index 0000000..55dea57
--- /dev/null
+++ b/src/response.rs
@@ -0,0 +1,68 @@
+//! The one descriptive success envelope, per the foundation design
+//! note (topics/gn4/gn4-api-foundation.gmi): every success response
+//! carries its data plus the next actions a caller (human or LLM) can
+//! take. Errors carry suggestions via the shared ApiError shape in
+//! error.rs. Never ad-hoc JSON per endpoint.
+//!
+//! Existing endpoints still return their bare payloads; migrating them
+//! onto Envelope is a deliberate wire-format change to agree on the
+//! thread before it ships.
+
+use serde::Serialize;
+
+/// A success response: the payload plus suggested follow-up calls.
+#[derive(Serialize)]
+pub struct Envelope<T: Serialize> {
+    pub data: T,
+    pub next: Vec<NextAction>,
+}
+
+/// One suggested follow-up call.
+#[derive(Serialize)]
+pub struct NextAction {
+    /// Endpoint to call, e.g. "/species/mouse".
+    pub href: String,
+    /// What this call gives you, e.g. "Drill down into one species".
+    pub description: String,
+}
+
+impl<T: Serialize> Envelope<T> {
+    pub fn of(data: T) -> Self {
+        Envelope { data, next: Vec::new() }
+    }
+
+    pub fn with_next(mut self, href: &str, description: &str) -> Self {
+        self.next.push(NextAction {
+            href: href.to_string(),
+            description: description.to_string(),
+        });
+        self
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn envelope_serializes_data_and_next_actions() {
+        let envelope = Envelope::of(vec!["mouse", "rat"])
+            .with_next("/species/mouse", "Drill down into one species");
+        let json = serde_json::to_value(&envelope).unwrap();
+        assert_eq!(
+            json["data"],
+            serde_json::json!(["mouse", "rat"])
+        );
+        assert_eq!(json["next"][0]["href"], "/species/mouse");
+        assert_eq!(
+            json["next"][0]["description"],
+            "Drill down into one species"
+        );
+    }
+
+    #[test]
+    fn envelope_can_carry_no_actions() {
+        let json = serde_json::to_value(Envelope::of(42)).unwrap();
+        assert_eq!(json["next"], serde_json::json!([]));
+    }
+}