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/main/docs/TECHNICAL.md
- Command line
-
hf download hf://spaces/dangkhoa2016/Nodejs-JSON-API-Server/docs/TECHNICAL.md
-
curl -L -o TECHNICAL.md https://huggingface.co/spaces/dangkhoa2016/Nodejs-JSON-API-Server/resolve/main/docs/TECHNICAL.md
9.96 kB
Technical Documentation
π Language / NgΓ΄n ngα»―: English | TiαΊΏng Viα»t
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
argon2for admin password hashing; everything else uses Node.js built-in modules (http,url,fs,path,net,node:sqlite).dotenvis a dev dependency. - Pure RESP protocol β the Redis client in
src/redis/index.jsimplements the Redis serialization protocol over raw TCP sockets without any third-party library. SupportsAUTHpassword authentication andREDIS_URLconnection strings. - Centralized config β all environment variables are read in
src/config/index.jsand exported as camelCase (port,dbPath,redisOpts,rateLimitMax,dbDebugSql,sensitiveKeys, etc.) for use across the codebase. - Rate limiter β
src/middleware/rate-limiter.jsfeatures 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 usesrateLimiter.updateConfig(); Redis reconnection usesRedis.reconnect(). - Testable seed script β
src/db/seed.jsacceptsdatabaseandfetchparameters via dependency injection, enabling full unit testing without mockingrequire(). - SQL query logging β
src/db/sql-logger.jsexportswrapDb/wrapStmtProxy wrappers that logexec,prepare,run,get, andallcalls to stderr.src/db/index.jsuses them viagetWrappedDb()whenDEBUG_SQL=true. - Multi-environment β
src/config/index.jsrequiressrc/config/load-env.jsat module level, which chain-loads all dotenv files in priority order withoverride: falseβ existingprocess.envvalues and earlier files take precedence over later ones. Every consumer (server, migrate, seed) simply requiressrc/config/index.jsand gets correct env values. In production, dotenv is skipped entirely β env vars must come from the deployment environment. - SQL injection prevention β
src/db/index.jsvalidates_sortagainst a whitelist of known columns and quotes identifiers with""; LIKE wildcards (%,_) are escaped to prevent injection through theqparameter - Argon2 auth cache β
src/server/route.jscachesADMIN_KEYverification results in aMapwith 5-second TTL and 1,000-entry limit, avoiding repeated argon2 hashing on burst admin requests - CORS enabled on all routes
- Graceful shutdown β handles
SIGINTandSIGTERMto close the server and Redis connection cleanly