How engwan/qcgi works
Project Type and Purpose
• This is a full‐stack, server‐side web preprocessor written in C++. Its role is to parse qCGI tags in incoming HTTP requests (via FastCGI), interpret them by offloading logic to an SQL server, manage session state in SQLite, and produce HTML output.
• It’s a proof‐of‐concept toy implementation intended for educational purposes.
File Structure Analysis
• Top level:
• README.md – project description, dependencies, syntax overview
• qcgi+ – (presumably the build/install script or executable placeholder)
• src/ – all C++ source code
• test.v – sample qCGI template demonstrating syntax
• src/:
• Makefile – build instructions linking against MySQL, SQLite3, FastCGI, RudeCGI, Boost.Regex
• qcgi+.cpp – main entrypoint, FastCGI loop, integration with RudeCGI
• parser.{cpp,h} – tokenization and parsing of {.…} tags (uses Boost.Regex)
• interpreter.{cpp,h} – AST walker, translates parsed nodes into SQL queries and HTML fragments
• db.{cpp,h} – MySQL client wrapper for running logic queries
• sessions.{cpp,h} – SQLite wrapper to store session data
• utils.{cpp,h} – helper functions for escaping, string manipulation, etc.
Key Architectural Patterns
• Modular layering inside one process: separation of concern between parsing, interpretation, database I/O, session management, and request handling.
• Single FastCGI worker process model: persistent process handles multiple requests.
• Interpreter pattern (AST + visitation) for implementing qCGI logic constructs.
• Adapter/wrapper pattern for DB clients (MySQL and SQLite).
Main Components
a. External Actors
• Web Client (browser)
• Web Server (e.g., Apache/nginx + fcgid or mod_fcgid)
b. Core System (FastCGI App)
1. FastCGI Listener (qcgi+.cpp + RudeCGI)
2. Parser Module (parser.cpp/h + Boost.Regex)
3. Interpreter Module (interpreter.cpp/h)
4. Database Layer
– MySQL Client (db.cpp/h) for business logic & flow control
– SQLite Client (sessions.cpp/h) for session persistence
5. Utilities (utils.cpp/h)
c. Supporting Artifacts
• qCGI Template Files (e.g., test.v)
• Build System (Makefile, gcc, linking libraries)
Component Interactions
• HTTP Request from Web Client → Web Server → FastCGI Listener
• FastCGI Listener uses RudeCGI to parse HTTP headers & body
• Template content scanned by Parser → emits AST or intermediate tokens
• Interpreter consumes AST, issues SQL queries via MySQL client to implement logic (if/else, loops)
• Interpreter reads/writes session state via SQLite client
• Interpreter emits dynamic HTML output → FastCGI Listener returns HTTP Response
• Build interactions: Makefile links correct libraries; hardcoded config parameters in db.cpp/h