# cablehead/http-nu architecture

> Architecture diagram of the GitHub repository cablehead/http-nu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cablehead/http-nu
- Repository: https://github.com/cablehead/http-nu

## Overview

##### Project Type & Purpose
- http-nu is a Rust-based command-line web server that dynamically executes Nushell closures as HTTP handlers.
- Its purpose is to bridge an HTTP interface with Nushell closures, offering features such as TLS support, UNIX domain socket listening, serving static files, streaming responses, and even potential server-sent events.
- The README also highlights usage examples and commands showing how closures (either passed inline or via files/STDIN) are integrated into the HTTP handling process.

##### Key Components Derived from File Tree & README
- Core Engine (src/engine.rs): Likely manages the execution of Nushell closures. This component is central to how HTTP requests are turned into Nushell command executions.
- Request Handler (src/handler.rs): Responsible for mapping incoming HTTP requests to the closure logic. It may process request metadata and handle response metadata configuration (including static content and streaming).
- Listener (src/listener.rs): Manages different types of network listeners, whether it’s on a TCP port or via a UNIX domain socket, and routes incoming connections to the handler/engine.
- Main Entry (src/main.rs): Orchestrates setting up the server, parsing command-line arguments (like specifying the closure, TLS files, etc.), and initializing the engine and listener.
- Library abstraction (src/lib.rs): Likely provides shared functionality used across the engine, handler, and listener.
- Tests (src/test_engine.rs, src/test_handler.rs): Although not diagrammed in a production architecture, understanding that there are modular tests shows that the engine and handler are designed independently and are unit-testable.

##### Relationships & Interactions
- The Listener accepts incoming HTTP (or UNIX socket) connections.
- The HTTP Request is forwarded to the Handler, which extracts and prepares request metadata.
- The Engine takes the prepared request and runs the Nushell closure, effectively executing user-defined code to generate a response.
- Optionally, TLS handling is integrated by processing certificate files if TLS is enabled.
- The external interfaces (like curl or browsers) connect to this backend service, while GitHub Actions and Cargo packaging manage CI/CD and build/testing workflows.

##### Architectural Patterns and Design Principles
- Modular Design: Separation of concerns is evident (listener, handler, engine) allowing independent development/testing.
- Layered Architecture: A clear division between network I/O (listener), request transformation (handler), and business logic (engine executing closures).
- Extensibility: By receiving closures at runtime, the engine is highly flexible in handling various processing pipelines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["HTTP Client (curl/browser)"]:::external

    %% Server Components
    CLI["CLI/Main Application"]:::server
    Listener["HTTP Listener (TCP/UNIX Socket)"]:::server
    Handler["HTTP Request Handler"]:::server
    Engine["Core Engine (Nushell Closure Executor)"]:::server
    Shared["Shared Library"]:::server

    %% Unit Tests Cluster
    subgraph "Unit Tests"
        TestEngine["Engine Unit Tests"]:::tests
        TestHandler["Handler Unit Tests"]:::tests
    end

    %% Data Flow Connections
    Client -->|"sends_HTTP_Request"| Listener
    CLI -->|"initializes"| Listener
    Listener -->|"forwards_Request"| Handler
    Handler -->|"delegates_to"| Engine
    Engine -->|"returns_Response"| Handler
    Handler -->|"sends_HTTP_Response"| Client

    %% Dependency on Shared Library
    CLI ---|"uses"| Shared
    Listener ---|"uses"| Shared
    Handler ---|"uses"| Shared
    Engine ---|"uses"| Shared

    %% Unit Tests targeting components
    TestEngine ---|"tests"| Engine
    TestHandler ---|"tests"| Handler

    %% Click Events
    click CLI "https://github.com/cablehead/http-nu/blob/main/src/main.rs"
    click Listener "https://github.com/cablehead/http-nu/blob/main/src/listener.rs"
    click Handler "https://github.com/cablehead/http-nu/blob/main/src/handler.rs"
    click Engine "https://github.com/cablehead/http-nu/blob/main/src/engine.rs"
    click Shared "https://github.com/cablehead/http-nu/blob/main/src/lib.rs"
    click TestEngine "https://github.com/cablehead/http-nu/blob/main/src/test_engine.rs"
    click TestHandler "https://github.com/cablehead/http-nu/blob/main/src/test_handler.rs"

    %% Styles
    classDef external fill:#FFE0B2,stroke:#BF360C,stroke-width:2px;
    classDef server fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef tests fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
```
