From 45172ae182feb4794b158b2976ec6f10f7914b3e Mon Sep 17 00:00:00 2001 From: Andrew Noyes Date: Tue, 19 Aug 2025 14:03:22 -0400 Subject: [PATCH] Remove http.md --- http.md | 151 -------------------------------------------------------- 1 file changed, 151 deletions(-) delete mode 100644 http.md diff --git a/http.md b/http.md deleted file mode 100644 index 8d9d6e3..0000000 --- a/http.md +++ /dev/null @@ -1,151 +0,0 @@ -# HTTP Server Design - -## Overview - -High-performance HTTP server implementation for WeaselDB using epoll-based event loop architecture with configurable threading model and lock-free communication between components. - -## Architecture - -### Threading Model - -#### Accept Threads -- **Configurable number** of dedicated accept threads -- Each thread calls `accept` in a loop on listening socket -- `accept` returns file descriptor used to construct connection object -- Connection posted to epoll with **EPOLLIN | EPOLLONESHOT** interest - -#### Network Threads -- **Configurable number** of network I/O threads -- Each thread calls **epoll_wait()** to receive connection ownership -- **EPOLLONESHOT** ensures clean ownership transfer without thundering herd -- Handle connection state transitions and HTTP protocol processing -- Either respond directly or post the connection to a service - -#### Service Threads -- **Service Pipelines** (e.g., commit and status can share pipeline) -- **Dequeue connections** from shared LMAX Disruptor inspired ring buffer `src/ThreadPipeline.h` -- Process business logic and generate responses -- **Post completed connections** back to epoll for response writing - -### Connection Lifecycle - -1. **Accept**: Accept thread creates connection, posts to epoll with read interest -2. **Read**: Network thread reads data, pumps llhttp streaming parser -3. **Route**: Complete request path triggers handler association -4. **Process**: Handler either: - - Processes in network thread (fast path) - - Posts to service ring buffer (slow path) -5. **Respond**: Connection posted to epoll with write interest -6. **Write**: Network thread writes response data -7. **Keep-alive**: Connection posted back with read interest for next request - -### HTTP Protocol Support - -#### Request Processing -- **llhttp streaming parser** for incremental request parsing -- **Content-Type based routing** to appropriate service handlers -- **HTTP/1.1 keep-alive support** for connection reuse -- **Malformed request handling** with proper HTTP error responses - -#### Response Handling -- **Direct response writing** by network threads -- **Partial write support** with epoll re-registration -- **Connection reuse** after complete response transmission - -### Memory Management - -#### Arena Allocation -- **Per-connection arena allocator** for request-scoped memory -- **Arena reset after each response** to prepare for next request -- **Zero-copy string views** pointing to arena-allocated memory -- **Efficient bulk deallocation** when connection closes - -#### Ring Buffer Communication -- **Ring buffer** for high-performance inter-thread communication -- **Backpressure handling** via ring buffer capacity limits - -### Error Handling - -#### Backpressure Response -- **Ring buffer full**: Network thread writes immediate error response -- **Partial write**: Connection re-posted to epoll with write interest -- **Connections are rejected** if there are too many concurrent connections. - Tries to maintain a configurable limit (best effort only.) - -#### Protocol Errors -- **Malformed HTTP**: Proper HTTP error responses (400 Bad Request, etc.) -- **Partial I/O**: Re-registration with epoll for completion -- **Client disconnection**: Clean up connection state - -## Integration Points - -### Parser Selection -- **Content-Type header inspection** for parser routing -- **CommitRequestParser extensibility** for future format support (protobuf, msgpack) - -### Configuration System -- **TOML configuration** using existing config system -- **Configurable parameters**: - - Accept thread count - - Network thread count - - Ring buffer sizes - - Connection timeouts - - Keep-alive settings - -### Request Routing -- **Path-based routing** to service handlers -- **Handler registration** for extensible endpoint support - -## Performance Characteristics - -### Scalability -- **Configurable parallelism** for accept and network operations -- **Lock-free communication** eliminates contention bottlenecks -- **EPOLLONESHOT semantics** prevent thundering herd effects and manages connection ownership - -### Efficiency -- **Zero-copy I/O** where possible using string views -- **Arena allocation** eliminates per-request malloc overhead -- **Connection reuse** reduces accept/close syscall overhead -- **Streaming parser** handles large requests incrementally - -### Resource Management -- **Bounded memory usage** via arena reset and ring buffer limits -- **Graceful backpressure** prevents resource exhaustion - -## Implementation Phases - -### Phase 1: Core Infrastructure -- Basic epoll event loop with accept/network threads -- Connection state management and lifecycle -- llhttp integration for request parsing - -### Phase 2: Service Integration -- Request routing and handler registration -- Arena-based memory management - -### Phase 3: Protocol Features -- HTTP/1.1 keep-alive support -- Error handling and backpressure responses -- Configuration system integration - -### Phase 4: Content Handling -- Content-Type based parser selection -- CommitRequest processing integration -- Response serialization and transmission - -## Configuration Schema - -```toml -[http] -accept_threads = 2 -network_threads = 8 -bind_address = "0.0.0.0" -port = 8080 -keepalive_timeout_sec = 30 -request_timeout_sec = 10 - -[http.pipelines.commit_status] -ring_buffer_size = 1024 -threads = 4 -```