Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

IPIP-356: IPFSClient API #356

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

IPIP-356: IPFSClient API #356

wants to merge 3 commits into from

Conversation

markg85
Copy link

@markg85 markg85 commented Dec 15, 2022

Draft for sure!

This spec is intended to specify how a "ipfsclient" works.
It relies on 3 different specs:

  1. IPIP-0280 (gateways file)
  2. IPIP-0000 (multi gateway client. This spec defines how gateways are determined to be used and use them)
  3. IPIP-0000 (using gateways. This spec defines how an application can find and use gateways)

The missing specs will be on github later. Will update this message when they are online.

@Winterhuman
Copy link

Maybe the doc should mention Cache-Control: only-if-cached (ipfs/kubo#9082) as the recommended way to contact gateways initially? Sending requests to multiple gateways seems wasteful if a gateway in the list already has the data and can begin sending content immediately

@markg85
Copy link
Author

markg85 commented Dec 16, 2022

Maybe the doc should mention Cache-Control: only-if-cached (ipfs/kubo#9082) as the recommended way to contact gateways initially? Sending requests to multiple gateways seems wasteful if a gateway in the list already has the data and can begin sending content immediately

Perhaps. But that would be the job of #359 :) You couldn't have known, that spec wasn't on github yet when you made the comment.

This spec will do no gateway managing on it's own!
Or in different terms, the way the function required Error ipfs(&Url ipfs_url); would be implemented would be through following #359.

Technically in terms of code it will all live in the same repository. Spec wise it's separated.


## Motivation

There is a need for places that can't quite run full IPFS nodes to still have a great IPFS experience. This could be a multitude of reasons (like constrained network resources, lower powered hardware, etc...). Using a gateway one can already IPFS content in a read-only manner, which is enough for many usecases. With mutiple gateways this approach becomes very distributed.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using a gateway one can already IPFS content
Grammer nit: should be "Using a gateway one can already access IPFS content"

}
```

Without this convenience wrapper you'd have to manually check if the type is `WEB` (in this example case) that can now be abstracted awar in the `error` function itself.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: awar => away


### interface Url

The Url object will contain 1 URL that is schema valid for the URL structure. Libraries and tools often already have a Url class that does this for you. Rust for example has the Url class too that should be used in this context. In C++ land with Qt as framework, there is the QUrl class to allow URL validation.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Links to the references URL classes per language could be a nice addition here


The network interface API is intended to be an interface to the API. It's implementation must come from the client application. The reasoning here is that each application implementing this API and/or the client application likely has their own network functionality already that should be reused for handing network traffic.

An example of how these functions are to be used from an API point fo view is as follows:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: fo => of

}
```

The below details to implement this interface are for the client implementation ony. The API implementations can ignore this part.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: ony => only

The library will call this function in an async matter. This will be up to the number defined in `Api.gateway_concurrency`. That effectively defines how many different gateways will potentially be used.

**Parameters**
`CID cid` is the `CID` we want to get the date from. Note that in multiple requests for the same `CID` this value will remain the same. The `http_url` will differ.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

date => data

@lidel lidel changed the title IPIP-0000: IPFSClient API IPIP-356: IPFSClient API Jan 19, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: 🏃 In Progress
Development

Successfully merging this pull request may close these issues.

3 participants