diff --git a/README.md b/README.md index 8077ed3..6e8444b 100644 --- a/README.md +++ b/README.md @@ -1,351 +1,95 @@ -

πŸš€ NLAP - FalconAS

-

XML based Next Level Application Protocol including a lightning-fast Python / Java Application Server (FalconAS)

+![FalconAS Logo](./image/falconas-logo.png) -
- - CodeQL - - - Docs Oxygen - - - Docs Sphinx - - - Release - -
+Falcon Application Server - NLAP (Next Level Application Protocol) ---- - -This project includes: - -- A rock-solid, fast, and secure HTTP/1.1 parser and generator C++ library for use in microcontroller (e.g., Arduino) projects -- A (not-yet-finished) XML-based (NLAP protocol) application server (Python or Java) for real-time or high-security requirements - -## :pushpin: Overview - -**NLAP (Next Level Application Protocol)** is an XML-based protocol designed to replace HTTP -for modern web application requirements. - -**NLAP solves these problems** with a clean, XML-based transport encapsulation that natively supports: - -- βœ… **Robust** parallel **multi-response** transmission **over a single socket** -- βœ… **Elimination** of **head-of-line blocking** (time-consuming responses do not block follow-ups) -- βœ… Structured, **XML-encapsulated transport** data, including **validatable** XML schemas -- βœ… Firewall-friendly, **port-separated protocol subtypes** (NLAFP for files, NLAMP for application server requests) -- βœ… Simple, non-TLS, HSM- and TPM-based X.509 authentication, signing and encryption - -**FalconAS Server Features**: - -- βœ… **Kernel Mutex-Less**: Built with on-chip atomic user space locks -- βœ… **Lightning-Fast Performance**: Epoll-based / multi-socket optimized architecture -- βœ… **Sendfile Static File Delivery**: In-kernel sendfile() decrease scheduling latency -- βœ… **Rock-Solid App-Server Security**: Runs with tight backend process-separation model (non-threaded) -- βœ… **SPA Realtime Demands**: Built for modern browser applications (SPAs) real-time demands -- βœ… **Zero Bloat**: Eliminates unnecessary complexity while maintaining compatibility -- βœ… **Python-Powered**: FalconAS application server with embedded Python scripting -- βœ… **Java-Powered**: FalconAS application server with embedded Java scripting - -## :bookmark_tabs: Table of Contents - -1. [Quick Start](#racehorse-quick-start) -2. [Features](#star2-features) -3. [Why NLAP Instead of HTTP/1.2?](#mega-why-nlap-instead-of-http12) -4. [Build & Installation](#hammer_and_wrench-build--installation) -5. [Testing](#test_tube-testing) -6. [Technical Architecture](#gear-technical-architecture) -7. [Documentation](#page_with_curl-documentation) -8. [Community & Support](#globe_with_meridians-community--support) -9. [Contributing](#wave-contributing) -10. [Future Milestones](#alarm_clock-future-milestones) -11. [License](#memo-license) - ---- - -## :racehorse: Quick Start - -Get FalconAS (using HTTP/1.1 or NLAP) running in minutes: - -```bash -# clone repository -git clone https://github.com/WEBcodeX1/http-1.2.git -cd http-1.2 - -# install dependencies (Ubuntu 22.04/Debian 12) -apt-get install git cmake python3-pip libboost-all-dev python3-dev nlohmann-json3-dev - -# build and install -cmake . -make -sudo make install - -# start using systemd (automatically configured during install) -sudo systemctl daemon-reload -sudo systemctl enable falcon-as -sudo systemctl start falcon-as - -# OR start manually -. ./scripts/ulimit.sh -. ./scripts/set-transparent-hugepages.sh -/usr/local/bin/falcon-as -``` - -The server will be available with test applications at: -- `http://testapp1.local/` (HTTP/1.1 compatibility mode) -- `http://testapp2.local/` (HTTP/1.1 compatibility mode) - -For detailed installation instructions, see [BUILD.md](BUILD.md). - ---- - -## :star2: Features - -### Core Advantages -- **πŸš€ Lightning-Fast**: Epoll-based architecture for maximum performance -- **πŸ”’ Secure by Design**: Interpreters run non-threaded / unix process isolated -- **⚑ Zero Bloat**: Clean XML-based protocol without HTTP's legacy complexity -- **🎯 SPA-Optimized**: Perfect for modern Single Page Applications real-time demands -- **🐍 Python-Powered**: Embedded Python interpreter / scripting integration -- **β˜• Java-Powered**: Embedded Java JNI / scripting integration - -### NLAP Protocol Innovations -- **XML-Based Transport**: Clean, structured request/response format -- **Native UUID System**: Built-in request/response matching -- **Multiple Subtypes**: NLAFP for file transfer, NLAMP for application metadata -- **Extensible Architecture**: XML schemas enable easy protocol evolution -- **Partial File Transfer**: Efficient handling of large files with chunked transfer -- **Request/Response Signing**: Built-in cryptographic signing support - -### Technical Features -- **Static Content Server**: High-performance file serving with sendfile() -- **Application Server**: Python scripting with shared memory architecture -- **Memory Management**: Huge pages support and optimized memory layout -- **Process Architecture**: Separate processes to avoid Python GIL limitations -- **JSON Configuration**: Clean, maintainable configuration system -- **JSON Powered By**: [nlohmann/json](https://github.com/nlohmann/json) C++ JSON library - ---- - -## :mega: Why NLAP Instead of HTTP/1.2? - -### The Problem with HTTP/1.2 - -**HTTP/1.2 is not being pursued** - The original plan to extend HTTP/1.1 with UUID headers faces insurmountable challenges: - -- **Ancient Text-Based Protocol Design**: HTTP's line-based parsing is incompatible with efficient UUID integration -- **Client Library Overhead**: Client processing must be re-implemented for a dead protocol, this means unnecessary effort, -better implement intop modern NLAP design - -### The Problem with HTTP/2 & HTTP/3 - -**HTTP/2 Complexity Crisis:** -- Excessive complexity destroys HTTP/1.1's elegant simplicity -- Everything packed into one "black box" without logical separation -- Libraries are confusing and difficult to understand -- TLS/SSL handling unnecessarily embedded in protocol - -**HTTP/3 UDP Issues:** -- Solves core issues but moves unneccessary (already worldwide approved and adopted) complexity -from TCP into UDP (application) layer - -### Our Solution: NLAP (Next Level Application Protocol) - -NLAP replaces HTTP's legacy concepts with a clean, modern XML-based and application-centric (not document-centric) protocol. - -> **🎯 Key Innovation**: XML transport encapsulation, structured data, reliable concurrent-response transmission and extensibility that HTTP's ancient text format cannot match. - -**NLAP Protocol Specifications:** -- **XML-Based**: Structured, parseable, extensible format -- **Built-in UUID**: Native request/response correlation -- **Multiple Subtypes**: NLAFP for file protocol, NLAMP for metadata protocol -- **First Specs Available**: See `/specs/xml/` for NLAFP and NLAMP documentation +[![CodeQL](https://github.com/WEBcodeX1/http-1.2/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/WEBcodeX1/http-1.2/actions/workflows/github-code-scanning/codeql) +[![License](https://img.shields.io/github/license/WEBcodeX1/http-1.2?style=flat)](https://github.com/WEBcodeX1/http-1.2/tree/main/LICENSE) +[![Doxygen API](https://img.shields.io/badge/docs-doxygen-blue)](https://docs.webcodex.de/developer/falconas/v0.3/doxygen/index.html) +[![Sphinx Docs](https://img.shields.io/badge/docs-sphinx-blue)](https://docs.webcodex.de/developer/falconas/v0.3/sphinx/index.html) --- -## :hammer_and_wrench: Build & Installation - -### Prerequisites +# 1. Overview -**Operating System Support:** -- Ubuntu 22.04 (Jammy Jellyfish) -- Ubuntu 24.04 (Noble Numbat) -- Debian 12 +An advanced architectural paradigm for **low-latency** **TCP**/IP transport tailored for +modern browser web-applications and **high-throughput** data aggregation middleware. -**Required Dependencies:** -```bash -# core build tools -apt-get install git cmake +It incorporates a high-speed *Python 3* or *Java* application server that natively utilizes +**NLAP** as its core transport protocol to minimize execution and scheduling overhead. -# c++ boost libraries -apt-get install libboost-all-dev +# 2. Project Evolution & History -# python development headers -apt-get install python3-dev +The project was originally conceptualized under the designation `HTTP/1.2`. The initial +objective was to mitigate the limitations of the flawed `HTTP/1.1` pipelining specification +by injecting unique **UUIDs** into individual requests. -# c++ json library -apt-get install nlohmann-json3-dev -``` +However, practical implementation demonstrated that this approach introduces severe +technical problems. -### Build Options +Because the `HTTP/1.1` specification relies strictly on synchronous, serial processing, +it remains fundamentally incompatible with modern, deterministic zero-latency architectures. +Consequently, the `HTTP/1.2` pipelining methodology was deprecated in favor of a novel +architectural framework: **NLAP**. -**Standard Build:** -```bash -cmake . -make -make install -``` +# 3. What is NLAP? What problems does NLAP solve? -**Debug Build:** -```bash -cmake -DDEBUG_BUILD=1 . -make -make install -``` +NLAP (Next Level Application Protocol) is a deterministic, transaction-oriented transport +framework that formally resolves long-standing architectural omissions in Layer 5 (Session) +and Layer 6 (Presentation) of the OSI model over standard TCP. Originally conceptualized by +IETF engineers as an in-kernel transactional framed protocol, NLAP realizes this design paradigm +in user space while maintaining full compatibility with standard `TCP_STREAM` sockets. -**Java Backend Build:** -```bash -export JAVA_HOME=/usr/lib/jvm/jdk-24.0.2-oracle-x64/ -cmake -DJAVA_BACKEND=1 . -make -make install -``` +By replacing traditional, continuous stream-based processing with discrete, strictly validated +XML message frames, NLAP achieves exceptional throughput, structural security, and minimal +latency. -For complete build instructions, see [BUILD.md](BUILD.md). +**Core Architectural Characteristics:** ---- - -## :test_tube: Testing - -Comprehensive testing infrastructure ensures reliability: +- **Strict XML Message Framing:** Eliminates stream-parsing ambiguities by processing strictly bounded data packets. This non-streamed approach significantly enhances parsing security, mitigates memory-corruption vectors, and maximizes raw processing performance. +- **Formalized Model Descriptions:** Reduces protocol complexity to a bare minimum by enforcing a 100% complete structural and semantic definition via Document Type Definitions (DTD) and YANG modeling schemas. +- **Granular Protocol Sub-typing:** Sub-divides transport traffic into distinct, functional protocol variants to maximize scalability and simplify network firewalls (see chapter [7. NLAP Subtypes](#7-nlap-subtypes)). +- **Simplified High-Integrity Cryptography**: Drastically reduces cryptographic complexity. Because data is processed as static, complete messages rather than continuous streams, the entire frame is signed and encrypted atomically. This enables hardware-native X.509 standard compliance with direct HSM and TPM integration without complex TLS state-machines. +- **End-to-End Non-Blocking Architecture:** Features non-blocking execution primitives across all protocol layers. This design integrates seamlessly with Linux Kernel 7.0 AccECN (Accurate ECN) to optimize TCP retransmission timeouts (RTO) and low-latency feedback loops. +- **Near-Kernel Latency & Zero HoL Blocking**: Inherently eliminates head-of-line (HoL) blocking over a single socket connection. By deploying hybridized io_uring and epoll I/O frameworks, NLAP achieves deterministic processing speeds that mirror kernel-level transport latencies. -- **Unit Tests**: Core component validation (`/test/unit/`) -- **Integration Tests**: End-to-end functionality (`/test/integration/`) -- **Performance Tests**: Benchmarking and optimization (`/test/performance/`) -- **Evaluation Tests**: Protocol compliance (`/test/eval/`) +# 4. Achievements -See [test documentation](/test/README.md) for detailed testing procedures. - ---- +The technical progression and current state of the NLAP implementation comprise the following structural phases and components: -## :gear: Technical Architecture +1. **Protocol Paradigm Validation:** Analytical evaluation of HTTP/1.1 pipeline extensions resulted in the complete deprecation of stream-oriented processing for the FalconAS architecture in favor of a transactional framework. +2. **I/O Subsystem Evaluation:** Systematic review of synchronous Berkeley Sockets and multi-threaded processing layouts identified critical architectural bottlenecks, leading to the rejection of traditional multi-threading paradigms. +3. **Reference Socket Specification:** Formulated and published a verified, non-blocking, and deterministic Berkeley Sockets blueprint on *Der IT PrΓΌfer* ([Technical Insight](https://www.der-it-pruefer.de/network/Network-Sockets-Insight)). +4. **Cross-Platform Verification:** Demonstrated the portability of the socket layer by adapting the core FalconAS network-handling runtime to resource-constrained environments, utilizing the ESP32-S3 microcontroller as a reference platform. +5. **C++23 Parsing Library:** Engineered a specialized, performance- and heap-optimized C++23 validation library for low-level HTTP/1.1 parsing and message generation. +6. **Architectural Refactoring:** Executed a comprehensive code-base refactoring based on the empirical performance metrics gathered from the initial reference implementations. +7. **Schema Implementation:** Developed the comprehensive structural boundaries for all NLAP protocol subtypes, formalized through complete Document Type Definitions (DTD) and YANG modeling layouts compiled with AI assistance. +8. **Zero-Copy XML Parsing Engine:** Implemented a memory-optimized XML parsing layer utilizing C++23 features (`std::generator`) and non-allocating string views (`std::string_view`) to minimize data-handling overhead, developed with AI assistance. -### Process Model +# 5. Working Components -```text -+----------------+---------------+---------------+----------------+ -| Server Process | AS Process 1 | AS Process x | Result Process | -| | Python Interp.| Python Interp.| | -+-----------------------------------------------------------------+ -| Shared Memory | -| - StaticFS Requests | -| - AS Metadata | -| - AS Requests | -| - AS Results | -+-----------------------------------------------------------------+ -``` +Below is a brief overview of the currently functional and production-ready components: -**Design Principles:** -- **Process-Based**: Separate processes avoid Python GIL limitations -- **Shared Memory**: High-performance IPC with atomic locks (kernel mutex-less) -- **Huge Pages**: Memory optimization for better performance +- **Memory (heap)-optimized HTTP/1.1 library:** Features a fast parser and message generator ([`/lib/http/`](/lib/http/)). +- **Microcontroller portability:** The HTTP/1.1 parser library is fully ported to the ESP-IDF based ESP32-S3 and ESP32-C3 platforms ([`/ports/arduino/`](/ports/arduino/)). +- **Structural specifications:** Includes core XML and workflow schemas formalized via DTD and YANG models ([`/specs/`](/specs/)). +- **Optimized XML processing:** A memory-optimized Apache Xerces-based parser tailored for NLAP validation and message processing. -### Performance Philosophy: Epoll vs Coroutines +# 6. Milestones -**⚠️ Coroutine Warning**: While trending, coroutines can be **counterproductive** for scalability if implemented incorrectly. +The following developments are scheduled for immediate implementation: -**The Problem with incorrectly implemented Coroutines:** -- In case a single connection awaits a syscall `read()` result -- Its similar to one `poll()` for a single connection file descriptor -- 10,000 connections = 10,000 syscalls (context switches) -- Massive overhead for checking received data (unscalable) - -**Our Epoll Advantage:** -- **Single syscall** informs about multiple FDs with pending data -- Used by nginx and other high-performance servers - ---- - -## :page_with_curl: Documentation - -### Official Documentation -- **Build Instructions**: [BUILD.md](BUILD.md) -- **Testing Guide**: [test/README.md](/test/README.md) -- **Technical Specifications**: [specs/md/README.md](/specs/md/README.md) -- **Feature Comparison**: [FEATURE-MATRIX.md](FEATURE-MATRIX.md) -- **Sphinx Rendered**: [Detailed Sphinx](https://docs.webcodex.de/developer/falconas/sphinx/index.html) -- **Doxygen Rendered**: [Doxygen - UML relations](https://docs.webcodex.de/developer/falconas/doxygen/index.html) - -### Online Resources -- **CI Documentation**: [/doc/README.md](/doc/README.md) -- **RFP/RFC Specs**: [http://docs.webcodex.de/wacp/rfp/](http://docs.webcodex.de/wacp/rfp/) -- **Detailed Analysis**: [Der IT PrΓΌfer](http://der-it-pruefer.de) - -### Protocol Specifications -- **NLAP XML Specs**: See [/specs/xml/](/specs/xml/) for detailed protocol documentation - - [NLAFP (Next Level Application File Protocol)](/specs/xml/NLAFP-XML-SPECS.md) - - [NLAMP (Next Level Application Metadata Protocol)](/specs/xml/NLAMP-XML-SPECS.md) -- **Internal Libraries**: [lib/README.md](lib/README.md) - ---- +- **Kernel I/O Integration:** Adaptation of Linux `io_uring` (for asynchronous zero-copy receiving and sending) and `epoll` (restricted to transmission operations), adhering to the architectures validated in sections 4.2, 4.3, and 4.4. +- **NLAMP Prototype:** Initial development of the Application Server Metadata ("M") prototype, featuring process-based Shared Memory (SHM) isolation within *FalconAS*. +- **NLAFP Prototype:** Initial development of the File-Transport ("F") prototype, utilizing high-speed, direct user-space I/O. +- **NLAPS Integration:** Full architectural implementation of the ("S") Security Extensions layer. -## :globe_with_meridians: Community & Support +# 7. NLAP Subtypes -### Get Help & Discuss -- **Issues**: [GitHub Issues](https://github.com/WEBcodeX1/http-1.2/issues) - Bug reports and feature requests -- **Email**: [http1-2@webcodex.de](mailto:http1-2@webcodex.de) - Questions and improvement ideas -- **Security**: [SECURITY.md](SECURITY.md) - Security vulnerability reporting +Each NLAP sub-protocol operates on a dedicated TCP port and is structured as follows: -### Stay Updated -- **Documentation**: [Official Docs](http://docs.webcodex.de/wacp/rfp/) -- **RFC Updates**: [Der IT PrΓΌfer](http://der-it-pruefer.de) - Detailed protocol analysis - ---- - -## :wave: Contributing - -We welcome contributions! Whether you're: -- πŸ› **Reporting bugs** -- πŸ’‘ **Suggesting features** -- πŸ“ **Improving documentation** -- πŸ”§ **Submitting code** - -Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. - -**Code Quality Standards:** -- Clean, readable, maintainable code -- Comprehensive testing -- Security-conscious development -- Commit signing with GPG/SSH keys - ---- - -## :alarm_clock: Future Milestones - -### Short-term Goals -- [x] **HTTP/1.1 Compatibility**: Minimal SPA related features -- [x] **x0 Framework Integration**: Seamless SPA framework compatibility -- [ ] **NLAP Protocol Implementation**: Complete NLAFP and NLAMP implementation -- [ ] **NLAP Client Library**: Reference implementation for clients -- [ ] **Performance Benchmarks**: Comprehensive HTTP/1.1, HTTP/2, HTTP/3, and NLAP comparisons - -### Long-term Vision -- [ ] **Protocol Standardization**: Submit NLAP as official RFC -- [ ] **Enterprise Features**: Advanced monitoring, analytics, management -- [ ] **Proxy Server Component**: Complete the load balancing/reverse proxy module -- [ ] **NLAP Browser Support**: Native NLAP support in modern browsers - -See [GitHub Milestones](https://github.com/WEBcodeX1/http-1.2/milestones) for detailed roadmap. - ---- - -## :memo: License - -**GNU Affero General Public License v3.0** - See [LICENSE](LICENSE) for details. - ---- +- **NLAFP:** File-transport operations. +- **NLAMP:** Application server Metadata (JSON) exchange. +- **NLAPP:** Upcoming Proxy Server implementation, featuring auto-scaling and multi-endpoint support. +- **NLAPS:** Security Extensions, handling cryptographic signing, encryption, and authentication. -

- πŸš€ Ready to experience the future of web protocols?
- Made with ❀️ by Claus Prüfer / clickIT / WEBcodeX -

+Detailed specifications for each sub-protocol are available in the [`/specs/`](/specs/) directory. diff --git a/config/README.md b/config/README.md new file mode 100644 index 0000000..dd27bf8 --- /dev/null +++ b/config/README.md @@ -0,0 +1,7 @@ +# 1. Runtime Configuration + +This directory contains the JSON configuration used by the server runtime. + +## 1.1. Contents + +- `config.json`: sample / default server configuration covering base paths, TCP options, runtime user/group, MIME types, CPU binding, and virtual host namespace routing. diff --git a/image/README.md b/image/README.md new file mode 100644 index 0000000..dc4134a --- /dev/null +++ b/image/README.md @@ -0,0 +1,8 @@ +# 1. Project Artwork + +This directory contains the FalconAS logo assets used by the project documentation. + +## 1.1. Contents + +- `falconas-logo.png`: rendered logo used by the root `README.md`. +- `falconas-logo.xcf`: editable GIMP source file for the logo artwork. diff --git a/image/falconas-logo.png b/image/falconas-logo.png new file mode 100644 index 0000000..a0fe2d3 Binary files /dev/null and b/image/falconas-logo.png differ diff --git a/image/falconas-logo.xcf b/image/falconas-logo.xcf new file mode 100644 index 0000000..3221e88 Binary files /dev/null and b/image/falconas-logo.xcf differ diff --git a/lib/README.md b/lib/README.md index ca482f2..5e03fa9 100644 --- a/lib/README.md +++ b/lib/README.md @@ -1,14 +1,9 @@ -# Internal C++ Libraries +# 1. Internal C++ Libraries -The following C++ Libraries are used internally by the project. +This directory contains the reusable libraries that are built before the main `falcon-as` server and linked into tests. -## 1. Event Library +## 1.1. Subdirectories -The **Event Library** is a tiny library providing a simple callback mechanism. - -## 2. HTTP/1.1 Library - -The **HTTP/1.1 Library** is used to - -- Parse HTTP Requests / Headers -- Generate HTTP Requests / Headers +- [`event/`](./event/): small shared callback / event helper library (`libevent2`). +- [`http/`](./http/): static HTTP parsing and message generation library (`httpparser`). +- [`xml/`](./xml/): static Xerces-C++ backed XML parsing library (`xmlparser`). diff --git a/lib/event/README.md b/lib/event/README.md new file mode 100644 index 0000000..bc81785 --- /dev/null +++ b/lib/event/README.md @@ -0,0 +1,9 @@ +# 1. Event Helper Library + +This directory contains the lightweight event / callback helper that is built as the shared library `libevent2`. + +## 1.1. Contents + +- `Event.hpp`: public interface for registering and dispatching callbacks. +- `Event.cpp`: implementation of the event helper. +- `CMakeLists.txt`: builds and installs the shared library. diff --git a/lib/http/README.md b/lib/http/README.md new file mode 100644 index 0000000..cf107cf --- /dev/null +++ b/lib/http/README.md @@ -0,0 +1,11 @@ +# 1. HTTP Parser / Generator Library + +This directory contains the internal static library `httpparser` that is linked into the server, unit tests, and benchmark targets. + +## 1.1. Contents + +- `httpparser.cpp` / `httpparser.hpp`: default C++23 parser implementation using `std::string_view`, `std::span`, and heterogeneous lookups. +- `httpparser-cpp11.cpp` / `httpparser-cpp11.hpp`: legacy parser implementation enabled with `-DUSE_LEGACY_CPP11=ON`. +- `httpgenerator.cpp` / `httpgenerator.hpp`: HTTP response / message generation helpers. +- `httpconstants.hpp` and `httpconstants-cpp11.hpp`: parser and generator constants for the corresponding implementation. +- `CMakeLists.txt`: selects the active parser implementation and builds the static archive. diff --git a/lib/xml/README.md b/lib/xml/README.md new file mode 100644 index 0000000..c3f2258 --- /dev/null +++ b/lib/xml/README.md @@ -0,0 +1,10 @@ +# 1. XML Parser Library + +This directory contains the internal static library `xmlparser` used for XML validation and message parsing. + +## 1.1. Contents + +- `xmlparser.hpp` / `xmlparser.cpp`: parser interface and implementation. +- `xmlconstants.hpp`: XML-related constants used by the parser. +- `static-dtd.hpp`: embedded DTD support used by the parser layer. +- `CMakeLists.txt`: resolves the Xerces-C++ dependency and builds the static archive. diff --git a/ports/README.md b/ports/README.md index 8bcac27..5de3025 100644 --- a/ports/README.md +++ b/ports/README.md @@ -1,5 +1,7 @@ -# Ported Systems -This directory contains ports to multiple systems. +# 1. Ported Systems -## Arduino -The ./arduino subdir contains ports to arduino based microcontrollers. +This directory contains platform-specific ports of reusable FalconAS components. + +## 1.1. Subdirectories + +- [`arduino/`](./arduino/): microcontroller-focused cross-builds of the HTTP parser library for ESP32 targets. diff --git a/ports/arduino/README.md b/ports/arduino/README.md index 34b2d4b..e930ab4 100644 --- a/ports/arduino/README.md +++ b/ports/arduino/README.md @@ -1,5 +1,10 @@ -# ESP32-C3 -The `./esp32c3` subdir contains the first port to the ESP32-C3 based RISCV32 single core SoC board (ESPRESSIF). +# 1. Arduino / ESP-IDF Ports -# ESP32-S3 -The `./esp32s3` subdir contains the port to the ESP32-S3 based XTENSA 32-bit dual core SoC board (ESPRESSIF). +This directory contains cross-build configurations for reusing the internal HTTP parser library on ESP-IDF based ESP32 targets. + +## 1.1. Subdirectories + +- [`esp32c3/`](./esp32c3/): RISCV32 based ESP32-C3 build configuration. +- [`esp32s3/`](./esp32s3/): Xtensa based ESP32-S3 build configuration. + +Each port builds and installs a target-specific static `httpparser.a` archive together with its public headers. diff --git a/scripts/README.md b/scripts/README.md index afe541a..9d2dfd4 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -1,4 +1,14 @@ -# Install Scripts +# 1. Installation and System Scripts -OS install scripts reside here. +This directory contains helper scripts used during installation and system preparation. +## 1.1. Contents + +- `add_user_group.sh`: creates the runtime user and group expected by the server. +- `cp_etc.sh`: copies packaged configuration files into their target location. +- `install_startup_script.cmake`: selects the startup integration matching the detected init system. +- `mk_www.sh`: prepares the web root used by the example setup. +- `patch_etc_hosts.sh`: adds local hostname mappings used by the sample namespaces. +- `set-transparent-hugepages.sh`: applies hugepage related runtime settings. +- `ulimit.sh`: raises the open-file limit for high-connection workloads. +- [`startup/`](./startup/): init-system specific service definitions. diff --git a/scripts/startup/README.md b/scripts/startup/README.md index 83fa8ec..2ed46e9 100644 --- a/scripts/startup/README.md +++ b/scripts/startup/README.md @@ -1,86 +1,17 @@ -# Startup Scripts +# 1. Startup Script Variants -This directory contains startup scripts for the Falcon HTTP Application Server. +This directory contains service definitions for the init systems currently supported by the installer. -## SystemD (Ubuntu, Debian 12+) +## 1.1. Subdirectories -To install and enable the systemd service: +- [`systemd/`](./systemd/): service unit for modern Linux distributions. +- [`openrc/`](./openrc/): OpenRC service wrapper. +- [`init.d/`](./init.d/): SysVinit compatible startup script. -```bash -# Copy service file to systemd directory -sudo cp systemd/falcon-as.service /etc/systemd/system/ +The top-level installer logic in [`../install_startup_script.cmake`](../install_startup_script.cmake) chooses one of these variants during installation. -# Reload systemd configuration -sudo systemctl daemon-reload +## 1.2. Manual Installation Quick Reference -# Enable service to start on boot -sudo systemctl enable falcon-as - -# Start the service -sudo systemctl start falcon-as - -# Check service status -sudo systemctl status falcon-as -``` - -## OpenRC (Devuan, Gentoo, Alpine) - -To install and enable the OpenRC init script: - -```bash -# Copy init script to init.d directory -sudo cp openrc/falcon-as /etc/init.d/ - -# Make it executable (if not already) -sudo chmod +x /etc/init.d/falcon-as - -# Add to default runlevel -sudo rc-update add falcon-as default - -# Start the service -sudo rc-service falcon-as start - -# Check service status -sudo rc-service falcon-as status -``` - -## SysVinit (Debian <= 11, Ubuntu <= 14.04, older systems) - -To install and enable the SysVinit init script: - -```bash -# Copy init script to init.d directory -sudo cp init.d/falcon-as /etc/init.d/ - -# Make it executable (if not already) -sudo chmod +x /etc/init.d/falcon-as - -# Enable service to start on boot -sudo update-rc.d falcon-as defaults - -# Start the service -sudo service falcon-as start -# or -sudo /etc/init.d/falcon-as start - -# Check service status -sudo service falcon-as status -# or -sudo /etc/init.d/falcon-as status - -# Stop the service -sudo service falcon-as stop - -# Restart the service -sudo service falcon-as restart -``` - -## Important Notes - -All startup scripts include: -- **ulimit settings**: Sets maximum open files to 1,000,000 -- **Transparent hugepages**: Sets vm.nr_hugepages to 1024 -- **User/Group**: Runs as `falcon-http` user and group -- **Working directory**: `/var/www` - -Make sure the `falcon-http` user and group exist before starting the service (see `/scripts/add_user_group.sh`). +- **systemd:** copy `systemd/falcon-as.service` to `/etc/systemd/system/`, then run `systemctl daemon-reload` and `systemctl enable --now falcon-as`. +- **OpenRC:** copy `openrc/falcon-as` to `/etc/init.d/`, make it executable, then run `rc-update add falcon-as default` and `rc-service falcon-as start`. +- **SysVinit:** copy `init.d/falcon-as` to `/etc/init.d/`, make it executable, then run `update-rc.d falcon-as defaults` and `service falcon-as start`. diff --git a/scripts/startup/init.d/README.md b/scripts/startup/init.d/README.md new file mode 100644 index 0000000..8146d51 --- /dev/null +++ b/scripts/startup/init.d/README.md @@ -0,0 +1,7 @@ +# 1. SysVinit Startup Files + +This directory contains the classic `/etc/init.d` startup script variant used on SysVinit based systems. + +## 1.1. Contents + +- `falcon-as`: init script for starting, stopping, and restarting the `falcon-as` service. diff --git a/scripts/startup/openrc/README.md b/scripts/startup/openrc/README.md index e69de29..11f4b2c 100644 --- a/scripts/startup/openrc/README.md +++ b/scripts/startup/openrc/README.md @@ -0,0 +1,7 @@ +# 1. OpenRC Startup Files + +This directory contains the OpenRC service wrapper used on systems that manage services with OpenRC. + +## 1.1. Contents + +- `falcon-as`: OpenRC service script for starting and stopping the `falcon-as` server binary. diff --git a/scripts/startup/systemd/README.md b/scripts/startup/systemd/README.md index e69de29..bea5653 100644 --- a/scripts/startup/systemd/README.md +++ b/scripts/startup/systemd/README.md @@ -0,0 +1,7 @@ +# 1. systemd Startup Files + +This directory contains the service unit used on systemd-based Linux distributions. + +## 1.1. Contents + +- `falcon-as.service`: systemd unit file for starting the `falcon-as` server process at boot. diff --git a/specs/README.md b/specs/README.md index 4abacf5..0ced424 100644 --- a/specs/README.md +++ b/specs/README.md @@ -1,24 +1,9 @@ -# 1. Specifications - -Main Specs in [./md/](./md/README.md). - -## 1.1. Database - -Database Definitions / Performance Test Data [./database/](./database). - -## 1.2. Markup - -Main Specs / Markup Documents [./md/](./md/README.md). - -## 1.3. Portable Document Format - -PDF rendered / from Visio [./pdf/](./pdf). - -## 1.4. MS Visio - -Microsoft Visio Slides [./visio/](./visio). - -## 1.5. XML - -XML Service Specifications [./xml/](./xml). - +# 1. Specifications + +This directory groups the protocol and benchmark specification material that accompanies the implementation. + +## 1.1. Subdirectories + +- [`xml/`](./xml/): XML / DTD protocol definitions and per-subtype specification drafts. +- [`yang/`](./yang/): YANG representation of the NLAP message model. +- [`database/`](./database/): database notes for performance-test result storage. diff --git a/specs/database/README.md b/specs/database/README.md new file mode 100644 index 0000000..f92f1f0 --- /dev/null +++ b/specs/database/README.md @@ -0,0 +1,7 @@ +# 1. Database Notes + +This directory contains database-oriented notes for storing and analysing performance measurements. + +## 1.1. Contents + +- `test-performance-db.md`: draft schema and workflow notes for persisting benchmark runs and result metadata. diff --git a/specs/xml/NLASP-XML-SPECS.md b/specs/xml/NLASP-XML-SPECS.md deleted file mode 100644 index 8f299dd..0000000 --- a/specs/xml/NLASP-XML-SPECS.md +++ /dev/null @@ -1,7 +0,0 @@ -# 3. Next Level Application Session Protocol (NLASP) - -## 3.1. Overview - -This specification is currently under development. - -Please refer to the [development status page](https://www.der-it-pruefer.de/network/Exemplary-HTTP-Processing-Protocol-Design) for the latest updates. diff --git a/specs/xml/README.md b/specs/xml/README.md index f10a2e6..8c4071a 100644 --- a/specs/xml/README.md +++ b/specs/xml/README.md @@ -1,15 +1,15 @@ # 1. XML Service Metadata Specifications -This directory contains XML service metadata specifications for the Next Level Application Protocol (NLAP) sub-protocols. +This directory contains the XML-oriented protocol material for NLAP. -## 1.1. Table of Contents +## 1.1. Contents -1. [Next Level Application Metadata Protocol (NLAMP)](./NLAMP-XML-SPECS.md) -2. [Next Level Application File Protocol (NLAFP)](./NLAFP-XML-SPECS.md) -3. [Next Level Application Session Protocol (NLASP)](./NLASP-XML-SPECS.md) -4. [Next Level Application Proxy Protocol (NLAPP)](./NLAPP-XML-SPECS.md) -5. [Next Level Application Protocol Secure Extension (NLAPS)](./NLAPS-XML-SPECS.md) +- `nlap.dtd`: shared DTD describing the common NLAP message envelope and elements. +- `NLAMP-XML-SPECS.md`: metadata protocol draft. +- `NLAFP-XML-SPECS.md`: file-transfer protocol draft. +- `NLAPP-XML-SPECS.md`: proxy protocol draft. +- `NLAPS-XML-SPECS.md`: security extension draft. -## 1.2. Development Status +## 1.2. Notes -Ongoing RFP / RFC development status: [Exemplary HTTP Processing Protocol Design](https://www.der-it-pruefer.de/network/Exemplary-HTTP-Processing-Protocol-Design) +The XML parser library and XML parser tests in this repository use these definitions as the current structural reference point. diff --git a/specs/yang/README.md b/specs/yang/README.md new file mode 100644 index 0000000..a634e07 --- /dev/null +++ b/specs/yang/README.md @@ -0,0 +1,7 @@ +# 1. YANG Specifications + +This directory contains the YANG representation of the NLAP message model. + +## 1.1. Contents + +- `nlap.yang`: YANG 1.1 module derived from `../xml/nlap.dtd`, covering the shared NLAP envelope and the currently modelled sub-protocol fields. diff --git a/specs/xml/nlap.yang b/specs/yang/nlap.yang similarity index 100% rename from specs/xml/nlap.yang rename to specs/yang/nlap.yang diff --git a/src/ASBackend/README.md b/src/ASBackend/README.md new file mode 100644 index 0000000..47ca9d0 --- /dev/null +++ b/src/ASBackend/README.md @@ -0,0 +1,8 @@ +# 1. Application Server Backend Headers + +This directory contains the backend-specific interface headers used by the application-server process layer. + +## 1.1. Contents + +- `PythonBackend.hpp`: Python embedding interface used by the default build. +- `JavaBackend.hpp`: JNI-based backend interface enabled when the project is configured with `-DJAVA_BACKEND=1`. diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..b1cfaa3 --- /dev/null +++ b/src/README.md @@ -0,0 +1,14 @@ +# 1. FalconAS Server Sources + +This directory contains the main application sources that build the `falcon-as` executable. + +## 1.1. Main Components + +- `main.cpp`: entry point that constructs and starts the server. +- `Server.*`: socket setup, accept loop, shared-memory setup, and process termination orchestration. +- `Client*` and `ClientHandler*`: client connection tracking, epoll integration, and request processing. +- `Configuration*`: JSON configuration loading and namespace / MIME type setup. +- `Filesystem*`: static file namespace helpers. +- `ASProcessHandler*`: application-server child process handling for Python or Java backends. +- `CPU*`, `MemoryManager.hpp`, `SHMVector.hpp`, `Vector.hpp`: low-level runtime helpers. +- [`ASBackend/`](./ASBackend/): backend-specific interface headers. diff --git a/test/README.md b/test/README.md index f4c106d..61d9c69 100644 --- a/test/README.md +++ b/test/README.md @@ -1,8 +1,10 @@ -# Tests +# 1. Tests -Tests are devided into the following Sub-Sections. +This directory contains the CMake-organized test and benchmark tree for FalconAS. -- Evaluation Tests [./eval](./eval) -- Unit Tests [./unit](./unit) -- Integration Tests [./integration](./integration) -- Performace Tests [./performance](./performance) +## 1.1. Subdirectories + +- [`eval/`](./eval/): exploratory and feature-evaluation executables. +- [`integration/`](./integration/): cross-component tests and end-to-end style checks. +- [`unit/`](./unit/): focused tests for individual libraries and helpers. +- [`performance/`](./performance/): benchmark and measurement-oriented executables. diff --git a/test/eval/JavaJNI/README.md b/test/eval/JavaJNI/README.md new file mode 100644 index 0000000..489f63b --- /dev/null +++ b/test/eval/JavaJNI/README.md @@ -0,0 +1,10 @@ +# 1. Java JNI Evaluation + +This directory contains the optional JNI-based evaluation target for the Java backend path. + +## 1.1. Contents + +- `test-run-jni.cpp`: Boost.Test executable that exercises the JNI bridge. +- `WebApp.java` / `WebApp.class`: small Java test application used by the JNI test. +- `json-java.jar`: bundled JSON dependency required by the Java sample. +- `CMakeLists.txt`: resolves Java / JNI packages and builds `test-run-jni`. diff --git a/test/eval/README.md b/test/eval/README.md new file mode 100644 index 0000000..8cbef4f --- /dev/null +++ b/test/eval/README.md @@ -0,0 +1,11 @@ +# 1. Evaluation Tests + +This directory contains exploratory targets used to validate implementation ideas or optional runtime integrations. + +## 1.1. Contents + +- `test-boost-python.cpp`: experiments with the embedded Python integration layer. +- `test-pointer-ref.cpp`: pointer / reference behavior checks. +- `test-shmem-vector.cpp`: shared-memory vector experimentation. +- [`ResultOrder/`](./ResultOrder/): focused result-ordering evaluation target. +- [`JavaJNI/`](./JavaJNI/): optional JNI evaluation target, built only when `JAVA_BACKEND` is enabled. diff --git a/test/eval/ResultOrder/README.md b/test/eval/ResultOrder/README.md new file mode 100644 index 0000000..68ee038 --- /dev/null +++ b/test/eval/ResultOrder/README.md @@ -0,0 +1,9 @@ +# 1. Result Order Evaluation + +This directory contains an evaluation test for ordering-related behavior. + +## 1.1. Contents + +- `test-result-order.cpp`: Boost.Test executable built as `test-result-order`. +- `test-result-order-class.cpp`: helper implementation used by the test executable. +- `test-result-order.hpp`: declarations shared by the result-order test sources. diff --git a/test/integration/README.md b/test/integration/README.md new file mode 100644 index 0000000..86eb774 --- /dev/null +++ b/test/integration/README.md @@ -0,0 +1,16 @@ +# 1. Integration Tests + +This directory contains tests that exercise multiple components together. + +## 1.1. CMake-Managed Targets + +- [`event/`](./event/): validates the internal event library in a linked executable. +- [`string-functions/`](./string-functions/): checks shared string helper behavior. +- [`vector-multi-erase/`](./vector-multi-erase/): verifies vector erase semantics. +- [`signal-termination/`](./signal-termination/): validates process shutdown and SIGTERM propagation. +- [`custom-vector/`](./custom-vector/): integration coverage for the shared-memory vector implementation. +- [`xml-parser/`](./xml-parser/): end-to-end XML parser integration coverage. + +## 1.2. Manual Checks + +- [`request-validation/`](./request-validation/): shell-based request validation scripts that are currently stored in the repository but not added to the integration CMake tree. diff --git a/test/integration/custom-vector/README.md b/test/integration/custom-vector/README.md new file mode 100644 index 0000000..70e454a --- /dev/null +++ b/test/integration/custom-vector/README.md @@ -0,0 +1,9 @@ +# 1. Custom Vector Integration Test + +This directory contains the integration test target for the shared-memory vector implementation. + +## 1.1. Contents + +- `test-SHMVector.cpp`: Boost.Test source built as `test-SHMVector`. +- `test-CustomVector`: prebuilt ELF test artifact committed alongside the source tree for this integration test. +- `CMakeLists.txt`: registers the executable and test entry. diff --git a/test/integration/event/README.md b/test/integration/event/README.md new file mode 100644 index 0000000..d754466 --- /dev/null +++ b/test/integration/event/README.md @@ -0,0 +1,9 @@ +# 1. Event Library Integration Test + +This directory contains the integration test that links against the internal `libevent2` shared library. + +## 1.1. Contents + +- `test-Event.cpp`: Boost.Test executable source built as `test-event`. +- `TestClass.cpp` / `TestClass.hpp`: helper class used by the event test. +- `CMakeLists.txt`: links the test against both Boost.Test and `libevent2`. diff --git a/test/integration/request-validation/README.md b/test/integration/request-validation/README.md new file mode 100644 index 0000000..d760170 --- /dev/null +++ b/test/integration/request-validation/README.md @@ -0,0 +1,10 @@ +# 1. Request Validation Scripts + +This directory contains manual shell-script checks for validating request samples. + +## 1.1. Contents + +- `test-valid-requests.sh`: validates request cases expected to pass. +- `test-invalid-requests.sh`: validates request cases expected to fail. + +These scripts are not currently wired into the repository's CMake-driven test targets. diff --git a/test/integration/signal-termination/README.md b/test/integration/signal-termination/README.md index 10f50c3..e198388 100644 --- a/test/integration/signal-termination/README.md +++ b/test/integration/signal-termination/README.md @@ -1,57 +1,32 @@ -# Signal Termination Handling Test +# 1. Signal Termination Integration Test -## Overview +This directory contains a self-contained Boost.Test executable that models the server's +child-process shutdown flow. -This integration test verifies that the server properly handles SIGTERM signals and propagates them to all child processes. +## 1.1. Contents -## Test Description +- `test-signal-termination.cpp`: forks helper child processes, installs `SIGTERM` + handlers, and verifies orderly shutdown behavior. +- `CMakeLists.txt`: registers the `test-signal-termination` executable. -The test validates the following behavior: +## 1.2. Covered Behavior -1. **Parent Process Tracking**: When child processes are forked, their PIDs are registered with the parent process -2. **Signal Propagation**: When the parent process receives a SIGTERM signal, it sends SIGTERM to all tracked child processes -3. **Clean Shutdown**: All child processes handle SIGTERM gracefully and exit cleanly +The test mirrors the shutdown pattern implemented in the runtime sources without starting +the full server: -## Test Cases +- `src/Server.cpp`: keeps track of child PIDs and terminates them during shutdown. +- `src/ASProcessHandler.cpp`: registers forked application-server processes with the + server-side PID tracker. -### Test 1: Parent Sends SIGTERM to Children -- Creates a parent process with two child processes -- Registers child PIDs with the parent -- Sends SIGTERM to parent -- Verifies that parent forwards SIGTERM to all children -- Verifies that all processes exit cleanly with status 0 +The Boost.Test cases verify that: -### Test 2: Child Processes Not Killed Without SIGTERM -- Creates a parent with a child process -- Verifies that without receiving SIGTERM, the child continues running -- Sends SIGTERM to verify clean shutdown capability +1. child PIDs can be collected by the parent-side tracker, +2. sending `SIGTERM` to the tracked children terminates them cleanly, and +3. a child process continues running until an explicit termination signal is sent. -## How It Works - -The termination handling in the HTTP server follows this pattern: - -1. **Server.cpp**: Main server process - - Maintains a static vector `ChildPIDs` to track all child process IDs - - `Server::terminate()` handler sends SIGTERM to all tracked children when parent receives SIGTERM - -2. **ASProcessHandler.cpp**: Application Server child processes - - Each forked AS process PID is registered via `registerChildPID()` - - Child processes have their own SIGTERM handlers to exit gracefully - -3. **ResultProcessor.cpp**: Result processor child process - - Forked process PID is returned and registered with parent - - Has its own SIGTERM handler for clean shutdown - -## Running the Test +## 1.3. Running the Test ```bash cd build/test/integration/signal-termination ./test-signal-termination ``` - -## Expected Output - -All test cases should pass, indicating: -- βœ“ Parent successfully tracks child PIDs -- βœ“ SIGTERM is propagated from parent to all children -- βœ“ All processes exit cleanly without requiring SIGKILL diff --git a/test/integration/string-functions/README.md b/test/integration/string-functions/README.md new file mode 100644 index 0000000..33f5848 --- /dev/null +++ b/test/integration/string-functions/README.md @@ -0,0 +1,8 @@ +# 1. String Function Integration Test + +This directory contains the integration test for shared string helper behavior. + +## 1.1. Contents + +- `test-string-functions.cpp`: Boost.Test source built as `test-string-functions`. +- `CMakeLists.txt`: registers the executable. diff --git a/test/integration/vector-multi-erase/README.md b/test/integration/vector-multi-erase/README.md new file mode 100644 index 0000000..a6403ce --- /dev/null +++ b/test/integration/vector-multi-erase/README.md @@ -0,0 +1,8 @@ +# 1. Vector Multi-Erase Integration Test + +This directory contains the integration test for multi-element erase behavior in the custom vector implementation. + +## 1.1. Contents + +- `test-Vector-multi-erase.cpp`: Boost.Test source built as `test-Vector-multi-erase`. +- `CMakeLists.txt`: registers the executable. diff --git a/test/integration/xml-parser/README.md b/test/integration/xml-parser/README.md new file mode 100644 index 0000000..8497c37 --- /dev/null +++ b/test/integration/xml-parser/README.md @@ -0,0 +1,8 @@ +# 1. XML Parser Integration Test + +This directory contains the end-to-end integration coverage for the XML parser library. + +## 1.1. Contents + +- `test-xml-parser-e2e.cpp`: Boost.Test executable source built as `test-xml-parser-e2e`. +- `CMakeLists.txt`: links the test against the internal `xmlparser` library. diff --git a/test/performance/README.md b/test/performance/README.md index 5fc041a..3470e3b 100644 --- a/test/performance/README.md +++ b/test/performance/README.md @@ -1,70 +1,11 @@ -# Performance Tests +# 1. Performance Tests -Performance Tests will record statistical data about *Static File* and *Application Server* components. +This directory contains benchmark-oriented targets and measurement notes. -# 1. Global Settings +## 1.1. Contents -Tests include the following subsections: - -- Static File Performance -- Performance under Idle Keep-Alive Connections -- Application Server Dynamic Data -- Proxy Server Performance -- Comparison to Apache2 and nginX external Web-Servers - -All Tests will be primarily done on FalconAS Server using HTTP/1.2 and HTTP/1.1 protocol. - -All Tests will be repeated externally on different web-servers using protocols: - -- HTTP/1.1 -- HTTP/2 - -# 2. External Products - -All Tests will be repeated on the following web-server products: - -- Apache2 Threaded Model -- Apache2 Event Driven Model -- nginX - -# 3. Detailed Workflow (SQL Database) - -1. Insert (TestID, TestIDRepeat) INTO "Test" table -2. Insert Server Test Parameter into "TestParameter" table -3. Write Server XML configuration -4. Start Server -5. Run / Loop Tests, write stat results into C++ structs -6. Insert Test Results into "TestMeasurement" table - -# 4. Test Specs (Google Sheet) - -https://docs.google.com/spreadsheets/d/1Da3KsIfTPGJOpeS1Ns2pHvEU_RpdWwx8kU5Ug-b_ZAE/edit?usp=drive_link - -# 5. Linux Sysctl Values - -- Disable Kernel Scheduler Autogrouping -- Disable Kernel Scheduler Energy Awareness -- Prevent Kernel Scheduler from collection Statistics -- Disable Virtual Memory Subsystem Memory Compaction -- Reduce Virtual Memory Subsystem Memory Swap Behaviour - -```bash - -# Kernel Scheduler Settings -sysctl -w kernel.sched_autogroup_enabled=0 -sysctl -w kernel.sched_energy_aware=0 -sysctl -w kernel.sched_schedstats=0 - -# Disable VM Memeory Compation -sysctl -w vm.compact_unevictable_allowed=0 -sysctl -w vm.compaction_proactiveness=0 - -# Disable Watchdogs -sysctl -w kernel.soft_watchdog=0 -sysctl -w kernel.watchdog=0 - -# Reduce Swappiness -sysctl -w vm.swappiness=0 - -``` +- `00_test-performance-nokeepalive.cpp`: root performance test source collected into the `test-performance` executable. +- [`http-parser/`](./http-parser/): parser wall-clock and memory benchmarks, including recorded CSV result snapshots. +- [`xml-parser/`](./xml-parser/): XML parser benchmark target. +The database notes used to persist benchmark runs are tracked separately in [`../../specs/database/`](../../specs/database/). diff --git a/test/performance/http-parser/README.md b/test/performance/http-parser/README.md new file mode 100644 index 0000000..299fd03 --- /dev/null +++ b/test/performance/http-parser/README.md @@ -0,0 +1,11 @@ +# 1. HTTP Parser Benchmarks + +This directory contains benchmark targets and stored result snapshots for the internal HTTP parser. + +## 1.1. Contents + +- `test-parser-performance.cpp`: wall-clock performance benchmark. +- `test-parser-memory.cpp`: heap-allocation / memory benchmark. +- `results-performance.csv`: recorded parser timing results. +- `results-memory.csv`: recorded parser memory results. +- `CMakeLists.txt`: builds the benchmark executables against `httpparser`. diff --git a/test/performance/xml-parser/README.md b/test/performance/xml-parser/README.md new file mode 100644 index 0000000..15ebf7e --- /dev/null +++ b/test/performance/xml-parser/README.md @@ -0,0 +1,8 @@ +# 1. XML Parser Benchmarks + +This directory contains the benchmark target for the internal XML parser. + +## 1.1. Contents + +- `test-xml-parser-performance.cpp`: XML parser performance benchmark source. +- `CMakeLists.txt`: builds the benchmark executable against `xmlparser`. diff --git a/test/unit/README.md b/test/unit/README.md new file mode 100644 index 0000000..e55c4cf --- /dev/null +++ b/test/unit/README.md @@ -0,0 +1,11 @@ +# 1. Unit Tests + +This directory contains focused tests for individual libraries and low-level helpers. + +## 1.1. Subdirectories + +- [`http-parser/`](./http-parser/): request parsing tests for the internal HTTP parser. +- [`http-generator/`](./http-generator/): response generation tests for the HTTP generator. +- [`memory-alignment/`](./memory-alignment/): checks alignment-related helper behavior. +- [`memory-manager/`](./memory-manager/): tests the custom memory manager. +- [`xml-parser/`](./xml-parser/): unit coverage for the XML parser library, including fuzz-style inputs. diff --git a/test/unit/http-generator/README.md b/test/unit/http-generator/README.md new file mode 100644 index 0000000..0eb8075 --- /dev/null +++ b/test/unit/http-generator/README.md @@ -0,0 +1,8 @@ +# 1. HTTP Generator Unit Tests + +This directory contains unit coverage for the HTTP response / message generation helpers. + +## 1.1. Contents + +- `test-generator-responses.cpp`: Boost.Test executable source built as `test-generator-responses`. +- `CMakeLists.txt`: links the test against the internal `httpparser` static archive, which also contains the HTTP generator helpers. diff --git a/test/unit/http-parser/README.md b/test/unit/http-parser/README.md new file mode 100644 index 0000000..b8e6c61 --- /dev/null +++ b/test/unit/http-parser/README.md @@ -0,0 +1,9 @@ +# 1. HTTP Parser Unit Tests + +This directory contains focused unit coverage for the internal HTTP request parser. + +## 1.1. Contents + +- `test-parser-requests.cpp`: Boost.Test executable source built as `test-parser-requests`. +- `as-get.json`: sample request / payload fixture used by the test set. +- `CMakeLists.txt`: links the test against the internal `httpparser` library. diff --git a/test/unit/memory-alignment/README.md b/test/unit/memory-alignment/README.md new file mode 100644 index 0000000..e69fd0c --- /dev/null +++ b/test/unit/memory-alignment/README.md @@ -0,0 +1,8 @@ +# 1. Memory Alignment Unit Tests + +This directory contains focused tests for alignment-related helper behavior. + +## 1.1. Contents + +- `test-memory-alignment.cpp`: Boost.Test executable source built as `test-memory-alignment`. +- `CMakeLists.txt`: registers the executable and CTest entry. diff --git a/test/unit/memory-manager/README.md b/test/unit/memory-manager/README.md new file mode 100644 index 0000000..bd25a3b --- /dev/null +++ b/test/unit/memory-manager/README.md @@ -0,0 +1,8 @@ +# 1. Memory Manager Unit Tests + +This directory contains focused tests for the custom memory manager helpers. + +## 1.1. Contents + +- `test-memory-manager.cpp`: Boost.Test executable source built as `test-memory-manager`. +- `CMakeLists.txt`: registers the executable and CTest entry. diff --git a/test/unit/xml-parser/README.md b/test/unit/xml-parser/README.md new file mode 100644 index 0000000..f434624 --- /dev/null +++ b/test/unit/xml-parser/README.md @@ -0,0 +1,9 @@ +# 1. XML Parser Unit Tests + +This directory contains focused unit coverage for the internal XML parser library. + +## 1.1. Contents + +- `test-xml-parser.cpp`: primary Boost.Test executable for parser behavior. +- `test-xml-parser-fuzz.cpp`: fuzz-style input coverage for the parser. +- `CMakeLists.txt`: links both executables against the internal `xmlparser` library. diff --git a/www/README.md b/www/README.md index 2a9db81..e64f81e 100644 --- a/www/README.md +++ b/www/README.md @@ -1,4 +1,9 @@ -# WWW Examples +# 1. WWW Example Content -Files used for Examples reside here. +This directory contains the static and dynamic example assets used by the sample FalconAS setup. +## 1.1. Contents + +- `index-app1.html` and `index-app2.html`: example static entry pages for the configured namespaces. +- `WebApp.py`: sample Python application backend. +- `falcon-robotics.jpg` and `favicon.ico`: assets referenced by the example pages.