Point users at canonical kubo/client/rpc library

[lidel]

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-api supports 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-client to Kubo repo as kubo/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.
• update docs to mention only the new client
  • docs: clean mentions of go-ipfs-api, go-ipfs-http-api #10176
  • Clean Kubo Client Story and Deprecated Packages ipfs-docs#1731
• 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)
    • Archive this repo and move remaining issues to ipfs/kubo go-ipfs-http-client#184
    • Archive this repo and point users at kubo/client/rpc go-ipfs-api#296
• 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.

cc @2color @BigLep @Jorropo @ajnavarro

[lidel]

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]

Triage notes:

• Talked with @Jorropo who suggested to deprecache & archive existing clients and move them to ./client directory 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

[MichaelMure]

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]

@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.

[lidel]

@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)

[BigLep]

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

[lidel]

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()

[BigLep]

@Jorropo : do you have the corresponding PR for this?

[Jorropo]

do you have the corresponding PR for this?

#9906

[lidel]

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]

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]

@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)

[Jorropo]

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)

[BigLep]

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.

[ElPaisano]

sounds good, thanks all

[BigLep]

2023-10-05 conversation: emphasis before IPFS Connect is just to make sure we're always pointing at the new thing.

[hacdias]

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.