Support for /refs endpoints

[aphelionz]

References:

• https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/refs.js
• https://docs-beta.ipfs.io/reference/http/api/#api-v0-refs
• https://github.com/ipfs/interop (no occurrences)

/refs

List links (references) from an object.
curl "http://localhost:5001/api/v0/refs?arg=<ipfs-path>&format=<dst>&edges=<value>&unique=<value>&recursive=<value>&max-depth=-1"

• Requires object.put Need to refactor tests.
• Arguments
  • arg [string]: Path to the object(s) to list refs from. Required: yes.
  • format [string]: Emit edges with given format. Available tokens: . Default: . Default: "". Required: no.
  • edges [bool]: Emit edge format: -> . Required: no.
  • unique [bool]: Omit duplicate refs from output. Required: no.
  • recursive [bool]: Recursively list links of child nodes. Required: no.
  • max-depth [int]: Only for recursive refs, limits fetch and listing to the given depth. Default: "-1". Required: no.
• On success, the call to this endpoint will return with 200 and the following body:

{
  "Err": "<string>",
  "Ref": "<string>"
}

/refs/local

List all local references.
curl "http://localhost:5001/api/v0/refs/local"

• Test requires IPFS add, perhaps we can refactor to ipfs.dag.put
• This endpoint takes no arguments.
• On success, the call to this endpoint will return with 200 and the following body:

{
  "Err": "<string>",
  "Ref": "<string>"
}

[aphelionz]

@vmx and @hugomrdias Looks like these interface tests use the object api. Should we plan to refactor those to /block?

[hugomrdias]

yes

[aphelionz]

@hugomrdias @vmx Forgive the potentially very basic question, but what is the transliteration between ipfs.add and ipfs.block.put, and also ipfs.object.put and ipfs.block.put? Default options are OK. I have the tests refactored and working but I'm 99.999999% sure I didn't do it correctly. For example in the refs.local tests:

- await all(ipfs.add(dirs))
+ await all(dirs.map(dir => ipfs.block.put(dir.content)))

[vmx]

but what is the transliteration between ipfs.add and ipfs.block.put

They do different things:

• ipfs.add() adds files, which includes chunking, which leads to several blocks.
• ipld.blockput()` adds a single already encoded block.

ipfs.object.put and ipfs.block.put

You could think of ipfs.object.put() as adding a not yet encoded DagPB node. ipfs.block.put() puts an already encoded block. So if you want to use ipfs.block.put() instead of ipfs.object.put(), you would take the input ipfs.object.put() takes, encode it with IPLD and use that encoded block as parameter for ipfs.block.put().

[aphelionz]

In terms of ipfs.add, would it be acceptable them to change the hashes in the tests so that they match the output?

[vmx]

Without having a closer look, I'd expect that ipfs.add() calls could be replaces with simpler ipfs.block.put() calls while still testing the same thing.

[aphelionz]

Ok, I'll be making a PR to that effect then 👍

[aphelionz]

A number of PRs were made to js-ipfs

• Refactor refs-local to not use ipfs.add ipfs/js-ipfs#2980
• chore: remove second greaterThanZero check from block.rm test ipfs/js-ipfs#2983
• Refactor refs tests ipfs/js-ipfs#2972
• test: make refs tests iteration order independent ipfs/js-ipfs#2982