From ce5074c57dfb29ddff7641e0e3f5f00a8c055e4f Mon Sep 17 00:00:00 2001 From: Juergen Kunz Date: Mon, 16 Feb 2026 13:15:12 +0000 Subject: [PATCH] fix(readme): Document Hub/Edge architecture and new RemoteIngressHub/RemoteIngressEdge API; add Rust core binary, protocol and usage details; note removal of ConnectorPublic/ConnectorPrivate (breaking change) --- changelog.md | 10 ++ readme.hints.md | 12 ++- readme.md | 222 +++++++++++++++++++++++++++++---------- ts/00_commitinfo_data.ts | 2 +- 4 files changed, 185 insertions(+), 61 deletions(-) diff --git a/changelog.md b/changelog.md index e58453d..66c0acd 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,15 @@ # Changelog +## 2026-02-16 - 3.0.2 - fix(readme) +Document Hub/Edge architecture and new RemoteIngressHub/RemoteIngressEdge API; add Rust core binary, protocol and usage details; note removal of ConnectorPublic/ConnectorPrivate (breaking change) + +- Adds comprehensive README describing v3 Hub↔Edge topology and usage examples +- Introduces Rust core binary (remoteingress-bin) and RustBridge IPC via @push.rocks/smartrust +- Documents custom multiplexed binary frame protocol over TLS and PROXY protocol v1 for client IP preservation +- Notes STUN-based public IP discovery and cross-compiled linux/amd64 and linux/arm64 binaries +- Calls out removal/rename of ConnectorPublic/ConnectorPrivate to RemoteIngressHub/RemoteIngressEdge (breaking API change) +- Updates install instruction to use pnpm and expands API reference, events, and examples + ## 2026-02-16 - 3.0.1 - fix(remoteingress) no changes detected in diff; no code modifications to release diff --git a/readme.hints.md b/readme.hints.md index cea51fe..162f967 100644 --- a/readme.hints.md +++ b/readme.hints.md @@ -1,3 +1,9 @@ -* this module is part of the @serve.zone stack -* it is used to reach private clusters from outside -* it can be used to create private tunnels to private networks +* This module is part of the @serve.zone stack +* v3.0.0+ uses a Hub/Edge architecture with a Rust core binary (`remoteingress-bin`) +* TypeScript classes `RemoteIngressHub` and `RemoteIngressEdge` bridge to Rust via `@push.rocks/smartrust` RustBridge IPC +* Custom multiplexed binary frame protocol over TLS for tunneling TCP connections +* PROXY protocol v1 preserves client IP when forwarding to SmartProxy/DcRouter +* Edge authenticates to Hub via shared secret over TLS +* STUN-based public IP discovery at the edge (Cloudflare STUN server) +* Cross-compiled Rust binary for linux/amd64 and linux/arm64 +* Old `ConnectorPublic`/`ConnectorPrivate` classes no longer exist (removed in v2.0.0/v3.0.0) diff --git a/readme.md b/readme.md index 3dc8a0a..923e2da 100644 --- a/readme.md +++ b/readme.md @@ -1,107 +1,215 @@ # @serve.zone/remoteingress -Provides a service for creating private tunnels and reaching private clusters from the outside as part of the @serve.zone stack. +Edge ingress tunnel for DcRouter — accepts incoming TCP connections at the network edge and tunnels them to a DcRouter SmartProxy instance, preserving the original client IP via PROXY protocol v1. + +## Issue Reporting and Security + +For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly. ## Install -To install `@serve.zone/remoteingress`, run the following command in your terminal: - ```sh -npm install @serve.zone/remoteingress +pnpm install @serve.zone/remoteingress ``` -This command will download and install the remoteingress package and its dependencies into your project. +## 🏗️ Architecture + +`@serve.zone/remoteingress` uses a **Hub ↔ Edge** topology with a high-performance Rust core and a TypeScript API surface: + +``` +┌─────────────────────┐ TLS Tunnel ┌─────────────────────┐ +│ Network Edge │ ◄══════════════════════════► │ Private Cluster │ +│ │ (multiplexed frames + │ │ +│ RemoteIngressEdge │ shared-secret auth) │ RemoteIngressHub │ +│ Listens on :80,:443│ │ Forwards to │ +│ Accepts client TCP │ │ SmartProxy on │ +│ │ │ local ports │ +└─────────────────────┘ └─────────────────────┘ + ▲ │ + │ TCP from end users ▼ + Internet DcRouter / SmartProxy +``` + +| Component | Role | +|-----------|------| +| **RemoteIngressEdge** | Deployed at the network edge (e.g. a VPS or cloud instance). Listens on public ports, accepts raw TCP connections, and multiplexes them over a single TLS tunnel to the hub. | +| **RemoteIngressHub** | Deployed alongside DcRouter/SmartProxy in a private cluster. Accepts edge connections, demuxes streams, and forwards each to SmartProxy with a PROXY protocol v1 header 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 + +- 🔒 **TLS-encrypted tunnel** between edge and hub (auto-generated self-signed cert or bring your own) +- 🔀 **Multiplexed streams** — thousands of client connections flow over a single tunnel +- 🌐 **PROXY protocol v1** — SmartProxy sees the real client IP, not the tunnel IP +- 🔐 **Shared-secret authentication** — edges must present valid credentials to connect +- 📡 **STUN-based public IP discovery** — the edge automatically discovers its public IP via Cloudflare STUN +- 🔄 **Auto-reconnect** with exponential backoff if the tunnel drops +- 📢 **Event-driven** — both Hub and Edge extend `EventEmitter` for real-time monitoring +- ⚡ **Rust core** — all frame encoding, TLS, and TCP proxying happen in native code for maximum throughput ## Usage -`@serve.zone/remoteingress` is designed to facilitate the creation of secure private tunnels and enable access to private clusters from external sources, offering an integral part of the @serve.zone stack infrastructure. Below, we illustrate how to employ this package within your project, leveraging TypeScript and ESM syntax for modern, type-safe, and modular code. +Both classes are imported from the package and communicate with the Rust binary under the hood. All you need to do is configure and start them. -### Prerequisites - -Ensure that you have Node.js and TypeScript installed in your environment. Your project should be set up with TypeScript support, and you might want to familiarize yourself with basic networking concepts and TLS/SSL for secure communication. - -### Importing and Initializing Connectors - -`@serve.zone/remoteingress` offers two primary components: `ConnectorPublic` and `ConnectorPrivate`. Here's how to use them: - -#### Setup ConnectorPublic - -`ConnectorPublic` acts as a gateway, accepting incoming tunnel connections from `ConnectorPrivate` instances and facilitating secure communication between the internet and your private network. +### Setting up the Hub (private cluster side) ```typescript -import { ConnectorPublic } from '@serve.zone/remoteingress'; +import { RemoteIngressHub } from '@serve.zone/remoteingress'; -// Initialize ConnectorPublic -const publicConnector = new ConnectorPublic({ - tlsOptions: { - key: fs.readFileSync(""), - cert: fs.readFileSync(""), - // Consider including 'ca' and 'passphrase' if required for your setup - }, - listenPort: 443 // Example listen port; adjust based on your needs +const hub = new RemoteIngressHub(); + +// Listen for events +hub.on('edgeConnected', ({ edgeId }) => { + console.log(`✅ Edge ${edgeId} connected`); }); +hub.on('edgeDisconnected', ({ edgeId }) => { + console.log(`❌ Edge ${edgeId} disconnected`); +}); +hub.on('streamOpened', ({ edgeId, streamId }) => { + console.log(`🔗 Stream ${streamId} opened from edge ${edgeId}`); +}); +hub.on('streamClosed', ({ edgeId, streamId }) => { + console.log(`🔗 Stream ${streamId} closed from edge ${edgeId}`); +}); + +// Start the hub — it will listen for incoming edge TLS connections +await hub.start({ + tunnelPort: 8443, // port edges connect to (default: 8443) + targetHost: '127.0.0.1', // SmartProxy host to forward streams to (default: 127.0.0.1) +}); + +// Register which edges are allowed to connect +await hub.updateAllowedEdges([ + { id: 'edge-nyc-01', secret: 'supersecrettoken1' }, + { id: 'edge-fra-02', secret: 'supersecrettoken2' }, +]); + +// Check status at any time +const status = await hub.getStatus(); +console.log(status); +// { +// running: true, +// tunnelPort: 8443, +// connectedEdges: [ +// { edgeId: 'edge-nyc-01', connectedAt: 1700000000, activeStreams: 12 } +// ] +// } + +// Graceful shutdown +await hub.stop(); ``` -#### Setup ConnectorPrivate - -`ConnectorPrivate` establishes a secure tunnel to `ConnectorPublic`, effectively bridging your internal services with the external point of access. +### Setting up the Edge (network edge side) ```typescript -import { ConnectorPrivate } from '@serve.zone/remoteingress'; +import { RemoteIngressEdge } from '@serve.zone/remoteingress'; -// Initialize ConnectorPrivate pointing to your ConnectorPublic instance -const privateConnector = new ConnectorPrivate({ - publicHost: 'your.public.domain.tld', - publicPort: 443, // Ensure this matches the listening port of ConnectorPublic - tlsOptions: { - // You might want to specify TLS options here, similar to ConnectorPublic - } +const edge = new RemoteIngressEdge(); + +// Listen for events +edge.on('tunnelConnected', () => { + console.log('🟢 Tunnel to hub established'); }); +edge.on('tunnelDisconnected', () => { + console.log('🔴 Tunnel to hub lost — will auto-reconnect'); +}); +edge.on('publicIpDiscovered', ({ ip }) => { + console.log(`🌐 Public IP: ${ip}`); +}); + +// Start the edge — it connects to the hub and starts listening for clients +await edge.start({ + hubHost: 'hub.example.com', // hostname or IP of the hub + hubPort: 8443, // must match hub's tunnelPort (default: 8443) + edgeId: 'edge-nyc-01', // unique edge identifier + secret: 'supersecrettoken1', // must match the hub's allowed edge secret + listenPorts: [80, 443], // public ports to accept TCP connections on + stunIntervalSecs: 300, // STUN refresh interval in seconds (default: 300) +}); + +// Check status at any time +const status = await edge.getStatus(); +console.log(status); +// { +// running: true, +// connected: true, +// publicIp: '203.0.113.42', +// activeStreams: 5, +// listenPorts: [80, 443] +// } + +// Graceful shutdown +await edge.stop(); ``` -### Secure Communication +### API Reference -It's imperative to ensure that the communication between `ConnectorPublic` and `ConnectorPrivate` is secure: +#### `RemoteIngressHub` -- Always use valid TLS certificates. -- Prefer using certificates issued by recognized Certificate Authorities (CA). -- Optionally, configure mutual TLS (mTLS) by requiring client certificates for an added layer of security. +| Method / Property | Description | +|-------------------|-------------| +| `start(config?)` | Spawns the Rust binary and starts the tunnel listener. Config: `{ tunnelPort?: number, targetHost?: string }` | +| `stop()` | Gracefully shuts down the hub and kills the Rust process. | +| `updateAllowedEdges(edges)` | Dynamically update which edges are authorized. Each edge: `{ id: string, secret: string }` | +| `getStatus()` | Returns current hub status including connected edges and active stream counts. | +| `running` | `boolean` — whether the Rust binary is alive. | -### Advanced Usage +**Events:** `edgeConnected`, `edgeDisconnected`, `streamOpened`, `streamClosed` -Both connectors can be finely tuned: +#### `RemoteIngressEdge` -- **Logging and Monitoring:** Integrate with your existing logging and monitoring systems to keep tabs on tunnel activity, performance metrics, and potential security anomalies. +| Method / Property | Description | +|-------------------|-------------| +| `start(config)` | Spawns the Rust binary, connects to the hub, and starts listening on the specified ports. | +| `stop()` | Gracefully shuts down the edge and kills the Rust process. | +| `getStatus()` | Returns current edge status including connection state, public IP, and active streams. | +| `running` | `boolean` — whether the Rust binary is alive. | -- **Custom Handlers:** Implement custom traffic handling logic for specialized routing, filtering, or protocol-specific processing. +**Events:** `tunnelConnected`, `tunnelDisconnected`, `publicIpDiscovered` -- **Automation:** Automate the deployment and scaling of both `ConnectorPublic` and `ConnectorPrivate` instances using infrastructure-as-code (IAC) tools and practices, ensuring that your tunneling infrastructure can dynamically adapt to the ever-changing needs of your services. +### 🔌 Wire Protocol + +The tunnel uses a custom binary frame protocol over TLS: + +``` +[stream_id: 4 bytes][type: 1 byte][length: 4 bytes][payload: N bytes] +``` + +| Frame Type | Value | Direction | Purpose | +|------------|-------|-----------|---------| +| `OPEN` | `0x01` | Edge → Hub | Open a new stream; payload is PROXY v1 header | +| `DATA` | `0x02` | Edge → Hub | Client data flowing upstream | +| `CLOSE` | `0x03` | Edge → Hub | Client closed the connection | +| `DATA_BACK` | `0x04` | Hub → Edge | Response data flowing downstream | +| `CLOSE_BACK` | `0x05` | Hub → Edge | Upstream (SmartProxy) closed the connection | + +Max payload size per frame: **16 MB**. ### Example Scenarios -1. **Securing Application APIs:** Use `@serve.zone/remoteingress` to expose private APIs to your frontend deployed on a public cloud, ensuring that only your infrastructure can access these endpoints. +1. **Expose a private Kubernetes cluster to the internet** — Deploy an Edge on a public VPS, configure your DNS to point to the VPS IP. The Edge tunnels all traffic to the Hub running inside the cluster, which hands it off to SmartProxy/DcRouter. Your cluster stays fully private — no public-facing ports needed. -2. **Remote Database Access:** Securely access databases within a private VPC from your local development machine without opening direct access to the internet. +2. **Multi-region edge ingress** — Run multiple Edges in different geographic regions (NYC, Frankfurt, Tokyo) all connecting to a single Hub. Use GeoDNS to route users to their nearest Edge. The Hub sees the real client IPs via PROXY protocol regardless of which edge they connected through. -3. **Service Mesh Integration:** Integrate `@serve.zone/remoteingress` as part of a service mesh setup to securely connect services across multiple clusters with robust identity and encryption at the tunnel level. - -For detailed documentation, API references, and additional use cases, please refer to the inline documentation and source code within the package. Always prioritize security and robustness when dealing with network ingress to protect your infrastructure and data from unauthorized access and threats. +3. **Secure API exposure** — Your backend runs on a private network with no direct internet access. An Edge on a minimal cloud instance acts as the only public entry point. TLS tunnel + shared-secret auth ensure only your authorized Edge can forward traffic. ## License and Legal Information -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. +This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file. **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 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. +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. + +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 +Task Venture Capital GmbH +Registered at District Court Bremen HRB 35230 HB, Germany -For any legal inquiries or if you require further information, please contact us via email at hello@task.vc. +For any legal inquiries or 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. diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 56833b3..a1acff2 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@serve.zone/remoteingress', - version: '3.0.1', + version: '3.0.2', description: 'Edge ingress tunnel for DcRouter - accepts incoming TCP connections at network edge and tunnels them to DcRouter SmartProxy preserving client IP via PROXY protocol v1.' }