@fails-components/webtransport 0.0.9 → 0.1.0-macarmbuild.5

package/package.json

@@ -1,21 +1,24 @@
 {
   "name": "@fails-components/webtransport",
-  "version": "0.0.9",
+  "version": "0.1.0-macarmbuild.5",
   "description": "A component to add webtransport support (server and client) to node.js using libquiche",
-  "main": "src/webtransport.js",
-  "module": "src/webtransport.js",
+  "main": "lib/index.js",
+  "module": "lib/index.js",
   "engines": {
     "node": ">=16"
   },
   "type": "module",
+  "types": "./dist/lib/index.d.ts",
   "scripts": {
     "start": "node test/echoserver.js",
-    "test": "node test/test.js",
+    "test": "mocha test/*.spec.js",
+    "oldtest": "node test/test.js",
     "install": "node build.js install",
     "build": "node build.js build",
     "rebuild": "node build.js rebuild",
     "rebuild-debug": "node build.js rebuild-debug -D",
-    "build-debug": "node build.js build-debug"
+    "build-debug": "node build.js build-debug",
+    "types": "tsc"
   },
   "repository": {
     "type": "git",
@@ -38,6 +41,10 @@
   "devDependencies": {
     "@babel/core": "^7.17.10",
     "@babel/eslint-parser": "^7.17.0",
+    "@types/chai": "^4.3.3",
+    "@types/mocha": "^10.0.0",
+    "@types/node": "^18.11.5",
+    "chai": "^4.3.6",
     "cmake-js": "^6.3.2",
     "eslint": "^7.32.0",
     "eslint-config-prettier": "^7.2.0",
@@ -47,8 +54,10 @@
     "eslint-plugin-prettier": "^3.4.1",
     "eslint-plugin-promise": "^4.3.1",
     "eslint-plugin-standard": "^4.1.0",
+    "mocha": "^10.1.0",
     "node-forge": "^1.3.1",
-    "prettier": "^2.4.1"
+    "prettier": "^2.4.1",
+    "typescript": "^4.8.4"
   },
   "binary": {
     "napi_versions": [

package/readme.md

@@ -40,23 +40,46 @@ In case of github packages, please add to your `.npmrc` file
 ```
 In this case you need to be authenticated against github.
 
-The package provides prebuild binaries for `windows`, `linux` and `macos` for the platform `x64` and `ia32` (only windows). 
+The package provides prebuild binaries for `windows`, `linux` and `macos` for the platform `x64` and `ia32` (only windows).
 Other platforms may be possible via crosscompiling in the github actions, if someone needs this, PRs are welcome.
 
 Of course you can also build the binary on your system.
 If you are running the compiling install as root, you need to use `--unsafe-perm` as flag.
-Installing the package without prebuild requires a full building environment including clang-9, perl6, python, golang,  ninja-build, icu. See the `Dockerfile` or `Dockerfile.development` for required debian packages. 
-This should work for Windows, linux and Mac OS X. 
+Installing the package without prebuild requires a full building environment including clang-9, perl6, python, golang,  ninja-build, icu. See the `Dockerfile` or `Dockerfile.development` for required debian packages.
+This should work for Windows, linux and Mac OS X.
 (You may want to check out the building dependencies (especially for windows) for BoringSSl, zlib, abseil on their respective websites).
 
-Of course,  PR for patches and for compiling instructions and necessary changes are welcome for all possible environments. 
+Of course,  PR for patches and for compiling instructions and necessary changes are welcome for all possible environments.
 
 ** Warning the build time takes more than 15 minutes, on windows even longer! (Due to the building of the third party libraries). **
 
-In the directory `test` you find a simple echo server code. That answers to a series of WebTransport echos. Furthermore some example browser code and finally a unit test of the library including certificate generation. 
+In the directory `test` you find a simple echo server code. That answers to a series of WebTransport echos. Furthermore some example browser code and finally a unit test of the library including certificate generation.
 
 When testing remember you might need to start chromium based browser with certain flags to accept your http/3 certificate with errors, e.g.:
 ```
 chrome --ignore-certificate-errors-spki-list=FINGERPRINTOFYOURCERTIFICATE --ignore-certificate-errors --v=2 --enable-logging=stderr --origin-to-force-quic-on=192.168.1.50:8080
 ```
 of course replace IP and fingerprint of your certificate accordingly.
+
+## 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.
+
+The types from the [W3C Working Draft](https://www.w3.org/TR/webtransport/) have been added to [lib/dom.ts](https://github.com/fails-components/webtransport/blob/master/lib/dom.ts) but some fields are commented out.
+
+These fields are unimplemented by this module at this time. Some may be implemented in the future, others are legacy fields that may be removed from the spec. PRs are welcome!
+
+They are:
+
+### WebTransport
+
+* [getStats()](https://www.w3.org/TR/webtransport/#dom-webtransport-getstats)
+* [reliability](https://www.w3.org/TR/webtransport/#dom-webtransport-reliability)
+
+### WebTransportDatagramDuplexStream
+
+* [maxDatagramSize](https://www.w3.org/TR/webtransport/#dom-webtransportdatagramduplexstream-maxdatagramsize)
+* [incomingMaxAge](https://www.w3.org/TR/webtransport/#dom-webtransportdatagramduplexstream-incomingmaxage)
+* [outgoingMaxAge](https://www.w3.org/TR/webtransport/#dom-webtransportdatagramduplexstream-outgoingmaxage)
+* [incomingHighWaterMark](https://www.w3.org/TR/webtransport/#dom-webtransportdatagramduplexstream-incominghighwatermark)
+* [outgoingHighWaterMark](https://www.w3.org/TR/webtransport/#dom-webtransportdatagramduplexstream-outgoinghighwatermark)

package/src/http3client.h

@@ -11,7 +11,6 @@
 #define WT_HTTP3_CLIENT_H
 
 #include <napi.h>
-#include <uv.h>
 
 #include <cstdint>
 #include <memory>

package/src/http3eventloop.cc

@@ -295,6 +295,17 @@ namespace quic
       progress_->Send(&report, 1);
   }
 
+  void Http3EventLoop::informServerStatus(Http3Server *serverobj, NetworkStatus status, ServerStatusDetails* details)
+  {
+    struct Http3ProgressReport report;
+    report.type = Http3ProgressReport::ServerStatus;
+    report.serverobj = serverobj;
+    report.status = status;
+    report.details = details;
+    if (progress_)
+      progress_->Send(&report, 1);
+  }
+
   void Http3EventLoop::freeData(Napi::Env env, void *data, std::string *hint)
   {
     // ok free data is actually using a string object
@@ -631,6 +642,41 @@ namespace quic
     cbsession_.Call({retObj});
   }
 
+  void Http3EventLoop::processServerStatus(Http3Server *serverobj, NetworkStatus status, ServerStatusDetails * details)
+  {
+    if (!checkQw()) return;
+    HandleScope scope(qw_->Env());
+
+    Napi::Object objVal = serverobj->getJS()->Value();
+
+    Napi::Object retObj = Napi::Object::New(qw_->Env());
+    retObj.Set("purpose", "ServerStatus");
+    retObj.Set("object", objVal);
+    Napi::Number portVal = Napi::Number::New(qw_->Env(), details->port);
+    retObj.Set("port", portVal);
+    Napi::String hostVal = Napi::String::New(qw_->Env(), details->host);
+    retObj.Set("host", hostVal);
+
+    delete details; // we own it and must throw it away
+    switch (status)
+    {
+      case NetError: {
+      retObj.Set("status", "error");
+      } break;
+      case NetListening: {
+      retObj.Set("status", "listening");
+      } break;
+      case NetClose: {
+      retObj.Set("status", "close");
+      } break;
+      default: {
+         Napi::Error::New(Env(), "Unknown status from server").ThrowAsJavaScriptException();
+        return;
+      } break;
+    };
+    cbtransport_.Call({retObj});
+  }
+
   void Http3EventLoop::HandleProgressCallback(const Http3ProgressReport *data, size_t count)
   {
     for (int i = 0; i < count; i++)
@@ -688,6 +734,12 @@ namespace quic
         processStream(false, false, cur.sessionobj, cur.stream);
       }
       break;
+      case Http3ProgressReport::ServerStatus:
+      {
+        processServerStatus(cur.serverobj, cur.status, cur.details);
+        cur.para = nullptr; // take ownership of the data
+      }
+      break;
       case Http3ProgressReport::StreamRecvSignal:
       {
         processStreamRecvSignal(cur.streamobj, cur.wtscode, cur.nettask);

package/src/http3eventloop.h

@@ -47,6 +47,13 @@ namespace quic
         streamFinal
     };
 
+    enum NetworkStatus
+    {
+        NetError,
+        NetClose,
+        NetListening
+    };
+
     struct Http3Constructors
     {
         Napi::FunctionReference stream;
@@ -54,6 +61,11 @@ namespace quic
 
     };
 
+    struct ServerStatusDetails {
+        std::string host;
+        int port;
+    };
+
     class Http3ProgressReport // actually struct would be a better fit but make napi happy
     {
     public:
@@ -69,6 +81,7 @@ namespace quic
             IncomUniDiStream,
             OutgoBiDiStream,
             OutgoUniDiStream,
+            ServerStatus,
             StreamRecvSignal,
             StreamRead,
             StreamWrite,
@@ -91,6 +104,7 @@ namespace quic
         {
             WebTransportSessionError wtecode;
             NetworkTask nettask;
+            NetworkStatus status;
         };
         union
         {
@@ -104,8 +118,11 @@ namespace quic
         {
             bool success;
         };
+        union {
 
-        std::string *para = nullptr; // for session, we own it, and must delete it
+            std::string *para = nullptr; // for session and others, we own it, and must delete it
+            ServerStatusDetails * details;
+        };
     };
 
     class Http3EventLoop : // may be replace char later
@@ -179,6 +196,8 @@ namespace quic
         void informSessionClosed(Http3WTSession *sessionobj, WebTransportSessionError error_code, absl::string_view error_message);
         void informSessionReady(Http3WTSession *sessionobj);
 
+        void informServerStatus(Http3Server *serverobj, NetworkStatus status, ServerStatusDetails* details);
+
         void informAboutStream(bool incom, bool bidir, Http3WTSession *sessionobj, Http3WTStream *stream);
         void informStreamRecvSignal(Http3WTStream *streamobj, WebTransportStreamError error_code, NetworkTask task);
         void informAboutStreamRead(Http3WTStream *streamobj, std::string *data, bool fin);
@@ -239,6 +258,8 @@ namespace quic
         void processSessionClose(Http3WTSession *sessionobj, uint32_t errorcode, const std::string &path);
         void processSessionReady(Http3WTSession *sessionobj);
 
+        void processServerStatus(Http3Server *serverobj, NetworkStatus status, ServerStatusDetails * details);
+
         void processStream(bool incom, bool bidi, Http3WTSession *sessionobj, Http3WTStream *stream);
         void processStreamRecvSignal(Http3WTStream *streamobj, WebTransportStreamError error_code, NetworkTask task);
         void processStreamRead(Http3WTStream *streamobj, std::string *data, bool fin);

package/src/http3server.cc

@@ -93,9 +93,12 @@ namespace quic
       dispatcher_.reset(CreateQuicDispatcher());
       dispatcher_->InitializeWithWriter(new QuicDefaultPacketWriter(fd_));
       std::move(closer).Cancel();
+
+      eventloop_->informServerStatus(this, NetListening, getStatusDetails());
       return true;
     }
 
+    eventloop_->informServerStatus(this, NetError, getStatusDetails());
     return false;
   }
 
@@ -113,6 +116,7 @@ namespace quic
     QuicUdpSocketApi api;
     api.Destroy(fd_);
     fd_ = -1;
+    eventloop_->informServerStatus(this, NetClose, getStatusDetails());
     eventloop_->informUnref(this->getJS()); // must be done on the other thread...
     return true;
   }
@@ -397,5 +401,4 @@ namespace quic
       obj->eventloop_->Schedule(task);
     }
   }
-
 }

package/src/http3server.h

@@ -50,6 +50,7 @@ namespace quic
 
         void addPath(const Napi::CallbackInfo &info);
 
+
         static void InitExports(Napi::Env env, Napi::Object exports)
         {
             Napi::Function tplsrv = DefineClass(env, "Http3WebTransportServer",
@@ -94,6 +95,13 @@ namespace quic
 
         Http3ServerJS *getJS() { return js_; };
 
+        ServerStatusDetails *getStatusDetails() {
+             ServerStatusDetails* details = new ServerStatusDetails();
+             details->host = host_;
+             details->port = port_;
+             return details;
+        }
+
     private:
         bool startServerInt();
         bool stopServerInt();

package/src/http3serversession.h

@@ -107,7 +107,7 @@ namespace quic
     {
       if (ShouldNegotiateWebTransport())
       {
-        return HttpDatagramSupport::kDraft04And09;
+        return HttpDatagramSupport::kRfcAndDraft04;
       }
       return QuicServerSessionBase::LocalHttpDatagramSupport();
     }

package/test/bidirectional-streams.spec.js

@@ -0,0 +1,137 @@
+/* eslint-disable no-undef */
+import { createServer } from './fixtures/server.js'
+import { getReaderValue } from './fixtures/reader-value.js'
+import { WebTransport } from '../lib/index.js'
+import { expect } from 'chai'
+import { readStream } from './fixtures/read-stream.js'
+import { writeStream } from './fixtures/write-stream.js'
+import { defer } from '../lib/utils.js'
+
+/**
+ * @template T
+ * @typedef {import('../lib/types').Deferred<T>} Deferred<T>
+ */
+
+const SERVER_PATH = '/bidirectional-streams'
+
+describe('bidirectional streams', function () {
+  /** @type {import('../lib/server').Http3Server} */
+  let server
+  /** @type {import('./fixtures/certificate.js').Certificate} */
+  let certificate
+  /** @type {import('../lib/dom').WebTransport | undefined} */
+  let client
+  /** @type {string} */
+  let url
+
+  this.timeout(30000) // this can vary depending on the setup and is not an error
+  // but it smells like a work around regarding a deeper problem
+
+  beforeEach(async () => {
+    this.timeout(2000)
+    ;({ server, certificate } = await createServer())
+    server.startServer()
+    await server.ready
+
+    const address = server.address()
+
+    if (address == null || address.port == null) {
+      throw new Error('No address')
+    }
+
+    url = `https://${address.host}:${address.port}`
+  })
+
+  afterEach(async () => {
+    if (client != null) {
+      client.close()
+    }
+
+    if (server != null) {
+      server.stopServer()
+      await server.closed
+    }
+  })
+
+  it('sends and receives data over an outgoing bidirectional stream', async () => {
+    this.timeout(200)
+    // server context - waits for the client to open a bidi stream and pipes it back to them
+    Promise.resolve().then(async () => {
+      const session = await getReaderValue(server.sessionStream(SERVER_PATH))
+      const bidiStream = await getReaderValue(
+        session.incomingBidirectionalStreams
+      )
+      // redirect input to output
+      await bidiStream.readable.pipeTo(bidiStream.writable)
+    })
+
+    // client context - connects to the server, opens a bidi stream, sends some data and reads the response
+    client = new WebTransport(`${url}${SERVER_PATH}`, {
+      serverCertificateHashes: [
+        {
+          algorithm: 'sha-256',
+          value: certificate.hash
+        }
+      ]
+    })
+    await client.ready
+
+    const input = [
+      Uint8Array.from([0, 1, 2, 3, 4]),
+      Uint8Array.from([5, 6, 7, 8, 9]),
+      Uint8Array.from([10, 11, 12, 13, 14])
+    ]
+
+    const stream = await client.createBidirectionalStream()
+    await writeStream(stream.writable, input)
+
+    const output = await readStream(stream.readable)
+    expect(output).to.deep.equal(
+      input,
+      'Did not receive the same bytes we sent'
+    )
+  })
+
+  it('sends and receives data over an incoming bidirectional stream', async () => {
+    this.timeout(200)
+    /** @type {Deferred<Uint8Array[]>} */
+    const serverData = defer()
+    const input = [
+      Uint8Array.from([0, 1, 2, 3, 4]),
+      Uint8Array.from([5, 6, 7, 8, 9]),
+      Uint8Array.from([10, 11, 12, 13, 14])
+    ]
+
+    // server context - waits for the client to connect, opens a bidi stream, sends some data and reads the response
+    Promise.resolve().then(async () => {
+      const session = await getReaderValue(server.sessionStream(SERVER_PATH))
+      const stream = await session.createBidirectionalStream()
+
+      await writeStream(stream.writable, input)
+
+      const output = await readStream(stream.readable)
+      serverData.resolve(output)
+    })
+
+    // client context - waits for the server to open a bidi stream then pipes it back to them
+    client = new WebTransport(`${url}${SERVER_PATH}`, {
+      serverCertificateHashes: [
+        {
+          algorithm: 'sha-256',
+          value: certificate.hash
+        }
+      ]
+    })
+    await client.ready
+
+    const bidiStream = await getReaderValue(client.incomingBidirectionalStreams)
+    // redirect input to output
+    await bidiStream.readable.pipeTo(bidiStream.writable)
+
+    const received = await serverData.promise
+    expect(received).to.deep.equal(
+      input,
+      'Did not receive the same bytes we sent'
+    )
+  })
+})

package/test/datagrams.spec.js

@@ -0,0 +1,131 @@
+/* eslint-disable no-undef */
+import { createServer } from './fixtures/server.js'
+import { getReaderValue } from './fixtures/reader-value.js'
+import { WebTransport } from '../lib/index.js'
+import { expect } from 'chai'
+import { readStream } from './fixtures/read-stream.js'
+import { writeStream } from './fixtures/write-stream.js'
+import { defer } from '../lib/utils.js'
+
+/**
+ * @template T
+ * @typedef {import('../lib/types').Deferred<T>} Deferred<T>
+ */
+
+const SERVER_PATH = '/datagrams'
+
+describe('datagrams', function () {
+  /** @type {import('../lib/server').Http3Server} */
+  let server
+  /** @type {import('./fixtures/certificate.js').Certificate} */
+  let certificate
+  /** @type {import('../lib/dom').WebTransport | undefined} */
+  let client
+  /** @type {string} */
+  let url
+
+  beforeEach(async () => {
+    ;({ server, certificate } = await createServer())
+    server.startServer()
+    await server.ready
+
+    const address = server.address()
+
+    if (address == null || address.port == null) {
+      throw new Error('No address')
+    }
+
+    url = `https://${address.host}:${address.port}`
+  })
+
+  afterEach(async () => {
+    if (client != null) {
+      client.close()
+    }
+
+    if (server != null) {
+      server.stopServer()
+      await server.closed
+    }
+  })
+
+  it('client sends datagrams to the server', async () => {
+    this.timeout(200)
+    // server context - waits for the client to connect and pipes their datagrams back to them
+    Promise.resolve().then(async () => {
+      const session = await getReaderValue(server.sessionStream(SERVER_PATH))
+
+      // redirect input to output
+      await session.datagrams.readable.pipeTo(session.datagrams.writable)
+    })
+
+    // client context - connects to the server, sends some datagrams and reads the response
+    client = new WebTransport(`${url}${SERVER_PATH}`, {
+      serverCertificateHashes: [
+        {
+          algorithm: 'sha-256',
+          value: certificate.hash
+        }
+      ]
+    })
+    await client.ready
+
+    const input = [
+      Uint8Array.from([0, 1, 2, 3, 4]),
+      Uint8Array.from([5, 6, 7, 8, 9]),
+      Uint8Array.from([10, 11, 12, 13, 14])
+    ]
+
+    await writeStream(client.datagrams.writable, input)
+
+    const output = await readStream(client.datagrams.readable, input.length)
+    expect(output).to.deep.equal(
+      input,
+      'Did not receive the same bytes we sent'
+    )
+  })
+
+  it('receives datagrams from the server', async () => {
+    this.timeout(200)
+    /** @type {Deferred<Uint8Array[]>} */
+    const serverData = defer()
+    const input = [
+      Uint8Array.from([0, 1, 2, 3, 4]),
+      Uint8Array.from([5, 6, 7, 8, 9]),
+      Uint8Array.from([10, 11, 12, 13, 14])
+    ]
+
+    // server context - waits for the client to connect, sends some datagrams and reads the response
+    Promise.resolve().then(async () => {
+      const session = await getReaderValue(server.sessionStream(SERVER_PATH))
+
+      await writeStream(session.datagrams.writable, input)
+
+      const output = await readStream(session.datagrams.readable, input.length)
+
+      // have to close the session to end the client's datagram stream
+      session.close()
+      serverData.resolve(output)
+    })
+
+    // client context - pipes the server's datagrams back to them
+    client = new WebTransport(`${url}${SERVER_PATH}`, {
+      serverCertificateHashes: [
+        {
+          algorithm: 'sha-256',
+          value: certificate.hash
+        }
+      ]
+    })
+    await client.ready
+
+    // redirect input to output
+    await client.datagrams.readable.pipeTo(client.datagrams.writable)
+
+    const received = await serverData.promise
+    expect(received).to.deep.equal(
+      input,
+      'Did not receive the same bytes we sent'
+    )
+  })
+})

package/test/echoclient.js

@@ -3,18 +3,22 @@
 // found in the LICENSE file.
 
 import { echoTestsConnection } from './testsuite.js'
-import { WebTransport  } from '../src/webtransport.js'
+import { WebTransport } from '../lib/index.js'
 
+/**
+ * @param {{ hostname: string, port: number }} args
+ * @param {{ serverCertificateHashes: Array<{ algorithm: string, value: string }> }} hashes
+ */
 async function startClientTests(args, hashes) {
   const url = 'https://' + args.hostname + ':' + args.port + '/echo'
   console.log('startconnection')
-  const hashargs = { ...hashes }
-  hashargs.serverCertificateHashes = hashes.serverCertificateHashes.map(
-    (el) => ({
+  const hashargs = {
+    ...hashes,
+    serverCertificateHashes: hashes.serverCertificateHashes.map((el) => ({
       algorithm: el.algorithm,
       value: Buffer.from(el.value.split(':').map((el) => parseInt(el, 16)))
-    })
-  )
+    }))
+  }
   // eslint-disable-next-line no-undef
   console.log('hashagrs', hashargs)
   const transport = new WebTransport(url, hashargs)

package/test/echoserver.js

@@ -2,11 +2,11 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-import { Http3Server } from '../src/webtransport.js'
+import { Http3Server } from '../lib/index.js'
 import { runEchoServer } from './testsuite.js'
 import { existsSync, readFileSync, writeFile } from 'node:fs'
-import { generateWebTransportCertificate } from './certificate.js'
-
+// @ts-ignore
+import { generateWebTransportCertificate } from './fixtures/certificate.js'
 
 let certificate = null
 
@@ -27,24 +27,22 @@ if (!certificate) {
   certificate = await generateWebTransportCertificate(attrs, {
     days: 13
   })
-  writeFile('./certificatecache.json', JSON.stringify(certificate),(err)=>{
+  writeFile('./certificatecache.json', JSON.stringify(certificate), (err) => {
     if (err) console.log('write certificate cache error', err)
   })
 }
 
 console.log('certificate hash ', certificate.fingerprint)
 
-
-
 try {
   const http3server = new Http3Server({
     port: 8080,
     host: '0.0.0.0',
     secret: 'mysecret',
-    cert: certificate.cert, 
+    cert: certificate.cert,
     privKey: certificate.private
   })
-  
+
   runEchoServer(http3server)
   http3server.startServer() // you can call destroy to remove the server
 } catch (error) {

package/test/event-loop.specoff.js

@@ -0,0 +1,23 @@
+/* eslint-disable no-undef */
+import { expect } from 'chai'
+import { Http3EventLoop } from '../lib/event-loop.js'
+
+describe('event-loop', () => {
+  beforeEach(() => {
+    if (Http3EventLoop.globalLoop != null) {
+      // shut down loop, otherwise we have to wait for
+      // it to time out which takes a long time.
+      Http3EventLoop.globalLoop.shutdownEventLoop()
+    }
+  })
+
+  it('should start and stop the event loop', () => {
+    expect(Http3EventLoop.globalLoop).to.be.null
+
+    Http3EventLoop.createGlobalEventLoop()
+    expect(Http3EventLoop.globalLoop).to.not.be.null
+
+    Http3EventLoop.globalLoop?.shutdownEventLoop()
+    expect(Http3EventLoop.globalLoop).to.be.null
+  })
+})