Network

Multi-protocol network communication helpers for HTTP requests, TCP/TLS sockets, and UDP datagrams with scoped logging, auto-reconnect, and client authentication support.

Quick Reference

Class	Extends	Protocol	Type
`AxiosNetworkRequest`	`BaseNetworkRequest<'axios'>`	HTTP/HTTPS	Client
`NodeFetchNetworkRequest`	`BaseNetworkRequest<'node-fetch'>`	HTTP/HTTPS	Client
`NetworkTcpClient`	`BaseNetworkTcpClient`	TCP	Client
`NetworkTcpServer`	`BaseNetworkTcpServer`	TCP	Server
`NetworkTlsTcpClient`	`BaseNetworkTcpClient`	TLS/SSL	Client
`NetworkTlsTcpServer`	`BaseNetworkTcpServer`	TLS/SSL	Server
`NetworkUdpClient`	`BaseHelper`	UDP	Client

Import Paths

typescript

// Main package -- TCP, UDP, and Node Fetch
import {
  NodeFetchNetworkRequest,
  BaseNetworkRequest,
  NetworkTcpClient,
  NetworkTcpServer,
  NetworkTlsTcpClient,
  NetworkTlsTcpServer,
  BaseNetworkTcpClient,
  BaseNetworkTcpServer,
  NetworkUdpClient,
} from '@venizia/ignis-helpers';

// Axios (separate export -- optional peer dependency)
import {
  AxiosNetworkRequest,
  AxiosFetcher,
  type IAxiosNetworkRequestOptions,
  type IAxiosRequestOptions,
} from '@venizia/ignis-helpers/axios';

// Types
import type {
  INodeFetchNetworkRequestOptions,
  INodeFetchRequestOptions,
  INetworkTcpClientProps,
  ITcpSocketServerOptions,
  ITcpSocketClient,
  IRequestOptions,
  IFetchable,
  TFetcherVariant,
} from '@venizia/ignis-helpers';

Creating an Instance

HTTP Request

HTTP helpers follow a two-layer design: a BaseNetworkRequest that holds the base URL and delegates to an underlying IFetchable fetcher (either Axios or native fetch). You typically extend one of the concrete classes to create a typed API client.

Axios

typescript

import { AxiosNetworkRequest } from '@venizia/ignis-helpers/axios';

class PaymentGateway extends AxiosNetworkRequest {
  constructor() {
    super({
      name: 'PaymentGateway',
      networkOptions: {
        baseUrl: 'https://api.payments.com',
        timeout: 30000,
        headers: {
          'X-API-Key': process.env.PAYMENT_API_KEY,
        },
      },
    });
  }
}

`IAxiosNetworkRequestOptions`

Option	Type	Default	Description
`name`	`string`	--	Helper name, used for scoped logging
`networkOptions.baseUrl`	`string`	`undefined`	Base URL prepended to all request paths
`networkOptions.timeout`	`number`	`60000`	Request timeout in milliseconds
`networkOptions.headers`	`object`	`{ 'content-type': 'application/json; charset=utf-8' }`	Default headers; your values override the default content-type
`networkOptions.*`	`AxiosRequestConfig`	--	All other Axios config options are accepted

TIP

AxiosNetworkRequest sets sensible defaults: Content-Type: application/json, withCredentials: true, validateStatus: status < 500, and timeout: 60000 (1 minute). Your options override these defaults.

Node.js Fetch

typescript

import { NodeFetchNetworkRequest } from '@venizia/ignis-helpers';

class MyApiClient extends NodeFetchNetworkRequest {
  constructor() {
    super({
      name: 'MyApiClient',
      networkOptions: {
        baseUrl: 'https://api.example.com',
        headers: {
          'Authorization': 'Bearer my-token',
        },
        credentials: 'include',
        mode: 'cors',
      },
    });
  }
}

`INodeFetchNetworkRequestOptions`

Option	Type	Default	Description
`name`	`string`	--	Helper name, used for scoped logging
`networkOptions.baseUrl`	`string`	`undefined`	Base URL prepended to all request paths
`networkOptions.headers`	`HeadersInit`	`{ 'content-type': 'application/json; charset=utf-8' }`	Default headers; supports `Headers` object or plain object
`networkOptions.*`	`RequestInit`	--	All other `fetch` options are accepted

TCP Client / Server

TCP Client

typescript

import { NetworkTcpClient } from '@venizia/ignis-helpers';

const tcpClient = new NetworkTcpClient({
  identifier: 'sensor-reader',
  options: {
    host: 'localhost',
    port: 8080,
  },
  reconnect: true,
  maxRetry: 10,
  encoding: 'utf8',
  onConnected: ({ client }) => { console.log('Connected'); },
  onData: ({ identifier, message }) => { console.log('Data:', message.toString()); },
  onClosed: ({ client }) => { console.log('Closed'); },
  onError: (error) => { console.error('Error:', error); },
});

TCP Client Options (`INetworkTcpClientProps`)

Option	Type	Default	Description
`identifier`	`string`	--	Unique client identifier for logging
`scope`	`string`	`identifier`	Logger scope name
`options`	`TcpSocketConnectOpts`	--	Node.js `net.connect` options (`host`, `port`, etc.)
`reconnect`	`boolean`	`false`	Enable automatic reconnection on error
`maxRetry`	`number`	`5`	Maximum reconnection attempts
`encoding`	`BufferEncoding`	`undefined`	Socket encoding (e.g., `'utf8'`)
`onConnected`	`(opts: { client }) => void`	Internal logger	Called when connection is established
`onData`	`(opts: { identifier, message }) => void`	No-op	Called when data is received
`onClosed`	`(opts: { client }) => void`	Internal logger	Called when connection closes
`onError`	`(error: any) => void`	Internal handler with auto-reconnect	Called on connection errors

TCP Server

typescript

import { NetworkTcpServer } from '@venizia/ignis-helpers';

const tcpServer = new NetworkTcpServer({
  identifier: 'my-tcp-server',
  serverOptions: {},
  listenOptions: { port: 8080, host: '0.0.0.0' },
  authenticateOptions: { required: true, duration: 5000 },
  onServerReady: ({ server }) => { console.log('Listening'); },
  onClientConnected: ({ id, socket }) => { console.log(`Client ${id} connected`); },
  onClientData: ({ id, socket, data }) => { console.log(`Data from ${id}:`, data.toString()); },
  onClientClose: ({ id, socket }) => { console.log(`Client ${id} disconnected`); },
  onClientError: ({ id, socket, error }) => { console.error(`Error from ${id}:`, error); },
});

IMPORTANT

When authenticateOptions.required is true, you must provide a positive duration value. Clients that do not authenticate within this duration are automatically disconnected with an "Unauthorized Client" message. Use doAuthenticate() in your onClientData handler to transition the client's state.

TCP Server Options (`ITcpSocketServerOptions`)

Option	Type	Default	Description
`identifier`	`string`	--	Server identifier for logging
`scope`	`string`	`identifier`	Logger scope name
`serverOptions`	`Partial<ServerOpts>`	--	Node.js `net.Server` options
`listenOptions`	`Partial<ListenOptions>`	--	Listen options (`port`, `host`, `backlog`, etc.)
`authenticateOptions.required`	`boolean`	--	Whether clients must authenticate
`authenticateOptions.duration`	`number`	`undefined`	Auth timeout in ms (required when `required: true`)
`extraEvents`	`Record<string, (opts) => void>`	`{}`	Additional socket events to register per client
`onServerReady`	`(opts: { server }) => void`	`undefined`	Called when server starts listening
`onClientConnected`	`(opts: { id, socket }) => void`	`undefined`	Called on new client connection
`onClientData`	`(opts: { id, socket, data }) => void`	`undefined`	Called when data is received from a client
`onClientClose`	`(opts: { id, socket }) => void`	`undefined`	Called when a client disconnects
`onClientError`	`(opts: { id, socket, error }) => void`	`undefined`	Called on client socket error

TLS Client / Server

TLS variants are identical to their TCP counterparts but use node:tls under the hood for encrypted connections. The constructor options accept TLS-specific fields (cert, key, ca, rejectUnauthorized, etc.) in addition to all the same handler options.

TLS Client

typescript

import { NetworkTlsTcpClient } from '@venizia/ignis-helpers';
import fs from 'node:fs';

const tlsClient = new NetworkTlsTcpClient({
  identifier: 'secure-client',
  options: {
    host: 'secure.example.com',
    port: 8443,
    rejectUnauthorized: true,
    ca: fs.readFileSync('ca.crt'),
    cert: fs.readFileSync('client.crt'),
    key: fs.readFileSync('client.key'),
  },
  reconnect: true,
  maxRetry: 3,
  onData: ({ message }) => { console.log('Secure data:', message); },
});

tlsClient.connect({ resetReconnectCounter: true });

NOTE

NetworkTlsTcpClient accepts ConnectionOptions from node:tls in the options field. All other options (reconnect, maxRetry, callbacks) are identical to NetworkTcpClient.

TLS Server

typescript

import { NetworkTlsTcpServer } from '@venizia/ignis-helpers';
import fs from 'node:fs';

const tlsServer = new NetworkTlsTcpServer({
  identifier: 'secure-tcp-server',
  serverOptions: {
    cert: fs.readFileSync('server.crt'),
    key: fs.readFileSync('server.key'),
    ca: [fs.readFileSync('ca.crt')],
    requestCert: true,
  },
  listenOptions: { port: 8443, host: '0.0.0.0' },
  authenticateOptions: { required: false },
  onClientData: ({ id, data }) => { console.log(`Secure data from ${id}:`, data.toString()); },
});

NOTE

NetworkTlsTcpServer accepts TlsOptions from node:tls in serverOptions. All handlers and methods are identical to NetworkTcpServer.

UDP Client

typescript

import { NetworkUdpClient } from '@venizia/ignis-helpers';

const udpClient = NetworkUdpClient.newInstance({
  identifier: 'my-udp-client',
  port: 8081,
  host: '0.0.0.0',
  reuseAddr: true,
  multicastAddress: {
    groups: ['239.1.2.3'],
    interface: '0.0.0.0',
  },
  onData: ({ message, remoteInfo }) => {
    console.log(`From ${remoteInfo.address}:${remoteInfo.port}:`, message.toString());
  },
  onBind: async ({ socket, multicastAddress }) => {
    if (multicastAddress?.groups) {
      for (const group of multicastAddress.groups) {
        socket.addMembership(group, multicastAddress.interface);
      }
    }
  },
});

UDP Client Options (`INetworkUdpClientProps`)

Option	Type	Default	Description
`identifier`	`string`	--	Unique client identifier for logging
`host`	`string`	`undefined`	Bind address
`port`	`number`	--	Bind port
`reuseAddr`	`boolean`	`undefined`	Allow address reuse (`SO_REUSEADDR`)
`multicastAddress.groups`	`string[]`	`undefined`	Multicast group addresses to join
`multicastAddress.interface`	`string`	`undefined`	Network interface for multicast
`onConnected`	`(opts: { identifier, host?, port }) => void`	Internal logger	Called when socket starts listening
`onData`	`(opts: { identifier, message, remoteInfo }) => void`	Internal logger	Called when data is received
`onClosed`	`(opts: { identifier, host?, port }) => void`	Internal logger	Called when socket is closed
`onError`	`(opts: { identifier, host?, port, error }) => void`	Internal logger	Called on socket error
`onBind`	`(opts: { identifier, socket, host?, port, reuseAddr?, multicastAddress? }) => void`	`undefined`	Called after socket is bound; use to join multicast groups

Usage

HTTP Requests

Access the underlying fetcher via getNetworkService(), then use send() or the convenience methods (get, post, put, patch, delete):

typescript

class PaymentGateway extends AxiosNetworkRequest {
  constructor() {
    super({
      name: 'PaymentGateway',
      networkOptions: {
        baseUrl: process.env.PAYMENT_API_URL,
        timeout: 30000,
        headers: { 'X-API-Key': process.env.PAYMENT_API_KEY },
      },
    });
  }

  async charge(amount: number, currency: string) {
    const url = this.getRequestUrl({ paths: ['v1', 'charges'] });
    const response = await this.getNetworkService().send({
      url,
      method: 'post',
      body: { amount, currency },
    });
    this.logger.for('charge').info('Payment processed: %s', response.data.id);
    return response.data;
  }

  async getTransaction(id: string) {
    const url = this.getRequestUrl({ paths: ['v1', 'transactions', id] });
    return this.getNetworkService().get({ url });
  }
}

Convenience Methods

typescript

const fetcher = this.getNetworkService();

// These are equivalent:
await fetcher.send({ url: '/users', method: 'get' });
await fetcher.get({ url: '/users' });

// POST with body
await fetcher.post({ url: '/users', body: { name: 'Alice' } });

// All methods: get(), post(), put(), patch(), delete()

HTTPS with Axios

For HTTPS requests, the AxiosFetcher automatically creates an https.Agent. By default, rejectUnauthorized is false. Override it per request:

typescript

await fetcher.send({
  url: 'https://strict-api.example.com/data',
  method: 'get',
  rejectUnauthorized: true,
});

Timeout with Node Fetch

The NodeFetcher implements timeout via AbortController. Pass timeout in each send() call:

typescript

await fetcher.send({
  url: '/slow-endpoint',
  method: 'get',
  timeout: 5000, // Aborts after 5 seconds
});

TCP Communication

typescript

import { NetworkTcpClient, NetworkTcpServer } from '@venizia/ignis-helpers';

// --- Server ---
const server = new NetworkTcpServer({
  identifier: 'echo-server',
  serverOptions: {},
  listenOptions: { port: 9000, host: '0.0.0.0' },
  authenticateOptions: { required: false },
  onClientData: ({ id, data }) => {
    // Echo back to the sender
    server.emit({ clientId: id, payload: data });
  },
});

// --- Client ---
const client = new NetworkTcpClient({
  identifier: 'echo-client',
  options: { host: 'localhost', port: 9000 },
  reconnect: true,
  maxRetry: 5,
  encoding: 'utf8',
  onData: ({ message }) => { console.log('Echo:', message); },
});

client.connect({ resetReconnectCounter: true });
client.emit({ payload: 'Hello, Server!' });

Server with Authentication Flow

typescript

const server = new NetworkTcpServer({
  identifier: 'auth-tcp-server',
  serverOptions: {},
  listenOptions: { port: 9000, host: '0.0.0.0' },
  authenticateOptions: { required: true, duration: 5000 },

  onClientData: ({ id, data }) => {
    const message = data.toString();
    const client = server.getClient({ id });

    if (client?.state === 'unauthorized') {
      if (message === 'secret-token') {
        server.doAuthenticate({ id, state: 'authenticated' });
        server.emit({ clientId: id, payload: 'Authenticated!' });
      } else {
        server.emit({ clientId: id, payload: 'Invalid credentials' });
      }
      return;
    }

    // Handle authenticated client messages
    console.log(`[${id}] ${message}`);
  },
});

Client State Tracking

Each connected client is tracked as an ITcpSocketClient:

typescript

interface ITcpSocketClient<SocketClientType> {
  id: string;
  socket: SocketClientType;
  state: 'unauthorized' | 'authenticating' | 'authenticated';
  subscriptions: Set<string>;
  storage: {
    connectedAt: dayjs.Dayjs;
    authenticatedAt: dayjs.Dayjs | null;
    [additionField: symbol | string]: any; // Extensible storage
  };
}

TLS Encrypted Communication

TLS classes share the same API as their TCP counterparts. Provide TLS certificates in the options or serverOptions field:

typescript

import { NetworkTlsTcpServer, NetworkTlsTcpClient } from '@venizia/ignis-helpers';
import fs from 'node:fs';

// --- TLS Server ---
const tlsServer = new NetworkTlsTcpServer({
  identifier: 'secure-server',
  serverOptions: {
    cert: fs.readFileSync('server.crt'),
    key: fs.readFileSync('server.key'),
    ca: [fs.readFileSync('ca.crt')],
    requestCert: true,
  },
  listenOptions: { port: 8443, host: '0.0.0.0' },
  authenticateOptions: { required: false },
  onClientData: ({ id, data }) => {
    console.log(`Secure data from ${id}:`, data.toString());
  },
});

// --- TLS Client ---
const tlsClient = new NetworkTlsTcpClient({
  identifier: 'secure-client',
  options: {
    host: 'localhost',
    port: 8443,
    rejectUnauthorized: true,
    ca: fs.readFileSync('ca.crt'),
    cert: fs.readFileSync('client.crt'),
    key: fs.readFileSync('client.key'),
  },
  onData: ({ message }) => { console.log('Secure:', message); },
});

tlsClient.connect({ resetReconnectCounter: true });
tlsClient.emit({ payload: 'Hello over TLS!' });

UDP Communication

typescript

import { NetworkUdpClient } from '@venizia/ignis-helpers';

const udpClient = NetworkUdpClient.newInstance({
  identifier: 'multicast-listener',
  port: 5000,
  host: '0.0.0.0',
  reuseAddr: true,
  multicastAddress: {
    groups: ['239.1.2.3'],
    interface: '0.0.0.0',
  },
  onData: ({ message, remoteInfo }) => {
    console.log(`From ${remoteInfo.address}:${remoteInfo.port}:`, message.toString());
  },
  onBind: async ({ socket, multicastAddress }) => {
    // Join multicast groups after socket is bound
    if (multicastAddress?.groups) {
      for (const group of multicastAddress.groups) {
        socket.addMembership(group, multicastAddress.interface);
      }
    }
  },
});

// Start listening
udpClient.connect();

// Access the underlying dgram.Socket
const socket = udpClient.getClient();

// Check if bound
if (udpClient.isConnected()) {
  // Send a datagram via the raw socket
  socket.send('Hello', 5001, '239.1.2.3');
}

// Stop listening
udpClient.disconnect();

Troubleshooting

HTTP: "[getRequestUrl] Invalid configuration for third party request base url!"

Cause: getRequestUrl() was called but no baseUrl was provided at construction time or in the call's opts.baseUrl parameter.

Fix: Provide a baseUrl either in the constructor's networkOptions or pass it in the opts parameter of getRequestUrl():

typescript

// At construction
const client = new AxiosNetworkRequest({
  name: 'MyClient',
  networkOptions: { baseUrl: 'https://api.example.com' },
});

// Or per call
const url = client.getRequestUrl({
  baseUrl: 'https://api.example.com',
  paths: ['v1', 'users'],
});

HTTP: Timeout not working with NodeFetchNetworkRequest

Cause: The timeout option on the constructor's networkOptions is not automatically applied to individual requests. Timeout must be set per-request.

Fix: Pass timeout in each send() call:

typescript

await this.getNetworkService().send({
  url: '/slow-endpoint',
  method: 'get',
  timeout: 5000,
});

The NodeFetcher internally creates an AbortController and aborts the request after the specified timeout.

TCP Server: "Invalid authenticate duration"

Cause: authenticateOptions.required is true but duration is missing, zero, or negative.

Fix: Provide a positive duration value when authentication is required:

typescript

// Correct
authenticateOptions: { required: true, duration: 5000 }

// Wrong -- throws at construction time
authenticateOptions: { required: true }
authenticateOptions: { required: true, duration: -1 }

TCP Client: Reconnect loop never stops

Cause: maxRetry is set to -1 (infinite retries) and the target server is unreachable. The reconnect delay is fixed at 5 seconds between attempts.

Fix: Use a finite maxRetry value, or set reconnect: false if you handle reconnection externally:

typescript

const client = new NetworkTcpClient({
  identifier: 'my-client',
  options: { host: 'localhost', port: 8080 },
  reconnect: true,
  maxRetry: 5, // Stop after 5 attempts
});

TCP Server: Client emit does nothing

Cause: The target client socket is not writable (already closed or half-closed), or the payload is empty. The server logs a warning but does not throw.

Fix: Check the client state before emitting:

typescript

const client = server.getClient({ id: clientId });
if (client && client.socket.writable) {
  server.emit({ clientId, payload: 'Hello' });
}

Network ​

Quick Reference ​

Import Paths ​

Creating an Instance ​

HTTP Request ​

Axios ​

IAxiosNetworkRequestOptions ​

Node.js Fetch ​

INodeFetchNetworkRequestOptions ​

TCP Client / Server ​

TCP Client ​

TCP Client Options (INetworkTcpClientProps) ​

TCP Server ​

TCP Server Options (ITcpSocketServerOptions) ​

TLS Client / Server ​

TLS Client ​

TLS Server ​

UDP Client ​

UDP Client Options (INetworkUdpClientProps) ​

Usage ​

HTTP Requests ​

Convenience Methods ​

HTTPS with Axios ​

Timeout with Node Fetch ​

TCP Communication ​

Server with Authentication Flow ​

Client State Tracking ​

TLS Encrypted Communication ​

UDP Communication ​

Troubleshooting ​

HTTP: "[getRequestUrl] Invalid configuration for third party request base url!" ​

HTTP: Timeout not working with NodeFetchNetworkRequest ​

TCP Server: "Invalid authenticate duration" ​

TCP Client: Reconnect loop never stops ​

TCP Server: Client emit does nothing ​

See Also ​

Network

Quick Reference

Import Paths

Creating an Instance

HTTP Request

Axios

`IAxiosNetworkRequestOptions`

Node.js Fetch

`INodeFetchNetworkRequestOptions`

TCP Client / Server

TCP Client

TCP Client Options (`INetworkTcpClientProps`)

TCP Server

TCP Server Options (`ITcpSocketServerOptions`)

TLS Client / Server

TLS Client

TLS Server

UDP Client

UDP Client Options (`INetworkUdpClientProps`)

Usage

HTTP Requests

Convenience Methods

HTTPS with Axios

Timeout with Node Fetch

TCP Communication

Server with Authentication Flow

Client State Tracking

TLS Encrypted Communication

UDP Communication

Troubleshooting

HTTP: "[getRequestUrl] Invalid configuration for third party request base url!"

HTTP: Timeout not working with NodeFetchNetworkRequest

TCP Server: "Invalid authenticate duration"

TCP Client: Reconnect loop never stops

TCP Server: Client emit does nothing

See Also