feat: implement HTTP server with Axum

* add deployment guide

Cargo.lock

···
 ]
 
 [[package]]
+name = "async-trait"
+version = "0.1.89"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9035ad2d096bed7955a320ee7e2230574d28fd3c3a0f186cbea1ff3c7eed5dbb"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
 name = "atomic-waker"
 version = "1.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
···
 checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
 
 [[package]]
+name = "axum"
+version = "0.7.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "edca88bc138befd0323b20752846e6587272d3b03b0343c8ea28a6f819e6e71f"
+dependencies = [
+ "async-trait",
+ "axum-core",
+ "bytes",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-util",
+ "itoa",
+ "matchit",
+ "memchr",
+ "mime",
+ "percent-encoding",
+ "pin-project-lite",
+ "rustversion",
+ "serde",
+ "serde_json",
+ "serde_path_to_error",
+ "serde_urlencoded",
+ "sync_wrapper",
+ "tokio",
+ "tower",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "axum-core"
+version = "0.4.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09f2bd6146b97ae3359fa0cc6d6b376d9539582c7b4220f041a33ec24c226199"
+dependencies = [
+ "async-trait",
+ "bytes",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "mime",
+ "pin-project-lite",
+ "rustversion",
+ "sync_wrapper",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
 name = "base64"
 version = "0.22.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
···
 checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
 
 [[package]]
+name = "httpdate"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
+
+[[package]]
 name = "hyper"
 version = "1.8.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
···
  "http",
  "http-body",
  "httparse",
+ "httpdate",
  "itoa",
  "pin-project-lite",
  "pin-utils",
···
 version = "0.4.28"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "34080505efa8e45a4b816c349525ebe327ceaa8559756f0356cba97ef3bf7432"
+
+[[package]]
+name = "matchit"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0e7465ac9959cc2b1404e8e2367b43684a6d13790fe23056cc8c6c5a6b7bcb94"
 
 [[package]]
 name = "mediatype"
···
 name = "pai"
 version = "0.1.0"
 dependencies = [
+ "axum",
  "chrono",
  "clap",
  "dirs",
  "owo-colors",
  "pai-core",
  "rusqlite",
+ "serde",
  "serde_json",
+ "tokio",
 ]
 
 [[package]]
···
 ]
 
 [[package]]
+name = "serde_path_to_error"
+version = "0.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457"
+dependencies = [
+ "itoa",
+ "serde",
+ "serde_core",
+]
+
+[[package]]
 name = "serde_spanned"
 version = "1.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
···
 checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
 
 [[package]]
+name = "signal-hook-registry"
+version = "1.4.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7664a098b8e616bdfcc2dc0e9ac44eb231eedf41db4e9fe95d8d32ec728dedad"
+dependencies = [
+ "libc",
+]
+
+[[package]]
 name = "siphasher"
 version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
···
  "libc",
  "mio",
  "pin-project-lite",
+ "signal-hook-registry",
  "socket2",
  "tokio-macros",
  "windows-sys 0.61.2",
···
  "tokio",
  "tower-layer",
  "tower-service",
+ "tracing",
 ]
 
 [[package]]
···
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "784e0ac535deb450455cbfa28a6f0df145ea1bb7ae51b821cf5e7927fdcfbdd0"
 dependencies = [
+ "log",
  "pin-project-lite",
  "tracing-core",
 ]

DEPLOYMENT.md

···
+# Personal Activity Index – Deployment Guide
+
+This guide walks through two common reverse proxy setups for `pai serve`: **nginx** and **Caddy**. Both sections include native (host binary) instructions and optional Docker paths if you prefer containerized deployments.
+
+## Prerequisites
+
+1. Build the CLI binary:
+
+   ```sh
+   cargo build --release -p pai
+   ```
+
+   The binary will live at `target/release/pai`.
+
+2. Prepare a configuration + database location. The default locations follow the XDG spec, but you can override them with `-C` (config dir) and `-d` (database path).
+
+3. Run a sync at least once so the database has data:
+
+   ```sh
+   ./target/release/pai sync -C /etc/pai -d /var/lib/pai/pai.db -a
+   ```
+
+4. Start the server (example binds to localhost so the proxy terminates TLS):
+
+   ```sh
+   ./target/release/pai serve -d /var/lib/pai/pai.db -a 127.0.0.1:8080
+   ```
+
+## nginx Deployment
+
+### Host Setup
+
+1. Install nginx via your package manager (`apt`, `dnf`, `brew`, etc.).
+2. Create a systemd service for `pai` (optional but recommended):
+
+   ```ini
+   [Unit]
+   Description=Personal Activity Index
+   After=network.target
+
+   [Service]
+   ExecStart=/usr/local/bin/pai serve -d /var/lib/pai/pai.db -a 127.0.0.1:8080
+   Restart=on-failure
+   User=pai
+   Group=pai
+   WorkingDirectory=/var/lib/pai
+
+   [Install]
+   WantedBy=multi-user.target
+   ```
+
+3. Enable and start it:
+
+   ```sh
+   sudo systemctl daemon-reload
+   sudo systemctl enable --now pai.service
+   ```
+
+### nginx Config
+
+Create `/etc/nginx/conf.d/pai.conf`:
+
+```nginx
+server {
+    listen 80;
+    server_name pai.example.com;
+
+    location / {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+Reload nginx: `sudo nginx -s reload`.
+
+### Optional: nginx via Docker
+
+Use an `nginx` image + bind-mount config:
+
+```yaml
+services:
+  pai:
+    image: ghcr.io/your-namespace/pai:latest
+    command: ["serve", "-d", "/data/pai.db", "-a", "0.0.0.0:8080"]
+    volumes:
+      - ./data:/data
+    expose:
+      - "8080"
+
+  nginx:
+    image: nginx:1.27
+    volumes:
+      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
+    ports:
+      - "80:80"
+    depends_on:
+      - pai
+```
+
+`nginx.conf` should proxy to `http://pai:8080` instead of localhost.
+
+## Caddy Deployment
+
+### Host Setup
+
+1. Install Caddy (<https://caddyserver.com/docs/install>).
+2. Keep the same `pai` systemd service from above (or run manually).
+
+### Caddyfile Example
+
+Create `/etc/caddy/Caddyfile`:
+
+```caddyfile
+pai.example.com {
+    reverse_proxy 127.0.0.1:8080
+    encode gzip zstd
+    header {
+        Referrer-Policy "no-referrer-when-downgrade"
+        X-Content-Type-Options "nosniff"
+    }
+}
+```
+
+Caddy automatically provisions TLS certificates with Let’s Encrypt. Reload with `sudo systemctl reload caddy`.
+
+### Optional: Caddy + Docker Compose
+
+```yaml
+services:
+  pai:
+    image: ghcr.io/your-namespace/pai:latest
+    command: ["serve", "-d", "/data/pai.db", "-a", "0.0.0.0:8080"]
+    volumes:
+      - ./data:/data
+    expose:
+      - "8080"
+
+  caddy:
+    image: caddy:2
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+      - caddy_config:/config
+    ports:
+      - "80:80"
+      - "443:443"
+    depends_on:
+      - pai
+
+volumes:
+  caddy_data:
+  caddy_config:
+```
+
+Use the same `Caddyfile` contents as above, but point `reverse_proxy` to `pai:8080`.
+
+## Health Checks & Monitoring
+
+- `GET /api/feed?limit=1` ensures the server can read from SQLite.
+- `GET /api/item/{id}` is handy for debugging a specific record.
+- Consider adding nginx/Caddy health check endpoints (`/healthz`) that proxy to `/api/feed?limit=1` and monitor via your platform.
+
+## Security Tips
+
+- Bind the `pai serve` process to `127.0.0.1` and let the proxy handle TLS.
+- Run the binary as an unprivileged user with read/write access only to the DB path.
+- Regularly rotate TLS certificates (Caddy does this automatically; for nginx use certbot or similar).

cli/Cargo.toml

···
 dirs = "6.0"
 owo-colors = "4.1"
 serde_json = "1.0"
+serde = { version = "1.0", features = ["derive"] }
+axum = "0.7"
+tokio = { version = "1.40", features = ["macros", "rt-multi-thread", "signal"] }

cli/src/main.rs

···
 mod paths;
+mod server;
 mod storage;
 
 use chrono::{DateTime, Duration, Utc};
···
 
 fn handle_serve(db_path: Option<PathBuf>, address: String) -> Result<(), PaiError> {
     let db_path = paths::resolve_db_path(db_path)?;
-    let _storage = SqliteStorage::new(db_path)?;
-
-    println!("serve command - address: {address}");
-    Ok(())
+    server::serve(db_path, address)
 }
 
 fn handle_db_check(db_path: Option<PathBuf>) -> Result<(), PaiError> {

cli/src/server.rs

···
+use crate::storage::SqliteStorage;
+use crate::{ensure_positive_limit, normalize_optional_string, normalize_since_input};
+use axum::{
+    extract::{Path, Query, State},
+    http::StatusCode,
+    response::{IntoResponse, Response},
+    routing::get,
+    Json, Router,
+};
+use owo_colors::OwoColorize;
+use pai_core::{Item, ListFilter, PaiError, SourceKind};
+use serde::{Deserialize, Serialize};
+use std::{net::SocketAddr, path::PathBuf, sync::Arc};
+use tokio::net::TcpListener;
+
+const DEFAULT_LIMIT: usize = 20;
+
+/// Launches the HTTP server using the provided SQLite database path and address.
+pub(crate) fn serve(db_path: PathBuf, address: String) -> Result<(), PaiError> {
+    let addr: SocketAddr = address
+        .parse()
+        .map_err(|e| PaiError::Config(format!("Invalid listen address '{address}': {e}")))?;
+
+    let runtime = tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .build()
+        .map_err(PaiError::Io)?;
+
+    runtime.block_on(async move { run_server(db_path, addr).await })
+}
+
+async fn run_server(db_path: PathBuf, addr: SocketAddr) -> Result<(), PaiError> {
+    // Ensure the database exists and schema is ready before serving requests.
+    let storage = SqliteStorage::new(&db_path)?;
+    storage.verify_schema()?;
+    drop(storage);
+
+    let state = AppState { db_path: Arc::new(db_path) };
+
+    let app = Router::new()
+        .route("/api/feed", get(feed_handler))
+        .route("/api/item/:id", get(item_handler))
+        .with_state(state);
+
+    let listener = TcpListener::bind(addr).await.map_err(PaiError::Io)?;
+    let local_addr = listener.local_addr().map_err(PaiError::Io)?;
+    println!("{} Listening on http://{}", "Info:".cyan(), local_addr);
+
+    axum::serve(listener, app.into_make_service())
+        .with_graceful_shutdown(shutdown_signal())
+        .await
+        .map_err(|err| PaiError::Io(std::io::Error::new(std::io::ErrorKind::Other, err)))
+}
+
+#[derive(Clone)]
+struct AppState {
+    db_path: Arc<PathBuf>,
+}
+
+impl AppState {
+    fn open_storage(&self) -> Result<SqliteStorage, PaiError> {
+        SqliteStorage::new(self.db_path.as_ref())
+    }
+}
+
+#[derive(Debug, Default, Deserialize)]
+struct FeedQuery {
+    source_kind: Option<SourceKind>,
+    source_id: Option<String>,
+    limit: Option<usize>,
+    since: Option<String>,
+    q: Option<String>,
+}
+
+impl FeedQuery {
+    fn into_filter(self) -> Result<ListFilter, PaiError> {
+        let limit = match self.limit {
+            Some(value) => ensure_positive_limit(value)?,
+            None => DEFAULT_LIMIT,
+        };
+
+        Ok(ListFilter {
+            source_kind: self.source_kind,
+            source_id: normalize_optional_string(self.source_id),
+            limit: Some(limit),
+            since: normalize_since_input(self.since)?,
+            query: normalize_optional_string(self.q),
+        })
+    }
+}
+
+#[derive(Serialize)]
+struct FeedResponse {
+    count: usize,
+    items: Vec<Item>,
+}
+
+async fn feed_handler(
+    State(state): State<AppState>, Query(query): Query<FeedQuery>,
+) -> Result<Json<FeedResponse>, ApiError> {
+    let filter = query.into_filter()?;
+    let storage = state.open_storage()?;
+    let items = pai_core::Storage::list_items(&storage, &filter)?;
+
+    Ok(Json(FeedResponse { count: items.len(), items }))
+}
+
+async fn item_handler(State(state): State<AppState>, Path(id): Path<String>) -> Result<Json<Item>, ApiError> {
+    let storage = state.open_storage()?;
+    let item = storage
+        .get_item(&id)?
+        .ok_or_else(|| ApiError::not_found(format!("Item '{id}' not found")))?;
+
+    Ok(Json(item))
+}
+
+struct ApiError {
+    status: StatusCode,
+    message: String,
+}
+
+impl ApiError {
+    fn bad_request(msg: impl Into<String>) -> Self {
+        Self { status: StatusCode::BAD_REQUEST, message: msg.into() }
+    }
+
+    fn not_found(msg: impl Into<String>) -> Self {
+        Self { status: StatusCode::NOT_FOUND, message: msg.into() }
+    }
+
+    fn internal(msg: impl Into<String>) -> Self {
+        Self { status: StatusCode::INTERNAL_SERVER_ERROR, message: msg.into() }
+    }
+}
+
+impl From<PaiError> for ApiError {
+    fn from(err: PaiError) -> Self {
+        match err {
+            PaiError::InvalidArgument(msg) => Self::bad_request(msg),
+            other => Self::internal(other.to_string()),
+        }
+    }
+}
+
+#[derive(Serialize)]
+struct ErrorBody {
+    error: String,
+}
+
+impl IntoResponse for ApiError {
+    fn into_response(self) -> Response {
+        (self.status, Json(ErrorBody { error: self.message })).into_response()
+    }
+}
+
+async fn shutdown_signal() {
+    let _ = tokio::signal::ctrl_c().await;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn feed_query_defaults() {
+        let filter = FeedQuery::default().into_filter().unwrap();
+        assert_eq!(filter.limit, Some(DEFAULT_LIMIT));
+        assert!(filter.source_kind.is_none());
+        assert!(filter.source_id.is_none());
+    }
+
+    #[test]
+    fn feed_query_respects_parameters() {
+        let query = FeedQuery {
+            source_kind: Some(SourceKind::Bluesky),
+            source_id: Some(" desertthunder.dev ".to_string()),
+            limit: Some(5),
+            since: Some("2024-01-01T00:00:00Z".to_string()),
+            q: Some(" rust ".to_string()),
+        };
+
+        let filter = query.into_filter().unwrap();
+        assert_eq!(filter.limit, Some(5));
+        assert_eq!(filter.source_kind, Some(SourceKind::Bluesky));
+        assert_eq!(filter.source_id.unwrap(), "desertthunder.dev");
+        assert_eq!(filter.query.unwrap(), "rust");
+        assert_eq!(filter.since.unwrap(), "2024-01-01T00:00:00+00:00");
+    }
+
+    #[test]
+    fn feed_query_rejects_zero_limit() {
+        let err = FeedQuery { limit: Some(0), ..Default::default() }
+            .into_filter()
+            .unwrap_err();
+        assert!(matches!(err, PaiError::InvalidArgument(_)));
+    }
+
+    #[test]
+    fn api_error_into_response_sets_status() {
+        let resp = ApiError::bad_request("oops").into_response();
+        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
+    }
+}

cli/src/storage/sqlite.rs

···
 
         Ok(())
     }
+
+    /// Fetches a single item by ID, if it exists
+    pub fn get_item(&self, id: &str) -> Result<Option<Item>> {
+        let mut stmt = self
+            .conn
+            .prepare(
+                "SELECT id, source_kind, source_id, author, title, summary, url, content_html, published_at, created_at
+             FROM items WHERE id = ?1 LIMIT 1",
+            )
+            .map_err(|e| PaiError::Storage(format!("Failed to prepare get_item query: {e}")))?;
+
+        stmt.query_row([id], |row| {
+            let source_kind_str: String = row.get(1)?;
+            let source_kind = source_kind_str
+                .parse::<SourceKind>()
+                .map_err(|e| rusqlite::Error::FromSqlConversionFailure(1, rusqlite::types::Type::Text, Box::new(e)))?;
+
+            Ok(Item {
+                id: row.get(0)?,
+                source_kind,
+                source_id: row.get(2)?,
+                author: row.get(3)?,
+                title: row.get(4)?,
+                summary: row.get(5)?,
+                url: row.get(6)?,
+                content_html: row.get(7)?,
+                published_at: row.get(8)?,
+                created_at: row.get(9)?,
+            })
+        })
+        .optional()
+        .map_err(|e| PaiError::Storage(format!("Failed to fetch item by id: {e}")))
+    }
 }
 
 impl Storage for SqliteStorage {
···
 
         let count = storage.count_items().expect("Failed to count items");
         assert_eq!(count, 3);
+    }
+
+    #[test]
+    fn get_item_returns_record() {
+        let storage = create_test_storage();
+        let item = create_test_item("test-1", SourceKind::Substack, "test.substack.com");
+        storage.insert_or_replace_item(&item).expect("Failed to insert");
+
+        let fetched = storage.get_item("test-1").expect("query failed").unwrap();
+        assert_eq!(fetched.id, "test-1");
+        assert_eq!(fetched.source_kind, SourceKind::Substack);
+    }
+
+    #[test]
+    fn get_item_returns_none_for_missing() {
+        let storage = create_test_storage();
+        let result = storage.get_item("nope").expect("query failed");
+        assert!(result.is_none());
     }
 }