~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
/**
* Runtime contracts for Socket.IO's FastAPI polling fallback ownership.
*
* These use the service's real fallback interval rather than injecting the
* page-level pollResearchStatus helper. That exercises the terminal cleanup
* and the late-response guard added for the migration's reconnect paths.
*/
function deferred() {
let resolve;
const promise = new Promise(res => {
resolve = res;
});
return { promise, resolve };
}
function createMockSocket() {
const handlers = {};
return {
connected: false,
emit: vi.fn(),
on: vi.fn((event, callback) => {
handlers[event] ||= [];
handlers[event].push(callback);
}),
off: vi.fn(),
disconnect: vi.fn(),
fire(event, ...args) {
(handlers[event] || []).forEach(callback => callback(...args));
},
};
}
async function loadSocketService(getResearchStatus) {
vi.resetModules();
Object.defineProperty(window, 'location', {
configurable: true,
value: {
pathname: '/progress/polling-contract',
protocol: 'http:',
host: 'localhost',
},
});
const socket = createMockSocket();
globalThis.io = vi.fn(() => socket);
window.api = {
getResearchStatus,
getCsrfToken: () => '',
};
window.ResearchStates = {
isTerminal: status => ['completed', 'failed', 'cancelled'].includes(status),
logLevel: () => 'info',
};
delete window.pollResearchStatus;
window.pollIntervals = {};
await import('@js/services/socket.js');
await vi.advanceTimersByTimeAsync(300);
expect(globalThis.io).toHaveBeenCalledOnce();
return { service: window.socket, socket };
}
function failSocketIntoPolling(service, socket, researchId) {
service.subscribeToResearch(researchId, () => {});
socket.fire('connect_error', new Error('attempt 1'));
socket.fire('connect_error', new Error('attempt 2'));
socket.fire('connect_error', new Error('attempt 3'));
}
describe('socket polling fallback terminal ownership', () => {
let service;
beforeEach(() => {
vi.useFakeTimers();
});
afterEach(() => {
service?.disconnect();
vi.useRealTimers();
delete globalThis.io;
delete window.pollResearchStatus;
delete window.pollIntervals;
delete window.ResearchStates;
service = undefined;
});
it('does not let a late terminal response release the newer research poll', async () => {
const oldResponse = deferred();
const getResearchStatus = vi.fn(researchId => {
if (researchId === 'research-old') return oldResponse.promise;
return new Promise(() => {});
});
const loaded = await loadSocketService(getResearchStatus);
service = loaded.service;
failSocketIntoPolling(service, loaded.socket, 'research-old');
vi.advanceTimersByTime(3000);
await Promise.resolve();
expect(getResearchStatus).toHaveBeenCalledWith('research-old');
service.unsubscribeFromResearch('research-old');
service.subscribeToResearch('research-current', () => {});
const currentInterval = window.pollIntervals['research-current'];
expect(currentInterval).toBeDefined();
oldResponse.resolve({ status: 'completed', progress: 100 });
await Promise.resolve();
await Promise.resolve();
// A later transport signal asks for fallback again. If the stale A
// response incorrectly released B's private polling ownership, this
// would allocate a second interval and overwrite the registry entry.
loaded.socket.fire('disconnect', 'late transport close');
expect(window.pollIntervals['research-current']).toBe(currentInterval);
expect(service.isUsingPolling()).toBe(true);
});
it('keeps the current fallback alive when an older room cleans up late', async () => {
const currentCallback = vi.fn();
const getResearchStatus = vi.fn(researchId => {
if (researchId === 'research-current') {
return Promise.resolve({ status: 'completed', progress: 100 });
}
return new Promise(() => {});
});
const loaded = await loadSocketService(getResearchStatus);
service = loaded.service;
failSocketIntoPolling(service, loaded.socket, 'research-old');
service.subscribeToResearch('research-current', currentCallback);
expect(window.pollIntervals['research-old']).toBeDefined();
expect(window.pollIntervals['research-current']).toBeDefined();
// Page cleanup for A may arrive after B already owns the service. It
// must retire only A's fallback generation, not B's.
service.unsubscribeFromResearch('research-old');
await vi.advanceTimersByTimeAsync(3000);
expect(getResearchStatus).toHaveBeenCalledWith('research-current');
expect(currentCallback).toHaveBeenCalledOnce();
expect(currentCallback).toHaveBeenCalledWith({
status: 'completed',
progress: 100,
});
expect(window.pollIntervals['research-current']).toBeUndefined();
});
it('keeps a fallback started synchronously by a terminal callback alive', async () => {
const currentCallback = vi.fn();
const getResearchStatus = vi.fn(researchId => Promise.resolve(
researchId === 'research-old'
? { status: 'completed', progress: 100 }
: { status: 'in_progress', progress: 40 },
));
const loaded = await loadSocketService(getResearchStatus);
service = loaded.service;
service.subscribeToResearch('research-old', () => {
service.unsubscribeFromResearch('research-old');
service.subscribeToResearch('research-current', currentCallback);
});
loaded.socket.fire('connect_error', new Error('attempt 1'));
loaded.socket.fire('connect_error', new Error('attempt 2'));
loaded.socket.fire('connect_error', new Error('attempt 3'));
await vi.advanceTimersByTimeAsync(3000);
expect(window.pollIntervals['research-current']).toBeDefined();
await vi.advanceTimersByTimeAsync(3000);
expect(getResearchStatus).toHaveBeenCalledWith('research-current');
expect(currentCallback).toHaveBeenCalledOnce();
expect(currentCallback).toHaveBeenCalledWith({
status: 'in_progress',
progress: 40,
});
expect(window.pollIntervals['research-current']).toBeDefined();
});
it('polls a later subscription when the transport failed before a room was known', async () => {
const getResearchStatus = vi.fn(() => new Promise(() => {}));
const loaded = await loadSocketService(getResearchStatus);
service = loaded.service;
// Eager connection attempts can be exhausted before a page component
// discovers its research id. That state must arm, rather than lose,
// the first subsequent subscription's HTTP fallback.
loaded.socket.fire('connect_error', new Error('attempt 1'));
loaded.socket.fire('connect_error', new Error('attempt 2'));
loaded.socket.fire('connect_error', new Error('attempt 3'));
expect(service.isUsingPolling()).toBe(true);
expect(window.pollIntervals).toEqual({});
service.subscribeToResearch('research-discovered-late', () => {});
expect(window.pollIntervals['research-discovered-late']).toBeDefined();
await vi.advanceTimersByTimeAsync(3000);
expect(getResearchStatus).toHaveBeenCalledOnce();
expect(getResearchStatus).toHaveBeenCalledWith(
'research-discovered-late',
);
});
it.each([false, true])('polls a late subscription after an established connection drops (page owner: %s)', async pageOwned => {
const getResearchStatus = vi.fn(() => new Promise(() => {}));
const loaded = await loadSocketService(getResearchStatus);
service = loaded.service;
// The eager transport can connect and disconnect before the page has
// discovered its research id or registered its own polling callback.
loaded.socket.connected = true;
loaded.socket.fire('connect');
loaded.socket.connected = false;
loaded.socket.fire('disconnect', 'transport close');
expect(window.pollIntervals).toEqual({});
const pagePolling = vi.fn();
if (pageOwned) service.setPollingFallback(pagePolling);
service.subscribeToResearch('research-discovered-late', () => {});
await vi.advanceTimersByTimeAsync(3000);
if (pageOwned) {
expect(pagePolling).toHaveBeenCalledExactlyOnceWith('research-discovered-late');
expect(getResearchStatus).not.toHaveBeenCalled();
} else {
expect(getResearchStatus).toHaveBeenCalledExactlyOnceWith('research-discovered-late');
}
});
it('uses the restored socket when it reconnects before the late subscription', async () => {
const getResearchStatus = vi.fn();
const loaded = await loadSocketService(getResearchStatus);
service = loaded.service;
loaded.socket.connected = true;
loaded.socket.fire('connect');
loaded.socket.connected = false;
loaded.socket.fire('disconnect', 'transport close');
loaded.socket.connected = true;
loaded.socket.fire('connect');
service.subscribeToResearch('research-after-reconnect', () => {});
await vi.advanceTimersByTimeAsync(6000);
expect(loaded.socket.emit).toHaveBeenCalledWith('subscribe_to_research', {
research_id: 'research-after-reconnect',
});
expect(getResearchStatus).not.toHaveBeenCalled();
expect(service.isUsingPolling()).toBe(false);
});
it('retries after a fallback request rejects and retires on terminal status', async () => {
const callback = vi.fn();
const getResearchStatus = vi.fn()
.mockRejectedValueOnce(new Error('temporary status outage'))
.mockResolvedValueOnce({ status: 'completed', progress: 100 });
const loaded = await loadSocketService(getResearchStatus);
service = loaded.service;
vi.spyOn(console, 'error').mockImplementation(() => {});
service.subscribeToResearch('research-retry', callback);
loaded.socket.fire('connect_error', new Error('attempt 1'));
loaded.socket.fire('connect_error', new Error('attempt 2'));
loaded.socket.fire('connect_error', new Error('attempt 3'));
await vi.advanceTimersByTimeAsync(3000);
expect(getResearchStatus).toHaveBeenCalledOnce();
expect(callback).not.toHaveBeenCalled();
expect(window.pollIntervals['research-retry']).toBeDefined();
await vi.advanceTimersByTimeAsync(3000);
expect(getResearchStatus).toHaveBeenCalledTimes(2);
expect(callback).toHaveBeenCalledOnce();
expect(callback).toHaveBeenCalledWith({
status: 'completed',
progress: 100,
});
expect(window.pollIntervals).toEqual({});
expect(service.isUsingPolling()).toBe(true);
});
it('ignores an in-flight fallback response after websocket recovery', async () => {
const stalePoll = deferred();
const callback = vi.fn();
const getResearchStatus = vi.fn(() => stalePoll.promise);
const loaded = await loadSocketService(getResearchStatus);
service = loaded.service;
service.subscribeToResearch('research-reconnected', callback);
loaded.socket.fire('connect_error', new Error('attempt 1'));
loaded.socket.fire('connect_error', new Error('attempt 2'));
loaded.socket.fire('connect_error', new Error('attempt 3'));
vi.advanceTimersByTime(3000);
await Promise.resolve();
expect(getResearchStatus).toHaveBeenCalledOnce();
loaded.socket.connected = true;
loaded.socket.fire('connect');
loaded.socket.fire('research_progress_research-reconnected', {
status: 'in_progress',
progress: 80,
});
expect(callback).toHaveBeenCalledOnce();
expect(callback).toHaveBeenLastCalledWith({
status: 'in_progress',
progress: 80,
});
stalePoll.resolve({ status: 'in_progress', progress: 20 });
await Promise.resolve();
await Promise.resolve();
expect(callback).toHaveBeenCalledOnce();
expect(window.pollIntervals).toEqual({});
expect(service.isUsingPolling()).toBe(false);
});
it('does not regress when fallback polls for one run resolve out of order', async () => {
const olderPoll = deferred();
const newerPoll = deferred();
const callback = vi.fn();
const getResearchStatus = vi.fn()
.mockImplementationOnce(() => olderPoll.promise)
.mockImplementationOnce(() => newerPoll.promise)
.mockImplementation(() => new Promise(() => {}));
const loaded = await loadSocketService(getResearchStatus);
service = loaded.service;
service.subscribeToResearch('research-overlap', callback);
loaded.socket.fire('connect_error', new Error('attempt 1'));
loaded.socket.fire('connect_error', new Error('attempt 2'));
loaded.socket.fire('connect_error', new Error('attempt 3'));
vi.advanceTimersByTime(3000);
await Promise.resolve();
vi.advanceTimersByTime(3000);
await Promise.resolve();
expect(getResearchStatus).toHaveBeenCalledTimes(2);
newerPoll.resolve({ status: 'in_progress', progress: 70 });
await Promise.resolve();
await Promise.resolve();
expect(callback).toHaveBeenCalledOnce();
expect(callback).toHaveBeenLastCalledWith({
status: 'in_progress',
progress: 70,
});
olderPoll.resolve({ status: 'in_progress', progress: 20 });
await Promise.resolve();
await Promise.resolve();
expect(callback).toHaveBeenCalledOnce();
expect(callback).not.toHaveBeenCalledWith({
status: 'in_progress',
progress: 20,
});
});
it('applies an older-request terminal snapshot after a newer nonterminal poll', async () => {
const terminalPoll = deferred();
const newerPoll = deferred();
const callback = vi.fn();
const getResearchStatus = vi.fn()
.mockImplementationOnce(() => terminalPoll.promise)
.mockImplementationOnce(() => newerPoll.promise)
.mockImplementation(() => new Promise(() => {}));
const loaded = await loadSocketService(getResearchStatus);
service = loaded.service;
service.subscribeToResearch('research-terminal', callback);
loaded.socket.fire('connect_error', new Error('attempt 1'));
loaded.socket.fire('connect_error', new Error('attempt 2'));
loaded.socket.fire('connect_error', new Error('attempt 3'));
vi.advanceTimersByTime(3000);
await Promise.resolve();
vi.advanceTimersByTime(3000);
await Promise.resolve();
expect(getResearchStatus).toHaveBeenCalledTimes(2);
newerPoll.resolve({ status: 'in_progress', progress: 70 });
await Promise.resolve();
await Promise.resolve();
expect(callback).toHaveBeenCalledOnce();
expect(callback).toHaveBeenLastCalledWith({
status: 'in_progress',
progress: 70,
});
terminalPoll.resolve({ status: 'completed', progress: 100 });
await Promise.resolve();
await Promise.resolve();
expect(callback).toHaveBeenCalledTimes(2);
expect(callback).toHaveBeenLastCalledWith({
status: 'completed',
progress: 100,
});
expect(window.pollIntervals).toEqual({});
});
});