multiformats / multiformats/js-multiformats

Proposal: Reconsider .code / .name fields of BlockEncoder / BlockDecoder

Open
#177 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
268
Forks
57
PR merge metrics
No merged PRs in 30d

Description

I find .code filed and .name (to lesser degree) fields on following interfaces to be troublesome

https://github.com/multiformats/js-multiformats/blob/9bcd7fef62888d7cefe8e4f5e929d4e3c9dadda9/src/codecs/interface.ts#L4-L15

Problem is that it prevents one from defining codec composition without introducing subtle footgun. For example dag-ucan in theory could be composition of dag-cbor and raw codecs, meaning it could decode block in either cbor or raw encoding and similarly encode node either in cbor or raw representation (depending on UCAN specific nuances).

This double representation is an implementation detail currently hidden under new 0x78c0 multicodec code https://github.com/multiformats/multicodec/pull/264.

Given the arguments in the thread I have considered dropping new code and make an implementation that is UCAN specialized BlockCodec<0x71|0x55> codec. However there are some interesting challenges:

  1. .code could be either 0x71 or 0x55, while type checker would be happy with either option it is misleading because it is common to use that code field when creating cids e.g.:
    https://github.com/multiformats/js-multiformats/blob/9bcd7fef62888d7cefe8e4f5e929d4e3c9dadda9/src/block.js#L148-L150
  2. I think this is a symptom of a broader problem I've experienced in different contexts. Result of encode carries no information about codec. Probably why I find myself resorting to { code, bytes } whenever I want to defer async CID creation.

Unfortunately I see no way to address this in backwards compatible manner. Maybe we could introduce MultiblockEncoder along the side of BlockEncoder similar to how we have MultibaseEncoder producing prefixed values and BaseEncoder without prefix:

https://github.com/multiformats/js-multiformats/blob/9bcd7fef62888d7cefe8e4f5e929d4e3c9dadda9/src/bases/interface.ts#L4-L14

https://github.com/multiformats/js-multiformats/blob/9bcd7fef62888d7cefe8e4f5e929d4e3c9dadda9/src/bases/interface.ts#L48-L62


Maybe this is even broader issue of having multicodes in address as opposed to data itself. E.g if we tagged encoded bytes themself with multihash all the IR representations would naturally be represented although that ship has probably sailed a long ago.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with src/codecs/interface.ts and src/block.js, then compare the related encoder interfaces in src/bases/interface.ts and src/hashes/interface.ts. Determine whether the proposed codec representation can be changed without breaking existing CID creation, and document a settled API direction with its compatibility impact.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
18/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.