Repository navigation
Point users at canonical kubo/client/rpc library #9124
Description
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
- CI Test To Ensure New Commands Are Added To Official Clients #10178
- we notes from JS version: Automation to detect new Kubo commands js-kubo-rpc-client#47 – most likely the CI workflow could be reused between JS and GO.
Reacted by James Thesken and tekakutli
Activity
[-]Create go-kubo-rpc-client[/-][+]Create go-kubo-rpc-client library[/+]lidel commentedon Dec 9, 2022
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.
lidel commentedon May 22, 2023
Triage notes:
./clientdirectory in https://github.com/ipfs/kubo, to make it easie to refactor and clean up things later./client/go-ipfs-api./client/go-ipfs-http-clientMichaelMure commentedon May 22, 2023
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?
Jorropo commentedon May 22, 2023
@MichaelMure
go-ipfs-http-clientalready depends on libp2p https://github.com/ipfs/go-ipfs-http-client/blob/b19af5f15743e0923bae036babdf5437624142a7/go.mod#L11, this is required to provide better types thanstringeverywhere 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.lidel commentedon May 23, 2023
@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-clientor./client/httprpcor./client/kuborpcduring the move, to avoid renaming in the future?(one breaking change, instead of two)
BigLep commentedon May 23, 2023
2023-05-23 conversation:
./client/httprpclidel commentedon May 23, 2023
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:BigLep commentedon May 30, 2023
@Jorropo : do you have the corresponding PR for this?
Jorropo commentedon May 30, 2023
#9906
[-]Create go-kubo-rpc-client library[/-][+]Create canonical kubo/client/rpc library[/+][-]Create canonical kubo/client/rpc library[/-][+]Point users at canonical kubo/client/rpc library[/+]lidel commentedon Jun 15, 2023
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.
ElPaisano commentedon Aug 22, 2023
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?
lidel commentedon Aug 22, 2023
@ElPaisano good question!
We've had a release with
kubo/client/rpclibrary 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)
Jorropo commentedon Aug 22, 2023
https://github.com/ipfs/go-ipfs-api is not replaced by
kubo/client/rpc, ideally we would but the coreapi implemented bykubo/client/rpclacks some Kubo features and endpoints.kubo/client/rpcis a direct upgrade of https://github.com/ipfs/go-ipfs-http-client in all ways (it's a fork after all)BigLep commentedon Aug 22, 2023
kubo/client/rpcis 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.
ElPaisano commentedon Aug 22, 2023
sounds good, thanks all
BigLep commentedon Oct 5, 2023
2023-10-05 conversation: emphasis before IPFS Connect is just to make sure we're always pointing at the new thing.
hacdias commentedon Oct 13, 2023
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.