Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions docs/mirror.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,9 @@ so a message written on one side shows up on the other. Voice channels, categori
Send Messages in both; bots are off; nobody is pinged across. The privacy rule is checked again whenever a
paused link resumes and on every message: a channel that turns private later stops the link ("no longer open
to the same people"). A pair that fails a rule is skipped, the reason
is in the report ("Linking channels through the bridge" and the notes), and the rest are linked.
is in the report ("Linking channels through the bridge" and the notes), and the rest are linked. The report sums
up the whole step in one sentence, for example "35 channels linked, 2 were linked already, 1 not linked (see the
notes)", also when the channels were linked in several batches.
- **Safe to run again.** "Copy again" links only the pairs that have no link yet. A channel that an owner
unlinked on the Bridge page stays unlinked, and a pair the owners bridged by hand is never taken over or
changed (it is reported as skipped). A server can have at most 50 bridged channels this way (10 when
Expand Down Expand Up @@ -176,7 +178,14 @@ update, and a drag that moves many channels becomes one reorder.
(Administrator, Manage Roles and the like), because a new role starts at the bottom where a member with Manage Roles
could hand it out; only after the order is set does Sylo give it its permissions. If a role ranks above Sylo's (the
order cannot be set) the mirror pauses with the roles named, and the new role stays without its permissions until the
Fluxer owner has fixed it and the mirror is resumed.
Fluxer owner has fixed it and the mirror is resumed. If Fluxer refuses the order itself, the report shows "Role
order" as failed with Fluxer's reason, the roles stay without their powerful permissions, and **Copy again** sends
the order again (and then grants them).
- **The channel order is the one Discord shows.** Inside a category the text, announcement, forum and media channels
come first and the voice channels after them (Discord numbers the two kinds separately, and Fluxer does not allow a
voice channel above a text channel); at the top, the channels without a category come before the categories.
Channels made on the Fluxer server by its own people stay where they are. A refused channel order is reported with
Fluxer's reason, and **Copy again** tries it again.
- **Limits.** Sylo plans with Fluxer's defaults (500 emoji and 500 stickers per server, 512 KB per emoji and per
sticker). If Fluxer refuses more because of its own limit, Sylo stops that kind and lists the rest in the report.

Expand Down
98 changes: 76 additions & 22 deletions src/mirror/engine.js
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,14 @@ import {
} from './bridgeLink.js';
import { MirrorError, MirrorPause, classifyError } from './errors.js';
import { checkOwnership } from './ownership.js';
import { NOT_COPIED_MODULES, buildModuleSpec, buildPlan, channelOrder, copiedSets } from './plan.js';
import {
NOT_COPIED_MODULES,
buildModuleSpec,
buildPlan,
channelOrder,
channelPositionUpdates,
copiedSets,
} from './plan.js';
import { snapshotDiscordGuild, snapshotFluxerGuild } from './snapshot.js';
import { createFluxerTarget } from './target.js';
import {
Expand Down Expand Up @@ -882,6 +889,19 @@ export function createEngine(overrides = {}) {
return done('copied', { notes: built.notes });
}

/**
* An order Fluxer refused, said plainly. Only a refusal of this one step is reworded: a rate limit, a network
* failure or a permission error goes on as it is (waited for, retried, or counted toward a pause).
*/
function orderRefused(err, what, after) {
const c = classifyError(err);
if (c.kind !== 'item' || err instanceof MirrorError) return err;
return new MirrorError(
`Fluxer did not take the ${what}: ${c.message.replace(/[.\s]+$/, '')}.${after}`,
'item'
);
}

async function reorder(ctx, which) {
if (which === 'roles') {
const order = roleOrderOf(ctx);
Expand All @@ -902,7 +922,19 @@ export function createEngine(overrides = {}) {
updates.push({ id: mapping.targetId, position: i + 1 });
}
const notes = [];
if (updates.length > 0) await ctx.target.setRolePositions(updates);
// A failed order sets nothing: no mapping, no grants. The roles stay without their powerful permissions, and the
// step is planned again by "Copy again" (or the next role change on Discord).
if (updates.length > 0) {
try {
await ctx.target.setRolePositions(updates);
} catch (err) {
throw orderRefused(
err,
'role order',
' The copied roles stay without their powerful permissions until the order is set. Copy again tries it once more.'
);
}
}
await store.putMapping({
pairId: ctx.pair.id,
kind: 'order',
Expand All @@ -919,14 +951,19 @@ export function createEngine(overrides = {}) {
const hash = specHash(layout);
const m = await store.getMapping(ctx.pair.id, 'order', 'channels');
if (m && m.specHash === hash) return done('unchanged');
const updates = [];
const targetIdOf = new Map();
for (const item of layout) {
const mapping = await store.getMapping(ctx.pair.id, 'channel', item.id);
if (!mapping) continue;
const parent = item.parentId ? await store.getMapping(ctx.pair.id, 'channel', item.parentId) : null;
updates.push({ id: mapping.targetId, position: item.position, parentId: parent?.targetId ?? null });
if (mapping?.targetId) targetIdOf.set(item.id, mapping.targetId);
}
const updates = channelPositionUpdates(layout, targetIdOf, ctx.target.listChannels());
if (updates.length > 1) {
try {
await ctx.target.setChannelPositions(updates);
} catch (err) {
throw orderRefused(err, 'channel order', ' Copy again tries it once more.');
}
}
if (updates.length > 1) await ctx.target.setChannelPositions(updates);
await store.putMapping({
pairId: ctx.pair.id,
kind: 'order',
Expand Down Expand Up @@ -1009,7 +1046,17 @@ export function createEngine(overrides = {}) {
async function linkChannels(ctx, job) {
const tried = new Set(job.payload?.tried ?? []);
const res = await deps.linkMirroredChannels(ctx.pair.id, { skip: tried });
const skippedPairs = res.skipped ?? [];
// The step can take several batches; each one says where the whole step stands, in one sentence. `tally` carries
// the counts from batch to batch: what this step linked, what was linked before it began (a later batch counts
// the links of the earlier ones as "already"), and the channels it could not link (each reported once).
const prev = job.payload?.tally ?? null;
const reported = new Set(prev?.notLinked ?? []);
const skippedPairs = (res.skipped ?? []).filter((s) => !reported.has(s.sourceId));
const tally = {
linked: (prev?.linked ?? 0) + (res.linked ?? 0),
before: prev ? prev.before : (res.already ?? 0),
notLinked: [...reported, ...skippedPairs.map((s) => s.sourceId)],
};
const notes = skippedPairs.map((s) => ({
code: `bridge-${s.code}`,
scope: 'channel',
Expand All @@ -1025,19 +1072,24 @@ export function createEngine(overrides = {}) {
kind: 'bridge',
sourceId: job.sourceId,
stepKey: job.stepKey,
payload: { ...job.payload, tried: [...tried, ...(res.tried ?? [])] },
payload: { ...job.payload, tried: [...tried, ...(res.tried ?? [])], tally },
now: deps.now(),
});
}
return done(linkSentence(tally, res), { notes, remote: res.linked > 0 });
}

/** The bridge step in one sentence: "35 channels linked, 2 were linked already, 1 not linked (see the notes)". */
function linkSentence(tally, res) {
const channels = (n) => `${n} ${n === 1 ? 'channel' : 'channels'}`;
const following = res.remaining ?? 0;
const parts = [];
if (res.linked > 0) parts.push(`${res.linked} channels linked`);
if ((res.already ?? 0) > 0) parts.push(`${res.already} already linked`);
if (skippedPairs.length > 0) parts.push(`${skippedPairs.length} not linked (see the notes)`);
if ((res.remaining ?? 0) > 0) parts.push(`${res.remaining} more follow`);
return done(parts.length ? parts.join(', ') : `not linked: ${res.reason ?? 'nothing to link'}`, {
notes,
remote: res.linked > 0,
});
if (tally.linked > 0 || following > 0)
parts.push(`${channels(tally.linked)} linked${following > 0 ? ' so far' : ''}`);
if (tally.before > 0) parts.push(`${tally.before} ${tally.before === 1 ? 'was' : 'were'} linked already`);
if (tally.notLinked.length > 0) parts.push(`${tally.notLinked.length} not linked (see the notes)`);
if (following > 0) parts.push(`${following} more follow`);
return parts.length ? parts.join(', ') : `not linked: ${res.reason ?? 'nothing to link'}`;
}

async function perform(ctx, job) {
Expand Down Expand Up @@ -1483,16 +1535,18 @@ export function createEngine(overrides = {}) {
detail: j.detail,
}));
const notes = jobs.flatMap((j) => j.notes);
// The bridge step can take several runs (a batch of channels each): show them as one.
// The bridge step can take several runs (a batch of channels each): show them as one. Each batch's detail already
// sums up the whole step so far, so the latest one is the sentence to show.
const links = jobs.filter((j) => j.op === 'link');
const open = links.find((j) => ['pending', 'running', 'failed'].includes(j.status));
const bridge = links.length
? {
status: open ? open.status : links[links.length - 1].status,
detail: links
.map((j) => j.detail)
.filter(Boolean)
.join('; '),
detail:
links
.map((j) => j.detail)
.filter(Boolean)
.at(-1) ?? '',
}
: null;
return {
Expand Down
15 changes: 14 additions & 1 deletion src/mirror/errors.js
Original file line number Diff line number Diff line change
Expand Up @@ -40,12 +40,25 @@ export function isNotFound(err) {
return /^(ROLE|CHANNEL|EMOJI|STICKER)_NOT_FOUND$/.test(String(err.code ?? ''));
}

/**
* What Fluxer said about the fields of a refused request. A 400 says only "Invalid form body." in its message; the
* reasons are in `errors` ([{ path, message, code }]), which the SDK keeps on the error.
*/
function fieldErrors(err) {
const list = Array.isArray(err?.errors) ? err.errors : [];
const parts = list
.slice(0, 3)
.map((e) => [e?.path, e?.message ?? e?.code].filter(Boolean).join(': '))
.filter(Boolean);
return parts.length ? ` (${parts.join('; ')})` : '';
}

/**
* @param {any} err
* @returns {{ kind: ErrorKind, retryAfterMs?: number, message: string }}
*/
export function classifyError(err) {
const message = String(err?.message ?? err ?? 'Unknown error').slice(0, 300);
const message = `${String(err?.message ?? err ?? 'Unknown error')}${fieldErrors(err)}`.slice(0, 300);
if (err instanceof MirrorError) return { kind: err.kind, message };
// The SDK wraps a failed look-up in an error that keeps the HTTP status only in `cause`.
const status = Number(err?.statusCode ?? err?.status ?? err?.cause?.statusCode ?? err?.cause?.status ?? 0);
Expand Down
103 changes: 91 additions & 12 deletions src/mirror/plan.js
Original file line number Diff line number Diff line change
Expand Up @@ -405,23 +405,102 @@ export function buildPlan({
return { steps, notes, summary: summarise(steps) };
}

/** The copied channels in the order they sit: for each parent, its children by position. */
/** Discord's voice-like channels (a stage becomes a voice channel on Fluxer). */
const VOICE_LIKE = new Set([DISCORD_CHANNEL.VOICE, DISCORD_CHANNEL.STAGE]);

/**
* The copied channels in the order Discord shows them, as the list of moves sent to Fluxer.
*
* Discord numbers text-like and voice channels separately (a voice channel at position 0 and a text channel at
* position 0 can share a category), and shows the text-like ones first; so a channel's place is its kind first and
* its position second, never the position alone. At the top, the channels without a category come before the
* categories, as on Discord.
*
* The list is in the order the moves are sent: first everything at the top (categories carry their channels along),
* then the text-like channels of every category, then the voice channels. Fluxer applies the moves one at a time and
* refuses any move that leaves a voice channel above a text channel in a category; in this order every text-like
* channel is in place before a voice channel moves, so no step does.
*
* Each item: `position` is its index among its siblings (0 first); `voice` marks a voice channel in a category.
* @returns {Array<{ id: string, parentId: string | null, position: number, voice?: boolean }>}
*/
export function channelOrder(source, copied) {
const list = source.channels.filter((c) => copied.has(c.id));
const out = [];
const groups = new Map();
const isCategory = (c) => c.type === DISCORD_CHANNEL.CATEGORY;
const categories = new Set(list.filter(isCategory).map((c) => c.id));
const rank = (c) => (VOICE_LIKE.has(c.type) ? 1 : 0);
const byLayout = (a, b) => rank(a) - rank(b) || byPosition(a, b);
const roots = [];
const children = new Map();
for (const c of list) {
const parent = c.parentId && copied.has(c.parentId) ? c.parentId : '';
if (!groups.has(parent)) groups.set(parent, []);
groups.get(parent).push(c);
if (!isCategory(c) && c.parentId && categories.has(c.parentId)) {
if (!children.has(c.parentId)) children.set(c.parentId, []);
children.get(c.parentId).push(c);
} else {
roots.push(c);
}
}
for (const [parent, children] of groups) {
children
.sort(byPosition)
.forEach((c, i) => out.push({ id: c.id, parentId: parent || null, position: i }));
const top = [
...roots.filter((c) => !isCategory(c)).sort(byLayout),
...roots.filter(isCategory).sort(byPosition),
];
const out = top.map((c, i) => ({ id: c.id, parentId: null, position: i }));
const groups = top
.filter(isCategory)
.map((cat) =>
(children.get(cat.id) ?? [])
.sort(byLayout)
.map((c, i) => ({ id: c.id, parentId: cat.id, position: i, voice: rank(c) === 1 }))
);
for (const group of groups) out.push(...group.filter((c) => !c.voice));
for (const group of groups) out.push(...group.filter((c) => c.voice));
return out;
}

/** Fluxer's voice channel type, and its category type: everything else sorts with the text channels. */
const FLUXER_VOICE = 2;
const FLUXER_CATEGORY = 4;

/**
* The moves for PATCH /guilds/{id}/channels, from channelOrder(): the Discord ids turned into Fluxer ids, and every
* position counted among the channels that are really there. A channel that has no copy on Fluxer (it could not be
* made) is left out and counts for nobody's position, and so is a channel whose category has no copy; otherwise a
* text channel could be placed after a voice channel, which Fluxer refuses.
*
* Channels on Fluxer that are not the mirror's stay where they are; a voice channel of the mirror's goes after every
* text-like channel of its category, the server's own ones included, so it never lands above one of them.
* @param {ReturnType<typeof channelOrder>} layout
* @param {Map<string, string>} targetIdOf Discord channel id -> Fluxer channel id
* @param {Array<{ id: string, type: number, parentId: string | null }>} fluxerChannels what is on Fluxer now
* @returns {Array<{ id: string, position: number, parentId: string | null }>}
*/
export function channelPositionUpdates(layout, targetIdOf, fluxerChannels = []) {
const ours = new Set(targetIdOf.values());
const foreignText = new Map();
for (const c of fluxerChannels) {
if (ours.has(c.id) || !c.parentId || c.type === FLUXER_VOICE || c.type === FLUXER_CATEGORY) continue;
foreignText.set(c.parentId, (foreignText.get(c.parentId) ?? 0) + 1);
}
const placed = new Map(); // `${parent}|text` and `${parent}|voice` -> how many are placed
const count = (key) => placed.get(key) ?? 0;
const updates = [];
for (const item of layout) {
const id = targetIdOf.get(item.id);
if (!id) continue;
const parentId = item.parentId ? (targetIdOf.get(item.parentId) ?? null) : null;
if (item.parentId && !parentId) continue;
const group = parentId ?? '';
let position;
if (item.voice) {
position = count(`${group}|text`) + (foreignText.get(parentId) ?? 0) + count(`${group}|voice`);
placed.set(`${group}|voice`, count(`${group}|voice`) + 1);
} else {
position = count(`${group}|text`);
placed.set(`${group}|text`, position + 1);
}
updates.push({ id, position, parentId });
}
// Categories are ordered among themselves like any top-level channel.
return out.sort((a, b) => (a.parentId ?? '').localeCompare(b.parentId ?? '') || a.position - b.position);
return updates;
}

function slotsLeft(cap, targetCount, mapped) {
Expand Down
36 changes: 34 additions & 2 deletions src/mirror/target.js
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,13 @@ export function createFluxerTarget(guild) {

const gone = () => Object.assign(new Error('Unknown channel or role'), { statusCode: 404 });

// The SDK's REST client, for the routes whose SDK method does not fit Fluxer's answer.
const rest = () => {
const client = guild.client?.rest;
if (typeof client?.patch !== 'function') throw new Error('The Fluxer REST client is not available.');
return client;
};

return {
kind: 'fluxer',
id: String(guild.id),
Expand Down Expand Up @@ -181,8 +188,18 @@ export function createFluxerTarget(guild) {
if (!role) throw gone();
await role.delete('Mirrored from the Discord server');
},
/**
* PATCH /guilds/{id}/roles with `[{ id, position }]`. Fluxer answers 204 No Content; the SDK's
* guild.setRolePositions() maps over the answer as if it were the role list (Discord's answer) and throws on it
* after the order was set, so the route is called through the SDK's REST client instead. The new positions reach
* the role cache through the gateway (GUILD_ROLE_UPDATE_BULK).
* @param {Array<{ id: string, position: number }>} updates
*/
async setRolePositions(updates) {
await guild.setRolePositions(updates);
await rest().patch(`/guilds/${guild.id}/roles`, {
body: updates.map((u) => ({ id: String(u.id), position: Number(u.position) })),
auth: true,
});
},

// --- channels ---
Expand All @@ -203,8 +220,23 @@ export function createFluxerTarget(guild) {
if (!channel) throw gone();
await channel.delete({ reason: 'Mirrored from the Discord server' });
},
/**
* PATCH /guilds/{id}/channels with `[{ id, position, parent_id, lock_permissions }]` (Fluxer answers 204). Fluxer
* applies the items one by one, in the order sent: `position` is the index among the channel's new siblings at
* that moment, and a move that leaves a voice channel above a text channel in a category is refused (400). The
* engine sends them in an order that keeps every step valid (see channelPositionUpdates in plan.js).
* @param {Array<{ id: string, position: number, parentId: string | null }>} updates
*/
async setChannelPositions(updates) {
await guild.setChannelPositions(updates);
await rest().patch(`/guilds/${guild.id}/channels`, {
body: updates.map((u) => ({
id: String(u.id),
position: Number(u.position),
parent_id: u.parentId == null ? null : String(u.parentId),
lock_permissions: false,
})),
auth: true,
});
},

// --- emoji and stickers ---
Expand Down
Loading
Loading