gnutella 1.0.0

package/src/gwebcache/response.ts

@@ -0,0 +1,391 @@
+import { DEFAULT_USER_AGENT } from "../const";
+import type {
+  GWebCacheCacheEntry,
+  GWebCacheHostEntry,
+  GWebCacheHttpResponse,
+  GWebCacheInfoLine,
+  GWebCachePong,
+  GWebCacheRequestOptions,
+  GWebCacheResponse,
+  GWebCacheUpdate,
+} from "./types";
+import {
+  DEFAULT_TIMEOUT_MS,
+  normalizeCacheUrl,
+  normalizeGWebCachePeer,
+  normalizeNetwork,
+  parseAge,
+  parseNetworks,
+  parseWarning,
+  sanitizeClient,
+  sanitizeVersion,
+  splitBodyLines,
+} from "./shared";
+
+type GWebCacheResponseState = {
+  peers: string[];
+  caches: string[];
+  warnings: string[];
+  info: GWebCacheInfoLine[];
+  hostEntries: GWebCacheHostEntry[];
+  cacheEntries: GWebCacheCacheEntry[];
+  seenPeers: Set<string>;
+  seenCaches: Set<string>;
+  pong?: GWebCachePong;
+  update?: GWebCacheUpdate;
+  recognized: boolean;
+};
+
+function buildUpdate(values: string[]): GWebCacheUpdate {
+  const head = values[0]?.trim().toUpperCase() || "";
+  if (head === "OK") {
+    return { ok: true, warning: parseWarning(values.slice(1)), values };
+  }
+  if (head === "WARNING") {
+    return {
+      ok: false,
+      warning: parseWarning(values.slice(1)) || "WARNING",
+      values,
+    };
+  }
+  return {
+    ok: values.some((value) => value.trim().toUpperCase() === "OK"),
+    warning: parseWarning(values),
+    values,
+  };
+}
+
+export function describeHttpError(result: GWebCacheHttpResponse): string {
+  const summary =
+    result.rawLines[0] || result.statusText || "request failed";
+  return `HTTP ${result.status}: ${summary}`;
+}
+
+export function describeUpdateError(
+  result: GWebCacheHttpResponse,
+): string {
+  if (!result.ok) return describeHttpError(result);
+  if (!result.spec) return "unexpected non-spec2 gwebcache response";
+  if (!result.update) return "missing spec2 gwebcache update response";
+  return result.update.warning || "gwebcache update rejected";
+}
+
+function setGWebCacheFlag(
+  url: URL,
+  key: string,
+  enabled: boolean | undefined,
+): void {
+  if (!enabled) return;
+  url.searchParams.set(key, "1");
+}
+
+function applyRequestMode(
+  url: URL,
+  options: GWebCacheRequestOptions,
+): void {
+  if (options.mode === "update") {
+    url.searchParams.set("update", "1");
+    return;
+  }
+  url.searchParams.set("get", "1");
+  url.searchParams.set("net", normalizeNetwork(options.network));
+}
+
+function applyRequestMetadata(
+  url: URL,
+  options: GWebCacheRequestOptions,
+): void {
+  if (options.spec) url.searchParams.set("spec", String(options.spec));
+  if (options.ping !== false) url.searchParams.set("ping", "1");
+  url.searchParams.set("client", sanitizeClient(options.client));
+  url.searchParams.set("version", sanitizeVersion(options.version));
+}
+
+function applyPeerUpdate(url: URL, peerSpec: string | undefined): void {
+  if (!peerSpec) return;
+  const peer = normalizeGWebCachePeer(peerSpec);
+  if (!peer) throw new Error(`invalid gwebcache peer update: ${peerSpec}`);
+  url.searchParams.set("ip", peer);
+  url.searchParams.set("update", "1");
+}
+
+function applyCacheUpdate(url: URL, cacheSpec: string | undefined): void {
+  if (!cacheSpec) return;
+  const cacheUrl = normalizeCacheUrl(cacheSpec);
+  if (!cacheUrl)
+    throw new Error(`invalid gwebcache cache update: ${cacheSpec}`);
+  url.searchParams.set("url", cacheUrl);
+  url.searchParams.set("update", "1");
+}
+
+function setOptionalCount(
+  url: URL,
+  key: string,
+  value: number | undefined,
+): void {
+  if (!Number.isInteger(value) || (value || 0) < 0) return;
+  url.searchParams.set(key, String(value));
+}
+
+function applyUpdateStats(
+  url: URL,
+  options: GWebCacheRequestOptions,
+): void {
+  setOptionalCount(url, "x_leaves", options.leafCount);
+  setOptionalCount(url, "x_max", options.maxLeaves);
+  setOptionalCount(url, "uptime", options.uptimeSec);
+}
+
+function applyLookupFlags(
+  url: URL,
+  options: GWebCacheRequestOptions,
+): void {
+  if (options.cluster?.trim()) {
+    url.searchParams.set("cluster", options.cluster.trim());
+  }
+  setGWebCacheFlag(url, "getleaves", options.getLeaves);
+  setGWebCacheFlag(url, "getclusters", options.getClusters);
+  setGWebCacheFlag(url, "getvendors", options.getVendors);
+  setGWebCacheFlag(url, "getuptime", options.getUptime);
+}
+
+export function buildGWebCacheUrl(
+  baseUrl: string,
+  options: GWebCacheRequestOptions = {},
+): string {
+  const normalizedBaseUrl = normalizeCacheUrl(baseUrl);
+  if (!normalizedBaseUrl)
+    throw new Error(`invalid gwebcache url: ${baseUrl}`);
+
+  const url = new URL(normalizedBaseUrl);
+  applyRequestMode(url, options);
+  applyRequestMetadata(url, options);
+  applyPeerUpdate(url, options.ip);
+  applyCacheUpdate(url, options.url);
+  applyUpdateStats(url, options);
+  applyLookupFlags(url, options);
+  return url.toString();
+}
+
+function createGWebCacheResponseState(): GWebCacheResponseState {
+  return {
+    peers: [],
+    caches: [],
+    warnings: [],
+    info: [],
+    hostEntries: [],
+    cacheEntries: [],
+    seenPeers: new Set<string>(),
+    seenCaches: new Set<string>(),
+    recognized: false,
+  };
+}
+
+function addResponsePeer(
+  state: GWebCacheResponseState,
+  value: string,
+  ageSec?: number,
+  cluster?: string,
+  leafCount?: number,
+  vendor?: string,
+  uptimeSec?: number,
+  extraFields: string[] = [],
+): void {
+  const peer = normalizeGWebCachePeer(value);
+  if (!peer || state.seenPeers.has(peer)) return;
+  state.seenPeers.add(peer);
+  state.peers.push(peer);
+  state.hostEntries.push({
+    peer,
+    ageSec,
+    cluster,
+    leafCount,
+    vendor,
+    uptimeSec,
+    extraFields,
+  });
+}
+
+function addResponseCache(
+  state: GWebCacheResponseState,
+  value: string,
+  ageSec?: number,
+): void {
+  const cacheUrl = normalizeCacheUrl(value);
+  if (!cacheUrl || state.seenCaches.has(cacheUrl)) return;
+  state.seenCaches.add(cacheUrl);
+  state.caches.push(cacheUrl);
+  state.cacheEntries.push({ url: cacheUrl, ageSec });
+}
+
+function applyPongInfo(
+  state: GWebCacheResponseState,
+  values: string[],
+): void {
+  state.pong = {
+    name: values[0] || "",
+    networks: parseNetworks(values[1]),
+  };
+}
+
+function applyUpdateInfo(
+  state: GWebCacheResponseState,
+  values: string[],
+): void {
+  state.update = buildUpdate(values);
+  if (state.update.warning) state.warnings.push(state.update.warning);
+}
+
+function applyWarningInfo(
+  state: GWebCacheResponseState,
+  values: string[],
+): void {
+  const warning = parseWarning(values);
+  if (warning) state.warnings.push(warning);
+}
+
+function parseInfoLineIntoState(
+  state: GWebCacheResponseState,
+  parts: string[],
+): void {
+  const key = parts[1]?.trim().toLowerCase() || "";
+  const values = parts.slice(2).map((value) => value.trim());
+  if (key === "pong") return applyPongInfo(state, values);
+  if (key === "update") return applyUpdateInfo(state, values);
+  if (key === "warning") return applyWarningInfo(state, values);
+  if (key) state.info.push({ key, values });
+}
+
+function parseHostLineIntoState(
+  state: GWebCacheResponseState,
+  parts: string[],
+): void {
+  const values = parts.slice(1).map((value) => value.trim());
+  addResponsePeer(
+    state,
+    values[0] || "",
+    parseAge(values[1]),
+    values[2] || undefined,
+    parseAge(values[3]),
+    values[4] || undefined,
+    parseAge(values[5]),
+    values.slice(6).filter(Boolean),
+  );
+}
+
+function parseCacheLineIntoState(
+  state: GWebCacheResponseState,
+  parts: string[],
+): void {
+  const values = parts.slice(1).map((value) => value.trim());
+  addResponseCache(state, values[0] || "", parseAge(values[1]));
+}
+
+function parseResponseLineIntoState(
+  state: GWebCacheResponseState,
+  line: string,
+): void {
+  const parts = line.split("|");
+  const code = parts[0]?.trim().toUpperCase();
+  if (code === "I") {
+    state.recognized = true;
+    parseInfoLineIntoState(state, parts);
+    return;
+  }
+  if (code === "H") {
+    state.recognized = true;
+    parseHostLineIntoState(state, parts);
+    return;
+  }
+  if (code === "U") {
+    state.recognized = true;
+    parseCacheLineIntoState(state, parts);
+  }
+}
+
+export function parseGWebCacheResponse(body: string): GWebCacheResponse {
+  const rawLines = splitBodyLines(body);
+  const state = createGWebCacheResponseState();
+  for (const line of rawLines) parseResponseLineIntoState(state, line);
+
+  return {
+    spec: state.recognized ? 2 : undefined,
+    rawLines,
+    peers: state.peers,
+    caches: state.caches,
+    warnings: [...new Set(state.warnings)],
+    info: state.info,
+    hostEntries: state.hostEntries,
+    cacheEntries: state.cacheEntries,
+    pong: state.pong,
+    update: state.update,
+  };
+}
+
+function combineSignals(
+  signal: AbortSignal | undefined,
+  timeoutMs: number,
+): {
+  signal?: AbortSignal;
+  cleanup: () => void;
+} {
+  if (!signal && !(timeoutMs > 0)) return { cleanup: () => void 0 };
+
+  const controller = new AbortController();
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const onAbort = () => controller.abort(signal?.reason);
+
+  if (signal) {
+    if (signal.aborted) controller.abort(signal.reason);
+    else signal.addEventListener("abort", onAbort, { once: true });
+  }
+
+  if (timeoutMs > 0) {
+    timeout = setTimeout(() => {
+      controller.abort(
+        new Error(`gwebcache request timed out after ${timeoutMs}ms`),
+      );
+    }, timeoutMs);
+  }
+
+  return {
+    signal: controller.signal,
+    cleanup: () => {
+      if (timeout) clearTimeout(timeout);
+      if (signal) signal.removeEventListener("abort", onAbort);
+    },
+  };
+}
+
+export async function requestGWebCache(
+  baseUrl: string,
+  options: GWebCacheRequestOptions = {},
+): Promise<GWebCacheHttpResponse> {
+  const requestUrl = buildGWebCacheUrl(baseUrl, options);
+  const timeoutMs = Math.max(0, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  const fetchImpl = options.fetchImpl || fetch;
+  const { signal, cleanup } = combineSignals(options.signal, timeoutMs);
+
+  try {
+    const response = await fetchImpl(requestUrl, {
+      method: "GET",
+      headers: {
+        Accept: "text/plain, text/*;q=0.9, */*;q=0.1",
+        "Cache-Control": "no-cache",
+        "User-Agent": DEFAULT_USER_AGENT,
+      },
+      signal,
+    });
+    const body = await response.text();
+    return {
+      requestUrl,
+      body,
+      status: response.status,
+      statusText: response.statusText,
+      ok: response.ok,
+      ...parseGWebCacheResponse(body),
+    };
+  } finally {
+    cleanup();
+  }
+}

package/src/gwebcache/shared.ts

@@ -0,0 +1,116 @@
+import { DEFAULT_USER_AGENT, DEFAULT_VENDOR_CODE } from "../const";
+import {
+  isRoutableIpv4,
+  normalizePeer,
+  parsePeer,
+  unique,
+} from "../shared";
+import { KNOWN_CACHES, type GWebCacheBootstrapState } from "./types";
+
+export const DEFAULT_TIMEOUT_MS = 5000;
+export const DEFAULT_MAX_PEERS = 20;
+export const DEFAULT_MAX_CACHES = 20;
+export const DEFAULT_MAX_BOOTSTRAP_PEERS = 4096;
+export const DEFAULT_MAX_BOOTSTRAP_CACHES = 256;
+
+export function normalizeCacheUrl(value: string): string | undefined {
+  const trimmed = String(value || "").trim();
+  if (!trimmed) return undefined;
+  try {
+    const url = new URL(trimmed);
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+      return undefined;
+    url.hash = "";
+    return url.toString();
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeCacheList(caches: readonly string[] = []): string[] {
+  return unique(
+    [...caches]
+      .map((cache) => normalizeCacheUrl(cache))
+      .filter((cache): cache is string => !!cache),
+  );
+}
+
+export function seedCacheList(caches?: readonly string[]): string[] {
+  return normalizeCacheList(caches?.length ? [...caches] : KNOWN_CACHES);
+}
+
+export function aliveCachesForState(
+  state: GWebCacheBootstrapState | undefined,
+): string[] {
+  return normalizeCacheList(state?.aliveCaches);
+}
+
+export function rememberAliveCaches(
+  state: GWebCacheBootstrapState | undefined,
+  caches: readonly string[],
+): void {
+  if (!state) return;
+  state.aliveCaches = normalizeCacheList([
+    ...aliveCachesForState(state),
+    ...caches,
+  ]);
+}
+
+export function sanitizeClient(value: string | undefined): string {
+  const client = String(value || DEFAULT_VENDOR_CODE)
+    .trim()
+    .toUpperCase();
+  return client.slice(0, 4) || DEFAULT_VENDOR_CODE;
+}
+
+export function sanitizeVersion(value: string | undefined): string {
+  const version = String(value || DEFAULT_USER_AGENT).trim();
+  return version || DEFAULT_USER_AGENT;
+}
+
+export function normalizeNetwork(
+  value: string | undefined,
+): "gnutella" | "gnutella2" {
+  const network = String(value || "gnutella")
+    .trim()
+    .toLowerCase();
+  if (network === "gnutella" || network === "gnutella2") return network;
+  throw new Error(`unsupported gwebcache network: ${value}`);
+}
+
+export function normalizeGWebCachePeer(value: string): string | undefined {
+  const parsed = parsePeer(value);
+  if (!parsed) return undefined;
+  if (!isRoutableIpv4(parsed.host)) return undefined;
+  return normalizePeer(parsed.host, parsed.port);
+}
+
+export function parseAge(value: string | undefined): number | undefined {
+  if (value == null || value === "") return undefined;
+  const age = Number(value);
+  return Number.isInteger(age) && age >= 0 ? age : undefined;
+}
+
+export function parseWarning(values: string[]): string | undefined {
+  const warning = values.join("|").trim();
+  return warning || undefined;
+}
+
+export function parseNetworks(value: string | undefined): string[] {
+  if (!value) return [];
+  return unique(
+    value
+      .split("-")
+      .map((part) => part.trim())
+      .filter(Boolean),
+  );
+}
+
+export function splitBodyLines(body: string): string[] {
+  return body
+    .replace(/^\uFEFF/, "")
+    .replace(/\r\n/g, "\n")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}

package/src/gwebcache/types.ts

@@ -0,0 +1,187 @@
+type GWebCacheMode = "get" | "update";
+
+type FetchLike = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export type GWebCacheRequestOptions = {
+  mode?: GWebCacheMode;
+  network?: "gnutella" | "gnutella2";
+  client?: string;
+  version?: string;
+  ping?: boolean;
+  spec?: 2;
+  ip?: string;
+  url?: string;
+  cluster?: string;
+  leafCount?: number;
+  maxLeaves?: number;
+  uptimeSec?: number;
+  getLeaves?: boolean;
+  getClusters?: boolean;
+  getVendors?: boolean;
+  getUptime?: boolean;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  fetchImpl?: FetchLike;
+};
+
+export type GWebCacheInfoLine = {
+  key: string;
+  values: string[];
+};
+
+export type GWebCachePong = {
+  name: string;
+  networks: string[];
+};
+
+export type GWebCacheUpdate = {
+  ok: boolean;
+  warning?: string;
+  values: string[];
+};
+
+export type GWebCacheHostEntry = {
+  peer: string;
+  ageSec?: number;
+  cluster?: string;
+  leafCount?: number;
+  vendor?: string;
+  uptimeSec?: number;
+  extraFields: string[];
+};
+
+export type GWebCacheCacheEntry = {
+  url: string;
+  ageSec?: number;
+};
+
+export type GWebCacheResponse = {
+  spec?: 2;
+  rawLines: string[];
+  peers: string[];
+  caches: string[];
+  warnings: string[];
+  info: GWebCacheInfoLine[];
+  hostEntries: GWebCacheHostEntry[];
+  cacheEntries: GWebCacheCacheEntry[];
+  pong?: GWebCachePong;
+  update?: GWebCacheUpdate;
+};
+
+export type GWebCacheHttpResponse = GWebCacheResponse & {
+  requestUrl: string;
+  body: string;
+  status: number;
+  statusText: string;
+  ok: boolean;
+};
+
+export type BootstrapOptions = {
+  caches?: readonly string[];
+  client?: string;
+  version?: string;
+  network?: "gnutella" | "gnutella2";
+  timeoutMs?: number;
+  maxPeers?: number;
+  maxCaches?: number;
+  queryAll?: boolean;
+  signal?: AbortSignal;
+  fetchImpl?: FetchLike;
+};
+
+export type BootstrapResult = {
+  peers: string[];
+  caches: string[];
+  queriedCaches: string[];
+  successfulCaches: string[];
+  errors: Array<{
+    cache: string;
+    message: string;
+  }>;
+};
+
+export type BootstrapPeer = {
+  host: string;
+  port: number;
+  peer: string;
+};
+
+export type GWebCacheBootstrapState = {
+  active?: boolean;
+  lastExhaustedPeerSet?: string;
+  aliveCaches?: string[];
+};
+
+export type ConnectBootstrapOptions = BootstrapOptions & {
+  peers: readonly string[];
+  connectTimeoutMs: number;
+  connectConcurrency: number;
+  connectedCount: () => number;
+  availableSlots: () => number;
+  connectPeer: (
+    host: string,
+    port: number,
+    timeoutMs: number,
+  ) => Promise<void>;
+  addPeer?: (peer: string) => void;
+  isSelfPeer?: (host: string, port: number) => boolean;
+  maxBootstrapPeers?: number;
+  maxBootstrapCaches?: number;
+  state?: GWebCacheBootstrapState;
+};
+
+export type ConnectBootstrapResult = {
+  attemptedPeers: string[];
+  fetchedFromCaches: boolean;
+  addedPeers: string[];
+  queriedCaches: string[];
+  errors: BootstrapResult["errors"];
+};
+
+export type ReportSelfOptions = {
+  caches?: readonly string[];
+  client?: string;
+  version?: string;
+  timeoutMs?: number;
+  ip: string;
+  cluster?: string;
+  leafCount?: number;
+  maxLeaves?: number;
+  uptimeSec?: number;
+  state?: GWebCacheBootstrapState;
+  signal?: AbortSignal;
+  fetchImpl?: FetchLike;
+};
+
+export type ReportSelfResult = {
+  referenceCache?: string;
+  attemptedCaches: string[];
+  reportedCaches: string[];
+  errors: BootstrapResult["errors"];
+};
+
+export const KNOWN_CACHES = [
+  "http://bj.ddns.net/beacon/gwc.php",
+  "http://bj.ddns.net/cachechu/",
+  "http://bj.ddns.net/gnucache/gcache.php",
+  "http://bj.ddns.net/gwebcache/gcache.php",
+  "http://bj.ddns.net/perlcache/perlgcache.cgi",
+  "http://bj.ddns.net/phpgnucacheii/gwcii.php",
+  "http://bj.ddns.net/skulls/skulls.php",
+  "http://cache.jayl.de/g2/gwc.php/",
+  "http://cache.trillinux.org/g2/bazooka.php",
+  "http://dkac.trillinux.org/dkac/dkac.php/",
+  "http://fascination77.free.fr/cachechu/",
+  "http://gweb3.4octets.co.uk/gwc.php",
+  "http://gweb4.4octets.co.uk/index.php",
+  "http://midian.jayl.de/g2/bazooka.php",
+  "http://p2p.findclan.net/skulls.php",
+  "http://skulls.gwc.dyslexicfish.net/skulls.php",
+  "http://www.paper.gwc.dyslexicfish.net/",
+  "http://www.rock.gwc.dyslexicfish.net/",
+  "http://www.scissors.gwc.dyslexicfish.net/",
+  "https://www.paper.gwc.dyslexicfish.net/",
+] as const;

package/src/gwebcache_client.ts

@@ -0,0 +1,13 @@
+export {
+  connectBootstrapPeers,
+  fetchBootstrapData,
+  getMorePeers,
+  reportSelfToGWebCaches,
+} from "./gwebcache/bootstrap";
+export {
+  buildGWebCacheUrl,
+  parseGWebCacheResponse,
+  requestGWebCache,
+} from "./gwebcache/response";
+export { KNOWN_CACHES } from "./gwebcache/types";
+export type { GWebCacheBootstrapState } from "./gwebcache/types";