docs: define MoloApp C++23 framework plan

Scope covers HTTP/1.1+HTTP/2, WebSockets, Socket.IO, ORM with
prod self-healing, realtime clients, observability, supervisor,
AI harness CLI, and living example project.

plan.md

@@ -0,0 +1,154 @@
+## MoloApp - C++ Web Application Framework
+
+### 1. Vision
+
+A full-stack, batteries-included, extremely object-oriented C++ web framework.
+Scope is closer to FastAPI + Django + aiohttp + a bit of Next.js/Realtime
+than to a thin HTTP layer.
+
+Native C++23 only (ISO/IEC 14882:2024, reference toolchains GCC 16+, Clang 22+,
+MSVC VS2026 or newer): standard library plus OS syscalls plus wolfSSL for TLS
+as the sole third-party dependency. Everything else (event loop, HTTP stack,
+crypto, compression, Postgres wire protocol, SQLite handling, templating, all
+clients) is implemented in-house. Components are isolated behind declared
+interfaces but DRY integrated through one shared core, never reimplemented per
+feature. C++26 stays excluded until published and stably supported.
+
+### 2. Core feature set (v1 definition)
+
+- Pubsub system
+- Key-value store
+- ORM with dual backends (Postgres and SQLite), auto-sync tables in dev and production, automatic self-healing of schema mismatches from DB errors
+- Session management
+- Base64 auth + full authentication and permission system
+- Static routes with path traversal protection, servable from disk or from embedded C++ assets
+- Asset embedder CLI: converts a static files directory (assets, templates, all files) into a C++ source file served as a static route, so applications build with everything embedded
+- AI vibe-coding harness CLI (OpenAI-compatible): smart prompting over framework features and preferences, able to build complete applications; completions base URL https://devplace.net/openai/v1, model molodetz, key from DEVPLACE_API_KEY env variable, streaming support, built on the framework HTTP client
+- Caching layer
+- Jinja-like HTML templating (responsive by default, mobile-first): template inheritance with extends and blocks, includes, if statements, for loops, filters, auto-escaping with explicit safe opt-out, reusable environment object holding loaders, filters, tests and globals
+- REST standards
+- Field validation framework (Pydantic-style)
+- Form framework built on the validation framework, parses JSON and HTML form posts
+- Request object providing GET and POST data
+- WebDAV HTTP methods (server) + WebDAV client able to stream directly through an HTTP response, with built-in caching and quota
+- Class-based views (aiohttp-style)
+- Routers (FastAPI-style) for building large applications
+- Main application class
+- Application chaining: apps can be sub-applications of others with automatic path merging, e.g. mounting three identical apps under each other gives `/app1/app1/app1`
+- Env parser: automatically loads `.env.json` from root/workdir if present, plus environment variable overrides and typed validated config objects
+- Middleware system
+- Password hashing system + generic encrypt/decrypt functionality with clear key hierarchy (Argon2id for passwords, AES-GCM or ChaCha20-Poly1305 for data)
+- Logging system used everywhere, with predefined log format and rules per log level, structured logging, correlation/request IDs flowing through middleware, ORM and replication
+- Event framework built on the pubsub system (typed event objects, sync and async listeners, lifecycle and domain events)
+- Metrics framework (counters, gauges, histograms, timers, per-route and per-query metrics)
+- Complete telemetry (distributed tracing, spans, request correlation, log plus metrics linkage)
+- Zero-cost observability: events, metrics and telemetry compile to near-zero overhead when disabled, so instrumentation stays everywhere and collects like a maniac
+- Non-blocking I/O everywhere
+- Built-in replication/sync functionality for objects, websockets, everything data related
+- File upload support
+- Process supervisor and task system (supervised workers, delayed/periodic/retry jobs, full CLI management)
+- WebSockets: class-based views, responses and handlers, router-mounted, plus a matching WebSocket client
+- Socket.IO protocol (namespaces, rooms, events, long-polling fallback): server plus a matching Socket.IO client
+- Client parity rule: everything the framework serves also ships a client (HTTP/REST, WebSocket, Socket.IO, SSE, WebDAV)
+- Response formats: HTML, JSON, XML, plain text and others, with content negotiation
+- Streaming responses and passthrough streaming (proxy or generate bodies without full buffering)
+- Modern async HTTP/API/REST client with HTTP/1.1 and HTTP/2 support (pooling, retries, timeouts, JSON/XML/form handling, file upload, streaming, test double)
+
+### 3. Core runtime and HTTP fundamentals
+
+- Event loop / async model: custom reactor built in-house on OS primitives (epoll, kqueue, IOCP), no external loop library. Documented. Coroutine (`co_await`) based handlers, callback interop where needed, clear thread-safety rules, defined way to schedule blocking work off the loop.
+- Connection and request lifecycle: idle/header/body timeouts, keep-alive, max concurrent connections, backpressure, graceful shutdown, signal handling.
+- HTTP/1.1 and HTTP/2 fully supported (H2 over TLS with ALPN plus h2c cleartext, multiplexed streams, HPACK, flow control), designed path to HTTP/3.
+- Response compression: gzip and Brotli with content-type and size thresholds, both codecs implemented in-house.
+- Static file serving: ETags / Last-Modified, cache-control headers, range requests, directory indexing configurable (default off).
+- First-class cookies: signed/encrypted cookies, SameSite, Secure, HttpOnly, domain/path options. Sessions and auth build on this.
+- Every runtime knob gets a hard cap: rates, sizes, counts, intervals, memory. Static ceilings, no magic autotuning.
+
+### 4. Security
+
+Framework ships secure by default. Every item below is specified, not optional
+folk knowledge:
+
+- CSRF protection for cookie-based sessions and form posts
+- CORS middleware with safe defaults and easy override
+- Security headers middleware: HSTS, X-Frame-Options / CSP, X-Content-Type-Options, Referrer-Policy, Permissions-Policy
+- Rate limiting / throttling: per-IP, per-user, per-route
+- Input size limits: request body, header size, file upload size, number of form fields, JSON depth
+- Session security: rotation on privilege change, absolute + idle timeouts, pluggable storage (in-memory, Redis-like, DB)
+- ORM query safety: parameterized queries only, raw string concatenation hard or impossible by default (SQL injection safe)
+- File upload safety: content-type validation, extension allow-lists, temp file handling, quotas, virus scan hook
+- Secrets management: loading and rotation story for passwords, API keys, encryption keys
+- XSS-safe templating defaults (auto-escaping), path traversal protection
+- TLS via wolfSSL (sole dependency exception, commercial license for closed-source use), natively compiled, TLS 1.3
+
+### 5. Data layer and ORM
+
+- Auto-sync tables in dev and production: when Postgres or SQLite reports a schema mismatch (wrong field type, too short length, missing column or table, or similar), the ORM automatically resolves it the right way (widen types, extend lengths, add columns and tables) and retries; migration generation is kept for review and audit.
+- Connection pooling for Postgres and SQLite (WAL mode, documented locking behavior); both drivers dependency-free with own Postgres wire-protocol client and own SQLite handling, no external driver libraries.
+- Transactions with clear async semantics.
+- Type-safe relations, joins, query builder where possible.
+- Cache integration: explicit invalidation hooks so ORM, key-value store and pubsub stay consistent, including under replication.
+- Schema evolution rules defined under structure-driven development and isolation rules.
+
+### 6. Request / response / routing polish
+
+- Path, query and body binding through the single validation framework.
+- Response formats and content negotiation: HTML, JSON, XML, plain text, form posts, file downloads; Accept header plus explicit format selection, one response object hierarchy with a subclass per format.
+- Streaming and passthrough responses: chunked and SSE streaming, file and upstream passthrough with backpressure, range and conditional request support.
+- Modern HTTP/API/REST client: HTTP/1.1 and HTTP/2, same timeout, retry, auth, cookie, proxy, TLS and logging behavior as the server side; sync and async usage from handlers, tasks and CLI; mockable transport for tests.
+- Matching clients for every realtime protocol: WebSocket client and Socket.IO client with the same auth, session, logging, reconnect and backoff behavior; usable from handlers, tasks, CLI and tests.
+- Redirects (permanent vs temporary) and flash messages (session-based one-time messages).
+- Dependency injection (or documented service-sharing pattern) for DB, cache, auth without globals.
+- Error handling hierarchy: exception types mapping to HTTP status codes, structured error responses (JSON for APIs, HTML for browsers), global exception handler.
+- OpenAPI / Swagger generation from routers + validation models.
+- Plugin / extension mechanism so users extend core without forking.
+
+### 7. Realtime, background work and replication
+
+- Native WebSocket and SSE support participating in the same middleware, auth and session system; WebSockets exposed as class-based views, responses and handlers mounted on routers.
+- WebSocket client plus SSE client for consuming own and third-party endpoints, sharing config, auth and logging with the server side.
+- Socket.IO protocol support on top of WebSockets: namespaces, rooms, event dispatch, acknowledgements, broadcast, long-polling fallback, same auth/session/middleware/logging path as plain WebSockets; plus a matching Socket.IO client with the same event, room and namespace API.
+- Replication semantics explicitly specified: conflict model (optimistic locking / LWW / CRDT / conflict hooks), consistency guarantees, failure behavior.
+- Process supervisor plus tasks framework: supervised worker processes with restarts, health checks and graceful shutdown; job queue with delayed, periodic and retry work that never blocks request handlers; in-process by default, optional external backends; every worker and task observable through events, metrics and telemetry.
+- Pubsub durability and delivery guarantees documented.
+- Multi-process / multi-instance deployment story: how sessions, pubsub and key-value state are shared.
+
+### 8. Developer experience and operations
+
+- Dev server with fast restart (hot reload where feasible), strict dev vs production settings split.
+- Test client: requests without real network, DB/ORM fixtures, time freezing.
+- Integration testing only, through the real stack (real HTTP, real routing, real middleware, real DB): no isolated unit tests, every test exercises a URL end to end.
+- Predefined test structure mirroring the app: test file location and naming reflect the URLs, paths and routers under test (one structured place per route), with fixed templates for cases, fixtures and assertions.
+- Health and readiness endpoints, metrics export (Prometheus format and OpenTelemetry), trace export, event stream inspection; all observability paths zero-cost when disabled with static caps on cardinality, buffer sizes and export rates.
+- CLI provides all project tooling: new-project scaffolding with Makefile, AGENTS.md for autonomous development, default directory structure, plug and play example files, .env.json, .gitignore and git init; generate migrations, run server, drive versioning/tagging flow; full supervisor and task management (start, stop, restart, scale, status, logs, enqueue, retry, cancel, inspect) with structured output for scripts; embed static asset directories into C++ source for fully embedded builds; AI harness mode for vibe-coding complete applications against the DevPlace endpoint with streaming.
+- i18n hooks, CSP builder for HTML templating.
+- Big living example project demonstrating every framework feature (routing, views, routers, ORM both backends, auth, sessions, forms, validation, templates, response formats, streaming/passthrough, WebSockets + Socket.IO, pubsub, events, metrics, telemetry, KV, cache, uploads, WebDAV, replication, supervisor plus background tasks, REST client, OpenAPI, embedded static assets, AI harness CLI, structured integration tests): kept compiling and green as part of the normal workflow, automatically extended or updated with every feature change, used as manual verification target after deploy.
+
+### 9. Project workflow: structure-driven, AI-driven, autonomous
+
+This project is developed structure-first with minimal manual intervention.
+An AI agent keeps the tree consistent following `AGENTS.md`.
+
+- Structure-driven development: literally everything gets a specification declared somewhere (spec per component) to keep components consistent.
+- Isolation rules: components depend only on declared interfaces, no duplicate logic, no cross-layer imports outside the spec; isolated components, DRY integrated through the shared core.
+- Sensible defaults everywhere; user-facing simplicity is a release gate.
+- Consistent documentation using templates; docs state what the system does today, gaps listed next to the code that closes them.
+- `AGENTS.md` describes the full automated workflow: build, test, lint, docs update, version bump, commit, tag, deploy, verify.
+- Autonomous git management: the AI agent commits, branches, tags and releases by rule, not by asking. Conventional commits, changelog generated from commits, version bumped and tagged automatically after defined change classes (feature/fix/breaking), deploy then verify live in the same session. Humans intervene on conflicts, floor hits (protected paths, retention windows, destructive ops), and release failures. Destructive git ops (history rewrite, force push, hard reset) are never autonomous: dry-run + explicit human confirmation.
+- Versioning documentation + changelog kept in-repo and updated by the same automated flow.
+- Commit/deploy/verify in that order, same session. A change that is not running is not done.
+- After behavior changes the suite runs; after deploys, live verification confirms green.
+- Responsive-by-default rule: every shipped template, example UI and generated page works on small phones; big button groups collapse to dropdowns or equivalent.
+- Living example project is part of the process: no feature is done until the example demonstrates it, its spec and docs are updated, and the example suite passes in the same session.
+- Architecture style is strictly DRY, plug and play, and extremely object-oriented: shared behavior lives in exactly one base class or component, features compose through declared interfaces, no copy-paste variants.
+- Deep structure over flat files: code is organized in depth over many small files and namespaces (one class or concern per file), never one level of giant files.
+
+### 10. Suggested build order
+
+1. Event loop + request lifecycle + timeouts + compression + cookies + full HTTP/1.1 and HTTP/2 + zero-cost events/metrics/telemetry backbone.
+2. CSRF, CORS, security headers, rate limiting, body limits.
+3. Migrations + connection pooling + transactions alongside auto-sync with production self-healing.
+4. WebSocket views/handlers plus WebSocket/SSE/Socket.IO clients on shared auth/middleware + streaming/passthrough responses + response formats + minimal supervisor plus task runner with CLI.
+5. OpenAPI generation, test client, modern HTTP/API/REST client, dev server / CLI experience.
+6. Replication/sync semantics and conflict handling.
+7. Autonomous git/versioning/changelog pipeline + `AGENTS.md` + docs templates + big living example project updated with every feature.