JSPrismarine

API reference / @jsprismarine/nethernet

@jsprismarine/nethernet ​

Join the Discord Servernpm

NetherNet is the WebRTC transport Minecraft: Bedrock Edition uses beside RakNet. This package implements it, for a server and a client:

  • NetherNetServer turns each client's offer into an answer and keeps the Connection it negotiates. Offers reach it from HTTP signaling, or from LAN discovery once listen binds UDP NETHERNET_LAN_PORT.
  • NetherNetClient opens the reliable and unreliable data channels, sends the offer with every candidate through whatever carries its signals, and connects on the answer. LanDiscovery finds servers on the local network and carries those signals there.
  • Connection splits each message into segments as large as the peer's description allows, each led by the number of segments still to come, and joins them back. It delivers messages from both channels and closes a peer that sends too much or reads too little.
  • SignalStructure, encodeDiscoveryPacket and decodeDiscoveryPacket are the wire formats: the signal text, and LAN discovery's packets with their checksum and AES encryption.
  • HttpSignaling, the HTTP signaling a client joining by address uses: GET /v1/join for the server's status and POST /v1/join/{networkId} to trade an SDP offer for an answer.
  • lookupPublicIp asks the web services in PUBLIC_IP_SERVICES, one after another, for the host's public address. withAdvertisedCandidates adds the configured and dialed addresses to an answer, and uses a looked-up address when the answer has no public candidate.
  • NetherNetIdentity, which signs the a=identity a client requires on every answer, and the SDP helpers it is built on.
  • encodeLanAdvertisement and decodeLanAdvertisement, the advertisement a server answers LAN discovery with.
  • compactEs384, detachedEs384 and verifiesDetachedEs384, the ES384 JSON Web Signatures Bedrock signs its tokens with, made and checked by jose.

The WebRTC stack underneath is a WebRtcDriver. loadNativeDriver loads the one this project ships, libdatachannel in @jsprismarine/native-network, and nothing else here names the library. Where it cannot load, loadNativeDriver throws NetherNetUnavailableError with the platform and the cause.

It knows nothing about Minecraft packets. The 0xFE batch id NetherNet leaves out of each message is the business of whichever transport carries batches over it.

Classes ​

Interfaces ​

ConnectionOptions ​

Defined in: packages/nethernet/src/Connection.ts:115

The limits of one Connection.

Properties ​

maxBufferedBytes? ​

readonly optional maxBufferedBytes?: number

Defined in: packages/nethernet/src/Connection.ts:119

How much sent data may wait in the WebRTC stack; DEFAULT_MAX_BUFFERED_BYTES when absent.

maxMessageBytes? ​

readonly optional maxMessageBytes?: number

Defined in: packages/nethernet/src/Connection.ts:117

The longest message accepted from the peer; MAX_MESSAGE_BYTES when absent.

DialedAddress ​

Defined in: packages/nethernet/src/udpPorts.ts:276

Where a client sent its offer: the address it typed, as the signaling request names it.

Properties ​

addresses ​

readonly addresses: readonly string[]

Defined in: packages/nethernet/src/udpPorts.ts:278

The IP addresses the client's server address names: itself, or what its hostname resolves to.

localPort ​

readonly localPort: number

Defined in: packages/nethernet/src/udpPorts.ts:282

The local port the request arrived on, which the dialed port is forwarded to.

port ​

readonly port: number

Defined in: packages/nethernet/src/udpPorts.ts:280

The port the client dialed.

DiscoveredServer ​

Defined in: packages/nethernet/src/LanDiscovery.ts:14

A server that answered a discovery request.

Properties ​

address ​

readonly address: string

Defined in: packages/nethernet/src/LanDiscovery.ts:17

readonly advertisement: Buffer

Defined in: packages/nethernet/src/LanDiscovery.ts:16

networkId ​

readonly networkId: bigint

Defined in: packages/nethernet/src/LanDiscovery.ts:15

port ​

readonly port: number

Defined in: packages/nethernet/src/LanDiscovery.ts:18

DiscoveryMessage ​

Defined in: packages/nethernet/src/protocol/Discovery.ts:32

A signal for one peer, as a signal's text.

Properties ​

data ​

readonly data: string

Defined in: packages/nethernet/src/protocol/Discovery.ts:36

recipientId ​

readonly recipientId: bigint

Defined in: packages/nethernet/src/protocol/Discovery.ts:35

senderId ​

readonly senderId: bigint

Defined in: packages/nethernet/src/protocol/Discovery.ts:34

type ​

readonly type: 2

Defined in: packages/nethernet/src/protocol/Discovery.ts:33

DiscoveryRequest ​

Defined in: packages/nethernet/src/protocol/Discovery.ts:19

A client asking who is on the network.

Properties ​

senderId ​

readonly senderId: bigint

Defined in: packages/nethernet/src/protocol/Discovery.ts:21

type ​

readonly type: 0

Defined in: packages/nethernet/src/protocol/Discovery.ts:20

DiscoveryResponse ​

Defined in: packages/nethernet/src/protocol/Discovery.ts:25

A server answering with its advertisement, as the bytes encodeLanAdvertisement makes.

Properties ​

readonly advertisement: Buffer

Defined in: packages/nethernet/src/protocol/Discovery.ts:28

senderId ​

readonly senderId: bigint

Defined in: packages/nethernet/src/protocol/Discovery.ts:27

type ​

readonly type: 1

Defined in: packages/nethernet/src/protocol/Discovery.ts:26

DriverChannel ​

Defined in: packages/nethernet/src/WebRtcDriver.ts:33

A data channel on a DriverPeer.

Properties ​

bufferedAmount ​

readonly bufferedAmount: number

Defined in: packages/nethernet/src/WebRtcDriver.ts:37

Bytes the stack has queued and not yet handed on.

label ​

readonly label: string

Defined in: packages/nethernet/src/WebRtcDriver.ts:34

readyState ​

readonly readyState: "connecting" | "closed" | "open" | "closing"

Defined in: packages/nethernet/src/WebRtcDriver.ts:35

Methods ​

close() ​

close(): void

Defined in: packages/nethernet/src/WebRtcDriver.ts:40

Returns ​

void

onClose() ​

onClose(listener): void

Defined in: packages/nethernet/src/WebRtcDriver.ts:42

Parameters ​
listener ​

() => void

Returns ​

void

onMessage() ​

onMessage(listener): void

Defined in: packages/nethernet/src/WebRtcDriver.ts:43

Parameters ​
listener ​

(data) => void

Returns ​

void

onOpen() ​

onOpen(listener): void

Defined in: packages/nethernet/src/WebRtcDriver.ts:41

Parameters ​
listener ​

() => void

Returns ​

void

send() ​

send(data): boolean

Defined in: packages/nethernet/src/WebRtcDriver.ts:39

Sends one message; false when the channel cannot take it.

Parameters ​
data ​

Uint8Array

Returns ​

boolean

DriverPeer ​

Defined in: packages/nethernet/src/WebRtcDriver.ts:47

One WebRTC peer connection.

Properties ​

iceState ​

readonly iceState: IceState

Defined in: packages/nethernet/src/WebRtcDriver.ts:50

How far ICE got: checking until a connectivity check passes both ways.

state ​

readonly state: PeerState

Defined in: packages/nethernet/src/WebRtcDriver.ts:48

Methods ​

addRemoteCandidate() ​

addRemoteCandidate(candidate, sdpMid?): void

Defined in: packages/nethernet/src/WebRtcDriver.ts:54

Adds a remote candidate line, with or without a=.

Parameters ​
candidate ​

string

sdpMid? ​

string

Returns ​

void

close() ​

close(): void

Defined in: packages/nethernet/src/WebRtcDriver.ts:66

Returns ​

void

createDataChannel() ​

createDataChannel(label, options?): DriverChannel

Defined in: packages/nethernet/src/WebRtcDriver.ts:56

Opens a data channel; the first one on a new connection makes the stack offer.

Parameters ​
label ​

string

options? ​
maxRetransmits? ​

number

unordered? ​

boolean

Returns ​

DriverChannel

localAddress() ​

localAddress(): PeerAddress | undefined

Defined in: packages/nethernet/src/WebRtcDriver.ts:65

The local address of the selected pair, once connected.

Returns ​

PeerAddress | undefined

localDescription() ​

localDescription(): Promise<string>

Defined in: packages/nethernet/src/WebRtcDriver.ts:58

The local description with every candidate, once gathering completes.

Returns ​

Promise<string>

onDataChannel() ​

onDataChannel(listener): void

Defined in: packages/nethernet/src/WebRtcDriver.ts:59

Parameters ​
listener ​

(channel) => void

Returns ​

void

onIceStateChange() ​

onIceStateChange(listener): void

Defined in: packages/nethernet/src/WebRtcDriver.ts:61

Parameters ​
listener ​

(state) => void

Returns ​

void

onStateChange() ​

onStateChange(listener): void

Defined in: packages/nethernet/src/WebRtcDriver.ts:60

Parameters ​
listener ​

(state) => void

Returns ​

void

remoteAddress() ​

remoteAddress(): PeerAddress | undefined

Defined in: packages/nethernet/src/WebRtcDriver.ts:63

The remote address of the candidate pair ICE selected, once connected.

Returns ​

PeerAddress | undefined

setRemoteDescription() ​

setRemoteDescription(type, sdp): void

Defined in: packages/nethernet/src/WebRtcDriver.ts:52

Applies the remote description. A remote offer makes the stack answer by itself.

Parameters ​
type ​

"offer" | "answer"

sdp ​

string

Returns ​

void

HttpSignalingOptions ​

Defined in: packages/nethernet/src/HttpSignaling.ts:64

What the signaling server needs besides the answerer.

Properties ​

answerer ​

readonly answerer: NetherNetOfferAnswerer

Defined in: packages/nethernet/src/HttpSignaling.ts:66

Turns an offer into an answer and keeps the peer it negotiates.

answerTimeoutMs? ​

readonly optional answerTimeoutMs?: number

Defined in: packages/nethernet/src/HttpSignaling.ts:81

How long an offer may wait for its answer.

logger ​

readonly logger: SignalingLogger

Defined in: packages/nethernet/src/HttpSignaling.ts:79

resolve? ​

readonly optional resolve?: (hostname) => Promise<readonly string[]>

Defined in: packages/nethernet/src/HttpSignaling.ts:78

Resolves a hostname a client dialed to its IP addresses; the system resolver when absent. The name comes from the request's Host header, so anyone who can reach signaling picks it.

Parameters ​
hostname ​

string

Returns ​

Promise<readonly string[]>

sign ​

readonly sign: (answer, dialed?) => string | Promise<string>

Defined in: packages/nethernet/src/HttpSignaling.ts:73

Adds the server's a=identity to an answer; the client refuses one without it. dialed is where the client sent its offer, for withDialedCandidates to add to the answer first.

Parameters ​
answer ​

string

dialed? ​

DialedAddress

Returns ​

string | Promise<string>

status ​

readonly status: () => string

Defined in: packages/nethernet/src/HttpSignaling.ts:68

The GET /v1/join body, read per request.

Returns ​

string

IdentityProof ​

Defined in: packages/nethernet/src/NetherNetIdentity.ts:141

What a description's a=identity offers as proof of a key: the detached signature over the description's DTLS fingerprints, and the bytes it should cover. Whoever holds the key that made the signature is the peer whose certificate the connection's DTLS handshake checked.

Properties ​

signature ​

readonly signature: string

Defined in: packages/nethernet/src/NetherNetIdentity.ts:143

The detached ES384 JWS from the assertion's fingerprints.

signed ​

readonly signed: string

Defined in: packages/nethernet/src/NetherNetIdentity.ts:145

The canonical fingerprints of the description, which the signature should cover.

JoinProbe ​

Defined in: packages/nethernet/src/joinByAddress.ts:25

What GET /v1/join said about a server that speaks NetherNet.

Properties ​

status? ​

readonly optional status?: NetherNetStatus

Defined in: packages/nethernet/src/joinByAddress.ts:30

The server's status, when it sent one. Bedrock Dedicated Server 1.26.51 answers with an empty body when LAN visibility is off, and go-nethernet does when it has no status to give.

LanAdvertisement ​

Defined in: packages/nethernet/src/LanAdvertisement.ts:14

What a server tells a client looking for games on the local network, in the answer to a NetherNet discovery request on UDP 7551. The client lists it among its LAN games.

Extends ​

Properties ​

acceptsOnlineAuth ​

readonly acceptsOnlineAuth: boolean

Defined in: packages/nethernet/src/LanAdvertisement.ts:18

Whether a client signed in to Xbox Live may join.

acceptsSelfSignedAuth ​

readonly acceptsSelfSignedAuth: boolean

Defined in: packages/nethernet/src/LanAdvertisement.ts:20

Whether a client that signs its own login may join, which an online-mode server refuses.

connectionType ​

readonly connectionType: number

Defined in: packages/nethernet/src/LanAdvertisement.ts:23

editorWorld ​

readonly editorWorld: boolean

Defined in: packages/nethernet/src/LanAdvertisement.ts:15

gameType ​

readonly gameType: number

Defined in: packages/nethernet/src/NetherNetStatus.ts:16

The Gametype id: 0 survival, 1 creative, 2 adventure.

Inherited from ​

NetherNetStatus.gameType

hardcore ​

readonly hardcore: boolean

Defined in: packages/nethernet/src/LanAdvertisement.ts:16

levelName ​

readonly levelName: string

Defined in: packages/nethernet/src/NetherNetStatus.ts:9

Inherited from ​

NetherNetStatus.levelName

maxPlayers ​

readonly maxPlayers: number

Defined in: packages/nethernet/src/NetherNetStatus.ts:14

Inherited from ​

NetherNetStatus.maxPlayers

motd ​

readonly motd: string

Defined in: packages/nethernet/src/NetherNetStatus.ts:8

Inherited from ​

NetherNetStatus.motd

nonce ​

readonly nonce: string

Defined in: packages/nethernet/src/LanAdvertisement.ts:22

A random token per server start; Bedrock Dedicated Server sends 64 random bits in hex.

playerCount ​

readonly playerCount: number

Defined in: packages/nethernet/src/NetherNetStatus.ts:13

Inherited from ​

NetherNetStatus.playerCount

protocol ​

readonly protocol: number

Defined in: packages/nethernet/src/NetherNetStatus.ts:10

Inherited from ​

NetherNetStatus.protocol

version ​

readonly version: string

Defined in: packages/nethernet/src/NetherNetStatus.ts:12

The game version, such as 1.26.51.

Inherited from ​

NetherNetStatus.version

LanDiscoveryOptions ​

Defined in: packages/nethernet/src/LanDiscovery.ts:22

Where a LAN discovery client asks, for a test that cannot use the fixed port.

Properties ​

broadcastAddress? ​

readonly optional broadcastAddress?: string

Defined in: packages/nethernet/src/LanDiscovery.ts:24

networkId? ​

readonly optional networkId?: bigint

Defined in: packages/nethernet/src/LanDiscovery.ts:23

port? ​

readonly optional port?: number

Defined in: packages/nethernet/src/LanDiscovery.ts:25

NativeDriverOptions ​

Defined in: packages/nethernet/src/nativeDriver.ts:38

How the native driver reports what the library logs.

Properties ​

log? ​

readonly optional log?: (line) => void

Defined in: packages/nethernet/src/nativeDriver.ts:43

Receives the warnings and errors no failing call claimed, such as a connection that fails after it opened. The lines a failing call logged go into its error's message instead.

Parameters ​
line ​

NativeLogLine

Returns ​

void

NativeLogLine ​

Defined in: packages/nethernet/src/nativeDriver.ts:30

A line the native library logged that no failing call claimed.

Properties ​

level ​

readonly level: number

Defined in: packages/nethernet/src/nativeDriver.ts:32

libdatachannel's level: 1 fatal, 2 error, 3 warning.

text ​

readonly text: string

Defined in: packages/nethernet/src/nativeDriver.ts:34

The line, without the source location libdatachannel puts first.

NetherNetClientOptions ​

Defined in: packages/nethernet/src/NetherNetClient.ts:16

How the client builds its peer and reaches the server.

Properties ​

connection? ​

readonly optional connection?: ConnectionOptions

Defined in: packages/nethernet/src/NetherNetClient.ts:30

How much the connection accepts and buffers; the protocol's limits when absent.

connectionId? ​

readonly optional connectionId?: bigint

Defined in: packages/nethernet/src/NetherNetClient.ts:23

driver ​

readonly driver: WebRtcDriver

Defined in: packages/nethernet/src/NetherNetClient.ts:17

networkId? ​

readonly optional networkId?: bigint

Defined in: packages/nethernet/src/NetherNetClient.ts:22

peerConfig? ​

readonly optional peerConfig?: PeerConfig

Defined in: packages/nethernet/src/NetherNetClient.ts:24

prepareOffer? ​

readonly optional prepareOffer?: (offer) => string | Promise<string>

Defined in: packages/nethernet/src/NetherNetClient.ts:26

Rewrites the offer before it is sent, such as to add the a=identity attribute.

Parameters ​
offer ​

string

Returns ​

string | Promise<string>

serverNetworkId? ​

readonly optional serverNetworkId?: bigint

Defined in: packages/nethernet/src/NetherNetClient.ts:21

The server's network ID, when the carrier needs it; 0 when joining by address.

signal ​

readonly signal: SignalSender

Defined in: packages/nethernet/src/NetherNetClient.ts:19

Sends the client's signals to the server.

timeoutMs? ​

readonly optional timeoutMs?: number

Defined in: packages/nethernet/src/NetherNetClient.ts:28

How long the join may take, answer and connection together.

NetherNetIdentityOptions ​

Defined in: packages/nethernet/src/NetherNetIdentity.ts:32

How a NetherNetIdentity presents itself.

Properties ​

domain? ​

readonly optional domain?: string

Defined in: packages/nethernet/src/NetherNetIdentity.ts:34

Shown to players on first use over plain HTTP. Bedrock Dedicated Server says self.

keyFormat? ​

readonly optional keyFormat?: IdentityKeyFormat

Defined in: packages/nethernet/src/NetherNetIdentity.ts:36

How the token carries the public key; a server's is a JWK, a client's base64 DER.

now? ​

readonly optional now?: () => number

Defined in: packages/nethernet/src/NetherNetIdentity.ts:38

The clock, in milliseconds since the epoch.

Returns ​

number

token? ​

readonly optional token?: string

Defined in: packages/nethernet/src/NetherNetIdentity.ts:44

A token an authority issued for this key, used instead of a self-signed one: a signed-in client's multiplayer token from Minecraft's authorization service, whose cpk claim names this key. The fingerprints are still signed with the key here.

NetherNetOfferAnswerer ​

Defined in: packages/nethernet/src/HttpSignaling.ts:41

The part of NetherNetServer that turns an offer into an answer.

Properties ​

connections ​

readonly connections: ReadonlyMap<bigint, { peer?: DriverPeer; close(reason?): void; }>

Defined in: packages/nethernet/src/HttpSignaling.ts:43

Every peer by connection ID, which a new offer's ID must not collide with.

Methods ​

handleOffer() ​

handleOffer(signal, respond, proof?): Promise<void>

Defined in: packages/nethernet/src/HttpSignaling.ts:45

Negotiates a peer for the offer, answering through respond.

Parameters ​
signal ​

SignalStructure

respond ​

(signal) => void

proof? ​

IdentityProof

Returns ​

Promise<void>

NetherNetServerOptions ​

Defined in: packages/nethernet/src/NetherNetServer.ts:32

How the server builds each peer, and how long it waits for one.

Properties ​

acceptTimeoutMs? ​

readonly optional acceptTimeoutMs?: number

Defined in: packages/nethernet/src/NetherNetServer.ts:40

connection? ​

readonly optional connection?: ConnectionOptions

Defined in: packages/nethernet/src/NetherNetServer.ts:49

How much each connection accepts and buffers; the protocol's limits when absent.

driver ​

readonly driver: WebRtcDriver

Defined in: packages/nethernet/src/NetherNetServer.ts:33

host? ​

readonly optional host?: string

Defined in: packages/nethernet/src/NetherNetServer.ts:37

The address LAN discovery binds; every IPv4 interface when absent.

lanPort? ​

readonly optional lanPort?: number

Defined in: packages/nethernet/src/NetherNetServer.ts:39

The LAN discovery port; NetherNet's fixed 7551 when absent, which a test cannot share.

networkId? ​

readonly optional networkId?: bigint

Defined in: packages/nethernet/src/NetherNetServer.ts:35

The server's network ID; random when absent.

peerConfig? ​

readonly optional peerConfig?: (connectionId) => PeerConfig

Defined in: packages/nethernet/src/NetherNetServer.ts:42

The configuration of the peer for a new offer, such as its bind address.

Parameters ​
connectionId ​

bigint

Returns ​

PeerConfig

ports? ​

readonly optional ports?: PortAllocator

Defined in: packages/nethernet/src/NetherNetServer.ts:47

The local UDP ports peers share, one mux port each; the system picks a port per peer when absent.

NetherNetStatus ​

Defined in: packages/nethernet/src/NetherNetStatus.ts:7

What a NetherNet client is told about a server before it joins: the LAN advertisement on UDP 7551 and the GET /v1/join answer on the game port both carry these.

Extended by ​

Properties ​

gameType ​

readonly gameType: number

Defined in: packages/nethernet/src/NetherNetStatus.ts:16

The Gametype id: 0 survival, 1 creative, 2 adventure.

levelName ​

readonly levelName: string

Defined in: packages/nethernet/src/NetherNetStatus.ts:9

maxPlayers ​

readonly maxPlayers: number

Defined in: packages/nethernet/src/NetherNetStatus.ts:14

motd ​

readonly motd: string

Defined in: packages/nethernet/src/NetherNetStatus.ts:8

playerCount ​

readonly playerCount: number

Defined in: packages/nethernet/src/NetherNetStatus.ts:13

protocol ​

readonly protocol: number

Defined in: packages/nethernet/src/NetherNetStatus.ts:10

version ​

readonly version: string

Defined in: packages/nethernet/src/NetherNetStatus.ts:12

The game version, such as 1.26.51.

PeerAddress ​

Defined in: packages/nethernet/src/WebRtcDriver.ts:27

A UDP address.

Properties ​

address ​

readonly address: string

Defined in: packages/nethernet/src/WebRtcDriver.ts:28

port ​

readonly port: number

Defined in: packages/nethernet/src/WebRtcDriver.ts:29

PeerConfig ​

Defined in: packages/nethernet/src/WebRtcDriver.ts:14

Where a peer binds and which local ports it may use.

Properties ​

bindAddress? ​

readonly optional bindAddress?: string

Defined in: packages/nethernet/src/WebRtcDriver.ts:18

The local address to bind; every interface when absent.

enableIceUdpMux? ​

readonly optional enableIceUdpMux?: boolean

Defined in: packages/nethernet/src/WebRtcDriver.ts:23

Serves every peer on a port from one socket.

iceServers? ​

readonly optional iceServers?: readonly string[]

Defined in: packages/nethernet/src/WebRtcDriver.ts:16

STUN and TURN server URLs.

portRangeBegin? ​

readonly optional portRangeBegin?: number

Defined in: packages/nethernet/src/WebRtcDriver.ts:20

The local UDP port range; 0 or absent lets the system choose.

portRangeEnd? ​

readonly optional portRangeEnd?: number

Defined in: packages/nethernet/src/WebRtcDriver.ts:21

PortLoad ​

Defined in: packages/nethernet/src/PortAllocator.ts:4

One port of a range and how many peers it serves now.

Properties ​

peers ​

readonly peers: number

Defined in: packages/nethernet/src/PortAllocator.ts:6

port ​

readonly port: number

Defined in: packages/nethernet/src/PortAllocator.ts:5

PortMapping ​

Defined in: packages/nethernet/src/udpPorts.ts:12

A NAT or port-forwarding mapping: clients reach internal through external.

Properties ​

external ​

readonly external: PortRange

Defined in: packages/nethernet/src/udpPorts.ts:13

internal ​

readonly internal: PortRange

Defined in: packages/nethernet/src/udpPorts.ts:14

PortRange ​

Defined in: packages/nethernet/src/udpPorts.ts:6

An inclusive range of UDP ports.

Properties ​

end ​

readonly end: number

Defined in: packages/nethernet/src/udpPorts.ts:8

start ​

readonly start: number

Defined in: packages/nethernet/src/udpPorts.ts:7

PortSelectionStrategy ​

Defined in: packages/nethernet/src/PortAllocator.ts:13

Picks the port a new peer goes on, from the ports of the range and the peers on each. Ports are reused once every one serves a peer, so a strategy always has a port to give.

Methods ​

select() ​

select(ports): number

Defined in: packages/nethernet/src/PortAllocator.ts:18

Parameters ​
ports ​

readonly PortLoad[]

Every port of the range, lowest first.

Returns ​

number

One of the ports.

PublicIpLookupOptions ​

Defined in: packages/nethernet/src/publicIpLookup.ts:22

What lookupPublicIp asks, and how.

Properties ​

fetch? ​

readonly optional fetch?: (url, init) => Promise<Response>

Defined in: packages/nethernet/src/publicIpLookup.ts:26

Sends a request; the global fetch when absent.

Parameters ​
url ​

string

init ​
signal ​

AbortSignal

Returns ​

Promise<Response>

services? ​

readonly optional services?: readonly string[]

Defined in: packages/nethernet/src/publicIpLookup.ts:24

The services to ask, in order; PUBLIC_IP_SERVICES when absent.

signal? ​

readonly optional signal?: AbortSignal

Defined in: packages/nethernet/src/publicIpLookup.ts:30

Stops the lookup, such as when the server stops first.

timeoutMs? ​

readonly optional timeoutMs?: number

Defined in: packages/nethernet/src/publicIpLookup.ts:28

How long each service may take, in milliseconds.

SdpFingerprint ​

Defined in: packages/nethernet/src/sdp.ts:12

One a=fingerprint attribute: the DTLS certificate hash the peer must present.

Properties ​

algorithm ​

readonly algorithm: string

Defined in: packages/nethernet/src/sdp.ts:14

The hash function, such as sha-256.

digest ​

readonly digest: string

Defined in: packages/nethernet/src/sdp.ts:16

The hash, colon-separated hex, as the SDP spells it.

SignalingAddress ​

Defined in: packages/nethernet/src/joinByAddress.ts:5

Where a NetherNet server signals: the TCP side of its game port.

Properties ​

host ​

readonly host: string

Defined in: packages/nethernet/src/joinByAddress.ts:6

port ​

readonly port: number

Defined in: packages/nethernet/src/joinByAddress.ts:7

SignalingLogger ​

Defined in: packages/nethernet/src/HttpSignaling.ts:56

Where the signaling server reports what it does. @jsprismarine/logger's Logger fits. Each join's candidates and progress go to debug, and a join that fails to warn.

Methods ​

debug() ​

debug(message): void

Defined in: packages/nethernet/src/HttpSignaling.ts:57

Parameters ​
message ​

string

Returns ​

void

error() ​

error(error): void

Defined in: packages/nethernet/src/HttpSignaling.ts:60

Parameters ​
error ​

unknown

Returns ​

void

info() ​

info(message): void

Defined in: packages/nethernet/src/HttpSignaling.ts:58

Parameters ​
message ​

string

Returns ​

void

warn() ​

warn(message): void

Defined in: packages/nethernet/src/HttpSignaling.ts:59

Parameters ​
message ​

string

Returns ​

void

UdpPorts ​

Defined in: packages/nethernet/src/udpPorts.ts:18

What server-udp-ports and server-public-ip say together.

Properties ​

local? ​

readonly optional local?: PortRange

Defined in: packages/nethernet/src/udpPorts.ts:20

The one continuous range of local ports, or undefined when the setting is unset or empty.

mappings ​

readonly mappings: readonly PortMapping[]

Defined in: packages/nethernet/src/udpPorts.ts:22

Mappings to advertise in answers, in the order they were written.

publicIp? ​

readonly optional publicIp?: string

Defined in: packages/nethernet/src/udpPorts.ts:24

The address to advertise, from server-public-ip or a deprecated IP prefix.

warnings ​

readonly warnings: readonly string[]

Defined in: packages/nethernet/src/udpPorts.ts:26

What the setting does that is deprecated, one sentence each, for the log.

VerifiedIdentity ​

Defined in: packages/nethernet/src/NetherNetIdentity.ts:187

What verifySelfSignedIdentity found in a description it accepted.

Properties ​

description ​

readonly description: string

Defined in: packages/nethernet/src/NetherNetIdentity.ts:193

The description without a=identity, ready for WebRTC.

domain ​

readonly domain: string

Defined in: packages/nethernet/src/NetherNetIdentity.ts:191

The domain the identity names, which a player may be shown.

publicKey ​

readonly publicKey: KeyObject

Defined in: packages/nethernet/src/NetherNetIdentity.ts:189

The identity's public key, from the token's cpk claim.

WebRtcDriver ​

Defined in: packages/nethernet/src/WebRtcDriver.ts:70

Builds peer connections.

Methods ​

createPeer() ​

createPeer(config?): DriverPeer

Defined in: packages/nethernet/src/WebRtcDriver.ts:71

Parameters ​
config? ​

PeerConfig

Returns ​

DriverPeer

Type Aliases ​

DiscoveryPacket ​

DiscoveryPacket = DiscoveryRequest | DiscoveryResponse | DiscoveryMessage

Defined in: packages/nethernet/src/protocol/Discovery.ts:40

Any discovery packet.

IceState ​

IceState = "new" | "checking" | "connected" | "completed" | "failed" | "disconnected" | "closed"

Defined in: packages/nethernet/src/WebRtcDriver.ts:11

A peer's ICE agent state, as the W3C iceConnectionState names it.

IdentityKeyFormat ​

IdentityKeyFormat = "jwk" | "der"

Defined in: packages/nethernet/src/NetherNetIdentity.ts:25

How an identity writes its public key into the token's cpk claim.

PeerState ​

PeerState = "new" | "connecting" | "connected" | "disconnected" | "failed" | "closed"

Defined in: packages/nethernet/src/WebRtcDriver.ts:8

A peer connection's state, as the W3C connectionState names it.

PublicIpLookupResult ​

PublicIpLookupResult = { address: string; service: string; } | { failures: readonly string[]; }

Defined in: packages/nethernet/src/publicIpLookup.ts:34

What lookupPublicIp found: the address and the service that named it, or why every service failed.

SignalResponder ​

SignalResponder = (signal) => void

Defined in: packages/nethernet/src/NetherNetServer.ts:29

How a signal's answer goes back to the client that sent it.

Parameters ​

signal ​

SignalStructure

Returns ​

void

SignalSender ​

SignalSender = (signal) => void

Defined in: packages/nethernet/src/NetherNetClient.ts:13

What the client sends signals with: HTTP signaling, LAN discovery, or anything else.

Parameters ​

signal ​

SignalStructure

Returns ​

void

SignalType ​

SignalType = typeof SignalType[keyof typeof SignalType]

Defined in: packages/nethernet/src/protocol/Signal.ts:2

One of the SignalType words.

Variables ​

BEDROCK_CURVE ​

const BEDROCK_CURVE: "secp384r1" = 'secp384r1'

Defined in: packages/nethernet/src/es384.ts:6

The curve Bedrock signs with: the login chain, the encryption handshake and NetherNet identities.

DEFAULT_ACCEPT_TIMEOUT_MS ​

const DEFAULT_ACCEPT_TIMEOUT_MS: 10000 = 10_000

Defined in: packages/nethernet/src/NetherNetServer.ts:23

How long a peer may take from its answer to opening both channels and connecting. Ten seconds is the default EndstoneMC's NetherNet specification gives for Bedrock's negotiation timeout. A client joining by address may ask its player to trust the server after it has the answer, and the time the player takes counts against this.

DEFAULT_CLIENT_TIMEOUT_MS ​

const DEFAULT_CLIENT_TIMEOUT_MS: 15000 = 15_000

Defined in: packages/nethernet/src/NetherNetClient.ts:10

How long a join may wait for the answer, and then for the connection to open.

DEFAULT_MAX_BUFFERED_BYTES ​

const DEFAULT_MAX_BUFFERED_BYTES: number

Defined in: packages/nethernet/src/Connection.ts:28

How many bytes of a reliable channel's data may wait in the WebRTC stack before the connection is given up as too slow. A join's chunks are a few megabytes; a peer that falls this far behind is not reading, and the queue would otherwise grow until memory runs out.

DISCOVERY_INTERVAL_MS ​

const DISCOVERY_INTERVAL_MS: 2000 = 2_000

Defined in: packages/nethernet/src/LanDiscovery.ts:11

How often a client asks the network who is there, as Bedrock does.

DiscoveryPacketType ​

const DiscoveryPacketType: object

Defined in: packages/nethernet/src/protocol/Discovery.ts:12

The packet types, as the u16 after the length numbers them.

Type Declaration ​

Message ​

readonly Message: 2 = 2

Request ​

readonly Request: 0 = 0

Response ​

readonly Response: 1 = 1

ErrorCode ​

const ErrorCode: object

Defined in: packages/nethernet/src/protocol/Signal.ts:13

The codes a CONNECTERROR signal carries, as Bedrock numbers them.

Type Declaration ​

CandidateAdd ​

readonly CandidateAdd: 8 = 8

ConnectRequest ​

readonly ConnectRequest: 6 = 6

ConnectResponse ​

readonly ConnectResponse: 7 = 7

DestinationNotLoggedIn ​

readonly DestinationNotLoggedIn: 1 = 1

FailedToCreateAnswer ​

readonly FailedToCreateAnswer: 11 = 11

FailedToCreateOffer ​

readonly FailedToCreateOffer: 10 = 10

FailedToCreatePeerConnection ​

readonly FailedToCreatePeerConnection: 4 = 4

FailedToSetLocalDescription ​

readonly FailedToSetLocalDescription: 12 = 12

FailedToSetRemoteDescription ​

readonly FailedToSetRemoteDescription: 13 = 13

ICE ​

readonly ICE: 5 = 5

InactivityTimeout ​

readonly InactivityTimeout: 9 = 9

IncomingConnectionIgnored ​

readonly IncomingConnectionIgnored: 16 = 16

NegotiationTimeout ​

readonly NegotiationTimeout: 2 = 2

NegotiationTimeoutWaitingForAccept ​

readonly NegotiationTimeoutWaitingForAccept: 15 = 15

NegotiationTimeoutWaitingForResponse ​

readonly NegotiationTimeoutWaitingForResponse: 14 = 14

None ​

readonly None: 0 = 0

NoSignalingChannel ​

readonly NoSignalingChannel: 24 = 24

NotLoggedIn ​

readonly NotLoggedIn: 25 = 25

SignalingBroadcastDeliveryFailed ​

readonly SignalingBroadcastDeliveryFailed: 20 = 20

SignalingFailedToSend ​

readonly SignalingFailedToSend: 26 = 26

SignalingFallbackToBestEffortDelivery ​

readonly SignalingFallbackToBestEffortDelivery: 23 = 23

SignalingMessageDeliveryFailed ​

readonly SignalingMessageDeliveryFailed: 21 = 21

SignalingParsingFailure ​

readonly SignalingParsingFailure: 17 = 17

SignalingTurnAuthFailed ​

readonly SignalingTurnAuthFailed: 22 = 22

SignalingUnicastMessageDeliveryFailed ​

readonly SignalingUnicastMessageDeliveryFailed: 19 = 19

SignalingUnknownError ​

readonly SignalingUnknownError: 18 = 18

WrongTransportVersion ​

readonly WrongTransportVersion: 3 = 3

LAN_ADVERTISEMENT_VERSION ​

const LAN_ADVERTISEMENT_VERSION: 7 = 7

Defined in: packages/nethernet/src/LanAdvertisement.ts:5

The advertisement layout Bedrock Dedicated Server 1.26.51 answers LAN discovery with.

MAX_MESSAGE_BYTES ​

const MAX_MESSAGE_BYTES: number

Defined in: packages/nethernet/src/Connection.ts:18

The longest message Bedrock sends: MAX_SEGMENTS full segments.

MAX_SEGMENTS ​

const MAX_SEGMENTS: 255 = 255

Defined in: packages/nethernet/src/Connection.ts:15

The most segments Bedrock splits one message into.

NETHERNET_LAN_PORT ​

const NETHERNET_LAN_PORT: 7551 = 7551

Defined in: packages/nethernet/src/NetherNetDefaults.ts:2

The UDP port NetherNet LAN discovery and its signals use. The protocol fixes it.

PUBLIC_IP_SERVICES ​

const PUBLIC_IP_SERVICES: readonly ["https://api.ipify.org", "https://ipv4.icanhazip.com", "https://checkip.amazonaws.com", "https://v4.ident.me"]

Defined in: packages/nethernet/src/publicIpLookup.ts:8

Free services that answer a plain-text request with the caller's public IPv4 address, in the order lookupPublicIp asks them. Several, so one being down or rate limited costs nothing. Each answers over IPv4 only, so the address is of the family most host candidates are.

SEGMENT_BYTES ​

const SEGMENT_BYTES: 262143 = 262_143

Defined in: packages/nethernet/src/Connection.ts:12

The most payload one data channel message carries, as Bedrock sends it: its a=max-message-size of 262144 less the count byte. A longer message is split into segments, and a remote description that allows less lowers it for that connection.

SignalType ​

const SignalType: object

Defined in: packages/nethernet/src/protocol/Signal.ts:2

The kinds of signal NetherNet's signaling carries, by the word that starts each one.

Type Declaration ​

CandidateAdd ​

readonly CandidateAdd: "CANDIDATEADD" = 'CANDIDATEADD'

ConnectError ​

readonly ConnectError: "CONNECTERROR" = 'CONNECTERROR'

ConnectRequest ​

readonly ConnectRequest: "CONNECTREQUEST" = 'CONNECTREQUEST'

ConnectResponse ​

readonly ConnectResponse: "CONNECTRESPONSE" = 'CONNECTRESPONSE'

fewestPeers ​

const fewestPeers: PortSelectionStrategy

Defined in: packages/nethernet/src/PortAllocator.ts:22

The port with the fewest peers, the lowest on a tie.

Functions ​

candidateAddress() ​

candidateAddress(candidate): PeerAddress | undefined

Defined in: packages/nethernet/src/WebRtcDriver.ts:80

The address and port in an ICE candidate line, which reads candidate:<foundation> <component> <protocol> <priority> <address> <port> typ <type> ….

Parameters ​

candidate ​

string

The candidate line, with or without the a= SDP prefix.

Returns ​

PeerAddress | undefined

The address, or undefined for a line that does not have one where the format puts it.

canonicalFingerprints() ​

canonicalFingerprints(fingerprints): string

Defined in: packages/nethernet/src/NetherNetIdentity.ts:19

The fingerprints as canonical JSON: keys in code point order, no whitespace. The client rebuilds these exact bytes from the answer's a=fingerprint lines to check the signature.

Parameters ​

fingerprints ​

readonly SdpFingerprint[]

The answer's fingerprints, in SDP order.

Returns ​

string

compactEs384() ​

compactEs384(header, payload, privateKey): Promise<string>

Defined in: packages/nethernet/src/es384.ts:18

A compact ES384 JWS (a JWT, when the payload is a claim set): header.payload.signature, signed by jose.

Parameters ​

Readonly<Record<string, unknown>>

Header fields besides alg, such as x5u.

payload ​

unknown

The JSON payload.

privateKey ​

KeyObject

A P-384 private key.

Returns ​

Promise<string>

decodeDiscoveryPacket() ​

decodeDiscoveryPacket(datagram): DiscoveryPacket

Defined in: packages/nethernet/src/protocol/Discovery.ts:104

Decodes a datagram from UDP 7551.

Parameters ​

datagram ​

Buffer

The datagram.

Returns ​

DiscoveryPacket

The packet.

Throws ​

When the datagram is short, its checksum does not match, or its type is unknown.

decodeJoinStatus() ​

decodeJoinStatus(body): NetherNetStatus

Defined in: packages/nethernet/src/NetherNetStatus.ts:39

Reads a GET /v1/join body back into the status.

Parameters ​

body ​

string

The JSON the server answered with.

Returns ​

NetherNetStatus

Throws ​

When a field is missing or has the wrong type.

decodeLanAdvertisement() ​

decodeLanAdvertisement(buffer): LanAdvertisement

Defined in: packages/nethernet/src/LanAdvertisement.ts:69

Decodes an advertisement in layout LAN_ADVERTISEMENT_VERSION.

Parameters ​

buffer ​

Buffer

Returns ​

LanAdvertisement

Throws ​

When the buffer carries another layout version or ends early.

describeCandidates() ​

describeCandidates(description): string[]

Defined in: packages/nethernet/src/tracePeerConnection.ts:4

The candidates a description lists, as address:port type, for a log line.

Parameters ​

description ​

string

Returns ​

string[]

detachedEs384() ​

detachedEs384(payload, privateKey): Promise<string>

Defined in: packages/nethernet/src/es384.ts:33

A detached ES384 JWS over exact payload bytes (RFC 7515 appendix F): header..signature. The verifier rebuilds the payload itself, so its bytes must be the canonical ones it will build.

Parameters ​

payload ​

string

The payload bytes, signed as given.

privateKey ​

KeyObject

A P-384 private key.

Returns ​

Promise<string>

encodeDiscoveryPacket() ​

encodeDiscoveryPacket(packet): Buffer

Defined in: packages/nethernet/src/protocol/Discovery.ts:73

Encodes a packet as the datagram LAN discovery sends.

Parameters ​

packet ​

DiscoveryPacket

The packet.

Returns ​

Buffer

The checksum and the encrypted packet.

encodeLanAdvertisement() ​

encodeLanAdvertisement(advertisement): Buffer

Defined in: packages/nethernet/src/LanAdvertisement.ts:46

Encodes the advertisement in layout LAN_ADVERTISEMENT_VERSION: a version byte, then varint-prefixed strings, zigzag varints and booleans in a fixed order.

Parameters ​

LanAdvertisement

Returns ​

Buffer

exchangeOffer() ​

exchangeOffer(address, networkId, offer, signal?): Promise<string>

Defined in: packages/nethernet/src/joinByAddress.ts:58

Trades a complete SDP offer for the server's complete answer, the one request a client sends per attempt.

Parameters ​

address ​

SignalingAddress

The server's host and game port.

networkId ​

bigint

The client's own network ID.

offer ​

string

The offer, with every candidate and the client's a=identity.

signal? ​

AbortSignal

Aborts the request.

Returns ​

Promise<string>

The answer.

Throws ​

When the server answers anything but 2xx.

hasPublicCandidate() ​

hasPublicCandidate(description): boolean

Defined in: packages/nethernet/src/udpPorts.ts:294

Whether a description has a candidate a host elsewhere on the internet can send to. An answer without one reaches clients on the server's own network and nobody else.

Parameters ​

description ​

string

The SDP description, with its candidates.

Returns ​

boolean

identityProofOf() ​

identityProofOf(description): IdentityProof | undefined

Defined in: packages/nethernet/src/NetherNetIdentity.ts:156

The proof a description's a=identity carries, without judging it: which key it proves is asked later with provesKey, once the peer has said who it is. A server uses this to tie a login to its connection, since NetherNet leaves out the encryption handshake that proves the login's key on RakNet.

Parameters ​

description ​

string

The SDP description, with its a=fingerprint lines.

Returns ​

IdentityProof | undefined

The proof, or undefined when the description has no usable a=identity.

joinStatusJson() ​

joinStatusJson(status): string

Defined in: packages/nethernet/src/NetherNetStatus.ts:23

The GET /v1/join body: the status under the field names Bedrock Dedicated Server 1.26.51 answers with, in its order.

Parameters ​

status ​

NetherNetStatus

Returns ​

string

lanAdvertisementOf() ​

lanAdvertisementOf(status, onlineMode, nonce): LanAdvertisement

Defined in: packages/nethernet/src/LanAdvertisement.ts:32

The advertisement for a server.

Parameters ​

status ​

NetherNetStatus

What every NetherNet client is told about the server.

onlineMode ​

boolean

Whether the server requires Xbox Live sign-in.

nonce ​

string

This server start's token.

Returns ​

LanAdvertisement

loadNativeDriver() ​

loadNativeDriver(options?): Promise<WebRtcDriver>

Defined in: packages/nethernet/src/nativeDriver.ts:163

Loads the native library and returns its driver.

Parameters ​

options? ​

NativeDriverOptions = {}

Where the library's log lines go.

Returns ​

Promise<WebRtcDriver>

The driver.

Throws ​

When the library cannot be loaded, with the platform and the cause.

lookupPublicIp() ​

lookupPublicIp(options?): Promise<PublicIpLookupResult>

Defined in: packages/nethernet/src/publicIpLookup.ts:44

Asks each service in turn for this host's public address, and returns the first that answers with a public IP literal. A service that fails, times out, or answers with anything else is skipped, and its reason kept for the log.

Parameters ​

options? ​

PublicIpLookupOptions = {}

The services, the transport and the timeout.

Returns ​

Promise<PublicIpLookupResult>

The address and its service, or one failure per service asked.

nativeDriver() ​

nativeDriver(network, options?): WebRtcDriver

Defined in: packages/nethernet/src/nativeDriver.ts:105

The native networking library as a WebRtcDriver.

Parameters ​

network ​

NativeNetwork

The loaded library.

options? ​

NativeDriverOptions = {}

Where the library's log lines go.

Returns ​

WebRtcDriver

The driver.

parsePublicIp() ​

parsePublicIp(setting): string | undefined

Defined in: packages/nethernet/src/udpPorts.ts:87

Reads server-public-ip as Bedrock Dedicated Server 1.26.70.24 does: empty, a raw IPv4, or a raw or bracketed IPv6. A hostname or a port is an error.

Parameters ​

setting ​

string

The setting.

Returns ​

string | undefined

The address, or undefined when it is empty.

Throws ​

For anything else, with Bedrock Dedicated Server's message.

parseUdpPorts() ​

parseUdpPorts(setting, publicIpSetting?): UdpPorts

Defined in: packages/nethernet/src/udpPorts.ts:132

Reads server-udp-ports with server-public-ip as Bedrock Dedicated Server 1.26.70.24 does (docs/research/bds-server-udp-ports.md):

  • Entries are separated by commas; spaces around them and empty entries are ignored, and a repeated entry is fine.
  • Each is a port, start-end, or a public:local mapping of a port or a range onto one of the same length.
  • The local ports of every entry must form one continuous range: adjacent and overlapping ranges merge, and a gap is an error.
  • A deprecated IP:public:local or [IPv6]:public:local prefix still sets the public address, with a warning that names server-public-ip. Two different prefixes, or one that differs from server-public-ip, is an error.

Parameters ​

setting ​

string

server-udp-ports; empty for unset.

publicIpSetting? ​

string = ''

server-public-ip; empty for unset.

Returns ​

UdpPorts

What the two say.

Throws ​

For a value Bedrock Dedicated Server refuses, with its message.

probeJoin() ​

probeJoin(address, signal?): Promise<JoinProbe | undefined>

Defined in: packages/nethernet/src/joinByAddress.ts:41

Asks whether the server speaks NetherNet, as a client does before it joins by address: any 2xx from GET /v1/join means yes, whatever the body says.

Parameters ​

address ​

SignalingAddress

The server's host and game port.

signal? ​

AbortSignal

Aborts the request.

Returns ​

Promise<JoinProbe | undefined>

What the server said, or undefined when it does not speak NetherNet there.

Throws ​

When a 2xx body is present but is not a join status.

provesKey() ​

provesKey(proof, publicKey): Promise<boolean>

Defined in: packages/nethernet/src/NetherNetIdentity.ts:176

Whether a proof was made with a key: the holder of its private half signed the fingerprints of the description the proof came from.

Parameters ​

proof ​

IdentityProof

The proof, from identityProofOf.

publicKey ​

string

The key, as base64 DER, the form a login's identityPublicKey takes.

Returns ​

Promise<boolean>

randomUint64() ​

randomUint64(): bigint

Defined in: packages/nethernet/src/randomUint64.ts:4

A random unsigned 64-bit integer, as network and connection IDs are.

Returns ​

bigint

sdpFingerprints() ​

sdpFingerprints(sdp): SdpFingerprint[]

Defined in: packages/nethernet/src/sdp.ts:23

Every a=fingerprint in a description, in the order they appear.

Parameters ​

sdp ​

string

The session description.

Returns ​

SdpFingerprint[]

segment() ​

segment(message, segmentBytes?): Buffer<ArrayBufferLike>[]

Defined in: packages/nethernet/src/Connection.ts:57

Splits a message into NetherNet's segments: each is one byte, the number of segments after it, and up to segmentBytes of the message.

Parameters ​

message ​

Uint8Array

The message.

segmentBytes? ​

number = SEGMENT_BYTES

The most payload one segment carries.

Returns ​

Buffer<ArrayBufferLike>[]

The segments, in order.

Throws ​

When the message is empty or needs more than MAX_SEGMENTS segments.

segmentBytesFor() ​

segmentBytesFor(description): number

Defined in: packages/nethernet/src/Connection.ts:42

The payload one segment may carry to a peer: what its description's a=max-message-size allows, less the count byte, and never more than SEGMENT_BYTES.

Parameters ​

description ​

string

The remote SDP description.

Returns ​

number

The segment size to send with.

tracePeerConnection() ​

tracePeerConnection(peer, log): void

Defined in: packages/nethernet/src/tracePeerConnection.ts:27

Reports a peer's connection states as they change, and the addresses ICE settles on: where a join that never finishes stopped. A peer that ends before it connects is reported with how far ICE got, which tells an answer the client could not reach from a handshake that stalled after the two sides found each other.

Parameters ​

peer ​

DriverPeer

The peer.

log ​

(line, failed) => void

Where each change goes, as one line. failed marks the line for a peer that ended before it connected, which is worth a warning; the rest is detail for debugging.

Returns ​

void

verifiesDetachedEs384() ​

verifiesDetachedEs384(jws, payload, publicKey): Promise<boolean>

Defined in: packages/nethernet/src/es384.ts:44

Whether jws is a detached ES384 signature over payload by publicKey.

Parameters ​

jws ​

string

The detached JWS, header..signature.

payload ​

string

The payload bytes the signer should have signed.

publicKey ​

KeyObject

The P-384 key it should verify against.

Returns ​

Promise<boolean>

verifySelfSignedIdentity() ​

verifySelfSignedIdentity(description, nowMs?): Promise<VerifiedIdentity>

Defined in: packages/nethernet/src/NetherNetIdentity.ts:218

Checks a self-signed a=identity the way a NetherNet client checks a server's: the token is signed by the key in its own cpk claim and not expired, and the detached signature covers this description's fingerprints. Offline clients sign their offers the same way; an online client's token is signed by the authorization service instead, which this does not check.

Parameters ​

description ​

string

The SDP description carrying a=identity.

nowMs? ​

number = ...

The clock, in milliseconds since the epoch.

Returns ​

Promise<VerifiedIdentity>

Throws ​

When the identity is missing, malformed, expired or does not verify.

withAdvertisedCandidates() ​

withAdvertisedCandidates(answer, ports, dialed?, fallbackPublicIp?): string

Defined in: packages/nethernet/src/udpPorts.ts:372

The answer with every address the server offers: the mapped and public candidates server-udp-ports and server-public-ip give, then the address the client dialed. When that leaves no candidate a host elsewhere on the internet can send to, a fallback public address, such as one looked up at startup, is added beside them: after each host of its family, on the public port a mapping gives the host's port, else on the host's own port.

Parameters ​

answer ​

string

The SDP answer, with its host candidates.

ports ​

Pick<UdpPorts, "mappings" | "publicIp">

What server-udp-ports and server-public-ip say.

dialed? ​

DialedAddress

Where the client sent its offer, when the request said.

fallbackPublicIp? ​

string

The address to offer when the answer would carry no public one.

Returns ​

string

The answer.

withDialedCandidates() ​

withDialedCandidates(answer, dialed, mappings?): string

Defined in: packages/nethernet/src/udpPorts.ts:311

The answer with the address the client dialed added as a server-reflexive candidate, when the answer does not list it already. The client reached signaling there, so behind NAT, port forwarding or a container network it is the one address known to lead to this server, and the server's own interface addresses do not. Each host candidate of the address's family gets one: on the public port a mapping gives its local port, else on the dialed port when its local port is the one signaling listens on, as with the default of one port for both, else on its own port. The client names the address and only that client receives the answer, so a false one costs it a candidate that goes nowhere.

Parameters ​

answer ​

string

The SDP answer, with its candidates and any mapped ones.

dialed ​

DialedAddress | undefined

Where the client sent its offer, when the request said.

mappings? ​

readonly PortMapping[] = []

The mappings server-udp-ports declares.

Returns ​

string

The answer.

withMappedCandidates() ​

withMappedCandidates(answer, mappings, publicIp?): string

Defined in: packages/nethernet/src/udpPorts.ts:259

The answer with a server-reflexive candidate after each host candidate that clients outside the network reach another way, as Bedrock Dedicated Server 1.26.70.24 answers: for a host on a mapped local port, the public port it maps to; at the public address when there is one and the host is of its family, else at the host's own address. With a public address and no mapping for the port, the public port is the local one. A host of the other family than the public address gets nothing added, and its related address and port name the host.

Parameters ​

answer ​

string

The SDP answer, with its candidates.

mappings ​

readonly PortMapping[]

The mappings to advertise.

publicIp? ​

string

The public address, when there is one.

Returns ​

string

The answer.

withRewrittenCandidates() ​

withRewrittenCandidates(sdp, map): Promise<string>

Defined in: packages/nethernet/src/sdp.ts:67

The description with each UDP candidate's address and port replaced, or the candidate dropped.

Parameters ​

sdp ​

string

The session description.

map ​

(address, port) => Promise<{ address: string; port: number; } | undefined>

Gives the new address for a candidate's address, or undefined to drop it.

Returns ​

Promise<string>

The rewritten description.

withSessionAttribute() ​

withSessionAttribute(sdp, attribute): string

Defined in: packages/nethernet/src/sdp.ts:43

The description with one session-level attribute added: after every other session-level line and before the first media section, which is where NetherNet expects a=identity.

Parameters ​

sdp ​

string

The session description.

attribute ​

string

The attribute line, such as a=identity:….

Returns ​

string

withoutCandidates() ​

withoutCandidates(sdp): string

Defined in: packages/nethernet/src/sdp.ts:58

The description with every candidate removed, so the other side learns this one's address only from where its checks come from.

Parameters ​

sdp ​

string

The session description.

Returns ​

string

withoutIdentity() ​

withoutIdentity(sdp): string

Defined in: packages/nethernet/src/sdp.ts:34

The description with every a=identity line removed. The identity is NetherNet's, checked before the description reaches WebRTC, which does not know the attribute.

Parameters ​

sdp ​

string

The session description.

Returns ​

string