hyper-http-fetch 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mauve Signweaver
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# hyper-http-fetch
+
+Use the fetch API to access HTTP servers exposed by hypertele.
+
+## Install
+
+```bash
+npm install hyper-http-fetch
+```
+
+## Usage
+
+### Client: Making requests
+
+Import `makeHyperHTTPFetch` to get a `fetch`-compatible function for requesting `hyper+http://` URLs:
+
+```js
+import makeHyperHTTPFetch from "hyper-http-fetch";
+
+const fetch = await makeHyperHTTPFetch({
+  bootstrap: ["list", "of", "dht", "nodes"], // optional DHT options
+});
+
+const res = await fetch("hyper+http://${z32 encoded public key}/path");
+console.log(res.ok);
+console.log(await res.text());
+
+// Clean up when done
+fetch.close();
+```
+
+You can also pass an existing `HyperDHT` instance instead of options:
+
+```js
+import HyperDHT from "hyperdht";
+import makeHyperHTTPFetch from "hyper-http-fetch";
+
+const dht = new HyperDHT();
+const fetch = await makeHyperHTTPFetch(dht);
+
+const res = await fetch("hyper+http://...");
+```
+
+A `Request` object can also be passed as the first argument:
+
+```js
+const res = await fetch(
+  new Request("hyper+http://.../path", { method: "POST", body: JSON.stringify({ hello: true }) })
+);
+```
+
+### Server: Exposing an HTTP server over the DHT
+
+Import `./server` to create an HTTP server accessible via `hyper+http://`:
+
+```js
+import createServer from "hyper-http-fetch/server";
+
+const server = await createServer((req) => {
+  return new Response("Hello World");
+});
+
+console.log(server.url); // e.g. "hyper+http://abcdef123.../"
+```
+
+The returned server object has:
+
+- **`url`** — the `hyper+http://` URL clients can use to reach this server
+- **`keyPair`** — `{ publicKey, privateKey }` used for the DHT identity
+- **`destroy()`** — shut down the server and clean up
+
+You can pass optional configuration:
+
+```js
+const server = await createServer(
+  (req) => new Response(req.url),
+  {
+    dht: { bootstrap: ["my.dht.peer:2000"] },
+    seed: crypto.randomBytes(32), // optional, for deterministic keys
+  }
+);
+```

package/eslint.config.js

@@ -0,0 +1,6 @@
+import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended";
+
+export default [
+  // Any other config imports go at the top
+  eslintPluginPrettierRecommended,
+];

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "hyper-http-fetch",
+  "version": "1.0.0",
+  "description": "Use the fetch API to access HTTP servers exposed by hypertele.",
+  "keywords": [
+    "http",
+    "p2p",
+    "fetch",
+    "hyperswarm"
+  ],
+  "homepage": "https://github.com/RangerMauve/hyper-http-fetch#readme",
+  "bugs": {
+    "url": "https://github.com/RangerMauve/hyper-http-fetch/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RangerMauve/hyper-http-fetch.git"
+  },
+  "license": "MIT",
+  "author": "RangerMauve",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "types":"./dist/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./src/server.js"
+    }
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint --fix && tsc"
+  },
+  "dependencies": {
+    "hypercore-id-encoding": "^1.3.0",
+    "hyperdht": "^6.32.0",
+    "undici": "^8.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "eslint": "^10.4.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.6",
+    "hypertele": "^1.1.4",
+    "prettier": "^3.8.3",
+    "typescript": "^6.0.3"
+  }
+}

package/src/index.js

@@ -0,0 +1,60 @@
+import {
+  Request,
+  Response,
+  Agent as UndiciAgent,
+  fetch as undiciFetch,
+} from "undici";
+// @ts-ignore
+import HyperDHT from "hyperdht";
+// @ts-ignore
+import idEncoding from "hypercore-id-encoding";
+
+export default async function makeHyperHTTPFetch(options = {}) {
+  const dht = options instanceof HyperDHT ? options : new HyperDHT(options);
+
+  await dht.fullyBootstrapped();
+
+  const agent = new UndiciAgent({
+    connect: ({ hostname }, cb) => {
+      const publicKey = idEncoding.decode(hostname);
+
+      const stream = dht.connect(publicKey, {
+        reusableSocket: true,
+      });
+
+      cb(null, stream);
+
+      stream.on("error", cb);
+      stream.on("open", () => {
+        stream.removeListener("error", cb);
+        cb(null, stream);
+      });
+    },
+  });
+
+  hyperHttpFetch.close = () => dht.destroy();
+  return hyperHttpFetch;
+
+  /**
+   * @param {string|Request} resource
+   * @param {import("undici").RequestInit} [options]
+   * @returns {Promise<Response>}
+   */
+  async function hyperHttpFetch(resource, options = {}) {
+    const isPlainResource = typeof resource === "string";
+    const url = isPlainResource ? resource : resource.url;
+
+    let finalOptions = options;
+
+    if (!isPlainResource) {
+      finalOptions.method = resource.method;
+      finalOptions.headers = resource.headers;
+      finalOptions.body = resource.body;
+    }
+
+    return undiciFetch(url.replace("hyper+http:", "http:"), {
+      ...finalOptions,
+      dispatcher: agent,
+    });
+  }
+}

package/src/server.js

@@ -0,0 +1,102 @@
+// @ts-ignore
+import HyperDHT from "hyperdht";
+// @ts-ignore
+import idEncoding from "hypercore-id-encoding";
+import { randomBytes } from "node:crypto";
+import http from "node:http";
+import { Duplex, Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+const SKIP_BODY_METHODS = new Set(["GET", "HEAD"]);
+
+/**
+ * @typedef {(request: Request) => Response|Promise<Response>} HyperRequestListener
+ */
+
+/**
+ * @typedef {object} HyperServerOptions
+ * @property {HyperDHT|ConstructorParameters<typeof HyperDHT>[0]} [dht]
+ * @property {Buffer|Uint8Array} [seed]
+ */
+
+/**
+ * @typedef {object} HyperServer
+ * @property {string} url
+ * @property {{publicKey: Buffer, privateKey: Buffer}} keyPair
+ * @property {() => Promise<void>} destroy
+ */
+
+/**
+ * Initialize an HTTP server for serving hyper+http requests
+ * @param {HyperRequestListener} onRequest
+ * @param {HyperServerOptions} [options]
+ * @returns {Promise<HyperServer>}
+ */
+export default async function createServer(
+  onRequest,
+  { dht: dhtOptions, seed = randomBytes(32) } = {},
+) {
+  const keyPair = HyperDHT.keyPair(seed);
+
+  const url = `hyper+http://${idEncoding.encode(keyPair.publicKey)}/`;
+
+  // start local http server
+  const httpServer = http.createServer(handleRawRequest);
+
+  /** @type {import("node:http").RequestListener} */
+  async function handleRawRequest(req, res) {
+    try {
+      const full = new URL(req.url ?? "/", url).href;
+      const method = req.method ?? "GET";
+      const request = new Request(full, {
+        // @ts-ignore It's OK, just TS being weird
+        headers: req.headers,
+        method: req.method,
+        // @ts-ignore Exists in newer node versions
+        signal: req.signal,
+        // @ts-ignore It's OK, just TS being weird
+        body: SKIP_BODY_METHODS.has(method) ? null : Readable.toWeb(req),
+      });
+
+      const response = await onRequest(request);
+
+      for (const [name, value] of response.headers) {
+        res.setHeader(name, value);
+      }
+      res.writeHead(response.status);
+
+      if (response.body) {
+        // @ts-ignore The types match up, trust me
+        await pipeline(Readable.fromWeb(response.body), res);
+      } else {
+        res.end("");
+      }
+    } catch (e) {
+      // Expected to happen on connection close
+      if (e.toString().includes("ERR_STREAM_PREMATURE_CLOSE")) return;
+      res.writeHead(500, {
+        "content-type": "text/plain",
+      });
+      res.end(e.message);
+    }
+  }
+
+  // start public DHT server
+  const dht =
+    dhtOptions instanceof HyperDHT ? dhtOptions : new HyperDHT(dhtOptions);
+
+  await dht.fullyBootstrapped();
+
+  const server = dht.createServer((/** @type {Duplex} */ conn) => {
+    httpServer.emit("connection", conn);
+  });
+
+  server.listen(keyPair);
+
+  async function destroy() {
+    await server.close();
+    await dht.destroy();
+  }
+
+  return { url, destroy, keyPair };
+}

package/test.js

@@ -0,0 +1,40 @@
+import test from "node:test";
+import makeHyperHTTPFetch from "./src/index.js";
+import assert from "node:assert";
+import createTestnet from "hyperdht/testnet.js";
+import createServer from "./src/server.js";
+
+test("Send a request to a server and get a response", async (t) => {
+  const testnet = await createTestnet();
+
+  t.after(() => testnet.destroy());
+
+  const url = await createTestServer(t, (_req) => new Response("Hello World"), {
+    dht: {
+      bootstrap: testnet.bootstrap,
+    },
+  });
+
+  const fetch = await makeHyperHTTPFetch({ bootstrap: testnet.bootstrap });
+
+  t.after(fetch.close);
+
+  const res = await fetch(url);
+  assert(res.ok, "Response is OK");
+  const message = await res.text();
+
+  assert.equal(message, "Hello World", "Body has expected message");
+});
+
+/**
+ *
+ * @param {import('node:test').TestContext} t
+ * @param {import("./src/server.js").HyperRequestListener} onRequest
+ * @param {import("./src/server.js").HyperServerOptions} [options]
+ */
+async function createTestServer(t, onRequest, options = {}) {
+  const server = await createServer(onRequest, options);
+  t.after(() => server.destroy());
+
+  return server.url;
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "outDir": "dist",
+    "checkJs": true,
+    "allowJs": true,
+    "rootDir": "src",
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "useUnknownInCatchVariables":false
+  },
+  "include": ["src/**/*.js"],
+  "exclude": ["node_modules", "dist"]
+}