Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
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.mdindex 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 andreports `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.tsindex 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.tsindex 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.");