module net

Supported only in the v8 engine. Introduced in Max v9.2.0.

The net module exposed by require("net") providing TCP client and server sockets.

This is a minimal net subset, not full Node parity.

In addition to TCP, the module supports IPC (inter-process) stream sockets via a path endpoint passed to net.connect / net.Server.listen. IPC is available on all platforms: on macOS and Linux it uses Unix domain sockets and on Windows it uses Win32 named pipes. See net.ConnectOptions.path for the per-platform path conventions and behavioral differences.

Examples

const net = require("net");
const socket = net.createConnection(7000, "127.0.0.1");
socket.on("connect", () => socket.write("hello\n"));
socket.on("data", (chunk) => post(chunk.toString("utf8"), "\n"));
socket.on("error", (error) => post(error.message, "\n"));

An IPC server and client over a local path. Use a Unix domain socket path on macOS/Linux, or a \\.\pipe\ name on Windows.

const net = require("net");
const PIPE = "/tmp/max-v8.sock"; // Windows: "\\\\.\\pipe\\max-v8"

const server = net.createServer((conn) => {
  conn.on("data", (chunk) => conn.write(chunk)); // echo
});
server.on("error", (error) => post(error.code, error.message, "\n"));
server.listen({ path: PIPE }, () => {
  const client = net.connect({ path: PIPE });
  client.on("connect", () => client.write("hello-ipc"));
  client.on("data", (chunk) => post(chunk.toString("utf8"), "\n"));
});

Index

Functions

• connect(port, host, callback)
• connect(options, callback)
• createConnection(port, host, callback)
• createConnection(options, callback)
• createServer(connectionListener)

Classes

• Server
• Socket

Interfaces

• ConnectOptions
• ListenOptions

function connect

Creates a net.Socket and connects to a TCP host/port.

function connect(port: number, host?: string, callback?: () => void): Socket;

function connect

Creates a net.Socket and connects using an options object.

function connect(options: ConnectOptions, callback?: () => void): Socket;

interface ConnectOptions

Options for net.Socket.connect / net.connect.

Properties

• host
• path
• port
• writableHighWaterMark

host string

path string

Connect to an IPC endpoint instead of a TCP host/port. Mutually exclusive with host/port — supplying both throws.

The path is interpreted per platform: - macOS / Linux: a Unix domain socket filesystem path (e.g. "/tmp/max-v8.sock"). - Windows: a Win32 named-pipe name, passed verbatim to the OS, so it must be a valid pipe name such as "\\\\.\\pipe\\max-v8" (matching Node's requirement; in a JS string literal each backslash is escaped).

A connect that finds no listener fails with an error event: ENOENT (no such endpoint), EACCES (permission denied), or, on Windows, EBUSY (all pipe instances busy).

port number

writableHighWaterMark number

Byte threshold at which write() starts returning false (default 65536).

function createConnection

Alias of net.connect.

function createConnection(
  port: number,
  host?: string,
  callback?: () => void,
): Socket;

function createConnection

Alias of net.connect.

function createConnection(
  options: ConnectOptions,
  callback?: () => void,
): Socket;

function createServer

Creates a net.Server.

function createServer(connectionListener?: (socket: Socket) => void): Server;

interface ListenOptions

Options for net.Server.listen.

Properties

• host
• path
• port
• writableHighWaterMark

host string

path string

Bind an IPC endpoint instead of a TCP host/port listener. See net.ConnectOptions.path for the per-platform path conventions. Listening on a name that is already bound fails with an error event whose code is EADDRINUSE.

port number

writableHighWaterMark number

Applied as net.ConnectOptions.writableHighWaterMark to accepted sockets.

class Server

A TCP (or IPC) server. Accepted connection sockets are delivered as net.Socket instances.

Events: listening, connection, close, error.

Properties

• listening

Methods

• address()
• close(callback)
• listen(port, host, callback)
• listen(options, callback)
• off(event, listener)
• on(event, listener)
• once(event, listener)

address()

Returns the bound local endpoint after listening.

address(): AddressInfo;

close(callback)

Stops the server.

close(callback?: () => void): this;

listen(port, host, callback)

Begins listening on a TCP host/port.

listen(port: number, host?: string, callback?: () => void): this;

listen(options, callback)

Begins listening using an options object (host/port or IPC path).

listen(options: ListenOptions, callback?: () => void): this;

listening boolean read-only

Whether the server is currently listening.

off(event, listener)

Removes an event listener.

off(event: string, listener: (...args: any[]) => void): this;

on(event, listener)

Registers an event listener.

on(event: string, listener: (...args: any[]) => void): this;

once(event, listener)

Registers a one-shot event listener.

once(event: string, listener: (...args: any[]) => void): this;

class Socket

A TCP (or IPC) stream socket.

Incoming data arrives as buffer.IOBuffer. write() returns a boolean and a drain event fires when the outbound queue falls below the high-water mark. Events: connect, data, drain, close, error.

The same class is used for TCP and IPC connections; the only IPC-specific behavior is around net.Socket.end() (half-close) — see that method.

Properties

• destroyed
• localAddress
• localPort
• remoteAddress
• remotePort

Methods

• address()
• connect(port, host, callback)
• connect(options, callback)
• destroy()
• end(chunk, encoding, callback)
• off(event, listener)
• on(event, listener)
• once(event, listener)
• pause()
• resume()
• write(chunk, encoding, callback)

address()

Returns the local endpoint once connected.

address(): AddressInfo;

connect(port, host, callback)

Connects to a TCP host/port.

connect(port: number, host?: string, callback?: () => void): this;

connect(options, callback)

Connects using an options object (TCP host/port or IPC path).

connect(options: ConnectOptions, callback?: () => void): this;

destroy()

Destroys the socket.

destroy(): void;

destroyed boolean read-only

Whether the socket has been destroyed.

end(chunk, encoding, callback)

Sends an optional final chunk and half-closes the writable side.

On TCP and on POSIX IPC sockets this performs a true half-close: the peer sees EOF immediately while this socket's readable side stays open to receive a reply. Windows named pipes have no half-duplex shutdown, so end() flushes pending writes but keeps the handle open; the read side stays alive (a reply sent after end() is still received) and the peer sees EOF only on a full net.Socket.destroy().

end(
  chunk?: string | buffer.IOBuffer | ArrayBufferView,
  encoding?: string,
  callback?: () => void,
): void;

localAddress string read-only

localPort number read-only

off(event, listener)

Removes an event listener.

off(event: string, listener: (...args: any[]) => void): this;

on(event, listener)

Registers an event listener.

on(event: string, listener: (...args: any[]) => void): this;

once(event, listener)

Registers a one-shot event listener.

once(event: string, listener: (...args: any[]) => void): this;

pause()

Pauses delivery of data events (single pending chunk).

pause(): void;

remoteAddress string read-only

remotePort number read-only

resume()

Resumes delivery of data events.

resume(): void;

write(chunk, encoding, callback)

Queues data to send.

write(
  chunk: string | buffer.IOBuffer | ArrayBufferView,
  encoding?: string,
  callback?: () => void,
): boolean;