Files
gerbeur/api/services/backlink-service.ts
khannurien d62e4a9883
All checks were successful
Build and Publish Docker Image / build-and-push (push) Successful in 47s
Build and deploy docs / build-and-push (push) Successful in 26s
v3: the backend is documented for deno doc, one way in every file, and the docs build and publish themselves — comments were in three shapes: file headers as // lines, as an untagged /** */ (which deno doc drops, only an @module block counts) or missing; 43 exports described by a // deno doc can't see, two JSDoc blocks sitting on the wrong declaration and one duplicated; endpoints commented in 5 of 18 route files, three ways, on router.get() calls no doc tool reads. The rule, applied to every non-test module of api/, migrations included: each opens with a /** … @module */ block; every export has JSDoc, and so does every field of an exported interface; a comment describing a declaration is /** */, // only notes code; functions open with a verb, everything else with a noun phrase; parameters are named in the prose, {@link} only for symbols in scope; whatever throws to its caller says so with @throws (for an APIException, the statuses and when); a router's JSDoc lists its endpoints, method and path, who may call it, what it does. deno doc --lint goes from 528 errors to none in api/ (shared/ keeps its 385; it is next). The lint also wanted explicit types on config.ts's settings and a few return types, JsonLdResult exported, and the routers typed Router. deno task doc builds the HTML reference into docs/ from every module of api/ and shared/ but the tests, deno task doc:lint lints it; the index page is the module doc of a root mod.ts (deno.json's exports), which introduces the backend, shared/ and the frontend to come and links every module, and mod.test.ts fails when one is missing. The docs workflow builds it on every push to main that touches them and publishes it to the gh-pages branch, like publish-assistant's. Two defects found along the way are fixed: a private playlist's cover was served to anyone who had its id or slug, and now needs its owner's media token, as private dump files do (playlistImageUrl adds it for private playlists only, so public cover URLs stay the same for everyone); og.ts and static.ts each filled index.html's placeholders, and now share lib/index-html.ts, so the OG middleware picks up a rebuilt index.html instead of keeping the first it read. The README states the documentation rule. 205 backend and 628 frontend tests pass.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 21:07:40 +00:00

127 lines
4.0 KiB
TypeScript

/**
* Backlinks between dumps: which dumps a dump's description and comments link
* to, and the dumps related to one through them.
*
* @module
*/
import type { Dump } from "../../shared/dump.ts";
import { db, transaction } from "../db/connection.ts";
import {
DUMP_SELECT_COLUMNS as SELECT_COLS,
dumpRowToApi,
isDumpRow,
} from "../model/dump.ts";
import { UUID_RE } from "../lib/slugify.ts";
/**
* An http(s) URL in free text — stops at whitespace or markdown-link
* delimiters (so `[text](url)` and `<url>` don't swallow the closing char).
*/
const URL_RE = /https?:\/\/[^\s)\]<>"']+/g;
/**
* A link to another dump's page on this same site (e.g. pasted from
* the address bar) — host-agnostic, since the configured public URL can differ
* between dev/prod/reverse-proxy setups. Matches `/dumps/{slug-or-id}`,
* ignoring any trailing path/query/hash (so `/edit` or `#comment-x` links
* still resolve to the same target dump).
*/
const DUMP_PATH_RE = /^\/dumps\/([^/?#]+)/;
/** Returns `url` as the URL parser normalises it, or null when it isn't one. */
function canonicalize(url: string): string | null {
try {
return new URL(url).toString();
} catch {
return null;
}
}
/** Resolves a same-site `/dumps/{slug-or-id}` path segment to a dump id. */
function resolveDumpPathId(idOrSlug: string): string | null {
const row = UUID_RE.test(idOrSlug)
? db.prepare(`SELECT id FROM dumps WHERE id = ?;`).get(idOrSlug)
: db.prepare(`SELECT id FROM dumps WHERE slug = ?;`).get(idOrSlug);
return (row as { id: string } | undefined)?.id ?? null;
}
/**
* Re-derives the backlinks contributed by one text source (a dump's own
* `comment` field, or a single comment's `body`) and persist them. Always
* deletes the source's previous contribution first, so editing/clearing the
* text correctly removes stale links — unlike `linkAttachments`/`notifyMentions`,
* which are purely additive.
*/
export function relinkBacklinks(
sourceType: "dump_comment" | "comment",
sourceId: string,
fromDumpId: string,
text: string,
): void {
const targetIds = new Set<string>();
const externalUrls = new Set<string>();
for (const match of text.matchAll(URL_RE)) {
const canonical = canonicalize(match[0]);
if (!canonical) continue;
let parsed: URL;
try {
parsed = new URL(canonical);
} catch {
continue;
}
const pathMatch = DUMP_PATH_RE.exec(parsed.pathname);
if (pathMatch) {
const resolved = resolveDumpPathId(decodeURIComponent(pathMatch[1]));
if (resolved) targetIds.add(resolved);
} else {
externalUrls.add(canonical);
}
}
if (externalUrls.size > 0) {
const placeholders = [...externalUrls].map(() => "?").join(", ");
const rows = db.prepare(
`SELECT id FROM dumps WHERE url IN (${placeholders});`,
).all(...externalUrls) as { id: string }[];
for (const row of rows) targetIds.add(row.id);
}
targetIds.delete(fromDumpId); // no self-links
transaction(() => {
db.prepare(
`DELETE FROM dump_backlinks WHERE source_type = ? AND source_id = ?;`,
).run(sourceType, sourceId);
const createdAt = new Date().toISOString();
const insert = db.prepare(
`INSERT INTO dump_backlinks (source_type, source_id, from_dump_id, to_dump_id, created_at)
VALUES (?, ?, ?, ?, ?);`,
);
for (const toDumpId of targetIds) {
insert.run(sourceType, sourceId, fromDumpId, toDumpId, createdAt);
}
});
}
/**
* Returns the dumps linked to or from `dumpId`, newest first and at most 20,
* without the private ones the requesting user can't see.
*/
export function getRelatedDumps(
dumpId: string,
requestingUserId?: string,
): Dump[] {
const rows = db.prepare(
`SELECT ${SELECT_COLS} FROM dumps WHERE id IN (
SELECT to_dump_id FROM dump_backlinks WHERE from_dump_id = ?
UNION
SELECT from_dump_id FROM dump_backlinks WHERE to_dump_id = ?
) AND (is_private = 0 OR user_id = ?)
ORDER BY created_at DESC LIMIT 20;`,
).all(dumpId, dumpId, requestingUserId ?? "");
return rows.filter(isDumpRow).map(dumpRowToApi);
}