feat: add CAR upload method (#72)

README.md

@@ -155,6 +155,7 @@ In the example above, `directoryCid` resolves to an IPFS directory with the foll
 - `Client`
  - [`uploadDirectory`](#uploaddirectory)
  - [`uploadFile`](#uploadfile)
+ - [`uploadCAR`](#uploadcar)
  - [`agent`](#agent)
  - [`currentSpace`](#currentspace)
  - [`setCurrentSpace`](#setcurrentspace)
@@ -215,6 +216,7 @@ function uploadDirectory (
  signal?: AbortSignal
  onShardStored?: ShardStoredCallback
  shardSize?: number
+ concurrentRequests?: number
  } = {}
 ): Promise<CID>
 ```
@@ -233,6 +235,7 @@ function uploadFile (
  signal?: AbortSignal
  onShardStored?: ShardStoredCallback
  shardSize?: number
+ concurrentRequests?: number
  } = {}
 ): Promise<CID>
 ```
@@ -241,6 +244,26 @@ Uploads a file to the service and returns the root data CID for the generated DA
 
 More information: [`ShardStoredCallback`](#shardstoredcallback)
 
+### `uploadCAR`
+
+```ts
+function uploadCAR (
+ car: Blob,
+ options: {
+ retries?: number
+ signal?: AbortSignal
+ onShardStored?: ShardStoredCallback
+ shardSize?: number
+ concurrentRequests?: number
+ rootCID?: CID
+ } = {}
+): Promise<void>
+```
+
+Uploads a CAR file to the service. The difference between this function and [capability.store.add](#capabilitystoreadd) is that the CAR file is automatically sharded and an "upload" is registered (see [`capability.upload.add`](#capabilityuploadadd)), linking the individual shards. Use the `onShardStored` callback to obtain the CIDs of the CAR file shards.
+
+More information: [`ShardStoredCallback`](#shardstoredcallback)
+
 ### `agent`
 
 ```ts

package.json

@@ -75,7 +75,7 @@
  "@ucanto/transport": "^4.0.2",
  "@web3-storage/access": "^9.1.1",
  "@web3-storage/capabilities": "^2.0.0",
- "@web3-storage/upload-client": "^5.2.0"
+ "@web3-storage/upload-client": "^5.3.0"
  },
  "devDependencies": {
  "@ucanto/server": "^4.0.2",

src/client.js

@@ -1,4 +1,4 @@
-import { uploadFile, uploadDirectory } from '@web3-storage/upload-client'
+import { uploadFile, uploadDirectory, uploadCAR } from '@web3-storage/upload-client'
 import { Store as StoreCapabilities, Upload as UploadCapabilities } from '@web3-storage/capabilities'
 import { Base } from './base.js'
 import { Space } from './space.js'
@@ -49,6 +49,24 @@ export class Client extends Base {
  return uploadDirectory(conf, files, options)
  }
 
+ /**
+ * Uploads a CAR file to the service.
+ *
+ * The difference between this function and `capability.store.add` is that the
+ * CAR file is automatically sharded and an "upload" is registered, linking
+ * the individual shards (see `capability.upload.add`).
+ *
+ * Use the `onShardStored` callback to obtain the CIDs of the CAR file shards.
+ *
+ * @param {import('./types').BlobLike} car CAR file.
+ * @param {import('./types').UploadOptions} [options]
+ */
+ async uploadCAR (car, options = {}) {
+ const conf = await this._invocationConfig([StoreCapabilities.add.can, UploadCapabilities.add.can])
+ options.connection = this._serviceConf.upload
+ return uploadCAR(conf, car, options)
+ }
+
  /**
  * The current user agent (this device).
  */

src/types.ts

@@ -75,6 +75,7 @@ export type {
  RequestOptions,
  ListRequestOptions,
  ShardingOptions,
+ ShardStoringOptions,
  UploadOptions,
  FileLike,
  BlobLike

test/client.test.js

@@ -6,7 +6,7 @@ import * as Signer from '@ucanto/principal/ed25519'
 import * as StoreCapabilities from '@web3-storage/capabilities/store'
 import * as UploadCapabilities from '@web3-storage/capabilities/upload'
 import { AgentData } from '@web3-storage/access/agent'
-import { randomBytes } from './helpers/random.js'
+import { randomBytes, randomCAR } from './helpers/random.js'
 import { toCAR } from './helpers/car.js'
 import { mockService, mockServiceConf } from './helpers/mocks.js'
 import { File } from './helpers/shims.js'
@@ -160,6 +160,69 @@ describe('Client', () => {
  })
  })
 
+ describe('uploadCAR', () => {
+ it('uploads a CAR file to the service', async () => {
+ const car = await randomCAR(32)
+
+ /** @type {import('../src/types').CARLink?} */
+ let carCID
+
+ const service = mockService({
+ store: {
+ add: provide(StoreCapabilities.add, ({ invocation }) => {
+ assert.equal(invocation.issuer.did(), alice.agent().did())
+ assert.equal(invocation.capabilities.length, 1)
+ const invCap = invocation.capabilities[0]
+ assert.equal(invCap.can, StoreCapabilities.add.can)
+ assert.equal(invCap.with, space.did())
+ return {
+ status: 'upload',
+ headers: { 'x-test': 'true' },
+ url: 'http://localhost:9200'
+ }
+ })
+ },
+ upload: {
+ add: provide(UploadCapabilities.add, ({ invocation }) => {
+ assert.equal(invocation.issuer.did(), alice.agent().did())
+ assert.equal(invocation.capabilities.length, 1)
+ const invCap = invocation.capabilities[0]
+ assert.equal(invCap.can, UploadCapabilities.add.can)
+ assert.equal(invCap.with, space.did())
+ if (!invCap.nb) throw new Error('nb must be present')
+ assert.equal(invCap.nb.shards?.length, 1)
+ assert.equal(invCap.nb.shards[0].toString(), carCID.toString())
+ return invCap.nb
+ })
+ }
+ })
+
+ const server = createServer({
+ id: await Signer.generate(),
+ service,
+ decoder: CAR,
+ encoder: CBOR
+ })
+
+ const alice = new Client(
+ await AgentData.create(),
+ { serviceConf: await mockServiceConf(server) }
+ )
+
+ const space = await alice.createSpace()
+ await alice.setCurrentSpace(space.did())
+ await alice.uploadCAR(car, { onShardStored: meta => { carCID = meta.cid } })
+
+ assert(service.store.add.called)
+ assert.equal(service.store.add.callCount, 1)
+ assert(service.upload.add.called)
+ assert.equal(service.upload.add.callCount, 1)
+
+ assert(carCID)
+ assert.equal(carCID.toString(), car.cid.toString())
+ })
+ })
+
  describe('currentSpace', () => {
  it('should return undefined or space', async () => {
  const alice = new Client(await AgentData.create())