@ipld/car 3.2.3 → 4.1.0

package/esm/node-test/test-errors.js

@@ -4,7 +4,8 @@ import { encode as vEncode } from 'varint';
 import { CarReader } from '../lib/reader.js';
 import {
   carBytes,
-  assert
+  assert,
+  goCarV2Bytes
 } from './common.js';
 function makeHeader(block) {
   const u = cbEncode(block);
@@ -26,42 +27,65 @@ describe('Misc errors', () => {
     });
   });
   it('bad version', async () => {
-    const buf2 = bytes.fromHex('0aa16776657273696f6e02');
-    assert.strictEqual(bytes.toHex(makeHeader({ version: 2 })), '0aa16776657273696f6e02');
-    await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR version: 2');
+    const buf2 = bytes.fromHex('0aa16776657273696f6e03');
+    assert.strictEqual(bytes.toHex(makeHeader({ version: 3 })), '0aa16776657273696f6e03');
+    await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR version: 3');
   });
-  it('bad header', async () => {
-    let buf2 = makeHeader({
-      version: 1,
-      roots: []
+  describe('bad header', async () => {
+    it('sanity check', async () => {
+      const buf2 = makeHeader({
+        version: 1,
+        roots: []
+      });
+      await assert.isFulfilled(CarReader.fromBytes(buf2));
     });
-    await assert.isFulfilled(CarReader.fromBytes(buf2));
-    buf2 = makeHeader({ roots: [] });
-    await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR version: undefined');
-    buf2 = makeHeader({
-      version: '1',
-      roots: []
+    it('no \'version\' array', async () => {
+      const buf2 = makeHeader({ roots: [] });
+      await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR header format');
     });
-    await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR version: "1"');
-    buf2 = makeHeader({ version: 1 });
-    await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR header format');
-    buf2 = makeHeader({
-      version: 1,
-      roots: {}
+    it('bad \'version\' type', async () => {
+      const buf2 = makeHeader({
+        version: '1',
+        roots: []
+      });
+      await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR header format');
     });
-    await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR header format');
-    buf2 = makeHeader({
-      version: 1,
-      roots: [],
-      blip: true
+    it('no \'roots\' array', async () => {
+      const buf2 = makeHeader({ version: 1 });
+      await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR header format');
+    });
+    it('bad \'roots\' type', async () => {
+      const buf2 = makeHeader({
+        version: 1,
+        roots: {}
+      });
+      await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR header format');
+    });
+    it('extraneous properties', async () => {
+      const buf2 = makeHeader({
+        version: 1,
+        roots: [],
+        blip: true
+      });
+      await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR header format');
+    });
+    it('not an object', async () => {
+      const buf2 = makeHeader([
+        1,
+        []
+      ]);
+      await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR header format');
+    });
+    it('not an object', async () => {
+      const buf2 = makeHeader(null);
+      await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR header format');
+    });
+    it('recursive v2 header', async () => {
+      const v2Header = goCarV2Bytes.slice(0, 51);
+      const buf2 = new Uint8Array(51 * 2);
+      buf2.set(v2Header, 0);
+      buf2.set(v2Header, 51);
+      await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR version: 2 (expected 1)');
     });
-    await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR header format');
-    buf2 = makeHeader([
-      1,
-      []
-    ]);
-    await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR header format');
-    buf2 = makeHeader(null);
-    await assert.isRejected(CarReader.fromBytes(buf2), Error, 'Invalid CAR header format');
   });
 });

package/esm/node-test/test-indexer.js

@@ -2,6 +2,9 @@ import { CarIndexer } from '../lib/indexer.js';
 import {
   goCarBytes,
   goCarIndex,
+  goCarV2Bytes,
+  goCarV2Roots,
+  goCarV2Index,
   makeIterable,
   assert
 } from './common.js';
@@ -17,6 +20,18 @@ describe('CarIndexer fromBytes()', () => {
     }
     assert.deepStrictEqual(indexData, goCarIndex);
   });
+  it('v2 complete', async () => {
+    const indexer = await CarIndexer.fromBytes(goCarV2Bytes);
+    const roots = await indexer.getRoots();
+    assert.strictEqual(roots.length, 1);
+    assert(goCarV2Roots[0].equals(roots[0]));
+    assert.strictEqual(indexer.version, 2);
+    const indexData = [];
+    for await (const index of indexer) {
+      indexData.push(index);
+    }
+    assert.deepStrictEqual(indexData, goCarV2Index);
+  });
   it('bad argument', async () => {
     for (const arg of [
         true,

package/esm/node-test/test-reader.js

@@ -1,12 +1,22 @@
 import { CarReader } from '../lib/reader.js';
 import { CarWriter } from '../lib/writer.js';
+import {
+  bytesReader,
+  readHeader
+} from '../lib/decoder.js';
 import * as Block from 'multiformats/block';
 import { sha256 } from 'multiformats/hashes/sha2';
 import * as raw from 'multiformats/codecs/raw';
+import { base64 } from 'multiformats/bases/base64';
+import * as dagPb from '@ipld/dag-pb';
 import {
   carBytes,
   makeIterable,
-  assert
+  assert,
+  goCarV2Bytes,
+  goCarV2Roots,
+  goCarV2Index,
+  goCarV2Contents
 } from './common.js';
 import {
   verifyRoots,
@@ -15,6 +25,8 @@ import {
   verifyBlocks,
   verifyCids
 } from './verify-store-reader.js';
+import { data as fixtures } from './fixtures.js';
+import { expectations as fixtureExpectations } from './fixtures-expectations.js';
 describe('CarReader fromBytes()', () => {
   it('complete', async () => {
     const reader = await CarReader.fromBytes(carBytes);
@@ -52,6 +64,29 @@ describe('CarReader fromBytes()', () => {
       message: 'Unexpected end of data'
     });
   });
+  it('v2 complete', async () => {
+    const reader = await CarReader.fromBytes(goCarV2Bytes);
+    const roots = await reader.getRoots();
+    assert.strictEqual(roots.length, 1);
+    assert(goCarV2Roots[0].equals(roots[0]));
+    assert.strictEqual(reader.version, 2);
+    for (const {cid} of goCarV2Index) {
+      const block = await reader.get(cid);
+      assert.isDefined(block);
+      if (block) {
+        assert(cid.equals(block.cid));
+        let content;
+        if (cid.code === dagPb.code) {
+          content = dagPb.decode(block.bytes);
+        } else if (cid.code === 85) {
+          content = new TextDecoder().decode(block.bytes);
+        } else {
+          assert.fail('Unexpected codec');
+        }
+        assert.deepStrictEqual(content, goCarV2Contents[cid.toString()]);
+      }
+    }
+  });
   it('decode error - trailing null bytes', async () => {
     const bytes = new Uint8Array(carBytes.length + 5);
     bytes.set(carBytes);
@@ -178,4 +213,58 @@ describe('CarReader fromIterable()', () => {
       message: 'Unexpected end of data'
     });
   });
+  it('v2 decode error - truncated', async () => {
+    const bytes = goCarV2Bytes.slice();
+    const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    dv.setBigUint64(35, BigInt(448 - 10), true);
+    await assert.isRejected(CarReader.fromIterable(makeIterable(bytes, 64)), {
+      name: 'Error',
+      message: 'Unexpected end of data'
+    });
+  });
+});
+describe('Shared fixtures', () => {
+  describe('Header', () => {
+    for (const [name, {
+            version: expectedVersion,
+            err: expectedError
+          }] of Object.entries(fixtureExpectations)) {
+      it(name, async () => {
+        const data = base64.baseDecode(fixtures[name]);
+        let header;
+        try {
+          header = await readHeader(bytesReader(data));
+        } catch (err) {
+          if (expectedError != null) {
+            assert.equal(err.message, expectedError);
+            return;
+          }
+          assert.ifError(err);
+        }
+        if (expectedError != null) {
+          assert.fail(`Expected error: ${ expectedError }`);
+        }
+        assert.isDefined(header, 'did not decode header');
+        if (expectedVersion != null && header != null) {
+          assert.strictEqual(header.version, expectedVersion);
+        }
+      });
+    }
+  });
+  describe('Contents', () => {
+    for (const [name, {cids: expectedCids}] of Object.entries(fixtureExpectations)) {
+      if (expectedCids == null) {
+        continue;
+      }
+      it(name, async () => {
+        const data = base64.baseDecode(fixtures[name]);
+        const reader = await CarReader.fromBytes(data);
+        let i = 0;
+        for await (const cid of reader.cids()) {
+          assert.strictEqual(cid.toString(), expectedCids[i++]);
+        }
+        assert.strictEqual(i, expectedCids.length);
+      });
+    }
+  });
 });

package/examples/car-to-fixture.js

@@ -42,10 +42,7 @@ async function run () {
   const indexer = await CarIndexer.fromBytes(bytes)
   const reader = await CarReader.fromBytes(bytes)
   const fixture = {
-    header: {
-      roots: await reader.getRoots(),
-      version: reader.version
-    },
+    header: reader._header, // a little naughty but we need gory details
     blocks: []
   }
   let i = 0

package/examples/dump-index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+// Take a .car file and dump its index in DAG-JSON format, one line per block
+
+import fs from 'fs'
+import { CarIndexer } from '@ipld/car/indexer'
+import * as dagJson from '@ipld/dag-json'
+
+if (!process.argv[2]) {
+  console.log('Usage: dump-index.js <path/to/car>')
+  process.exit(1)
+}
+
+async function run () {
+  const indexer = await CarIndexer.fromIterable(fs.createReadStream(process.argv[2]))
+  for await (const blockIndex of indexer) {
+    console.log(new TextDecoder().decode(dagJson.encode(blockIndex)))
+  }
+}
+
+run().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/examples/test-examples.js

@@ -76,6 +76,39 @@ Blocks:
     assert.strictEqual(stdout, '{"blocks":[{"blockLength":55,"blockOffset":137,"cid":{"/":"bafyreihyrpefhacm6kkp4ql6j6udakdit7g3dmkzfriqfykhjw6cad5lrm"},"content":{"link":{"/":"QmNX6Tffavsya4xgBi2VJQnSuqy9GsxongxZZ9uZBqp16d"},"name":"blip"},"length":92,"offset":100},{"blockLength":97,"blockOffset":228,"cid":{"/":"QmNX6Tffavsya4xgBi2VJQnSuqy9GsxongxZZ9uZBqp16d"},"content":{"Links":[{"Hash":{"/":"bafkreifw7plhl6mofk6sfvhnfh64qmkq73oeqwl6sloru6rehaoujituke"},"Name":"bear","Tsize":4},{"Hash":{"/":"QmWXZxVQ9yZfhQxLD35eDR8LiMRsYtHxYqTFCBbJoiJVys"},"Name":"second","Tsize":149}]},"length":133,"offset":192},{"blockLength":4,"blockOffset":362,"cid":{"/":"bafkreifw7plhl6mofk6sfvhnfh64qmkq73oeqwl6sloru6rehaoujituke"},"content":{"/":{"bytes":"Y2NjYw"}},"length":41,"offset":325},{"blockLength":94,"blockOffset":402,"cid":{"/":"QmWXZxVQ9yZfhQxLD35eDR8LiMRsYtHxYqTFCBbJoiJVys"},"content":{"Links":[{"Hash":{"/":"bafkreiebzrnroamgos2adnbpgw5apo3z4iishhbdx77gldnbk57d4zdio4"},"Name":"dog","Tsize":4},{"Hash":{"/":"QmdwjhxpxzcMsR3qUuj7vUL8pbA7MgR3GAxWi2GLHjsKCT"},"Name":"first","Tsize":51}]},"length":130,"offset":366},{"blockLength":4,"blockOffset":533,"cid":{"/":"bafkreiebzrnroamgos2adnbpgw5apo3z4iishhbdx77gldnbk57d4zdio4"},"content":{"/":{"bytes":"YmJiYg"}},"length":41,"offset":496},{"blockLength":47,"blockOffset":572,"cid":{"/":"QmdwjhxpxzcMsR3qUuj7vUL8pbA7MgR3GAxWi2GLHjsKCT"},"content":{"Links":[{"Hash":{"/":"bafkreidbxzk2ryxwwtqxem4l3xyyjvw35yu4tcct4cqeqxwo47zhxgxqwq"},"Name":"cat","Tsize":4}]},"length":82,"offset":537},{"blockLength":4,"blockOffset":656,"cid":{"/":"bafkreidbxzk2ryxwwtqxem4l3xyyjvw35yu4tcct4cqeqxwo47zhxgxqwq"},"content":{"/":{"bytes":"YWFhYQ"}},"length":41,"offset":619},{"blockLength":18,"blockOffset":697,"cid":{"/":"bafyreidj5idub6mapiupjwjsyyxhyhedxycv4vihfsicm2vt46o7morwlm"},"content":{"link":null,"name":"limbo"},"length":55,"offset":660}],"header":{"roots":[{"/":"bafyreihyrpefhacm6kkp4ql6j6udakdit7g3dmkzfriqfykhjw6cad5lrm"},{"/":"bafyreidj5idub6mapiupjwjsyyxhyhedxycv4vihfsicm2vt46o7morwlm"}],"version":1}}\n')
     console.log('\u001b[32m✔\u001b[39m [example] car-to-fixture ../test/go.car')
   })
+}).then(async () => {
+  await runExample('dump-index', ['example.car']).then(({ stdout, stderr }) => {
+    assert.strictEqual(stderr, '')
+    assert.strictEqual(stdout, '{"blockLength":24,"blockOffset":96,"cid":{"/":"bafkreihwkf6mtnjobdqrkiksr7qhp6tiiqywux64aylunbvmfhzeql2coa"},"length":61,"offset":59}\n')
+    console.log('\u001b[32m✔\u001b[39m [example] dump-index example.car')
+  })
+}).then(async () => {
+  await runExample('dump-index', ['../test/go.car']).then(({ stdout, stderr }) => {
+    assert.strictEqual(stderr, '')
+    assert.strictEqual(stdout,
+`{"blockLength":55,"blockOffset":137,"cid":{"/":"bafyreihyrpefhacm6kkp4ql6j6udakdit7g3dmkzfriqfykhjw6cad5lrm"},"length":92,"offset":100}
+{"blockLength":97,"blockOffset":228,"cid":{"/":"QmNX6Tffavsya4xgBi2VJQnSuqy9GsxongxZZ9uZBqp16d"},"length":133,"offset":192}
+{"blockLength":4,"blockOffset":362,"cid":{"/":"bafkreifw7plhl6mofk6sfvhnfh64qmkq73oeqwl6sloru6rehaoujituke"},"length":41,"offset":325}
+{"blockLength":94,"blockOffset":402,"cid":{"/":"QmWXZxVQ9yZfhQxLD35eDR8LiMRsYtHxYqTFCBbJoiJVys"},"length":130,"offset":366}
+{"blockLength":4,"blockOffset":533,"cid":{"/":"bafkreiebzrnroamgos2adnbpgw5apo3z4iishhbdx77gldnbk57d4zdio4"},"length":41,"offset":496}
+{"blockLength":47,"blockOffset":572,"cid":{"/":"QmdwjhxpxzcMsR3qUuj7vUL8pbA7MgR3GAxWi2GLHjsKCT"},"length":82,"offset":537}
+{"blockLength":4,"blockOffset":656,"cid":{"/":"bafkreidbxzk2ryxwwtqxem4l3xyyjvw35yu4tcct4cqeqxwo47zhxgxqwq"},"length":41,"offset":619}
+{"blockLength":18,"blockOffset":697,"cid":{"/":"bafyreidj5idub6mapiupjwjsyyxhyhedxycv4vihfsicm2vt46o7morwlm"},"length":55,"offset":660}
+`)
+    console.log('\u001b[32m✔\u001b[39m [example] dump-index ../test/go.carv2')
+  })
+}).then(async () => {
+  await runExample('dump-index', ['../test/go.carv2']).then(({ stdout, stderr }) => {
+    assert.strictEqual(stderr, '')
+    assert.strictEqual(stdout,
+`{"blockLength":47,"blockOffset":143,"cid":{"/":"QmfEoLyB5NndqeKieExd1rtJzTduQUPEV8TwAYcUiy3H5Z"},"length":82,"offset":108}
+{"blockLength":99,"blockOffset":226,"cid":{"/":"QmczfirA7VEH7YVvKPTPoU69XM3qY4DC39nnTsWd4K3SkM"},"length":135,"offset":190}
+{"blockLength":54,"blockOffset":360,"cid":{"/":"Qmcpz2FHJD7VAhg1fxFXdYJKePtkx1BsHuCrAgWVnaHMTE"},"length":89,"offset":325}
+{"blockLength":4,"blockOffset":451,"cid":{"/":"bafkreifuosuzujyf4i6psbneqtwg2fhplc2wxptc5euspa2gn3bwhnihfu"},"length":41,"offset":414}
+{"blockLength":7,"blockOffset":492,"cid":{"/":"bafkreifc4hca3inognou377hfhvu2xfchn2ltzi7yu27jkaeujqqqdbjju"},"length":44,"offset":455}
+`)
+    console.log('\u001b[32m✔\u001b[39m [example] dump-index ../test/go.carv2')
+  })
 }).catch((err) => {
   console.error(err.stack)
   process.exit(1)

package/lib/buffer-writer.js

@@ -0,0 +1,286 @@
+import varint from 'varint'
+import { Token, Type } from 'cborg'
+import { tokensToLength } from 'cborg/length'
+import * as CBOR from '@ipld/dag-cbor'
+
+/**
+ * @typedef {import('../api').CID} CID
+ * @typedef {import('../api').Block} Block
+ * @typedef {import('../api').CarBufferWriter} Writer
+ * @typedef {import('../api').CarBufferWriterOptions} Options
+ * @typedef {import('./coding').CarEncoder} CarEncoder
+ */
+
+/**
+ * A simple CAR writer that writes to a pre-allocated buffer.
+ *
+ * @class
+ * @name CarBufferWriter
+ * @implements {Writer}
+ */
+class CarBufferWriter {
+  /**
+   * @param {Uint8Array} bytes
+   * @param {number} headerSize
+   */
+  constructor (bytes, headerSize) {
+    /** @readonly */
+    this.bytes = bytes
+    this.byteOffset = headerSize
+
+    /**
+     * @readonly
+     * @type {CID[]}
+     */
+    this.roots = []
+    this.headerSize = headerSize
+  }
+
+  /**
+   * Add a root to this writer, to be used to create a header when the CAR is
+   * finalized with {@link CarBufferWriter.close `close()`}
+   *
+   * @param {CID} root
+   * @param {{resize?:boolean}} [options]
+   * @returns {CarBufferWriter}
+   */
+  addRoot (root, options) {
+    addRoot(this, root, options)
+    return this
+  }
+
+  /**
+   * Write a `Block` (a `{ cid:CID, bytes:Uint8Array }` pair) to the archive.
+   * Throws if there is not enough capacity.
+   *
+   * @param {Block} block A `{ cid:CID, bytes:Uint8Array }` pair.
+   * @returns {CarBufferWriter}
+   */
+  write (block) {
+    addBlock(this, block)
+    return this
+  }
+
+  /**
+   * Finalize the CAR and return it as a `Uint8Array`.
+   *
+   * @param {object} [options]
+   * @param {boolean} [options.resize]
+   * @returns {Uint8Array}
+   */
+  close (options) {
+    return close(this, options)
+  }
+}
+
+/**
+ * @param {CarBufferWriter} writer
+ * @param {CID} root
+ * @param {{resize?:boolean}} [options]
+ */
+export const addRoot = (writer, root, { resize = false } = {}) => {
+  const { bytes, headerSize, byteOffset, roots } = writer
+  writer.roots.push(root)
+  const size = headerLength(writer)
+  // If there is not enough space for the new root
+  if (size > headerSize) {
+    // Check if we root would fit if we were to resize the head.
+    if (size - headerSize + byteOffset < bytes.byteLength) {
+      // If resize is enabled resize head
+      if (resize) {
+        resizeHeader(writer, size)
+      // otherwise remove head and throw an error suggesting to resize
+      } else {
+        roots.pop()
+        throw new RangeError(`Header of size ${headerSize} has no capacity for new root ${root}.
+  However there is a space in the buffer and you could call addRoot(root, { resize: root }) to resize header to make a space for this root.`)
+      }
+    // If head would not fit even with resize pop new root and throw error
+    } else {
+      roots.pop()
+      throw new RangeError(`Buffer has no capacity for a new root ${root}`)
+    }
+  }
+}
+
+/**
+ * Calculates number of bytes required for storing given block in CAR. Useful in
+ * estimating size of an `ArrayBuffer` for the `CarBufferWriter`.
+ *
+ * @name CarBufferWriter.blockLength(Block)
+ * @param {Block} block
+ * @returns {number}
+ */
+export const blockLength = ({ cid, bytes }) => {
+  const size = cid.bytes.byteLength + bytes.byteLength
+  return varint.encodingLength(size) + size
+}
+
+/**
+ * @param {CarBufferWriter} writer
+ * @param {Block} block
+ */
+export const addBlock = (writer, { cid, bytes }) => {
+  const byteLength = cid.bytes.byteLength + bytes.byteLength
+  const size = varint.encode(byteLength)
+  if (writer.byteOffset + size.length + byteLength > writer.bytes.byteLength) {
+    throw new RangeError('Buffer has no capacity for this block')
+  } else {
+    writeBytes(writer, size)
+    writeBytes(writer, cid.bytes)
+    writeBytes(writer, bytes)
+  }
+}
+
+/**
+ * @param {CarBufferWriter} writer
+ * @param {object} [options]
+ * @param {boolean} [options.resize]
+ */
+export const close = (writer, { resize = false } = {}) => {
+  const { roots, bytes, byteOffset, headerSize } = writer
+
+  const headerBytes = CBOR.encode({ version: 1, roots })
+  const varintBytes = varint.encode(headerBytes.length)
+
+  const size = varintBytes.length + headerBytes.byteLength
+  const offset = headerSize - size
+
+  // If header size estimate was accurate we just write header and return
+  // view into buffer.
+  if (offset === 0) {
+    writeHeader(writer, varintBytes, headerBytes)
+    return bytes.subarray(0, byteOffset)
+    // If header was overestimated and `{resize: true}` is passed resize header
+  } else if (resize) {
+    resizeHeader(writer, size)
+    writeHeader(writer, varintBytes, headerBytes)
+    return bytes.subarray(0, writer.byteOffset)
+  } else {
+    throw new RangeError(`Header size was overestimated.
+You can use close({ resize: true }) to resize header`)
+  }
+}
+
+/**
+ * @param {CarBufferWriter} writer
+ * @param {number} byteLength
+ */
+export const resizeHeader = (writer, byteLength) => {
+  const { bytes, headerSize } = writer
+  // Move data section to a new offset
+  bytes.set(bytes.subarray(headerSize, writer.byteOffset), byteLength)
+  // Update header size & byteOffset
+  writer.byteOffset += byteLength - headerSize
+  writer.headerSize = byteLength
+}
+
+/**
+ * @param {CarBufferWriter} writer
+ * @param {number[]|Uint8Array} bytes
+ */
+
+const writeBytes = (writer, bytes) => {
+  writer.bytes.set(bytes, writer.byteOffset)
+  writer.byteOffset += bytes.length
+}
+/**
+ * @param {{bytes:Uint8Array}} writer
+ * @param {number[]} varint
+ * @param {Uint8Array} header
+ */
+const writeHeader = ({ bytes }, varint, header) => {
+  bytes.set(varint)
+  bytes.set(header, varint.length)
+}
+
+const headerPreludeTokens = [
+  new Token(Type.map, 2),
+  new Token(Type.string, 'version'),
+  new Token(Type.uint, 1),
+  new Token(Type.string, 'roots')
+]
+
+const CID_TAG = new Token(Type.tag, 42)
+
+/**
+ * Calculates header size given the array of byteLength for roots.
+ *
+ * @name CarBufferWriter.calculateHeaderLength(rootLengths)
+ * @param {number[]} rootLengths
+ * @returns {number}
+ */
+export const calculateHeaderLength = (rootLengths) => {
+  const tokens = [...headerPreludeTokens]
+  tokens.push(new Token(Type.array, rootLengths.length))
+  for (const rootLength of rootLengths) {
+    tokens.push(CID_TAG)
+    tokens.push(new Token(Type.bytes, { length: rootLength + 1 }))
+  }
+  const length = tokensToLength(tokens) // no options needed here because we have simple tokens
+  return varint.encodingLength(length) + length
+}
+
+/**
+ * Calculates header size given the array of roots.
+ *
+ * @name CarBufferWriter.headerLength({ roots })
+ * @param {object} options
+ * @param {CID[]} options.roots
+ * @returns {number}
+ */
+export const headerLength = ({ roots }) =>
+  calculateHeaderLength(roots.map(cid => cid.bytes.byteLength))
+
+/**
+ * Estimates header size given a count of the roots and the expected byte length
+ * of the root CIDs. The default length works for a standard CIDv1 with a
+ * single-byte multihash code, such as SHA2-256 (i.e. the most common CIDv1).
+ *
+ * @name CarBufferWriter.estimateHeaderLength(rootCount[, rootByteLength])
+ * @param {number} rootCount
+ * @param {number} [rootByteLength]
+ * @returns {number}
+ */
+export const estimateHeaderLength = (rootCount, rootByteLength = 36) =>
+  calculateHeaderLength(new Array(rootCount).fill(rootByteLength))
+
+/**
+ * Creates synchronous CAR writer that can be used to encode blocks into a given
+ * buffer. Optionally you could pass `byteOffset` and `byteLength` to specify a
+ * range inside buffer to write into. If car file is going to have `roots` you
+ * need to either pass them under `options.roots` (from which header size will
+ * be calculated) or provide `options.headerSize` to allocate required space
+ * in the buffer. You may also provide known `roots` and `headerSize` to
+ * allocate space for the roots that may not be known ahead of time.
+ *
+ * Note: Incorrect `headerSize` may lead to copying bytes inside a buffer
+ * which will have a negative impact on performance.
+ *
+ * @name CarBufferWriter.createWriter(buffer[, options])
+ * @param {ArrayBuffer} buffer
+ * @param {object} [options]
+ * @param {CID[]} [options.roots]
+ * @param {number} [options.byteOffset]
+ * @param {number} [options.byteLength]
+ * @param {number} [options.headerSize]
+ * @returns {CarBufferWriter}
+ */
+export const createWriter = (
+  buffer,
+  {
+    roots = [],
+    byteOffset = 0,
+    byteLength = buffer.byteLength,
+    headerSize = headerLength({ roots })
+  } = {}
+) => {
+  const bytes = new Uint8Array(buffer, byteOffset, byteLength)
+
+  const writer = new CarBufferWriter(bytes, headerSize)
+  for (const root of roots) {
+    writer.addRoot(root)
+  }
+
+  return writer
+}

package/lib/coding.ts

@@ -20,10 +20,25 @@ export interface IteratorChannel<T> {
   iterator: AsyncIterator<T>
 }
 
-export type CarHeader = { version: number, roots: CID[] }
+export interface CarHeader {
+  version: 1,
+  roots: CID[]
+}
+
+export interface CarV2FixedHeader {
+  characteristics: [bigint, bigint],
+  dataOffset: number,
+  dataSize: number,
+  indexOffset: number
+}
+
+export interface CarV2Header extends CarV2FixedHeader {
+  version: 2,
+  roots: CID[],
+}
 
 export interface CarDecoder {
-  header(): Promise<CarHeader>
+  header(): Promise<CarHeader|CarV2Header>
 
   blocks(): AsyncGenerator<Block>