Skip to content

Build your personal knowledge base with Trilium Notes

fix(clipper): stop falling back to "searching" while connected (closes #1503)

Elian Doranb4786dbde23e
diff --git a/.claude/skills/developing-web-clipper/SKILL.md b/.claude/skills/developing-web-clipper/SKILL.md
index 894461ea86..c90bfb6966 100644
--- a/.claude/skills/developing-web-clipper/SKILL.md
+++ b/.claude/skills/developing-web-clipper/SKILL.md
@@ -52,8 +52,12 @@ pages or the extension stores, where no content script runs.
- **Desktop first.** `getPort()` returns the port from the options page, or **37840** (production)
/ **37743** (development build, the port `pnpm desktop:start` uses). It tries that one port — there is no port scan — with
- `GET http://127.0.0.1:<port>/api/clipper/handshake`, then falls back to the configured server.
- It repeats every 60 seconds, and on the popup's **check** button.
+ `GET http://127.0.0.1:<port>/api/clipper/handshake` and asks the configured server at the same
+ time, with timeouts of 2 s and 10 s; the desktop app wins when both answer. It repeats every
+ 60 seconds in the background, keeping the last status, and only the popup's **check** button
+ shows "searching". The last status is kept in `browser.storage.session`, so an MV3 service
+ worker that Chrome restarted does not start from "searching"; `callService()` waits for the
+ latest search, and an older search that ends later is discarded (`searchCount`).
- **Version check.** The handshake returns `protocolVersion` (`CLIPPER_PROTOCOL_VERSION` in
`packages/trilium-core/src/services/app_info.ts`); the extension compares the major version and
reports `version-mismatch`.
diff --git a/apps/web-clipper/entrypoints/background/trilium_server_facade.spec.ts b/apps/web-clipper/entrypoints/background/trilium_server_facade.spec.ts
index 16091faa47..079fc65a08 100644
--- a/apps/web-clipper/entrypoints/background/trilium_server_facade.spec.ts
+++ b/apps/web-clipper/entrypoints/background/trilium_server_facade.spec.ts
@@ -6,6 +6,9 @@ import TriliumServerFacade, { TriliumError } from "./trilium_server_facade";
const fetchMock = vi.fn<(url: string, init?: RequestInit) => Promise<Response>>();
const SERVER = { triliumServerUrl: "https://trilium.example", authToken: "secret" };
const LOCAL_DATE_TIME = /^\d{4}-\d\d-\d\d \d\d:\d\d:\d\d\.\d{3}[+-]\d\d:\d\d$/;
+const DESKTOP_HANDSHAKE = "http://127.0.0.1:37743/api/clipper/handshake";
+const FOUND_DESKTOP = { status: "found-desktop", port: 37743, url: "http://127.0.0.1:37743" };
+const FOUND_SERVER = { status: "found-server", url: "https://trilium.example", token: "secret" };
type PopupMessage = { name: string, triliumSearch?: unknown, searchNote?: unknown };
const sendMessage = vi.fn(async (_message: PopupMessage) => {});
@@ -31,41 +34,53 @@ describe("TriliumServerFacade", () => {
});
describe("search for Trilium", () => {
- it("finds the desktop app on the default port and reports it to the popup", async () => {
- fetchMock.mockResolvedValue(handshake("1.0"));
+ it("finds the desktop app on the default port without showing a search in progress", async () => {
+ fetchMock.mockImplementation(async () => handshake("1.0"));
await createFacade();
- expect(fetchMock).toHaveBeenCalledWith("http://127.0.0.1:37743/api/clipper/handshake");
- expect(searchStatuses()).toEqual([
- { status: "searching" },
- { status: "found-desktop", port: 37743, url: "http://127.0.0.1:37743" }
- ]);
+ expect(fetchMock).toHaveBeenCalledWith(DESKTOP_HANDSHAKE, handshakeInit());
+ expect(searchStatuses()).toEqual([ FOUND_DESKTOP ]);
});
it("looks for a production desktop app on its own port", async () => {
vi.stubEnv("DEV", false);
- fetchMock.mockResolvedValue(handshake("1.0"));
+ fetchMock.mockImplementation(async () => handshake("1.0"));
await createFacade();
- expect(fetchMock).toHaveBeenCalledWith("http://127.0.0.1:37840/api/clipper/handshake");
+ expect(fetchMock).toHaveBeenCalledWith(
+ "http://127.0.0.1:37840/api/clipper/handshake", handshakeInit());
});
- it("uses the configured desktop port and searches again every minute", async () => {
+ it("uses the configured desktop port and checks again every minute in the background", async () => {
await fakeBrowser.storage.sync.set({ triliumDesktopPort: "12345" });
- fetchMock.mockResolvedValue(handshake("1.2"));
+ fetchMock.mockImplementation(async () => handshake("1.2"));
await createFacade();
- expect(fetchMock)
- .toHaveBeenLastCalledWith("http://127.0.0.1:12345/api/clipper/handshake");
+ expect(fetchMock).toHaveBeenLastCalledWith(
+ "http://127.0.0.1:12345/api/clipper/handshake", handshakeInit());
+ sendMessage.mockClear();
await vi.advanceTimersByTimeAsync(60 * 1000);
expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(searchStatuses()).toEqual([
+ { status: "found-desktop", port: 12345, url: "http://127.0.0.1:12345" }
+ ]);
+ });
+
+ it("shows a search in progress when the popup asks for one", async () => {
+ fetchMock.mockImplementation(async () => handshake("1.0"));
+ const facade = await createFacade();
+ sendMessage.mockClear();
+
+ await facade.triggerSearchForTrilium();
+
+ expect(searchStatuses()).toEqual([ { status: "searching" }, FOUND_DESKTOP ]);
});
it("reports a protocol version mismatch", async () => {
- fetchMock.mockResolvedValue(handshake("2.0"));
+ fetchMock.mockImplementation(async () => handshake("2.0"));
await createFacade();
@@ -76,23 +91,35 @@ describe("TriliumServerFacade", () => {
});
});
- it("falls back to the configured server with its token", async () => {
+ it("asks the server while the desktop app has not answered, and falls back to it", async () => {
await fakeBrowser.storage.sync.set(SERVER);
- fetchMock.mockImplementation(async (url) => {
- if (url.startsWith("http://127.0.0.1")) throw new Error("connection refused");
- return handshake("1.0");
- });
+ let refuseDesktop: (error: Error) => void = () => {};
+ fetchMock.mockImplementation((url) => url === DESKTOP_HANDSHAKE
+ ? new Promise((_resolve, reject) => refuseDesktop = reject)
+ : Promise.resolve(handshake("1.0")));
+ const timeout = vi.spyOn(AbortSignal, "timeout");
+
+ const facade = new TriliumServerFacade();
+ await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
+ expect(fetchMock).toHaveBeenCalledWith(
+ "https://trilium.example/api/clipper/handshake",
+ handshakeInit({ Authorization: "secret" }));
+ expect(timeout.mock.calls).toEqual([ [ 10000 ], [ 2000 ] ]);
+ expect(sendMessage).not.toHaveBeenCalled();
+
+ refuseDesktop(new DOMException("The operation timed out.", "TimeoutError"));
+ await expect(facade.waitForTriliumSearch()).resolves.toEqual(FOUND_SERVER);
+ expect(lastSearchStatus()).toEqual(FOUND_SERVER);
+ });
+
+ it("prefers the desktop app when the server answers too", async () => {
+ await fakeBrowser.storage.sync.set(SERVER);
+ fetchMock.mockImplementation(async () => handshake("1.0"));
await createFacade();
- expect(fetchMock).toHaveBeenLastCalledWith(
- "https://trilium.example/api/clipper/handshake",
- { headers: { Authorization: "secret" } });
- expect(lastSearchStatus()).toEqual({
- status: "found-server",
- url: "https://trilium.example",
- token: "secret"
- });
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(lastSearchStatus()).toEqual(FOUND_DESKTOP);
});
it("reports not-found when neither the desktop app nor the server is Trilium", async () => {
@@ -100,19 +127,17 @@ describe("TriliumServerFacade", () => {
fetchMock.mockImplementation(async () => Response.json({ appName: "other" }));
await createFacade();
expect(lastSearchStatus()).toEqual({ status: "not-found" });
- expect(fetchMock).toHaveBeenLastCalledWith(
- "https://trilium.example/api/clipper/handshake", { headers: { Authorization: "secret" } });
- expect(console.log).not.toHaveBeenCalledWith(
- "Request to the configured server instance failed with:", expect.anything());
+ expect(fetchMock).toHaveBeenCalledTimes(2);
fetchMock.mockReset();
fetchMock.mockImplementation(async (url) => {
- if (url.startsWith("http://127.0.0.1")) return new Response("not json");
+ if (url === DESKTOP_HANDSHAKE) return new Response("not json");
throw new Error("server down");
});
await createFacade();
expect(lastSearchStatus()).toEqual({ status: "not-found" });
- expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(console.log).toHaveBeenCalledWith(
+ "Handshake with https://trilium.example failed with:", new Error("server down"));
});
it("skips the server when no URL or token is configured", async () => {
@@ -125,11 +150,52 @@ describe("TriliumServerFacade", () => {
expect(lastSearchStatus()).toEqual({ status: "not-found" });
});
+ it("starts from the status found before the service worker stopped", async () => {
+ await fakeBrowser.storage.session.set({ triliumSearch: FOUND_DESKTOP });
+ let refuseDesktop: (error: Error) => void = () => {};
+ fetchMock.mockImplementation(() => new Promise((_resolve, reject) => refuseDesktop = reject));
+
+ const facade = new TriliumServerFacade();
+ await facade.sendTriliumSearchStatusToPopup();
+ expect(searchStatuses()).toEqual([ FOUND_DESKTOP ]);
+
+ await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledOnce());
+ refuseDesktop(new Error("connection refused"));
+ await expect(facade.waitForTriliumSearch()).rejects.toThrow(
+ expect.objectContaining({ reason: "not-found" }));
+ expect(lastSearchStatus()).toEqual({ status: "not-found" });
+ expect(await fakeBrowser.storage.session.get("triliumSearch"))
+ .toEqual({ triliumSearch: { status: "not-found" } });
+ });
+
+ it("keeps the outcome of the latest search when an older one ends after it", async () => {
+ const answers: ((response: Response) => void)[] = [];
+ fetchMock.mockImplementation(() => new Promise((resolve) => answers.push(resolve)));
+ const facade = new TriliumServerFacade();
+ await vi.waitFor(() => expect(answers).toHaveLength(1));
+
+ const call = facade.waitForTriliumSearch();
+ const latest = facade.triggerSearchForTrilium();
+ await vi.waitFor(() => expect(answers).toHaveLength(2));
+ answers[1]?.(handshake("1.0"));
+ await latest;
+ answers[0]?.(handshake("2.0"));
+
+ await expect(call).resolves.toEqual(FOUND_DESKTOP);
+ await vi.advanceTimersByTimeAsync(0);
+ expect(lastSearchStatus()).toEqual(FOUND_DESKTOP);
+ expect(await fakeBrowser.storage.session.get("triliumSearch"))
+ .toEqual({ triliumSearch: FOUND_DESKTOP });
+ expect(searchStatuses()).not.toContainEqual(
+ expect.objectContaining({ status: "version-mismatch" }));
+ });
+
it("ignores the popup being closed", async () => {
sendMessage.mockRejectedValue(new Error("Could not establish connection"));
- fetchMock.mockResolvedValue(handshake("1.0"));
+ fetchMock.mockImplementation(async () => handshake("1.0"));
- const facade = await createFacade();
+ const facade = new TriliumServerFacade();
+ await expect(facade.waitForTriliumSearch()).resolves.toEqual(FOUND_DESKTOP);
await expect(facade.sendTriliumSearchNoteToPopup()).resolves.toBeUndefined();
});
});
@@ -292,10 +358,14 @@ function handshake(protocolVersion: string) {
return Response.json({ appName: "trilium", protocolVersion });
}
+function handshakeInit(headers?: Record<string, string>) {
+ return { headers, signal: expect.any(AbortSignal) };
+}
+
async function createFacade() {
sendMessage.mockClear();
const facade = new TriliumServerFacade();
- await vi.waitFor(() => expect(lastSearchStatus()?.status).not.toBe("searching"));
+ await facade.waitForTriliumSearch().catch(() => {});
return facade;
}
diff --git a/apps/web-clipper/entrypoints/background/trilium_server_facade.ts b/apps/web-clipper/entrypoints/background/trilium_server_facade.ts
index f642e835ef..80435dd3f5 100644
--- a/apps/web-clipper/entrypoints/background/trilium_server_facade.ts
+++ b/apps/web-clipper/entrypoints/background/trilium_server_facade.ts
@@ -1,4 +1,6 @@
const PROTOCOL_VERSION_MAJOR = 1;
+const DESKTOP_TIMEOUT_MS = 2000;
+const SERVER_TIMEOUT_MS = 10000;
export type TriliumSearchStatus = {
status: "searching";
@@ -18,7 +20,9 @@ export type TriliumSearchStatus = {
triliumMajor: number;
};
-type FoundStatus = Exclude<TriliumSearchStatus, { status: "searching" | "not-found" }>;
+/** The outcome of a finished search. */
+type SearchResult = Exclude<TriliumSearchStatus, { status: "searching" }>;
+type FoundStatus = Exclude<SearchResult, { status: "not-found" }>;
export type TriliumSearchNoteStatus = {
status: "not-found",
@@ -43,15 +47,26 @@ export class TriliumError extends Error {
export default class TriliumServerFacade {
private triliumSearch: TriliumSearchStatus = { status: "searching" };
private triliumSearchNote?: TriliumSearchNoteStatus;
+ /** The latest search, which `callService()` waits for. */
+ private search: Promise<SearchResult>;
+ private searchCount = 0;
+ /** Reads the status found before the service worker was last stopped. */
+ private readonly restored: Promise<void>;
constructor() {
- this.triggerSearchForTrilium();
+ this.restored = browser.storage.session
+ .get<{ triliumSearch?: SearchResult }>("triliumSearch")
+ .then(({ triliumSearch }) => {
+ if (triliumSearch) this.triliumSearch = triliumSearch;
+ });
+ this.search = this.triggerSearchForTrilium(false);
// continually scan for changes (if e.g. desktop app is started after browser)
- setInterval(() => this.triggerSearchForTrilium(), 60 * 1000);
+ setInterval(() => this.triggerSearchForTrilium(false), 60 * 1000);
}
async sendTriliumSearchStatusToPopup() {
+ await this.restored;
try {
await browser.runtime.sendMessage({
name: "trilium-search-status",
@@ -82,90 +97,50 @@ export default class TriliumServerFacade {
this.sendTriliumSearchStatusToPopup();
}
- setTriliumSearchWithVersionCheck(json: { protocolVersion: string }, resp: TriliumSearchStatus) {
- const [ major = NaN ] = json.protocolVersion
- .split(".")
- .map(chunk => parseInt(chunk, 10));
-
- // minor version is intended to be used to dynamically limit features provided by extension
- // if some specific Trilium API is not supported. So far not needed.
-
- if (major !== PROTOCOL_VERSION_MAJOR) {
- this.setTriliumSearch({
- status: 'version-mismatch',
- extensionMajor: PROTOCOL_VERSION_MAJOR,
- triliumMajor: major
+ /**
+ * Looks for Trilium and reports the outcome to the popup. With `showProgress` false, the popup
+ * keeps the last status until the search ends, so a background check does not flash "searching".
+ */
+ triggerSearchForTrilium(showProgress = true) {
+ const id = ++this.searchCount;
+ const search = this.restored
+ .then(() => {
+ if (showProgress) this.setTriliumSearch({ status: "searching" });
+ return this.findTrilium();
+ })
+ .then(async (status) => {
+ if (id === this.searchCount) {
+ this.setTriliumSearch(status);
+ await browser.storage.session.set({ triliumSearch: status });
+ }
+ return status;
});
- }
- else {
- this.setTriliumSearch(resp);
- }
+ this.search = search;
+ return search;
}
- async triggerSearchForTrilium() {
- this.setTriliumSearch({ status: 'searching' });
-
- try {
- const port = await this.getPort();
-
- console.debug(`Trying port ${port}`);
-
- const resp = await fetch(`http://127.0.0.1:${port}/api/clipper/handshake`);
-
- const text = await resp.text();
-
- console.log("Received response:", text);
-
- const json = JSON.parse(text);
-
- if (json.appName === 'trilium') {
- this.setTriliumSearchWithVersionCheck(json, {
- status: 'found-desktop',
- port,
- url: `http://127.0.0.1:${port}`
- });
-
- return;
- }
- }
- catch (error) {
- // continue
- }
-
- const {triliumServerUrl} = await browser.storage.sync.get<{ triliumServerUrl: string }>("triliumServerUrl");
- const {authToken} = await browser.storage.sync.get<{ authToken: string }>("authToken");
-
- if (triliumServerUrl && authToken) {
- try {
- const resp = await fetch(`${triliumServerUrl }/api/clipper/handshake`, {
- headers: {
- Authorization: authToken
- }
- });
-
- const text = await resp.text();
-
- console.log("Received response:", text);
-
- const json = JSON.parse(text);
-
- if (json.appName === 'trilium') {
- this.setTriliumSearchWithVersionCheck(json, {
- status: 'found-server',
- url: triliumServerUrl,
- token: authToken
- });
-
- return;
- }
- }
- catch (e) {
- console.log("Request to the configured server instance failed with:", e);
- }
+ /** Asks the desktop app and the server at once, and prefers the desktop app when both answer. */
+ private async findTrilium(): Promise<SearchResult> {
+ const port = await this.getPort();
+ const desktopUrl = `http://127.0.0.1:${port}`;
+ const { triliumServerUrl, authToken } = await browser.storage.sync
+ .get<{ triliumServerUrl?: string, authToken?: string }>([ "triliumServerUrl", "authToken" ]);
+
+ const server = triliumServerUrl && authToken
+ ? handshake(triliumServerUrl, SERVER_TIMEOUT_MS, { Authorization: authToken })
+ .then((json) => json && checkVersion(json, {
+ status: "found-server",
+ url: triliumServerUrl,
+ token: authToken
+ }))
+ : Promise.resolve(null);
+
+ const desktop = await handshake(desktopUrl, DESKTOP_TIMEOUT_MS);
+ if (desktop) {
+ return checkVersion(desktop, { status: "found-desktop", port, url: desktopUrl });
}
- // if all above fails it's not found
- this.setTriliumSearch({ status: 'not-found' });
+ return await server ?? { status: "not-found" };
}
async triggerSearchNoteByUrl(noteUrl: string) {
@@ -185,22 +160,20 @@ export default class TriliumServerFacade {
}
this.setTriliumSearchNote(newStatus);
}
- /** Resolves with the outcome of the running search, and rejects if Trilium was not found. */
- async waitForTriliumSearch() {
- return new Promise<FoundStatus>((res, rej) => {
- const checkStatus = () => {
- const search = this.triliumSearch;
- if (search.status === "searching") {
- setTimeout(checkStatus, 500);
- } else if (search.status === "not-found") {
- rej(notFound());
- } else {
- res(search);
- }
- };
- checkStatus();
- });
+ /** Resolves with the outcome of the latest search, and rejects if Trilium was not found. */
+ async waitForTriliumSearch(): Promise<FoundStatus> {
+ let search: Promise<SearchResult>;
+ let status: SearchResult;
+ do {
+ search = this.search;
+ status = await search;
+ } while (search !== this.search);
+
+ if (status.status === "not-found") {
+ throw notFound();
+ }
+ return status;
}
async getPort() {
@@ -268,6 +241,42 @@ export default class TriliumServerFacade {
}
}
+
+type HandshakeResponse = { appName?: string, protocolVersion: string };
+
+/** Resolves with the handshake of the Trilium at `url`, or `null` if none answers in time. */
+async function handshake(url: string, timeoutMs: number, headers?: Record<string, string>) {
+ try {
+ const response = await fetch(`${url}/api/clipper/handshake`, {
+ headers,
+ signal: AbortSignal.timeout(timeoutMs)
+ });
+ const json = JSON.parse(await response.text()) as HandshakeResponse;
+ return json.appName === "trilium" ? json : null;
+ } catch (e) {
+ console.log(`Handshake with ${url} failed with:`, e);
+ return null;
+ }
+}
+
+function checkVersion(json: HandshakeResponse, found: FoundStatus): SearchResult {
+ const [ major = NaN ] = json.protocolVersion
+ .split(".")
+ .map(chunk => parseInt(chunk, 10));
+
+ // minor version is intended to be used to dynamically limit features provided by extension
+ // if some specific Trilium API is not supported. So far not needed.
+
+ if (major !== PROTOCOL_VERSION_MAJOR) {
+ return {
+ status: "version-mismatch",
+ extensionMajor: PROTOCOL_VERSION_MAJOR,
+ triliumMajor: major
+ };
+ }
+ return found;
+}
+
function notFound() {
return new TriliumError("not-found", "Trilium was not found. Start the desktop app, or check "
+ "the server address and token in the clipper's options.");