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