gnutella 1.0.0 → 1.1.0

package/CLI.md

@@ -61,6 +61,7 @@ GnutellaBun keeps both settings and remembered state in the same JSON file.
 | `config.ultrapeer`                 | Set `true` if you want GnutellaBun to behave like a larger relay-style node. Leave `false` for a lighter client.                                          |
 | `config.max_ultrapeer_connections` | Cap for ultrapeer-to-ultrapeer links.                                                                                                                     |
 | `config.max_leaf_connections`      | Cap for leaf links.                                                                                                                                       |
+| `config.max_ttl`                   | Maximum descriptor TTL to advertise and relay. Defaults to `4`.                                                                                           |
 | `config.log_ignore`                | Event categories to hide when `monitor` is enabled.                                                                                                       |
 
 ### Saved State

package/gnutella.json.example

@@ -6,6 +6,7 @@
     "ultrapeer": false,
     "max_ultrapeer_connections": 64,
     "max_leaf_connections": 64,
+    "max_ttl": 4,
     "log_ignore": [],
     "data_dir": "."
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gnutella",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "GnutellaBun is a small Gnutella client for Bun, usable as a CLI or TypeScript library.",
   "license": "GPL-3.0-only",
   "bin": {
@@ -11,7 +11,8 @@
   "exports": {
     ".": "./src/protocol.ts",
     "./types": "./src/types.ts",
-    "./gwebcache": "./src/gwebcache_client.ts"
+    "./gwebcache": "./src/gwebcache_client.ts",
+    "./query-routing": "./src/query_routing/index.ts"
   },
   "files": [
     "bin",
@@ -65,7 +66,7 @@
     "test:integration": "bun test tests/integration/protocol.test.ts",
     "test:unit": "bun test tests/unit",
     "typecheck": "tsc --noEmit",
-    "unused-exports": "ts-unused-exports tsconfig.json --excludePathsFromReport=src/protocol.ts --exitWithCount",
+    "unused-exports": "ts-unused-exports tsconfig.json \"--excludePathsFromReport=src/protocol.ts;src/query_routing/index.ts\" --exitWithCount",
     "fix": "./scripts/fix-all.sh",
     "verify": "./scripts/verify-all.sh"
   }

package/src/cli_shared.ts

@@ -1,18 +1,22 @@
 import { errMsg } from "./shared";
-import { RESULT_NAME_WIDTH_MAX } from "./const";
 import type { CliNode, ParsedCli } from "./types";
 import { buildMagnetUri } from "./protocol/magnet";
 
 const SIZE_FORMAT = new Intl.NumberFormat("en-US", {
+  minimumFractionDigits: 1,
   maximumFractionDigits: 1,
+  useGrouping: false,
 });
-const SIZE_UNITS = ["B", "KB", "MB", "GB", "TB", "PB"];
+const SIZE_UNITS = ["b", "kb", "mb", "gb", "tb", "pb"];
+const SIZE_VALUE_WIDTH = 5;
+const SIZE_UNIT_WIDTH = 2;
 const RESULT_COUNT_DISPLAY_MAX = 999;
 const PEER_TABLE_WIDTH_MAX = 80;
 
 type ResultInfo = ReturnType<CliNode["getResults"]>[number];
+type FormattedSize = { value: string; unit: string };
 
-function formatSize(bytes: number): string {
+function formattedSize(bytes: number): FormattedSize {
   const safeBytes =
     Number.isFinite(bytes) && bytes > 0 ? Math.floor(bytes) : 0;
   let value = safeBytes;
@@ -21,7 +25,20 @@ function formatSize(bytes: number): string {
     value /= 1024;
     unitIndex++;
   }
-  return `${SIZE_FORMAT.format(value)}${SIZE_UNITS[unitIndex]}`;
+  return {
+    value: unitIndex === 0 ? String(value) : SIZE_FORMAT.format(value),
+    unit: SIZE_UNITS[unitIndex],
+  };
+}
+
+function formatSize(bytes: number): string {
+  const size = formattedSize(bytes);
+  return `${size.value} ${size.unit}`;
+}
+
+function formatResultSize(bytes: number): string {
+  const size = formattedSize(bytes);
+  return `${size.value.padStart(SIZE_VALUE_WIDTH, " ")} ${size.unit.padEnd(SIZE_UNIT_WIDTH, " ")}`;
 }
 
 export function displayResultCount(count: number): number {
@@ -234,19 +251,12 @@ export function printResults(
   const rows = [...results]
     .sort(
       (a, b) =>
-        a.resultNo - b.resultNo ||
-        a.fileName.localeCompare(b.fileName) ||
-        a.fileSize - b.fileSize ||
-        a.remoteHost.localeCompare(b.remoteHost) ||
-        a.remotePort - b.remotePort,
+        a.resultNo - b.resultNo || a.fileName.localeCompare(b.fileName),
     )
     .map((result) => ({
       resultNo: String(result.resultNo),
+      fileSize: formatResultSize(result.fileSize),
       fileName: sanitizeTableCell(result.fileName),
-      fileSize: formatSize(result.fileSize),
-      remote: sanitizeTableCell(
-        `${result.remoteHost}:${result.remotePort}`,
-      ),
     }));
 
   const widths = {
@@ -254,49 +264,28 @@ export function printResults(
       "No".length,
       ...rows.map((row) => row.resultNo.length),
     ),
-    fileName: RESULT_NAME_WIDTH_MAX,
     fileSize: Math.max(
       "Size".length,
       ...rows.map((row) => row.fileSize.length),
     ),
-    remote: Math.max("IP".length, ...rows.map((row) => row.remote.length)),
+    fileName: Math.max(
+      "File".length,
+      ...rows.map((row) => row.fileName.length),
+    ),
   };
 
-  const line = (
-    resultNo: string,
-    fileName: string,
-    fileSize: string,
-    remote: string,
-  ) =>
-    `${resultNo.padStart(widths.resultNo, " ")}  ${fileName}  ${fileSize.padStart(widths.fileSize, " ")}  ${remote}`.trimEnd();
-
-  const fitName = (fileName: string): string => {
-    if (fileName.length <= widths.fileName - 2)
-      return fileName.padEnd(widths.fileName, " ");
-    if (widths.fileName <= 2) return fileName.slice(0, widths.fileName);
-    const kept = widths.fileName - 2;
-    const head = Math.floor(kept / 2);
-    const tail = kept - head;
-    return `${fileName.slice(0, head)}..${fileName.slice(-tail)}`;
-  };
+  const line = (resultNo: string, fileSize: string, fileName: string) =>
+    `${resultNo.padStart(widths.resultNo, " ")}  ${fileSize.padStart(widths.fileSize, " ")}  ${fileName.padEnd(widths.fileName, " ")}`.trimEnd();
 
   log(
     [
-      line("No", "File".padEnd(widths.fileName, " "), "Size", "IP"),
+      line("No", "Size", "File"),
       line(
         "-".repeat(widths.resultNo),
-        "-".repeat(widths.fileName),
         "-".repeat(widths.fileSize),
-        "-".repeat(widths.remote),
-      ),
-      ...rows.map((row) =>
-        line(
-          row.resultNo,
-          fitName(row.fileName),
-          row.fileSize,
-          row.remote,
-        ),
+        "-".repeat(widths.fileName),
       ),
+      ...rows.map((row) => line(row.resultNo, row.fileSize, row.fileName)),
     ].join("\n"),
   );
 }

package/src/const.ts

@@ -1,8 +1,5 @@
 export const HEADER_LEN = 23;
 export const LOCAL_ROUTE = "__local__";
-export const DEFAULT_QRP_TABLE_SIZE = 65536;
-export const DEFAULT_QRP_INFINITY = 7;
-export const DEFAULT_QRP_ENTRY_BITS = 1;
 export const DEFAULT_LISTEN_HOST = "0.0.0.0";
 export const DEFAULT_LISTEN_PORT_MIN = 20000;
 export const DEFAULT_LISTEN_PORT_MAX = 29999;
@@ -18,7 +15,7 @@ export const RESCAN_SHARES_SEC = 30;
 export const ROUTE_TTL_SEC = 600;
 export const SEEN_TTL_SEC = 600;
 export const MAX_PAYLOAD_BYTES = 1024 * 1024;
-export const MAX_TTL = 7;
+export const MAX_TTL = 4;
 export const DEFAULT_PING_TTL = 1;
 export const DEFAULT_QUERY_TTL = 4;
 export const ADVERTISED_SPEED_KBPS = 512;
@@ -37,8 +34,6 @@ export const ENABLE_BYE = true;
 export const ENABLE_PONG_CACHING = true;
 export const ENABLE_GGEP = true;
 export const SERVE_URI_RES = true;
-export const QRP_COMPRESSOR_NONE = 0;
-export const QRP_COMPRESSOR_DEFLATE = 1;
 export const MAX_XTRY = 10;
 export const BYE_DEFAULT_CODE = 200;
 export const BOOTSTRAP_CONNECT_CONCURRENCY = 8;
@@ -104,7 +99,6 @@ export const INTERESTING_HANDSHAKE_HEADERS = [
   "remote-ip",
 ] as const;
 
-export const QRP_HASH_MULTIPLIER = 0x4f1bbcdc;
 export const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
 
 export const PROMPT_THROBBER_FRAMES = ["*", "o", ".", " "] as const;
@@ -134,5 +128,3 @@ export const CLI_HELP_LINES = [
   "quit",
   "sleep",
 ] as const;
-
-export const RESULT_NAME_WIDTH_MAX = 48;

package/src/descriptor_routing/index.ts

@@ -0,0 +1,17 @@
+export {
+  overflowPongCacheKeys,
+  pongCacheKey,
+  selectCachedPongPayloads,
+} from "./pong_cache";
+export { responseRouteDecision } from "./response_routes";
+export {
+  shouldMarkDescriptorSeen,
+  shouldSuppressDescriptor,
+} from "./seen";
+export {
+  forwardedDescriptorLifetime,
+  normalizeQueryLifetime,
+  pongReplyTtl,
+  queryHitReplyTtl,
+  shouldRelayPing,
+} from "./ttl";

package/src/descriptor_routing/pong_cache.ts

@@ -0,0 +1,32 @@
+import crypto from "node:crypto";
+
+import type { PongCacheEntry } from "./types";
+
+export function pongCacheKey(payload: Buffer): string {
+  return crypto.createHash("sha1").update(payload).digest("hex");
+}
+
+export function overflowPongCacheKeys(
+  entries: Iterable<[string, Pick<PongCacheEntry, "at">]>,
+  maxSize: number,
+): string[] {
+  const all = [...entries];
+  if (all.length <= maxSize) return [];
+  return all
+    .sort((a, b) => a[1].at - b[1].at)
+    .slice(0, all.length - maxSize)
+    .map(([key]) => key);
+}
+
+export function selectCachedPongPayloads(
+  entries: Iterable<PongCacheEntry>,
+  alreadySent: number,
+  maxSent: number,
+): Buffer[] {
+  const available = Math.max(0, maxSent - alreadySent);
+  if (available === 0) return [];
+  return [...entries]
+    .sort((a, b) => b.at - a.at)
+    .slice(0, available)
+    .map((entry) => entry.payload);
+}

package/src/descriptor_routing/response_routes.ts

@@ -0,0 +1,15 @@
+import { LOCAL_ROUTE } from "../const";
+import type { Route } from "../types";
+import type { ResponseRouteDecision, ResponseRouteOptions } from "./types";
+
+export function responseRouteDecision(
+  route: Route | typeof LOCAL_ROUTE | undefined,
+  options: ResponseRouteOptions = {},
+): ResponseRouteDecision {
+  if (!route) return { kind: "drop" };
+  if (route === LOCAL_ROUTE) return { kind: "local" };
+  if (options.nodeMode === "leaf" && !options.forwardInLeaf) {
+    return { kind: "drop" };
+  }
+  return { kind: "forward", route };
+}

package/src/descriptor_routing/seen.ts

@@ -0,0 +1,20 @@
+import { TYPE } from "../const";
+import type { DescriptorSuppressionInput } from "./types";
+
+export function shouldSuppressDescriptor(
+  input: DescriptorSuppressionInput,
+): boolean {
+  if (
+    input.closingAfterBye &&
+    input.payloadType !== TYPE.QUERY_HIT &&
+    input.payloadType !== TYPE.PUSH
+  ) {
+    return true;
+  }
+  if (input.payloadType === TYPE.ROUTE_TABLE_UPDATE) return false;
+  return input.alreadySeen;
+}
+
+export function shouldMarkDescriptorSeen(payloadType: number): boolean {
+  return payloadType !== TYPE.ROUTE_TABLE_UPDATE;
+}

package/src/descriptor_routing/ttl.ts

@@ -0,0 +1,37 @@
+import type { DescriptorLifetime } from "./types";
+
+export function normalizeQueryLifetime(
+  ttl: number,
+  hops: number,
+  maxTtl: number,
+): DescriptorLifetime | null {
+  if (ttl > 15) return null;
+  const maxLife = Math.max(1, maxTtl);
+  if (hops > maxLife) return null;
+  return { ttl: Math.max(0, Math.min(ttl, maxLife - hops)), hops };
+}
+
+export function forwardedDescriptorLifetime(
+  ttl: number,
+  hops: number,
+): DescriptorLifetime | undefined {
+  if (ttl <= 0) return undefined;
+  return { ttl: Math.max(0, ttl - 1), hops: hops + 1 };
+}
+
+export function pongReplyTtl(hops: number): number {
+  return Math.max(1, hops);
+}
+
+export function queryHitReplyTtl(hops: number, maxTtl: number): number {
+  return Math.min(maxTtl, Math.max(1, hops + 2));
+}
+
+export function shouldRelayPing(
+  ttl: number,
+  now: number,
+  lastPingAt: number,
+  minIntervalMs: number,
+): boolean {
+  return ttl > 1 && now - lastPingAt >= minIntervalMs;
+}

package/src/descriptor_routing/types.ts

@@ -0,0 +1,27 @@
+import type { Route, RuntimeConfig } from "../types";
+
+export type DescriptorLifetime = {
+  ttl: number;
+  hops: number;
+};
+
+export type DescriptorSuppressionInput = {
+  closingAfterBye: boolean;
+  payloadType: number;
+  alreadySeen: boolean;
+};
+
+export type ResponseRouteOptions = {
+  nodeMode?: RuntimeConfig["nodeMode"];
+  forwardInLeaf?: boolean;
+};
+
+export type ResponseRouteDecision =
+  | { kind: "drop" }
+  | { kind: "local" }
+  | { kind: "forward"; route: Route };
+
+export type PongCacheEntry = {
+  payload: Buffer;
+  at: number;
+};

package/src/gwebcache/bootstrap.ts

@@ -1,4 +1,9 @@
-import { normalizePeer, parsePeer } from "../shared";
+import {
+  addPeerCandidatesToKnownSet,
+  normalizePeerCandidates,
+  peerCandidateSetKey,
+  shouldFetchFreshPeerCandidates,
+} from "../peer_discovery";
 import {
   DEFAULT_MAX_BOOTSTRAP_CACHES,
   DEFAULT_MAX_BOOTSTRAP_PEERS,
@@ -16,7 +21,6 @@ import {
 } from "./response";
 import type {
   BootstrapOptions,
-  BootstrapPeer,
   BootstrapResult,
   ConnectBootstrapOptions,
   ConnectBootstrapResult,
@@ -27,38 +31,6 @@ import type {
   ReportSelfResult,
 } from "./types";
 
-function normalizeBootstrapPeers(
-  peers: readonly string[],
-  isSelfPeer?: (host: string, port: number) => boolean,
-): BootstrapPeer[] {
-  const out: BootstrapPeer[] = [];
-  const seen = new Set<string>();
-
-  for (const peer of peers) {
-    const parsed = parsePeer(peer);
-    if (!parsed) continue;
-    if (isSelfPeer?.(parsed.host, parsed.port)) continue;
-
-    const normalized = normalizePeer(parsed.host, parsed.port);
-    if (seen.has(normalized)) continue;
-    seen.add(normalized);
-    out.push({
-      host: parsed.host,
-      port: parsed.port,
-      peer: normalized,
-    });
-  }
-
-  return out;
-}
-
-function bootstrapPeerSetKey(peers: BootstrapPeer[]): string {
-  return peers
-    .map((peer) => peer.peer)
-    .sort((a, b) => a.localeCompare(b))
-    .join(",");
-}
-
 function buildReportReferenceUrl(
   cache: string,
   knownAliveCaches: readonly string[],
@@ -117,25 +89,18 @@ function emptyConnectBootstrapResult(
   };
 }
 
-function exhaustedBootstrapPeerSet(
-  candidates: BootstrapPeer[],
-  initialAttempt: Awaited<ReturnType<typeof connectBootstrapPeerSet>>,
-): boolean {
-  return (
-    candidates.length === 0 ||
-    initialAttempt.attemptedPeers.length >= candidates.length
-  );
-}
-
 function shouldSkipCacheBootstrap(
-  candidates: BootstrapPeer[],
+  candidates: ReturnType<typeof normalizePeerCandidates>,
   initialAttempt: Awaited<ReturnType<typeof connectBootstrapPeerSet>>,
   candidateKey: string,
   state: GWebCacheBootstrapState | undefined,
 ): boolean {
-  if (!exhaustedBootstrapPeerSet(candidates, initialAttempt)) return true;
-  if (state?.active) return true;
-  return state?.lastExhaustedPeerSet === candidateKey;
+  return !shouldFetchFreshPeerCandidates({
+    candidates,
+    initialAttempt,
+    candidateKey,
+    state,
+  });
 }
 
 function buildBootstrapFetchOptions(
@@ -156,15 +121,13 @@ function buildBootstrapFetchOptions(
 }
 
 function addDiscoveredBootstrapPeers(
-  peers: BootstrapPeer[],
+  peers: ReturnType<typeof normalizePeerCandidates>,
   knownPeers: Set<string>,
   addPeer: ConnectBootstrapOptions["addPeer"],
 ): string[] {
-  const addedPeers: string[] = [];
-  for (const peer of peers) {
-    knownPeers.add(peer.peer);
-    addedPeers.push(peer.peer);
-    addPeer?.(peer.peer);
+  const addedPeers = addPeerCandidatesToKnownSet(peers, knownPeers);
+  for (const peer of addedPeers) {
+    addPeer?.(peer);
   }
   return addedPeers;
 }
@@ -182,7 +145,7 @@ async function fetchAndRetryBootstrapPeers(
     buildBootstrapFetchOptions(options),
   );
   rememberAliveCaches(options.state, bootstrap.successfulCaches);
-  const discovered = normalizeBootstrapPeers(
+  const discovered = normalizePeerCandidates(
     bootstrap.peers,
     options.isSelfPeer,
   ).filter((peer) => !knownPeers.has(peer.peer));
@@ -200,7 +163,7 @@ async function fetchAndRetryBootstrapPeers(
 }
 
 async function connectBootstrapPeerSet(
-  peers: BootstrapPeer[],
+  peers: ReturnType<typeof normalizePeerCandidates>,
   options: Pick<
     ConnectBootstrapOptions,
     | "availableSlots"
@@ -433,11 +396,11 @@ function finishCacheBootstrap(
 export async function connectBootstrapPeers(
   options: ConnectBootstrapOptions,
 ): Promise<ConnectBootstrapResult> {
-  const candidates = normalizeBootstrapPeers(
+  const candidates = normalizePeerCandidates(
     options.peers,
     options.isSelfPeer,
   );
-  const candidateKey = bootstrapPeerSetKey(candidates);
+  const candidateKey = peerCandidateSetKey(candidates);
   const knownPeers = new Set(candidates.map((peer) => peer.peer));
   const initialAttempt = await connectBootstrapPeerSet(
     candidates,

package/src/gwebcache/types.ts

@@ -92,21 +92,17 @@ export type BootstrapOptions = {
   fetchImpl?: FetchLike;
 };
 
+type BootstrapCacheError = {
+  cache: string;
+  message: string;
+};
+
 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;
+  errors: BootstrapCacheError[];
 };
 
 export type GWebCacheBootstrapState = {

package/src/handshake_policy/admission.ts

@@ -0,0 +1,17 @@
+import { lowerCaseHeaders, parseRemoteIpHeader } from "./headers";
+import type { RejectHandshakePolicy } from "./types";
+
+export function buildRejectHeaders(
+  policy: RejectHandshakePolicy,
+): Record<string, string> {
+  const headers = lowerCaseHeaders(policy.extraHeaders || {});
+  const observedRemote = parseRemoteIpHeader(policy.remoteIp);
+  const tryPeers = policy.tryPeers || [];
+  if (observedRemote) headers["remote-ip"] = observedRemote;
+  if (tryPeers.length) {
+    const value = tryPeers.join(",");
+    headers["x-try"] = value;
+    headers["x-try-ultrapeers"] = value;
+  }
+  return headers;
+}