librats 0.3.1

package/lib/index.d.ts

@@ -0,0 +1,522 @@
+/**
+ * LibRats Node.js Bindings - TypeScript Definitions
+ * 
+ * High-performance peer-to-peer networking library with support for DHT, GossipSub,
+ * file transfer, NAT traversal, and more.
+ */
+
+/**
+ * Version information structure
+ */
+export interface VersionInfo {
+  major: number;
+  minor: number;
+  patch: number;
+  build: number;
+}
+
+/**
+ * Connection strategy options for connecting to peers
+ */
+export enum ConnectionStrategy {
+  /** Direct connection only, no NAT traversal */
+  DIRECT_ONLY = 0,
+  /** STUN-assisted connection */
+  STUN_ASSISTED = 1,
+  /** Full ICE negotiation with STUN and connection checks */
+  ICE_FULL = 2,
+  /** TURN relay connection */
+  TURN_RELAY = 3,
+  /** Automatic strategy selection based on network conditions */
+  AUTO_ADAPTIVE = 4
+}
+
+/**
+ * Error codes returned by various operations
+ */
+export enum ErrorCodes {
+  /** Operation completed successfully */
+  SUCCESS = 0,
+  /** Invalid client handle */
+  INVALID_HANDLE = -1,
+  /** Invalid parameter provided */
+  INVALID_PARAMETER = -2,
+  /** Client is not running */
+  NOT_RUNNING = -3,
+  /** Operation failed */
+  OPERATION_FAILED = -4,
+  /** Peer not found */
+  PEER_NOT_FOUND = -5,
+  /** Memory allocation error */
+  MEMORY_ALLOCATION = -6,
+  /** JSON parsing error */
+  JSON_PARSE = -7
+}
+
+/**
+ * Main RatsClient class for peer-to-peer networking
+ */
+export class RatsClient {
+  /**
+   * Create a new RatsClient instance
+   * @param listenPort - Port to listen on for incoming connections
+   */
+  constructor(listenPort: number);
+
+  // ============ Basic Operations ============
+
+  /**
+   * Start the client
+   * @returns true if started successfully, false otherwise
+   */
+  start(): boolean;
+
+  /**
+   * Stop the client
+   */
+  stop(): void;
+
+  /**
+   * Connect to a peer
+   * @param host - IP address or hostname of the peer
+   * @param port - Port number of the peer
+   * @returns true if connection initiated successfully
+   */
+  connect(host: string, port: number): boolean;
+
+  /**
+   * Connect to a peer with a specific connection strategy
+   * @param host - IP address or hostname of the peer
+   * @param port - Port number of the peer
+   * @param strategy - Connection strategy to use
+   * @returns true if connection initiated successfully
+   */
+  connectWithStrategy(host: string, port: number, strategy: ConnectionStrategy): boolean;
+
+  /**
+   * Disconnect from a peer
+   * @param peerId - ID of the peer to disconnect from
+   */
+  disconnect(peerId: string): void;
+
+  // ============ Information ============
+
+  /**
+   * Get the number of connected peers
+   * @returns Number of connected peers
+   */
+  getPeerCount(): number;
+
+  /**
+   * Get our own peer ID
+   * @returns Our peer ID, or null if not started
+   */
+  getOurPeerId(): string | null;
+
+  /**
+   * Get list of connected peer IDs
+   * @returns Array of peer IDs
+   */
+  getPeerIds(): string[];
+
+  /**
+   * Get connection statistics as JSON string
+   * @returns JSON string with statistics, or null if unavailable
+   */
+  getConnectionStatistics(): string | null;
+
+  /**
+   * Get file transfer statistics as JSON string
+   * @returns JSON string with statistics, or null if unavailable
+   */
+  getFileTransferStatistics(): string | null;
+
+  // ============ Peer Management ============
+
+  /**
+   * Set maximum number of peers
+   * @param maxPeers - Maximum number of peers to allow
+   * @returns true if set successfully
+   */
+  setMaxPeers(maxPeers: number): boolean;
+
+  /**
+   * Get maximum number of peers
+   * @returns Maximum number of peers allowed
+   */
+  getMaxPeers(): number;
+
+  /**
+   * Check if peer limit has been reached
+   * @returns true if at or over peer limit
+   */
+  isPeerLimitReached(): boolean;
+
+  // ============ Messaging ============
+
+  /**
+   * Send a string message to a peer
+   * @param peerId - ID of the peer to send to
+   * @param message - String message to send
+   * @returns true if sent successfully
+   */
+  sendString(peerId: string, message: string): boolean;
+
+  /**
+   * Send binary data to a peer
+   * @param peerId - ID of the peer to send to
+   * @param data - Buffer containing binary data
+   * @returns true if sent successfully
+   */
+  sendBinary(peerId: string, data: Buffer): boolean;
+
+  /**
+   * Send JSON data to a peer
+   * @param peerId - ID of the peer to send to
+   * @param jsonStr - JSON string to send
+   * @returns true if sent successfully
+   */
+  sendJson(peerId: string, jsonStr: string): boolean;
+
+  /**
+   * Broadcast a string message to all connected peers
+   * @param message - String message to broadcast
+   * @returns Number of peers the message was sent to
+   */
+  broadcastString(message: string): number;
+
+  /**
+   * Broadcast binary data to all connected peers
+   * @param data - Buffer containing binary data
+   * @returns Number of peers the data was sent to
+   */
+  broadcastBinary(data: Buffer): number;
+
+  /**
+   * Broadcast JSON data to all connected peers
+   * @param jsonStr - JSON string to broadcast
+   * @returns Number of peers the data was sent to
+   */
+  broadcastJson(jsonStr: string): number;
+
+  // ============ File Transfer ============
+
+  /**
+   * Send a file to a peer
+   * @param peerId - ID of the peer to send to
+   * @param filePath - Local path to the file
+   * @param remoteFilename - Optional filename on remote side
+   * @returns Transfer ID, or null if failed
+   */
+  sendFile(peerId: string, filePath: string, remoteFilename?: string): string | null;
+
+  /**
+   * Send a directory to a peer
+   * @param peerId - ID of the peer to send to
+   * @param dirPath - Local path to the directory
+   * @param remoteDirName - Optional directory name on remote side
+   * @param recursive - Whether to send recursively (default: true)
+   * @returns Transfer ID, or null if failed
+   */
+  sendDirectory(peerId: string, dirPath: string, remoteDirName?: string, recursive?: boolean): string | null;
+
+  /**
+   * Request a file from a peer
+   * @param peerId - ID of the peer to request from
+   * @param remoteFilePath - Path to the file on remote side
+   * @param localPath - Local path where file should be saved
+   * @returns Transfer ID, or null if failed
+   */
+  requestFile(peerId: string, remoteFilePath: string, localPath: string): string | null;
+
+  /**
+   * Request a directory from a peer
+   * @param peerId - ID of the peer to request from
+   * @param remoteDirPath - Path to the directory on remote side
+   * @param localDirPath - Local path where directory should be saved
+   * @param recursive - Whether to request recursively (default: true)
+   * @returns Transfer ID, or null if failed
+   */
+  requestDirectory(peerId: string, remoteDirPath: string, localDirPath: string, recursive?: boolean): string | null;
+
+  /**
+   * Accept an incoming file transfer
+   * @param transferId - ID of the transfer to accept
+   * @param localPath - Local path where file should be saved
+   * @returns true if accepted successfully
+   */
+  acceptFileTransfer(transferId: string, localPath: string): boolean;
+
+  /**
+   * Reject an incoming file transfer
+   * @param transferId - ID of the transfer to reject
+   * @param reason - Optional reason for rejection
+   * @returns true if rejected successfully
+   */
+  rejectFileTransfer(transferId: string, reason?: string): boolean;
+
+  /**
+   * Cancel an ongoing file transfer
+   * @param transferId - ID of the transfer to cancel
+   * @returns true if cancelled successfully
+   */
+  cancelFileTransfer(transferId: string): boolean;
+
+  /**
+   * Pause a file transfer
+   * @param transferId - ID of the transfer to pause
+   * @returns true if paused successfully
+   */
+  pauseFileTransfer(transferId: string): boolean;
+
+  /**
+   * Resume a paused file transfer
+   * @param transferId - ID of the transfer to resume
+   * @returns true if resumed successfully
+   */
+  resumeFileTransfer(transferId: string): boolean;
+
+  // ============ GossipSub ============
+
+  /**
+   * Check if GossipSub is available
+   * @returns true if GossipSub is available
+   */
+  isGossipsubAvailable(): boolean;
+
+  /**
+   * Check if GossipSub is running
+   * @returns true if GossipSub is running
+   */
+  isGossipsubRunning(): boolean;
+
+  /**
+   * Subscribe to a topic
+   * @param topic - Topic name to subscribe to
+   * @returns true if subscribed successfully
+   */
+  subscribeToTopic(topic: string): boolean;
+
+  /**
+   * Unsubscribe from a topic
+   * @param topic - Topic name to unsubscribe from
+   * @returns true if unsubscribed successfully
+   */
+  unsubscribeFromTopic(topic: string): boolean;
+
+  /**
+   * Check if subscribed to a topic
+   * @param topic - Topic name to check
+   * @returns true if subscribed
+   */
+  isSubscribedToTopic(topic: string): boolean;
+
+  /**
+   * Publish a message to a topic
+   * @param topic - Topic name to publish to
+   * @param message - Message to publish
+   * @returns true if published successfully
+   */
+  publishToTopic(topic: string, message: string): boolean;
+
+  /**
+   * Publish JSON data to a topic
+   * @param topic - Topic name to publish to
+   * @param jsonStr - JSON string to publish
+   * @returns true if published successfully
+   */
+  publishJsonToTopic(topic: string, jsonStr: string): boolean;
+
+  /**
+   * Get list of subscribed topics
+   * @returns Array of topic names
+   */
+  getSubscribedTopics(): string[];
+
+  /**
+   * Get peers subscribed to a topic
+   * @param topic - Topic name
+   * @returns Array of peer IDs
+   */
+  getTopicPeers(topic: string): string[];
+
+  // ============ DHT ============
+
+  /**
+   * Start DHT discovery
+   * @param dhtPort - Port to use for DHT
+   * @returns true if started successfully
+   */
+  startDhtDiscovery(dhtPort: number): boolean;
+
+  /**
+   * Stop DHT discovery
+   */
+  stopDhtDiscovery(): void;
+
+  /**
+   * Check if DHT is running
+   * @returns true if DHT is running
+   */
+  isDhtRunning(): boolean;
+
+  /**
+   * Get DHT routing table size
+   * @returns Number of entries in the routing table
+   */
+  getDhtRoutingTableSize(): number;
+
+  /**
+   * Announce availability for a content hash
+   * @param contentHash - Hash to announce for
+   * @param port - Port to announce
+   * @returns true if announced successfully
+   */
+  announceForHash(contentHash: string, port: number): boolean;
+
+  // ============ mDNS ============
+
+  /**
+   * Start mDNS discovery
+   * @param serviceName - Service name to advertise
+   * @returns true if started successfully
+   */
+  startMdnsDiscovery(serviceName: string): boolean;
+
+  /**
+   * Stop mDNS discovery
+   */
+  stopMdnsDiscovery(): void;
+
+  /**
+   * Check if mDNS is running
+   * @returns true if mDNS is running
+   */
+  isMdnsRunning(): boolean;
+
+  // ============ Encryption ============
+
+  /**
+   * Enable or disable encryption
+   * @param enabled - Whether encryption should be enabled
+   * @returns true if set successfully
+   */
+  setEncryptionEnabled(enabled: boolean): boolean;
+
+  /**
+   * Check if encryption is enabled
+   * @returns true if encryption is enabled
+   */
+  isEncryptionEnabled(): boolean;
+
+  /**
+   * Generate a new encryption key
+   * @returns Hex-encoded encryption key, or null if failed
+   */
+  generateEncryptionKey(): string | null;
+
+  /**
+   * Set the encryption key
+   * @param keyHex - Hex-encoded encryption key
+   * @returns true if set successfully
+   */
+  setEncryptionKey(keyHex: string): boolean;
+
+  /**
+   * Get the current encryption key
+   * @returns Hex-encoded encryption key, or null if not set
+   */
+  getEncryptionKey(): string | null;
+
+  // ============ Configuration Persistence ============
+
+  /**
+   * Set data directory for configuration files
+   * @param directory - Path to data directory
+   * @returns true if set successfully
+   */
+  setDataDirectory(directory: string): boolean;
+
+  /**
+   * Get current data directory
+   * @returns Path to data directory, or null if not set
+   */
+  getDataDirectory(): string | null;
+
+  /**
+   * Save current configuration to disk
+   * @returns true if saved successfully
+   */
+  saveConfiguration(): boolean;
+
+  /**
+   * Load configuration from disk
+   * @returns true if loaded successfully
+   */
+  loadConfiguration(): boolean;
+
+  // ============ Event Handlers ============
+
+  /**
+   * Set callback for when a peer connects
+   * @param callback - Function to call with peer ID
+   */
+  onConnection(callback: (peerId: string) => void): void;
+
+  /**
+   * Set callback for string messages
+   * @param callback - Function to call with peer ID and message
+   */
+  onString(callback: (peerId: string, message: string) => void): void;
+
+  /**
+   * Set callback for binary messages
+   * @param callback - Function to call with peer ID and data
+   */
+  onBinary(callback: (peerId: string, data: Buffer) => void): void;
+
+  /**
+   * Set callback for JSON messages
+   * @param callback - Function to call with peer ID and JSON string
+   */
+  onJson(callback: (peerId: string, jsonStr: string) => void): void;
+
+  /**
+   * Set callback for when a peer disconnects
+   * @param callback - Function to call with peer ID
+   */
+  onDisconnect(callback: (peerId: string) => void): void;
+
+  /**
+   * Set callback for file transfer progress updates
+   * @param callback - Function to call with transfer ID, progress percentage, and status
+   */
+  onFileProgress(callback: (transferId: string, progressPercent: number, status: string) => void): void;
+}
+
+// ============ Utility Functions ============
+
+/**
+ * Get the library version as a string
+ * @returns Version string (e.g., "1.0.0.123")
+ */
+export function getVersionString(): string;
+
+/**
+ * Get the library version components
+ * @returns Version information object
+ */
+export function getVersion(): VersionInfo;
+
+/**
+ * Get git describe string
+ * @returns Git describe string
+ */
+export function getGitDescribe(): string;
+
+/**
+ * Get ABI version number
+ * @returns ABI version
+ */
+export function getAbi(): number;
+

package/lib/index.js

@@ -0,0 +1,82 @@
+/**
+ * LibRats Node.js Bindings
+ * 
+ * High-performance peer-to-peer networking library with support for DHT, GossipSub,
+ * file transfer, NAT traversal, and more.
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+// Try to load the native addon from the build directory
+let addon;
+let addonPath;
+
+// Possible locations for the built addon
+const possiblePaths = [
+  // Standard node-gyp build location
+  path.join(__dirname, '..', 'build', 'Release', 'librats.node'),
+  path.join(__dirname, '..', 'build', 'Debug', 'librats.node'),
+  // Alternative build locations
+  path.join(__dirname, '..', 'build', 'librats.node'),
+];
+
+// Try each path
+for (const tryPath of possiblePaths) {
+  try {
+    if (fs.existsSync(tryPath)) {
+      addon = require(tryPath);
+      addonPath = tryPath;
+      break;
+    }
+  } catch (err) {
+    // Continue to next path
+  }
+}
+
+if (!addon) {
+  throw new Error(
+    'Could not load librats native addon. ' +
+    'Make sure the package is installed correctly and the native library is built. ' +
+    'Try running: npm rebuild librats'
+  );
+}
+
+// Export all native bindings
+module.exports = {
+  // Main class
+  RatsClient: addon.RatsClient,
+  
+  // Version functions
+  getVersionString: addon.getVersionString,
+  getVersion: addon.getVersion,
+  getGitDescribe: addon.getGitDescribe,
+  getAbi: addon.getAbi,
+  
+  // Constants
+  ConnectionStrategy: {
+    DIRECT_ONLY: 0,
+    STUN_ASSISTED: 1,
+    ICE_FULL: 2,
+    TURN_RELAY: 3,
+    AUTO_ADAPTIVE: 4
+  },
+  
+  ErrorCodes: {
+    SUCCESS: 0,
+    INVALID_HANDLE: -1,
+    INVALID_PARAMETER: -2,
+    NOT_RUNNING: -3,
+    OPERATION_FAILED: -4,
+    PEER_NOT_FOUND: -5,
+    MEMORY_ALLOCATION: -6,
+    JSON_PARSE: -7
+  }
+};
+
+// Log successful load for debugging
+if (process.env.LIBRATS_DEBUG) {
+  console.log(`[librats] Loaded native addon from: ${addonPath}`);
+  console.log(`[librats] Version: ${addon.getVersionString()}`);
+}
+

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "librats",
+  "version": "0.3.1",
+  "description": "Node.js bindings for librats - A high-performance peer-to-peer networking library",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "node-gyp rebuild",
+    "clean": "node-gyp clean",
+    "preinstall": "node scripts/build-librats.js",
+    "install": "node-gyp rebuild",
+    "postinstall": "node scripts/postinstall.js",
+    "test": "node test/test.js",
+    "verify": "node scripts/verify-installation.js",
+    "prepare": "node scripts/prepare-package.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "p2p",
+    "peer-to-peer",
+    "networking",
+    "dht",
+    "gossipsub",
+    "file-transfer",
+    "mdns",
+    "stun",
+    "ice",
+    "nat-traversal",
+    "encryption",
+    "native"
+  ],
+  "author": "librats team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/librats/librats.git",
+    "directory": "nodejs"
+  },
+  "bugs": {
+    "url": "https://github.com/librats/librats/issues"
+  },
+  "homepage": "https://github.com/librats/librats#readme",
+  "dependencies": {
+    "node-addon-api": "^8.5.0"
+  },
+  "devDependencies": {
+    "node-gyp": "^11.4.2",
+    "@types/node": "^24.3.1"
+  },
+  "files": [
+    "lib/**/*",
+    "src/**/*",
+    "scripts/**/*",
+    "binding.gyp",
+    "README.md",
+    "../src/**/*.cpp",
+    "../src/**/*.h",
+    "../src/**/*.in",
+    "../3rdparty/**/*",
+    "../CMakeLists.txt",
+    "../LICENSE",
+    "!../src/main.cpp"
+  ],
+  "gypfile": true
+}