feat: Update Dockerfile and server configuration for improved health checks and error handling

server/errors.js

@@ -12,6 +12,7 @@
  *   429 busy                the server is parsing other imports
  *   502 source_unavailable  the university catalog did not answer
  *   502 source_invalid      the catalog answered, but its folders or tables are not recognised
+ *   503 not_ready           /api/ready only: the server is still loading the catalog or its index
  *   504 source_timeout      the university catalog answered too slowly
  *   500 internal            a fault of the server itself
  */
@@ -29,12 +30,12 @@ const SOURCE_DOWN = "Каталог университета сейчас не
 const SOURCE_SLOW = "Каталог университета отвечает слишком долго. Попробуйте позже.";
 
 /**
- * A failed download from the university as an API error: curl's exit code 28 (or our own
- * kill on the time limit) is a timeout, any other failure means the source is unavailable.
+ * A failed download from the university as an API error: fetch aborted on the time limit is a
+ * timeout, any other failure (no connection, an HTTP error, a redirect) means the source is unavailable.
  */
 export function sourceError(error) {
   if (error instanceof ApiError) return error;
-  const timedOut = error?.code === 28 || error?.killed || error?.signal === "SIGTERM";
+  const timedOut = error?.name === "TimeoutError" || error?.name === "AbortError";
   return timedOut
     ? new ApiError(504, "source_timeout", SOURCE_SLOW)
     : new ApiError(502, "source_unavailable", SOURCE_DOWN);

server/index.js

@@ -1,6 +1,7 @@
 import express from "express";
 import compression from "compression";
 import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
 import multer from "multer";
 import { parseWord, PARSER_VERSION } from "./parser.js";
 import { scheduleFor } from "./schedules.js";
@@ -47,20 +48,43 @@ app.use("/api", (_req, res, next) => {
 // 4 — compression, ETag revalidation, throttled refresh and import limits;
 // 5 — error codes (`code` beside `error`, see server/errors.js), timetable 304 before any work;
 // 6 — the timetable carries the group's exams and credits from other catalog documents;
-// 7 — /api/diagnostics, cells the parser could not read with confidence.
-const API_VERSION = 7;
+// 7 — /api/diagnostics, cells the parser could not read with confidence;
+// 8 — /api/ready, and `ready` in /api/health.
+const API_VERSION = 8;
 
+/**
+ * What the server still waits for before it answers from memory: the catalog, the week table
+ * and the directory index. A first start without a cache crawls and parses every document.
+ */
+const waitingFor = (sources, directory) =>
+  [!sources.catalog && "catalog", !sources.calendar && "calendar", !directory.builtAt && "index"].filter(Boolean);
 // Liveness plus what the server currently reads from the university, without network calls.
 app.get("/api/health", async (_req, res) => {
   const sources = await sourceStatus().catch((e) => ({ error: e.message }));
   res.json({
     ok: true,
+    ready: waitingFor(sources, indexStatus()).length === 0,
     apiVersion: API_VERSION,
     parserVersion: PARSER_VERSION,
     ...sources,
     directory: indexStatus(),
   });
 });
+// Readiness for Docker and a proxy: 503 until the catalog, the week table and the index are
+// loaded, so traffic does not reach a server whose first requests would wait half a minute.
+app.get("/api/ready", async (_req, res) => {
+  const sources = await sourceStatus().catch(() => ({}));
+  const directory = indexStatus();
+  const waiting = waitingFor(sources, directory);
+  if (waiting.length)
+    return res.status(503).json({
+      ready: false,
+      waiting,
+      error: "Сервер ещё загружает каталог расписаний. Попробуйте через минуту.",
+      code: "not_ready",
+    });
+  res.json({ ready: true, documents: directory.documents, builtAt: directory.builtAt });
+});
 const isDate = (s) => /^\d{4}-\d{2}-\d{2}$/.test(s || "");
 const badRequest = (res, error) => res.status(400).json({ error, code: "bad_request" });
 // University-wide lookups over every catalog document.
@@ -254,11 +278,16 @@ app.use((error, req, res, _next) => {
   else console.error(`${req.method} ${req.originalUrl} → ${status} ${code}: ${error.message}`);
   res.status(status).json({ error: message, code });
 });
-const port = Number(process.env.PORT || 3001);
-app.listen(port, process.env.HOST || "127.0.0.1", () => {
-  console.log(`API и PWA: http://127.0.0.1:${port}`);
-  // Read the week table and parse the whole catalog in the background,
-  // so the first visit and the first search do not wait for the university.
-  getCalendar().catch((e) => console.error(`Таблица недель: ${e.message}`));
-  getIndex().catch((e) => console.error(`Индекс: ${e.message}`));
-});
+export { app };
+
+/** Starts listening and loads the week table and the whole catalog in the background. */
+export function start(port = Number(process.env.PORT || 3001), host = process.env.HOST || "127.0.0.1") {
+  return app.listen(port, host, () => {
+    console.log(`API и PWA: http://127.0.0.1:${port}`);
+    // So the first visit and the first search do not wait for the university.
+    getCalendar().catch((e) => console.error(`Таблица недель: ${e.message}`));
+    getIndex().catch((e) => console.error(`Индекс: ${e.message}`));
+  });
+}
+// `node server/index.js` serves; tests import the app without listening.
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) start();

server/paths.js

@@ -0,0 +1,7 @@
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Where the catalog, the week table and parsed documents are cached; tests use a temporary one. */
+export const DATA = process.env.PSU_DATA_DIR
+  ? resolve(process.env.PSU_DATA_DIR) + "/"
+  : fileURLToPath(new URL("../.data/", import.meta.url));

server/schedules.js

@@ -1,9 +1,9 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
 import { parseWord, PARSER_VERSION } from "./parser.js";
 import { request, MIN_REFRESH } from "./source.js";
+import { DATA } from "./paths.js";
 
-const data = fileURLToPath(new URL("../.data/parsed/", import.meta.url));
+const data = DATA + "parsed/";
 // When each document was last downloaded, and the downloads under way: a forced refresh
 // downloads a document at most once per MIN_REFRESH, and simultaneous ones share a download.
 const fetchedAt = new Map(),

server/source.js

@@ -1,22 +1,19 @@
 import { XMLParser } from "fast-xml-parser";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { parseWeeksDocx, parseBellsDocx } from "./calendar.js";
 import { apiError, sourceError } from "./errors.js";
+import { DATA } from "./paths.js";
 import {
   academicStartYear,
   assignSemesters,
   todayIso,
   weekIndexOf,
 } from "../shared/weeks.js";
-const run = promisify(execFile);
-const ORIGIN = "https://nextcloud.psu.by";
+// The university's Nextcloud; tests point PSU_SOURCE_ORIGIN at a local stand-in.
+const ORIGIN = process.env.PSU_SOURCE_ORIGIN || "https://nextcloud.psu.by";
 const SHARE = "/public.php/dav/files/no5zKbMrns6j5jQ/";
 const YEAR_FOLDER = /^(\d{4})-(\d{4})$/;
-const DATA = fileURLToPath(new URL("../.data/", import.meta.url));
 const parser = new XMLParser({ removeNSPrefix: true, ignoreAttributes: false });
 const arr = (value) => (value ? (Array.isArray(value) ? value : [value]) : []);
 const DISCOVERY_TTL = 15 * 60 * 1000,
@@ -39,6 +36,8 @@ const status = { catalogError: null, calendarError: null };
 const failedAt = { catalog: 0, calendar: 0 };
 const backingOff = (what) => Date.now() - failedAt[what] < MIN_REFRESH;
 
+const TIMEOUT = Number(process.env.PSU_SOURCE_TIMEOUT_MS) || 25000;
+const MAX_SIZE = 10 * 1024 * 1024;
 export async function request(path, method = "GET") {
   // Only the university share is reachable; listings and catalog entries supply the paths.
   if (
@@ -48,31 +47,35 @@ export async function request(path, method = "GET") {
     !["GET", "PROPFIND"].includes(method)
   )
     throw new Error("Недопустимый путь документа.");
-  const url = ORIGIN + path;
-  // curl also works with the system trust store on macOS. Certificate checks stay enabled.
-  const args = [
-    "--fail",
-    "--silent",
-    "--show-error",
-    "--max-time",
-    "25",
-    "--max-filesize",
-    "10485760",
-    "--max-redirs",
-    "0",
-    "--request",
-    method,
-  ];
-  if (method === "PROPFIND") args.push("--header", "Depth: 1");
-  args.push(url);
-  const { stdout } = await run("curl", args, {
-    encoding: "buffer",
-    maxBuffer: 11 * 1024 * 1024,
-    timeout: 28000,
-  }).catch((error) => {
+  // Node's fetch keeps connections to the university open between requests, so a catalog
+  // crawl of a hundred listings pays for one TLS handshake, not a hundred. Certificates are
+  // checked, redirects are refused, and the answer is cut off past 10 MB or 25 seconds.
+  try {
+    const response = await fetch(ORIGIN + path, {
+      method,
+      headers: method === "PROPFIND" ? { Depth: "1" } : {},
+      redirect: "manual",
+      signal: AbortSignal.timeout(TIMEOUT),
+    });
+    if (!response.ok) {
+      await response.body?.cancel();
+      throw new Error(`HTTP ${response.status}`);
+    }
+    if (Number(response.headers.get("content-length")) > MAX_SIZE) {
+      await response.body?.cancel();
+      throw new Error("Документ больше 10 МБ.");
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of response.body || []) {
+      size += chunk.length;
+      if (size > MAX_SIZE) throw new Error("Документ больше 10 МБ.");
+      chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+  } catch (error) {
     throw sourceError(error);
-  });
-  return stdout;
+  }
 }
 export function decodeListing(xml, root = SHARE) {
   const entries = arr(parser.parse(xml).multistatus?.response);