@libp2p/yamux 7.0.4

package/src/errors.ts

@@ -0,0 +1,89 @@
+import { GoAwayCode } from './frame.ts'
+
+export class ProtocolError extends Error {
+  static name = 'ProtocolError'
+
+  public reason: GoAwayCode
+
+  constructor (message: string, reason: GoAwayCode) {
+    super(message)
+    this.name = 'ProtocolError'
+    this.reason = reason
+  }
+}
+
+export function isProtocolError (err?: any): err is ProtocolError {
+  return err?.reason !== null
+}
+
+export class InvalidFrameError extends ProtocolError {
+  static name = 'InvalidFrameError'
+
+  constructor (message = 'The frame was invalid') {
+    super(message, GoAwayCode.ProtocolError)
+    this.name = 'InvalidFrameError'
+  }
+}
+
+export class UnRequestedPingError extends ProtocolError {
+  static name = 'UnRequestedPingError'
+
+  constructor (message = 'Un-requested ping error') {
+    super(message, GoAwayCode.ProtocolError)
+    this.name = 'UnRequestedPingError'
+  }
+}
+
+export class NotMatchingPingError extends ProtocolError {
+  static name = 'NotMatchingPingError'
+
+  constructor (message = 'Not matching ping error') {
+    super(message, GoAwayCode.ProtocolError)
+    this.name = 'NotMatchingPingError'
+  }
+}
+
+export class InvalidStateError extends Error {
+  static name = 'InvalidStateError'
+
+  constructor (message = 'Invalid state') {
+    super(message)
+    this.name = 'InvalidStateError'
+  }
+}
+
+export class StreamAlreadyExistsError extends ProtocolError {
+  static name = 'StreamAlreadyExistsError'
+
+  constructor (message = 'Stream already exists') {
+    super(message, GoAwayCode.ProtocolError)
+    this.name = 'StreamAlreadyExistsError'
+  }
+}
+
+export class DecodeInvalidVersionError extends ProtocolError {
+  static name = 'DecodeInvalidVersionError'
+
+  constructor (message = 'Decode invalid version') {
+    super(message, GoAwayCode.ProtocolError)
+    this.name = 'DecodeInvalidVersionError'
+  }
+}
+
+export class BothClientsError extends ProtocolError {
+  static name = 'BothClientsError'
+
+  constructor (message = 'Both clients') {
+    super(message, GoAwayCode.ProtocolError)
+    this.name = 'BothClientsError'
+  }
+}
+
+export class ReceiveWindowExceededError extends ProtocolError {
+  static name = 'ReceiveWindowExceededError'
+
+  constructor (message = 'Receive window exceeded') {
+    super(message, GoAwayCode.ProtocolError)
+    this.name = 'ReceiveWindowExceededError'
+  }
+}

package/src/frame.ts

@@ -0,0 +1,64 @@
+export enum FrameType {
+  /** Used to transmit data. May transmit zero length payloads depending on the flags. */
+  Data = 0x0,
+  /** Used to updated the senders receive window size. This is used to implement per-session flow control. */
+  WindowUpdate = 0x1,
+  /** Used to measure RTT. It can also be used to heart-beat and do keep-alive over TCP. */
+  Ping = 0x2,
+  /** Used to close a session. */
+  GoAway = 0x3
+}
+
+export enum Flag {
+  /** Signals the start of a new stream. May be sent with a data or window update message. Also sent with a ping to indicate outbound. */
+  SYN = 0x1,
+  /** Acknowledges the start of a new stream. May be sent with a data or window update message. Also sent with a ping to indicate response. */
+  ACK = 0x2,
+  /** Performs a half-close of a stream. May be sent with a data message or window update. */
+  FIN = 0x4,
+  /** Reset a stream immediately. May be sent with a data or window update message. */
+  RST = 0x8
+}
+
+const flagCodes = Object.values(Flag).filter((x) => typeof x !== 'string') as Flag[]
+
+export const YAMUX_VERSION = 0
+
+export enum GoAwayCode {
+  NormalTermination = 0x0,
+  ProtocolError = 0x1,
+  InternalError = 0x2
+}
+
+export const HEADER_LENGTH = 12
+
+export interface FrameHeader {
+  /**
+   * The version field is used for future backward compatibility.
+   * At the current time, the field is always set to 0, to indicate the initial version.
+   */
+  version?: number
+  /** The type field is used to switch the frame message type. */
+  type: FrameType
+  /** The flags field is used to provide additional information related to the message type. */
+  flag: number
+  /**
+   * The StreamID field is used to identify the logical stream the frame is addressing.
+   * The client side should use odd ID's, and the server even.
+   * This prevents any collisions. Additionally, the 0 ID is reserved to represent the session.
+   */
+  streamID: number
+  /**
+   * The meaning of the length field depends on the message type:
+   * Data - provides the length of bytes following the header
+   * Window update - provides a delta update to the window size
+   * Ping - Contains an opaque value, echoed back
+   * Go Away - Contains an error code
+   */
+  length: number
+}
+
+export function stringifyHeader (header: FrameHeader): string {
+  const flags = flagCodes.filter(f => (header.flag & f) === f).map(f => Flag[f]).join('|')
+  return `streamID=${header.streamID} type=${FrameType[header.type]} flag=${flags} length=${header.length}`
+}

package/src/index.ts

@@ -0,0 +1,90 @@
+/**
+ * @packageDocumentation
+ *
+ * This module is a JavaScript implementation of [Yamux from Hashicorp](https://github.com/hashicorp/yamux/blob/master/spec.md) designed to be used with [js-libp2p](https://github.com/libp2p/js-libp2p).
+ *
+ * @example Configure libp2p with Yamux
+ *
+ * ```typescript
+ * import { createLibp2p } from 'libp2p'
+ * import { yamux } from '@libp2p/yamux'
+ *
+ * const node = await createLibp2p({
+ *   // ... other options
+ *   streamMuxers: [
+ *     yamux()
+ *   ]
+ * })
+ * ```
+ *
+ * @example Using the low-level API
+ *
+ * ```js
+ * import { yamux } from '@libp2p/yamux'
+ * import { pipe } from 'it-pipe'
+ * import { duplexPair } from 'it-pair/duplex'
+ * import all from 'it-all'
+ *
+ * // Connect two yamux muxers to demo basic stream multiplexing functionality
+ *
+ * const clientMuxer = yamux({
+ *   client: true,
+ *   onIncomingStream: stream => {
+ *     // echo data on incoming streams
+ *     pipe(stream, stream)
+ *   },
+ *   onStreamEnd: stream => {
+ *     // do nothing
+ *   }
+ * })()
+ *
+ * const serverMuxer = yamux({
+ *   client: false,
+ *   onIncomingStream: stream => {
+ *     // echo data on incoming streams
+ *     pipe(stream, stream)
+ *   },
+ *   onStreamEnd: stream => {
+ *     // do nothing
+ *   }
+ * })()
+ *
+ * // `p` is our "connections", what we use to connect the two sides
+ * // In a real application, a connection is usually to a remote computer
+ * const p = duplexPair()
+ *
+ * // connect the muxers together
+ * pipe(p[0], clientMuxer, p[0])
+ * pipe(p[1], serverMuxer, p[1])
+ *
+ * // now either side can open streams
+ * const stream0 = clientMuxer.newStream()
+ * const stream1 = serverMuxer.newStream()
+ *
+ * // Send some data to the other side
+ * const encoder = new TextEncoder()
+ * const data = [encoder.encode('hello'), encoder.encode('world')]
+ * pipe(data, stream0)
+ *
+ * // Receive data back
+ * const result = await pipe(stream0, all)
+ *
+ * // close a stream
+ * stream1.close()
+ *
+ * // close the muxer
+ * clientMuxer.close()
+ * ```
+ */
+
+import { Yamux } from './muxer.js'
+import type { YamuxMuxer, YamuxMuxerInit } from './muxer.js'
+import type { StreamMuxerFactory } from '@libp2p/interface'
+
+export { GoAwayCode } from './frame.js'
+export type { FrameHeader, FrameType } from './frame.js'
+export type { YamuxMuxerInit }
+
+export function yamux (init: YamuxMuxerInit = {}): () => StreamMuxerFactory<YamuxMuxer> {
+  return () => new Yamux(init)
+}