@venizia/ignis-docs 0.0.5 → 0.0.6-0

package/wiki/references/helpers/network/index.md

@@ -0,0 +1,620 @@
+# 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' });
+}
+```
+
+## See Also
+
+- [API Reference](./api) -- Full method signatures and types