Developer Documentation

Welcome to the Rusty Beam developer documentation. This section provides in-depth technical information for developers who want to understand, extend, or contribute to Rusty Beam.

🚀 Getting Started

New to Rusty Beam development? Start with the Architecture Overview to understand the system design, then move on to the Plugin Development Guide to build your first plugin.

Architecture

Deep dive into Rusty Beam's architecture, including:

Core design principles
Request processing pipeline
Plugin system internals
Memory model and concurrency
Security architecture

Essential reading for understanding how Rusty Beam works under the hood.

Plugin Development

Complete guide to creating Rusty Beam plugins:

Quick start tutorial
Plugin trait API reference
Request and response handling
State management patterns
Testing strategies
Real-world examples

Everything you need to extend Rusty Beam with custom functionality.

Core Concepts

The Plugin Pipeline

Rusty Beam processes every request through a configurable pipeline of plugins. Each plugin can:

Inspect and modify the request
Generate a response (short-circuiting the pipeline)
Pass the request to the next plugin
Modify responses on the way back

Async-First Design

Built on Tokio and Hyper, Rusty Beam is fully asynchronous. All I/O operations are non-blocking, enabling high concurrency with low resource usage.

HTML as Configuration

Following the DOM-Aware Server philosophy, even server configuration is HTML. This enables:

Self-documenting configuration
Configuration queryable via the same selector API
Visual configuration editors
Version control friendly format

Development Setup

Prerequisites

# Install Rust (latest stable)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone the repository
git clone https://github.com/jamesaduncan/rusty-beam.git
cd rusty-beam

# Build the project
cargo build --release

# Build all plugins
./build-plugins.sh

Running Tests

# Run all tests
./run_all_tests.sh

# Run specific test suites
cargo test                      # Unit tests
./run_hurl_tests.sh            # Integration tests
./run_plugin_tests_isolated.sh # Plugin tests

Contributing

Code Style

Follow Rust standard style (enforced by cargo fmt)
Use cargo clippy to catch common mistakes
Write tests for new functionality
Document public APIs with doc comments

Pull Request Process

Fork the repository and create a feature branch
Make your changes with appropriate tests
Ensure all tests pass: ./run_all_tests.sh
Update documentation if needed
Submit a pull request with a clear description

Advanced Topics

Performance Optimization

Profile with cargo flamegraph
Use criterion for benchmarking
Minimize allocations in hot paths
Leverage async parallelism

Security Considerations

All file paths must be canonicalized
Input validation is mandatory
Use secure defaults
Follow OWASP guidelines

Resources

Internal Documentation

Schema Reference - All configuration schemas
Plugin Documentation - Built-in plugins
Main Documentation - User guide and vision