Spaces:
Sleeping
Sleeping
|
Download docs/TECHNICAL.md from dangkhoa2016/Nodejs-JSON-API-Server: direct link, hf CLI and curl.
- Browser
- Download file 9.96 kB
-
https://huggingface.co/spaces/dangkhoa2016/Nodejs-JSON-API-Server/resolve/42e30c2fc13d198cc76d79446c2a4308bbca4162/docs/TECHNICAL.md
- Command line
-
hf download hf://spaces/dangkhoa2016/Nodejs-JSON-API-Server@42e30c2fc13d198cc76d79446c2a4308bbca4162/docs/TECHNICAL.md
-
curl -L -o TECHNICAL.md https://huggingface.co/spaces/dangkhoa2016/Nodejs-JSON-API-Server/resolve/42e30c2fc13d198cc76d79446c2a4308bbca4162/docs/TECHNICAL.md
9.96 kB
| # Technical Documentation | |
| > π Language / NgΓ΄n ngα»―: **English** | [TiαΊΏng Viα»t](TECHNICAL.vi.md) | |
| > Architecture, implementation notes, and internal design of json-api-server. | |
| ## Architecture | |
| ``` | |
| json-api-server/ | |
| βββ bin/ | |
| β βββ start.js # Entry point β loads .env via src/config/load-env.js, starts server | |
| βββ src/ | |
| β βββ config/ | |
| β β βββ index.js # Centralized config β auto-loads dotenv via load-env.js, exports camelCase | |
| β β βββ load-env.js # Shared dotenv loader β auto-run on require, skips in production | |
| β β βββ runtime-config.js # Thread-safe in-memory config overrides for runtime updates (rate-limit, Redis) | |
| β β βββ setting-defs.js # Setting definitions for 14 env vars (NODE_ENV, PORT, ADMIN_KEY, etc.) | |
| β βββ db/ | |
| β β βββ index.js # SQLite layer (node:sqlite) β CRUD operations (reads config) | |
| β β βββ migrate.js # Table creation (standalone via npm run db:migrate) | |
| β β βββ seed.js # Fetches seed data from JSONPlaceholder API, auto-runs migrate | |
| β β βββ seed-settings.js # Seeds 14 env vars (NODE_ENV, PORT, ADMIN_KEY, etc.) into settings table | |
| β β βββ sql-logger.js # Shared Proxy wrappers β logs exec/prepare/run/get/all to stderr | |
| β βββ middleware/ | |
| β β βββ rate-limiter.js # Rate limiter (Redis/in-memory, circuit breaker, escalating blocks) | |
| β βββ redis/ | |
| β β βββ index.js # Pure-Node Redis client via RESP protocol over TCP | |
| β βββ public/ | |
| β β βββ favicon.ico # Favicon (ICO format) | |
| β β βββ favicon.png # Favicon (PNG format) | |
| β β βββ license.md # Flaticon license file | |
| β βββ server/ | |
| β βββ index.js # HTTP server, graceful shutdown, startup orchestration | |
| β βββ route.js # Route parser, request handlers, admin auth, favicon, runtime config updates | |
| βββ tests/ | |
| β βββ config/ | |
| β β βββ config.test.js # Config defaults and env var branches (9) | |
| β β βββ load-env.test.js # Load-env file loading chain and error paths (7) | |
| β βββ db/ | |
| β β βββ database.test.js # Database CRUD, pagination, search, sort, SQL injection, cascade delete (11) | |
| β β βββ migrate.test.js # Migration success and failure paths (2) | |
| β β βββ seed.test.js # Seed with real DB + mocked deps, JSONPlaceholder fetch (5) | |
| β β βββ sql-logger.test.js # SQL query logger wrapping (5) | |
| β βββ middleware/ | |
| β β βββ rate-limiter.test.js # In-memory, Redis, circuit breaker, proxy IPs, updateConfig (57) | |
| β βββ redis/ | |
| β β βββ redis.test.js # RESP protocol encoding/parsing, constructor options, eval, reconnect (33) | |
| β βββ server/ | |
| β β βββ coverage-printlog.test.js # Printlog and server export V8 coverage (4) | |
| β β βββ graceful-shutdown.test.js # SIGINT/SIGTERM handler coverage (1) | |
| β β βββ index.test.js # Server request handler, admin auth, graceful shutdown (13) | |
| β β βββ integration.test.js # API integration tests β real HTTP + SQLite, runtime PATCH (81) | |
| β β βββ route.test.js # Route parsing, favicon, health, admin auth cache, runtime config (18) | |
| β βββ README.md # Testing documentation (English) | |
| β βββ README.vi.md # Testing documentation (Vietnamese) | |
| β βββ helpers/ | |
| β βββ coverage.js # Test-coverage utilities (save/restore/setEnv/clearCjs/configMockFactory) | |
| β βββ index.js # startServer / stopServer / request utilities | |
| β βββ mock-factory.js # Mock factory helpers (mkDb/mkReq/mkRes/mkRedis/mkSettingsTable) | |
| β βββ seed.js # Standalone script to create & seed temp DB | |
| β βββ seed-settings-coverage.test.js # Seed-settings.js V8 coverage (4) | |
| βββ manual/ | |
| β βββ admin.sh # Admin panel curl commands | |
| β βββ albums.sh # Albums endpoints | |
| β βββ comments.sh # Comments endpoints | |
| β βββ curl.sh # Quick curl commands | |
| β βββ health.sh # Health endpoint | |
| β βββ inspect-queries.sql # SQL queries for database inspection | |
| β βββ inspect.sh # Database inspection script | |
| β βββ inspect-docker-data.sh # Docker data inspection script | |
| β βββ photos.sh # Photos endpoints | |
| β βββ posts.sh # Posts endpoints | |
| β βββ todos.sh # Todos endpoints | |
| β βββ users.sh # Users endpoints | |
| βββ manual-test-coverage/ | |
| β βββ README.md # Coverage verification documentation | |
| β βββ verify-commit-coverage.sh # Coverage verification script | |
| βββ Dockerfile # Docker image definition | |
| βββ docker-entrypoint.sh # Container entrypoint script | |
| βββ .dockerignore # Docker ignore rules | |
| βββ storage/ # SQLite database files (auto-created) | |
| βββ temp/ # Temporary files (gitignored) | |
| βββ .env # Base configuration (tried first in development β highest priority) | |
| βββ .env.dev # Development fallback (tried if .env not found) | |
| βββ .env.test # Test configuration (port 3001, separate DB, no rate limit) | |
| βββ .env.prod.example # Production template (copy to .env.prod) | |
| βββ .env.example # Reference for all available variables | |
| βββ package.json # Metadata and scripts | |
| βββ LICENSE # MIT license | |
| βββ README.md # Documentation (English) | |
| βββ README.vi.md # Documentation (Vietnamese) | |
| βββ .gitignore # Git ignore rules | |
| βββ vitest.config.js # Vitest test runner configuration | |
| ``` | |
| ### Startup Flow | |
| ``` | |
| bin/start.js β src/config/load-env.js (loads .env per NODE_ENV, skipped in production) | |
| β src/server/index.js | |
| βββ src/config/index.js (centralized config, auto-loads dotenv) | |
| βββ src/db/index.js (SQLite CRUD) | |
| βββ src/redis/index.js (pure RESP + AUTH + URL) | |
| βββ src/middleware/rate-limiter.js (Redis || in-memory, circuit breaker, escalating blocks) | |
| # Standalone scripts: npm run db:migrate / npm run db:seed / npm run db:setup (config loads dotenv automatically) | |
| ``` | |
| ### Request Flow | |
| ``` | |
| HTTP Request β CORS headers β Rate limiter β Route parser β Handler β JSON Response | |
| ``` | |
| --- | |
| ## Implementation Notes | |
| - **Minimal runtime dependencies** β only `argon2` for admin password hashing; everything else uses Node.js built-in modules (`http`, `url`, `fs`, `path`, `net`, `node:sqlite`). `dotenv` is a dev dependency. | |
| - **Pure RESP protocol** β the Redis client in `src/redis/index.js` implements the Redis serialization protocol over raw TCP sockets without any third-party library. Supports `AUTH` password authentication and `REDIS_URL` connection strings. | |
| - **Centralized config** β all environment variables are read in `src/config/index.js` and exported as camelCase (`port`, `dbPath`, `redisOpts`, `rateLimitMax`, `dbDebugSql`, `sensitiveKeys`, etc.) for use across the codebase. | |
| - **Rate limiter** β `src/middleware/rate-limiter.js` features a circuit breaker for Redis failures, CIDR-based trusted proxy IP extraction, escalating block durations (5m β 20m β 1h), atomic Redis Lua scripts, and an in-memory fallback with LRU eviction. `createRateLimiter()` accepts options directly instead of reading config lazily. | |
| - **Runtime configuration** β Patching rate-limit or Redis settings via the admin API immediately applies changes through `RuntimeConfig` (in-memory overrides), avoiding server restarts. Rate-limit hot-swapping uses `rateLimiter.updateConfig()`; Redis reconnection uses `Redis.reconnect()`. | |
| - **Testable seed script** β `src/db/seed.js` accepts `database` and `fetch` parameters via dependency injection, enabling full unit testing without mocking `require()`. | |
| - **SQL query logging** β `src/db/sql-logger.js` exports `wrapDb`/`wrapStmt` Proxy wrappers that log `exec`, `prepare`, `run`, `get`, and `all` calls to stderr. `src/db/index.js` uses them via `getWrappedDb()` when `DEBUG_SQL=true`. | |
| - **Multi-environment** β `src/config/index.js` requires `src/config/load-env.js` at module level, which chain-loads all dotenv files in priority order with `override: false` β existing `process.env` values and earlier files take precedence over later ones. Every consumer (server, migrate, seed) simply requires `src/config/index.js` and gets correct env values. In production, dotenv is skipped entirely β env vars must come from the deployment environment. | |
| - **SQL injection prevention** β `src/db/index.js` validates `_sort` against a whitelist of known columns and quotes identifiers with `""`; LIKE wildcards (`%`, `_`) are escaped to prevent injection through the `q` parameter | |
| - **Argon2 auth cache** β `src/server/route.js` caches `ADMIN_KEY` verification results in a `Map` with 5-second TTL and 1,000-entry limit, avoiding repeated argon2 hashing on burst admin requests | |
| - **CORS** enabled on all routes | |
| - **Graceful shutdown** β handles `SIGINT` and `SIGTERM` to close the server and Redis connection cleanly | |