Hypercore Blob Server

Common errors

• TypeError: store is not an object or store.ready is not a function

  cause The `store` argument passed to the `BlobServer` constructor is either null/undefined, not an object, or is not a valid and initialized `Corestore` instance.
  fix Initialize `Corestore` correctly and ensure `await store.ready()` has been called: `const Corestore = require('corestore'); const store = new Corestore('./data-path'); await store.ready();`

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

  cause The default port (49833) or the custom port specified in `BlobServer` options is already in use by another process on the system.
  fix Change the `port` option in the `BlobServer` constructor to an available port (e.g., `port: 0` to let the OS assign a random available port), or terminate the process currently using the desired port.

• HTTP/1.1 404 Not Found (when attempting to fetch a generated link)

  cause The `key` for the Hypercore/Hyperdrive or the `blob` ID/`filename` provided in `server.getLink()` does not correspond to existing, accessible data within the `Corestore` being served.
  fix Verify that the `key` is correct, the associated Hypercore/Hyperdrive has been opened and contains data, and the `blob` or `filename` parameters precisely match the content intended to be served.

• HTTP/1.1 416 Range Not Satisfiable (when fetching with a Range header)

  cause The `Range` header in the client request specifies byte ranges that are outside the bounds of the available data for the requested blob, or the header format is invalid.
  fix Adjust the `Range` header to request valid byte ranges within the blob's actual size. Ensure the header format is strictly `bytes=<start>-<end>` (e.g., `Range: bytes=0-500`).

Warnings

• gotcha The `BlobServer` constructor requires a fully initialized `corestore` instance. Passing an uninitialized or incorrect object will lead to runtime errors when the server attempts to access it.
  Fix: Ensure `const store = new Corestore('./path/to/data'); await store.ready()` is called and awaited before passing the `store` instance to `BlobServer`.
• gotcha When serving sensitive data, the `token` option should be configured to secure access to the server. Without a token, the server is publicly accessible on its configured port to anyone who knows the URL.
  Fix: Configure the `token` option in the `BlobServer` constructor: `new BlobServer(store, { token: process.env.BLOB_SERVER_TOKEN })`. Clients will then need to pass this token in request headers for authorization.
• gotcha Incorrectly formatted `Range` headers can lead to `416 Range Not Satisfiable` errors or unexpected partial content responses. The format must strictly follow `bytes=<start>-<end>` (e.g., `bytes=0-100` or `bytes=50-`).
  Fix: Validate client `Range` header syntax and ensure byte offsets are within the blob's actual bounds. Ensure no spaces or invalid characters are present.
• gotcha When generating links for Hypercore blobs, the `blob` option requires a precise `{ blockOffset, blockLength, byteOffset, byteLength }` object. Errors in these values will result in 404s or malformed responses, as the server cannot locate the specified data segment.
  Fix: Ensure the `blob` object accurately describes the segment of data within the Hypercore. This often requires careful tracking of data appended to the core, or using library utilities to derive these values.

Install

• npm install hypercore-blob-server npm
• yarn add hypercore-blob-server yarn
• pnpm add hypercore-blob-server pnpm

Imports

• BlobServer
  wrong:

  import BlobServer from 'hypercore-blob-server'

  correct:

  const BlobServer = require('hypercore-blob-server')

  The official README example uses CommonJS `require()`. While ESM imports might work in some setups, `require()` is the most robust and documented approach for Node.js environments, especially with older v1.x projects in the Holepunch ecosystem.
• BlobServer
  wrong:

  const { BlobServer } = require('hypercore-blob-server')

  correct:

  import BlobServer from 'hypercore-blob-server'

  For ESM environments, `import BlobServer from 'hypercore-blob-server'` is the correct syntax, as `BlobServer` is typically the default export. Attempting to destructure a CommonJS default export with `const { BlobServer } = require(...)` is a common mistake.
• BlobServerOptions

  import type { BlobServerOptions } from 'hypercore-blob-server'

  When using TypeScript, `BlobServerOptions` can be imported as a type for defining the configuration object passed to the `BlobServer` constructor.

Quickstart

Demonstrates the full flow of initializing a Corestore, creating a Hypercore, appending data, starting a BlobServer, and generating a shareable link to the content.

const BlobServer = require('hypercore-blob-server')
const Corestore = require('corestore')
const Hypercore = require('hypercore')

async function startServer () {
  // Initialize a Corestore for data management and persistence
  const store = new Corestore('./my-hypercore-data')
  await store.ready()

  // Create a Hypercore instance and append some data to it
  const core = store.get({ name: 'my-test-feed' })
  await core.ready()
  await core.append(Buffer.from('Hello, Hypercore blob server!'))

  // Instantiate the BlobServer with the initialized corestore
  const server = new BlobServer(store, {
    port: 49833,
    host: '127.0.0.1',
    // For production deployments, consider adding a 'token' for security:
    // token: process.env.BLOB_SERVER_TOKEN ?? ''
  })

  // Start the HTTP server to listen for incoming requests
  await server.listen()
  const address = server.server.address()
  console.log(`BlobServer listening on http://${address.address}:${address.port}`)

  // Generate a public URL link to the appended blob data
  // The 'blob' option requires precise byte offsets and lengths.
  const link = server.getLink(core.key, {
    blob: { blockOffset: 0, blockLength: 1, byteOffset: 0, byteLength: 29 },
    type: 'text/plain'
  })
  console.log('Access your Hypercore blob data here:', link)

  // To gracefully stop the server and close the corestore:
  // await server.suspend()
  // await store.close()
}

startServer().catch(console.error)