Files
stack/packages/library/src/mirror.mjs
T

262 lines
15 KiB
JavaScript

// C2-04: host-only bare library storage. No remote, fetch, credential or
// working tree. The broker receives these functions through the runtime.
import { constants, closeSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync,
openSync, readSync, readdirSync, realpathSync, rmSync } from 'node:fs';
import { dirname, isAbsolute, join, normalize } from 'node:path';
import { execFile, spawn } from 'node:child_process';
import { projectRepo, noLinks } from '../../project/src/paths.mjs';
import { git } from '../../project/src/git.mjs';
import { checkMapping } from './mapping.mjs';
import { classify } from './scope.mjs';
import { LibraryError, RULES } from './problems.mjs';
import { listTree, readLibrary, readTexts } from './reader.mjs';
export const SYNC_STATE_FILE = 'mosaic-library-sync.json';
const LOCK_FILE = 'mosaic-library-sync.lock';
const STATE_MAX = 8 * 1024 * 1024;
const SHA = /^[a-f0-9]{40}$/;
const fail = (code, message = code) => { throw new LibraryError(code, message); };
const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
const keys = (value, expected) => object(value) && Object.keys(value).length === expected.length
&& Object.keys(value).every(key => expected.includes(key));
const optional = (value, check) => value === null || check(value);
const utc = value => {
if (typeof value !== 'string') return false;
try { return new Date(value).toISOString() === value; } catch { return false; }
};
const empty = branch => ({ version: 1, branch, served: null, lastFetch: null, lastError: null, diverged: null, problems: [] });
function contextEntry(context) {
const { business, project } = context;
if (!Object.hasOwn(business?.projects ?? {}, project)) fail('project-not-declared');
const entry = business.projects[project];
if (entry?.kind !== 'library') fail('library-mapping-invalid', 'expected a library project');
return checkMapping(entry);
}
export function mirrorPath(context) {
contextEntry(context);
try { return projectRepo(context, { allowLibrary: true }); }
catch (error) { throw new LibraryError(error.code ?? 'library-git', 'unsafe mirror path'); }
}
function ownedRoot(mirror) {
try {
if (typeof mirror !== 'string' || !isAbsolute(mirror) || normalize(mirror) !== mirror) throw Error();
noLinks(mirror);
const st = lstatSync(mirror);
if (!st.isDirectory() || st.uid !== process.getuid() || (st.mode & 0o077) || realpathSync(mirror) !== mirror) throw Error();
} catch { fail('library-git', 'expected a private owned bare mirror'); }
}
function privateFile(st) {
return st.isFile() && st.uid === process.getuid() && st.nlink === 1 && (st.mode & 0o077) === 0;
}
async function inspectMirrorUnchecked(mirror) {
ownedRoot(mirror);
const normal = ['HEAD', 'config', 'description', 'hooks', 'info', 'objects', 'refs', 'logs', 'packed-refs', 'shallow', 'FETCH_HEAD', 'ORIG_HEAD'];
const allowed = new Set([...normal, ...normal.filter(name => !['hooks', 'info', 'objects', 'refs', 'logs', 'description'].includes(name)).map(name => name + '.lock'), SYNC_STATE_FILE, LOCK_FILE]);
const top = readdirSync(mirror);
if (top.some(name => !allowed.has(name)) || ['HEAD', 'config', 'objects', 'refs'].some(name => !top.includes(name)))
fail('library-git', 'unexpected bare mirror layout');
for (const path of ['commondir', 'objects/info/alternates', 'objects/info/http-alternates'])
if (existsSync(join(mirror, path))) fail('library-git', 'Git metadata indirection refused');
const walk = (folder, topLevel = false) => {
for (const name of readdirSync(folder)) {
const file = join(folder, name); let st;
try { st = lstatSync(file); }
catch (error) { if (error.code === 'ENOENT') continue; throw error; }
const state = topLevel && [SYNC_STATE_FILE, LOCK_FILE].includes(name);
if (state) { if (!privateFile(st)) fail('library-state-invalid', 'unsafe state or lock metadata'); }
else if (st.isDirectory() && !st.isSymbolicLink()) walk(file);
else if (!st.isFile() || st.nlink !== 1 || st.uid !== process.getuid()) fail('library-git', 'unsafe Git metadata');
}
};
walk(mirror, true);
if (!top.includes(LOCK_FILE)) fail('library-state-invalid', 'mirror lock file missing');
if (lstatSync(join(mirror, 'config')).size > 65536) fail('library-git', 'Git config too large');
let config;
try { config = await git(mirror, ['config', '--no-includes', '--file', join(mirror, 'config'), '--list', '--null']); }
catch { fail('library-git', 'cannot inspect mirror config'); }
const values = { 'core.repositoryformatversion': ['0'], 'core.filemode': ['true', 'false'], 'core.bare': ['true'],
'core.logallrefupdates': ['true', 'false'], 'core.ignorecase': ['true', 'false'] };
let bare = false;
for (const item of config.split('\0').filter(Boolean)) {
const at = item.indexOf('\n'), key = item.slice(0, at), value = item.slice(at + 1);
if (key === 'core.bare' && value === 'true') bare = true;
if (at < 0 || !values[key]?.includes(value)) fail('library-git', 'unsupported bare mirror config');
}
if (!bare) fail('library-git', 'expected a bare repository');
}
async function inspectMirror(mirror) {
try { await inspectMirrorUnchecked(mirror); }
catch (error) {
if (error instanceof LibraryError) throw error;
fail('library-git', 'unreadable bare mirror metadata');
}
}
export async function ensureMirror(context) {
const mirror = mirrorPath(context);
if (existsSync(mirror)) { await inspectMirror(mirror); return mirror; }
const parent = dirname(mirror); mkdirSync(parent, { recursive: true, mode: 0o700 }); noLinks(parent);
const staged = mkdtempSync(join(parent, '.library-init-'));
const original = lstatSync(staged);
const isOwnStage = st => st.isDirectory() && st.uid === process.getuid() && st.dev === original.dev && st.ino === original.ino;
try {
await git(staged, ['init', '--bare', '--initial-branch=served', '--template=']);
const fd = openSync(join(staged, LOCK_FILE), constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
closeSync(fd);
await inspectMirror(staged);
// Coreutils versions disagree on the status of a skipped no-clobber
// rename. The original inode, rather than that status, decides who won.
const moveError = await new Promise(resolve => execFile('/usr/bin/mv', ['--no-clobber', '--no-target-directory', staged, mirror],
{ timeout: 5000, maxBuffer: 65536, env: { PATH: '/usr/bin:/bin', LC_ALL: 'C' } }, error => resolve(error)));
let remaining;
try { remaining = lstatSync(staged); } catch (error) { if (error.code !== 'ENOENT') throw error; }
if (remaining) {
if (!isOwnStage(remaining)) fail('library-git', 'staging directory was replaced');
// A skipped rename is valid only when another intact mirror won.
// Signals, timeouts and spawn failures are always genuine errors.
if (moveError && (typeof moveError.code !== 'number' || moveError.killed || moveError.signal)) throw moveError;
} else {
if (!isOwnStage(lstatSync(mirror))) fail('library-git', 'mirror publication identity mismatch');
if (moveError) throw moveError;
}
await inspectMirror(mirror);
return mirror;
} catch (error) {
if (error instanceof LibraryError) throw error;
fail('library-git', 'bare mirror initialization refused');
} finally {
let remaining;
try { remaining = lstatSync(staged); } catch (error) { if (error.code !== 'ENOENT') throw error; }
if (remaining) {
if (!isOwnStage(remaining)) fail('library-git', 'refusing to remove replaced staging directory');
rmSync(staged, { recursive: true });
}
}
}
// Each acquisition opens a distinct description. flock(1) inherits it as
// fd 3 and exits after acquisition; this parent's fd retains the lock.
export async function withLibraryLock(mirror, operation) {
ownedRoot(mirror);
let fd;
try {
try {
fd = openSync(join(mirror, LOCK_FILE), constants.O_RDWR | constants.O_NOFOLLOW | constants.O_NONBLOCK);
if (!privateFile(fstatSync(fd))) fail('library-state-invalid', 'unsafe library lock');
} catch { fail('library-state-invalid', 'library lock missing or unsafe'); }
await new Promise((resolve, reject) => {
const child = spawn('/usr/bin/flock', ['--exclusive', '--wait', '5', '--conflict-exit-code', '75', '3'],
{ env: { PATH: '/usr/bin:/bin', LC_ALL: 'C' }, stdio: ['ignore', 'ignore', 'ignore', fd] });
child.once('error', () => reject(new LibraryError('library-state-invalid', 'host requires /usr/bin/flock')));
child.once('close', code => code === 0 ? resolve() : reject(new LibraryError(code === 75 ? 'library-sync-busy' : 'library-state-invalid', 'library lock acquisition refused')));
});
try {
const heldStat = fstatSync(fd), pathStat = lstatSync(join(mirror, LOCK_FILE));
if (!privateFile(pathStat) || pathStat.ino !== heldStat.ino || pathStat.dev !== heldStat.dev) throw Error();
} catch { fail('library-state-invalid', 'library lock was replaced'); }
let held = true;
const pending = new Set();
const readSyncState = options => {
if (!held) return Promise.reject(new LibraryError('library-state-invalid', 'library lock scope expired'));
const read = readStateHeld(mirror, options).finally(() => pending.delete(read));
pending.add(read); read.catch(() => {});
return read;
};
try { return await operation({ readSyncState }); }
finally {
held = false;
// An accidentally unawaited scoped read must finish before this fd
// releases the lock. No new read can start after the callback ends.
await Promise.allSettled([...pending]);
}
} finally { if (fd !== undefined) closeSync(fd); }
}
export async function servedCommit(mirror) {
await inspectMirror(mirror);
try {
const refs = await git(mirror, ['for-each-ref', '--format=%(refname) %(objectname)', 'refs/heads/served']);
const line = refs.split('\n').find(line => line.startsWith('refs/heads/served '));
if (!line) {
if (existsSync(join(mirror, 'refs/heads/served'))) fail('library-state-invalid', 'invalid served ref');
return null;
}
const commit = line.slice('refs/heads/served '.length);
if (!SHA.test(commit) || await git(mirror, ['cat-file', '-t', commit]) !== 'commit') fail('library-state-invalid', 'served ref must name a commit');
return commit;
} catch { fail('library-state-invalid', 'served ref is unreadable'); }
}
function validProblem(value) {
return object(value) && Object.keys(value).every(key => ['code', 'path', 'message', 'line'].includes(key))
&& Object.hasOwn(RULES, value.code) && value.message === RULES[value.code]
&& typeof value.path === 'string' && value.path.length > 0 && value.path.length <= 4096 && !value.path.includes('\0')
&& (!Object.hasOwn(value, 'line') || Number.isSafeInteger(value.line) && value.line > 0);
}
async function readStateHeld(mirror, { branch } = {}) {
if (typeof branch !== 'string' || !branch) fail('library-state-invalid', 'configured branch required');
const served = await servedCommit(mirror);
let fd, value;
try {
try { fd = openSync(join(mirror, SYNC_STATE_FILE), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
catch (error) {
if (error.code === 'ENOENT' && served === null) return empty(branch);
fail('library-state-invalid', 'sync state missing or unsafe');
}
const st = fstatSync(fd);
if (!privateFile(st) || st.size > STATE_MAX) fail('library-state-invalid', 'sync state must be bounded and private');
const bytes = Buffer.alloc(Math.min(st.size + 1, STATE_MAX + 1));
let used = 0;
while (used < bytes.length) { const read = readSync(fd, bytes, used, bytes.length - used, null); if (!read) break; used += read; }
if (used > STATE_MAX || used > st.size) fail('library-state-invalid', 'state changed during bounded read');
value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, used)));
} catch { fail('library-state-invalid', 'invalid sync state'); }
finally { if (fd !== undefined) closeSync(fd); }
// C2-03b adds `credential`, { kind, user } or null. It is optional, so a state from before it reads.
const listed = ['version', 'branch', 'served', 'lastFetch', 'lastError', 'diverged', 'problems'];
if (!keys(value, Object.hasOwn(value ?? {}, 'credential') ? [...listed, 'credential'] : listed)
|| !optional(value.credential ?? null, v => keys(v, ['kind', 'user']) && ['slot', 'chief', 'seat', 'human'].includes(v.kind)
&& typeof v.user === 'string' && /^[A-Za-z0-9_.-]{1,100}$/.test(v.user))
|| value.version !== 1 || value.branch !== branch || value.served !== served
|| !optional(value.served, v => typeof v === 'string' && SHA.test(v)) || !optional(value.lastFetch, utc)
|| !optional(value.lastError, v => keys(v, ['code', 'at']) && typeof v.code === 'string' && /^[a-z-]{1,64}$/.test(v.code) && utc(v.at))
|| !optional(value.diverged, v => keys(v, ['commit', 'at']) && typeof v.commit === 'string' && SHA.test(v.commit) && utc(v.at))
|| !Array.isArray(value.problems) || !value.problems.every(validProblem))
fail('library-state-invalid', 'sync state does not match its contract or served ref');
return value;
}
export async function readSyncState(mirror, options) {
return withLibraryLock(mirror, lock => lock.readSyncState(options));
}
export async function libraryStatus(context) {
const mapping = contextEntry(context), mirror = mirrorPath(context);
return { project: context.project, ...await readSyncState(mirror, { branch: mapping.branch }) };
}
export async function readLibraryFile(context) {
if (!object(context) || Object.keys(context).some(key => !['business', 'project', 'dataRoot', 'path'].includes(key)))
fail('project-read-path', 'unknown library read arguments');
const mapping = contextEntry(context), path = context.path;
if (typeof path !== 'string' || !path || isAbsolute(path) || path.includes('\0') || path.split('/').some(p => !p || p === '.' || p === '..')
|| classify(mapping, path).scope === 'unmapped') fail('project-read-path', 'expected a mapped library note');
const mirror = mirrorPath(context);
// Snapshot under the publication lock, then read only immutable objects.
const state = await readSyncState(mirror, { branch: mapping.branch });
if (!state.served) fail('library-commit', 'library has never been synced');
const read = await readLibrary({ repo: mirror, commit: state.served, mapping });
if (!read.files.some(file => file.path === path)) fail('project-read-missing', 'file is absent or excluded at served commit');
const entry = (await listTree(mirror, state.served)).find(entry => entry.path === path);
const texts = await readTexts(mirror, [entry]);
if (!texts.has(path)) fail('project-read-missing', 'file is not readable');
return { project: context.project, path, commit: state.served, content: texts.get(path) };
}