Hero Website Framework

Modular Rust library for building embedded website applications with Unix socket support

A lightweight, reusable library that extracts common website patterns from production deployments (like www_coop_cloud) into a modular framework. Build websites faster by focusing on templates, routes, and business logic while the framework handles server setup, socket binding, and request routing.

Project Structure

hero_website_framework/
├── crates/
│   ├── hero_website_lib/       # Core library (reusable)
│   │   └── src/
│   │       ├── lib.rs          # Public API
│   │       ├── server.rs       # WebsiteServer trait & implementation
│   │       ├── state.rs        # State management traits
│   │       ├── response.rs     # Response helpers
│   │       └── socket.rs       # Unix socket utilities
│   │
│   └── (future) other shared crates
│
├── examples/
│   └── simple_website/         # Minimal example showing library usage
│       └── src/main.rs
│
├── Makefile                    # Build targets
├── buildenv.sh                 # Build configuration
├── scripts/
│   └── build_lib.sh            # Build system library
│
└── README.md (this file)

Key Design Principles

1. Modularity

• Library (hero_website_lib): Provides core abstractions
• Websites: Each website is a separate binary that implements WebsiteServer trait
• Separation of Concerns: Server logic, routing, templates, and business logic are clearly separated

2. Unix Sockets

• All services bind to Unix domain sockets (no TCP ports)
• Standard socket directory: $HOME/.hero/var/sockets/
• Socket naming convention: {service_name}.sock
• Automatic cleanup of stale socket files

3. Trait-Based Extension

• Implement the WebsiteServer trait to create your website
• Provide custom state by implementing WebsiteState
• Full control over router building and request handling

4. Embedded Assets

• Templates, static files, and content are embedded in the binary using rust-embed
• Single binary deployments with no external dependencies

Core Components

WebsiteServer Trait

Your main interface for creating a website:

pub trait WebsiteServer: Send + Sync {
    /// Build the Axum router with all routes
    fn build_router(&self) -> Router;

    /// Get the service name (used for socket path)
    fn service_name(&self) -> &str;

    /// Optional: custom socket directory
    fn socket_dir(&self) -> Option<PathBuf> { None }

    /// Start the server on Unix socket
    async fn run(&self) -> std::io::Result<()>;
}

WebsiteState Trait

For managing shared application state:

pub trait WebsiteState: Send + Sync {
    fn templates(&self) -> &Tera;
    fn site_info(&self) -> serde_json::Value;
}

Socket Management

Automatic Unix socket binding with:

• Directory creation if needed
• Stale socket removal
• Standard path resolution
• Health check socket support

Creating a Website

Step 1: Define Your State

#[derive(Clone)]
struct MyWebsiteState {
    templates: Tera,
    // Your custom fields
    config: MyConfig,
    db: Arc<Database>,
}

Step 2: Create Route Handlers

async fn index(State(state): State<Arc<MyWebsiteState>>) -> Html<String> {
    let ctx = tera::Context::new();
    let html = state.templates.render("index.html", &ctx).unwrap();
    Html(html)
}

Step 3: Implement WebsiteServer

struct MyWebsite {
    state: Arc<MyWebsiteState>,
}

impl WebsiteServer for MyWebsite {
    fn build_router(&self) -> Router {
        Router::new()
            .route("/", get(index))
            .route("/about", get(about))
            .with_state(self.state.clone())
    }

    fn service_name(&self) -> &str { "my_website" }
}

Step 4: Run It

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let website = MyWebsite::new(/* ... */);
    website.run().await
}

Building and Testing

Development

make check        # Fast code check
make test         # Run unit tests
make build        # Build release binaries

Examples

make run-example  # Shows how to run the example website
./target/release/examples/simple_website  # Run example

Full Workflow

make all          # clean + check + test + build

Extending the Framework

The framework provides hooks for common patterns:

Custom Response Types

Add new response helpers in response.rs:

pub struct MyResponse(pub MyData);
impl IntoResponse for MyResponse { /* ... */ }

Template Helpers

Create filter functions and macros in your website:

templates.register_filter("my_filter", my_filter_fn);

Middleware

Add middleware to routes:

.route("/admin", admin_page)
.layer(middleware::from_fn(auth_middleware))

Database Integration

Add database layer to your state:

pub struct WebsiteState {
    templates: Tera,
    db: Arc<MyDatabase>,
}

Comparison with www_coop_cloud

This framework extracts from the www_coop_cloud architecture:

Aspect	www_coop_cloud	framework	benefit
Server	Single binary (monolithic)	Library + website binaries	Reusable across projects
Socket	TCP port	Unix socket	Better isolation, no port conflicts
State	Concrete AppState	WebsiteState trait	Customizable per website
Templates	Embedded (fixed)	Your choice	Flexibility
Code	All in src/	Modular crates	Better organization

Future Enhancements

Planned additions to the library:

• Built-in authentication middleware
• Form validation helpers
• Database transaction utilities
• Asset pipeline helpers
• OpenRPC integration for JSON-RPC endpoints
• Admin dashboard scaffolding
• Health check endpoints
• Metrics/tracing integration

License

MIT OR Apache-2.0