{"id":17298,"library":"multiblob-http","title":"multiblob-http","description":"multiblob-http is a Node.js library designed to serve content-addressed blobs over HTTP. It provides an HTTP handler, compatible with frameworks like Express, that exposes endpoints for retrieving blobs by hash (`GET /blobs/get/{id}`) and adding new blobs (`POST /blobs/add`). The library ensures efficient content delivery by setting appropriate HTTP headers, including `ETag` (based on the blob hash) and `Expires` (a year in the future), and supports HTTP range requests (RFC 7233) crucial for streaming media and partial content retrieval. The current stable version is 1.2.1, with releases appearing to follow a maintenance cadence, focusing on stability rather than frequent new features. Its primary differentiator is its tight integration with the `multiblob` package for backend storage and its robust handling of HTTP caching mechanisms for immutable, content-addressed data.","status":"maintenance","version":"1.2.1","language":"javascript","source_language":"en","source_url":"git://github.com/ssbc/multiblob-http","tags":["javascript"],"install":[{"cmd":"npm install multiblob-http","lang":"bash","label":"npm"},{"cmd":"yarn add multiblob-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add multiblob-http","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for backend blob storage and retrieval functionality, as multiblob-http acts as the HTTP interface for a multiblob instance.","package":"multiblob","optional":false}],"imports":[{"note":"The primary export is a default-like CommonJS export. For ESM, use `import MultiBlobHttp from 'multiblob-http'` if your environment supports CJS interop.","wrong":"const { MultiBlobHttp } = require('multiblob-http')","symbol":"MultiBlobHttp","correct":"const MultiBlobHttp = require('multiblob-http')"},{"note":"While the examples are CJS, modern Node.js projects using ESM should use this import. Ensure proper CJS interop or module resolution is configured.","symbol":"MultiBlobHttp (ESM)","correct":"import MultiBlobHttp from 'multiblob-http'"},{"note":"MultiBlobHttp returns a request handler function when called with a multiblob instance and an optional prefix. It is not an HTTP handler itself directly.","wrong":"http.createServer(MultiBlobHttp).listen(8000)","symbol":"HTTP Handler","correct":"http.createServer(MultiBlobHttp(blobs, '/blobs')).listen(8000)"}],"quickstart":{"code":"import MultiBlob from 'multiblob';\nimport MultiBlobHttp from 'multiblob-http';\nimport http from 'http';\nimport path from 'path';\nimport fs from 'fs';\n\n// Ensure a directory exists for blobs\nconst dir = path.join(process.cwd(), 'my-blobs');\nif (!fs.existsSync(dir)) {\n  fs.mkdirSync(dir, { recursive: true });\n}\n\nconst blobs = MultiBlob(dir);\nconst port = process.env.PORT || 8000;\n\nhttp.createServer(MultiBlobHttp(blobs, '/blobs')).listen(port, () => {\n  console.log(`multiblob-http server listening on http://localhost:${port}`);\n  console.log(`GET blobs: http://localhost:${port}/blobs/get/{hash}`);\n  console.log(`POST to add: http://localhost:${port}/blobs/add`);\n});\n\n// Example of adding a blob programmatically\nasync function addExampleBlob() {\n  const content = Buffer.from('Hello, multiblob-http!');\n  const ws = blobs.createWriteStream();\n  ws.end(content);\n  const hash = await new Promise((resolve, reject) => {\n    ws.on('error', reject);\n    ws.on('finish', () => resolve(ws.hash));\n  });\n  console.log(`Added example blob with hash: ${hash}`);\n  console.log(`Try to fetch it: curl http://localhost:${port}/blobs/get/${hash}`);\n}\n\naddExampleBlob();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install `multiblob` via `npm install multiblob` or `yarn add multiblob`. Always pass a correctly initialized `multiblob` instance to `MultiBlobHttp()`.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install `multiblob` (`npm install multiblob`) and ensure it's imported correctly: `const MultiBlob = require('multiblob')` or `import MultiBlob from 'multiblob'`.","cause":"The `multiblob` dependency was not installed or incorrectly imported/initialized before being passed to `MultiBlobHttp`.","error":"TypeError: MultiBlob is not a function"},{"fix":"Choose a different port for your HTTP server, or identify and terminate the process currently using the port.","cause":"The specified port (e.g., 8000) is already being used by another process on your system.","error":"Error: listen EADDRINUSE: address already in use :::8000"},{"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`).","cause":"The requested blob with the specified hash does not exist in the configured `multiblob` store, or the URL path/prefix is incorrect.","error":"Cannot GET /blobs/get/{hash} (404 Not Found)"},{"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.","cause":"Attempting to use `require()` in an ES Module (ESM) context without proper configuration for CommonJS interop.","error":"ReferenceError: require is not defined"}],"ecosystem":"npm","meta_description":null}