Fix issue #17: Foundry Module: Show pairing status

This commit is contained in:
Gitea OpenCode Agent
2026-10-14 12:59:26 +00:00
parent 67ca4b0210
commit ed0b9af00b
6 changed files with 359 additions and 2 deletions

View File

@@ -41,6 +41,14 @@ For a local backend, use `http://localhost:5000`; the module omits `/api` and th
the local pairing route at its root. Character synchronization works without the optional snapshot
bridge. Configure that bridge only if you also need the read-only world snapshot API described below.
**Dragonroll Pairing Status** in the module settings always says whether this browser holds a pairing
and, once Dragonroll has answered `GET /api/foundry/sync/status`, which campaign the world is
connected to. It is written by the module, not by the GM: it appears as not connected until the world
is paired, names the campaign after a pairing or a check on world start and every minute afterwards,
gives the reason when a pairing code can never be redeemed, and says the world is no longer linked
once the campaign unlinks it. Because both the pairing code and the sync token are client settings,
another browser of the same world reads as not paired.
The campaign settings show the linked world's title and system. A Foundry world can be linked to
only one campaign at a time. The pairing endpoint accepts cross-origin requests from the Foundry
client and uses the one-time code instead of a Dragonroll login token.
@@ -103,6 +111,7 @@ The module calls these Dragonroll routes with the campaign sync token (no Dragon
| `POST /api/foundry/sync/item-delete` | A world item was deleted |
| `GET /api/foundry/sync/characters` | Characters to apply back in Foundry |
| `GET /api/foundry/sync/items` | Items to apply back in Foundry |
| `GET /api/foundry/sync/status` | The campaign this world's token belongs to, for the module's pairing status |
| `POST /api/foundry/sync/map` / `map-item` | Store an id mapping after creating a document |
| `POST /api/foundry/sync/delete` | An actor was deleted |

View File

@@ -4,6 +4,7 @@ const SETTING_PUSH_TOKEN = "pushToken";
const SETTING_BRIDGE_CONFIG = "bridgeConfig";
const SETTING_DRAGONROLL_API_URL = "dragonrollApiUrl";
const SETTING_LINK_CODE = "linkCode";
const SETTING_PAIRING_STATUS = "pairingStatus";
const SETTING_SYNC_TOKEN = "syncToken";
const SETTING_AUTO_SYNC = "autoSync";
let syncTimeout;
@@ -16,6 +17,12 @@ const FATAL_LINK_ERRORS = new Set([
"foundry.errors.link-expired",
"foundry.errors.world-already-linked",
]);
// Marks a pairing Dragonroll honoured once and no longer accepts: the campaign
// unlinked this world, so the token this client holds is dead.
const PAIRING_REVOKED = "revoked";
let updatingPairingStatus = false;
let linkedCampaignName = "";
let pairingProblem = "";
let actorSyncTimeout;
let characterSyncRunning = false;
let actorSyncErrorLogged = false;
@@ -140,6 +147,16 @@ Hooks.once("init", () => {
onChange: handleLinkCodeChange,
});
game.settings.register(MODULE_ID, SETTING_PAIRING_STATUS, {
name: "Dragonroll Pairing Status",
hint: "Whether this world is connected to a Dragonroll campaign. The module keeps this text up to date and the pairing lives in the browser of whoever linked the world: there is nothing to set here.",
scope: "client",
config: true,
type: String,
default: "",
onChange: handlePairingStatusChange,
});
game.settings.register(MODULE_ID, SETTING_AUTO_SYNC, {
name: "Dragonroll Auto-sync",
hint: "Keep the linked Dragonroll campaign in step with this world as its actors and items change. Turn this off to stop synchronizing; the actor directory's Dragonroll: Force Sync entry then sends an actor over only when you ask for it.",
@@ -221,6 +238,9 @@ async function setLinkCode(value) {
function handleLinkCodeChange(value) {
if (updatingLinkCodeSetting || handlingLinkCode || !value?.trim()) return;
linkRetriesDisabled = false;
// A code typed by hand supersedes whatever went wrong with the last one.
pairingProblem = "";
setPairingStatus(pairingStatusText());
completeDragonrollCampaignLink(value.trim());
}
@@ -257,13 +277,19 @@ async function completeDragonrollCampaignLink(code, options = {}) {
scheduleSnapshotSync(0);
setTimeout(initializeCharacterSync, 0);
setTimeout(reconcileDragonrollItems, 2000);
linkedCampaignName = String(result.campaign?.name || "").trim();
ui.notifications?.info("This Foundry world is now linked to the Dragonroll campaign.");
await setPairingStatus(pairingStatusText());
} catch (error) {
console.error(`${MODULE_ID} | Could not complete the campaign link.`, error);
// Expired or already-used codes will never redeem, so stop the background
// retry; any error keeps retrying (the Dragonroll server may be restarting).
linkRetriesDisabled = FATAL_LINK_ERRORS.has(error.message);
// Only a code that can never be redeemed belongs in the status: while the
// retry is still running, waiting for Dragonroll is the honest text.
if (linkRetriesDisabled) pairingProblem = linkErrorMessage(error);
if (notifyOnError) ui.notifications?.error(linkErrorMessage(error));
await setPairingStatus(pairingStatusText());
} finally {
handlingLinkCode = false;
}
@@ -278,6 +304,69 @@ async function resumePendingDragonrollLink(options = {}) {
if (code) await completeDragonrollCampaignLink(code, options);
}
// --- Pairing status --------------------------------------------------------
// The pairing status is the sentence the module settings show. Everything in it
// comes from this client plus what Dragonroll last said about its token, so it
// reads correctly from the first frame and is corrected by refreshPairingStatus.
function pairingStatusText() {
if (pairingProblem === PAIRING_REVOKED) {
return "Not connected: this world is no longer linked to the Dragonroll campaign it was paired with. Create a new pairing code there to link it again.";
}
if (getSyncToken()) {
return linkedCampaignName
? `Connected to the Dragonroll campaign "${linkedCampaignName}".`
: "Connected to a Dragonroll campaign.";
}
if (pairingProblem) return `Not connected: Dragonroll did not accept that pairing code (${pairingProblem})`;
if (game.settings.get(MODULE_ID, SETTING_LINK_CODE)?.trim()) {
return "Not connected yet: waiting for Dragonroll to accept this pairing code.";
}
return "Not connected to a Dragonroll campaign. Paste a pairing code from that campaign's settings to link this world.";
}
async function setPairingStatus(text) {
if (game.settings.get(MODULE_ID, SETTING_PAIRING_STATUS) === text) return;
updatingPairingStatus = true;
try {
await game.settings.set(MODULE_ID, SETTING_PAIRING_STATUS, text);
} catch (error) {
console.warn(`${MODULE_ID} | Could not store the Dragonroll pairing status.`, error);
} finally {
updatingPairingStatus = false;
}
}
// Nothing is configured here: anything typed into the status is replaced by the
// status the module actually has.
function handlePairingStatusChange() {
if (updatingPairingStatus) return;
setPairingStatus(pairingStatusText());
}
// A token in this client only proves the world was paired once. Ask Dragonroll
// which campaign that token belongs to, and hear back when the campaign has
// unlinked this world again in the meantime.
async function refreshPairingStatus() {
const token = getSyncToken();
if (!token) {
linkedCampaignName = "";
await setPairingStatus(pairingStatusText());
return;
}
try {
const result = await getDragonroll("foundry/sync/status", token);
linkedCampaignName = String(result.campaign?.name || "").trim();
if (pairingProblem === PAIRING_REVOKED) pairingProblem = "";
} catch (error) {
// An unauthorized token is a campaign that unlinked this world. Any other
// failure (an unreachable Dragonroll, or one old enough to have no status
// route) says nothing about the pairing, so keep showing what we know.
if (error.message === "unauthorized") pairingProblem = PAIRING_REVOKED;
}
await setPairingStatus(pairingStatusText());
}
function scheduleSnapshotSync(delay = 500) {
clearTimeout(syncTimeout);
syncTimeout = setTimeout(publishSnapshot, delay);
@@ -1051,11 +1140,12 @@ async function publishHeartbeat() {
}
Hooks.once("ready", () => {
resumePendingDragonrollLink();
resumePendingDragonrollLink().then(refreshPairingStatus);
setInterval(() => {
if (linkRetriesDisabled) return;
resumePendingDragonrollLink({ notifyOnError: false });
}, 60000);
setInterval(refreshPairingStatus, 60000);
scheduleSnapshotSync(0);
setInterval(publishHeartbeat, 60000);
setTimeout(initializeCharacterSync, 1000);