@fails-components/webtransport 1.0.10 → 1.1.0

package/lib/http2/parserbase.js

@@ -30,6 +30,8 @@ export class ParserBase {
   static WT_STREAM_DATA_BLOCKED = 0x190b4d42
   static WT_STREAMS_BLOCKED_UNIDI = 0x190b4d43
   static WT_STREAMS_BLOCKED_BIDI = 0x190b4d44
+  static CLOSE_WEBTRANSPORT_SESSION = 0x2843
+  static DRAIN_WEBTRANSPORT_SESSION = 0x78ae
   static DATAGRAM = 0x00
 
   /**
@@ -38,7 +40,8 @@ export class ParserBase {
   constructor({
     nativesession,
     isclient,
-    initialStreamSendWindowOffset,
+    initialStreamSendWindowOffsetBidi,
+    initialStreamSendWindowOffsetUnidi,
     initialStreamReceiveWindowOffset,
     streamShouldAutoTuneReceiveWindow,
     streamReceiveWindowSizeLimit
@@ -48,7 +51,8 @@ export class ParserBase {
     /** @type {boolean} */
     this.blocked = false
 
-    this.initialStreamSendWindowOffset = initialStreamSendWindowOffset
+    this.initialStreamSendWindowOffsetUnidi = initialStreamSendWindowOffsetUnidi
+    this.initialStreamSendWindowOffsetBidi = initialStreamSendWindowOffsetBidi
     this.initialStreamReceiveWindowOffset = initialStreamReceiveWindowOffset
     this.streamShouldAutoTuneReceiveWindow = streamShouldAutoTuneReceiveWindow
     this.streamReceiveWindowSizeLimit = streamReceiveWindowSizeLimit
@@ -67,16 +71,31 @@ export class ParserBase {
 
   /**
    * @abstract
-   * @param{{type: Number, headerVints: Array<Number|bigint>, payload: Uint8Array|undefined}} bs
+   * @param{{type: Number, headerVints: Array<Number|bigint>, payload: Uint8Array|undefined, end?: () => void}} bs
    */
-  writeCapsule({ type, headerVints, payload }) {
+  writeCapsule({ type, headerVints, payload, end }) {
     throw new Error('Implement writeCapsule in derived Class')
   }
 
   /**
    * @param{{code: Number, reason: string}}arg
    */
-  sendClose({ code, reason }) {}
+  sendClose({ code, reason }) {
+    const encoder = new TextEncoder()
+    const payload = encoder.encode('AAAA' + reason)
+    payload[0] = (code >> 24) & 0xff
+    payload[1] = (code >> 16) & 0xff
+    payload[2] = (code >> 8) & 0xff
+    payload[3] = code & 0xff
+    this.writeCapsule({
+      type: ParserBase.CLOSE_WEBTRANSPORT_SESSION,
+      headerVints: [],
+      payload,
+      end: () => {
+        this.closeHttp2Stream(code)
+      }
+    })
+  }
 
   /**
    * @param {bigint} streamid
@@ -101,12 +120,15 @@ export class ParserBase {
         return undefined
       }
     }
+    const unidirectional = !!(streamid & 0x2n)
     const stream = new Http2WebTransportStream({
       streamid,
-      unidirectional: !!(streamid & 0x2n),
+      unidirectional,
       incoming,
       capsuleParser: this,
-      sendWindowOffset: this.initialStreamSendWindowOffset,
+      sendWindowOffset: unidirectional
+        ? this.initialStreamSendWindowOffsetUnidi
+        : this.initialStreamSendWindowOffsetBidi,
       receiveWindowOffset: this.initialStreamReceiveWindowOffset,
       shouldAutoTuneReceiveWindow: this.streamShouldAutoTuneReceiveWindow,
       receiveWindowSizeLimit: this.streamReceiveWindowSizeLimit,
@@ -212,6 +234,21 @@ export class ParserBase {
     }
   }
 
+  /**
+   * @param {{code:  number, reason: string}} opts
+   */
+  onCloseWebTransportSession({ code, reason }) {
+    this.session.jsobj.onClose({
+      errorcode: code,
+      error: reason
+    })
+    this.closeHttp2Stream(code) // is this necessary
+  }
+
+  onDrain() {
+    this.session.jsobj.onGoAwayReceived()
+  }
+
   /**
    * @param {number} code
    */

package/lib/http2/parserbasehttp2.js

@@ -4,6 +4,17 @@ import { ParserBase } from './parserbase.js'
  * @typedef {import('node:http2').Http2Stream} Http2Stream
  */
 
+/**
+ * @param{{offset: Number, buffer: Buffer, size: Number}} bs
+ */
+
+export function readUint32(bs) {
+  if (bs.offset + 4 > bs.size) return undefined
+  const toret = bs.buffer.readUInt32BE(bs.offset)
+  bs.offset += 4
+  return toret
+}
+
 /**
  * @param{{offset: Number, buffer: Buffer, size: Number}} bs
  */
@@ -63,7 +74,8 @@ export class ParserBaseHttp2 extends ParserBase {
     stream,
     nativesession,
     isclient,
-    initialStreamSendWindowOffset,
+    initialStreamSendWindowOffsetBidi,
+    initialStreamSendWindowOffsetUnidi,
     initialStreamReceiveWindowOffset,
     streamShouldAutoTuneReceiveWindow,
     streamReceiveWindowSizeLimit
@@ -71,7 +83,8 @@ export class ParserBaseHttp2 extends ParserBase {
     super({
       nativesession,
       isclient,
-      initialStreamSendWindowOffset,
+      initialStreamSendWindowOffsetBidi,
+      initialStreamSendWindowOffsetUnidi,
       initialStreamReceiveWindowOffset,
       streamShouldAutoTuneReceiveWindow,
       streamReceiveWindowSizeLimit

package/lib/http2/session.js

@@ -209,10 +209,7 @@ export class Http2WebTransportSession {
    */
   close({ code, reason }) {
     this.capsParser.sendClose({ code, reason }) // this includes for ws closing the session!
-    // what to do with the reason
-    if (this.stream) {
-      this.capsParser.closeHttp2Stream(code)
-    }
+    // should also close the stream
   }
 
   /**
@@ -252,7 +249,6 @@ export class Http2WebTransportSession {
    * @param {{ code: number, reason: string }} arg
    */
   closeConnection({ code, reason }) {
-    console.trace()
     // called in case of failure in parsing or flowcontrol
     this.jsobj.onClose({
       errorcode: code,

package/lib/index.node.js

@@ -25,4 +25,4 @@
 
 // also edit index.types.js
 export { HttpServer, Http3Server, Http2Server } from './server.js'
-export { WebTransport } from './webtransport.node.js'
+export { WebTransport, quicheLoaded } from './webtransport.node.js'

package/lib/index.types.js

@@ -25,7 +25,7 @@
 
 // both imports from the browser side and for nodes to generate a joint type file
 export { HttpServer, Http3Server, Http2Server } from './server.js'
-export { WebTransport } from './webtransport.node.js'
+export { WebTransport, quicheLoaded } from './webtransport.node.js'
 
 export {
   WebTransportPonyfill,

package/lib/server.js

@@ -82,8 +82,8 @@ class TransportIntServerProxy {
   }
 
   /**
-   * @param {string} cert
-   * @param {string} privKey
+   * @param {string|string[]} cert
+   * @param {string|string[]} privKey
    * @param {boolean} http2only
    * */
   updateCert(cert, privKey, http2only) {
@@ -245,16 +245,18 @@ export class HttpServer {
    * @param {ServerSessionRequestEvent} args
    */
   onSessionRequest(args) {
-    if (args.promise && args.header) {
+    if ((args.promise || args.protocol !== 'http3:libquiche') && args.header) {
       if (!this.requestHandler) throw new Error('Request handler not set')
       this.requestHandler({ header: args.header })
         .then((/** @type {any} */ result) => {
           log('oSR', result)
-          args.object.finishSessionRequest({
+          this.transportInt.finishSessionRequest({
             promise: args.promise,
             header: args.header,
             session: args.session,
             head: args.head,
+            transportPrivate: args.transportPrivate,
+            protocol: args.protocol,
             ...result
           })
         })
@@ -272,6 +274,7 @@ export class HttpServer {
     const sesobj = new HttpWTSession({
       object: args.session,
       header: args.header,
+      userData: args.userData ?? {},
       parentobj: this
     })
     args.session.jsobj = sesobj

package/lib/session.js

@@ -50,7 +50,8 @@ export class HttpWTSession {
    * @param {object} args
    * @param {import('./types').NativeHttpWTSession} [args.object]
    * @param {HttpServer | HttpClient} args.parentobj
-   * @param {any | undefined} [args.header= undefined]
+   * @param {Object | undefined} [args.header= undefined]
+   * @param {Object | undefined} [args.userData= undefined]
    */
   constructor(args) {
     if (args.object) {
@@ -68,8 +69,10 @@ export class HttpWTSession {
     this.readyResolve = null
     /** @type {(() => void) | null | undefined} */
     this.closeHook = null
-    /** @type {(any | null | undefined)} */
+    /** @type {(Object | null | undefined)} */
     this.header = args.header
+    /** @type {(Object | null | undefined)} */
+    this.userData = args.userData
 
     /** @type {Promise<void>} */
     this.ready = new Promise((resolve, reject) => {

package/lib/types.ts

@@ -4,7 +4,7 @@ import type {
   WebTransportOptions,
   WebTransportSendGroup
 } from './dom'
-import type { IncomingHttpHeaders, Http2Stream } from 'http2'
+import type { IncomingHttpHeaders, Http2Stream, ServerHttp2Stream } from 'http2'
 import { ParserBase } from './http2/parserbase'
 import { Http2WebTransportSession } from './http2/session'
 import { HttpClient } from './client'
@@ -103,11 +103,14 @@ export interface ReadBuffer {
 }
 
 export interface NativeFinishSessionRequest {
+  path: string
   header: IncomingHttpHeaders
-  session: Http2Stream
+  session: ServerHttp2Stream
   status: number
   protocol: 'capsule' | 'websocket' | 'websocketoverhttp1' | 'http3'
   head?: Buffer
+  userData?: object
+  transportPrivate?: object
 }
 
 export type Purpose =
@@ -219,6 +222,7 @@ export interface HttpWTServerSessionVisitorEvent
   extends HttpWTSessionVisitorEvent {
   path: string
   header: Object
+  userData?: Object | undefined
 }
 
 export interface ServerSessionRequestEvent {
@@ -228,6 +232,7 @@ export interface ServerSessionRequestEvent {
   session: any
   object?: any // the actual transport object itself, actually present on all messages, but required here
   protocol: string //'capsule' | 'websocket' | 'http3'
+  transportPrivate?: Object //private information from the transport object
 }
 
 /**
@@ -266,10 +271,17 @@ export interface WebTransportSessionImpl extends WebTransportSession {
   state: WebTransportSessionState
 }
 
+export type QUICHE_LOG_OFF = -1
+export type QUICHE_LOG_INFO = 0
+export type QUICHE_LOG_WARNING = 1
+export type QUICHE_LOG_ERROR = 2
+export type QUICHE_LOG_FATAL = 3
+export type QUICHE_LOG = QUICHE_LOG_OFF | QUICHE_LOG_INFO | QUICHE_LOG_WARNING | QUICHE_LOG_ERROR | QUICHE_LOG_FATAL
+
 export interface HttpWebTransportInit extends WebTransportOptions {
   host: string
   port: string | number
-  quicheLogVerbose?: number
+  quicheLogVerbose?: QUICHE_LOG
   forceIpv6?: boolean
   localPort?: number
 }
@@ -284,8 +296,8 @@ export interface HttpServerInit extends HttpWebTransportInit {
   port: string | number
   host: string
   secret: string
-  cert: string
-  privKey: string
+  cert: string | string[]
+  privKey: string | string[]
   maxConnections?: number
   initialStreamFlowControlWindow?: number
   streamShouldAutoTuneReceiveWindow?: boolean
@@ -331,7 +343,8 @@ export type CreateParserFunction = (
 export interface ParserInit {
   isclient: boolean
   nativesession: any
-  initialStreamSendWindowOffset: number
+  initialStreamSendWindowOffsetBidi: number
+  initialStreamSendWindowOffsetUnidi: number
   initialStreamReceiveWindowOffset: number
   streamShouldAutoTuneReceiveWindow: boolean
   streamReceiveWindowSizeLimit: number

package/lib/webtransport.browser.js

@@ -61,9 +61,10 @@ export class WebTransportPonyfill extends WebTransportBase {
    * @param{{client: HttpClient, sessionint: HttpWTSession, ourl: URL}} args
    */
   startUpConnection({ client, sessionint, ourl }) {
+    const path = ourl.pathname + (ourl.search ?? '')
     client
-      .handleConnection({ createTransport: true, path: ourl.pathname })
-      .then(() => client.createWTSession(sessionint, ourl.pathname))
+      .handleConnection({ createTransport: true, path })
+      .then(() => client.createWTSession(sessionint, path))
       .catch((error) => {
         client.closeHookSession()
         sessionint.readyReject(error)

package/lib/webtransport.node.js

@@ -18,9 +18,13 @@ let Http3WebTransportClientSocket
  * @type {new (arg0: import("./types").HttpWebTransportInit) => any}
  */
 let Http3WebTransportClient
+/**
+ * @type {boolean}
+ */
+let quicheLoadedReady
 // @ts-ignore
 // eslint-disable-next-line no-unused-vars
-const quicheLoaded = new Promise((resolve, reject) => {
+export const quicheLoaded = new Promise((resolve, reject) => {
   // @ts-ignore
   import('@fails-components/webtransport-transport-http3-quiche')
     .then(
@@ -39,6 +43,9 @@ const quicheLoaded = new Promise((resolve, reject) => {
         resolve(undefined)
       }
     )
+    .finally(() => {
+      quicheLoadedReady = true
+    })
     .catch((error) => {
       log('Problem loading http3-quiche transport', error)
       reject(error)
@@ -68,17 +75,18 @@ export class WebTransport extends WebTransportBase {
    * @param{{client: HttpClient, sessionint: HttpWTSession, ourl: URL}} args
    */
   startUpConnection({ client, sessionint, ourl }) {
+    const path = ourl.pathname + (ourl.search ?? '')
     client
-      .handleConnection({ createTransport: true, path: ourl.pathname })
-      .then(() => client.createWTSession(sessionint, ourl.pathname))
+      .handleConnection({ createTransport: true, path })
+      .then(() => client.createWTSession(sessionint, path))
       .catch((error) => {
         if (client.transportIntSwitchToReliable) {
           log('Connecting to unreliable failed:', error)
           log('Now switching to reliable')
           client.transportIntSwitchToReliable()
           client
-            .handleConnection({ createTransport: false, path: ourl.pathname })
-            .then(() => client.createWTSession(sessionint, ourl.pathname))
+            .handleConnection({ createTransport: false, path })
+            .then(() => client.createWTSession(sessionint, path))
             .catch((error) => {
               client.closeHookSession()
               sessionint.readyReject(error)
@@ -102,6 +110,9 @@ export class WebTransport extends WebTransportBase {
    */
   createClient(args) {
     let createUnreliableClient
+    // @ts-ignore
+    if (!quicheLoadedReady && !args?.forceReliable)
+      throw new Error('Lib quiche loading attempt did not end')
     if (checkQuicheInit) {
       createUnreliableClient = function (/** @type {any} */ _client) {
         if (

package/lib/webtransportbase.js

@@ -68,7 +68,7 @@ export class WebTransportBase {
    * @abstract
    */
   startUpConnection({ client, sessionint, ourl }) {
-    throw new Error('Implement createClient')
+    throw new Error('Implement startUpConnection')
   }
 
   get reliability() {

package/old_test/test.js

@@ -5,7 +5,12 @@
 // this file runs various tests
 
 import { generateWebTransportCertificate } from '../test/fixtures/certificate.js'
-import { Http3Server, Http2Server, WebTransport } from '../lib/index.node.js'
+import {
+  Http3Server,
+  Http2Server,
+  WebTransport,
+  quicheLoaded
+} from '../lib/index.node.js'
 import { echoTestsConnection, runEchoServer } from './testsuite.js'
 
 let http2 = false
@@ -15,6 +20,13 @@ if (process.argv.some((el) => el === 'http2')) {
 }
 
 async function run() {
+  if (
+    process.env.USE_HTTP2 !== 'true' &&
+    process.env.USE_PONYFILL !== 'true' &&
+    process.env.USE_POLYFILL !== 'true'
+  ) {
+    await quicheLoaded
+  }
   console.log('try connecting to server that does not exist')
   const badClient = new WebTransport('https://127.0.0.1:49823/echo', {
     serverCertificateHashes: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fails-components/webtransport",
-  "version": "1.0.10",
+  "version": "1.1.0",
   "description": "A component to add webtransport support (server and client) to node.js using libquiche",
   "exports": {
     ".": {
@@ -43,7 +43,7 @@
   "bugs": {
     "url": "https://github.com/fails-components/webtransport/issues"
   },
-  "homepage": "https://github.com/fails-components/webtransport/main/#readme",
+  "homepage": "https://github.com/fails-components/webtransport/tree/master/main#readme",
   "dependencies": {
     "@types/debug": "^4.1.7",
     "bindings": "^1.5.0",
@@ -83,6 +83,7 @@
   },
   "browser": {
     "./test/fixtures/webtransport.js": "./test/fixtures/webtransport.browser.js",
+    "./test/fixtures/quiche.js": "./test/fixtures/quiche.browser.js",
     "./lib/webstreams.js": "./lib/webstreams.browser.js"
   }
 }

package/readme.md

@@ -35,7 +35,7 @@ Note, that it is only partially implemented and also some http2 features require
 Use for the server side either `HttpServer` for http/2 and http/3 support (including WebTransport over WebSocket), Http3Server for http/3 only and Http2Server for http/2 only.
 For the client side pass the options `forceReliable`, `requireUnreliable` etc. to force/select a type of transport.
 
- **Note, that the http/2 webtransport protocol (not supported by any browser yet), is implemented without the support of receiving initial settings, which can cause a problem with the initial flow control of the WebTransport streams. This is a current limitation in node.js, but a patch to add support will soon be part of new node versions. Note, that for sending the required initial setting you need a very recent version (>=21.6.1) of node.js.** This limitation does not apply to the polyfill/ponyfill and the webtransport over websocket protocol.
+ **Note, that the http/2 webtransport protocol (not supported by any browser yet), requires support for sending and receiving initial a node version with support for receiving customSettings. Versions without support can cause a problem with the initial flow control of the WebTransport streams.  Note, that for sending and receiving the required initial setting you need a very recent version (>=21.6.1 sending >= 21.7.0 receiving) of node.js.** This limitation does not apply to the polyfill/ponyfill and the webtransport over websocket protocol.
 
  The current proposal for the WebTransport over WebSocket protocol can be found [here] (https://datatracker.ietf.org/doc/draft-richter-webtransport-websocket/).
 
@@ -126,6 +126,9 @@ The `WebTransportSession` should behave most like a WebTransport object on the b
 ### Using a client
 The `WebTransport` object for node or the `WebTransportPonyfill`,  `WebTransportPolyfill` objects for the browser, behave like the `WebTransport` client object for the browser with few additions and some missing features.
 
+As the http/3 package is loaded dynamically and the WebTransport object is created synchronously, you may want to make sure, that the modules are already loaded. You can do so, by waiting for the promise `quicheLoaded` exported by the package.
+
+
 ## Specification divergence
 
 This module implements parts of the [WebTransport spec](https://datatracker.ietf.org/doc/html/draft-vvv-webtransport-quic-00) but not all of it.

package/test/bidirectional-streams.spec.js

@@ -6,6 +6,7 @@ import { readStream } from './fixtures/read-stream.js'
 import { writeStream } from './fixtures/write-stream.js'
 import { readCertHash } from './fixtures/read-cert-hash.js'
 import WebTransport from './fixtures/webtransport.js'
+import { quicheLoaded } from './fixtures/quiche.js'
 import * as ui8 from 'uint8arrays'
 import {
   KNOWN_BYTES,
@@ -38,6 +39,17 @@ describe('bidirectional streams', function () {
     // @ts-ignore
     delete wtOptions.serverCertificateHashes
 
+  // @ts-ignore
+  beforeEach(async () => {
+    if (
+      process.env.USE_HTTP2 !== 'true' &&
+      process.env.USE_PONYFILL !== 'true' &&
+      process.env.USE_POLYFILL !== 'true'
+    ) {
+      await quicheLoaded
+    }
+  })
+
   // @ts-ignore
   afterEach(async () => {
     if (client != null) {
@@ -116,4 +128,23 @@ describe('bidirectional streams', function () {
     expect(result).to.have.property('reason', '')
     expect(result).to.have.property('closeCode', 0)
   })
+
+  it('receives data from server and checks receiving stream fin', async () => {
+    // client context - waits for the server to open a bidi stream then pipes it back to them
+    client = new WebTransport(
+      `${process.env.SERVER_URL}/bidirectional_server_fin_send`,
+      wtOptions
+    )
+    await client.ready
+
+    const bidiStream = await getReaderValue(client.incomingBidirectionalStreams)
+    const reader = bidiStream.readable.getReader()
+
+    while (true) {
+      const res = await reader.read()
+      if (res.done) {
+        break
+      }
+    }
+  })
 })

package/test/datagrams.spec.js

@@ -5,6 +5,7 @@ import { expect } from './fixtures/chai.js'
 import { readStream } from './fixtures/read-stream.js'
 import { readCertHash } from './fixtures/read-cert-hash.js'
 import { pTimeout } from './fixtures/p-timeout.js'
+import { quicheLoaded } from './fixtures/quiche.js'
 
 /**
  * @template T
@@ -32,6 +33,17 @@ describe('datagrams', function () {
     // @ts-ignore
     delete wtOptions.serverCertificateHashes
 
+  // @ts-ignore
+  beforeEach(async () => {
+    if (
+      process.env.USE_HTTP2 !== 'true' &&
+      process.env.USE_PONYFILL !== 'true' &&
+      process.env.USE_POLYFILL !== 'true'
+    ) {
+      await quicheLoaded
+    }
+  })
+
   // @ts-ignore
   afterEach(async () => {
     if (client != null) {

package/test/fixtures/quiche.browser.js

@@ -0,0 +1,2 @@
+const quicheLoaded = Promise.resolve()
+export { quicheLoaded }

package/test/fixtures/quiche.js

@@ -0,0 +1 @@
+export { quicheLoaded } from '../../lib/index.node.js'

package/test/fixtures/read-stream.js

@@ -1,15 +1,10 @@
-/**
- * @template T
- * @typedef {import('../../lib/webstreams').ReadableStream<T>} ReadableStream<T>
- */
-
 /**
  * Read a stream contents to the end and return it
  *
  * @template T
  * @param {ReadableStream<T>} readable
  * @param {number} [expected]
- * @returns
+ * @returns {T[]}
  */
 export async function readStream(readable, expected) {
   const reader = readable.getReader()
@@ -27,7 +22,6 @@ export async function readStream(readable, expected) {
       }
 
       if (value != null) {
-        // @ts-ignore
         outputlength += value.length
         output.push(value)
       }
@@ -42,3 +36,22 @@ export async function readStream(readable, expected) {
     reader.releaseLock()
   }
 }
+
+/**
+ * @param {ReadableStream<Uint8Array>} stream
+ * @returns {string}
+ */
+export async function readStringFromStream(stream) {
+  const decoder = new TextDecoder()
+  let output = ''
+
+  for (const buf of await readStream(stream)) {
+    output += decoder.decode(buf, {
+      stream: true
+    })
+  }
+
+  output += decoder.decode()
+
+  return output
+}

package/test/fixtures/reader-value.js

@@ -1,8 +1,3 @@
-/**
- * @template T
- * @typedef {import('../../lib/webstreams').ReadableStream<T>} ReadableStream<T>
- */
-
 /**
  * @template T
  * @param {ReadableStream<T>} readableStream