fix(go): harden route config lifecycle

Refs #3750
This commit is contained in:
Gergo Magyar 2026-11-01 17:37:20 +00:00
parent 13076b73c3
commit 6beba7aee7
9 changed files with 196 additions and 64 deletions

View file

@ -7,7 +7,8 @@
* (e.g. an earlier commit of this feature), not a build from before it.
*
* Parsing and module startup are excluded. Nine batches alternate build order;
* serialized bytes measure the worker payload, not heap or whole-index memory.
* serialized bytes measure the collected direct routes and facts, excluding
* worker-envelope metadata, heap usage and whole-index memory.
*/
import assert from 'node:assert/strict';
import path from 'node:path';

View file

@ -405,6 +405,8 @@ const FILESYSTEM = [
'test/integration/filesystem-walker.test.ts',
'test/integration/analyze-directory-symlinks.test.ts',
'test/integration/watch-filesystem.test.ts',
'test/unit/watch-external-config.test.ts',
'test/integration/server-route-hook-config.test.ts',
'test/integration/markdown-processor-crlf.test.ts',
'test/integration/ignore-and-skip-e2e.test.ts',
// Pins that the bridge pairing verdict is measured before the database is

View file

@ -1,6 +1,7 @@
/** Local incremental watch (`gitnexus analyze --watch`). Remote auto-sync lives in `auto-sync.ts`. */
import path from 'node:path';
import fs from 'node:fs/promises';
import { watchFile, unwatchFile } from 'node:fs';
import { watch, type FSWatcher } from 'chokidar';
import { createWatchIgnorePredicate } from '../config/ignore-service.js';
import {
@ -381,33 +382,15 @@ export async function startWatchFileLoop(
let watcher: FSWatcher = createWatcher();
// The external config file is outside the repository watcher. Watch its
// directory, not the file: an editor's atomic save replaces the inode, and
// a watch on the file itself would go quiet after the first replacement.
const createExternalConfigWatcher = (configPath: string): FSWatcher => {
const directory = path.dirname(configPath);
const created: FSWatcher = watch(directory, {
ignoreInitial: true,
atomic: true,
depth: 0,
followSymlinks: false,
awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 20 },
ignored: (candidate) =>
path.resolve(candidate) !== directory && path.resolve(candidate) !== configPath,
});
created.on('all', (event, changedPath) => {
if (event !== 'add' && event !== 'change' && event !== 'unlink') return;
if (path.resolve(changedPath) !== configPath) return;
logger.debug({ event, file: configPath }, 'watch: GITNEXUS_RC changed; reloading config');
queue.enqueue(EXTERNAL_CONFIG_WATCH_PATH);
});
created.on('error', (error) => onWatcherError(error));
return created;
// Poll this one explicit path: stat follows symlinks, and continues observing
// the path after atomic saves, target deletion/restoration or link retargeting.
// Watching only the link's directory misses writes in the target directory.
const configPath =
externalConfigPath === undefined ? undefined : path.resolve(externalConfigPath);
const configChanged = () => {
logger.debug({ file: configPath }, 'watch: GITNEXUS_RC changed; reloading config');
queue.enqueue(EXTERNAL_CONFIG_WATCH_PATH);
};
const externalConfigWatcher =
externalConfigPath === undefined
? undefined
: createExternalConfigWatcher(path.resolve(externalConfigPath));
// Chokidar emits `ready` once per instance and `add()` returns before the
// rescan it starts has finished, with no signal for that completion. A file
@ -443,13 +426,13 @@ export async function startWatchFileLoop(
};
try {
if (configPath) watchFile(configPath, { interval: 100 }, configChanged);
await waitUntilReady(watcher);
if (externalConfigWatcher) await waitUntilReady(externalConfigWatcher);
await queue.runInitial();
} catch (error) {
closed = true;
await watcher.close();
await externalConfigWatcher?.close();
if (configPath) unwatchFile(configPath, configChanged);
await queue.close();
throw error;
}
@ -459,7 +442,7 @@ export async function startWatchFileLoop(
close: async () => {
closed = true;
await watcher.close();
await externalConfigWatcher?.close();
if (configPath) unwatchFile(configPath, configChanged);
await queue.close();
},
};
@ -543,7 +526,9 @@ export async function watchCommandWithRunnerIdentity(
repoPath,
debounceMs,
async (paths) => {
if (paths.some(isConfigControlPath) || !configControlValid) {
// Initial validation precedes watcher setup. Read again after it is
// armed so a change during startup cannot leave stale options live.
if (paths.length === 0 || paths.some(isConfigControlPath) || !configControlValid) {
const retryingInvalidConfig = !configControlValid;
try {
analyzeOptions = await resolveWatchOptions(

View file

@ -11,6 +11,11 @@ export function normalizeRouterAliases(value: unknown, source: string): RouteFra
if (!Array.isArray(value) || value.length === 0) {
throw new Error(`${source} must be a non-empty array of alias objects.`);
}
if (value.length > MAX_ROUTER_ALIASES) {
throw new Error(
`${source} declares ${value.length} aliases; at most ${MAX_ROUTER_ALIASES} are allowed.`,
);
}
const out = new Map<string, RouteFrameworkAlias>();
for (const entry of value) {
if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
@ -50,10 +55,5 @@ export function normalizeRouterAliases(value: unknown, source: string): RouteFra
}
out.set(key, { importPath, type, framework });
}
if (out.size > MAX_ROUTER_ALIASES) {
throw new Error(
`${source} declares ${out.size} aliases; at most ${MAX_ROUTER_ALIASES} are allowed.`,
);
}
return [...out.values()];
}

View file

@ -6,17 +6,19 @@
* omission as "configuration removed" and drop alias Routes and wrapped
* HANDLES_ROUTE edges, even with the same `GITNEXUS_RC` in the environment.
*
* Drives CLI-style indexing, then the server path: options resolved by
* `resolveLaunchRouteHookConfig` (what the launch forwards) and run through
* `runWorkerAnalysis` (what the forked worker runs).
* Drives CLI-style indexing, then the real server launcher and its forked
* worker, so omitting configuration from the start message loses evidence.
*/
import fs from 'node:fs/promises';
import path from 'node:path';
import { once } from 'node:events';
import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
import { runFullAnalysis } from '../../src/core/run-analyze.js';
import { resolveLaunchRouteHookConfig } from '../../src/server/analyze-launch.js';
import { runWorkerAnalysis } from '../../src/server/analyze-worker-core.js';
import type { WorkerMessage } from '../../src/server/analyze-worker-protocol.js';
import {
createLaunchAnalysisWorker,
resolveLaunchRouteHookConfig,
} from '../../src/server/analyze-launch.js';
import { JobManager } from '../../src/server/analyze-job.js';
import { getStoragePaths } from '../../src/storage/repo-manager.js';
import { commitAll, initGitRepo } from '../helpers/temp-git-repo.js';
import { createTempDir } from '../helpers/test-db.js';
@ -80,7 +82,7 @@ describe('server reindex with route aliases from GITNEXUS_RC', () => {
await temp.cleanup();
});
it('keeps alias Routes and wrapped handler edges across an HTTP reindex', async () => {
it('keeps alias Routes and wrapped handler edges across a server-launched reindex', async () => {
const routeHookConfig = resolveLaunchRouteHookConfig(repo);
await runFullAnalysis(
repo,
@ -89,26 +91,38 @@ describe('server reindex with route aliases from GITNEXUS_RC', () => {
);
expect(await routeEvidence(repo)).toEqual({ routes: 3, handled: 2 });
const send = vi.fn<(message: WorkerMessage) => void>();
await runWorkerAnalysis(
repo,
// Exactly what `createLaunchAnalysisWorker` sends for a forced reindex.
{ force: true, embeddings: false, dropEmbeddings: false, routeHookConfig },
{
runFullAnalysis: (repoPath, options, callbacks, ...rest) =>
runFullAnalysis(
repoPath,
{ ...options, skipNativeCloseOnExit: false },
callbacks,
...rest,
),
assertAnalysisFinalized: async () => undefined,
send,
claimTerminal: () => true,
},
);
expect(send).toHaveBeenCalledWith(expect.objectContaining({ type: 'complete' }));
const jobManager = new JobManager();
const childExits: Promise<unknown>[] = [];
const registerChild = jobManager.registerChild.bind(jobManager);
vi.spyOn(jobManager, 'registerChild').mockImplementation((id, child) => {
childExits.push(once(child, 'exit'));
registerChild(id, child);
});
const releaseRepoLock = vi.fn();
const backendInit = vi.fn(async () => undefined);
const launch = createLaunchAnalysisWorker({
jobManager,
backend: { init: backendInit },
acquireRepoLock: () => null,
releaseRepoLock,
closeDbHandle: async () => (await import('../../src/core/lbug/lbug-adapter.js')).closeLbug(),
});
const job = jobManager.createJob({ repoPath: repo });
try {
await launch(job, repo, { force: true });
await vi.waitFor(
() => expect(['complete', 'failed']).toContain(jobManager.getJob(job.id)?.status),
{ timeout: 180_000, interval: 100 },
);
// The completion IPC precedes process exit, which releases the worker's
// native database handle. Only then can this process reopen the graph.
await Promise.all(childExits);
expect(jobManager.getJob(job.id)?.status).toBe('complete');
expect(backendInit).toHaveBeenCalledOnce();
expect(releaseRepoLock).toHaveBeenCalledOnce();
} finally {
jobManager.dispose();
}
expect(await routeEvidence(repo)).toEqual({ routes: 3, handled: 2 });
}, 300_000);

View file

@ -339,6 +339,8 @@ describe('analyze-config (.gitnexusrc support, #243)', () => {
JSON.stringify({ goRouterAliases: Array.from({ length: 101 }, (_, i) => alias(i)) }),
);
expect(() => loadAnalyzeConfig(dir)).toThrow(/declares 101 aliases; at most 100/);
await writeRc(JSON.stringify({ goRouterAliases: Array.from({ length: 101 }, () => alias(0)) }));
expect(() => loadAnalyzeConfig(dir)).toThrow(/declares 101 aliases; at most 100/);
});
describe('GITNEXUS_RC out-of-repo config', () => {

View file

@ -260,6 +260,30 @@ describe('createLaunchAnalysisWorker — collapsed index is never published', ()
expect(job?.error).toMatch(/Could not read GITNEXUS_RC file/);
expect(calls).toContain('releaseRepoLock');
});
it('preserves cancellation during storage resolution when config is invalid', async () => {
vi.stubEnv('GITNEXUS_RC', `${rcDir}/missing.json`);
const launch = createLaunchAnalysisWorker({
jobManager,
backend: { init: backendInit },
acquireRepoLock: () => null,
releaseRepoLock: () => calls.push('releaseRepoLock'),
closeDbHandle,
});
const queued = jobManager.createJob({ repoPath: REPO_PATH });
H.requireStoragePath.mockImplementationOnce(async () => {
jobManager.cancelJob(queued.id, 'Cancelled during storage resolution');
return H.STORAGE_PATH;
});
await launch(queued, REPO_PATH, {});
const job = jobManager.getJob(queued.id);
expect(job?.error).toBe('Cancelled during storage resolution');
expect(jobManager.hasPendingCancel(queued.id)).toBe(false);
expect(forkMock).not.toHaveBeenCalled();
expect(calls.filter((call) => call === 'releaseRepoLock')).toHaveLength(1);
});
});
it('uses the force storage set only when launch options request force', async () => {

View file

@ -13,7 +13,24 @@ import os from 'node:os';
import path from 'node:path';
import { afterEach, describe, expect, it, vi } from 'vitest';
const H = vi.hoisted(() => ({ calls: [] as unknown[] }));
const H = vi.hoisted(() => ({
calls: [] as unknown[],
afterConfigLoad: undefined as (() => Promise<void>) | undefined,
}));
vi.mock('../../src/cli/analyze-config.js', async (importActual) => {
const actual = await importActual<typeof import('../../src/cli/analyze-config.js')>();
return {
...actual,
loadAnalyzeConfigStrict: async (repo: string) => {
const options = await actual.loadAnalyzeConfigStrict(repo);
const afterLoad = H.afterConfigLoad;
H.afterConfigLoad = undefined;
await afterLoad?.();
return options;
},
};
});
vi.mock('../../src/core/run-analyze.js', () => ({
analyzeFailureMayHaveMutatedLiveIndex: () => false,
@ -35,6 +52,7 @@ const dirs: string[] = [];
afterEach(async () => {
vi.unstubAllEnvs();
H.calls.length = 0;
H.afterConfigLoad = undefined;
await Promise.all(dirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
});
@ -51,6 +69,90 @@ const aliases = (importPath: string) => ({
});
describe('watch mode with an external GITNEXUS_RC file', () => {
it('rereads configuration changed between validation and watcher startup', async () => {
const repo = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-watch-rc-start-'));
const outside = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-watch-rc-'));
dirs.push(repo, outside);
execFileSync('git', ['init', '-q'], { cwd: repo });
const rc = path.join(outside, 'service.json');
await fs.writeFile(rc, JSON.stringify(aliases('example.com/old')));
vi.stubEnv('GITNEXUS_RC', rc);
H.afterConfigLoad = () => fs.writeFile(rc, JSON.stringify(aliases('example.com/new')));
const command = watchCommandWithRunnerIdentity({} as AnalyzerRunnerIdentity, repo, {
debounce: '25',
});
try {
await waitFor(() => H.calls.length > 0);
expect(H.calls[0]).toEqual({
routeFrameworkAliases: aliases('example.com/new').goRouterAliases,
routeHandlerWrappers: undefined,
});
} finally {
process.emit('SIGINT');
await command;
}
});
it('reloads symlink targets after edits, replacement, removal, restoration and retargeting', async ({
skip,
}) => {
const repo = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-watch-rc-link-'));
const outside = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-watch-rc-'));
dirs.push(repo, outside);
execFileSync('git', ['init', '-q'], { cwd: repo });
await fs.mkdir(path.join(outside, 'targets'));
const target = path.join(outside, 'targets', 'service.json');
const rc = path.join(outside, 'config.json');
await fs.writeFile(target, JSON.stringify(aliases('example.com/one')));
try {
await fs.symlink(target, rc, 'file');
} catch (error) {
if (process.platform === 'win32' && (error as NodeJS.ErrnoException).code === 'EPERM') {
skip('Creating file symlinks requires Windows Developer Mode or elevation.');
}
throw error;
}
vi.stubEnv('GITNEXUS_RC', rc);
const command = watchCommandWithRunnerIdentity({} as AnalyzerRunnerIdentity, repo, {
debounce: '25',
});
const latestConfig = () => H.calls.at(-1);
const config = (name: string) => ({
routeFrameworkAliases: aliases(`example.com/${name}`).goRouterAliases,
routeHandlerWrappers: undefined,
});
try {
await waitFor(() => H.calls.length > 0);
expect(latestConfig()).toEqual(config('one'));
await fs.writeFile(target, JSON.stringify(aliases('example.com/two')));
await vi.waitFor(() => expect(latestConfig()).toEqual(config('two')), { timeout: 8_000 });
await fs.writeFile(`${target}.tmp`, JSON.stringify(aliases('example.com/three')));
await fs.rename(`${target}.tmp`, target);
await vi.waitFor(() => expect(latestConfig()).toEqual(config('three')), { timeout: 8_000 });
await fs.rm(target);
await new Promise((resolve) => setTimeout(resolve, 600));
const settled = H.calls.length;
await fs.writeFile(path.join(repo, 'main.go'), 'package main\n');
await new Promise((resolve) => setTimeout(resolve, 600));
expect(H.calls).toHaveLength(settled);
await fs.writeFile(target, JSON.stringify(aliases('example.com/four')));
await vi.waitFor(() => expect(latestConfig()).toEqual(config('four')), { timeout: 8_000 });
const nextTarget = path.join(outside, 'targets', 'next.json');
await fs.writeFile(nextTarget, JSON.stringify(aliases('example.com/five')));
await fs.rm(rc);
await fs.symlink(nextTarget, rc, 'file');
await vi.waitFor(() => expect(latestConfig()).toEqual(config('five')), { timeout: 8_000 });
await fs.writeFile(nextTarget, JSON.stringify(aliases('example.com/six')));
await vi.waitFor(() => expect(latestConfig()).toEqual(config('six')), { timeout: 8_000 });
} finally {
process.emit('SIGINT');
await command;
}
}, 45_000);
it('reloads edits and replacements, and blocks refreshes while the file is invalid or gone', async () => {
const repo = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-watch-rc-repo-'));
const outside = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-watch-rc-'));

View file

@ -85,6 +85,7 @@ export default defineConfig({
'test/integration/incremental-worktree-context.test.ts',
'test/integration/incremental-method-integrity.test.ts',
'test/integration/go-incremental-method-owners.test.ts',
'test/integration/server-route-hook-config.test.ts',
'test/integration/query-symbol-integrity.test.ts',
'test/integration/mcp-index-generation.test.ts',
'test/integration/mcp-refresh-index-e2e.test.ts',
@ -201,6 +202,7 @@ export default defineConfig({
'test/integration/incremental-worktree-context.test.ts',
'test/integration/incremental-method-integrity.test.ts',
'test/integration/go-incremental-method-owners.test.ts',
'test/integration/server-route-hook-config.test.ts',
'test/integration/query-symbol-integrity.test.ts',
'test/integration/mcp-index-generation.test.ts',
'test/integration/mcp-refresh-index-e2e.test.ts',