Send the native NUClearNet logs to the JavaScript logger

The library wrote its logs straight to stderr while our own messages went
through console.error with a [NUClearNet.js] prefix, so turning debug on
gave you two differently formatted streams and the native half ignored
any redirection of console.

NUClear now lets an embedder install a log handler, so hand the native
messages to the same _log path as everything else. The component the
message came from is included as a field.

Also syncs the vendored nuclear subtree from NUClear@b7caa31c, which
brings in the log handler along with the SO_REUSEADDR/SO_REUSEPORT
pairing and member initializer changes made since 18c2877b.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: Trent Houliston

README.md

@@ -8,7 +8,7 @@ Node.js module for interacting with the [NUClear](https://github.com/Fastcode/NU
 
 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@18c2877b](https://github.com/Fastcode/NUClear/commit/18c2877b)).
+The vendored NUClear tree is updated via `git subtree` from the `houliston/nuclearnet-v2` branch (currently [NUClear@b7caa31c](https://github.com/Fastcode/NUClear/commit/b7caa31c)).
 
 Peer join events may arrive slightly later than in 1.x because connection requires both multicast announce and a unicast CONNECT handshake.
 

index.d.ts

@@ -35,7 +35,7 @@ export interface NUClearNetOptions {
 
   /**
    * Enable debug logging. `true` is equivalent to `info`.
-   * Native logs go to stderr; JavaScript logs use `console.error` with a `[NUClearNet.js]` prefix.
+   * 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';

index.js

@@ -70,6 +70,7 @@ class NUClearNet extends EventEmitter {
     this._net.onJoin(this._onJoin.bind(this));
     this._net.onLeave(this._onLeave.bind(this));
     this._net.onWait(this._onWait.bind(this));
+    this._net.onLog(this._onNativeLog.bind(this));
 
     this._applyLogLevel(parseLogLevel(this._constructorDebug, process.env.NUCLEARNET_DEBUG));
   }
@@ -79,6 +80,19 @@ class NUClearNet extends EventEmitter {
     this._net.setLogLevel(level);
   }
 
+  /**
+   * A log message from the native NUClearNet library.
+   * The native side has already filtered by level, but check again so a level change that
+   * races with a queued message can't slip through.
+   *
+   * @param {number} level
+   * @param {string} component
+   * @param {string} message
+   */
+  _onNativeLog(level, component, message) {
+    this._log(level, message, { component: component });
+  }
+
   /**
    * @param {number} level
    * @param {string} message

src/NetworkBinding.cpp

@@ -137,6 +137,11 @@ NetworkBinding::NetworkBinding(const Napi::CallbackInfo& info) : Napi::ObjectWra
     this->net.set_socket_change_callback([this]() { this->request_listener_restart(); });
 }
 
+NetworkBinding::~NetworkBinding() {
+    // The log handler is global and captures this, so make sure it can't outlive us even if destroy() was missed
+    network::NUClearNet::set_log_handler(nullptr);
+}
+
 void NetworkBinding::stop_listener() {
     ++this->listener_generation;
 
@@ -340,6 +345,26 @@ void NetworkBinding::OnWait(const Napi::CallbackInfo& info) {
     });
 }
 
+void NetworkBinding::OnLog(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+
+    on_log = Napi::ThreadSafeFunction::New(env, info[0].As<Napi::Function>(), "OnLog", 0, 1);
+
+    // Hand the native logs to the JavaScript logger so they come out the same way as our own messages.
+    // This is a global handler, so the most recently created network wins if there is more than one.
+    network::NUClearNet::set_log_handler(
+        [this](network::LogLevel level, const char* component, const std::string& message) {
+            on_log.BlockingCall(
+                [level, component = std::string(component), message](Napi::Env env, Napi::Function js_callback) {
+                    js_callback.Call({
+                        Napi::Number::New(env, static_cast<int>(level)),
+                        Napi::String::New(env, component),
+                        Napi::String::New(env, message),
+                    });
+                });
+        });
+}
+
 void NetworkBinding::Reset(const Napi::CallbackInfo& info) {
     Napi::Env env = info.Env();
 
@@ -468,6 +493,9 @@ void NetworkBinding::Destroy(const Napi::CallbackInfo& info) {
 
     this->stop_listener();
 
+    // Put the native logs back on stderr before releasing the function they were going to
+    network::NUClearNet::set_log_handler(nullptr);
+
     this->net.set_socket_change_callback([]() {});
     this->net.set_packet_callback(
         [](const sock_t&, const std::string&, uint64_t, bool, std::vector<uint8_t>&&) {});
@@ -479,6 +507,9 @@ void NetworkBinding::Destroy(const Napi::CallbackInfo& info) {
     on_join.Release();
     on_leave.Release();
     on_wait.Release();
+    if (this->on_log) {
+        this->on_log.Release();
+    }
     if (this->listener_restart) {
         this->listener_restart.Release();
     }
@@ -523,6 +554,9 @@ void NetworkBinding::Init(Napi::Env env, Napi::Object exports) {
                                        InstanceMethod<&NetworkBinding::SetLogLevel>(
                                            "setLogLevel",
                                            static_cast<napi_property_attributes>(napi_writable | napi_configurable)),
+                                       InstanceMethod<&NetworkBinding::OnLog>(
+                                           "onLog",
+                                           static_cast<napi_property_attributes>(napi_writable | napi_configurable)),
                                        InstanceMethod<&NetworkBinding::Destroy>(
                                            "destroy",
                                            static_cast<napi_property_attributes>(napi_writable | napi_configurable))});

src/NetworkBinding.hpp

@@ -31,13 +31,15 @@ class NetworkListener;
 class NetworkBinding : public Napi::ObjectWrap<NetworkBinding> {
 public:
     NetworkBinding(const Napi::CallbackInfo& info);
+    ~NetworkBinding();
 
     Napi::Value Hash(const Napi::CallbackInfo& info);
     void Send(const Napi::CallbackInfo& info);
     void OnPacket(const Napi::CallbackInfo& info);
     void OnJoin(const Napi::CallbackInfo& info);
     void OnLeave(const Napi::CallbackInfo& info);
     void OnWait(const Napi::CallbackInfo& info);
+    void OnLog(const Napi::CallbackInfo& info);
     void Reset(const Napi::CallbackInfo& info);
     void Process(const Napi::CallbackInfo& info);
     void Shutdown(const Napi::CallbackInfo& info);
@@ -57,6 +59,7 @@ class NetworkBinding : public Napi::ObjectWrap<NetworkBinding> {
     Napi::ThreadSafeFunction on_join;
     Napi::ThreadSafeFunction on_leave;
     Napi::ThreadSafeFunction on_wait;
+    Napi::ThreadSafeFunction on_log;
     Napi::ThreadSafeFunction listener_restart;
 
 #ifdef _WIN32

src/nuclear/docs/explanation/nuclearnet.md

@@ -153,12 +153,46 @@ The connection is only considered "up" once both the announce path and data path
 
 ### Announce address options
 
+The announce address determines how discovery packets are delivered.
+All nodes in a mesh must agree on the same address and port.
+For multi-peer discovery on one host, the address must fan out to every process bound to the shared announce port.
+
+#### Socket binding
+
+NUClearNet binds the announce socket to **all interfaces** (`INADDR_ANY`) by default, even when the announce address is multicast or broadcast.
+This default is required for broadcast fan-out on macOS.
+An explicit `bind_address` to a specific interface IP can prevent broadcast reception on macOS.
+
+#### Reuse options
+
+NUClearNet sets **`SO_REUSEADDR`** on all platforms and **`SO_REUSEPORT`** when the platform provides it — the two options are always paired where `SO_REUSEPORT` exists.
+Platforms without `SO_REUSEPORT` use `SO_REUSEADDR` alone.
+Socket setup is consistent; fan-out vs load-balance depends on the announce address and OS stack.
+
+#### Address types and multi-peer validity
+
 The announce address can be:
 
 - **Multicast** (e.g., `239.226.152.162`) — the most common setup.
-    All nodes on the same network join the multicast group and hear each other's announcements.
-- **Broadcast** (e.g., `255.255.255.255`) — works on simple LANs without multicast support.
-- **Unicast** — for point-to-point setups or testing.
+    All nodes join the multicast group and hear each other's announcements.
+    Valid for multi-peer on one host on both Linux and macOS (recommended on macOS).
+- **Subnet broadcast** (e.g., `192.168.1.255`) — all nodes on the subnet receive announce messages.
+    Valid for multi-peer on one host on both platforms (requires default `INADDR_ANY` bind on macOS).
+- **Global broadcast** (`255.255.255.255`) — valid for multi-peer on one host on both platforms (noisy; requires default bind on macOS).
+- **Loopback broadcast** (`127.255.255.255`) — valid for multi-peer local dev on **Linux only**.
+    macOS does not deliver UDP to this address locally — a macOS stack limitation, not reuse-option behavior.
+- **Unicast** (e.g., `127.0.0.1`, `192.168.1.50`) — for point-to-point setups between two known peers.
+    Unicast does not fan out to every socket bound on the shared announce port — **invalid for multi-peer on one host** on both platforms.
+
+#### Quick reference — multi-peer on one host
+
+| Address | Linux | macOS |
+| ------- | ----- | ----- |
+| Multicast `239.226.152.162` | Valid | Valid (recommended) |
+| Loopback broadcast `127.255.255.255` | Valid (recommended local dev) | **Invalid** |
+| Subnet broadcast `x.x.x.255` | Valid | Valid (default bind) |
+| Global broadcast `255.255.255.255` | Valid | Valid (default bind) |
+| Unicast `127.0.0.1` / specific IP | **Invalid** | **Invalid** |
 
 ### NAT-friendly port learning
 
@@ -851,12 +885,37 @@ emit(std::make_unique<NetworkConfiguration>(
 | `name`             | `string`   | —                   | Unique name for this node on the network        |
 | `announce_address` | `string`   | `"239.226.152.162"` | Address for node discovery announcements        |
 | `announce_port`    | `uint16_t` | `7447`              | Port for announce messages                      |
-| `bind_address`     | `string`   | `""` (all)          | Local interface to bind to                      |
+| `bind_address`     | `string`   | `""` (all)          | Local interface to bind to (default `INADDR_ANY`; required for broadcast fan-out on macOS) |
 | `mtu`              | `uint16_t` | `1500`              | Maximum transmission unit (fragments if larger) |
+| `log_level`        | `LogLevel` | `UNKNOWN` (off)     | Level to log the networking internals at        |
 
 When a new configuration is received, the `NetworkController` tears down existing sockets and reinitializes with the new settings.
 The node name becomes the identifier that other peers see in `NetworkJoin` events.
 
+### Logging
+
+Every component logs what it is doing through a single sink in `Log.hpp`, gated by a process wide log level that
+defaults to `Off`.
+Because the library is usable without the reactor framework, that sink is a callback rather than a hard dependency
+on NUClear's logging system:
+
+```cpp
+using LogHandler = std::function<void(LogLevel level, const char* component, const std::string& message)>;
+NUClearNet::set_log_handler(handler);  // an empty handler restores the stderr default
+```
+
+Each embedder installs its own handler:
+
+| Embedder            | Where the messages go                                                      |
+| ------------------- | -------------------------------------------------------------------------- |
+| `NetworkController` | Re-emitted as NUClear `LogMessage`s, so the usual log handlers pick them up |
+| NUClearNet.js       | Handed to the JavaScript logger alongside the binding's own messages        |
+| Standalone          | `std::cerr`, formatted as `[NUClearNet:<component>] <level> <message>`      |
+
+Under the reactor framework `NetworkConfiguration::log_level` drives both the library level (which decides what
+the library hands to the handler) and the `NetworkController` reactor level (which decides what it emits), so a
+single setting controls the whole path.
+
 ### Internal engine parameters
 
 The `NUClearNet` engine supports additional parameters beyond what's exposed through `NetworkConfiguration`:

src/nuclear/docs/how-to/networking.md

@@ -55,8 +55,44 @@ public:
 | `name`             | `string`   | —                   | Unique name for this node on the network        |
 | `announce_address` | `string`   | `"239.226.152.162"` | Address for node discovery announcements        |
 | `announce_port`    | `uint16_t` | `7447`              | Port for announce messages                      |
-| `bind_address`     | `string`   | `""` (all)          | Local interface to bind to                      |
+| `bind_address`     | `string`   | `""` (all)          | Local interface to bind to (see [Forming a mesh](#forming-a-mesh) — default `INADDR_ANY` is required for broadcast fan-out on macOS) |
 | `mtu`              | `uint16_t` | `1500`              | Maximum transmission unit (fragments if larger) |
+| `log_level`        | `LogLevel` | `UNKNOWN` (off)     | Level to log the networking internals at (see [Logging](#logging)) |
+
+### Logging
+
+NUClearNet logs what it is doing internally — discovery, handshakes, fragmentation, retransmission.
+Set `log_level` on the `NetworkConfiguration` to turn it on:
+
+```cpp
+emit(std::make_unique<NUClear::message::NetworkConfiguration>(
+    "alice",             // Node name
+    "239.226.152.162",   // Multicast announce address
+    7447,                // Announce port
+    "",                  // Bind address
+    1500,                // MTU
+    NUClear::LogLevel::DEBUG
+));
+```
+
+This sets both the log level inside the NUClearNet library and the log level of the `NetworkController` reactor
+that emits the messages, so the two cannot disagree.
+The messages come out through the normal NUClear logging system as `LogMessage`s, so your existing log handlers
+see them alongside everything else.
+Leaving `log_level` as `UNKNOWN` disables the networking logs entirely, which is the default.
+
+When NUClearNet is used as a standalone library (without the reactor framework) the messages are written to
+stderr instead. Call `NUClearNet::set_log_handler` to redirect them into your own logging system:
+
+```cpp
+NUClear::network::NUClearNet::set_log_level(NUClear::network::LogLevel::Debug);
+NUClear::network::NUClearNet::set_log_handler(
+    [](NUClear::network::LogLevel level, const char* component, const std::string& message) {
+        my_logger.write(level, component, message);
+    });
+```
+
+Pass an empty handler to go back to the stderr default.
 
 ### Network modes
 
@@ -67,6 +103,8 @@ NUClearNet supports several discovery modes depending on the `announce_address`
 | **Multicast IPv4**    | `239.x.x.x`  | `239.226.152.162` | LAN discovery, multiple nodes   |
 | **Multicast IPv6**    | `ff02::x`    | `ff02::1`         | IPv6 LAN discovery              |
 | **Broadcast IPv4**    | `x.x.x.255`  | `192.168.1.255`   | Simple LAN, all nodes on subnet |
+| **Loopback broadcast** | `127.255.255.255` | `127.255.255.255` | Local dev on Linux only (see [Forming a mesh](#forming-a-mesh)) |
+| **Loopback unicast** | `127.0.0.1` | `127.0.0.1` | Point-to-point between two nodes (not multi-peer on shared port) |
 | **Unicast IPv4/IPv6** | Specific IP  | `192.168.1.50`    | Point-to-point, two nodes       |
 
 #### Multicast (Default)
@@ -109,6 +147,63 @@ emit(std::make_unique<NUClear::message::NetworkConfiguration>(
 
 In unicast mode, each peer announces directly to the other.
 This is useful when multicast/broadcast is unavailable (e.g., across subnets or VPNs).
+Unicast does **not** fan out to every socket bound on the shared announce port, so it cannot form a multi-peer mesh on one host.
+
+### Forming a mesh
+
+A mesh forms when all nodes share the same `announce_address` and `announce_port`.
+Each node periodically sends discovery packets to that address; every peer that receives them can discover the others and complete a CONNECT handshake.
+
+For multi-peer discovery on one machine, announce traffic must reach **every** process bound to the shared announce port.
+Which addresses satisfy that depends on the announce address and OS stack, not on socket option policy.
+
+#### Socket binding
+
+By default, NUClearNet binds the announce socket to **all interfaces** (`INADDR_ANY`), regardless of the announce address.
+This default is required for broadcast fan-out on macOS.
+Setting `bind_address` to a specific interface IP can prevent broadcast reception on macOS — leave it empty unless you have a specific reason to bind to one interface.
+
+#### Reuse options
+
+Multiple processes on one host must bind the same UDP announce port.
+NUClearNet sets **`SO_REUSEADDR`** on all platforms and **`SO_REUSEPORT`** when the platform provides it — the two options are always paired where `SO_REUSEPORT` exists.
+Socket setup is consistent everywhere; what varies is which announce addresses fan out to every bound socket vs one socket.
+
+#### Valid announce addresses
+
+| Address | Linux | macOS |
+| ------- | ----- | ----- |
+| `239.226.152.162` (multicast, default) | Valid — all sockets join the group | Valid — recommended |
+| `127.255.255.255` (loopback broadcast) | Valid — recommended for local dev | **Invalid** — macOS does not deliver UDP to this address locally (stack limitation) |
+| `192.168.x.255` (subnet broadcast) | Valid | Valid — requires default `INADDR_ANY` bind |
+| `255.255.255.255` (global broadcast) | Valid — noisy | Valid — requires default `INADDR_ANY` bind |
+| `127.0.0.1` or specific IP (unicast) | **Invalid** — one bound socket | **Invalid** — load-balanced to one bound socket |
+
+```cpp
+// Linux local dev — loopback broadcast fans out to every peer
+emit(std::make_unique<NUClear::message::NetworkConfiguration>(
+    "my-node", "127.255.255.255", 7447));
+
+// macOS local dev — use the default multicast address
+emit(std::make_unique<NUClear::message::NetworkConfiguration>(
+    "my-node", "239.226.152.162", 7447));
+```
+
+#### Cross-platform summary
+
+| Scenario | Recommended address |
+| -------- | ------------------- |
+| LAN, multiple machines | `239.226.152.162` (multicast) or subnet broadcast |
+| Local dev, Linux | `127.255.255.255` (loopback broadcast) or multicast |
+| Local dev, macOS | `239.226.152.162` (multicast) |
+| Two known peers, point-to-point | Unicast to each other's IP (not multi-peer on shared port) |
+
+#### Loopback (local development)
+
+When running multiple NUClearNet processes on one machine, pick an announce address that fans out to every listener on the shared port (see tables above).
+
+On Linux, `127.255.255.255` is the simplest local-dev choice when you want to avoid multicast.
+On macOS, use the default multicast address — loopback broadcast is not delivered locally.
 
 ## 2. Send Messages