Spaces:
Sleeping
Sleeping
File size: 9,955 Bytes
42e30c2 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 | # 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
|