aboutsummaryrefslogtreecommitdiff
path: root/castle-search/src/http.ts
diff options
context:
space:
mode:
authorIgor Soarez <igor@soarez.org>2026-11-18 04:55:45 +0000
committerIgor Soarez <igor@soarez.org>2026-11-18 04:55:45 +0000
commitb03415aafeea985561f3980f8b484173530a05f8 (patch)
tree3748f62ae52a5c4d7906ec3268bb8b2863a5114a /castle-search/src/http.ts
parent4c1f9b4ea943d03e9610f13344c372e630db5b9d (diff)
castle-search: search X over HTTP, through the browser's signed-in session
POST /x-search reads x.com/search in a background tab: posts with their link, author, time, text, counts and quoted post, scrolling for up to 20. GET /openapi.json describes it for Open WebUI's tool servers. Signed out, an X error page or a stuck page are errors, never an empty list.
Diffstat (limited to 'castle-search/src/http.ts')
-rw-r--r--castle-search/src/http.ts107
1 files changed, 102 insertions, 5 deletions
diff --git a/castle-search/src/http.ts b/castle-search/src/http.ts
index 31b1eaa..17c8c70 100644
--- a/castle-search/src/http.ts
+++ b/castle-search/src/http.ts
@@ -19,12 +19,18 @@
* 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.
+ *
+ * POST /x-search searches X instead (x-search.ts), through the browser's
+ * signed-in X session, and GET /openapi.json describes it, so that Open WebUI
+ * can offer it as a tool: `{ "query", "count", "sort" }` in, `{ "query", "sort",
+ * "posts": [...] }` out, 502 with `{ "error" }` on failure.
*/
import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
import { messageOf } from "./errors.ts";
import { disconnect, search, type SearchOutcome, type SearchRequest } from "./search.ts";
+import { xSearch, type XSearchOutcome, type XSearchRequest } from "./x-search.ts";
export const DEFAULT_LISTEN = "127.0.0.1:11158";
const MAX_BODY_BYTES = 64 * 1024;
@@ -68,6 +74,85 @@ export const handleSearch = async (raw: string, run: Searcher, signal: AbortSign
}
};
+export type XSearcher = (request: XSearchRequest, signal: AbortSignal) => Promise<XSearchOutcome>;
+
+const X_DEFAULT_COUNT = 10;
+
+/** POST /x-search: `{ query, count?, sort? }` in, `{ query, sort, posts }` out. */
+export const handleXSearch = async (raw: string, run: XSearcher, signal: AbortSignal): Promise<Reply> => {
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(raw);
+ } catch {
+ return { status: 400, body: { error: "request body is not JSON" } };
+ }
+ const { query, count, sort } = (parsed ?? {}) as { query?: unknown; count?: unknown; sort?: unknown };
+ if (typeof query !== "string" || query.trim() === "") {
+ return { status: 400, body: { error: "query must be a non-empty string" } };
+ }
+ if (sort !== undefined && sort !== null && sort !== "latest" && sort !== "top") {
+ return { status: 400, body: { error: 'sort must be "latest" or "top"' } };
+ }
+ const n = typeof count === "number" && Number.isFinite(count) ? Math.trunc(count) : X_DEFAULT_COUNT;
+ try {
+ const outcome = await run(
+ { query: query.trim(), count: Math.min(MAX_COUNT, Math.max(1, n)), sort: sort ?? "latest" },
+ signal,
+ );
+ return { status: 200, body: { query: outcome.query, sort: outcome.sort, posts: outcome.posts } };
+ } catch (e) {
+ return { status: 502, body: { error: messageOf(e) } };
+ }
+};
+
+/**
+ * The OpenAPI description Open WebUI reads to offer /x-search as a tool. Its
+ * descriptions are what the model sees, so they say what the tool is for and
+ * how to write a query.
+ */
+export const OPENAPI = {
+ openapi: "3.1.0",
+ info: {
+ title: "castle X search",
+ version: "1.0.0",
+ description: "Searches posts on X (Twitter) through a signed-in browser. Free per search.",
+ },
+ paths: {
+ "/x-search": {
+ post: {
+ operationId: "search_x",
+ summary: "Search posts on X (Twitter)",
+ description:
+ "Search X for posts, newest first by default. Use it for anything on X: what someone posted, " +
+ "reactions to news, posts about a topic. The query uses X's search syntax: from:handle, to:handle, " +
+ '"exact phrase", OR, -word, since:YYYY-MM-DD, until:YYYY-MM-DD, min_faves:N, filter:media, ' +
+ "-filter:replies, lang:en. A handle is written without @ after from:. Each post comes with its " +
+ "link: cite it. Text cut short by X is marked truncated.",
+ requestBody: {
+ required: true,
+ content: {
+ "application/json": {
+ schema: {
+ type: "object",
+ required: ["query"],
+ properties: {
+ query: { type: "string", description: "X search query, e.g. from:nasa since:2026-11-01" },
+ count: { type: "integer", minimum: 1, maximum: MAX_COUNT, default: X_DEFAULT_COUNT, description: "How many posts" },
+ sort: { type: "string", enum: ["latest", "top"], default: "latest", description: "latest: newest first; top: most engaged" },
+ },
+ },
+ },
+ },
+ },
+ responses: {
+ "200": { description: "Matching posts", content: { "application/json": { schema: { type: "object" } } } },
+ "502": { description: "The search failed; error says why", content: { "application/json": { schema: { type: "object" } } } },
+ },
+ },
+ },
+ },
+} as const;
+
const readBody = (req: IncomingMessage): Promise<string> =>
new Promise((resolve, reject) => {
let size = 0;
@@ -110,8 +195,13 @@ const main = (): void => {
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" } });
+ if (req.method === "GET" && path === "/openapi.json") {
+ send(res, { status: 200, body: OPENAPI });
+ return;
+ }
+ const isX = path === "/x-search";
+ if (req.method !== "POST" || (path !== "/" && path !== "/search" && !isX)) {
+ send(res, { status: 404, body: { error: "POST a search to / or /search, or an X search to /x-search" } });
return;
}
// Stop the search, and free its tab, if the client goes away first.
@@ -127,9 +217,16 @@ const main = (): void => {
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`);
+ const reply = isX
+ ? await handleXSearch(raw, xSearch, controller.signal)
+ : await handleSearch(raw, runSearch, controller.signal);
+ const outcome =
+ reply.status !== 200
+ ? `error ${reply.status}`
+ : isX
+ ? `${(reply.body as { posts: unknown[] }).posts.length} posts`
+ : `${(reply.body as unknown[]).length} results`;
+ console.log(`${isX ? "x-search" : "search"} ${outcome} in ${Date.now() - started} ms`);
if (reply.status !== 200) console.log(` ${(reply.body as { error: string }).error}`);
send(res, reply);
});