Merge pull request #18 from PrismarineJS/update

Updates

Author: extremeheat

.github/workflows/ci.yml

@@ -9,11 +9,13 @@ on:
 jobs:
   build:
 
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
 
     strategy:
       matrix:
         node-version: [24.x]
+        os: [ubuntu-latest, macos-latest, windows-latest]
 
     steps:
     - uses: actions/checkout@v2

README.md

@@ -1,5 +1,5 @@
 # node-nethernet
-[![NPM version](https://img.shields.io/npm/v/node-nethernet.svg?logo=npm)](http://npmjs.com/package/node-nethernet)
+[![NPM version](https://img.shields.io/npm/v/nethernet.svg?logo=npm)](https://npmjs.com/package/nethernet)
 [![Build Status](https://img.shields.io/github/actions/workflow/status/PrismarineJS/node-nethernet/ci.yml.svg?label=CI&logo=github)](https://github.com/PrismarineJS/node-nethernet/actions?query=workflow%3A%22CI%22)
 [![Try it on gitpod](https://img.shields.io/static/v1.svg?label=try&message=on%20gitpod&color=brightgreen&logo=gitpod)](https://gitpod.io/#https://github.com/PrismarineJS/node-nethernet)
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/PrismarineJS)](https://github.com/sponsors/PrismarineJS)
@@ -18,7 +18,7 @@ npm install nethernet
 ## Example
 
 ```ts
-const { Client, Server } = require('node-nethernet')
+const { Client, Server } = require('nethernet')
 
 const server = new Server()
 // Client sends request to the broadcast address and server responds with a message
@@ -38,3 +38,59 @@ server.listen()
 client.connect()
 
 ```
+
+## Connection options and lifecycle
+
+`new Client(serverNetworkId, broadcastAddress?, options?)` starts UDP discovery.
+The default broadcast address is `255.255.255.255`; use `127.0.0.1` for local tests.
+Call `connect()` to initiate a connection and listen for `connected`, `disconnect`,
+and `error`. `connect()` returns immediately; it is not a promise for connection readiness.
+
+Client options:
+
+- `networkId`, `connectionId`: optional bigint IDs. A retry uses a fresh connection ID.
+- `iceServers` (or `credentials`, which takes precedence): string STUN/TURN URLs or
+  objects such as `{ urls: 'turn:relay.example.com:3478', username: 'user', credential: 'secret' }`.
+- `responseTimeoutMs`: defaults to 15000; bounds discovery and then waiting for an answer.
+- `inactivityTimeoutMs`: defaults to 5000; bounds connection establishment after the answer,
+  not application inactivity once connected.
+
+`new Server(options?)` accepts `networkId`, the same ICE options, and
+`acceptTimeoutMs` (default 5000) for waiting for connection establishment after an answer.
+A timeout value of zero or less disables that timeout.
+
+Negotiation failures produce a `disconnect` reason of `connecterror:<ErrorCode>`.
+Local offer/configuration errors also reach an attached `error` listener; without
+one they are logged via `DEBUG=nethernet`. Register listeners before calling `connect()`.
+After failure or remote disconnect, call `connect()` again to retry. Repeated calls
+while connecting or connected are ignored. Call `close()` when finished to release
+discovery sockets, timers, and peer resources, including after a failed attempt.
+`close()` is idempotent and works before `connect()`/`listen()`. Explicitly closed
+clients and servers cannot be reused; create a new instance.
+
+## External signalling
+
+Assign `client.signalHandler` before `connect()` to send signals through your own
+transport instead of UDP discovery. Feed incoming signals to `client.handleSignal()`.
+`SignalStructure.networkId` identifies the destination on outgoing signals; set it
+to the sender's network ID when delivering an incoming signal. Preserve `connectionId`.
+
+On a server, route `ConnectRequest` to `server.handleOffer(signal, respond)` and
+`CandidateAdd` to `server.handleCandidate(signal, respond)`. Route `ConnectError` to
+`server.connections.get(signal.connectionId)?.close('connecterror:' + signal.data)`.
+The `respond` callback must deliver responses to the client through your transport.
+Await these asynchronous handlers and handle transport errors. Deliver the SDP
+offer/answer before their ICE candidates; arbitrary signalling reordering is not
+currently supported. A server used only for external signalling need not call `listen()`.
+
+## WebRTC API and validation
+
+Peer connections and data channels use `@roamhq/wrtc` and expose the standard
+WebRTC API (for example `connectionState`, `getStats()`, and `bufferedAmount`).
+Type declarations use TypeScript's DOM interfaces; backend-specific extensions are
+not declared. The former `node-datachannel` methods are no longer supported.
+
+`npm test` runs lint, strict TypeScript checks, and runtime tests without forcing
+process exit. Tests cover local transport, signalling errors, cancellation, and
+resource cleanup. Live Minecraft/Realms and authenticated TURN interoperability
+still require testing against a real environment before release.

index.d.ts

@@ -1,9 +1,21 @@
+/// <reference lib="dom" />
 import EventEmitter from 'node:events'
 import { RemoteInfo, Socket } from 'node:dgram'
-import { PeerConnection, DataChannel, IceServer } from 'node-datachannel'
 
 declare module 'nethernet' {
 
+  // wrtc implements the standard WebRTC API. Use its standard interfaces without
+  // importing wrtc's upstream declarations, which currently fail strict checking.
+  export interface RTCPeerConnectionLike extends RTCPeerConnection {}
+
+  export interface RTCDataChannelLike extends RTCDataChannel {}
+
+  export interface IceServer {
+    urls: string | string[]
+    username?: string
+    credential?: string
+  }
+
   export interface ResponsePacket {
     binary: number[]
     buffer: Buffer
@@ -18,24 +30,29 @@ declare module 'nethernet' {
   export class Connection {
     nethernet: Client | Server;
     address: bigint;
-    rtcConnection: PeerConnection;
-    reliable: DataChannel | null;
-    unreliable: DataChannel | null;
+    rtcConnection: RTCPeerConnectionLike;
+    reliable: RTCDataChannelLike | null;
+    unreliable: RTCDataChannelLike | null;
     promisedSegments: number;
     buf: Buffer | null;
-    sendQueue: Buffer[];      
+    sendQueue: Buffer[];
 
-    constructor(nethernet: Client | Server, address: bigint, rtcConnection: PeerConnection);
-    setChannels(reliable?: DataChannel | null, unreliable?: DataChannel | null): void;
+    closed: boolean;
+
+    constructor(nethernet: Client | Server, address: bigint, rtcConnection: RTCPeerConnectionLike);
+    setChannels(reliable?: RTCDataChannelLike | null, unreliable?: RTCDataChannelLike | null): void;
     handleMessage(data: Buffer | string | ArrayBuffer): void;
     send(data: Buffer | string): number;
     sendNow(data: Buffer): number;
     flushQueue(): void;
-    close(): void;
+    close(reason?: string): void;
   }
 
   export interface ServerOptions {
     networkId?: bigint;
+    credentials?: (string | IceServer)[];
+    iceServers?: (string | IceServer)[];
+    acceptTimeoutMs?: number;
   }
 
   export interface ServerEvents {
@@ -47,15 +64,18 @@ declare module 'nethernet' {
 
   export class Server extends EventEmitter {
     options: ServerOptions;
+    credentials: IceServer[];
+    acceptTimeoutMs: number;
     networkId: bigint;
     connections: Map<bigint, Connection>;
+    acceptTimeouts: Map<bigint, NodeJS.Timeout>;
     advertisement?: Buffer;
     socket: Socket;
     serializer: any;
     deserializer: any;
 
     constructor(options?: ServerOptions);
-    handleCandidate(signal: SignalStructure): Promise<void>;
+    handleCandidate(signal: SignalStructure, respond?: (signal: SignalStructure) => void): Promise<void>;
     handleOffer(signal: SignalStructure, respond: (signal: SignalStructure) => void, credentials?: (string | IceServer)[]): Promise<void>;
     processPacket(buffer: Buffer, rinfo: RemoteInfo): void;
     setAdvertisement(buffer: Buffer): void;
@@ -73,7 +93,17 @@ declare module 'nethernet' {
     disconnect: (connectionId: bigint, reason: string) => void;
     encapsulated: (data: Buffer, connectionId: bigint) => void;
     pong: (packet: any) => void;
-  }  
+    error: (error: Error) => void;
+  }
+
+  export interface ClientOptions {
+    networkId?: bigint;
+    connectionId?: bigint;
+    credentials?: (string | IceServer)[];
+    iceServers?: (string | IceServer)[];
+    responseTimeoutMs?: number;
+    inactivityTimeoutMs?: number;
+  }
 
   export class Client extends EventEmitter {
     serverNetworkId: bigint;
@@ -85,14 +115,17 @@ declare module 'nethernet' {
     deserializer: any;
     responses: Map<bigint, any>;
     addresses: Map<bigint, RemoteInfo>;
-    credentials: (string | IceServer)[];
+    credentials: IceServer[];
+    responseTimeoutMs: number;
+    inactivityTimeoutMs: number;
     signalHandler: (signal: SignalStructure) => void;
-    connection?: Connection;
-    rtcConnection?: PeerConnection;
+    connection?: Connection | null;
+    rtcConnection?: RTCPeerConnectionLike | null;
     pingInterval?: NodeJS.Timeout;
     running: boolean;
-  
+
     constructor(networkId: bigint, broadcastAddress?: string);
+    constructor(networkId: bigint, broadcastAddress: string | undefined, options: ClientOptions);
     handleCandidate(signal: SignalStructure): Promise<void>;
     handleAnswer(signal: SignalStructure): Promise<void>;
     createOffer(): Promise<void>;
@@ -102,7 +135,7 @@ declare module 'nethernet' {
     handleSignal(signal: SignalStructure): void;
     sendDiscoveryRequest(): void;
     sendDiscoveryMessage(signal: SignalStructure): void;
-    connect(): Promise<void>;
+    connect(): void;
     send(buffer: Buffer): void;
     ping(): void;
     close(reason?: string): void;
@@ -118,6 +151,36 @@ declare module 'nethernet' {
     ConnectError = 'CONNECTERROR'
   }
 
+  export enum ErrorCode {
+    None = 0,
+    DestinationNotLoggedIn = 1,
+    NegotiationTimeout = 2,
+    WrongTransportVersion = 3,
+    FailedToCreatePeerConnection = 4,
+    ICE = 5,
+    ConnectRequest = 6,
+    ConnectResponse = 7,
+    CandidateAdd = 8,
+    InactivityTimeout = 9,
+    FailedToCreateOffer = 10,
+    FailedToCreateAnswer = 11,
+    FailedToSetLocalDescription = 12,
+    FailedToSetRemoteDescription = 13,
+    NegotiationTimeoutWaitingForResponse = 14,
+    NegotiationTimeoutWaitingForAccept = 15,
+    IncomingConnectionIgnored = 16,
+    SignalingParsingFailure = 17,
+    SignalingUnknownError = 18,
+    SignalingUnicastMessageDeliveryFailed = 19,
+    SignalingBroadcastDeliveryFailed = 20,
+    SignalingMessageDeliveryFailed = 21,
+    SignalingTurnAuthFailed = 22,
+    SignalingFallbackToBestEffortDelivery = 23,
+    NoSignalingChannel = 24,
+    NotLoggedIn = 25,
+    SignalingFailedToSend = 26
+  }
+
   export class SignalStructure {
     type: SignalType;
     connectionId: bigint;

index.js

@@ -1,6 +1,6 @@
 const { Client } = require('./src/client')
 const { Server } = require('./src/server')
-const { SignalStructure } = require('./src/signalling')
+const { ErrorCode, SignalStructure } = require('./src/signalling')
 
 const SignalType = {
   ConnectRequest: 'CONNECTREQUEST',
@@ -11,6 +11,7 @@ const SignalType = {
 
 module.exports = {
   Client,
+  ErrorCode,
   Server,
   SignalType,
   SignalStructure

package.json

@@ -4,9 +4,10 @@
   "description": "(WIP) Minecraft Bedrock nethernet protocol",
   "main": "index.js",
   "scripts": {
-    "test": "mocha --reporter spec --exit",
-    "pretest": "npm run lint",
+    "test": "mocha --reporter spec",
+    "pretest": "npm run lint && npm run typecheck",
     "lint": "standard",
+    "typecheck": "tsc --noEmit --strict --types node --target ES2022 --module Node16 --moduleResolution Node16 test/types.test.ts",
     "fix": "standard --fix"
   },
   "repository": {
@@ -24,13 +25,15 @@
   },
   "homepage": "https://github.com/PrismarineJS/node-nethernet#readme",
   "devDependencies": {
+    "@types/node": "^24.13.6",
     "debug": "^4.4.0",
     "mocha": "^11.7.5",
     "nethernet": "file:.",
-    "standard": "^17.0.0"
+    "standard": "^17.0.0",
+    "typescript": "^7.0.2"
   },
   "dependencies": {
-    "node-datachannel": "^0.26.0",
+    "@roamhq/wrtc": "^0.10.0",
     "protodef": "^1.19.0"
   }
 }