⛔️ DEPRECATED: js-IPFS has been superseded by Helia
📚 Learn more about this deprecation or how to migrate
⚠️ If you continue using this repo, please note that security fixes will not be provided
ipfs-message-port-protocol
IPFS client/server protocol over message port
Table of contents
Install
$ npm i ipfs-message-port-protocolBrowser <script> tag
Loading this module through a script tag will make it's exports available as IpfsMessagePortProtocol in the global namespace.
<script src="https://unpkg.com/ipfs-message-port-protocol/dist/index.min.js"></script>Usage
Wire protocol codecs
This module provides encode / decode functions for types that are not supported by structured cloning algorithm and therefore need to be encoded before being posted over the message channel and decoded on the other end.
All encoders take an optional transfer array. If provided, the encoder will add all Transferable fields of the given value so they can be moved across threads without copying.
CID
Codecs for CID implementation in JavaScript.
import { CID, encodeCID, decodeCID } from 'ipfs-message-port-protocol/cid'
const cid = CID.parse('bafybeig6xv5nwphfmvcnektpnojts33jqcuam7bmye2pb54adnrtccjlsu')
const { port1, port2 } = new MessageChannel()
// Will copy underlying memory
port1.postMessage(encodeCID(cid))
// Will transfer underlying memory (cid is corrupt on this thread)
const transfer = []
port1.postMessage(encodeCID(cid, transfer), transfer)
// On the receiver thread
port2.onmessage = ({data}) => {
const cid = decodeCID(data)
data instanceof CID // => true
}DAGNode
Codec for DAGNodes accepted by ipfs.dag.put API.
import { encodeNode, decodeNode } from 'ipfs-message-port-protocol/dag'
const cid = CID('QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n')
const dagNode = { hi: 'hello', link: cid }
const { port1, port2 } = new MessageChannel()
// Will copy underlying memory
port1.postMessage(encodeNode(dagNode))
// Will transfer underlying memory (`dagNode.link` will be corrupt on this thread)
const transfer = []
port1.postMessage(encodeNode(dagNode, transfer), transfer)
// On the receiver thread
port2.onmessage = ({data}) => {
const dagNode = decodeNode(data)
dagNode.link instanceof CID // true
}AsyncIterable
This encoder encodes async iterables such that they can be transferred
across threads and decoded by a consumer on the other end while taking care of
all the IO coordination between two. It needs to be provided encoder /
decoder function to encode / decode each yielded item of the async iterable.
Unlike other encoders the transfer argument is mandatory (because async
iterable is encoded to a MessagePort that can only be transferred).
import { encodeIterable, decodeIterable } from 'ipfs-message-port-protocol/core')
const data = ipfs.cat('/ipfs/QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n')
const { port1, port2 } = new MessageChannel()
// Will copy each chunk to the receiver thread
{
const transfer = []
port1.postMessage(
encodeIterable(content, chunk => chunk, transfer),
transfer
)
}
// Will transfer each chunk to the receiver thread (corrupting it on this thread)
{
const transfer = []
port1.postMessage(
encodeIterable(
content,
(chunk, transfer) => {
transfer.push(chunk.buffer)
return chunk
},
transfer
),
transfer
)
}
// On the receiver thread
port2.onmessage = async ({data}) => {
for await (const chunk of decodeIterable(data)) {
chunk instanceof Uint8Array
}
}Callback
Primitive callbacks that take single parameter supported by structured cloning algorithm like progress callback used across IPFS APIs can be encoded / decoded. Unlike most encoders transfer argument is required (because value is encoded to a MessagePort that can only be transferred)
import { encodeCallback, decodeCallback } from 'ipfs-message-port-protocol/core'
const { port1, port2 } = new MessageChannel()
const progress = (value) => console.log(progress)
const transfer = []
port1.postMessage(encodeCallback(progress, transfer))
// On the receiver thread
port2.onmessage = ({data}) => {
const progress = decodeCallback(data)
// Invokes `progress` on the other end
progress(20)
}License
Licensed under either of
- Apache 2.0, (LICENSE-APACHE / http://www.apache.org/licenses/LICENSE-2.0)
- MIT (LICENSE-MIT / http://opensource.org/licenses/MIT)
Contribute
Contributions welcome! Please check out the issues.
Also see our contributing document for more information on how we work, and about contributing in general.
Please be aware that all interactions related to this repo are subject to the IPFS Code of Conduct.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
