Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
587 lines (451 loc) · 15.8 KB

ARCHITECTURE.md

File metadata and controls

587 lines (451 loc) · 15.8 KB

Bazzounquester Architecture

Status: v1.8.0 - Production-Ready Modular Architecture

Executive Summary

Bazzounquester has evolved from a simple HTTP CLI tool into a comprehensive API testing platform with Postman-level capabilities. This document describes the current architecture, design decisions, and modular structure.

🏗️ Architecture Overview

Design Principles

  1. Modularity - Clean separation of concerns with focused modules
  2. Testability - Every module has comprehensive unit tests (280+ total)
  3. Extensibility - Easy to add new features without breaking existing code
  4. Performance - Rust's zero-cost abstractions for maximum speed
  5. User Experience - Beautiful terminal output, intuitive API

Key Metrics (v1.8.0)

  • 280+ Unit Tests - Comprehensive test coverage
  • 13+ Modules - Clean separation of concerns
  • 8,000+ Lines of Code - Production-ready implementation
  • ~85% Test Coverage - High-quality codebase
  • Zero Dependencies on Unsafe Code - Memory-safe Rust

📦 Module Structure

Current Architecture (v1.8.0)

src/
├── main.rs              # CLI entry point & REPL
├── lib.rs               # Public library exports
│
├── http/                # Core HTTP functionality
│   ├── mod.rs           # Module exports
│   ├── client.rs        # HTTP client (reqwest wrapper)
│   ├── request.rs       # Request builder pattern
│   ├── response.rs      # Response handling & formatting
│   └── method.rs        # HTTP method enum
│
├── auth/                # Authentication modules
│   ├── mod.rs           # Auth system exports
│   ├── basic.rs         # Basic authentication (RFC 7617)
│   ├── bearer.rs        # Bearer token authentication
│   ├── apikey.rs        # API key (header/query)
│   └── oauth2.rs        # OAuth 2.0 (5 grant types)
│
├── upload/              # File upload system
│   ├── mod.rs           # Upload module exports
│   ├── file.rs          # FileUpload with MIME detection
│   ├── form.rs          # FormData builder
│   └── multipart.rs     # Multipart request builder
│
├── scripts/             # Scripting engine
│   ├── mod.rs           # Script system exports
│   ├── script.rs        # Script definition (pre/post)
│   ├── engine.rs        # Rhai execution engine
│   └── context.rs       # Script execution context
│
├── assertions/          # Validation framework
│   ├── mod.rs           # Assertion exports
│   ├── assertion.rs     # Assertion definition
│   ├── matcher.rs       # 14 matcher types
│   └── validator.rs     # Response validation
│
├── workflow/            # Request chaining
│   ├── mod.rs           # Workflow exports
│   ├── step.rs          # WorkflowStep builder
│   ├── chain.rs         # RequestChain container
│   ├── executor.rs      # Workflow execution engine
│   └── variables.rs     # Variable substitution
│
├── collections/         # Collections & workspaces
│   ├── mod.rs           # Collection exports
│   ├── collection.rs    # Request collection
│   ├── workspace.rs     # Workspace management
│   └── storage.rs       # Persistence layer
│
├── env/                 # Environment management
│   ├── mod.rs           # Environment exports
│   ├── environment.rs   # Environment variables
│   ├── manager.rs       # Multi-env management
│   └── substitutor.rs   # Variable substitution
│
├── session/             # Session & cookie handling
│   ├── mod.rs           # Session exports
│   ├── session.rs       # Session management
│   └── cookies.rs       # Cookie jar (cookie_store)
│
└── history/             # Request history
    ├── mod.rs           # History exports
    ├── manager.rs       # History storage
    ├── entry.rs         # History entry
    └── logger.rs        # Request/response logging

🔧 Core Components

1. HTTP Module (src/http/)

Purpose: Core HTTP client functionality

Key Types:

  • HttpClient - Wrapper around reqwest::blocking::Client
  • RequestBuilder - Fluent API for building requests
  • HttpResponse - Response container with timing
  • HttpMethod - Enum for all HTTP methods

Design Decisions:

  • Blocking API for simplicity (async planned for v2.0)
  • Builder pattern for intuitive request construction
  • Automatic JSON pretty-printing
  • Response timing built-in

Example:

let client = HttpClient::new();
let request = RequestBuilder::new(HttpMethod::Get, "https://api.example.com")
    .header("Authorization", "Bearer token")
    .query("page", "1")
    .build()?;
let response = client.execute(request)?;

2. Authentication Module (src/auth/)

Purpose: Support all major authentication methods

Implementations:

Basic Authentication (basic.rs)

  • RFC 7617 compliant
  • Base64 encoding
  • Username/password pairs

Bearer Token (bearer.rs)

  • JWT token support
  • Simple token wrapper
  • Header injection

API Key (apikey.rs)

  • Header-based: X-API-Key: secret
  • Query-based: ?api_key=secret
  • Custom key names

OAuth 2.0 (oauth2.rs)

Five grant types:

  1. Authorization Code - Web app flow
  2. Implicit - Client-side apps (deprecated but supported)
  3. Password - Resource owner credentials
  4. Client Credentials - Machine-to-machine
  5. Refresh Token - Token renewal

Design Decisions:

  • Trait-based design for extensibility
  • Each auth type is independent
  • Easy integration with RequestBuilder

3. File Upload Module (src/upload/)

Purpose: Multipart form data and file uploads

Key Types:

  • FileUpload - Single file representation
  • FormData - Form builder (fields + files)
  • MultipartBuilder - Constructs multipart requests

Features:

  • Automatic MIME type detection (mime_guess)
  • Custom filename support
  • File size validation
  • Mixed text fields and file uploads

Example:

let file = FileUpload::new("./document.pdf", "file")?;
let mut form = FormData::new();
form.add_field("title", "Document");
form.add_file(file)?;
let multipart = form.build()?;

4. Scripting Module (src/scripts/)

Purpose: Pre/post-request automation with JavaScript-like scripts

Key Types:

  • Script - Script definition (code + type)
  • ScriptEngine - Rhai execution engine
  • ScriptContext - Variable storage + console output

Features:

  • Pre-request scripts (setup, dynamic data)
  • Post-request scripts (extraction, validation)
  • Console logging
  • Variable get/set
  • Response access in post-scripts

Available in Scripts:

  • variables.get(name) / variables.set(name, value)
  • response.status, response.body, response.time
  • console.log(message)
  • JSON parsing/stringifying
  • Math operations

Example:

let script = Script::post(r#"
    let data = JSON.parse(response.body);
    variables.set("token", data.auth.token);
    console.log("Token extracted: " + data.auth.token);
"#);

let mut engine = ScriptEngine::new();
engine.execute(&script, &mut context)?;

5. Assertions Module (src/assertions/)

Purpose: Response validation and testing

Key Types:

  • Assertion - Single assertion (field + matcher)
  • Matcher - Comparison logic (14 types)
  • ResponseValidator - Runs assertions against responses

Supported Matchers:

  1. Equals / NotEquals - Exact matching
  2. Contains / NotContains - Substring search
  3. StartsWith / EndsWith - Prefix/suffix
  4. Regex - Pattern matching
  5. LessThan / LessThanOrEqual - Numeric < / <=
  6. GreaterThan / GreaterThanOrEqual - Numeric > / >=
  7. IsEmpty / IsNotEmpty - Empty string check
  8. HasLength - Exact length
  9. IsNull / IsNotNull - Null checks

Example:

let assertions = vec![
    Assertion::new("$.status", Matcher::new(MatcherType::Equals, "200")),
    Assertion::new("$.data.email", Matcher::new(MatcherType::Contains, "@")),
    Assertion::new("$.data.age", Matcher::new(MatcherType::GreaterThan, "0")),
];

let validator = ResponseValidator::new(assertions);
let results = validator.validate(&response)?;

6. Workflow Module (src/workflow/)

Purpose: Multi-step request chaining with variable extraction

Key Types:

  • WorkflowStep - Single step (request + scripts + assertions + extractions)
  • RequestChain - Container for ordered steps
  • WorkflowExecutor - Executes chains with variable substitution
  • VariableSubstitutor - Replaces {{var}} placeholders

Features:

  • Variable extraction from JSON responses ($.path.to.field)
  • Variable substitution in URLs, headers, and bodies
  • Pre/post scripts per step
  • Assertions per step
  • Iteration over datasets
  • Detailed execution results

Example:

let login = WorkflowStep::new("login")
    .request(RequestBuilder::new(Post, "/login").body(credentials))
    .extract_variable("token", "$.auth.token");

let fetch = WorkflowStep::new("fetch")
    .request(RequestBuilder::new(Get, "/user/{{user_id}}")
        .header("Authorization", "Bearer {{token}}"))
    .assertion(Assertion::new("$.status", Matcher::equals("success")));

let chain = RequestChain::new("auth_flow")
    .step(login)
    .step(fetch);

let result = executor.execute(&chain)?;

7. Collections Module (src/collections/)

Purpose: Organize and persist request collections

Key Types:

  • Collection - Named group of requests
  • Workspace - Container for multiple collections
  • Storage - Persistence (YAML/JSON)

Features:

  • Save/load collections
  • Import/export formats
  • Request organization
  • Tagging and metadata

8. Environment Module (src/env/)

Purpose: Manage variables across environments

Key Types:

  • Environment - Key-value variable store
  • EnvironmentManager - Multi-environment handling
  • VariableSubstitutor - {{var}} replacement

Features:

  • Multiple environments (dev, staging, prod)
  • Active environment switching
  • Global vs collection-scoped variables
  • Secret management

9. Session Module (src/session/)

Purpose: Cookie handling and session persistence

Key Types:

  • Session - Session container
  • CookieJar - Cookie storage (cookie_store crate)

Features:

  • Automatic cookie extraction
  • Cookie persistence across requests
  • Session save/load
  • Cookie expiration handling

10. History Module (src/history/)

Purpose: Track and replay past requests

Key Types:

  • HistoryManager - History storage
  • HistoryEntry - Single request/response pair
  • HistoryLogger - Automatic logging

Features:

  • Automatic request logging
  • Search and filter
  • Replay from history
  • Export to JSON/YAML

🧪 Testing Strategy

Test Organization

tests/
├── integration/         # End-to-end tests (planned)
├── fixtures/           # Test data
└── common/             # Shared test utilities

Unit Tests:

  • Every module has #[cfg(test)] tests
  • 280+ tests covering all features
  • Mock HTTP servers using mockito and wiremock

Test Examples:

  • http/client.rs - 15 tests
  • auth/oauth2.rs - 39 tests
  • scripts/engine.rs - 29 tests
  • assertions/matcher.rs - 46 tests
  • workflow/executor.rs - 23 tests

Running Tests

cargo test           # All tests
cargo test --lib     # Unit tests only
cargo test -- --nocapture  # With output

📊 Dependencies

Core Dependencies

Crate Version Purpose
clap 4.5 CLI argument parsing
reqwest 0.12 HTTP client (blocking)
tokio 1.x Async runtime (future use)
serde 1.0 Serialization
serde_json 1.0 JSON handling
colored 2.1 Terminal colors
rustyline 14.0 REPL/readline
rhai 1.21 Scripting engine
base64 0.22 Base64 encoding
cookie_store 0.21 Cookie management
mime_guess 2.0 MIME type detection
uuid 1.11 ID generation
chrono 0.4 Date/time
directories 6.0 Standard directories
serde_yaml 0.9 YAML serialization
regex 1.11 Regular expressions

Dev Dependencies

Crate Version Purpose
mockito 1.5 HTTP mocking
wiremock 0.6 HTTP server mocking
criterion 0.5 Benchmarking
tempfile 3.14 Temporary files

🚀 Performance Considerations

Current Performance (v1.8.0)

  • Cold Start: ~50ms (REPL launch)
  • Request Overhead: <10ms (builder + client setup)
  • Memory: ~20MB baseline (REPL mode)
  • Test Suite: ~2s for 280 tests

Optimization Opportunities (v2.0+)

  1. Async/Await - Non-blocking I/O with Tokio
  2. Connection Pooling - Reuse HTTP connections
  3. HTTP/2 - Multiplexing
  4. Lazy Initialization - Defer module loading

🔮 Future Architecture Plans

v2.0 - Async Refactor

  • Full async/await implementation
  • Tokio-based execution
  • Connection pooling
  • HTTP/2 support

v2.5 - Advanced Protocols

  • WebSocket client
  • GraphQL support
  • gRPC support
  • Server-Sent Events (SSE)

v3.0 - Enterprise Features

  • Performance testing (load generation)
  • Mock server
  • CI/CD runner (Newman-like)
  • Security testing

📐 Design Patterns Used

Builder Pattern

  • RequestBuilder - Fluent request construction
  • WorkflowStep - Step-by-step workflow building
  • FormData - Form construction

Facade Pattern

  • HttpClient - Simplifies reqwest API
  • WorkflowExecutor - Orchestrates complex workflows

Strategy Pattern

  • Matcher - 14 different comparison strategies
  • Authentication types - Multiple auth strategies

Repository Pattern

  • HistoryManager - Persistence abstraction
  • Workspace - Collection storage

🔒 Security Considerations

Current Implementation

  1. No Unsafe Code - 100% safe Rust
  2. Input Validation - URL parsing, file paths
  3. Secret Handling - Environment variables for secrets
  4. HTTPS by Default - Secure connections
  5. Cookie Security - Respect HttpOnly, Secure flags

Future Security Features (v3.0)

  • Certificate pinning
  • OWASP API Security checks
  • Secrets detection in requests
  • Security header analysis

📚 Documentation

Public API Documentation

cargo doc --open  # Generate and open docs

All public types and functions are documented with:

  • Purpose and usage
  • Examples
  • Parameter descriptions
  • Return values

🎯 Success Metrics

Achieved (v1.8.0)

  • ✅ 280+ passing tests
  • ✅ ~85% test coverage
  • ✅ 13 modular components
  • ✅ Zero unsafe code
  • ✅ Comprehensive examples
  • ✅ Production-ready error handling

Goals (v2.0+)

  • 90%+ test coverage
  • <1s test suite execution
  • HTTP/2 support
  • Async architecture
  • 1000+ RPS throughput

🤝 Contributing to Architecture

When adding new features:

  1. Follow Module Structure - Keep related code together
  2. Write Tests First - TDD approach
  3. Document Public APIs - Rustdoc comments
  4. Use Builder Patterns - For complex types
  5. Avoid Unsafe Code - Unless absolutely necessary
  6. Error Handling - Use Result<T> everywhere

📝 Version History

Version Date Key Changes
v1.0.0 2025-11-13 Initial release - Basic HTTP client
v1.1.0 2025-11-13 Modular architecture + tests
v1.2.0 2025-11-13 Collections + history
v1.3.0 2025-11-13 Sessions + cookies
v1.4.0 2025-11-14 File uploads
v1.5.0 2025-11-14 Authentication suite
v1.6.0 2025-11-14 Scripting engine
v1.7.0 2025-11-14 Assertions system
v1.8.0 2025-11-15 Workflows + chaining

Last Updated: 2025-11-15 Version: 1.8.0