Point users at canonical kubo/client/rpc library
lidel opened this issue · 17 comments
Part of #8959 – based on discussions from IPFS Thing 2022
JS counterpart: #9125
Current state
We have two RPC clients for "GO-IPFS":
- https://github.com/ipfs/go-ipfs-api (the oldest one)
- https://github.com/ipfs/go-ipfs-http-client (more modern)
After renaming to Kubo, this state of things is arguably a really really bad user experience:
- Which RPC client should GO developers use to interact with Kubo?
- What is the reason to choose one over another?
Desired state
Ideally, we should have one Kubo client at https://github.com/ipfs/go-kubo-rpc-client
Keeping go- prefix is important because we want consistency across languages,
and Kubo team will maintain go-kubo-rpc-client too.
TODO
- decide if we need to maintain both libraries, or if one of them should be abandoned (or maybe create something totally new)
- People who may have relevant historical context: @Stebalien @hsanjuan @MichaelMure @magik6k
go-ipfs-apisupports more things, e.g. MFS.- Our CLI/RPC uses https://github.com/ipfs/go-ipfs-cmds/ – maybe use this directly and generate RPC based on implemented commands, like we generate docs https://github.com/ipfs/ipfs-docs/tree/main/tools/http-api-docs ?
- 👉 DECISION: move
go-ipfs-http-clientto Kubo repo askubo/client/rpc, and use it going forward.
- decide how to handle transition to minimize blast radius.
- 👉DECISION: keep old repos intact, and create a new one, forking
go-ipfs-http-client, making it "official" one.
- 👉DECISION: keep old repos intact, and create a new one, forking
- update docs to mention only the new client
- archive old clients
- update their README's and godocs to point at the new
go-kubo-rpc-client - archive repositories (but don't move them anywhere - we don't want to break existing code that depends on them)
- update their README's and godocs to point at the new
- #10178
- we notes from JS version: ipfs/js-kubo-rpc-client#47 – most likely the CI workflow could be reused between JS and GO.
Food for thought:
Our CLI for RPC over HTTP is built with https://github.com/ipfs/go-ipfs-cmds/
We use this library for generating docs at https://docs.ipfs.tech/reference/kubo/rpc/
(Generator code at https://github.com/ipfs/ipfs-docs/tree/main/tools/http-api-docs)
Would be really nice if we leveraged this somehow in HTTP client library.
Ideally, it would depend on Kubo, and generate client for commands based on go-ipfs-cmds annotations present in Kubo sources. Not sure how feasible this is, but someone wants to explore this, we could add more annotations if needed – prior art in #8802.
Triage notes:
- Talked with @Jorropo who suggested to deprecache & archive existing clients and move them to
./clientdirectory in https://github.com/ipfs/kubo, to make it easie to refactor and clean up things later- https://github.com/ipfs/go-ipfs-api →
./client/go-ipfs-api - https://github.com/ipfs/go-ipfs-http-client →
./client/go-ipfs-http-client
- https://github.com/ipfs/go-ipfs-api →
One not-so-nice aspect of this idea is that suddenly your API client depend on quite heavy and break prone dependencies like libp2p. Maybe consider at least a dedicated go.mod file?
@MichaelMure go-ipfs-http-client already depends on libp2p https://github.com/ipfs/go-ipfs-http-client/blob/b19af5f15743e0923bae036babdf5437624142a7/go.mod#L11, this is required to provide better types than string everywhere in the API (peer.ID, ...).
I'm not planning to move go-ipfs-api, as it's not a blocker for our CI and I don't want to have to think about two HTTP clients.
@Jorropo is go-ipfs-http-client the thing we want to support going forward?
If so, should we rename it to ./client/go-kubo-rpc-client or ./client/httprpc or ./client/kuborpc during the move, to avoid renaming in the future?
(one breaking change, instead of two)
2023-05-23 conversation:
- We are going to copy to
./client/httprpc - Add Kubo changelog.md
- go-ipfs-http-client: Add stubs
- go-ipfs-http-client: Add readme notice
- go-ipfs-http-client: archive the repo
Maybe let's just call it client/rpc? Will look less ugly, and will allow us to use websockets or webtransport behind the scenes if we ever need to opportunistically use other transport than plain HTTP:
kuboClient "github.com/ipfs/kubo/client/rpc"
node, err := kuboClient.NewLocalApi()Updated progress in the top comment + filled ipfs/go-ipfs-http-client#184 and ipfs/go-ipfs-api#296 based on my understanding of next steps.
Hi all, triaging old ipfs-docs issues right now and I came across Issue 1194: List other Kubo RPC API clients, which depends on this. It looks like work can't yet start on 1194?
@ElPaisano good question!
We've had a release with kubo/client/rpc library already, so I think we can move forward with this in sense that we no longer mention https://github.com/ipfs/go-ipfs-http-client and https://github.com/ipfs/go-ipfs-api and instead point users in docs and readmes to kubo/client/rpc which lives in this repo.
(This can happen without being blocked by ipfs/go-ipfs-http-client#184 and ipfs/go-ipfs-api#296)
https://github.com/ipfs/go-ipfs-api is not replaced by kubo/client/rpc, ideally we would but the coreapi implemented by kubo/client/rpc lacks some Kubo features and endpoints.
kubo/client/rpc is a direct upgrade of https://github.com/ipfs/go-ipfs-http-client in all ways (it's a fork after all)
kubo/client/rpc is the only thing we're supporting or investing in. Lets just point users there.
As a result, I agree with @lidel, that ipfs/ipfs-docs#1194 shouldn't be blocked. Carry on please @ElPaisano.
sounds good, thanks all
2023-10-05 conversation: emphasis before IPFS Connect is just to make sure we're always pointing at the new thing.
The only point remaining here is to create an automation to alert us when a new command is added, which I extracted to #10178. I think that is enough of its own thing to deserve its own issue. Therefore, I am closing this one. I think the main points (documentation, archiving repositories, directing to new clients) have been done.
If you find a wild mention to the old clients that we no longer want to support, feel free to submit a PR to replace the links.