ADFA-4838: REST endpoints + wire the job engine into server.ts

- routes.ts: POST /api/:type/download, GET /api/:type/jobs(/:id), POST .../cancel.
  Stateless calls over the durable engine; clients re-attach by polling the id.
- server.ts: mount express.json() + /api router, import the kiwix runner (registers it),
  and call jobs.reconcileOnBoot() on listen so interrupted jobs resume.
- nginx: add a localhost-only /api/ proxy to :4000 (mirrors the /dashboard/ + /socket.io/
  locations).

Kiwix now works end-to-end over REST. maps/books runners and retiring the socket-owned
job paths are the next steps. Typechecks (tsc --noEmit).

Author: luisguzman-adfa

static/dashboard/dash-node-nginx.conf

@@ -15,6 +15,21 @@ location ^~ /dashboard/ {
     proxy_set_header X-Forwarded-Proto $scheme;
 }
 
+# Proxy for the REST content API (ADFA-4838, localhost only)
+location ^~ /api/ {
+    allow 127.0.0.1;
+    allow ::1;
+    deny all;
+
+    error_page 403 =404 /404.html;
+
+    proxy_pass http://127.0.0.1:4000/api/;
+    proxy_set_header Host $http_host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+
 # Proxy for WebSockets (socket.io uses it by default)
 location ^~ /socket.io/ {
     # Basic security (localhost only)

static/dashboard/routes.ts

@@ -0,0 +1,64 @@
+// routes.ts — ADFA-4838
+//
+// REST surface over the durable job engine. Short, stateless calls the app (and the
+// web UI) use instead of a long-lived socket: start a job, poll its structured status,
+// cancel it. The job itself lives in the dashboard process (see sockets/jobs.ts), so
+// none of these calls hold state — a client can drop and re-attach by polling the id.
+import express, { Router, Request, Response } from 'express';
+import { jobs, Job, JobType } from './sockets/jobs';
+
+const VALID_TYPES: JobType[] = ['kiwix', 'maps', 'books'];
+function isType(t: string): t is JobType {
+    return (VALID_TYPES as string[]).includes(t);
+}
+
+/** Public shape returned to clients: ids as an array, no raw JSON column. */
+function toApi(job: Job) {
+    let ids: string[] = [];
+    try { ids = JSON.parse(job.target) as string[]; } catch { ids = []; }
+    return {
+        id: job.id,
+        type: job.type,
+        ids,
+        phase: job.phase,
+        percent: job.percent,
+        speed: job.speed,
+        detail: job.detail,
+        error: job.error,
+        updated: job.updated,
+    };
+}
+
+export const apiRouter: Router = express.Router();
+
+// Start a content job → 202 { ...job }
+apiRouter.post('/:type/download', (req: Request, res: Response): void => {
+    const type = String(req.params.type);
+    if (!isType(type)) { res.status(404).json({ error: 'unknown type' }); return; }
+    const body = req.body as { ids?: unknown };
+    const ids = Array.isArray(body?.ids) ? body.ids.map((x) => String(x)) : [];
+    if (ids.length === 0) { res.status(400).json({ error: 'ids required' }); return; }
+    res.status(202).json(toApi(jobs.create(type, ids)));
+});
+
+// Poll one job's structured status.
+apiRouter.get('/:type/jobs/:id', (req: Request, res: Response): void => {
+    const job = jobs.get(String(req.params.id));
+    if (!job || job.type !== String(req.params.type)) { res.status(404).json({ error: 'not found' }); return; }
+    res.json(toApi(job));
+});
+
+// List a type's jobs (most recent first).
+apiRouter.get('/:type/jobs', (req: Request, res: Response): void => {
+    const type = String(req.params.type);
+    if (!isType(type)) { res.status(404).json({ error: 'unknown type' }); return; }
+    res.json(jobs.list(type).map(toApi));
+});
+
+// Cancel a running job.
+apiRouter.post('/:type/jobs/:id/cancel', (req: Request, res: Response): void => {
+    const job = jobs.get(String(req.params.id));
+    if (!job || job.type !== String(req.params.type)) { res.status(404).json({ error: 'not found' }); return; }
+    jobs.cancel(job.id);
+    res.json({ ok: true });
+});

static/dashboard/server.ts

@@ -10,6 +10,12 @@ import { handleKiwixEvents } from './sockets/kiwix.socket';
 import { handleHomeEvents } from './sockets/home.socket';
 import { handleBooksEvents } from './sockets/books.socket';
 
+// ADFA-4838: durable REST job engine. Importing the runner modules registers them with
+// the shared JobManager; the router exposes them over /api.
+import { jobs } from './sockets/jobs';
+import './sockets/kiwix.exec';
+import { apiRouter } from './routes';
+
 const app = express();
 const server = http.createServer(app);
 const io = new Server(server);
@@ -28,9 +34,13 @@ app.set('view engine', 'ejs');
 app.set('views', path.join(__dirname, 'views'));
 app.use(express.static(path.join(__dirname, 'public')));
 
+// ADFA-4838: JSON body parsing + the REST content API.
+app.use(express.json());
+app.use('/api', apiRouter);
+
 // Main route
 app.get('/', (req, res) => {
-    res.render('index'); 
+    res.render('index');
 });
 
 // Main Socket Connection Handler
@@ -53,6 +63,8 @@ server.listen(PORT, () => {
     console.log(`===========================================`);
     console.log(`K2Go Dashboard active on port ${PORT}`);
     console.log(`===========================================`);
+    // ADFA-4838: resume any content jobs that were mid-flight before a restart.
+    try { jobs.reconcileOnBoot(); } catch (e) { console.error('[jobs] reconcile failed', e); }
 });
 
 // ==========================================