fetchurl JavaScript SDK

Protocol-level client for fetchurl content-addressable cache servers.

Uses the Web Crypto API — works in Node.js 19+, Deno, Bun, and browsers. Pass any spec-compliant fetch for dependency injection.

Install

npm install fetchurl-sdk

(Package name on npm is fetchurl-sdk; publish separately when ready.)

Protocol

Normative behavior: fetchurl/spec (SPEC.md).

Reference server: fetchurl/fetchurl.

Usage

import { fetchurl, parseFetchurlServer } from 'fetchurl-sdk';

const servers = parseFetchurlServer(process.env.FETCHURL_SERVER ?? '');
const data = await fetchurl({
  fetch,
  servers,
  algo: 'sha256',
  hash: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
  sourceUrls: ['https://cdn.example.com/file.tar.gz'],
});
// data is Uint8Array, hash-verified

Clients must treat the server as untrusted and verify the hash (this SDK does that for you).

Environment

| Variable | Meaning | |----------|---------| | FETCHURL_SERVER | Server base URL(s) per the spec (RFC 8941 list or a single URL). Empty/absent disables server use. |

Development

npm install
npm test
# Integration tests (needs Docker + fetchurl image):
# FETCHURL_TEST_IMAGE=fetchurl:local node --test fetchurl.integration.test.js

Related

| Repo | Role | |------|------| | fetchurl/spec | Protocol | | fetchurl/fetchurl | Go server | | fetchurl/sdk-python | Python SDK | | fetchurl/sdk-rust | Rust SDK |