@libp2p/webrtc 2.0.2 → 2.0.4

package/src/stream.ts

@@ -1,30 +1,22 @@
+import { AbstractStream, type AbstractStreamInit } from '@libp2p/interface-stream-muxer/stream'
+import { CodeError } from '@libp2p/interfaces/errors'
 import { logger } from '@libp2p/logger'
 import * as lengthPrefixed from 'it-length-prefixed'
-import merge from 'it-merge'
-import { pipe } from 'it-pipe'
-import { pushable } from 'it-pushable'
-import defer, { type DeferredPromise } from 'p-defer'
+import { type Pushable, pushable } from 'it-pushable'
+import { pEvent, TimeoutError } from 'p-event'
 import { Uint8ArrayList } from 'uint8arraylist'
 import { Message } from './pb/message.js'
-import type { Stream, StreamStat, Direction } from '@libp2p/interface-connection'
-import type { Source } from 'it-stream-types'
+import type { Direction, Stream } from '@libp2p/interface-connection'
 
 const log = logger('libp2p:webrtc:stream')
 
-/**
- * Constructs a default StreamStat
- */
-export function defaultStat (dir: Direction): StreamStat {
-  return {
-    direction: dir,
-    timeline: {
-      open: 0,
-      close: undefined
-    }
-  }
+export interface DataChannelOpts {
+  maxMessageSize: number
+  maxBufferedAmount: number
+  bufferedAmountLowEventTimeout: number
 }
 
-interface StreamInitOpts {
+export interface WebRTCStreamInit extends AbstractStreamInit {
   /**
    * The network channel used for bidirectional peer-to-peer transfers of
    * arbitrary data
@@ -33,216 +25,85 @@ interface StreamInitOpts {
    */
   channel: RTCDataChannel
 
-  /**
-   * User defined stream metadata
-   */
-  metadata?: Record<string, any>
-
-  /**
-   * Stats about this stream
-   */
-  stat: StreamStat
-
-  /**
-   * Callback to invoke when the stream is closed.
-   */
-  closeCb?: (stream: WebRTCStream) => void
-}
-
-/*
- * State transitions for a stream
- */
-interface StreamStateInput {
-  /**
-   * Outbound conections are opened by the local node, inbound streams are
-   * opened by the remote
-   */
-  direction: 'inbound' | 'outbound'
-
-  /**
-   * Message flag from the protobufs
-   *
-   * 0 = FIN
-   * 1 = STOP_SENDING
-   * 2 = RESET
-   */
-  flag: Message.Flag
-}
-
-export enum StreamStates {
-  OPEN,
-  READ_CLOSED,
-  WRITE_CLOSED,
-  CLOSED,
+  dataChannelOptions?: Partial<DataChannelOpts>
 }
 
-// Checked by the Typescript compiler. If this fails it's because the switch
-// statement is not exhaustive.
-function unreachableBranch (x: never): never {
-  throw new Error('Case not handled in switch')
-}
-
-class StreamState {
-  state: StreamStates = StreamStates.OPEN
-
-  isWriteClosed (): boolean {
-    return (this.state === StreamStates.CLOSED || this.state === StreamStates.WRITE_CLOSED)
-  }
-
-  transition ({ direction, flag }: StreamStateInput): [StreamStates, StreamStates] {
-    const prev = this.state
-
-    // return early if the stream is closed
-    if (this.state === StreamStates.CLOSED) {
-      return [prev, StreamStates.CLOSED]
-    }
-
-    if (direction === 'inbound') {
-      switch (flag) {
-        case Message.Flag.FIN:
-          if (this.state === StreamStates.OPEN) {
-            this.state = StreamStates.READ_CLOSED
-          } else if (this.state === StreamStates.WRITE_CLOSED) {
-            this.state = StreamStates.CLOSED
-          }
-          break
-
-        case Message.Flag.STOP_SENDING:
-          if (this.state === StreamStates.OPEN) {
-            this.state = StreamStates.WRITE_CLOSED
-          } else if (this.state === StreamStates.READ_CLOSED) {
-            this.state = StreamStates.CLOSED
-          }
-          break
-
-        case Message.Flag.RESET:
-          this.state = StreamStates.CLOSED
-          break
-        default:
-          unreachableBranch(flag)
-      }
-    } else {
-      switch (flag) {
-        case Message.Flag.FIN:
-          if (this.state === StreamStates.OPEN) {
-            this.state = StreamStates.WRITE_CLOSED
-          } else if (this.state === StreamStates.READ_CLOSED) {
-            this.state = StreamStates.CLOSED
-          }
-          break
-
-        case Message.Flag.STOP_SENDING:
-          if (this.state === StreamStates.OPEN) {
-            this.state = StreamStates.READ_CLOSED
-          } else if (this.state === StreamStates.WRITE_CLOSED) {
-            this.state = StreamStates.CLOSED
-          }
-          break
-
-        case Message.Flag.RESET:
-          this.state = StreamStates.CLOSED
-          break
-
-        default:
-          unreachableBranch(flag)
-      }
-    }
-    return [prev, this.state]
-  }
-}
+// Max message size that can be sent to the DataChannel
+const MAX_MESSAGE_SIZE = 16 * 1024
 
-export class WebRTCStream implements Stream {
-  /**
-   * Unique identifier for a stream
-   */
-  id: string
+// How much can be buffered to the DataChannel at once
+const MAX_BUFFERED_AMOUNT = 16 * 1024 * 1024
 
-  /**
-   * Stats about this stream
-   */
-  stat: StreamStat
+// How long time we wait for the 'bufferedamountlow' event to be emitted
+const BUFFERED_AMOUNT_LOW_TIMEOUT = 30 * 1000
 
-  /**
-   * User defined stream metadata
-   */
-  metadata: Record<string, any>
+// protobuf field definition overhead
+const PROTOBUF_OVERHEAD = 3
 
+class WebRTCStream extends AbstractStream {
   /**
    * The data channel used to send and receive data
    */
   private readonly channel: RTCDataChannel
 
   /**
-   * The current state of the stream
+   * Data channel options
    */
-  streamState = new StreamState()
-
-  /**
-   * Read unwrapped protobuf data from the underlying datachannel.
-   * _src is exposed to the user via the `source` getter to .
-   */
-  private readonly _src: AsyncGenerator<Uint8ArrayList, any, unknown>
+  private readonly dataChannelOptions: DataChannelOpts
 
   /**
    * push data from the underlying datachannel to the length prefix decoder
    * and then the protobuf decoder.
    */
-  private readonly _innersrc = pushable()
-
-  /**
-   * Deferred promise that resolves when the underlying datachannel is in the
-   * open state.
-   */
-  opened: DeferredPromise<void> = defer()
-
-  /**
-   * sinkCreated is set to true once the sinkFunction is invoked
-   */
-  _sinkCalled: boolean = false
+  private readonly incomingData: Pushable<Uint8Array>
 
-  /**
-   * Triggers a generator which can be used to close the sink.
-   */
-  closeWritePromise: DeferredPromise<void> = defer()
+  private messageQueue?: Uint8ArrayList
 
-  /**
-   * Callback to invoke when the stream is closed.
-   */
-  closeCb?: (stream: WebRTCStream) => void
+  constructor (init: WebRTCStreamInit) {
+    super(init)
 
-  constructor (opts: StreamInitOpts) {
-    this.channel = opts.channel
+    this.channel = init.channel
     this.channel.binaryType = 'arraybuffer'
-    this.id = this.channel.label
+    this.incomingData = pushable()
+    this.messageQueue = new Uint8ArrayList()
+    this.dataChannelOptions = {
+      bufferedAmountLowEventTimeout: init.dataChannelOptions?.bufferedAmountLowEventTimeout ?? BUFFERED_AMOUNT_LOW_TIMEOUT,
+      maxBufferedAmount: init.dataChannelOptions?.maxBufferedAmount ?? MAX_BUFFERED_AMOUNT,
+      maxMessageSize: init.dataChannelOptions?.maxMessageSize ?? MAX_MESSAGE_SIZE
+    }
 
-    this.stat = opts.stat
+    // set up initial state
     switch (this.channel.readyState) {
       case 'open':
-        this.opened.resolve()
         break
 
       case 'closed':
       case 'closing':
-        this.streamState.state = StreamStates.CLOSED
         if (this.stat.timeline.close === undefined || this.stat.timeline.close === 0) {
-          this.stat.timeline.close = new Date().getTime()
+          this.stat.timeline.close = Date.now()
         }
-        this.opened.resolve()
         break
       case 'connecting':
         // noop
         break
 
       default:
-        unreachableBranch(this.channel.readyState)
+        log.error('unknown datachannel state %s', this.channel.readyState)
+        throw new CodeError('Unknown datachannel state', 'ERR_INVALID_STATE')
     }
 
-    this.metadata = opts.metadata ?? {}
-
     // handle RTCDataChannel events
     this.channel.onopen = (_evt) => {
       this.stat.timeline.open = new Date().getTime()
-      this.opened.resolve()
+
+      if (this.messageQueue != null) {
+        // send any queued messages
+        this._sendMessage(this.messageQueue)
+          .catch(err => {
+            this.abort(err)
+          })
+        this.messageQueue = undefined
+      }
     }
 
     this.channel.onclose = (_evt) => {
@@ -256,207 +117,157 @@ export class WebRTCStream implements Stream {
 
     const self = this
 
-    // reader pipe
-    this.channel.onmessage = async ({ data }) => {
-      if (data === null || data.length === 0) {
+    this.channel.onmessage = async (event: MessageEvent<ArrayBuffer>) => {
+      const { data } = event
+
+      if (data === null || data.byteLength === 0) {
         return
       }
-      this._innersrc.push(new Uint8Array(data as ArrayBufferLike))
+
+      this.incomingData.push(new Uint8Array(data, 0, data.byteLength))
     }
 
     // pipe framed protobuf messages through a length prefixed decoder, and
     // surface data from the `Message.message` field through a source.
-    this._src = pipe(
-      this._innersrc,
-      (source) => lengthPrefixed.decode(source),
-      (source) => (async function * () {
-        for await (const buf of source) {
-          const message = self.processIncomingProtobuf(buf.subarray())
-          if (message != null) {
-            yield new Uint8ArrayList(message)
-          }
+    Promise.resolve().then(async () => {
+      for await (const buf of lengthPrefixed.decode(this.incomingData)) {
+        const message = self.processIncomingProtobuf(buf.subarray())
+
+        if (message != null) {
+          self.sourcePush(new Uint8ArrayList(message))
         }
-      })()
-    )
+      }
+    })
+      .catch(err => {
+        log.error('error processing incoming data channel messages', err)
+      })
   }
 
-  // If user attempts to set a new source this should be a noop
-  set source (_src: AsyncGenerator<Uint8ArrayList, any, unknown>) { }
-
-  get source (): AsyncGenerator<Uint8ArrayList, any, unknown> {
-    return this._src
+  sendNewStream (): void {
+    // opening new streams is handled by WebRTC so this is a noop
   }
 
-  /**
-   * Write data to the remote peer.
-   * It takes care of wrapping data in a protobuf and adding the length prefix.
-   */
-  async sink (src: Source<Uint8ArrayList | Uint8Array>): Promise<void> {
-    if (this._sinkCalled) {
-      throw new Error('sink already called on this stream')
+  async _sendMessage (data: Uint8ArrayList, checkBuffer: boolean = true): Promise<void> {
+    if (checkBuffer && this.channel.bufferedAmount > this.dataChannelOptions.maxBufferedAmount) {
+      try {
+        await pEvent(this.channel, 'bufferedamountlow', { timeout: this.dataChannelOptions.bufferedAmountLowEventTimeout })
+      } catch (err: any) {
+        if (err instanceof TimeoutError) {
+          this.abort(err)
+          throw new Error('Timed out waiting for DataChannel buffer to clear')
+        }
+
+        throw err
+      }
     }
-    // await stream opening before sending data
-    await this.opened.promise
-    try {
-      await this._sink(src)
-    } finally {
-      this.closeWrite()
+
+    if (this.channel.readyState === 'closed' || this.channel.readyState === 'closing') {
+      throw new CodeError('Invalid datachannel state - closed or closing', 'ERR_INVALID_STATE')
     }
-  }
 
-  /**
-   * Closable sink implementation
-   */
-  private async _sink (src: Source<Uint8ArrayList | Uint8Array>): Promise<void> {
-    const closeWrite = this._closeWriteIterable()
-    for await (const buf of merge(closeWrite, src)) {
-      if (this.streamState.isWriteClosed()) {
-        return
+    if (this.channel.readyState === 'open') {
+      // send message without copying data
+      for (const buf of data) {
+        this.channel.send(buf)
+      }
+    } else if (this.channel.readyState === 'connecting') {
+      // queue message for when we are open
+      if (this.messageQueue == null) {
+        this.messageQueue = new Uint8ArrayList()
       }
-      const msgbuf = Message.encode({ message: buf.subarray() })
-      const sendbuf = lengthPrefixed.encode.single(msgbuf)
 
-      this.channel.send(sendbuf.subarray())
+      this.messageQueue.append(data)
+    } else {
+      log.error('unknown datachannel state %s', this.channel.readyState)
+      throw new CodeError('Unknown datachannel state', 'ERR_INVALID_STATE')
     }
   }
 
-  /**
-   * Handle incoming
-   */
-  processIncomingProtobuf (buffer: Uint8Array): Uint8Array | undefined {
-    const message = Message.decode(buffer)
+  async sendData (data: Uint8ArrayList): Promise<void> {
+    const msgbuf = Message.encode({ message: data.subarray() })
+    const sendbuf = lengthPrefixed.encode.single(msgbuf)
 
-    if (message.flag !== undefined) {
-      const [currentState, nextState] = this.streamState.transition({ direction: 'inbound', flag: message.flag })
-
-      if (currentState !== nextState) {
-        switch (nextState) {
-          case StreamStates.READ_CLOSED:
-            this._innersrc.end()
-            break
-          case StreamStates.WRITE_CLOSED:
-            this.closeWritePromise.resolve()
-            break
-          case StreamStates.CLOSED:
-            this.close()
-            break
-          // StreamStates.OPEN will never be a nextState
-          case StreamStates.OPEN:
-            break
-          default:
-            unreachableBranch(nextState)
-        }
-      }
-    }
+    await this._sendMessage(sendbuf)
+  }
 
-    return message.message
+  async sendReset (): Promise<void> {
+    await this._sendFlag(Message.Flag.RESET)
   }
 
-  /**
-   * Close a stream for reading and writing
-   */
-  close (): void {
-    this.stat.timeline.close = new Date().getTime()
-    this.streamState.state = StreamStates.CLOSED
-    this._innersrc.end()
-    this.closeWritePromise.resolve()
-    this.channel.close()
-
-    if (this.closeCb !== undefined) {
-      this.closeCb(this)
-    }
+  async sendCloseWrite (): Promise<void> {
+    await this._sendFlag(Message.Flag.FIN)
+  }
+
+  async sendCloseRead (): Promise<void> {
+    await this._sendFlag(Message.Flag.STOP_SENDING)
   }
 
   /**
-   * Close a stream for reading only
+   * Handle incoming
    */
-  closeRead (): void {
-    const [currentState, nextState] = this.streamState.transition({ direction: 'outbound', flag: Message.Flag.STOP_SENDING })
-    if (currentState === nextState) {
-      // No change, no op
-      return
-    }
+  private processIncomingProtobuf (buffer: Uint8Array): Uint8Array | undefined {
+    const message = Message.decode(buffer)
 
-    if (currentState === StreamStates.OPEN || currentState === StreamStates.WRITE_CLOSED) {
-      this._sendFlag(Message.Flag.STOP_SENDING)
-      this._innersrc.end()
-    }
+    if (message.flag !== undefined) {
+      if (message.flag === Message.Flag.FIN) {
+        // We should expect no more data from the remote, stop reading
+        this.incomingData.end()
+        this.closeRead()
+      }
 
-    if (nextState === StreamStates.CLOSED) {
-      this.close()
-    }
-  }
+      if (message.flag === Message.Flag.RESET) {
+        // Stop reading and writing to the stream immediately
+        this.reset()
+      }
 
-  /**
-   * Close a stream for writing only
-   */
-  closeWrite (): void {
-    const [currentState, nextState] = this.streamState.transition({ direction: 'outbound', flag: Message.Flag.FIN })
-    if (currentState === nextState) {
-      // No change, no op
-      return
+      if (message.flag === Message.Flag.STOP_SENDING) {
+        // The remote has stopped reading
+        this.closeWrite()
+      }
     }
 
-    if (currentState === StreamStates.OPEN || currentState === StreamStates.READ_CLOSED) {
-      this._sendFlag(Message.Flag.FIN)
-      this.closeWritePromise.resolve()
-    }
+    return message.message
+  }
 
-    if (nextState === StreamStates.CLOSED) {
-      this.close()
-    }
+  private async _sendFlag (flag: Message.Flag): Promise<void> {
+    log.trace('Sending flag: %s', flag.toString())
+    const msgbuf = Message.encode({ flag })
+    const prefixedBuf = lengthPrefixed.encode.single(msgbuf)
+
+    await this._sendMessage(prefixedBuf, false)
   }
+}
 
+export interface WebRTCStreamOptions {
   /**
-   * Call when a local error occurs, should close the stream for reading and writing
+   * The network channel used for bidirectional peer-to-peer transfers of
+   * arbitrary data
+   *
+   * {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel}
    */
-  abort (err: Error): void {
-    log.error(`An error occurred, closing the stream for reading and writing: ${err.message}`)
-    this.close()
-  }
+  channel: RTCDataChannel
 
   /**
-   * Close the stream for writing, and indicate to the remote side this is being done 'abruptly'
-   *
-   * @see this.closeWrite
+   * The stream direction
    */
-  reset (): void {
-    const [currentState, nextState] = this.streamState.transition({ direction: 'outbound', flag: Message.Flag.RESET })
-    if (currentState === nextState) {
-      // No change, no op
-      return
-    }
+  direction: Direction
 
-    this._sendFlag(Message.Flag.RESET)
-    this.close()
-  }
+  dataChannelOptions?: Partial<DataChannelOpts>
 
-  private _sendFlag (flag: Message.Flag): void {
-    try {
-      log.trace('Sending flag: %s', flag.toString())
-      const msgbuf = Message.encode({ flag })
-      this.channel.send(lengthPrefixed.encode.single(msgbuf).subarray())
-    } catch (err) {
-      if (err instanceof Error) {
-        log.error(`Exception while sending flag ${flag}: ${err.message}`)
-      }
-    }
-  }
+  maxMsgSize?: number
 
-  private _closeWriteIterable (): Source<Uint8ArrayList | Uint8Array> {
-    const self = this
-    return {
-      async * [Symbol.asyncIterator] () {
-        await self.closeWritePromise.promise
-        yield new Uint8Array(0)
-      }
-    }
-  }
+  onEnd?: (err?: Error | undefined) => void
+}
 
-  eq (stream: Stream): boolean {
-    if (stream instanceof WebRTCStream) {
-      return stream.channel.id === this.channel.id
-    }
-    return false
-  }
+export function createStream (options: WebRTCStreamOptions): Stream {
+  const { channel, direction, onEnd, dataChannelOptions } = options
+
+  return new WebRTCStream({
+    id: direction === 'inbound' ? (`i${channel.id}`) : `r${channel.id}`,
+    direction,
+    maxDataSize: (dataChannelOptions?.maxMessageSize ?? MAX_MESSAGE_SIZE) - PROTOBUF_OVERHEAD,
+    dataChannelOptions,
+    onEnd,
+    channel
+  })
 }