multiblob-http

Common errors

• TypeError: MultiBlob is not a function

  cause The `multiblob` dependency was not installed or incorrectly imported/initialized before being passed to `MultiBlobHttp`.
  fix Install `multiblob` (`npm install multiblob`) and ensure it's imported correctly: `const MultiBlob = require('multiblob')` or `import MultiBlob from 'multiblob'`.

• Error: listen EADDRINUSE: address already in use :::8000

  cause The specified port (e.g., 8000) is already being used by another process on your system.
  fix Choose a different port for your HTTP server, or identify and terminate the process currently using the port.

• Cannot GET /blobs/get/{hash} (404 Not Found)

  cause The requested blob with the specified hash does not exist in the configured `multiblob` store, or the URL path/prefix is incorrect.
  fix Verify the hash is correct and corresponds to an existing blob. Check that the `prefix` argument passed to `MultiBlobHttp(blobs, '/blobs')` matches the URL path you are requesting (e.g., `/blobs`).

• ReferenceError: require is not defined

  cause Attempting to use `require()` in an ES Module (ESM) context without proper configuration for CommonJS interop.
  fix Convert `require('multiblob-http')` to `import MultiBlobHttp from 'multiblob-http'` (and similarly for `multiblob`) if your project is ESM-first. Ensure your `package.json` has `"type": "module"` if using `.js` files as ESM.

Warnings

• gotcha The README and most examples use CommonJS `require()`. While Node.js supports CommonJS in ESM projects, explicit ESM import paths (`import MultiBlobHttp from 'multiblob-http'`) might be preferred for modern applications. Ensure your build system or Node.js configuration handles CJS interop correctly.
  Fix: For ESM projects, use `import MultiBlobHttp from 'multiblob-http'`. If issues arise, consider configuring your bundler (e.g., Webpack, Rollup) or `tsconfig.json` for proper CJS module resolution.
• breaking The package explicitly depends on `multiblob`. If `multiblob` is not installed or incorrectly configured, `multiblob-http` will fail to initialize or serve content. Ensure `multiblob` is a direct dependency and properly instantiated.
  Fix: Install `multiblob` via `npm install multiblob` or `yarn add multiblob`. Always pass a correctly initialized `multiblob` instance to `MultiBlobHttp()`.
• gotcha The `engines` field in `package.json` specifies `"node": ">=12"`. While the library might function on newer Node.js versions, it indicates a lack of explicit testing or consideration for potential breaking changes in very recent Node.js releases beyond version 12.
  Fix: Ensure your Node.js version is at least 12. If running on much newer Node.js versions (e.g., Node.js 18+), monitor for unexpected behavior or deprecated APIs, though a simple HTTP handler is less prone to such issues.
• gotcha The `POST /add` endpoint currently responds with the hash but does not validate if the received content matches a hash specified in the URL (e.g., `POST /add/{id}`). This 'TODO' in the README implies a potential for mismatch if the client provides a hash that doesn't match the content.
  Fix: Clients should only use `POST /add` and rely on the server's response for the generated hash. Avoid sending a hash in the URL for `POST /add` as it will be ignored for validation purposes in the current implementation.

Install

• npm install multiblob-http npm
• yarn add multiblob-http yarn
• pnpm add multiblob-http pnpm

Imports

• MultiBlobHttp
  wrong:

  const { MultiBlobHttp } = require('multiblob-http')

  correct:

  const MultiBlobHttp = require('multiblob-http')

  The primary export is a default-like CommonJS export. For ESM, use `import MultiBlobHttp from 'multiblob-http'` if your environment supports CJS interop.
• MultiBlobHttp (ESM)

  import MultiBlobHttp from 'multiblob-http'

  While the examples are CJS, modern Node.js projects using ESM should use this import. Ensure proper CJS interop or module resolution is configured.
• HTTP Handler
  wrong:

  http.createServer(MultiBlobHttp).listen(8000)

  correct:

  http.createServer(MultiBlobHttp(blobs, '/blobs')).listen(8000)

  MultiBlobHttp returns a request handler function when called with a multiblob instance and an optional prefix. It is not an HTTP handler itself directly.

Quickstart

This quickstart sets up a basic `multiblob-http` server to serve content-addressed blobs from a local directory, demonstrating how to initialize the server and programmatically add a blob.

import MultiBlob from 'multiblob';
import MultiBlobHttp from 'multiblob-http';
import http from 'http';
import path from 'path';
import fs from 'fs';

// Ensure a directory exists for blobs
const dir = path.join(process.cwd(), 'my-blobs');
if (!fs.existsSync(dir)) {
  fs.mkdirSync(dir, { recursive: true });
}

const blobs = MultiBlob(dir);
const port = process.env.PORT || 8000;

http.createServer(MultiBlobHttp(blobs, '/blobs')).listen(port, () => {
  console.log(`multiblob-http server listening on http://localhost:${port}`);
  console.log(`GET blobs: http://localhost:${port}/blobs/get/{hash}`);
  console.log(`POST to add: http://localhost:${port}/blobs/add`);
});

// Example of adding a blob programmatically
async function addExampleBlob() {
  const content = Buffer.from('Hello, multiblob-http!');
  const ws = blobs.createWriteStream();
  ws.end(content);
  const hash = await new Promise((resolve, reject) => {
    ws.on('error', reject);
    ws.on('finish', () => resolve(ws.hash));
  });
  console.log(`Added example blob with hash: ${hash}`);
  console.log(`Try to fetch it: curl http://localhost:${port}/blobs/get/${hash}`);
}

addExampleBlob();