v4.14.3

.smartconfig.json

@@ -11,26 +11,26 @@
       "githost": "code.foss.global",
       "gitscope": "serve.zone",
       "gitrepo": "remoteingress",
-      "description": "Provides a service for creating private tunnels and reaching private clusters from the outside, facilitating secure remote access as part of the @serve.zone stack.",
+      "description": "Edge ingress tunnel for DcRouter - tunnels TCP and UDP traffic from the network edge to SmartProxy over TLS or QUIC, preserving client IP via PROXY protocol.",
       "npmPackagename": "@serve.zone/remoteingress",
       "license": "MIT",
       "projectDomain": "serve.zone",
       "keywords": [
         "remote access",
-        "private tunnels",
+        "ingress tunnel",
-        "network security",
+        "network edge",
-        "TLS encryption",
+        "PROXY protocol",
-        "connector",
+        "multiplexed tunnel",
+        "TCP proxy",
+        "TLS tunnel",
+        "QUIC transport",
+        "UDP tunneling",
         "serve.zone stack",
-        "private clusters access",
+        "TypeScript",
-        "public access management",
+        "Rust",
-        "TypeScript application",
+        "SmartProxy",
-        "node.js package",
+        "DcRouter",
-        "secure communications",
+        "flow control"
-        "TLS/SSL certificates",
-        "development tools",
-        "software development",
-        "private network integration"
       ]
     },
     "release": {

changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2026-03-26 - 4.14.3 - fix(docs)
+refresh project metadata and README to reflect current ingress tunnel capabilities
+
+- update package metadata description and keywords to better describe edge ingress, TLS/QUIC transport, and SmartProxy integration
+- revise README terminology, API docs, and feature list to document crash recovery, bindAddress support, and current event names
+- improve README formatting and examples for architecture, wire protocol, QoS, and token usage
+
 ## 2026-03-26 - 4.14.2 - fix(hub-core)
 improve stream shutdown handling and connection cleanup in hub and edge
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/remoteingress",
-  "version": "4.14.2",
+  "version": "4.14.3",
   "private": false,
   "description": "Edge ingress tunnel for DcRouter - tunnels TCP and UDP traffic from the network edge to SmartProxy over TLS or QUIC, preserving client IP via PROXY protocol.",
   "main": "dist_ts/index.js",

readme.md

@@ -12,23 +12,24 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 pnpm install @serve.zone/remoteingress
 ```
 
-## 🏗️ Architecture
+## Architecture
 
 `@serve.zone/remoteingress` uses a **Hub/Edge** topology with a high-performance Rust core and a TypeScript API surface:
 
 ```
-┌─────────────────────┐      TLS or QUIC Tunnel       ┌─────────────────────┐
+                                   TLS or QUIC Tunnel
-│   Network Edge      │  ◄══════════════════════════►  │   Private Cluster   │
+┌─────────────────────┐  ◄══════════════════════════►  ┌─────────────────────┐
-│                     │   TCP+TLS: frame mux           │                     │
+│   Network Edge      │   TCP+TLS: frame mux           │   Private Cluster   │
-│  RemoteIngressEdge  │   QUIC:    native streams      │  RemoteIngressHub   │
+│                     │   QUIC:    native streams       │                     │
-│                     │   UDP:     QUIC datagrams       │                     │
+│  RemoteIngressEdge  │   UDP:     QUIC datagrams       │  RemoteIngressHub   │
-│  Accepts TCP & UDP  │                                │  Forwards to        │
+│                     │                                 │                     │
-│  on hub-assigned    │                                │  SmartProxy on      │
+│  Accepts TCP & UDP  │                                 │  Forwards to        │
-│  ports              │                                │  local ports        │
+│  on hub-assigned    │                                 │  SmartProxy on      │
-└─────────────────────┘                                └─────────────────────┘
+│  ports              │                                 │  local ports        │
-        ▲                                                       │
+└─────────────────────┘                                 └─────────────────────┘
-        │  TCP + UDP from end users                             ▼
+        ▲                                                        │
-   Internet                                             DcRouter / SmartProxy
+        │  TCP + UDP from end users                              ▼
+   Internet                                              DcRouter / SmartProxy
 ```
 
 | Component | Role |
@@ -37,24 +38,25 @@ pnpm install @serve.zone/remoteingress
 | **RemoteIngressHub** | Deployed alongside DcRouter/SmartProxy in a private cluster. Accepts edge connections, demuxes streams/datagrams, and forwards each to SmartProxy with PROXY protocol headers so the real client IP is preserved. |
 | **Rust Binary** (`remoteingress-bin`) | The performance-critical networking core. Managed via `@push.rocks/smartrust` RustBridge IPC — you never interact with it directly. Cross-compiled for `linux/amd64` and `linux/arm64`. |
 
-### ✨ Key Features
+### Key Features
 
-- 🔒 **Dual transport** — choose between TCP+TLS (frame-multiplexed) or QUIC (native stream multiplexing, zero head-of-line blocking)
+- **Dual transport** — choose between TCP+TLS (frame-multiplexed) or QUIC (native stream multiplexing, zero head-of-line blocking)
-- 🌐 **TCP + UDP tunneling** — tunnel any TCP connection or UDP datagram through the same edge/hub pair
+- **TCP + UDP tunneling** — tunnel any TCP connection or UDP datagram through the same edge/hub pair
-- 📋 **PROXY protocol v1 & v2** — SmartProxy sees the real client IP for both TCP (v1 text) and UDP (v2 binary)
+- **PROXY protocol v1 & v2** — SmartProxy sees the real client IP for both TCP (v1 text) and UDP (v2 binary)
-- 🔀 **Multiplexed streams** — thousands of concurrent TCP connections over a single tunnel
+- **Multiplexed streams** — thousands of concurrent TCP connections over a single tunnel
-- ⚡ **QUIC datagrams** — UDP traffic forwarded via QUIC unreliable datagrams for lowest possible latency
+- **QUIC datagrams** — UDP traffic forwarded via QUIC unreliable datagrams for lowest possible latency
-- 🔑 **Shared-secret authentication** — edges must present valid credentials to connect
+- **Shared-secret authentication** — edges must present valid credentials to connect
-- 🎫 **Connection tokens** — encode all connection details into a single opaque base64url string
+- **Connection tokens** — encode all connection details into a single opaque base64url string
-- 📡 **STUN-based public IP discovery** — edges automatically discover their public IP via Cloudflare STUN
+- **STUN-based public IP discovery** — edges automatically discover their public IP via Cloudflare STUN
-- 🔄 **Auto-reconnect** with exponential backoff if the tunnel drops
+- **Auto-reconnect** with exponential backoff if the tunnel drops
-- 🎛️ **Dynamic port configuration** — the hub assigns TCP and UDP listen ports per edge, hot-reloadable at runtime
+- **Dynamic port configuration** — the hub assigns TCP and UDP listen ports per edge, hot-reloadable at runtime
-- 📣 **Event-driven** — both Hub and Edge extend `EventEmitter` for real-time monitoring
+- **Event-driven** — both Hub and Edge extend `EventEmitter` for real-time monitoring
-- 🎚️ **3-tier QoS** — control frames, normal data, and sustained (elephant flow) traffic each get their own priority queue
+- **3-tier QoS** — control frames, normal data, and sustained (elephant flow) traffic each get their own priority queue
-- 📊 **Adaptive flow control** — per-stream windows scale with active stream count to prevent memory overuse
+- **Adaptive flow control** — per-stream windows scale with active stream count to prevent memory overuse
-- 🕒 **UDP session management** — automatic session tracking with 60s idle timeout and cleanup
+- **UDP session management** — automatic session tracking with 60s idle timeout and cleanup
+- **Crash recovery** — automatic restart with exponential backoff if the Rust binary crashes unexpectedly
 
-## 🚀 Usage
+## Usage
 
 Both classes are imported from the package and communicate with the Rust binary under the hood.
 
@@ -160,7 +162,7 @@ await edge.stop();
 | `'quic'` | QUIC with native stream multiplexing. Eliminates head-of-line blocking. Uses QUIC datagrams for UDP traffic. |
 | `'quicWithFallback'` | Tries QUIC first (5s timeout), falls back to TCP+TLS if UDP is blocked by the network. |
 
-### 🎫 Connection Tokens
+### Connection Tokens
 
 Encode all connection details into a single opaque string for easy distribution:
 
@@ -183,7 +185,7 @@ const data = decodeConnectionToken(token);
 
 Tokens are base64url-encoded — safe for environment variables, CLI arguments, and config files.
 
-## 📖 API Reference
+## API Reference
 
 ### `RemoteIngressHub`
 
@@ -195,18 +197,18 @@ Tokens are base64url-encoded — safe for environment variables, CLI arguments,
 | `getStatus()` | Returns `{ running, tunnelPort, connectedEdges: [...] }`. |
 | `running` | `boolean` — whether the Rust binary is alive. |
 
-**Events:** `edgeConnected`, `edgeDisconnected`, `streamOpened`, `streamClosed`
+**Events:** `edgeConnected`, `edgeDisconnected`, `streamOpened`, `streamClosed`, `crashRecovered`, `crashRecoveryFailed`
 
 ### `RemoteIngressEdge`
 
 | Method / Property | Description |
 |-------------------|-------------|
-| `start(config)` | Connect to hub. Accepts `{ token }` or `{ hubHost, hubPort, edgeId, secret, transportMode? }`. |
+| `start(config)` | Connect to hub. Accepts `{ token }` or `{ hubHost, hubPort, edgeId, secret, bindAddress?, transportMode? }`. |
 | `stop()` | Graceful shutdown. |
 | `getStatus()` | Returns `{ running, connected, publicIp, activeStreams, listenPorts }`. |
 | `running` | `boolean` — whether the Rust binary is alive. |
 
-**Events:** `tunnelConnected`, `tunnelDisconnected`, `publicIpDiscovered`, `portsAssigned`, `portsUpdated`
+**Events:** `tunnelConnected`, `tunnelDisconnected`, `publicIpDiscovered`, `portsAssigned`, `portsUpdated`, `crashRecovered`, `crashRecoveryFailed`
 
 ### Token Utilities
 
@@ -244,7 +246,7 @@ interface IConnectionTokenData {
 }
 ```
 
-## 🔌 Wire Protocol
+## Wire Protocol
 
 ### TCP+TLS Transport (Frame Protocol)
 
@@ -256,19 +258,19 @@ The tunnel uses a custom binary frame protocol over a single TLS connection:
 
 | Frame Type | Value | Direction | Purpose |
 |------------|-------|-----------|---------|
-| `OPEN` | `0x01` | Edge → Hub | Open TCP stream; payload is PROXY v1 header |
+| `OPEN` | `0x01` | Edge -> Hub | Open TCP stream; payload is PROXY v1 header |
-| `DATA` | `0x02` | Edge → Hub | Client data (upload) |
+| `DATA` | `0x02` | Edge -> Hub | Client data (upload) |
-| `CLOSE` | `0x03` | Edge → Hub | Client closed connection |
+| `CLOSE` | `0x03` | Edge -> Hub | Client closed connection |
-| `DATA_BACK` | `0x04` | Hub → Edge | Response data (download) |
+| `DATA_BACK` | `0x04` | Hub -> Edge | Response data (download) |
-| `CLOSE_BACK` | `0x05` | Hub → Edge | Upstream closed connection |
+| `CLOSE_BACK` | `0x05` | Hub -> Edge | Upstream closed connection |
-| `CONFIG` | `0x06` | Hub → Edge | Runtime config update (JSON payload) |
+| `CONFIG` | `0x06` | Hub -> Edge | Runtime config update (JSON payload) |
-| `PING` | `0x07` | Hub → Edge | Heartbeat probe (every 15s) |
+| `PING` | `0x07` | Hub -> Edge | Heartbeat probe (every 15s) |
-| `PONG` | `0x08` | Edge → Hub | Heartbeat response |
+| `PONG` | `0x08` | Edge -> Hub | Heartbeat response |
-| `WINDOW_UPDATE` | `0x09` | Edge → Hub | Flow control: edge consumed N bytes |
+| `WINDOW_UPDATE` | `0x09` | Edge -> Hub | Flow control: edge consumed N bytes |
-| `WINDOW_UPDATE_BACK` | `0x0A` | Hub → Edge | Flow control: hub consumed N bytes |
+| `WINDOW_UPDATE_BACK` | `0x0A` | Hub -> Edge | Flow control: hub consumed N bytes |
-| `UDP_OPEN` | `0x0B` | Edge → Hub | Open UDP session; payload is PROXY v2 header |
+| `UDP_OPEN` | `0x0B` | Edge -> Hub | Open UDP session; payload is PROXY v2 header |
-| `UDP_DATA` | `0x0C` | Edge → Hub | UDP datagram (upload) |
+| `UDP_DATA` | `0x0C` | Edge -> Hub | UDP datagram (upload) |
-| `UDP_DATA_BACK` | `0x0D` | Hub → Edge | UDP datagram (download) |
+| `UDP_DATA_BACK` | `0x0D` | Hub -> Edge | UDP datagram (download) |
 | `UDP_CLOSE` | `0x0E` | Either | Close UDP session |
 
 ### QUIC Transport
@@ -288,15 +290,15 @@ When using QUIC, the frame protocol is replaced by native QUIC primitives:
 4. Edge starts TCP and UDP listeners on the assigned ports
 5. Data flows — TCP frames/QUIC streams for TCP traffic, UDP frames/QUIC datagrams for UDP traffic
 
-## 🎚️ QoS & Flow Control
+## QoS & Flow Control
 
 ### Priority Tiers (TCP+TLS Transport)
 
 | Tier | Frames | Behavior |
 |------|--------|----------|
-| 🔴 **Control** | PING, PONG, WINDOW_UPDATE, OPEN, CLOSE, CONFIG | Always drained first. Never delayed. |
+| **Control** | PING, PONG, WINDOW_UPDATE, OPEN, CLOSE, CONFIG | Always drained first. Never delayed. |
-| 🟡 **Data** | DATA/DATA_BACK from normal streams, UDP frames | Drained when control queue is empty. |
+| **Data** | DATA/DATA_BACK from normal streams, UDP frames | Drained when control queue is empty. |
-| 🟢 **Sustained** | DATA/DATA_BACK from elephant flows | Lowest priority with guaranteed **1 MB/s** drain rate. |
+| **Sustained** | DATA/DATA_BACK from elephant flows | Lowest priority with guaranteed **1 MB/s** drain rate. |
 
 ### Sustained Stream Classification
 
@@ -312,13 +314,13 @@ Each TCP stream has a send window from a shared **200 MB budget**:
 
 | Active Streams | Window per Stream |
 |---|---|
-| 1–50 | 4 MB (maximum) |
+| 1-50 | 4 MB (maximum) |
-| 51–200 | Scales down (4 MB → 1 MB) |
+| 51-200 | Scales down (4 MB -> 1 MB) |
 | 200+ | 1 MB (floor) |
 
 UDP traffic uses no flow control — datagrams are fire-and-forget, matching UDP semantics.
 
-## 💡 Example Scenarios
+## Example Scenarios
 
 ### 1. Expose a Private Cluster to the Internet
 
@@ -362,6 +364,8 @@ await edge.start({
 Generate connection tokens on the hub side and distribute them to edge operators:
 
 ```typescript
+import { encodeConnectionToken, RemoteIngressEdge } from '@serve.zone/remoteingress';
+
 const token = encodeConnectionToken({
   hubHost: 'hub.prod.example.com',
   hubPort: 8443,
@@ -376,21 +380,19 @@ await edge.start({ token });
 
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license.md) file.
+This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
 ### Trademarks
 
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
-
-Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
 Task Venture Capital GmbH
-Registered at District Court Bremen HRB 35230 HB, Germany
+Registered at District court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or further information, please contact us via email at hello@task.vc.
+For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
 
 By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/remoteingress',
-  version: '4.14.2',
+  version: '4.14.3',
   description: 'Edge ingress tunnel for DcRouter - tunnels TCP and UDP traffic from the network edge to SmartProxy over TLS or QUIC, preserving client IP via PROXY protocol.'
 }