Merge branch 'master' into ai/issue-67
All checks were successful
Test / test (push) Successful in 2s

This commit is contained in:
2026-10-15 16:40:30 +00:00
20 changed files with 823 additions and 60 deletions

View File

@@ -134,6 +134,9 @@ export DRAGONROLL_FOUNDRY_PUSH_TOKEN='replace-with-a-different-long-random-publi
export DRAGONROLL_FOUNDRY_ALLOWED_ORIGINS='https://vtt.example.com'
export DRAGONROLL_FOUNDRY_HOST='0.0.0.0'
export DRAGONROLL_FOUNDRY_PORT='8787'
# Optional: the Foundry Data directory. With it the bridge can list the core
# `icons/` library Dragonroll's item icon browser shows.
export DRAGONROLL_FOUNDRY_DATA_PATH='/home/foundry/Foundry Data'
npm start --prefix foundry/bridge
```
@@ -169,6 +172,7 @@ The backend exposes these JWT-protected routes when the optional snapshot bridge
| `GET /api/foundry/actors/:id/items` | Items embedded in an actor |
| `GET /api/foundry/items` | World-level items |
| `GET /api/foundry/items/:id` | One world-level item |
| `GET /api/foundry/icons?campaign=&dir=&offset=` | One folder of Foundry's core icon library |
The bridge exposes the matching routes under `/api/*`, plus `GET /health`. Data routes require
`Authorization: Bearer <read-token>`. Responses contain `{ status: "ok", data, world, syncedAt,
@@ -176,6 +180,13 @@ ageSeconds, stale }`. The snapshot stays in memory; `stale` becomes true when th
received a GM heartbeat for more than two minutes. The bridge returns `503 foundry.not-ready` until a
configured GM client has published its first snapshot.
The icon library is the one route that reads the disk instead of the snapshot: with
`DRAGONROLL_FOUNDRY_DATA_PATH` set, `GET /api/icons?dir=icons/svg&offset=120&limit=120` answers one
folder at a time — `{ status: "ok", dir, directories, files, offset, next }` of paths relative to the
data directory — and never reads outside `icons/`. `next` is the offset of the next page of icons, or
null once the folder is listed, which is how the campaign's icon browser keeps a library of thousands
lazy to load. Without that variable the route answers `503 foundry.errors.icons-unavailable`.
World-level items come from Foundry's `game.items`; actor inventories come from each actor's embedded
items collection. The API returns plain document data snapshots. This is a read-only integration: it
does not create or update Foundry documents, and it does not persist the bridge cache across restarts.

View File

@@ -1,4 +1,6 @@
const http = require("node:http");
const fs = require("node:fs");
const path = require("node:path");
const { timingSafeEqual } = require("node:crypto");
const host = process.env.DRAGONROLL_FOUNDRY_HOST || "0.0.0.0";
@@ -12,6 +14,9 @@ const allowedOrigins = new Set(
.filter(Boolean),
);
const maxBodySize = 50 * 1024 * 1024;
// The Foundry Data directory, for listing the core `icons/` library. Optional:
// without it the bridge simply cannot answer icon listing requests.
const dataPath = (process.env.DRAGONROLL_FOUNDRY_DATA_PATH || "").trim();
if (!readToken || !pushToken) {
throw new Error("Set DRAGONROLL_FOUNDRY_READ_TOKEN and DRAGONROLL_FOUNDRY_PUSH_TOKEN before starting the bridge.");
@@ -106,6 +111,80 @@ function decodePathSegment(segment) {
}
}
// --- Core icon library -----------------------------------------------------
// Foundry keeps the icons it ships in the `icons/` folder of its data directory:
// thousands of images over a folder tree of their own. The campaign's icon window
// browses that tree, so the bridge lists one folder per request and pages the
// icons inside it. It never reads outside `icons/`.
const iconRoot = "icons";
const iconExtensions = new Set([".svg", ".png", ".webp", ".jpg", ".jpeg", ".gif", ".avif"]);
const defaultIconPageSize = 120;
const maxIconPageSize = 500;
function normalizeIconDirectory(input) {
const raw = String(input ?? "").trim().replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
if (!raw || raw === ".") return iconRoot;
const segments = raw.split("/").filter((segment) => segment && segment !== ".");
if (!segments.length || segments.includes("..") || segments[0] !== iconRoot) return null;
return segments.join("/");
}
function readIconDirectory(dir, offset, limit) {
const root = path.resolve(dataPath, iconRoot);
const target = path.resolve(dataPath, dir);
if (target !== root && !target.startsWith(root + path.sep)) return null;
const directories = [];
const files = [];
for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
const entryPath = path.posix.join(dir, entry.name);
if (entry.isDirectory()) directories.push(entryPath);
else if (entry.isFile() && iconExtensions.has(path.extname(entry.name).toLowerCase())) files.push(entryPath);
}
directories.sort((a, b) => a.localeCompare(b));
files.sort((a, b) => a.localeCompare(b));
const page = files.slice(offset, offset + limit);
return {
// Subfolders always come back whole: the window needs every one of them to
// navigate, and there are never many. Paging covers the icons.
directories,
files: page,
offset,
next: offset + page.length < files.length ? offset + page.length : null,
};
}
function sendIconListing(request, response) {
if (!dataPath) return sendJson(response, 503, { status: "error", msg: "foundry.errors.icons-unavailable" });
const params = new URL(request.url, "http://localhost").searchParams;
const dir = normalizeIconDirectory(params.get("dir"));
if (!dir) return sendJson(response, 400, { status: "error", msg: "errors.missing-data" });
const requestedLimit = Number(params.get("limit"));
const limit = Number.isFinite(requestedLimit)
? Math.min(maxIconPageSize, Math.max(1, Math.trunc(requestedLimit)))
: defaultIconPageSize;
const requestedOffset = Number(params.get("offset"));
const offset = Number.isFinite(requestedOffset) ? Math.max(0, Math.trunc(requestedOffset)) : 0;
try {
const listing = readIconDirectory(dir, offset, limit);
if (!listing) return sendJson(response, 400, { status: "error", msg: "errors.missing-data" });
sendJson(response, 200, { status: "ok", dir, ...listing });
} catch (error) {
if (error.code === "ENOENT" || error.code === "ENOTDIR") {
sendJson(response, 404, { status: "error", msg: "errors.notfound" });
return;
}
console.error(`Could not list the Foundry icon folder ${dir}.`, error);
sendJson(response, 500, { status: "error", msg: "foundry.errors.icons-unavailable" });
}
}
const server = http.createServer(async (request, response) => {
if (!setCorsHeaders(request, response)) {
sendJson(response, 403, { status: "error", msg: "foundry.origin-not-allowed" });
@@ -188,6 +267,10 @@ const server = http.createServer(async (request, response) => {
return;
}
// The icon library is on disk, not in the world snapshot, so it answers whether
// or not a GM client has published one yet.
if (pathname === "/api/icons") return sendIconListing(request, response);
const current = currentSnapshot(response);
if (!current) return;