Project Overview: silenloc's Rust Workspace

A collection of Rust-based web applications, tools, and libraries built with modern async patterns.

Directory Structure

/home/silen/
├── catch/              # Hurl testing extension with JavaScript runtime
├── chtm/               # Minimal HTTP server
├── chtmx/              # ClickHouse + HTMX integration server
├── corium/             # WASM-based file-as-endpoint system
├── ff/                 # File finder utility
├── fig/                # Git server with web UI
├── hsetup/             # Home server setup configuration
├── migs/               # SQL migration macros for Rust
├── server-ui-template/ # Template for Actix-web + Maud projects
├── spruce/             # Deployment/build tool
├── wishlist/           # Book/documentation project
└── what_I_did_with_rust/  # Typst demo (current directory)

Major Projects

1. fig - Git Server with Web UI

Purpose: Self-hosted Git backend with HTTP support and web interface

Key Features:

Git HTTP backend (clone, fetch, push)
Web UI for browsing repositories, namespaces, and commits
User authentication with Argon2 password hashing
Session-based and API key authentication
Markdown and Typst rendering support

Architecture:

fig/
├── src/
│   ├── main.rs           # Actix-web server setup
│   ├── config.rs         # Environment configuration
│   ├── assets.rs         # Static asset serving
│   ├── auth/             # Authentication handlers
│   │   ├── mod.rs
│   │   └── handlers.rs
│   ├── db/               # Database layer (libsql/SQLite)
│   │   ├── mod.rs
│   │   ├── users.rs
│   │   ├── tokens.rs
│   │   ├── tickets.rs
│   │   ├── namespaces.rs
│   │   └── migration.rs
│   ├── git/              # Git operations
│   │   ├── mod.rs
│   │   ├── repo.rs
│   │   └── bare.rs
│   ├── git_backend.rs    # Git HTTP backend
│   ├── typst_render.rs   # Typst document rendering
│   └── view/             # Web UI handlers
│       ├── mod.rs
│       ├── auth.rs
│       ├── namespace.rs
│       ├── repo.rs
│       ├── overview.rs
│       ├── settings.rs
│       └── session_auth.rs
├── assets/               # Static files
├── tests/                # Hurl acceptance tests
├── docs/                 # Documentation
├── Cargo.toml
└── Dockerfile

Key Dependencies:

[dependencies]
actix-web = "4"
git2 = "0.18"           # Git operations
maud = "0.27.0"         # HTML templating
turso = "0.5.3"         # SQLite/libsql client
argon2 = "0.5"          # Password hashing
pulldown-cmark = "0.12" # Markdown parsing

Code Example - Main Server:

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let config = config::from_env();
    env_logger::Builder::from_env(
        Env::default().default_filter_or(config.log_level())
    ).init();

    let auth_state = auth::AuthState::new(&db_path, api_key).await?;
    
    HttpServer::new(move || {
        App::new()
            .app_data(config.clone())
            .app_data(auth_state.clone())
            .service(health)
            .service(assets::assets)
            // Git endpoints with auth
            .service(git::repo::init)
            .route("/{namespace}/{repo}/{endpoint:.*}",
                web::get().guard(is_git()).to(git::git_handler))
    })
    .bind(bind_address)?
    .run()
    .await
}

Authentication Flow:

Admin generates signup ticket (requires API Key)
User creates account with ticket (single-use)
User logs in → session cookie set
User can create namespaces and repositories
Git operations use Basic Auth

2. catch - Hurl Testing Extension

Purpose: Extension to Hurl testing tool with JavaScript runtime support

Key Features:

Run JavaScript scripts in Hurl test context
Key-value store for test results
Proxy mode to record HTTP calls as Hurl files
File storage for test artifacts

Architecture:

catch/
├── src/
│   ├── main.rs           # Server entry point
│   ├── config.rs         # Configuration
│   ├── health.rs         # Health check endpoints
│   ├── assets.rs         # Static assets
│   ├── proxy.rs          # HTTP proxy functionality
│   ├── script.rs         # JavaScript runtime
│   ├── kv_store.rs       # Key-value storage
│   ├── file_store.rs     # File storage
│   ├── test_endpoint.rs  # Test endpoints
│   ├── runtime/          # Runtime modules
│   │   ├── mod.rs
│   │   ├── shell.rs
│   │   └── javascript.rs
│   └── view/             # UI components
│       ├── mod.rs
│       ├── key_value.rs
│       ├── file_store.rs
│       ├── script.rs
│       ├── proxy/
│       └── components/
├── assets/               # Static files (JS, CSS, logos)
├── tests/                # Hurl test files
└── Cargo.toml

Key Dependencies:

[dependencies]
actix-web = "4"
ion = { git = "https://github.com/alshdavid/ion.git" }  # JavaScript runtime
maud = { version = "0.27.0", features = ["actix-web"] }
awc = { version = "3", features = ["rustls"] }        # HTTP client

3. chtmx - ClickHouse + HTMX Server

Purpose: HTTP server integrating ClickHouse database with HTMX frontend

Key Features:

ClickHouse database integration
CSV import/export
HTMX-based dynamic UI
Multipart file upload support

Dependencies:

[dependencies]
actix-web = "4"
clickhouse = "0.12.2"
csv = "1.4.0"
maud = { version = "0.27.0", features = ["actix-web"] }

4. migs - SQL Migration Macros

Purpose: Compile-time SQL migration registration for Rust

Key Features:

Compile-time SQL script registration via macros
File and inline SQL support
Scoped organization (init, seed, migrate)
Zero runtime overhead using inventory crate

Usage Example:

use migs::{migs, collect, Migs};

// Register SQL from file
migs!(path = "migrations/001_init.sql");
migs!(path = "migrations/002_seed.sql", scope = "seed");

// Register inline SQL
migs!(sql = "CREATE TABLE users (id INT PRIMARY KEY, name TEXT)");

// Collect all registered scripts
let scripts: Vec<&Migs> = collect!();

Structure:

migs/
├── src/
│   └── lib.rs
├── migs-macro/          # Procedural macro crate
│   └── src/
├── tests/
└── Cargo.toml

5. corium - WASM File-as-Endpoint

Purpose: Define HTTP endpoints by writing code files that get compiled to WASM

Concept: Users write code files which are compiled to WASM and served as endpoints

Structure:

corium/
├── src/
│   └── main.rs
├── assets/
└── Cargo.toml

6. hsetup - Home Server Setup

Purpose: Infrastructure-as-code for home server deployment

Contents:

Docker Compose configurations
Caddy reverse proxy config
Application deployment configs

hsetup/
├── Caddyfile              # Reverse proxy configuration
├── docker-compose.yml     # Main compose file
├── docker.just           # Docker helper recipes
├── justfile              # Task runner
├── apps/                 # Application configs
├── certs/                # SSL certificates
└── ezbookkeeping/        # Specific app config

Common Patterns

Web Framework: Actix-web + Maud

All web projects use the same stack:

use actix_web::{App, HttpServer, get, web, Responder};
use maud::html;

#[get("/")]
async fn index() -> impl Responder {
    html! {
        html {
            head {
                title { "Hello" }
            }
            body {
                h1 { "Hello World" }
            }
        }
    }
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| {
        App::new()
            .service(index)
    })
    .bind("0.0.0.0:8080")?
    .run()
    .await
}

Configuration Pattern

// From fig/src/config.rs
pub struct Server {
    address: (String, u16),
    log_level: String,
    project_root: String,
    db_path: String,
    api_key: String,
}

pub fn from_env() -> Server {
    let port = std::env::var("PORT")
        .unwrap_or_else(|_| "80".to_string())
        .parse()
        .unwrap_or(80);
    let log_level = std::env::var("LOG_LEVEL")
        .unwrap_or_else(|_| "info".to_string());
    // ...
}

Build Tool: just

All projects use just as the task runner:

# From fig/justfile
run:
    cargo run

fmt:
    cargo fmt
    cargo clippy --fix --allow-dirty

verify:
    cargo fmt -- --check
    cargo check
    cargo clippy
    cargo test
    just hurl test

docker-build:
    docker build -t fig:latest .

Technology Stack Summary

Component	Technology
Language	Rust (Edition 2024)
Web Framework	Actix-web
Templating	Maud (compile-time HTML)
Database	SQLite/libsql (via turso), ClickHouse
Git Operations	git2 crate
JavaScript Runtime	ion (V8-based)
Testing	Hurl, cargo test
Task Runner	just
Containerization	Docker
Reverse Proxy	Caddy

Testing Strategy

Hurl Tests

Hurl tests are used for HTTP API testing:

# Example: tests/health.hurl
GET http://localhost:8080/health
HTTP 200

Run with: just hurl test

Unit Tests

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_something() {
        assert_eq!(1 + 1, 2);
    }
}

Deployment

Docker

All major projects include Docker support:

# From fig/Dockerfile
FROM rust:1.85 AS builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y git ca-certificates
COPY --from=builder /app/target/release/fig /usr/local/bin/
EXPOSE 8080
CMD ["fig"]

Environment Variables

Common pattern across projects:

Variable	Default	Description
`PORT`	8080	Server port
`LOG_LEVEL`	info	Logging verbosity
`DB_PATH`	-	Database file path
`API_KEY`	generated	API authentication
`PROJECT_ROOT`	/srv/git	Git repositories root

Code Style

Import Ordering

use std::path::Path;

use actix_web::{HttpRequest, get, web};
use serde::Deserialize;

use crate::{config, git};

Naming Conventions

Structs/Enums: PascalCase (GitRequest, Server)
Functions/Variables: snake_case (get_commits, project_root)
Constants: SCREAMING_SNAKE_CASE (TCSS, HTMX)
Modules: snake_case (repo.rs, bare.rs)

Summary

This workspace represents a cohesive ecosystem of Rust web applications:

fig - Git server (most complex, full-featured)
catch - Testing tool with JS runtime
chtmx - Database integration server
migs - Migration macros library
corium - WASM endpoint experiments
hsetup - Infrastructure/deployment configs

All projects share:

Modern Rust (2024 edition)
Async/await patterns with Tokio
Actix-web framework
Maud templating
Just task runner
Docker deployment
Hurl testing

Markdown Files

Project Overview: silenloc's Rust Workspace

Directory Structure

Major Projects

1. fig - Git Server with Web UI

2. catch - Hurl Testing Extension

3. chtmx - ClickHouse + HTMX Server

4. migs - SQL Migration Macros

5. corium - WASM File-as-Endpoint

6. hsetup - Home Server Setup

Common Patterns

Web Framework: Actix-web + Maud

Configuration Pattern

Build Tool: just

Technology Stack Summary

Testing Strategy

Hurl Tests

Unit Tests

Deployment

Docker

Environment Variables

Code Style

Import Ordering

Naming Conventions

Summary