Skip to content
This repository was archived by the owner on Feb 12, 2024. It is now read-only.

docs: update block api documentation #4124

Merged
merged 1 commit into from
Jun 10, 2022
Merged

docs: update block api documentation #4124

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 6 additions & 20 deletions docs/core-api/BLOCK.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ An optional object which may have the following keys:
| ---- | ---- | ------- | ----------- |
| timeout | `Number` | `undefined` | A timeout in ms |
| signal | [AbortSignal][] | `undefined` | Can be used to cancel any long running requests started as a result of this call |
| preload | `boolean` | `false` | Whether to preload all blocks created during this operation |

### Returns

Expand All @@ -63,7 +64,7 @@ A great source of [examples][] can be found in the tests for this API.

| Name | Type | Description |
| ---- | ---- | ----------- |
| block | A `Uint8Array` or [Block][] instance | The block or data to store |
| block | `Uint8Array` | The block of data to store |

### Options

Expand All @@ -73,19 +74,18 @@ An optional object which may have the following keys:
| ---- | ---- | ------- | ----------- |
| format | `String` | `'dag-pb'` | The codec to use to create the CID |
| mhtype | `String` | `sha2-256` | The hashing algorithm to use to create the CID |
| mhlen | `Number` | | |
| mhlen | `Number` | `undefined` | The hash length (only relevant for `go-ipfs`) |
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://github.com/ipfs/js-ipfs/blob/master/packages/ipfs-core-types/src/block/index.ts does not include this option. However, the go-ipfs CLI seems to support this option and found this mentions in this repository:

js-ipfs/packages/ipfs-cli/src/commands/block/put.js

Lines 34 to 37 in 548cfb2

mhlen: {
describe: 'multihash hash length',
default: undefined
},

js-ipfs/packages/ipfs-http-server/src/api/resources/block.js

Line 111 in 548cfb2

mhlen: Joi.number(),

  • Is this option relevant? Should it be removed?
  • Is it supported by js-ipfs or only go-ipfs?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not supported by js-ipfs and I'm not clear on what it even does for go-ipfs. It defaults to -1 which means.. 🤷

If you could find out the what and the why maybe we could even remove it entirely.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, it seems to be literally the multihash length, but doesn't seem to be very useful looking at the very limited search results. I tried figuring out if this was useful when opening this PR, but couldn't find anything that explained why it may be needed.

Copy link
Member

@lidel lidel Jun 6, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had to refactor relevant go-ipfs code around this recently and can provide some details.

afaik the only place where this is used, is when mhlen gets passed deep into go-multihash code responsible for digert (Sum) calculation: https://github.com/multiformats/go-multihash/blob/75ae3688857d036ea15947be9df68d3172b19470/sum.go

tldr:

  • -1 is the implicit default which means "set length based on hashing function output"
    • same applies to any value <=0
  • setting custom mhlen allows for truncating longer digests produces by alternative hash functions
  • setting it to longer than the default output of specific hash function will produce error

| version | `Number` | `0` | The version to use to create the CID |
| pin | `boolean` | `false` | If true, pin added blocks recursively |
| timeout | `Number` | `undefined` | A timeout in ms |
| signal | [AbortSignal][] | `undefined` | Can be used to cancel any long running requests started as a result of this call |

**Note:** If you pass a [`Block`][block] instance as the block parameter, you don't need to pass options, as the block instance will carry the CID value as a property.
| preload | `boolean` | `false` | Whether to preload all blocks created during this operation |

### Returns

| Type | Description |
| -------- | -------- |
| `Promise<Block>` | A [Block][block] type object, containing both the data and the hash of the block |
| `Promise<CID>` | A [CID][CID] type object containing the hash of the block |

### Example

Expand All @@ -96,21 +96,6 @@ const decoder = new TextDecoder()

const block = await ipfs.block.put(buf)

console.log(decoder.decode(block.data))
// Logs:
// a serialized object
console.log(block.cid.toString())
// Logs:
// the CID of the object

// With custom format and hashtype through CID
import { CID } from 'multiformats/cid'
import * as dagPB from '@ipld/dag-pb'
const buf = new TextEncoder().encode('another serialized object')
const cid = CID.createV1(dagPB.code, multihash)

const block = await ipfs.block.put(blob, cid)

console.log(decoder.decode(block.data))
// Logs:
// a serialized object
Expand Down Expand Up @@ -191,6 +176,7 @@ An optional object which may have the following keys:
| ---- | ---- | ------- | ----------- |
| timeout | `Number` | `undefined` | A timeout in ms |
| signal | [AbortSignal][] | `undefined` | Can be used to cancel any long running requests started as a result of this call |
| preload | `boolean` | `false` | Whether to preload all blocks created during this operation |

### Returns

Expand Down
13 changes: 0 additions & 13 deletions packages/ipfs-core-types/src/block/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,19 +32,6 @@ export interface API<OptionExtension = {}> {
* console.log(block.cid.toString())
* // Logs:
* // the CID of the object
*
* // With custom format and hashtype through CID
* import { CID } from 'multiformats/cid'
* const another = encoder.encode('another serialized object')
* const cid = CID.createV1(dagPB.code, multihash)
* const block = await ipfs.block.put(another, cid)
* console.log(decoder.decode(block.data))
*
* // Logs:
* // a serialized object
* console.log(block.cid.toString())
* // Logs:
* // the CID of the object
* ```
*/
put: (block: Uint8Array, options?: PutOptions & OptionExtension) => Promise<CID>
Expand Down