docs(kubo-rps): describe JSONL returned by /api/vo/dag/import

[smoyer64]

Describe your changes

As described in #1980, the JSON body for the /api/v0/dag/import command is actually JSONL is the stats=true argument is included.

Files changed

• docs/reference/kubo/rpc.md

What issue(s) does this address?

• The documented JSON output for /api/v0/dag/import is incorrect #1980

Does this update depend on any other PRs?

No

Checklist before requesting a review

• Passing the beta version of the Check Markdown links for modified files check. Action results can be viewed here.

Checklist before merging

• Passing all required checks (The beta Check Markdown links for modified files check is not required)

[welcome]

Thank you for submitting this PR!
A maintainer will be here shortly to review it.
We are super grateful, but we are also overloaded! Help us by making sure that:

• The context for this PR is clear, with relevant discussion, decisions and stakeholders linked/mentioned.
• Your contribution itself is clear (grammar and spelling checked, any code blocks checked and commented) and in its best form. Follow the docs contribution guidelines if they apply.

Getting other community members to do a review would be great help too on complex PRs (you can ask in the chats/forums). If you are unsure about something, just leave us a comment.
Next steps:

• A maintainer will triage and assign priority to this PR, commenting on any missing things and potentially assigning a reviewer for high priority items.
• The PR gets reviews, discussed and approvals as needed.
• The PR is merged by maintainers when it has been approved and comments addressed.

We currently aim to provide initial feedback/triaging within two business days. Please keep an eye on any labelling actions, as these will indicate priorities and status of your contribution.
We are very grateful for your contribution!

[2color]

Thanks for the PR @smoyer64. I can confirm that two separate JSON objects are returned, in what seems to be like ndjson, though I'm not sure if that's actually deliberate.

Either way, this can't be merged, because these docs are actually autogenerated:

ipfs-docs/docs/reference/kubo/rpc.md

Lines 50 to 53 in ff99b4d

	::: tip Generated on 2024-11-26, from kubo v0.32.1
	This document was autogenerated from [v0.32.1](https://github.com/ipfs/kubo/releases/tag/v0.32.1).
	For issues and support, check out the [http-api-docs](https://github.com/ipfs/ipfs-docs/tree/main/tools/http-api-docs) generator on GitHub.
	:::

@lidel I haven't been able to figure out exactly how the docs are generated, but it seems it's a combination of:

• https://github.com/ipfs/ipfs-docs/tree/main/tools/http-api-docs
• https://github.com/ipfs/go-ipfs-cmds
• https://github.com/ipfs/kubo/blob/f41b190e1b526ea2baa37f1ab991b7eba7b48790/core/commands/dag/dag.go#L171-L251

[smoyer64]

I AM SERIOUS, DO NOT EDIT ANYTHING BELOW ;-D

Well that was an epic fail ... I searched for the title line for that command and never scrolled up to see I was about to fail :)

I'll amend this PR (or replace it) once I figure out how the code generation works. I believe this file was generated by the tool(s) at the first link you referenced ... and it appears to be keyed off this output type: https://github.com/ipfs/kubo/blob/f41b190e1b526ea2baa37f1ab991b7eba7b48790/core/commands/dag/dag.go#L205

That type is defined as https://github.com/ipfs/kubo/blob/f41b190e1b526ea2baa37f1ab991b7eba7b48790/core/commands/dag/dag.go#L63-L66

Which makes me think that

though I'm not sure if that's actually deliberate.

might be very prescient. I ran the equivalent command using the IPFS CLI and captured the response packet using WireShark. The response is two chunks each with a complete JSON document:

I'll wait for @lidel to respond so I don't waste time chasing this.

P.S. I asked my team members and they're vaguely remembering other places where the response is JSONL - so far, we haven't found those examples (yet).

[smoyer64]

One point for this being the intended behavior is that if I import two CAR files, I get two Root responses and one Stats response. I'm not exactly sure how we'd show this in documentation based on how (I think) the generator works:

[smoyer64]

This code also makes me think this behavior is intentional. And I therefore think that the problem is that the CarImportOutput type is NOT actually used to produce the response and that the problem is that the documentation generation tool can't represent the output of this code, which will generate a JSONL (aka ndJSON) "record" for each CAR file's 'Root' as well as an optional record for the Stats

[lidel]

@smoyer64 your analysis is correct, I've added more context in #1980 (comment).

I'm closing this PR because the fix needs to happen elsewhere.
Let's continue in #1980