remoteingress/readme.md

# @serve.zone/remoteingress

Edge ingress tunnel for DcRouter — accepts incoming TCP connections at the network edge and tunnels them over a single encrypted TLS connection 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

```sh
pnpm install @serve.zone/remoteingress
```

## 🏗️ 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   │
│  Accepts client TCP │                                │  Forwards to        │
│  connections on     │                                │  SmartProxy on      │
│  hub-assigned ports │                                │  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 ports assigned by the hub, accepts raw TCP connections, and multiplexes them over a single TLS tunnel to the hub. Ports are hot-reloadable — the hub can change them at runtime. |
| **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. Controls which ports each edge listens on. |
| **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
- 🎫 **Connection tokens** — encode all connection details into a single opaque string
- 📡 **STUN-based public IP discovery** — the edge automatically discovers its public IP via Cloudflare STUN
- 🔄 **Auto-reconnect** with exponential backoff if the tunnel drops
- 🎛️ **Dynamic port configuration** — the hub assigns listen ports per edge and can hot-reload them at runtime via `FRAME_CONFIG` frames
- 📣 **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
- 🎚️ **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

## 🚀 Usage

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.

### Setting Up the Hub (Private Cluster Side)

```typescript
import { RemoteIngressHub } from '@serve.zone/remoteingress';

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, including their listen ports
await hub.updateAllowedEdges([
  {
    id: 'edge-nyc-01',
    secret: 'supersecrettoken1',
    listenPorts: [80, 443],        // ports the edge should listen on
    stunIntervalSecs: 300,         // STUN discovery interval (default: 300)
  },
  {
    id: 'edge-fra-02',
    secret: 'supersecrettoken2',
    listenPorts: [443, 8080],
  },
]);

// Dynamically update ports for a connected edge — changes are pushed instantly
await hub.updateAllowedEdges([
  {
    id: 'edge-nyc-01',
    secret: 'supersecrettoken1',
    listenPorts: [80, 443, 8443],  // added port 8443 — edge picks it up in real time
  },
]);

// 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();
```

### Setting Up the Edge (Network Edge Side)

The edge can be configured in two ways: with an **opaque connection token** (recommended) or with explicit config fields.

#### Option A: Connection Token (Recommended)

A single token encodes all connection details — ideal for provisioning edges at scale:

```typescript
import { RemoteIngressEdge } from '@serve.zone/remoteingress';

const edge = new RemoteIngressEdge();

edge.on('tunnelConnected', () => console.log('Tunnel established'));
edge.on('tunnelDisconnected', () => console.log('Tunnel lost — will auto-reconnect'));
edge.on('publicIpDiscovered', ({ ip }) => console.log(`Public IP: ${ip}`));
edge.on('portsAssigned', ({ listenPorts }) => console.log(`Listening on ports: ${listenPorts}`));
edge.on('portsUpdated', ({ listenPorts }) => console.log(`Ports updated: ${listenPorts}`));

// Single token contains hubHost, hubPort, edgeId, and secret
await edge.start({
  token: 'eyJoIjoiaHViLmV4YW1wbGUuY29tIiwicCI6ODQ0MywiZSI6ImVkZ2UtbnljLTAxIiwicyI6InN1cGVyc2VjcmV0dG9rZW4xIn0',
});
```

#### Option B: Explicit Config

```typescript
import { RemoteIngressEdge } from '@serve.zone/remoteingress';

const edge = new RemoteIngressEdge();

edge.on('tunnelConnected', () => console.log('Tunnel established'));
edge.on('tunnelDisconnected', () => console.log('Tunnel lost — will auto-reconnect'));
edge.on('publicIpDiscovered', ({ ip }) => console.log(`Public IP: ${ip}`));
edge.on('portsAssigned', ({ listenPorts }) => console.log(`Listening on ports: ${listenPorts}`));
edge.on('portsUpdated', ({ listenPorts }) => console.log(`Ports updated: ${listenPorts}`));

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
});

// Check status at any time
const edgeStatus = await edge.getStatus();
console.log(edgeStatus);
// {
//   running: true,
//   connected: true,
//   publicIp: '203.0.113.42',
//   activeStreams: 5,
//   listenPorts: [80, 443]
// }

// Graceful shutdown
await edge.stop();
```

### 🎫 Connection Tokens

Connection tokens let you distribute a single opaque string instead of four separate config values. The hub operator generates the token; the edge operator just pastes it in.

```typescript
import { encodeConnectionToken, decodeConnectionToken } from '@serve.zone/remoteingress';

// Hub side: generate a token for a new edge
const token = encodeConnectionToken({
  hubHost: 'hub.example.com',
  hubPort: 8443,
  edgeId: 'edge-nyc-01',
  secret: 'supersecrettoken1',
});
console.log(token);
// => 'eyJoIjoiaHViLmV4YW1wbGUuY29tIiwi...'

// Edge side: inspect a token (optional — start() does this automatically)
const data = decodeConnectionToken(token);
console.log(data);
// {
//   hubHost: 'hub.example.com',
//   hubPort: 8443,
//   edgeId: 'edge-nyc-01',
//   secret: 'supersecrettoken1'
// }
```

Tokens are base64url-encoded (URL-safe, no padding) — safe to pass as environment variables, CLI arguments, or store in config files.

## 📖 API Reference

### `RemoteIngressHub`

| 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 and what ports they listen on. Each edge: `{ id: string, secret: string, listenPorts?: number[], stunIntervalSecs?: number }`. If ports change for a connected edge, the update is pushed immediately via a `FRAME_CONFIG` frame. |
| `getStatus()` | Returns current hub status including connected edges and active stream counts. |
| `running` | `boolean` — whether the Rust binary is alive. |

**Events:** `edgeConnected`, `edgeDisconnected`, `streamOpened`, `streamClosed`

### `RemoteIngressEdge`

| Method / Property | Description |
|-------------------|-------------|
| `start(config)` | Spawns the Rust binary and connects to the hub. Accepts `{ token: string }` or `IEdgeConfig`. Listen ports are received from the hub during handshake. |
| `stop()` | Gracefully shuts down the edge and kills the Rust process. |
| `getStatus()` | Returns current edge status including connection state, public IP, listen ports, and active streams. |
| `running` | `boolean` — whether the Rust binary is alive. |

**Events:** `tunnelConnected`, `tunnelDisconnected`, `publicIpDiscovered`, `portsAssigned`, `portsUpdated`

### Token Utilities

| Function | Description |
|----------|-------------|
| `encodeConnectionToken(data)` | Encodes `IConnectionTokenData` into a base64url token string. |
| `decodeConnectionToken(token)` | Decodes a token back into `IConnectionTokenData`. Throws on malformed or incomplete tokens. |

### Interfaces

```typescript
interface IHubConfig {
  tunnelPort?: number;   // default: 8443
  targetHost?: string;   // default: '127.0.0.1'
}

interface IEdgeConfig {
  hubHost: string;
  hubPort?: number;      // default: 8443
  edgeId: string;
  secret: string;
}

interface IConnectionTokenData {
  hubHost: string;
  hubPort: number;
  edgeId: string;
  secret: string;
}
```

## 🔌 Wire Protocol

The tunnel uses a custom binary frame protocol over TLS:

```
[stream_id: 4 bytes BE][type: 1 byte][length: 4 bytes BE][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 |
| `CONFIG` | `0x06` | Hub → Edge | Runtime configuration update (e.g. port changes); payload is JSON |
| `PING` | `0x07` | Hub → Edge | Heartbeat probe (sent every 15s) |
| `PONG` | `0x08` | Edge → Hub | Heartbeat response |
| `WINDOW_UPDATE` | `0x09` | Edge → Hub | Per-stream flow control: edge consumed N bytes, hub can send more |
| `WINDOW_UPDATE_BACK` | `0x0A` | Hub → Edge | Per-stream flow control: hub consumed N bytes, edge can send more |

Max payload size per frame: **16 MB**. Stream IDs are 32-bit unsigned integers.

### Handshake Sequence

1. Edge opens a TLS connection to the hub
2. Edge sends: `EDGE <edgeId> <secret>\n`
3. Hub verifies credentials (constant-time comparison) and responds with JSON: `{"listenPorts":[...],"stunIntervalSecs":300}\n`
4. Edge starts TCP listeners on the assigned ports
5. Frame protocol begins — `OPEN`/`DATA`/`CLOSE` frames flow in both directions
6. Hub can push `CONFIG` frames at any time to update the edge's listen ports

## 🎚️ QoS & Flow Control

The tunnel multiplexer uses a **3-tier priority system** and **per-stream flow control** to ensure fair bandwidth sharing across thousands of concurrent streams.

### Priority Tiers

All outbound frames are queued into one of three priority levels:

| Tier | Queue | Frames | Behavior |
|------|-------|--------|----------|
| 🔴 **Control** (highest) | `ctrl_queue` | PING, PONG, WINDOW_UPDATE, OPEN, CLOSE, CONFIG | Always drained first. Never delayed. |
| 🟡 **Data** (normal) | `data_queue` | DATA, DATA_BACK from normal streams | Drained when ctrl is empty. Gated at 64 buffered items for backpressure. |
| 🟢 **Sustained** (lowest) | `sustained_queue` | DATA, DATA_BACK from elephant flows | Drained freely when ctrl+data are empty. Otherwise guaranteed **1 MB/s** via forced drain every second. |

This prevents large bulk transfers (e.g. git clones, file downloads) from starving interactive traffic and ensures `WINDOW_UPDATE` frames are never delayed — which would cause flow control deadlocks.

### Sustained Stream Classification

A stream is automatically classified as **sustained** (elephant flow) when:
- It has been active for **>10 seconds**, AND
- Its average throughput exceeds **20 Mbit/s** (2.5 MB/s)

Once classified, the stream's flow control window is locked to the **1 MB floor** and its data frames move to the lowest-priority queue. Classification is one-way — a stream never gets promoted back to normal.

### Adaptive Per-Stream Windows

Each stream has a send window that limits bytes-in-flight. The window size adapts to the number of active streams using a shared **200 MB memory budget**:

| Active Streams | Window per Stream |
|---|---|
| 1–50 | 4 MB (maximum) |
| 51–100 | Scales down (4 MB → 2 MB) |
| 200+ | 1 MB (floor) |

The consumer sends `WINDOW_UPDATE` frames after processing data, allowing the producer to send more. This prevents any single stream from consuming unbounded memory and provides natural backpressure.

## 💡 Example Scenarios

### 1. Expose a Private Kubernetes Cluster to the Internet

Deploy an Edge on a public VPS, point your DNS 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. 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. 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.

### 4. Token-Based Edge Provisioning

Generate connection tokens on the hub side and distribute them to edge operators. Each edge only needs a single token string to connect — no manual configuration of host, port, ID, and secret.

```typescript
// Hub operator generates token
const token = encodeConnectionToken({
  hubHost: 'hub.prod.example.com',
  hubPort: 8443,
  edgeId: 'edge-tokyo-01',
  secret: 'generated-secret-abc123',
});
// Send `token` to the edge operator via secure channel

// Edge operator starts with just the token
const edge = new RemoteIngressEdge();
await edge.start({ token });
```

### 5. Dynamic Port Management

The hub controls which ports each edge listens on. Ports can be changed at runtime without restarting the edge — the hub pushes a `CONFIG` frame and the edge hot-reloads its TCP listeners.

```typescript
// Initially assign ports 80 and 443
await hub.updateAllowedEdges([
  { id: 'edge-nyc-01', secret: 'secret', listenPorts: [80, 443] },
]);

// Later, add port 8080 — the connected edge picks it up instantly
await hub.updateAllowedEdges([
  { id: 'edge-nyc-01', secret: 'secret', listenPorts: [80, 443, 8080] },
]);
```

## 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) 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 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

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.