From 4c1f9b4ea943d03e9610f13344c372e630db5b9d Mon Sep 17 00:00:00 2001 From: Igor Soarez Date: Tue, 17 Nov 2026 08:46:39 +0000 Subject: castle-search: serve searches over HTTP for clients that are not pi src/http.ts speaks Open WebUI's external web search protocol. A failed search answers 502 with its reason, never an empty list, so a captcha cannot pass for nothing found. --- castle-search/src/http.ts | 147 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 castle-search/src/http.ts (limited to 'castle-search/src') diff --git a/castle-search/src/http.ts b/castle-search/src/http.ts new file mode 100644 index 0000000..31b1eaa --- /dev/null +++ b/castle-search/src/http.ts @@ -0,0 +1,147 @@ +/** + * castle_cdp_search as a plain HTTP service, for clients that are not pi. + * + * It speaks Open WebUI's "external" web search protocol: POST a JSON body + * `{ "query": "...", "count": 5 }`, get back `[{ "link", "title", "snippet" }]`. + * Any client that can send that can use it. + * + * node --experimental-strip-types src/http.ts [host:port] (default 127.0.0.1:11158) + * + * The engine and the browser are chosen exactly as for the pi tool: + * CCS_SEARCH_ENGINE and BU_CDP_HTTP, then the stored choices, then the defaults. + * + * A failed search is answered with HTTP 502 and `{ "error": "" }`, never + * with an empty list: an empty list reads as "the web has nothing on this", and + * a captcha or a rate limit is not that. A search that genuinely finds nothing + * is a failure too here (NoResultsError), because an engine that is quietly + * rate-limiting serves exactly that page, and the message says which it may be. + * + * It has no authentication, so bind it to loopback, as the default does, or to + * an address only trusted peers reach. Each search opens and closes one + * background tab in a browser someone may be looking at. + */ + +import { createServer, type IncomingMessage, type ServerResponse } from "node:http"; + +import { messageOf } from "./errors.ts"; +import { disconnect, search, type SearchOutcome, type SearchRequest } from "./search.ts"; + +export const DEFAULT_LISTEN = "127.0.0.1:11158"; +const MAX_BODY_BYTES = 64 * 1024; +const DEFAULT_COUNT = 5; +const MAX_COUNT = 20; + +// Said after every error. The castle-search messages tell the caller to retry +// with another `engine`, which a client of this protocol cannot do: it sends a +// query and a count, nothing else. +const ENGINE_NOTE = + "This search service cannot switch engines per call. Tell the user web search failed and why; " + + "the operator can change the engine (CCS_SEARCH_ENGINE) or clear the check in the browser."; + +export type Reply = { status: number; body: unknown }; + +export type Searcher = (request: SearchRequest, signal: AbortSignal) => Promise; + +/** Everything but the socket: parse a request body, run the search, shape the reply. */ +export const handleSearch = async (raw: string, run: Searcher, signal: AbortSignal): Promise => { + let parsed: unknown; + try { + parsed = JSON.parse(raw); + } catch { + return { status: 400, body: { error: "request body is not JSON" } }; + } + const { query, count } = (parsed ?? {}) as { query?: unknown; count?: unknown }; + if (typeof query !== "string" || query.trim() === "") { + return { status: 400, body: { error: "query must be a non-empty string" } }; + } + const n = typeof count === "number" && Number.isFinite(count) ? Math.trunc(count) : DEFAULT_COUNT; + const numResults = Math.min(MAX_COUNT, Math.max(1, n)); + + try { + const outcome = await run({ query: query.trim(), numResults }, signal); + return { + status: 200, + body: outcome.results.map((r) => ({ link: r.url, title: r.title, snippet: r.snippet })), + }; + } catch (e) { + return { status: 502, body: { error: `${messageOf(e)} ${ENGINE_NOTE}` } }; + } +}; + +const readBody = (req: IncomingMessage): Promise => + new Promise((resolve, reject) => { + let size = 0; + const chunks: Buffer[] = []; + req.on("data", (chunk: Buffer) => { + size += chunk.length; + if (size > MAX_BODY_BYTES) { + reject(new Error("request body too large")); + req.destroy(); + return; + } + chunks.push(chunk); + }); + req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8"))); + req.on("error", reject); + }); + +const send = (res: ServerResponse, reply: Reply): void => { + res.writeHead(reply.status, { "Content-Type": "application/json; charset=utf-8" }); + res.end(JSON.stringify(reply.body)); +}; + +export const parseListen = (value: string): { host: string; port: number } => { + const at = value.lastIndexOf(":"); + const host = value.slice(0, at); + const port = Number(value.slice(at + 1)); + if (at <= 0 || !Number.isInteger(port) || port < 1 || port > 65535) { + throw new Error(`listen address must be host:port, got "${value}"`); + } + return { host, port }; +}; + +const main = (): void => { + const { host, port } = parseListen(process.argv[2] ?? DEFAULT_LISTEN); + const runSearch: Searcher = (request, signal) => search(request, signal, () => {}); + + const server = createServer(async (req, res) => { + const path = (req.url ?? "/").split("?")[0]; + if (req.method === "GET" && path === "/health") { + send(res, { status: 200, body: { status: true } }); + return; + } + if (req.method !== "POST" || (path !== "/" && path !== "/search")) { + send(res, { status: 404, body: { error: "POST a search to / or /search" } }); + return; + } + // Stop the search, and free its tab, if the client goes away first. + const controller = new AbortController(); + res.on("close", () => { + if (!res.writableEnded) controller.abort(); + }); + let raw: string; + try { + raw = await readBody(req); + } catch (e) { + send(res, { status: 413, body: { error: messageOf(e) } }); + return; + } + const started = Date.now(); + const reply = await handleSearch(raw, runSearch, controller.signal); + const outcome = reply.status === 200 ? `${(reply.body as unknown[]).length} results` : `error ${reply.status}`; + console.log(`search ${outcome} in ${Date.now() - started} ms`); + if (reply.status !== 200) console.log(` ${(reply.body as { error: string }).error}`); + send(res, reply); + }); + + const stop = (): void => { + disconnect(); + server.close(() => process.exit(0)); + }; + process.on("SIGTERM", stop); + process.on("SIGINT", stop); + + server.listen(port, host, () => console.log(`castle-search HTTP listening on ${host}:${port}`)); +}; + +if (import.meta.url === `file://${process.argv[1]}`) main(); -- cgit v1.2.3