nixamp 0.36.4 → 0.37.0

package/src/ai-routes.ts

@@ -0,0 +1,220 @@
+/**
+ * AI radio and listener shares over HTTP.
+ *
+ * Public, no key, because sharing and reporting are what the guide offers
+ * anybody: `/api/v1/share` (what may be shared, and a link to share),
+ * `/api/v1/share/upload` (the file as the body), `/api/v1/share/:id?t=`
+ * (how it went; DELETE takes it back) and `/api/v1/share/report` (take what
+ * is playing off the air). Everything else is the owner's, under
+ * /api/v1/stations/ai and /api/v1/stations/shares.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { AI_KEY_NAMES, aiKeysSet, saveAiKey, type AiKeyName } from "./ai-keys.ts";
+import type { AiRadio } from "./ai-radio.ts";
+import { SHARE_BASES, SHARE_GENRES, ownerShareView, sharerView, type ListenerShares } from "./listener-shares.ts";
+import { StationError } from "./stations.ts";
+
+const PUBLIC = /^\/api\/v1\/share(?:\/(upload|report|[a-f0-9]{12}))?$/;
+
+/** Whether this path is one anybody may use without the server's key. */
+export function isPublicSharePath(path: string): boolean {
+  return PUBLIC.test(path);
+}
+
+export interface AiRoutesContext {
+  ai?: AiRadio;
+  shares?: ListenerShares;
+  canControl: boolean;
+  /** Who is asking, for per-sharer limits (an address; hashed before it is kept). */
+  caller: string;
+  json: (response: ServerResponse, status: number, body: unknown) => void;
+  readBody: (request: IncomingMessage) => Promise<string>;
+  headers: Record<string, string>;
+  /** Null to go ahead, or how long to wait: a public limit on top of the per-sharer one. */
+  throttle?: () => { retryAfter: number } | null;
+}
+
+async function jsonBody(ctx: AiRoutesContext, request: IncomingMessage): Promise<Record<string, unknown>> {
+  const raw = await ctx.readBody(request);
+  if (raw.trim() === "") return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new StationError("bad_json", "the body is not JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new StationError("bad_json", "the body is not a JSON object");
+  return parsed as Record<string, unknown>;
+}
+
+/** Answers the paths above; false when the path is not one of them. */
+export async function handleAiRoutes(
+  request: IncomingMessage,
+  response: ServerResponse,
+  path: string,
+  url: URL,
+  ctx: AiRoutesContext,
+): Promise<boolean> {
+  const method = request.method ?? "GET";
+  const publicPath = PUBLIC.exec(path);
+  const ownerPath = path === "/api/v1/stations/ai" || path.startsWith("/api/v1/stations/ai/") || path === "/api/v1/stations/shares" || path.startsWith("/api/v1/stations/shares/");
+  if (!publicPath && !ownerPath) return false;
+  try {
+    if (publicPath) {
+      const shares = ctx.shares;
+      if (!shares) {
+        ctx.json(response, 404, { error: "this server does not take shared tracks", code: "not_found" });
+        return true;
+      }
+      const what = publicPath[1];
+      if (what === undefined && method === "GET") {
+        const setting = shares.setting();
+        ctx.json(response, 200, { open: setting.open, bases: SHARE_BASES, genres: SHARE_GENRES, maxMb: Math.round(setting.maxBytes / 1048576), perHour: setting.perHour });
+        return true;
+      }
+      if (method !== "GET" && method !== "DELETE" && ctx.throttle) {
+        const wait = ctx.throttle();
+        if (wait) {
+          response.setHeader("retry-after", String(wait.retryAfter));
+          ctx.json(response, 429, { error: "too many at once; wait a moment", code: "rate_limited", retryAfter: wait.retryAfter });
+          return true;
+        }
+      }
+      if (what === undefined && method === "POST") {
+        const share = shares.fromUrl(await jsonBody(ctx, request), ctx.caller);
+        ctx.json(response, 202, { share: sharerView(share), token: share.token, status: `/api/v1/share/${share.id}?t=${share.token}` });
+        return true;
+      }
+      if (what === "upload" && (method === "PUT" || method === "POST")) {
+        const input = Object.fromEntries(url.searchParams.entries());
+        const share = await shares.fromUpload(request, input, ctx.caller);
+        ctx.json(response, 202, { share: sharerView(share), token: share.token, status: `/api/v1/share/${share.id}?t=${share.token}` });
+        return true;
+      }
+      if (what === "report" && method === "POST") {
+        const input = await jsonBody(ctx, request);
+        ctx.json(response, 200, shares.report(input, ctx.caller));
+        return true;
+      }
+      if (what && /^[a-f0-9]{12}$/.test(what) && (method === "GET" || method === "DELETE")) {
+        const share = shares.forSharer(what, url.searchParams.get("t") ?? "");
+        if (!share) {
+          ctx.json(response, 404, { error: "no such share, or not with that link", code: "not_found" });
+          return true;
+        }
+        ctx.json(response, 200, { share: sharerView(method === "DELETE" ? shares.withdraw(share) : share) });
+        return true;
+      }
+      ctx.json(response, 405, { error: "not like that", code: "method_not_allowed" });
+      return true;
+    }
+
+    if (!ctx.canControl) {
+      ctx.json(response, 403, { error: "only this server's owner manages AI radio and shares", code: "forbidden" });
+      return true;
+    }
+
+    if (path === "/api/v1/stations/shares" || path.startsWith("/api/v1/stations/shares/")) {
+      const shares = ctx.shares;
+      if (!shares) {
+        ctx.json(response, 404, { error: "shares are not available here", code: "not_found" });
+        return true;
+      }
+      if (path === "/api/v1/stations/shares") {
+        if (method === "GET") {
+          const list = shares.list(url.searchParams.get("state") ?? undefined);
+          ctx.json(response, 200, { setting: shares.setting(), total: list.length, shares: list.slice(0, 200).map(ownerShareView) });
+          return true;
+        }
+        if (method === "POST") {
+          ctx.json(response, 200, { setting: shares.configure(await jsonBody(ctx, request)) });
+          return true;
+        }
+      }
+      const match = /^\/api\/v1\/stations\/shares\/([a-f0-9]{12})(?:\/(approve|reject))?$/.exec(path);
+      if (match) {
+        const [, id, decision] = match;
+        if (!decision && method === "GET") {
+          const share = shares.get(id!);
+          if (!share) throw new StationError("not_found", "no such share", 404);
+          ctx.json(response, 200, { share: ownerShareView(share) });
+          return true;
+        }
+        if (!decision && method === "DELETE") {
+          shares.decide(id!, "delete");
+          ctx.json(response, 200, { deleted: id });
+          return true;
+        }
+        if (decision && method === "POST") {
+          const input = await jsonBody(ctx, request);
+          const share = shares.decide(id!, decision as "approve" | "reject", typeof input["reason"] === "string" ? input["reason"].slice(0, 300) : "");
+          ctx.json(response, 200, { share: share ? ownerShareView(share) : null });
+          return true;
+        }
+      }
+      ctx.json(response, 404, { error: "no such share route", code: "not_found" });
+      return true;
+    }
+
+    const ai = ctx.ai;
+    if (!ai) {
+      ctx.json(response, 404, { error: "AI radio is not available here", code: "not_found" });
+      return true;
+    }
+    if (path === "/api/v1/stations/ai") {
+      if (method === "GET") {
+        ctx.json(response, 200, { ...ai.status(), keys: aiKeysSet() });
+        return true;
+      }
+      if (method === "POST") {
+        ctx.json(response, 200, { settings: ai.configure(await jsonBody(ctx, request)) });
+        return true;
+      }
+    }
+    if (path === "/api/v1/stations/ai/keys" && method === "POST") {
+      const input = await jsonBody(ctx, request);
+      const name = String(input["name"] ?? "");
+      if (!AI_KEY_NAMES.includes(name as AiKeyName)) throw new StationError("unknown_key", `keys: ${AI_KEY_NAMES.join(", ")}`);
+      saveAiKey(name as AiKeyName, typeof input["value"] === "string" ? input["value"] : "");
+      ctx.json(response, 200, { keys: aiKeysSet() });
+      return true;
+    }
+    if (path === "/api/v1/stations/ai/stations" && method === "POST") {
+      ctx.json(response, 201, { station: ai.create(await jsonBody(ctx, request)) });
+      return true;
+    }
+    const match = /^\/api\/v1\/stations\/ai\/stations\/([a-f0-9]{10})(?:\/(generate))?$/.exec(path);
+    if (match) {
+      const [, key, action] = match;
+      if (!action && method === "GET") {
+        const station = ai.get(key!);
+        if (!station) throw new StationError("not_found", "no such AI station", 404);
+        ctx.json(response, 200, { station });
+        return true;
+      }
+      if (!action && method === "PATCH") {
+        ctx.json(response, 200, { station: ai.update(key!, await jsonBody(ctx, request)) });
+        return true;
+      }
+      if (!action && method === "DELETE") {
+        ai.remove(key!, url.searchParams.get("files") === "1");
+        ctx.json(response, 200, { deleted: key });
+        return true;
+      }
+      if (action === "generate" && method === "POST") {
+        // Composing takes a minute or two; answer when it is on the station.
+        ctx.json(response, 200, { track: await ai.generate(key!) });
+        return true;
+      }
+    }
+    ctx.json(response, 404, { error: "no such AI radio route", code: "not_found" });
+    return true;
+  } catch (error) {
+    if (error instanceof StationError) {
+      ctx.json(response, error.status, { error: error.message, code: error.code });
+    } else {
+      ctx.json(response, 500, { error: error instanceof Error ? error.message : String(error), code: "internal" });
+    }
+    return true;
+  }
+}

package/src/ai-text.ts

@@ -0,0 +1,117 @@
+/**
+ * One question to a language model, one JSON answer.
+ *
+ * AI radio asks for small things: a title and a prompt for the next track, a
+ * genre and a verdict for a shared file. Whichever model has a key answers --
+ * Gemini, then OpenAI, then Anthropic -- and when none has, the caller is told
+ * so and does without (a rule of its own, or a person). The answer is parsed
+ * and handed back as an object; a model that rambles round its JSON is read
+ * for the first object in what it said.
+ */
+import { aiKey } from "./ai-keys.ts";
+
+export interface AskOptions {
+  /** What the model is for, said once. */
+  system: string;
+  /** The question, with what it should answer from. */
+  prompt: string;
+  /** Milliseconds before giving up (default 30 s). */
+  timeoutMs?: number;
+  fetcher?: typeof fetch;
+  env?: Record<string, string | undefined>;
+}
+
+export interface Answer {
+  /** Which model answered, for the record ("gemini-flash-latest", ...). */
+  model: string;
+  value: Record<string, unknown>;
+}
+
+export class NoModel extends Error {
+  constructor() {
+    super("no language model key is set (GEMINI_API_KEY, OPENAI_API_KEY or ANTHROPIC_API_KEY)");
+  }
+}
+
+/** The first JSON object in a model's answer. */
+export function firstObject(text: string): Record<string, unknown> {
+  const cleaned = text.replace(/^```(?:json)?\s*/i, "").replace(/```\s*$/, "");
+  try {
+    const parsed = JSON.parse(cleaned) as unknown;
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) return parsed as Record<string, unknown>;
+  } catch {
+    // Look inside it instead.
+  }
+  const start = cleaned.indexOf("{");
+  const end = cleaned.lastIndexOf("}");
+  if (start !== -1 && end > start) {
+    const parsed = JSON.parse(cleaned.slice(start, end + 1)) as unknown;
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) return parsed as Record<string, unknown>;
+  }
+  throw new Error("the model did not answer with a JSON object");
+}
+
+/** Whether any model can be asked. */
+export function hasModel(env: Record<string, string | undefined> = process.env): boolean {
+  return Boolean(aiKey("GEMINI_API_KEY", env) || aiKey("OPENAI_API_KEY", env) || aiKey("ANTHROPIC_API_KEY", env));
+}
+
+export async function askJson(options: AskOptions): Promise<Answer> {
+  const env = options.env ?? process.env;
+  const send = options.fetcher ?? fetch;
+  const signal = AbortSignal.timeout(options.timeoutMs ?? 30_000);
+  const gemini = aiKey("GEMINI_API_KEY", env);
+  const openai = aiKey("OPENAI_API_KEY", env);
+  const anthropic = aiKey("ANTHROPIC_API_KEY", env);
+  if (gemini) {
+    const model = env["NIXAMP_GEMINI_MODEL"] || "gemini-flash-latest";
+    const response = await send(`https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`, {
+      method: "POST",
+      signal,
+      headers: { "content-type": "application/json", "x-goog-api-key": gemini },
+      body: JSON.stringify({
+        systemInstruction: { parts: [{ text: options.system }] },
+        contents: [{ role: "user", parts: [{ text: options.prompt }] }],
+        generationConfig: { responseMimeType: "application/json", temperature: 0.9 },
+      }),
+    });
+    if (!response.ok) throw new Error(`gemini answered HTTP ${response.status}`);
+    const body = (await response.json()) as { candidates?: Array<{ content?: { parts?: Array<{ text?: string }> } }> };
+    const text = body.candidates?.[0]?.content?.parts?.map((one) => one.text ?? "").join("") ?? "";
+    return { model, value: firstObject(text) };
+  }
+  if (openai) {
+    const model = env["NIXAMP_OPENAI_MODEL"] || "gpt-4.1-mini";
+    const response = await send("https://api.openai.com/v1/chat/completions", {
+      method: "POST",
+      signal,
+      headers: { "content-type": "application/json", authorization: `Bearer ${openai}` },
+      body: JSON.stringify({
+        model,
+        response_format: { type: "json_object" },
+        messages: [{ role: "system", content: options.system }, { role: "user", content: options.prompt }],
+      }),
+    });
+    if (!response.ok) throw new Error(`openai answered HTTP ${response.status}`);
+    const body = (await response.json()) as { choices?: Array<{ message?: { content?: string } }> };
+    return { model, value: firstObject(body.choices?.[0]?.message?.content ?? "") };
+  }
+  if (anthropic) {
+    const model = env["NIXAMP_ANTHROPIC_MODEL"] || "claude-haiku-5-5";
+    const response = await send("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      signal,
+      headers: { "content-type": "application/json", "x-api-key": anthropic, "anthropic-version": "2023-06-01" },
+      body: JSON.stringify({
+        model,
+        max_tokens: 1024,
+        system: `${options.system}\nAnswer with one JSON object and nothing else.`,
+        messages: [{ role: "user", content: options.prompt }],
+      }),
+    });
+    if (!response.ok) throw new Error(`anthropic answered HTTP ${response.status}`);
+    const body = (await response.json()) as { content?: Array<{ type: string; text?: string }> };
+    return { model, value: firstObject(body.content?.filter((one) => one.type === "text").map((one) => one.text ?? "").join("") ?? "") };
+  }
+  throw new NoModel();
+}

package/src/library.ts

@@ -31,6 +31,8 @@ export interface Config {
   guideHosts?: string[];
   /** Station limits kept across restarts (station-metering.ts). */
   limits?: Record<string, unknown>;
+  /** Proxies whose X-Forwarded-For is believed for listener shares (`nixamp station shares trust ADDRESS`). */
+  trustedProxies?: string[];
 }
 
 export function configPath(): string {
@@ -47,6 +49,7 @@ export function readConfig(): Config {
       ...(typeof record["publish"] === "boolean" ? { publish: record["publish"] } : {}),
       ...(typeof record["autoStations"] === "object" && record["autoStations"] !== null ? { autoStations: record["autoStations"] as Record<string, unknown> } : {}),
       ...(typeof record["limits"] === "object" && record["limits"] !== null ? { limits: record["limits"] as Record<string, unknown> } : {}),
+      ...(Array.isArray(record["trustedProxies"]) ? { trustedProxies: (record["trustedProxies"] as unknown[]).filter((one): one is string => typeof one === "string") } : {}),
       ...(Array.isArray(record["guideHosts"]) ? { guideHosts: (record["guideHosts"] as unknown[]).filter((one): one is string => typeof one === "string") } : {}),
     };
   } catch {