feat: client perma cache

[vasco-santos]

This PR adds perma-cache client to client package. There are potential improvements on the pipeline (like converting given URLs to nftstorage.link if they are IPFS urls), but keeping scope smaller for initial implementation.

It includes:

• all 4 initial methods (put, delete, list, status)
  • Support for batching, retries, and rate limit control as needed
• smoke tests with mock API (we can move on later to spin up the actual API + DB + Gateway)
• workflow tests updated to run bundlesize and pre mocking
• client docs separated between scopes, one (unchanged) Markdown file for gateway utils and other for perma cache docs.

Closes #92

BREAKING CHANGE: GET /perma-cache/status renamed to /perma-cache/account

[alanshaw]

Suggested change

	put(urls: string[]): PromiseResult<PermaCacheEntry>[]>
	put(urls: string[]): Promise<PromiseResult<PermaCacheEntry>[]>

...although I'd be cautious exposing PromiseResult...You could make it a bit more erganomic by returning a custom type:

put(urls: string[]): Promise<CacheResult[]>

Where CacheResult is:

interface CacheSuccess {
  url: string
  size: number
  insertedAt: string
}

interface CacheFailure {
  url: string
  error: string
}

type CacheResult = CacheSuccess | CacheFailure

[vasco-santos]

Yeah, I think this is a good call 👍🏼

[alanshaw]

Suggested change

	delete(urls: string[]): PromiseResult<PermaCacheDeletedEntry>[]>
	delete(urls: string[]): Promise<PromiseResult<PermaCacheDeletedEntry>[]>

[alanshaw]

Same here:

delete(urls: string[]): Promise<CacheDeleteResult>

When is success false? It should be an error message no?

interface CacheDeleteSuccess {
  url: string
}

interface CacheDeleteFailure {
  url: string
  error: string
}

type CacheDeleteResult = CacheDeleteSuccess | CacheDeleteFailure

[alanshaw]

Since put, delete and list are top level I would have assumed status was relating to a cached item - i.e. for getting the cache status of a given URL, not getting account related information.

Suggested change

	status(): omise<PermaCacheStatus>
	accountInfo(): Promise<AccountInfo>

The endpoint should maybe be /account instead also?

[cloudflare-pages]

Deploying with    Cloudflare Pages

Latest commit:	57aaece
Status:	✅  Deploy successful!
Preview URL:	https://5536a151.nftstorage-link.pages.dev
Branch Preview URL:	https://feat-client-perma-cache.nftstorage-link.pages.dev

View logs

[vasco-santos]

@alanshaw renamed API route as you suggest, we are still in private beta. Thinking if we should keep /perma-cache/status for now as deprecated, or just get it out right away. What do you think?

[alanshaw]

@alanshaw renamed API route as you suggest, we are still in private beta. Thinking if we should keep /perma-cache/status for now as deprecated, or just get it out right away. What do you think?

It's the same response right? I'd maybe just stick a redirect in for now...

[alanshaw]

So, I'd do the error handling in this map, then you lose a level of indentation above and I think don't need the @ts-ignore:

Suggested change

	// @ts-ignore p-settle will always handle error internally
	return cacheResults.map((cacheResult) => cacheResult.value)
	return cacheResults.map((r, i) => {
	return r.reason ? { url: urls[i], error: r.reason.message } : r.value
	})

[alanshaw]

url should be in the response no?

Suggested change

	return {
	...res,
	url, // decoded
	}
	return res

[vasco-santos]

yeah, the issue was in the mock 🤦🏼

[alanshaw]

Bah, maybe just while(true), move entry yielding above this conditional and break if !link?