# `@web3-storage/access-api` data storage

## Purpose of this Document

* Explain how [`@web3-storage/access-api`](https://github.com/web3-storage/w3up/tree/main/packages/access-api) stores data today.
* https://github.com/web3-storage/w3up/issues/684
* Enable planning of how to scale the service

## access-api invocation handlers

not exhaustive. these are the recent ones that interact with data stores.

* [`provider/add`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/service/provider-add.js#L26)
* [`access/delegate`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/service/access-delegate.js#L62)
* asserts [`hasStorageProvider({ consumer: space })`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/service/access-delegate.js#L66)
* then [putMany](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/service/access-delegate.js#L75) delegations
* [`access/claim`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/service/access-claim.js#L35)
* retrieves stored delegations
* select by delegation `audience`
* may need to sort/filter by expiry

## access-api operations that interact with data stores

* [`DelegationsStorage#find`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/types/delegations.ts#L35)
* [`DbDelegationsStorageWithR2#find`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/models/delegations.js#L117)
* [`DelegationsStorage#putMany`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/types/delegations.ts#L16)
* [`DbDelegationsStorageWithR2#putMany`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/models/delegations.js#L95)
* [`DelegationsStorage#count`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/types/delegations.ts#L23)
* [`DbDelegationsStorageWithR2#count`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/models/delegations.js#L110)

* [`ProvisionsStorage#hasStorageProvider(consumer: DID<'key'>)`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/types/provisions.ts#L21)
* [`DbProvisions#hasStorageProvider`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/models/provisions.js#L189)
* [`ProvisionsStorage#put({ invocation, space, account, provider })`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/types/provisions.ts#L27)
* [`DbProvisions#put`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/models/provisions.js#L110)
* there is currently not

## access-api data stores

### Cloudflare D1 (sqlite-ish)

* [`delegations_v3`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/migrations/0007_add_delegations_v3.sql#L10)
* [`provisions`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/migrations/0006_add_storage_provider_consumer_schema.sql#L11) - result of `provider/add`

Other tables, not used by `access/*` or `provider/*`

* [`accounts`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/migrations/0004_add_accounts_table.sql#L3) - not needed (at all afaict)
* [`spaces`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/migrations/0003_space.metadata_can_be_null.sql#L6)
* may not be needed - depends on `space/info` et al expectations
* spaces registered by `provider/add` only return `space/info` `{ did }`
* This doesn't require `spaces` table
* spaces registered by `voucher/` would returns essentially this whole row.

### Cloudflare R2 (s3-ish)

* `DbDelegationsStorageWithR2` [stores the bytes of the delegations in r2](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/models/delegations.js#L153) and CIDs-only in d1
* at key `/delegations/{ucan.cid.toString(base32)}.car`

## opportunities to use ucan-stream

* reduce `access/delegate` invocations into an index that can serve `access/claim`
* alternative to `access/claim` [calling](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/service/access-claim.js#L40) [`DbDelegationsStorageWithR2#find`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/models/delegations.js#L117)
* write to
* if dynamodb, should probably account for expiry sort key at same time (via @mikeal)
* May not need dynamodb. We could group by audience and write to s3

* reduce `provider/add` receipts into an index that can answer whether a given space has at least one storage provider of a certain provider did
* alternative to `access/delegate` [calling](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/service/access-delegate.js#L66) [`DbProvisions#hasStorageProvider`](https://github.com/web3-storage/w3up/blob/main/packages/access-api/src/models/provisions.js#L189)