@push-stream-std/push-handshake (0.0.7)
Installation
@push-stream-std:registry=https://hub.kl1.tenere.ai/api/packages/push-stream-std/npm/npm install @push-stream-std/push-handshake@0.0.7"@push-stream-std/push-handshake": "0.0.7"About this package
@push-stream-std/push-handshake
Create handshakes for binary protocols with push streams.
Published as @push-stream-std/push-handshake.
Synopsis
import handshake, { createMockDuplex } from '@push-stream-std/push-handshake';
const duplex = createMockDuplex();
const hs = handshake(duplex, { timeout: 5000 }, (err) => {
if (err) console.error('handshake failed:', err);
else console.log('handshake complete');
});
hs.handshake.write(Buffer.from([0x01, 0x00])); // send protocol version
hs.handshake.read(2, (err, buf) => {
if (err) return console.error('read failed:', err);
console.log('server responded:', buf); // Buffer [0x02, 0x00]
const rest = hs.handshake.rest();
rest.sink.write(Buffer.from('hello over stream'));
});
Install
npm config set @push-stream-std:registry https://hub.kl1.tenere.ai/api/packages/push-stream-std/npm/
npm config set -- //hub.kl1.tenere.ai/api/packages/push-stream-std/npm/:_authToken "$PACKAGE_TOKEN"
npm install @push-stream-std/push-handshake
Why
Provides a structured handshake mechanism for binary push-stream protocols. You write data to the stream, read specific byte lengths from the stream, and when the handshake is done, call rest() to get the raw duplex stream for the remainder of the connection. Supports optional timeout. Reads are buffered — if not enough data is available, the read callback is queued until more data arrives. The callback passed to handshake() fires exactly once when rest() is called or on error.
API
handshake(duplex, [callback], [opts])
handshake(duplex, [opts], [callback])
handshake([callback], [opts])
duplex- Stream withonDatasetter and optionalsink.write. If omitted, a mock duplex is created.callback-function(err)- Called exactly once on handshake completion or error.opts.timeout-number- Timeout in milliseconds. If the handshake does not complete in time, pending reads and the callback are called with a timeout error.
Returns { handshake: { read, write, abort, rest } }.
handshake.read(length, callback)
length- Number of bytes to read.callback-function(err, buffer)- Called with the read bytes when enough data is buffered.
handshake.write(buffer)
buffer- Buffer to write to the duplex sink.
handshake.abort(err)
err- Error to abort with. Calls all pending read callbacks and the handshake callback with the error.
handshake.rest()
Completes the handshake and returns the duplex stream for further use. The handshake callback fires with no error. Reads or writes after calling rest() will fail. Idempotent — multiple calls return the same duplex.
createMockDuplex()
Creates a mock duplex stream for testing or standalone use. Supports write(data), end(err), abort(err), and the onData setter. Writes before onData is set are buffered and replayed.
Tests
npm test
Tests cover basic handshake creation, write/read interfaces, buffered reads across multiple chunks, multiple writes before reads, rest() idempotency, abort with pending reads, createMockDuplex buffering, timeout handling, and edge cases (exact boundary reads, read after rest).
Requirements
Node.js 22 or later. ESM only.