techbro 0.0.0-stage → 0.5.0

package/templates/_default/apps/backend/src/error.rs

@@ -0,0 +1,115 @@
+use axum::{
+    Json,
+    http::StatusCode,
+    response::{IntoResponse, Response},
+};
+use serde::Serialize;
+use serde_json::json;
+
+/// Request id stored in request extensions and in a task-local for error bodies.
+#[derive(Debug, Clone)]
+pub struct RequestId(pub String);
+
+tokio::task_local! {
+    pub static CURRENT_REQUEST_ID: String;
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct FieldError {
+    pub field: String,
+    pub message: String,
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum AppError {
+    #[error("not found")]
+    NotFound,
+    #[error("validation failed: {message}")]
+    Validation {
+        message: String,
+        details: Vec<FieldError>,
+    },
+    #[error("database error: {0}")]
+    Database(#[from] sqlx::Error),
+    #[error("internal error: {0}")]
+    Internal(String),
+    #[error("service unavailable")]
+    Unavailable,
+    #[error("draining")]
+    Draining,
+}
+
+impl AppError {
+    pub fn validation(field: &str, message: &str) -> Self {
+        Self::Validation {
+            message: "Invalid input".into(),
+            details: vec![FieldError {
+                field: field.into(),
+                message: message.into(),
+            }],
+        }
+    }
+}
+
+impl IntoResponse for AppError {
+    fn into_response(self) -> Response {
+        let (status, code, message, details) = match &self {
+            AppError::NotFound => (
+                StatusCode::NOT_FOUND,
+                "NOT_FOUND",
+                "Resource not found".to_string(),
+                None,
+            ),
+            AppError::Validation { message, details } => (
+                StatusCode::BAD_REQUEST,
+                "VALIDATION_ERROR",
+                message.clone(),
+                Some(details.clone()),
+            ),
+            AppError::Draining => (
+                StatusCode::SERVICE_UNAVAILABLE,
+                "DRAINING",
+                "Server is shutting down".to_string(),
+                None,
+            ),
+            AppError::Unavailable => (
+                StatusCode::SERVICE_UNAVAILABLE,
+                "SERVICE_UNAVAILABLE",
+                "Service not ready".to_string(),
+                None,
+            ),
+            AppError::Database(e) => {
+                tracing::error!(error = %e, "database error");
+                (
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    "INTERNAL_ERROR",
+                    "Internal server error".to_string(),
+                    None,
+                )
+            }
+            AppError::Internal(e) => {
+                tracing::error!(error = %e, "internal error");
+                (
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    "INTERNAL_ERROR",
+                    "Internal server error".to_string(),
+                    None,
+                )
+            }
+        };
+        let request_id = CURRENT_REQUEST_ID
+            .try_with(Clone::clone)
+            .unwrap_or_default();
+        let mut error = json!({ "code": code, "message": message });
+        if let Some(d) = details
+            && !d.is_empty()
+        {
+            error["details"] = json!(d);
+        }
+        (
+            status,
+            Json(json!({ "error": error, "requestId": request_id })),
+        )
+            .into_response()
+    }
+}

package/templates/_default/apps/backend/src/lib.rs

@@ -0,0 +1,7 @@
+pub mod config;
+pub mod controllers;
+pub mod error;
+pub mod models;
+pub mod routes;
+pub mod state;
+pub mod views;

package/templates/_default/apps/backend/src/main.rs

@@ -0,0 +1,71 @@
+use std::{
+    error::Error,
+    sync::{
+        Arc,
+        atomic::{AtomicBool, Ordering},
+    },
+    time::Duration,
+};
+
+use backend::{config::Config, routes, state::AppState};
+use sqlx::any::AnyPoolOptions;
+use tracing_subscriber::EnvFilter;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    dotenvy::dotenv().ok();
+    let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info"));
+    tracing_subscriber::fmt()
+        .json()
+        .with_env_filter(filter)
+        .with_current_span(true)
+        .with_span_list(false)
+        .init();
+
+    let config = Config::from_env()?;
+    sqlx::any::install_default_drivers();
+    let pool = AnyPoolOptions::new()
+        .max_connections(5)
+        .connect(&config.database_url)
+        .await?;
+
+    let addr = format!("0.0.0.0:{}", config.port);
+    let app_name = config.app_name.clone();
+    let drain = Duration::from_secs(config.shutdown_drain_seconds);
+    let draining = Arc::new(AtomicBool::new(false));
+    let app = routes::router(AppState {
+        pool: pool.clone(),
+        config: Arc::new(config),
+        draining: draining.clone(),
+    });
+    let listener = tokio::net::TcpListener::bind(&addr).await?;
+    tracing::info!(app = %app_name, %addr, "server listening");
+    axum::serve(listener, app)
+        .with_graceful_shutdown(shutdown_signal(draining, drain))
+        .await?;
+    pool.close().await;
+    tracing::info!("shutdown complete");
+    Ok(())
+}
+
+/// Flags the server as draining so /ready fails, then waits before the listener closes.
+async fn shutdown_signal(draining: Arc<AtomicBool>, drain: Duration) {
+    let ctrl_c = async {
+        let _ = tokio::signal::ctrl_c().await;
+    };
+    #[cfg(unix)]
+    let term = async {
+        match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) {
+            Ok(mut s) => {
+                s.recv().await;
+            }
+            Err(_) => std::future::pending::<()>().await,
+        }
+    };
+    #[cfg(not(unix))]
+    let term = std::future::pending::<()>();
+    tokio::select! { _ = ctrl_c => {}, _ = term => {} }
+    tracing::info!("shutdown signal received, draining");
+    draining.store(true, Ordering::SeqCst);
+    tokio::time::sleep(drain).await;
+}

package/templates/_default/apps/backend/src/models/item.rs

@@ -0,0 +1,94 @@
+use serde::Serialize;
+use sqlx::{AnyPool, FromRow};
+
+use crate::error::AppError;
+
+const MAX_NAME_LEN: usize = 200;
+
+#[derive(Debug, Clone, Serialize, FromRow)]
+#[serde(rename_all = "camelCase")]
+pub struct Item {
+    pub id: i64,
+    pub name: String,
+    pub created_at: String,
+}
+
+/// Returns the trimmed name, or a validation error.
+pub fn validate_name(raw: &str) -> Result<String, AppError> {
+    let name = raw.trim();
+    if name.is_empty() {
+        return Err(AppError::validation("name", "Must not be empty"));
+    }
+    if name.chars().count() > MAX_NAME_LEN {
+        return Err(AppError::validation(
+            "name",
+            "Must be at most 200 characters",
+        ));
+    }
+    Ok(name.to_string())
+}
+
+// CAST keeps created_at decodable as text on both SQLite and PostgreSQL.
+macro_rules! columns {
+    () => {
+        "id, name, CAST(created_at AS TEXT) AS created_at"
+    };
+}
+
+pub async fn list(
+    pool: &AnyPool,
+    limit: i64,
+    offset: i64,
+) -> Result<(Vec<Item>, i64), sqlx::Error> {
+    let items = sqlx::query_as::<_, Item>(concat!(
+        "SELECT ",
+        columns!(),
+        " FROM items ORDER BY id LIMIT $1 OFFSET $2"
+    ))
+    .bind(limit)
+    .bind(offset)
+    .fetch_all(pool)
+    .await?;
+    let total = sqlx::query_scalar::<_, i64>("SELECT COUNT(*) FROM items")
+        .fetch_one(pool)
+        .await?;
+    Ok((items, total))
+}
+
+pub async fn create(pool: &AnyPool, name: &str) -> Result<Item, sqlx::Error> {
+    sqlx::query_as::<_, Item>(concat!(
+        "INSERT INTO items (name) VALUES ($1) RETURNING ",
+        columns!()
+    ))
+    .bind(name)
+    .fetch_one(pool)
+    .await
+}
+
+pub async fn find(pool: &AnyPool, id: i64) -> Result<Option<Item>, sqlx::Error> {
+    sqlx::query_as::<_, Item>(concat!("SELECT ", columns!(), " FROM items WHERE id = $1"))
+        .bind(id)
+        .fetch_optional(pool)
+        .await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::validate_name;
+
+    #[test]
+    fn trims_valid_name() {
+        assert_eq!(validate_name("  box ").unwrap(), "box");
+    }
+
+    #[test]
+    fn rejects_blank_name() {
+        assert!(validate_name("   ").is_err());
+    }
+
+    #[test]
+    fn rejects_long_name() {
+        assert!(validate_name(&"a".repeat(201)).is_err());
+        assert!(validate_name(&"a".repeat(200)).is_ok());
+    }
+}

package/templates/_default/apps/backend/src/models/mod.rs

@@ -0,0 +1 @@
+pub mod item;

package/templates/_default/apps/backend/src/routes.rs

@@ -0,0 +1,94 @@
+use axum::{
+    Router,
+    extract::Request,
+    http::{HeaderName, HeaderValue, Method, header},
+    middleware::{self, Next},
+    response::Response,
+    routing::get,
+};
+use tower_http::{cors::CorsLayer, trace::TraceLayer};
+
+use crate::{
+    controllers::{health, items},
+    error::{CURRENT_REQUEST_ID, RequestId},
+    state::AppState,
+};
+
+const REQUEST_ID_HEADER: &str = "x-request-id";
+const TRACE_ID_HEADER: &str = "x-trace-id";
+
+#[derive(Clone)]
+struct TraceId(String);
+
+async fn trace_id(mut req: Request, next: Next) -> Response {
+    let id = req
+        .headers()
+        .get(TRACE_ID_HEADER)
+        .and_then(|v| v.to_str().ok())
+        .filter(|v| uuid::Uuid::parse_str(v).is_ok())
+        .map(str::to_string)
+        .unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
+    req.extensions_mut().insert(TraceId(id.clone()));
+    let mut res = next.run(req).await;
+    if let Ok(value) = HeaderValue::from_str(&id) {
+        res.headers_mut()
+            .insert(HeaderName::from_static(TRACE_ID_HEADER), value);
+    }
+    res
+}
+
+async fn request_id(mut req: Request, next: Next) -> Response {
+    let id = req
+        .headers()
+        .get(REQUEST_ID_HEADER)
+        .and_then(|v| v.to_str().ok())
+        .filter(|v| !v.is_empty() && v.len() <= 128)
+        .map(str::to_string)
+        .unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
+    req.extensions_mut().insert(RequestId(id.clone()));
+    let mut res = CURRENT_REQUEST_ID.scope(id.clone(), next.run(req)).await;
+    if let Ok(v) = HeaderValue::from_str(&id) {
+        res.headers_mut()
+            .insert(HeaderName::from_static(REQUEST_ID_HEADER), v);
+    }
+    res
+}
+
+pub fn router(state: AppState) -> Router {
+    let cors = CorsLayer::new()
+        .allow_origin(state.config.cors_allowed_origins.clone())
+        .allow_methods([Method::GET, Method::POST])
+        .allow_headers([
+            header::CONTENT_TYPE,
+            HeaderName::from_static(REQUEST_ID_HEADER),
+            HeaderName::from_static(TRACE_ID_HEADER),
+        ])
+        .expose_headers([HeaderName::from_static(TRACE_ID_HEADER)]);
+    let app_name = state.config.app_name.clone();
+    let trace = TraceLayer::new_for_http().make_span_with(move |req: &Request| {
+        let rid = req
+            .extensions()
+            .get::<RequestId>()
+            .map(|r| r.0.as_str())
+            .unwrap_or("");
+        tracing::info_span!(
+            "request",
+            app = %app_name,
+            method = %req.method(),
+            path = %req.uri().path(),
+            request_id = %rid,
+            trace_id = %req.extensions().get::<TraceId>().map(|id| id.0.as_str()).unwrap_or(""),
+        )
+    });
+
+    Router::new()
+        .route("/health", get(health::health))
+        .route("/ready", get(health::ready))
+        .route("/api/v1/items", get(items::list).post(items::create))
+        .route("/api/v1/items/{id}", get(items::get))
+        .with_state(state)
+        .layer(trace)
+        .layer(middleware::from_fn(request_id))
+        .layer(cors)
+        .layer(middleware::from_fn(trace_id))
+}

package/templates/_default/apps/backend/src/state.rs

@@ -0,0 +1,12 @@
+use std::sync::{Arc, atomic::AtomicBool};
+
+use sqlx::AnyPool;
+
+use crate::config::Config;
+
+#[derive(Clone)]
+pub struct AppState {
+    pub pool: AnyPool,
+    pub config: Arc<Config>,
+    pub draining: Arc<AtomicBool>,
+}

package/templates/_default/apps/backend/src/views/items.rs

@@ -0,0 +1,18 @@
+use serde::Serialize;
+
+use crate::models::item::Item;
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Pagination {
+    pub page: i64,
+    pub per_page: i64,
+    pub total: i64,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ItemListResponse {
+    pub items: Vec<Item>,
+    pub pagination: Pagination,
+}

package/templates/_default/apps/backend/src/views/mod.rs

@@ -0,0 +1 @@
+pub mod items;

package/templates/_default/apps/backend/tests/api.rs

@@ -0,0 +1,234 @@
+use std::sync::{
+    Arc,
+    atomic::{AtomicBool, Ordering},
+};
+
+use axum::{
+    Router,
+    body::Body,
+    http::{Request, StatusCode, header},
+};
+use backend::{config::Config, routes, state::AppState};
+use http_body_util::BodyExt;
+use serde_json::{Value, json};
+use sqlx::any::AnyPoolOptions;
+use tower::ServiceExt;
+
+async fn app() -> Router {
+    app_with_flag().await.0
+}
+
+async fn app_with_flag() -> (Router, Arc<AtomicBool>) {
+    sqlx::any::install_default_drivers();
+    let pool = AnyPoolOptions::new()
+        .max_connections(1)
+        .connect("sqlite::memory:")
+        .await
+        .expect("connect sqlite");
+    sqlx::raw_sql(include_str!(
+        "../../../database/migrations/sqlite/20261008120000_create_items.sql"
+    ))
+    .execute(&pool)
+    .await
+    .expect("apply migration");
+    let config = Config {
+        app_name: "test".into(),
+        port: 0,
+        database_url: "sqlite::memory:".into(),
+        cors_allowed_origins: vec!["http://localhost:5173".parse().expect("origin")],
+        shutdown_drain_seconds: 0,
+    };
+    let draining = Arc::new(AtomicBool::new(false));
+    let router = routes::router(AppState {
+        pool,
+        config: Arc::new(config),
+        draining: draining.clone(),
+    });
+    (router, draining)
+}
+
+async fn send(app: &Router, req: Request<Body>) -> (StatusCode, Value) {
+    let res = app.clone().oneshot(req).await.expect("response");
+    let status = res.status();
+    let bytes = res.into_body().collect().await.expect("body").to_bytes();
+    (
+        status,
+        serde_json::from_slice(&bytes).unwrap_or(Value::Null),
+    )
+}
+
+fn get(uri: &str) -> Request<Body> {
+    Request::get(uri).body(Body::empty()).expect("request")
+}
+
+const TRACE_ID: &str = "5d632031-f1ac-4a8f-8837-b4b2bef63596";
+
+#[tokio::test]
+async fn trace_id_echo_generation_and_errors() {
+    let app = app().await;
+    for (path, supplied) in [
+        ("/health", Some(TRACE_ID)),
+        ("/health", None),
+        ("/health", Some("not-a-uuid")),
+        ("/api/v1/items/999", Some(TRACE_ID)),
+        ("/unknown", Some(TRACE_ID)),
+        ("/api/v1/items/not-an-integer", Some(TRACE_ID)),
+    ] {
+        let mut req = Request::get(path).header("x-request-id", "existing-request");
+        if let Some(id) = supplied {
+            req = req.header("x-trace-id", id);
+        }
+        let res = app
+            .clone()
+            .oneshot(req.body(Body::empty()).expect("request"))
+            .await
+            .expect("response");
+        let trace = res
+            .headers()
+            .get("x-trace-id")
+            .expect("trace header")
+            .to_str()
+            .expect("header text");
+        assert!(uuid::Uuid::parse_str(trace).is_ok());
+        if supplied == Some(TRACE_ID) {
+            assert_eq!(trace, TRACE_ID);
+        }
+        assert_eq!(res.headers()["x-request-id"], "existing-request");
+        if path == "/api/v1/items/999" {
+            let bytes = res.into_body().collect().await.expect("body").to_bytes();
+            let body: Value = serde_json::from_slice(&bytes).expect("json");
+            assert_eq!(body["requestId"], "existing-request");
+            assert!(body.get("traceId").is_none());
+        }
+    }
+}
+
+#[tokio::test]
+async fn cors_allows_and_exposes_trace_only_for_configured_origins() {
+    let app = app().await;
+    for origin in ["http://localhost:5173", "https://untrusted.example"] {
+        let res = app
+            .clone()
+            .oneshot(
+                Request::builder()
+                    .method("OPTIONS")
+                    .uri("/health")
+                    .header("origin", origin)
+                    .header("access-control-request-method", "GET")
+                    .header(
+                        "access-control-request-headers",
+                        "x-trace-id,x-request-id,content-type",
+                    )
+                    .body(Body::empty())
+                    .expect("request"),
+            )
+            .await
+            .expect("response");
+        assert!(
+            res.headers()["access-control-allow-headers"]
+                .to_str()
+                .expect("headers")
+                .contains("x-trace-id")
+        );
+        assert_eq!(
+            res.headers().get("access-control-allow-origin").is_some(),
+            origin == "http://localhost:5173"
+        );
+        assert!(res.headers().contains_key("x-trace-id"));
+    }
+    let res = app
+        .oneshot(
+            Request::get("/health")
+                .header("origin", "http://localhost:5173")
+                .body(Body::empty())
+                .expect("request"),
+        )
+        .await
+        .expect("response");
+    assert!(
+        res.headers()["access-control-expose-headers"]
+            .to_str()
+            .expect("headers")
+            .contains("x-trace-id")
+    );
+    assert!(
+        !res.headers()
+            .contains_key("access-control-allow-credentials")
+    );
+}
+
+fn post(uri: &str, body: Value) -> Request<Body> {
+    Request::post(uri)
+        .header(header::CONTENT_TYPE, "application/json")
+        .body(Body::from(body.to_string()))
+        .expect("request")
+}
+
+#[tokio::test]
+async fn health_and_ready() {
+    let app = app().await;
+    let (s, b) = send(&app, get("/health")).await;
+    assert_eq!((s, b["status"].as_str()), (StatusCode::OK, Some("ok")));
+    let (s, _) = send(&app, get("/ready")).await;
+    assert_eq!(s, StatusCode::OK);
+}
+
+#[tokio::test]
+async fn create_then_list_and_get() {
+    let app = app().await;
+    let (s, created) = send(&app, post("/api/v1/items", json!({"name": " widget "}))).await;
+    assert_eq!(s, StatusCode::CREATED);
+    assert_eq!(created["name"], "widget");
+    assert!(created["createdAt"].is_string());
+
+    let (s, list) = send(&app, get("/api/v1/items")).await;
+    assert_eq!(s, StatusCode::OK);
+    assert_eq!(list["items"].as_array().map(Vec::len), Some(1));
+    assert_eq!(list["pagination"]["page"], 1);
+    assert_eq!(list["pagination"]["perPage"], 20);
+    assert_eq!(list["pagination"]["total"], 1);
+
+    let uri = format!("/api/v1/items/{}", created["id"]);
+    let (s, one) = send(&app, get(&uri)).await;
+    assert_eq!(s, StatusCode::OK);
+    assert_eq!(one["name"], "widget");
+}
+
+#[tokio::test]
+async fn missing_item_is_404_with_error_shape() {
+    let app = app().await;
+    let (s, b) = send(&app, get("/api/v1/items/999")).await;
+    assert_eq!(s, StatusCode::NOT_FOUND);
+    assert_eq!(b["error"]["code"], "NOT_FOUND");
+    assert!(b["requestId"].as_str().is_some_and(|r| !r.is_empty()));
+}
+
+#[tokio::test]
+async fn blank_name_is_validation_error() {
+    let app = app().await;
+    let (s, b) = send(&app, post("/api/v1/items", json!({"name": "  "}))).await;
+    assert_eq!(s, StatusCode::BAD_REQUEST);
+    assert_eq!(b["error"]["code"], "VALIDATION_ERROR");
+    assert_eq!(b["error"]["details"][0]["field"], "name");
+    assert!(b["requestId"].is_string());
+}
+
+#[tokio::test]
+async fn per_page_over_max_is_rejected() {
+    let app = app().await;
+    let (s, b) = send(&app, get("/api/v1/items?perPage=101")).await;
+    assert_eq!(s, StatusCode::BAD_REQUEST);
+    assert_eq!(b["error"]["code"], "VALIDATION_ERROR");
+}
+
+#[tokio::test]
+async fn ready_is_503_when_draining() {
+    let (app, flag) = app_with_flag().await;
+    flag.store(true, Ordering::SeqCst);
+    let (s, b) = send(&app, get("/ready")).await;
+    assert_eq!(s, StatusCode::SERVICE_UNAVAILABLE);
+    assert_eq!(b["error"]["code"], "DRAINING");
+    let (s, b) = send(&app, get("/health")).await;
+    assert_eq!(s, StatusCode::OK);
+    assert!(b["version"].is_string() && b["build"].is_string());
+}

package/templates/_default/apps/frontend/.env.example

@@ -0,0 +1,2 @@
+VITE_API_BASE_URL=
+VITE_APP_NAME=

package/templates/_default/apps/frontend/.prettierignore

@@ -0,0 +1,3 @@
+dist
+node_modules
+package-lock.json

package/templates/_default/apps/frontend/.prettierrc

@@ -0,0 +1 @@
+{ "semi": true, "singleQuote": false, "trailingComma": "all", "printWidth": 100 }

package/templates/_default/apps/frontend/Dockerfile

@@ -0,0 +1,15 @@
+FROM node:22-alpine AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+ARG VITE_API_BASE_URL=""
+ARG VITE_APP_NAME=""
+ENV VITE_API_BASE_URL=$VITE_API_BASE_URL \
+    VITE_APP_NAME=$VITE_APP_NAME
+RUN npm run build
+
+FROM nginxinc/nginx-unprivileged:stable-alpine
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /app/dist /usr/share/nginx/html
+EXPOSE 8080