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
docs(search): document the query route contract
Amp587016b9e89d
diff --git a/apps/server/e2e/exact_search.spec.ts b/apps/server/e2e/exact_search.spec.tsindex d94d1e1eda..82394315c5 100644--- a/apps/server/e2e/exact_search.spec.ts+++ b/apps/server/e2e/exact_search.spec.ts@@ -155,6 +155,16 @@ test.describe("Exact Search with Leading = Operator", () => {console.log("Note titles:", testResults.map((r: any) => r.noteTitle));});+ test("Search APIs accept slash-bearing query text", async ({ page }) => {+ for (const path of [ "quick-search", "search" ] as const) {+ const response = await page.request.get(getSearchUrl(path, "中/英"), {+ headers: { "x-csrf-token": csrfToken }+ });++ expect(response.ok()).toBeTruthy();+ }+ });+test("Quick search with = operator returns only exact matches", async ({ page }) => {// Test the /quick-search endpoint WITH the = operatorconst response = await page.request.get(getSearchUrl("quick-search", "=pagio"), {diff --git a/apps/server/internal.openapi.yaml b/apps/server/internal.openapi.yamlindex 9d2105b605..3b6d1bff71 100644--- a/apps/server/internal.openapi.yaml+++ b/apps/server/internal.openapi.yaml@@ -1934,6 +1934,29 @@ paths:$ref: '#/components/schemas/SearchResult''400':description: Missing or empty search string++ /api/search/{searchString}:+ get:+ tags: [Search]+ summary: Full text search with a path parameter+ description: Deprecated. Use `/api/search` with the `searchString` query parameter.+ operationId: searchLegacy+ deprecated: true+ parameters:+ - name: searchString+ in: path+ required: true+ schema:+ type: string+ responses:+ '200':+ description: Search results+ content:+ application/json:+ schema:+ type: array+ items:+ $ref: '#/components/schemas/SearchResult'/api/quick-search:get:@@ -1958,6 +1981,29 @@ paths:$ref: '#/components/schemas/SearchResult''400':description: Missing or empty search string++ /api/quick-search/{searchString}:+ get:+ tags: [Search]+ summary: Quick search with a path parameter+ description: Deprecated. Use `/api/quick-search` with the `searchString` query parameter.+ operationId: quickSearchLegacy+ deprecated: true+ parameters:+ - name: searchString+ in: path+ required: true+ schema:+ type: string+ responses:+ '200':+ description: Quick search results+ content:+ application/json:+ schema:+ type: array+ items:+ $ref: '#/components/schemas/SearchResult'/api/search-note/{noteId}:get:diff --git a/docs/Developer Guide/Developer Guide/Architecture/APIs.md b/docs/Developer Guide/Developer Guide/Architecture/APIs.mdindex cdd954a610..2e76737068 100644--- a/docs/Developer Guide/Developer Guide/Architecture/APIs.md+++ b/docs/Developer Guide/Developer Guide/Architecture/APIs.md@@ -21,7 +21,7 @@ Used by the frontend for all operations:**Search:**-* `GET /api/search?query=...` - Search notes+* `GET /api/search?searchString=...` - Search notes* `GET /api/search-note/:noteId` - Execute search note### ETAPI (External API)@@ -69,4 +69,4 @@ Located at: `apps/server/src/services/ws.ts`ws.subscribe('entity-change', (data) => {froca.processEntityChange(data)})-```\ No newline at end of file+```diff --git a/docs/User Guide/User Guide/Installation & Setup/Server Installation/2. Reverse proxy/Traefik.md b/docs/User Guide/User Guide/Installation & Setup/Server Installation/2. Reverse proxy/Traefik.mdindex 59af92a7e9..a869934f68 100644--- a/docs/User Guide/User Guide/Installation & Setup/Server Installation/2. Reverse proxy/Traefik.md+++ b/docs/User Guide/User Guide/Installation & Setup/Server Installation/2. Reverse proxy/Traefik.md@@ -3,7 +3,7 @@ The goal of this article is to configure Traefik proxy and HTTPS. See [#7768](ht## Breaking change in Traefik 3.6.4-Traefik 3.6.4 introduced a [breaking change](https://doc.traefik.io/traefik/migrate/v3/#encoded-characters-in-request-path) regarding how percent-encoded characters are handled in URLs. More specifically some URLs used by Trilium (such as `search/%23workspace%20%23!template`) are automatically rejected by Traefik, resulting in HTTP 400 errors.+Traefik 3.6.4 introduced a [breaking change](https://doc.traefik.io/traefik/migrate/v3/#encoded-characters-in-request-path) regarding how percent-encoded characters are handled in URLs. Some paths used by older Trilium clients, such as `/api/search/%23workspace%20%23!template`, are automatically rejected by Traefik and result in HTTP 400 errors. Current clients send search text in a query parameter, but older clients and other routes can still need this configuration.The easiest solution is to update to Traefik 3.6.7 or later which reverts this configuration change. Alternatively, the configuration can be changed according to the section below.@@ -16,7 +16,7 @@ The easiest solution is to update to Traefik 3.6.7 or later which reverts this cencodedCharacters:allowEncodedSlash: trueallowEncodedHash: true</code></pre>- <aside class="admonition tip"><p>If you still have issues, depending on how Trilium is used (especially regarding search), you might need to enable more encoded character groups. For more information, see <a href="https://github.com/TriliumNext/Trilium/issues/7968">the relevant GitHub issue</a>; feel free to report your findings.</p></aside>+ <aside class="admonition tip"><p>If you still have issues, older clients or other routes might need more encoded character groups. For more information, see <a href="https://github.com/TriliumNext/Trilium/issues/7968">the relevant GitHub issue</a>; feel free to report your findings.</p></aside></details>### Build the docker-compose file@@ -75,4 +75,4 @@ services:networks:traefik-proxy:external: true-```\ No newline at end of file+```diff --git a/packages/trilium-core/src/routes/api/search.spec.ts b/packages/trilium-core/src/routes/api/search.spec.tsindex fc8379930c..7640020778 100644--- a/packages/trilium-core/src/routes/api/search.spec.ts+++ b/packages/trilium-core/src/routes/api/search.spec.ts@@ -163,6 +163,16 @@ describe("Search API (core)", () => {});it("keeps path parameters compatible with existing clients", async () => {+ const legacyFull = await api.get<string[]>(`/api/search/${UNIQUE_TOKEN}`);+ expect(legacyFull.status).toBe(200);+ expect(legacyFull.body).toContain(createdNoteId);++ const legacyQuick = await api.get<{ searchResultNoteIds: string[] }>(+ `/api/quick-search/${UNIQUE_TOKEN}`+ );+ expect(legacyQuick.status).toBe(200);+ expect(legacyQuick.body.searchResultNoteIds).toContain(createdNoteId);+const full = await api.get<string[]>(`/api/search/${UNIQUE_TOKEN}`, {query: { searchString: "" }});diff --git a/packages/trilium-core/src/routes/api/search.ts b/packages/trilium-core/src/routes/api/search.tsindex fb2bd34092..3028b3e0e7 100644--- a/packages/trilium-core/src/routes/api/search.ts+++ b/packages/trilium-core/src/routes/api/search.ts@@ -173,7 +173,7 @@ function getSearchString(req: Request<{ searchString?: string }>): string {const searchString = req.params.searchString ?? req.query.searchString;if (typeof searchString !== "string" || searchString.length === 0) {- throw new ValidationError("Search string must be a string.");+ throw new ValidationError("Search string must be a non-empty string.");}return searchString;