NUClearNet 2 (protocol 0x03)

.dockerignore

@@ -0,0 +1,4 @@
+node_modules
+build
+.git
+.github

.github/workflows/docker-test.yml

@@ -0,0 +1,16 @@
+name: Docker Linux test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build and test in Docker
+        run: docker build -t nuclearnet.js-test .

Dockerfile

@@ -0,0 +1,15 @@
+FROM node:20-bookworm
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends python3 make g++ \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY . .
+
+RUN npm run build
+CMD ["npm", "test"]

README.md

@@ -4,6 +4,14 @@
 
 Node.js module for interacting with the [NUClear](https://github.com/Fastcode/NUClear) network.
 
+## NUClearNet 2 (v2.0.0+)
+
+Version 2 uses the redesigned **NUClearNet** library from [NUClear PR #190](https://github.com/Fastcode/NUClear/pull/190) (wire protocol **0x03**). It is **not** compatible with 1.x clients or NUClear builds that still use the old `NUClearNetwork` stack (protocol 0x02). Upgrade Node clients and NUClear robots together.
+
+The vendored NUClear tree is updated via `git subtree` from the `houliston/nuclearnet-v2` branch (currently [NUClear@92711931](https://github.com/Fastcode/NUClear/commit/92711931)).
+
+Peer join events may arrive slightly later than in 1.x because connection requires both multicast announce and a unicast CONNECT handshake.
+
 ## Installation
 
 The package contains a native module, so you'll need a working C++ compiler on your system to install and build it.
@@ -57,6 +65,25 @@ net.on('packet_type_a', function (packet) {
 net.connect({ name: 'My Name' });
 ```
 
+## Debugging
+
+Logging is off by default. Enable tiered logs with `connect({ debug: ... })`, the constructor default, or the `NUCLEARNET_DEBUG` environment variable (`connect` wins when both are set).
+
+| Level | JavaScript | Native (stderr) |
+| ----- | ---------- | ----------------- |
+| `info` | connect, join, leave, subscriptions | reset, shutdown, peer timeouts |
+| `debug` | send, packets, listener subscribe/unsubscribe | handshake, announce/connect, send routing |
+| `trace` | process wait scheduling | `process()` ticks, socket reads |
+
+```js
+const net = new NUClearNet({ debug: 'info' });
+net.connect({ name: 'node-1', debug: 'debug' }); // overrides constructor for this session
+```
+
+```bash
+NUCLEARNET_DEBUG=info node your-app.js
+```
+
 ## API
 
 See [`index.d.ts`](./index.d.ts) for types and API details.

binding.gyp

@@ -6,17 +6,22 @@
                 'src/binding.cpp',
                 'src/NetworkBinding.cpp',
                 'src/NetworkListener.cpp',
-                'src/nuclear/src/extension/network/NUClearNetwork.cpp',
-                'src/nuclear/src/util/platform.cpp',
-                'src/nuclear/src/util/network/get_interfaces.cpp',
-                'src/nuclear/src/util/network/if_number_from_address.cpp',
+                'src/nuclear/src/nuclearnet/Discovery.cpp',
+                'src/nuclear/src/nuclearnet/Log.cpp',
+                'src/nuclear/src/nuclearnet/Fragmentation.cpp',
+                'src/nuclear/src/nuclearnet/NUClearNet.cpp',
+                'src/nuclear/src/nuclearnet/PacketDeduplicator.cpp',
+                'src/nuclear/src/nuclearnet/RTTEstimator.cpp',
+                'src/nuclear/src/nuclearnet/Reliability.cpp',
+                'src/nuclear/src/nuclearnet/Routing.cpp',
                 'src/nuclear/src/util/network/resolve.cpp',
+                'src/nuclear/src/util/platform.cpp',
                 'src/nuclear/src/util/serialise/xxhash.cpp'
             ],
             'cflags': [],
             'include_dirs': [
                 '<!@(node -p "require(\'node-addon-api\').include")',
-                'src/nuclear/src/include'
+                'src/nuclear/src'
             ],
             "defines": [
                 # Restrict NAPI to v6 (to support Node v10)
@@ -82,7 +87,12 @@
                 ],
                 [
                     'OS=="win"', {
-                        'defines': [ '_HAS_EXCEPTIONS=1' ]
+                        'defines': [ '_HAS_EXCEPTIONS=1' ],
+                        'libraries': [
+                            'ws2_32.lib',
+                            'mswsock.lib',
+                            'iphlpapi.lib'
+                        ]
                     }
                 ]
             ]

index.d.ts

@@ -32,6 +32,13 @@ export interface NUClearNetOptions {
 
   /** The MTU of the network. Used for splitting packets optimally. */
   mtu?: number;
+
+  /**
+   * Enable debug logging. `true` is equivalent to `info`.
+   * Logs from the native library and from JavaScript both use `console.error` with a `[NUClearNet.js]` prefix.
+   * The `NUCLEARNET_DEBUG` environment variable applies when this option is omitted.
+   */
+  debug?: boolean | 'off' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
 }
 
 /**
@@ -131,8 +138,11 @@ export declare class NUClearNet {
   /** Stores the `connect()` options. Is an empty object until `connect()` is called. */
   options: Partial<NUClearNetOptions>;
 
-  /** Create a new NUClearNet instance. */
-  public constructor();
+  /**
+   * Create a new NUClearNet instance.
+   * @param options Optional default `debug` level (overridden by `connect({ debug })`).
+   */
+  public constructor(options?: { debug?: NUClearNetOptions['debug'] });
 
   /** Emitted when a peer joins or leaves the network. */
   public on(event: 'nuclear_join' | 'nuclear_leave', callback: (peer: NUClearNetPeer) => void): this;