hypercore-protocol-substream
Independent virtual streams through a hypercore-protocol stream
Usage
Dedicated primary feed for communication
Creating a substream through a manually instantiated hypercore-protocol
instance.
const substream = const protocol = // Any buffer will effectively do for encryptionconst key = Bufferkey // Create a protocol stream with the substream extensionconst stream = // Create a primary feed with an encryption keyconst virtualFeed = stream // Initialize new virtual stream as namespace 'beef'const sub1 = // 'connected' event is fired when a virtual stream with the same// namespace have been initialized on the remote end.sub1 // A virtual stream is a regular full-duplex streamsub1sub1 // Ending the stream in one end, also signals end to the remote.sub1 // Create another substream using callback-style initializer // Don't forget to connect the main stream to a valid endpointstream
Using an existing feed for communication
Alternatively you can piggyback onto another core's replication stream
as long as it supports forwarding the extensions
hypercore-protocol option
on it's replicate()
method.
But you will also need to tell the hypercore replication stream to stay open
after it finished it's own replication, either by opening it in live
mode
or incrementing the stream.expectedFeeds
const realCore = realCore
Listening for incoming substreams
Once you have an initialize hypercore-protocol stream
with
the substream router installed.
You can listen for incoming streams without any prior knowledge of the namespace.
const connectionHandler = { if namespace == 'Awsomechat' } streamstream
( Please open an issue if you're interested in formalizing this feature, I'm not intending to use this myself right now. )
API
substream(protofeed, namespace, opts, callback')
protofeed
A hypercore-protocol feed
instance
or compatible that supports listening on
extension
events and sending extensions messages through extension(name, data)
namespace
a string or buffer identifying the channel.
opts
Object
timeout: 5000 // Time to wait for remote to answer the call. // causes 'HandshakeTimeoutError' error to be emitted
callback
optional function (error, virtualStream)
If provided, will be called when stream becomes either active or fails to initialize.
VirtualStream
event connected
Emitted when a connection has been established on both peer's ends.
Note: the sub stream is initialized in corked and paused state.
It is resumed and uncorked after the connected
event has been fired.
MainStream
event substream-discovered
Once your main stream has been initialized with the extension
substream.EXTENSION
- the substream-discovered
event will be fired
whenever a remote peer sends a handshake
MainStream
event substream-connected
Once your main stream has been initialized with the extension
substream.EXTENSION
- the substream-connected
event will be fired
whenever a virtual stream enters state ESTABLISHED
MainStream
event substream-disconnected
Once your main stream has been initialized with the extension
substream.EXTENSION
- the substream-connected
event will be fired
whenever an active virtual stream is disconnected either on your or the remote's
end.
License
MIT