Upstream/public/js/api.js
jvanvik 249818a7aa Stage 3-5 server (military, expansion, social), web client for stages 1-2, ops/deploy
Built: units/research/training, movements (scan, raid, attack, takeover, reinforce, settle, transport), deterministic
combat resolved in the event queue, reports, power/offline units, founding + conquest + incumbent sites; alliances,
roles, diplomacy (24h pact cancel via events), messages, rankings; vanilla-JS phone-first client (auth, POP, map,
alerts, settings, en/nb); systemd units, backup timer, DEPLOY.md, tools/admin.js.
Tested: npm test 96/96 (fake clock, in-memory db, a few real-HTTP tests); client checked with headless Chromium
screenshots only. NOT done: marketplace/transport trade, client screens for military/social, WebSocket push,
bots/balance, e2e suite. All unit stats and costs are unbalanced first guesses.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
2026-10-11 18:32:36 +02:00

203 lines
9.1 KiB
JavaScript

'use strict';
/*
* REST client for /api/v1. No DOM; fetch, storage, clock and sleep are injected so Node tests can drive it
* (test/client-api.test.js). Loads as a browser script (window.UpstreamApi) and as a Node module.
*
* const api = UpstreamApi.createApi({ fetch, storage: localStorage });
* const me = await api.get('/me');
* await api.post('/towns/3/build', { key: 'f1' }, { intent: 'build:3:f1' });
* api.serverNow(); // server clock estimate in ms: use this for every countdown
* api.on('unauthorized', fn); // token rejected: the shell drops to the login screen
* api.on('push', fn); // reserved: the WebSocket client (stage 6) calls api.emit('push', msg)
*
* Rules it follows (docs/API.md):
* - every response carries serverTime; the offset is kept from the lowest-latency sample (replayed idempotent
* responses carry the ORIGINAL serverTime and are ignored for this)
* - errors are { error: { code, message, details } } and become ApiError with .code; callers switch on code
* - mutating POSTs of a logged-in user carry an Idempotency-Key. An "intent" (a stable string like
* 'build:3:f1') keeps the same key across calls until the server has given a definite answer, so a tap that
* died on a flaky network and is tapped again cannot build twice. Without an intent, one key per call, reused
* by that call's retries.
* - retries with backoff: network errors, 429 (Retry-After honoured, seconds), 502/503/504 and request_in_progress.
* Network errors and 5xx are only retried when repeating is safe (GET, a keyed POST). 429 is always safe.
*/
(function (root, factory) {
if (typeof module === 'object' && module.exports) module.exports = factory();
else root.UpstreamApi = factory();
}(typeof self !== 'undefined' ? self : this, function () {
class ApiError extends Error {
constructor(code, message, status, details, retryAfter) {
super(message || code);
this.name = 'ApiError';
this.code = code;
this.status = status || 0;
this.details = details || {};
this.retryAfter = retryAfter || 0;
}
}
const KEY_RE = /^[A-Za-z0-9_.:-]{8,64}$/;
function defaultHex() {
const c = typeof globalThis !== 'undefined' && globalThis.crypto;
if (c && c.getRandomValues) {
const a = new Uint8Array(12);
c.getRandomValues(a);
return Array.prototype.map.call(a, (b) => (b < 16 ? '0' : '') + b.toString(16)).join('');
}
let s = '';
for (let i = 0; i < 24; i++) s += Math.floor(Math.random() * 16).toString(16);
return s;
}
function createApi(opts) {
opts = opts || {};
const doFetch = opts.fetch;
const now = opts.now || Date.now;
const sleep = opts.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
const base = (opts.base || 'api/v1').replace(/\/$/, '');
const tokenKey = opts.tokenKey || 'upstream.token';
const maxRetries = opts.maxRetries === undefined ? 4 : opts.maxRetries;
const maxWaitMs = opts.maxWaitMs || 15000; // a Retry-After longer than this is given to the caller instead
const hex = opts.randomHex || defaultHex;
const jitter = opts.jitter || (() => Math.random());
// ---- token (storage can throw or be empty in private windows: stay usable from memory)
let memToken = null;
const store = opts.storage;
function getToken() {
if (memToken) return memToken;
try { return (store && store.getItem(tokenKey)) || null; } catch (e) { return null; }
}
function setToken(t) {
memToken = t || null;
try { if (store) { if (t) store.setItem(tokenKey, t); else store.removeItem(tokenKey); } } catch (e) { /* memory only */ }
}
const clearToken = () => setToken(null);
// ---- events
const handlers = {};
function on(evt, fn) {
(handlers[evt] = handlers[evt] || new Set()).add(fn);
return () => off(evt, fn);
}
function off(evt, fn) { if (handlers[evt]) handlers[evt].delete(fn); }
function emit(evt, data) {
if (!handlers[evt]) return;
for (const fn of Array.from(handlers[evt])) { try { fn(data); } catch (e) { /* a listener must not break the client */ } }
}
// ---- server clock
let offset = 0, bestRtt = null, bestAt = 0, haveOffset = false;
function observeServerTime(serverTime, t0, t1) {
if (!Number.isFinite(serverTime)) return;
const rtt = Math.max(0, t1 - t0);
if (bestRtt === null || rtt <= bestRtt || t1 - bestAt > 5 * 60 * 1000) {
offset = serverTime - (t0 + t1) / 2;
bestRtt = rtt; bestAt = t1; haveOffset = true;
emit('offset', offset);
}
}
const serverNow = () => now() + offset;
// ---- idempotency keys
const intents = new Map();
const newKey = () => 'u' + hex();
function keyFor(intent) {
if (!intent) return newKey();
let k = intents.get(intent);
if (!k) { k = newKey(); intents.set(intent, k); }
return k;
}
function backoff(attempt) { return Math.round(400 * Math.pow(2, attempt) * (0.75 + jitter() * 0.5)); }
let offline = false;
function setOffline(v) { if (v !== offline) { offline = v; emit(v ? 'offline' : 'online'); } }
function buildUrl(path, query) {
let u = base + (path[0] === '/' ? path : '/' + path);
if (query) {
const p = [];
for (const k of Object.keys(query)) if (query[k] !== undefined && query[k] !== null) p.push(encodeURIComponent(k) + '=' + encodeURIComponent(query[k]));
if (p.length) u += '?' + p.join('&');
}
return u;
}
async function request(method, path, o) {
o = o || {};
const authed = o.auth !== false;
const token = authed ? getToken() : null;
const hasBody = o.body !== undefined && method !== 'GET';
const keyed = method === 'POST' && !!token;
const key = keyed ? keyFor(o.intent) : null;
const safeToRepeat = method === 'GET' || keyed;
const headers = { Accept: 'application/json' };
if (token) headers.Authorization = 'Bearer ' + token;
if (hasBody) headers['Content-Type'] = 'application/json';
if (key) headers['Idempotency-Key'] = key;
const init = { method, headers, cache: 'no-store' };
if (hasBody) init.body = JSON.stringify(o.body);
const url = buildUrl(path, o.query);
const retries = o.retries === undefined ? maxRetries : o.retries;
for (let attempt = 0; ; attempt++) {
const t0 = now();
let res;
try {
res = await doFetch(url, init);
} catch (e) {
setOffline(true);
if (attempt < retries && (safeToRepeat || method === 'DELETE')) { await sleep(backoff(attempt)); continue; }
throw new ApiError('network_error', String(e && e.message || e), 0); // intent key is kept: same tap, same key
}
const t1 = now();
let body = null;
try { body = await res.json(); } catch (e) { body = null; }
const replay = res.headers && res.headers.get && res.headers.get('Idempotent-Replay');
if (body && !replay) observeServerTime(body.serverTime, t0, t1);
if (res.ok) {
setOffline(false);
if (o.intent) intents.delete(o.intent);
return body || {};
}
const err = body && body.error ? body.error : {};
const code = err.code || (res.status === 429 ? 'rate_limited' : 'http_' + res.status);
let retryAfter = 0;
const ra = res.headers && res.headers.get ? Number(res.headers.get('Retry-After')) : NaN;
if (Number.isFinite(ra) && ra > 0) retryAfter = ra;
else if (err.details && Number(err.details.retryAfter) > 0) retryAfter = Number(err.details.retryAfter);
// 429 was refused before doing anything, so it is always safe to repeat.
if (res.status === 429 && attempt < retries) {
const wait = retryAfter ? retryAfter * 1000 : backoff(attempt);
if (wait <= maxWaitMs) { await sleep(wait); continue; }
}
if ([502, 503, 504].includes(res.status) && attempt < retries && safeToRepeat) { await sleep(backoff(attempt)); continue; }
if (code === 'request_in_progress' && attempt < retries) { await sleep(500 + backoff(attempt)); continue; }
setOffline(false); // the server answered: the network is fine
if (o.intent && res.status !== 429 && res.status < 500) intents.delete(o.intent); // a definite answer ends the intent
if (res.status === 401 && token && code === 'unauthorized') { clearToken(); emit('unauthorized', {}); }
throw new ApiError(code, err.message, res.status, err.details, retryAfter);
}
}
return {
request,
get: (path, query, o) => request('GET', path, Object.assign({ query }, o)),
post: (path, body, o) => request('POST', path, Object.assign({ body: body === undefined ? {} : body }, o)),
del: (path, o) => request('DELETE', path, o),
getToken, setToken, clearToken, hasToken: () => !!getToken(),
on, off, emit,
serverNow, hasServerTime: () => haveOffset, serverOffset: () => offset,
pendingIntents: () => Array.from(intents.keys()),
isValidKey: (k) => KEY_RE.test(k),
};
}
return { createApi, ApiError };
}));