librats 1.0.2 → 2.2.0

package/README.md

@@ -1,410 +1,224 @@
-# LibRats Node.js Bindings
+# librats — Node.js bindings
 
-Node.js bindings for librats - A high-performance peer-to-peer networking library with support for DHT, GossipSub, file transfer, NAT traversal, and more.
+Node.js bindings for [librats](../README.md), a C++17 peer-to-peer networking
+library: encrypted transport, DHT/mDNS discovery, NAT traversal, pub/sub, typed
+JSON messaging and file transfer.
 
-## Features
+## The model
 
-- **Peer-to-peer networking** - Direct connections between peers
-- **DHT (Distributed Hash Table)** - Decentralized peer discovery
-- **GossipSub** - Topic-based publish/subscribe messaging
-- **File Transfer** - Send and receive files and directories
-- **mDNS Discovery** - Local network peer discovery
-- **NAT Traversal** - STUN/ICE support for connecting through firewalls
-- **Encryption** - End-to-end encryption using Noise protocol
-- **Message Exchange** - String, binary, and JSON message types
-- **Configuration Persistence** - Save and restore client settings
+A `RatsNode` is one librats node. On its own it gives you secure transport
+(Noise XX over TCP **or** the library's reliable stream over UDP, both on the
+same port), a self-certifying peer id, manual dialing, and raw messaging on named
+channels — nothing else. Discovery, pub/sub, JSON messaging, file transfer, NAT
+port mapping, hole punching, RTT probing and reconnection are **opt-in
+subsystems**: you pay only for what you turn on.
 
-## Installation
+Two rules follow from that:
+
+- **Enable subsystems and register callbacks before `start()`.** Enabling after
+  start throws `RATS_ERR_ALREADY_STARTED`; using a subsystem before its enable
+  throws `RATS_ERR_NOT_ENABLED`.
+- **Callbacks are marshalled onto the JS thread** from a librats reactor thread.
+  Keep them short anyway — a slow handler backs up the reactor's queue.
 
-### Quick Install
+Fallible calls **throw** an `Error` whose message is `librats: <CODE>`; pure
+getters are properties.
 
-Install directly from npm:
+## Installation
 
 ```bash
 npm install librats
 ```
 
-The installation process will automatically:
-1. Download all necessary source files
-2. Build the native librats library using CMake
-3. Build the Node.js native addon
-4. Set up the bindings
-
-**No additional build steps required!**
+The install builds the native librats library with CMake, then compiles the
+Node.js addon against it. You need:
 
-### Prerequisites
+- **Node.js** 20+
+- **CMake** 3.14+ ([download](https://cmake.org/download/))
+- a **C++17 toolchain** — Visual Studio Build Tools 2017+ (Windows),
+  `build-essential` (Linux), `xcode-select --install` (macOS)
 
-The following build tools are required and will be used automatically during installation:
+See [INSTALLATION.md](INSTALLATION.md) for what runs during install and how to
+troubleshoot it.
 
-- **Node.js**: 20.0.0 or higher
-- **CMake**: Version 3.10 or higher ([download here](https://cmake.org/download/))
-- **C++ Compiler and Build Tools**:
-  - **Windows**: Visual Studio Build Tools 2017 or later ([download here](https://visualstudio.microsoft.com/downloads/))
-  - **Linux**: `build-essential` and `cmake` packages
-    ```bash
-    sudo apt install build-essential cmake
-    ```
-  - **macOS**: Xcode Command Line Tools
-    ```bash
-    xcode-select --install
-    ```
-
-### Verifying Installation
-
-After installation, you can verify everything is working:
-
-```bash
-npm run verify
-```
-
-This will check that the native addon is built correctly and all features are available.
-
-### Building from Source
-
-If you're developing or need to rebuild:
-
-```bash
-# Clone the repository
-git clone https://github.com/librats/librats.git
-cd librats/nodejs
-
-# Install (builds everything automatically)
-npm install
-
-# Verify the installation
-npm run verify
-
-# Or build manually
-npm run build
-```
-
-## Quick Start
-
-### Basic Example
+## Quick start
 
 ```javascript
-const { RatsClient, ConnectionStrategy } = require('librats');
+const { RatsNode } = require('librats');
 
-// Create a client listening on port 8080
-const client = new RatsClient(8080);
+const node = new RatsNode({ listenPort: 8080, dataDir: './state' });
 
-// Set up event handlers
-client.onConnection((peerId) => {
-  console.log(`Peer connected: ${peerId}`);
-  client.sendString(peerId, 'Hello from Node.js!');
+// Everything below happens before start().
+node.onPeerConnected((peerId) => {
+  console.log(`+ ${peerId}`);
+  node.send(peerId, 'chat', 'Hello from Node.js!');
 });
-
-client.onString((peerId, message) => {
-  console.log(`Received: ${message} from ${peerId}`);
+node.on('chat', (peerId, data) => {
+  console.log(`[chat] ${peerId}: ${data.toString('utf8')}`);
 });
+node.enableDht();       // find peers on the mainline DHT
+node.enableMdns();      // …and on the local network
 
-// Start the client
-client.start();
-
-// Connect to another peer
-client.connect('127.0.0.1', 8081);
+node.start();
+console.log(node.localId, 'listening on', node.listenPort);
 ```
 
-### File Transfer Example
+### Pub/sub
 
 ```javascript
-const { RatsClient } = require('librats');
-
-const client = new RatsClient(8080);
-
-// Set up file transfer progress monitoring
-client.onFileProgress((transferId, progressPercent, status) => {
-  console.log(`Transfer ${transferId}: ${progressPercent}% - ${status}`);
+node.enablePubsub();
+node.subscribe('lobby', (peerId, topic, data) => {
+  console.log(`[${topic}] ${peerId}: ${data.toString('utf8')}`);
 });
+node.start();
+node.publish('lobby', 'hi everyone');
+```
 
-// Accept incoming transfer offers (transfers are push-only)
-client.onFileRequest((peerId, transferId, filename) => {
-  console.log(`Incoming offer "${filename}" from ${peerId}`);
-  client.acceptFileTransfer(transferId, `./downloads/${filename}`);
-});
+### Typed JSON messaging
 
-client.start();
+Values are serialized and parsed for you — handlers receive the parsed value.
 
-// Send a file to a peer
-const transferId = client.sendFile('peer_id_here', './myfile.txt', 'remote_file.txt');
-console.log(`File transfer started: ${transferId}`);
+```javascript
+node.enableJson();
+node.onJson('greeting', (peerId, value) => console.log(peerId, value.hello));
+node.start();
+node.broadcastJson('greeting', { hello: 'world' });
 ```
 
-### GossipSub Chat Example
+### File transfer
 
 ```javascript
-const { RatsClient } = require('librats');
-
-const client = new RatsClient(8080);
-client.start();
-
-// Subscribe to a topic
-client.subscribeToTopic('general-chat');
+node.enableFileTransfer('./tmp');   // in-progress downloads live here
 
-// Publish a message
-const message = {
-  type: 'chat',
-  username: 'Alice',
-  message: 'Hello everyone!',
-  timestamp: Date.now()
-};
+node.onFileOffer((peerId, transferId, name, size, isDirectory) => {
+  node.acceptFile(peerId, transferId, `./downloads/${name}`);
+});
+node.onFileProgress((transferId, peerId, done, total) => {
+  console.log(`${transferId}: ${done}/${total}`);
+});
+node.onFileComplete((transferId, success, path) => {
+  console.log(`${transferId} ${success ? 'done' : 'failed'} ${path}`);
+});
 
-client.publishJsonToTopic('general-chat', JSON.stringify(message));
+node.start();
+const transferId = node.sendFile(peerId, './myfile.txt');  // 0 on failure
 ```
 
-## API Reference
+### NAT traversal
 
-### RatsClient
+Port forwarding is the easy path; hole punching covers the networks where it
+fails. Both are opt-in, and punching needs peers that relay the rendezvous.
 
-#### Constructor
+```javascript
+node.enablePortMapping();     // UPnP IGD + NAT-PMP
+node.enableHolePunch(true);   // true = also relay other peers' rendezvous
+node.enableRelay(false);      // last resort; true = also carry others' connections
+node.start();
 
-- `new RatsClient(listenPort: number)` - Create a new client instance
+node.punchPeer(peerId);       // success arrives as onPeerConnected
+console.log(node.natMapping); // NatMapping.ENDPOINT_INDEPENDENT ⇒ punchable
+```
 
-#### Basic Operations
+A symmetric NAT cannot be punched at all, and that is what `enableRelay` is for: the
+connection itself is routed through a node both ends already reach. It stays
+encrypted end to end — the relay moves ciphertext — and the peer behaves like any
+other, except that `peerTransport(peerId)` reports `Transport.RELAY`. With both
+enabled the ladder runs itself: a punch that cannot work falls back to a relay, and
+a relayed peer keeps trying to become a direct one.
 
-- `start(): boolean` - Start the client
-- `stop(): void` - Stop the client
-- `connect(host: string, port: number): boolean` - Connect to a peer
-- `connectWithStrategy(host: string, port: number, strategy: number): boolean` - Connect with specific strategy
-- `disconnect(peerId: string): void` - Disconnect from a peer
+## API
 
-#### Messaging
+### Construction
 
-- `sendString(peerId: string, message: string): boolean` - Send string message
-- `sendBinary(peerId: string, data: Buffer): boolean` - Send binary data
-- `sendJson(peerId: string, jsonStr: string): boolean` - Send JSON data
-- `broadcastString(message: string): number` - Broadcast string to all peers
-- `broadcastBinary(data: Buffer): number` - Broadcast binary to all peers
-- `broadcastJson(jsonStr: string): number` - Broadcast JSON to all peers
+```javascript
+new RatsNode(port)     // listen on port (0 = ephemeral)
+new RatsNode(config)   // full config
+```
 
-#### Information
+| config field | default | meaning |
+|---|---|---|
+| `listenPort` | `0` | inbound port shared by both transports; 0 = ephemeral |
+| `enableListen` | `true` | `false` makes a dial-only node |
+| `bindAddress` | `"::"` | dual-stack wildcard by default |
+| `security` | `Security.NOISE` | or `Security.PLAINTEXT` |
+| `dataDir` | — | persistent identity + subsystem state; omit for an ephemeral identity |
+| `protocol` | `"librats/1.0"` | handshake app id; peers whose protocol differs cannot connect |
+| `maxPeers` | `0` | established-peer cap; 0 = unlimited |
+| `enableTcp` / `enableUdp` | `true` | which wires to accept and dial on |
+| `preferredTransport` | `Transport.UDP` | which one a dial tries first |
+| `transportFallbackMs` | `1200` | delay before racing the other; 0 disables |
 
-- `getPeerCount(): number` - Get number of connected peers
-- `getOurPeerId(): string | null` - Get our peer ID
-- `getPeerIds(): string[]` - Get list of connected peer IDs
-- `getConnectionStatistics(): string | null` - Get connection statistics as JSON
+### Lifecycle
 
-#### File Transfer
+`start()` · `stop()` · `destroy()`
 
-- `sendFile(peerId: string, filePath: string, remoteFilename?: string): string | null` - Send file
-- `sendDirectory(peerId: string, dirPath: string, remoteDirName?: string): string | null` - Send directory (always recursive)
-- `acceptFileTransfer(transferId: string, localPath: string): boolean` - Accept an incoming file/directory transfer offer
-- `rejectFileTransfer(transferId: string, reason?: string): boolean` - Reject file transfer
-- `cancelFileTransfer(transferId: string): boolean` - Cancel file transfer
-- `pauseFileTransfer(transferId: string): boolean` - Pause file transfer
-- `resumeFileTransfer(transferId: string): boolean` - Resume file transfer
+### Properties
 
-#### GossipSub
+`listenPort` · `localId` · `protocol` · `transports` · `peerCount` · `peerIds` ·
+`maxPeers` *(settable)* · `natMapping`
 
-- `isGossipsubAvailable(): boolean` - Check if GossipSub is available
-- `subscribeToTopic(topic: string): boolean` - Subscribe to topic
-- `unsubscribeFromTopic(topic: string): boolean` - Unsubscribe from topic
-- `publishToTopic(topic: string, message: string): boolean` - Publish message
-- `publishJsonToTopic(topic: string, jsonStr: string): boolean` - Publish JSON
-- `getSubscribedTopics(): string[]` - Get subscribed topics
-- `getTopicPeers(topic: string): string[]` - Get peers in topic
+### Connections
 
-#### DHT
+`connect(host, port)` · `peerTransport(peerId)` · `peerTransports(peerId)`
 
-- `startDhtDiscovery(dhtPort: number): boolean` - Start DHT discovery
-- `stopDhtDiscovery(): void` - Stop DHT discovery
-- `isDhtRunning(): boolean` - Check if DHT is running
-- `announceForHash(contentHash: string, port: number, callback?: (peers: string[]) => void): boolean` - Announce for hash with optional peer discovery callback
+### Raw channel messaging
 
-#### Encryption
+`send(peerId, channel, data)` · `broadcast(channel, data)` ·
+`on(channel, (peerId, data) => …)` — `data` is a `Buffer` in, `string | Buffer` out
 
-- `setEncryptionEnabled(enabled: boolean): boolean` - Enable/disable encryption
-- `isEncryptionEnabled(): boolean` - Check if encryption is enabled
-- `generateEncryptionKey(): string | null` - Generate new encryption key
-- `setEncryptionKey(keyHex: string): boolean` - Set encryption key
-- `getEncryptionKey(): string | null` - Get current encryption key
+### Peer events *(before start)*
 
-#### Event Handlers
+`onPeerConnected(cb)` · `onPeerDisconnected(cb)`
 
-- `onConnection(callback: (peerId: string) => void): void` - Set connection callback
-- `onString(callback: (peerId: string, message: string) => void): void` - Set string message callback
-- `onBinary(callback: (peerId: string, data: Buffer) => void): void` - Set binary message callback
-- `onJson(callback: (peerId: string, jsonStr: string) => void): void` - Set JSON message callback
-- `onDisconnect(callback: (peerId: string) => void): void` - Set disconnect callback
-- `onFileProgress(callback: (transferId: string, progressPercent: number, status: string) => void): void` - Set file progress callback
-- `onFileRequest(callback: (peerId: string, transferId: string, filename: string) => void): void` - Set incoming transfer offer callback (respond with `acceptFileTransfer`/`rejectFileTransfer`)
+### Subsystems *(enable before start)*
 
-### Utility Functions
+| subsystem | enable | then |
+|---|---|---|
+| DHT discovery | `enableDht(dhtPort?, discoveryKey?)` | — |
+| mDNS discovery | `enableMdns()` | — |
+| NAT port mapping | `enablePortMapping(upnp?, natpmp?)` | — |
+| Hole punching | `enableHolePunch(serveAsRelay?)` | `punchPeer(peerId)`, `natMapping` |
+| Relaying | `enableRelay(serveAsRelay?)` | `connectViaRelay(peerId)` |
+| Pub/sub | `enablePubsub()` | `subscribe(topic, cb)`, `unsubscribe(topic)`, `publish(topic, data)` |
+| Typed JSON | `enableJson()` | `onJson(type, cb)`, `onceJson(type, cb)`, `offJson(type)`, `sendJson(peerId, type, value)`, `broadcastJson(type, value)` |
+| File transfer | `enableFileTransfer(tempDir?)` | `onFileOffer/onFileProgress/onFileComplete`, `sendFile`, `sendDirectory`, `acceptFile`, `rejectFile`, `cancelFile`, `pauseFile`, `resumeFile` |
+| Liveness | `enablePing()` | `peerRttMs(peerId)` — ms, or -1 if unknown |
+| Reconnection | `enableReconnect()` | `addReconnect(host, port)`, `removeReconnect(host, port)` |
 
-- `getVersionString(): string` - Get librats version string
-- `getVersion(): VersionInfo` - Get version components
-- `getGitDescribe(): string` - Get git describe string
-- `getAbi(): number` - Get ABI version
+### Module level
 
-### Constants
+`version()` · `versionInfo()` · `gitDescribe()` · `abi()` ·
+`setLogLevel(level)` · `setLogFile(path?)` ·
+`Security` · `Transport` · `TransportMask` · `NatMapping` · `LogLevel`
 
-#### ConnectionStrategy
+## TypeScript
 
-- `ConnectionStrategy.DIRECT_ONLY` - Direct connection only
-- `ConnectionStrategy.STUN_ASSISTED` - STUN-assisted connection
-- `ConnectionStrategy.ICE_FULL` - Full ICE negotiation
-- `ConnectionStrategy.TURN_RELAY` - TURN relay connection
-- `ConnectionStrategy.AUTO_ADAPTIVE` - Automatic strategy selection
+Definitions ship with the package.
 
-#### ErrorCodes
+```typescript
+import { RatsNode, Security } from 'librats';
 
-- `ErrorCodes.SUCCESS` - Operation successful
-- `ErrorCodes.INVALID_HANDLE` - Invalid client handle
-- `ErrorCodes.INVALID_PARAMETER` - Invalid parameter
-- `ErrorCodes.NOT_RUNNING` - Client not running
-- `ErrorCodes.OPERATION_FAILED` - Operation failed
-- `ErrorCodes.PEER_NOT_FOUND` - Peer not found
-- `ErrorCodes.MEMORY_ALLOCATION` - Memory allocation error
-- `ErrorCodes.JSON_PARSE` - JSON parsing error
+const node = new RatsNode({ listenPort: 8080, security: Security.NOISE });
+node.start();
+```
 
 ## Examples
 
-The `examples/` directory contains comprehensive examples:
-
-- **`basic_client.js`** - Basic peer-to-peer networking and messaging
-- **`file_transfer.js`** - File and directory transfer with interactive CLI
-- **`gossipsub_chat.js`** - Topic-based chat using GossipSub
-
-### Running Examples
-
 ```bash
-# Basic client (listens on port 8080)
-node examples/basic_client.js
-
-# Basic client connecting to another peer
+node examples/basic_client.js 8080
 node examples/basic_client.js 8081 127.0.0.1 8080
-
-# File transfer client
 node examples/file_transfer.js 8080
-
-# GossipSub chat
-node examples/gossipsub_chat.js 8080 Alice
+node examples/gossipsub_chat.js 8080 Alice lobby
 ```
 
 ## Testing
 
-Run the test suite:
-
 ```bash
 npm test
+npm run verify     # check a fresh install end-to-end
+LIBRATS_DEBUG=1 node examples/basic_client.js   # log which addon was loaded
 ```
 
-Or run the simple test script:
-
-```bash
-node test/test.js
-```
-
-## Building from Source
-
-### Debug Build
-
-```bash
-npm run build
-```
-
-### Clean Build
-
-```bash
-npm run clean
-npm run build
-```
-
-## TypeScript Support
-
-Full TypeScript definitions are included. Import types:
-
-```typescript
-import { RatsClient, ConnectionStrategy, ErrorCodes, VersionInfo } from 'librats';
-
-const client: RatsClient = new RatsClient(8080);
-client.start();
-```
-
-## Error Handling
-
-Most operations return boolean values indicating success/failure. For detailed error information, check the console output or use the statistics functions:
-
-```javascript
-const stats = client.getConnectionStatistics();
-if (stats) {
-  const parsed = JSON.parse(stats);
-  console.log('Connection stats:', parsed);
-}
-```
-
-## Performance Considerations
-
-- Use binary messages for large data transfers
-- Enable encryption only when needed (adds overhead)
-- Monitor file transfer progress for large files
-- Use appropriate connection strategies for your network environment
-
-## Platform Support
-
-- **Windows** - Requires Visual Studio Build Tools
-- **Linux** - Requires build-essential
-- **macOS** - Requires Xcode Command Line Tools
-- **Android** - Supported via native Android bindings (separate package)
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests for new functionality
-5. Submit a pull request
-
 ## License
 
-This project is licensed under the MIT License - see the LICENSE file for details.
-
-## Troubleshooting
-
-### Build Issues
-
-**Windows**: Ensure Visual Studio Build Tools are installed
-```bash
-npm install --global windows-build-tools
-```
-
-**Linux**: Install build dependencies
-```bash
-sudo apt install build-essential python3
-```
-
-**macOS**: Install Xcode Command Line Tools
-```bash
-xcode-select --install
-```
-
-### Runtime Issues
-
-**Port already in use**: Choose a different port or kill the process using the port
-```bash
-# Find process using port
-netstat -tulpn | grep :8080
-
-# Kill process
-kill -9 <pid>
-```
-
-**Permission denied**: Run with appropriate permissions or use ports > 1024
-
-**Connection timeout**: Check firewall settings and ensure peers are reachable
-
-### Debug Mode
-
-Enable debug logging by setting environment variable:
-```bash
-export LIBRATS_DEBUG=1
-node examples/basic_client.js
-```
-
-## Support
-
-- [GitHub Issues](https://github.com/librats/librats/issues)
-- [Documentation](https://librats.github.io/)
-- [Examples Repository](https://github.com/librats/librats/tree/main/nodejs/examples)
-
-For more advanced usage, see the [C API documentation](../docs/) and the [main project README](../README.md).
+MIT — see [LICENSE](../LICENSE).

package/binding.gyp

@@ -8,8 +8,15 @@
       ],
       "include_dirs": [
         "<!@(node -p \"require('node-addon-api').include\")",
+        # librats headers. "librats/bindings/rats.h" is the canonical C ABI; it
+        # pulls in librats/util/rats_export.h. These paths are the include ROOT
+        # (the parent of librats/), matching CMakeLists.txt. native-src/src is
+        # used when the package is installed from npm (sources bundled there);
+        # ../src in dev.
         "native-src/src",
         "../src",
+        # Generated headers (version.h, features.h) produced by the CMake build into
+        # build-native/src/. Mirrors PROJECT_BINARY_DIR/src in CMakeLists.txt.
         "build-native/src"
       ],
       "dependencies": [
@@ -17,20 +24,26 @@
       ],
       "cflags!": [ "-fno-exceptions" ],
       "cflags_cc!": [ "-fno-exceptions" ],
+      "cflags_cc": [ "-std=c++17" ],
       "xcode_settings": {
         "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
         "CLANG_CXX_LIBRARY": "libc++",
-        "MACOSX_DEPLOYMENT_TARGET": "10.7"
+        "CLANG_CXX_LANGUAGE_STANDARD": "c++17",
+        "MACOSX_DEPLOYMENT_TARGET": "10.13"
       },
       "msvs_settings": {
-        "VCCLCompilerTool": { 
+        "VCCLCompilerTool": {
           "ExceptionHandling": 1,
-          "RuntimeLibrary": 2
+          "RuntimeLibrary": 2,
+          "AdditionalOptions": [ "/std:c++17" ]
         }
       },
       "defines": [ "NAPI_DISABLE_CPP_EXCEPTIONS" ],
       "conditions": [
         ["OS=='win'", {
+          # Link the prebuilt static archive produced by scripts/build-librats.js
+          # (CMake builds rats.lib with RATS_BINDINGS=ON, so the rats_* C ABI is
+          # already inside). Plus the platform networking/crypto libs.
           "configurations": {
             "Debug": {
               "msvs_settings": {