Built: SQLite (node:sqlite) via server/db.js with checksummed migrations, injectable clock, persistent event scheduler with catch-up, tiny REST router (error envelope, idempotency keys, rate limits, bearer tokens with scrypt passwords), lazy-resource economy in public/js/rules.js + data.js, build/cancel/rename commands, seeded map + spawn ring, generated docs/openapi.json. NETWALL net.js/static.js reused. Tested: manual smoke run only (signup, town view, build, map). No unit tests or e2e yet. NOT done: military, expansion, social, client, push, deploy docs, bots/admin. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
227 lines
10 KiB
JavaScript
227 lines
10 KiB
JavaScript
'use strict';
|
|
/*
|
|
* Tiny REST layer on node:http: router, JSON in/out, error envelope, bearer auth, rate limits, Idempotency-Key.
|
|
*
|
|
* const api = createApi({ db, clock, log, opts, services });
|
|
* routes.register(api.router, services);
|
|
* server.on('request', (req, res) => url.startsWith('/api/') ? api.handle(req, res) : serveStatic(req, res));
|
|
*
|
|
* Route meta (also the source of docs/openapi.json, see tools/gen-openapi.js):
|
|
* { summary, tag, auth: true|false, query: schema, body: schema, response: schema, errors: [codes], limit: 'auth' }
|
|
* Every JSON response is an object carrying `serverTime`. Errors are { error: { code, message, details } }.
|
|
*/
|
|
const crypto = require('crypto');
|
|
const { GameError, CODES } = require('./errors');
|
|
const { validate } = require('./validate');
|
|
const { TokenBucket, clientIp } = require('./net');
|
|
const { applySecurityHeaders } = require('./static');
|
|
|
|
const MAX_BODY = 32 * 1024;
|
|
const INT_PARAMS = new Set(['id', 'townId', 'eventId', 'tokenId']);
|
|
|
|
// Per-key token buckets (per IP, per token). Idle full buckets are pruned so the map cannot grow without bound.
|
|
class Limiter {
|
|
constructor(ratePerSec, burst, maxKeys) { this.rate = ratePerSec; this.burst = burst; this.maxKeys = maxKeys || 20000; this.m = new Map(); }
|
|
take(key) {
|
|
let b = this.m.get(key);
|
|
if (!b) {
|
|
if (this.m.size >= this.maxKeys) this.prune();
|
|
b = new TokenBucket(this.rate, this.burst); this.m.set(key, b);
|
|
}
|
|
return b.take();
|
|
}
|
|
prune() {
|
|
for (const [k, b] of this.m) if (b.tokens >= b.burst - 0.5) this.m.delete(k);
|
|
if (this.m.size >= this.maxKeys) this.m.clear(); // under attack from >maxKeys distinct keys: forget, do not grow
|
|
}
|
|
}
|
|
|
|
class Router {
|
|
constructor() { this.routes = []; }
|
|
// path like '/towns/:id/build' (relative to /api/v1)
|
|
add(method, path, meta, handler) {
|
|
const names = [];
|
|
const re = new RegExp('^' + path.replace(/:([A-Za-z]+)/g, (m, n) => { names.push(n); return '([^/]+)'; }) + '$');
|
|
this.routes.push({ method, path, re, names, meta: meta || {}, handler });
|
|
}
|
|
get(path, meta, h) { this.add('GET', path, meta, h); }
|
|
post(path, meta, h) { this.add('POST', path, meta, h); }
|
|
del(path, meta, h) { this.add('DELETE', path, meta, h); }
|
|
// -> { route, params } | { methods: [...] } (path matches, method does not) | null
|
|
find(method, pathname) {
|
|
const allowed = [];
|
|
for (const r of this.routes) {
|
|
const m = r.re.exec(pathname);
|
|
if (!m) continue;
|
|
if (r.method !== method) { allowed.push(r.method); continue; }
|
|
const params = {};
|
|
for (let i = 0; i < r.names.length; i++) {
|
|
let v;
|
|
try { v = decodeURIComponent(m[i + 1]); } catch (e) { return null; }
|
|
if (INT_PARAMS.has(r.names[i])) {
|
|
if (!/^\d{1,12}$/.test(v)) return null;
|
|
v = Number(v);
|
|
}
|
|
params[r.names[i]] = v;
|
|
}
|
|
return { route: r, params };
|
|
}
|
|
return allowed.length ? { methods: allowed } : null;
|
|
}
|
|
}
|
|
|
|
// A handler returns a plain object (HTTP 200) or reply(status, object).
|
|
class Reply { constructor(status, body) { this.status = status; this.body = body; } }
|
|
const reply = (status, body) => new Reply(status, body);
|
|
|
|
function createApi({ db, clock, log, opts, auth }) {
|
|
const router = new Router();
|
|
const ipLimit = new Limiter(opts.ipRate || 30, opts.ipBurst || 90);
|
|
const tokenLimit = new Limiter(opts.tokenRate || 15, opts.tokenBurst || 45);
|
|
const authLimit = new Limiter(opts.authRate || 0.1, opts.authBurst || 8); // login / signup: ~1 per 10 s sustained
|
|
const inflight = new Set();
|
|
|
|
function send(res, status, body, extra) {
|
|
const text = JSON.stringify(body);
|
|
applySecurityHeaders(res);
|
|
res.writeHead(status, Object.assign({ 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': Buffer.byteLength(text), 'Cache-Control': 'no-store' }, extra));
|
|
res.end(text);
|
|
}
|
|
|
|
function fail(res, err, ctx) {
|
|
let ge = err;
|
|
if (!(err instanceof GameError)) {
|
|
log('internal error ' + (ctx || '') + ': ' + (err && err.stack || err));
|
|
ge = new GameError('internal_error');
|
|
}
|
|
const extra = ge.status === 429 && ge.details.retryAfter ? { 'Retry-After': String(ge.details.retryAfter) } : undefined;
|
|
send(res, ge.status, { serverTime: clock.now(), error: { code: ge.code, message: ge.message, details: ge.details } }, extra);
|
|
}
|
|
|
|
function readBody(req) {
|
|
return new Promise((resolve, reject) => {
|
|
const len = Number(req.headers['content-length'] || 0);
|
|
if (len > MAX_BODY) return reject(new GameError('payload_too_large'));
|
|
const chunks = []; let size = 0;
|
|
req.on('data', (c) => {
|
|
size += c.length;
|
|
if (size > MAX_BODY) { reject(new GameError('payload_too_large')); req.destroy(); return; }
|
|
chunks.push(c);
|
|
});
|
|
req.on('end', () => resolve(Buffer.concat(chunks)));
|
|
req.on('error', () => reject(new GameError('bad_request')));
|
|
});
|
|
}
|
|
|
|
async function handle(req, res) {
|
|
const ip = clientIp(req, opts.trustProxy, opts.trustedProxies);
|
|
const started = clock.now();
|
|
let pathname = '', routeKey = '';
|
|
try {
|
|
const u = new URL(req.url, 'http://x');
|
|
pathname = u.pathname;
|
|
if (!ipLimit.take(ip)) { log('refused rate_limited(ip) ip=' + ip + ' path=' + pathname); throw new GameError('rate_limited', { retryAfter: 1 }); }
|
|
if (!pathname.startsWith('/api/v1/')) throw new GameError('not_found');
|
|
const found = router.find(req.method, pathname.slice('/api/v1'.length));
|
|
if (!found) throw new GameError('not_found');
|
|
if (found.methods) { const e = new GameError('method_not_allowed', { allowed: found.methods }); throw e; }
|
|
const { route, params } = found;
|
|
routeKey = route.method + ' ' + route.path;
|
|
const meta = route.meta;
|
|
|
|
if (meta.limit === 'auth' && !authLimit.take(ip)) { log('refused rate_limited(auth) ip=' + ip + ' route=' + routeKey); throw new GameError('rate_limited', { retryAfter: 10 }); }
|
|
|
|
let user = null, tokenId = null;
|
|
if (meta.auth !== false) {
|
|
const a = auth.authenticate(req.headers.authorization, clock.now());
|
|
if (!a) { log('refused unauthorized ip=' + ip + ' route=' + routeKey); throw new GameError('unauthorized'); }
|
|
user = a.user; tokenId = a.tokenId;
|
|
if (!tokenLimit.take('t' + tokenId)) { log('refused rate_limited(token) token=' + tokenId + ' route=' + routeKey); throw new GameError('rate_limited', { retryAfter: 1 }); }
|
|
}
|
|
|
|
// query
|
|
const query = {};
|
|
for (const [k, v] of u.searchParams) query[k] = v;
|
|
let q = {};
|
|
if (meta.query) {
|
|
const v = validate(meta.query, query, { coerce: true });
|
|
if (!v.ok) throw new GameError('validation_failed', { errors: v.errors });
|
|
q = v.value;
|
|
}
|
|
|
|
// body
|
|
let body = {};
|
|
if (meta.body) {
|
|
const raw = await readBody(req);
|
|
let parsed = {};
|
|
if (raw.length) {
|
|
if (!/^application\/json\b/i.test(req.headers['content-type'] || '')) throw new GameError('bad_request', { reason: 'content-type must be application/json' });
|
|
try { parsed = JSON.parse(raw.toString('utf8')); } catch (e) { throw new GameError('bad_request', { reason: 'invalid JSON' }); }
|
|
}
|
|
const v = validate(meta.body, parsed);
|
|
if (!v.ok) throw new GameError('validation_failed', { errors: v.errors });
|
|
body = v.value;
|
|
} else if (req.method !== 'GET' && req.method !== 'HEAD') {
|
|
await readBody(req).catch(() => null); // drain
|
|
}
|
|
|
|
const ctx = { req, ip, user, tokenId, params, query: q, body, now: clock.now() };
|
|
|
|
// Idempotency-Key on mutating POSTs of authenticated users
|
|
const idem = req.method === 'POST' && user ? req.headers['idempotency-key'] : undefined;
|
|
let idemId = null;
|
|
if (idem !== undefined) {
|
|
if (typeof idem !== 'string' || !/^[A-Za-z0-9_.:-]{8,64}$/.test(idem)) throw new GameError('validation_failed', { errors: [{ path: 'Idempotency-Key', message: 'must be 8-64 of A-Za-z0-9_.:-' }] });
|
|
const sig = req.method + ' ' + pathname + ' ' + crypto.createHash('sha256').update(JSON.stringify(body)).digest('hex');
|
|
idemId = user.id + ':' + idem;
|
|
const row = db.get('SELECT request, status, body FROM idempotency WHERE user_id = ? AND key = ?', user.id, idem);
|
|
if (row) {
|
|
if (row.request !== sig) throw new GameError('idempotency_key_reuse');
|
|
return send(res, row.status, JSON.parse(row.body), { 'Idempotent-Replay': 'true' });
|
|
}
|
|
if (inflight.has(idemId)) throw new GameError('request_in_progress');
|
|
inflight.add(idemId);
|
|
ctx.idem = { key: idem, sig };
|
|
}
|
|
try {
|
|
let out;
|
|
let status = 200;
|
|
try {
|
|
out = await route.handler(ctx);
|
|
if (out instanceof Reply) { status = out.status; out = out.body; }
|
|
out = Object.assign({ serverTime: clock.now() }, out);
|
|
} catch (err) {
|
|
if (ctx.idem && err instanceof GameError && err.status < 500) {
|
|
// Replaying a rejected request must give the same rejection, not run it again.
|
|
const eb = { serverTime: clock.now(), error: { code: err.code, message: err.message, details: err.details } };
|
|
storeIdem(user.id, ctx.idem, err.status, eb);
|
|
}
|
|
throw err;
|
|
}
|
|
if (ctx.idem) storeIdem(user.id, ctx.idem, status, out);
|
|
send(res, status, out);
|
|
} finally { if (idemId) inflight.delete(idemId); }
|
|
} catch (err) {
|
|
if (!(err instanceof GameError)) log('request failed ' + routeKey + ' ' + pathname + ': ' + (err && err.stack || err));
|
|
else if (err.status >= 400 && err.code !== 'not_found' && err.code !== 'unauthorized' && err.status !== 429) {
|
|
// game-rule refusals are normal traffic; keep them out of the log except for the security-relevant codes
|
|
if (err.code === 'forbidden' || err.code === 'validation_failed' || err.code === 'bad_request') log('refused ' + err.code + ' ip=' + ip + ' route=' + routeKey);
|
|
}
|
|
if (!res.headersSent) fail(res, err, routeKey);
|
|
}
|
|
}
|
|
|
|
function storeIdem(userId, idem, status, body) {
|
|
try {
|
|
db.run('INSERT OR IGNORE INTO idempotency (user_id, key, request, status, body, created_at) VALUES (?, ?, ?, ?, ?, ?)', userId, idem.key, idem.sig, status, JSON.stringify(body), clock.now());
|
|
} catch (e) { log('could not store idempotency key: ' + e.message); }
|
|
}
|
|
|
|
function pruneIdempotency() {
|
|
db.run('DELETE FROM idempotency WHERE created_at < ?', clock.now() - 24 * 3600 * 1000);
|
|
}
|
|
|
|
return { router, handle, pruneIdempotency, CODES };
|
|
}
|
|
|
|
module.exports = { createApi, Router, Reply, reply, Limiter };
|