officerdev/platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

a plugin can claim a file type the platform cannot read

Browse Source 
the file browser's thumbnailer read what sharp and ffmpeg read, and that list was a
constant in core. HEIC forced the question: sharp's bundled libheif has no HEVC
decoder, and teaching core to shell out to ImageMagick means the PLATFORM acquiring
a system dependency for one format. that is a plugin's job.

so a manifest may declare `fileTypes` — extensions, plus a thumbnail path and a
render path on its own sidecar. `ls` unions those with core's, so a file only
promises a thumbnail when something can actually produce one. `/thumb` forwards a
claimed type to whoever claimed it.

CORE DOES NOT KNOW av-club EXISTS. it reads a claim at runtime from whatever is
installed and enabled, calls a path by name, and falls back to a file icon when
nothing claims the type. no import, no name, no special case.

PROVEN BY DISABLING IT: heic reports thumb=image with av-club enabled, thumb=none
disabled, image again re-enabled. that is the whole requirement — the file browser
is what it was without the plugin — and it is a test rather than a claim.

the plugin's bytes are cached by CORE, under the same key everything else uses, so
a HEIC thumbnail is produced once and then served from disk like any other. that is
why `buildThumbnail` takes a producer rather than there being a second path beside
it: the cache key with its mtime and size, the concurrency cap and the remembered
failures all live in that one function, and a parallel path would be a second place
to forget the negative caching.

TWO THINGS FOUND BY WIRING IT UP. a claimed-but-not-running sidecar is skipped
rather than recorded, or `ls` promises a thumbnail that cannot be fetched while a
plugin restarts. and the sidecar authenticates: it accepts `x-officer-user` from
anything on loopback, by its own design, so core sends the account the request is
FOR — passing anything else would be lying to a plugin that scopes per user.

verified: HEIC 2 MB in, 12 KB out, 5.4s cold and 101ms cached; png and mp4
unchanged; 1665 tests; docs:check green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043
This commit is contained in:
pastilhas
2026-08-29 07:50:51 +01:00
co-authored by Claude Opus 5
parent 9cb875ca79
commit 111618bd7f
4 changed files with 199 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/servers/api/file-browser/router.ts
+53 -5
View File
@@ -10,6 +10,7 @@ import { readTtsConfig } from '@@/api/server-settings/tts';
import { readOcrConfig } from '@@/api/server-settings/ocr';
import { getUserSettings } from 'officerdb';
import { buildThumbnail, clampSize, thumbnailKind } from './thumbnails';
import { pluginFileTypes, sidecarFetch } from './plugin-file-types';
async function getUserTtsVoice(userId: number): Promise<string | null> {
try {
@@ -204,6 +205,12 @@ router.get('/ls', async (ctx) => {
}
return ctx.json({ path: '/', entries: [], reset: true });
}
/*
What a plugin can show that we cannot. Resolved ONCE per listing rather than per entry — it reads the
database, and a folder of two hundred files would otherwise ask two hundred times for one answer.
*/
const claimed = await pluginFileTypes();
const entries = await Promise.all(
names.map(async (name) => {
const fullPath = resolve(absPath, name);
@@ -228,7 +235,18 @@ router.get('/ls', async (ctx) => {
Costs nothing: this entry has just been stat'd and the answer is a lookup on its name.
*/
thumb: isDirectory ? null : thumbnailKind(name),
/*
Core's own answer first, then a plugin's claim.
A file only says `thumb` when something can actually produce one: core for the formats sharp
and ffmpeg read, a plugin for what it declared in `fileTypes`. Without that second half, `.heic`
promised a thumbnail nothing would make and cost a 422 on every scroll — which is why core
stopped claiming it.
*/
thumb: isDirectory
? null
: (thumbnailKind(name) ??
(claimed.has(name.slice(name.lastIndexOf('.') + 1).toLowerCase()) ? 'image' : null)),
};
}),
);
@@ -375,12 +393,42 @@ router.get('/thumb', async (ctx) => {
if (!relPath) throw errors.BAD_REQUEST('path is required');
const absPath = resolveUserPath(rootDir, relPath);
const size = clampSize(ctx.req.query('size'));
const kind = thumbnailKind(relPath);
// 415 rather than 404: the file is there, it is simply not something a frame can be taken from. The
// client does not ask for these, so this is the answer to a stale tab rather than to normal use.
if (!kind) return ctx.text('no thumbnail for this file type', 415);
const result = await buildThumbnail(absPath, getUserDataDir(user.email), kind, clampSize(ctx.req.query('size')));
/*
A type core cannot read, but an installed plugin can.
Forwarded to the plugin's own sidecar and cached HERE, under the same key everything else uses —
so a HEIC thumbnail is produced once and then served from disk like any other, and the plugin is
not asked again on every scroll.
`buildThumbnail` is given the fetch rather than a path: the caching, the concurrency limit and the
remembered failures are all in that one function, and a second copy of them here for this one case
is how the two would come to behave differently.
*/
if (!kind) {
const claimed = (await pluginFileTypes()).get(relPath.slice(relPath.lastIndexOf('.') + 1).toLowerCase());
if (claimed?.thumbnail) {
const fetched = await buildThumbnail(absPath, getUserDataDir(user.email), 'image', size, async () => {
const res = await sidecarFetch(
`${claimed.thumbnail}?path=${encodeURIComponent(absPath)}&size=${size}`,
user.email,
);
return res.ok ? Buffer.from(await res.arrayBuffer()) : null;
});
if (!fetched.ok) return ctx.text(fetched.reason, 422);
return new Response(Bun.file(fetched.path), {
headers: { 'Content-Type': 'image/jpeg', 'Cache-Control': 'private, max-age=31536000, immutable' },
});
}
// 415 rather than 404: the file is there, it is simply not something anything here can read. The
// client does not ask for these, so this answers a stale tab rather than normal use.
return ctx.text('no thumbnail for this file type', 415);
}
const result = await buildThumbnail(absPath, getUserDataDir(user.email), kind, size);
// 422, and the client falls back to the file icon. Not 500: a file ffmpeg cannot read is a fact about
// the file, and logging it as a server error would bury the ones that are.
if (!result.ok) return ctx.text(result.reason, 422);