How unf0r9et/ceptember works
1. Overall shape
CEPTEMBER is a small C++ HTTP micro-framework built around the Linux socket API. The repo is split into a reusable core/ framework layer and an application layer under src/main/ that defines the actual route handlers.
2. Startup and server runtime
src/main/main.cpp is the entry point. It boots the server engine in core/engine/engine.cpp, which is the central runtime component responsible for accepting connections and driving the request/response flow.
3. Request lifecycle
Raw network data is parsed into a requestEntity object. That entity is the shared request model used by the rest of the stack: method, path, headers, and body. The README notes that oversized bodies can be moved to disk, with the body field then holding a file path instead of inline bytes.
4. HTTP parsing layer
Parsing is handled by core/parser/ and includes two important pieces: picoHttpParser for HTTP message parsing and MultipartParser for multipart/form-data. This layer turns socket input into structured request data and is the main boundary between transport bytes and application logic.
5. Dispatch and routing
core/httpController/httpController.cpp routes requests by HTTP method. The method-specific entry points are methods_GET, methods_POST, methods_PUT, and methods_DELETE, which are implemented in src/main/handlers/*.cpp. Routing within handlers uses a custom hashed-string switch mechanism, so path-based dispatch is compile-time-friendly and avoids chained string comparisons.
6. Application handler layer
The four files in src/main/handlers/ are the user extension points. They contain the project-specific business logic for each verb and decide how to respond to a given path. The README’s example shows handlers reading from a thread-local rqEntity, so per-request state is exposed directly to handler code.
7. Static file serving
Static content is handled separately by core/staticHandler/staticHandler.cpp and its related file-search/read helpers. The framework is designed to map URL paths to directories under static/, so HTML/CSS/JS are treated as a distinct serving path from API-style request handlers.
8. File upload and large-body processing
There is a dedicated upload/storage subsystem: fileSaver, MultipartParser, requestBodiesWorker, and the type-specific workers under core/utils/workers/ (photoWorker, videoWorker, txtWorker, docsWorker). This suggests the framework can classify incoming content and persist it appropriately rather than keeping all uploads in memory.
9. Filesystem helpers
File I/O is factored into reusable helpers: fileReader, fileWriter, fileSearch, and deleteFile. These are used by both static serving and upload persistence, which keeps low-level filesystem concerns out of the request handlers.
10. Response construction
Responses are built through two layers: basicResponse provides standard canned HTTP responses such as 404/405, while responseBuilder assembles custom responses with headers, status, content type, and optional binary attachments. This cleanly separates simple error responses from dynamic or file-backed responses.
11. Core API vs internal implementation
core/publicHeaders/ exposes the framework-facing API (engine.hpp, httpController.hpp, requestEntity.hpp, responseBuilder.hpp, fileSaver.hpp, logger.hpp). core/internalHeaders/ contains implementation details used by the framework itself. That boundary is important for diagramming: application code depends on the public headers, while the parser/workers/storage internals stay inside the core.
12. Cross-cutting concerns
core/logger/logger.cpp provides logging, and core/raindrop.hpp appears to act as an umbrella include for framework internals. The build is managed with CMakeLists.txt, so the project is packaged as a native C++ service rather than a web framework deployed on a separate runtime.
13. Key architecture takeaway
The main flow is: socket input → HTTP parsing → requestEntity → method dispatch in httpController → route handler → static/file/response utilities → serialized HTTP response back to the client. The main boundaries are transport/parsing, request dispatch, filesystem/file upload handling, and response construction.
Main entry points: engine.hpp Public API · requestBodiesWorker.cpp Body worker · GET.cpp Route handlers · engine.cpp Engine
Components 21
Build & support
Project packaging and cross-cutting support
- Logger · Cross-cutting logging facility for framework activity.
core/logger/logger.cpp
Framework core
HTTP runtime, parsing, routing, storage, and response utilities
- Engine · Central server loop that accepts connections and drives request handling.
core/engine/engine.cpp - HTTP controller · Routes requests by HTTP method into the application handler layer.
core/httpController/httpController.cpp - Parser · Converts raw socket input into structured request data.
core/parser/parser.cpp - HTTP parser · Parses HTTP messages and headers from the network stream.
core/parser/picoHttpParser/picoHttpParser.c - Multipart parser · Extracts multipart/form-data payloads for uploads.
core/parser/MultipartParser/MultipartParser.cpp - Request entity · Shared request state for method, path, headers, and body.
core/publicHeaders/requestEntity.hpp - Static handler · Maps URL paths to files and serves static assets.
core/staticHandler/staticHandler.cpp - Response builder · Builds custom HTTP responses, headers, and attachments.
core/utils/responseBuilder/responseBuilder.cpp - Basic responses · Provides standard responses such as 404 and 405.
core/publicHeaders/basicResponse.h - File saver · Persists uploaded content and large request bodies to disk.
core/utils/fileSaver/fileSaver.cpp - Body worker · Coordinates classification and handling of incoming request bodies.
core/utils/workers/requestBodiesWorker/requestBodiesWorker.cpp - Photo worker · Handles image-oriented upload persistence and processing.
core/utils/workers/photoWorker/photoWorker.cpp - Video worker · Handles video-oriented upload persistence and processing.
core/utils/workers/videoWorker/videoWorker.cpp - Text worker · Handles text upload persistence and processing.
core/utils/workers/txtWorker/txtWorker.cpp - Docs worker · Handles document upload persistence and processing.
core/utils/workers/docsWorker/docsWorker.cpp - File IO · Shared file read, write, and search helpers used by serving and upload paths.
core/utils/workers/fileWorker/fileReader.cpp - Public API · Framework-facing headers exposed to application code.
core/publicHeaders/engine.hpp - Internal headers · Implementation-only headers for parsing, storage, and workers.
core/internalHeaders/parser.hpp
Application layer
Project-specific entrypoint and route handlers
- Main · Starts the server process and hands control to the framework engine.
src/main/main.cpp - Route handlers · Verb-specific application logic for GET, POST, PUT, and DELETE.
src/main/handlers/GET.cpp
Connections 30
- Main → Engine: boots · Application startup transfers control into the server runtime.
- Engine → Parser: parses · Runtime sends raw network data into the request parsing pipeline.
- Parser → HTTP parser: uses · Core parser delegates HTTP message parsing to the low-level HTTP parser.
- Parser → Multipart parser: uses · Core parser delegates multipart form parsing to the multipart parser.
- Parser → Request entity: builds · Parsed request data is assembled into the shared request model.
- Engine → HTTP controller: dispatches · Completed requests are routed into method-based dispatch.
- HTTP controller → Route handlers: calls · Dispatcher invokes the application-defined verb handlers.
- Route handlers → Response builder: creates · Handlers construct custom responses for successful and dynamic outcomes.
- Route handlers → Basic responses: returns · Handlers can emit canned error or fallback responses.
- Route handlers → Static handler: serves · Handlers may route file-like paths through the static serving path.
- Route handlers → File saver: stores · Handlers can persist uploads or large bodies through the storage path.
- File saver → Body worker: delegates · Upload persistence is coordinated by request-body processing workers.
- Body worker → Photo worker: classifies · Media-specific handling for images.
- Body worker → Video worker: classifies · Media-specific handling for videos.
- Body worker → Text worker: classifies · Media-specific handling for text payloads.
- Body worker → Docs worker: classifies · Media-specific handling for document payloads.
- Static handler → File IO: reads · Static serving relies on shared filesystem read/search helpers.
- File saver → File IO: writes · Upload persistence uses shared filesystem read/write helpers.
- Response builder → Basic responses: reuses · Custom response assembly can fall back to canned responses.
- Engine → Logger: logs · Runtime events and errors are reported through the logger.
- Public API → Engine: exposes · Public headers expose the server engine interface to application code.
- Public API → HTTP controller: exposes · Public headers expose dispatch interfaces to application code.
- Public API → Request entity: exposes · Public headers expose the request model to handlers.
- Public API → Response builder: exposes · Public headers expose response construction APIs.
- Public API → File saver: exposes · Public headers expose upload/storage APIs.
- Public API → Logger: exposes · Public headers expose logging APIs.
- Internal headers → Parser: supports · Internal headers define parser internals and shared declarations.
- Internal headers → Static handler: supports · Internal headers define static serving internals.
- Internal headers → File IO: supports · Internal headers define filesystem helper declarations.
- Internal headers → Body worker: supports · Internal headers define body-processing worker internals.