# DATAWHEREHOUSE

> or... where is that CAR parked?

## Background

1. We're missing a mapping of CAR CID -> bucket URI.
2. We don't have bucket events in Cloudflare, so need the client to tell us when it has uploaded something.
3. We don't want clients to create location claims for internal bucket URLs because we might change the location in the future (reputation hit for client).
4. We want freeway code to be usable in Saturn nodes, so ideally it uses only content claims to discover locations.

## High level proposed solution

* Simulate bucket event by having client submit `store/confirm` invocation.
* Capability name TBC!
* Confirms successful transfer of data.
* Effect linked by `store/add` receipt.
* Can be batched with other invocations like `filecoin/offer`
* store/confirm handler writes to carwhere
* CAR CID -> bucket mapping table
* Materialize location claims on demand for CAR CID from data in table. Short lived so we can change location and not have to revoke 1,000's of UCANs.

## carwhere store design

carwhere is a store that enables a `store/*` implementer to map CAR CIDs to one or more locations where they are written (and confirmed!).

The store should be indexed and queryable by CAR CID, but should also support multiple entries with CAR CID. Therefore, we have two potential solutions for this Store:
- Bucket store with format as `${carCid}/${bucketName}/${key}`. So, quite similar to current Dudewhere indexes. E.g. `bag.../carpark-prod-0/bag.../bag....key`
- DynamoDB store where partition key is `${carCid}` and `${bucketName}/${key}`

From a price standpoint, as well as ease of storage migration, Bucket store will be way cheaper. However, dynamoDB will be faster for high throughputs. Given the index read will likely be one of the less costly parts of reading content, it MAY not make a big difference to read from the indexes. Specially as we will have full content cached later on.

Proposal: Bucket Store

## commit storage

Confirmation of storage successful MUST be invoked for the system to put the necessary indexes in place for reads, i.e. fill up carwhere store. This invocation SHOULD be linked with trigger invocation via an effect.

There are a few alternatives for capability naming already, such as:
- `store/added`
- `store/confirm`
- `store/commit`

(will use `store/confirm` until decision)

For `store/add` to have a join effect of storage commited, the effect should be issued by the service, given service will need to compute the task effect CID to return within `store/add` handler. However, it is under the control of the issuer of `store/add` to know when the file was stored into the provided presigned URL in `store/add` receipt. There are two ways we can facilitate linking of `store/add` to confirming storage:
- have issuer of `store/add` to also invoke `store/confirm`, while service when executing `store/confirm` issued by client MAY verify if the content is really in the bucket before self issuing `store/confirm` as well to map out to the effect of task CID. In the self issued handler, the index would actually be written as it is trusted to be previously validated by service.
- not have issuer of `store/add` to also invoke `store/confirm`. We can have a queue that periodically performs a HEAD request to check if content was stored (expires on presigned url expiration date). Once the content is there, service self invokes `store/confirm` to make it available in the network via its index.

While second option would not need user request, it would likely be more costly with multiple HEAD requests until ready (specially for big files), as well as more slow. Intervals between attempts could lead more time until content being retrievable.


Proposal: `store/confirm` with issuer invoking it, followed by service to self invoke it.

## Materialize location claims

Extend materialized location claims to include carwhere locations short lived. We will need to align on how these claims will look like. See https://hackmd.io/5qyJwDORTc6B-nqZSmzmWQ#Client-location-claims-proposal for inspiration for URIs.

## Plan

### P0
- implement `store/confirm` handler
- invoke `store/confirm` from client
- materialize location claims to include these
- migrate all `carpark-prod-0` into the store (or fallback into `carpark-prod-0` if not available)

### P1
- Abstract freeway to be deployable in saturn nodes

## Questions/Notes