rdp-proxy/docs/architecture/FABRIC_SERVICE_OVER_TRANSPORT_MODEL.md

# Fabric Service-Over-Transport Model

Status: active target architecture.

This document defines the mandatory separation between:

1. the internal fabric transport;
2. the logical service channel contract;
3. the external service ingress edge.

It exists to prevent a recurring failure pattern where external TCP/HTTP/HTTPS
listeners are mistaken for the fabric's internal transport.

## 1. Core rule

The fabric is the internal transport substrate.

- Inside the fabric, node-to-node runtime transport is `QUIC over UDP`.
- Services do not implement their own inter-node transport.
- Services do not need to understand relay, NAT, route replacement, or peer
  selection details.

A service asks the fabric for a channel. The fabric creates, maintains,
rebuilds, and heals that channel.

## 2. Three-layer model

### 2.1 Fabric Transport

Fabric Transport is the lowest runtime layer.

Responsibilities:

- peer discovery and peer memory
- endpoint candidate verification
- direct and relay path establishment
- route maintenance
- route replacement
- cross-area recovery
- QUIC session lifecycle
- cert pin and authority trust enforcement

Transport contract:

- node-to-node runtime transport is `QUIC/UDP`
- TCP is not an alternate transport carrier inside the fabric

### 2.2 Fabric Service Channel

The service channel is the logical contract used by any upper-layer service.

Responsibilities:

- request a route to a node or pool
- expose a stable channel identifier
- carry bidirectional application traffic
- survive path rebuild when possible
- surface degraded or migrated channel state to the service without exposing
  internal route topology details

The service channel must hide:

- which relay was chosen
- which direct peer was replaced
- which ingress or NAT path was changed
- which recovery seed was used

The service should see channel semantics, not transport topology.

### 2.3 External Service Ingress

External ingress is the edge that accepts user-facing or third-party traffic.

Examples:

- HTTP/HTTPS ingress for admin UI and personal cabinet
- VPN ingress that accepts client traffic
- future RDP ingress

Ingress may speak TCP/HTTP/HTTPS or another external protocol at the edge, but
after acceptance it must map traffic into a fabric service channel.

The ingress edge is not the fabric transport.

## 3. Examples

### 3.1 Admin panel

The user opens an HTTPS page.

1. the public ingress listens on `80/443`;
2. it accepts HTTPS and performs edge policy checks;
3. it opens or reuses a `control_ui` fabric service channel;
4. the request is forwarded through the fabric to a panel service instance;
5. the response is returned through the fabric channel back to the ingress;
6. the ingress returns the HTTP response to the browser.

The browser sees HTTPS. The fabric sees an internal service channel over
`QUIC/UDP`.

### 3.2 VPN

The VPN edge accepts client-side tunnel traffic.

1. the VPN service receives IPv4 packets from the client-facing side;
2. it requests a `vpn_tunnel` channel to an egress pool;
3. the fabric chooses and maintains the route;
4. an egress node performs IPv4 exit/NAT to the external network;
5. return traffic follows the maintained channel back through the fabric.

The VPN service does not decide how the route is built. The fabric does.

## 4. Service contract requirements

Every service-over-fabric integration must use a channel contract with at least
these concepts:

- `channel_request`
- `channel_id`
- `channel_class`
- `destination_selector`
- `current_state`
- `send`
- `receive`
- `close`

Optional but recommended:

- `channel_migrated`
- `channel_degraded`
- `preferred_qos_class`
- `pool_affinity`
- `session_stickiness`

## 5. Channel classes

Minimum channel classes:

- `control_ui`
- `vpn_tunnel`
- `rdp_session`
- `artifact_delivery`
- `service_admin`
- `internal_control`

Each class must define:

- latency sensitivity
- loss tolerance
- bandwidth expectation
- stickiness requirement
- pool failover behavior
- health check behavior

## 6. Pool-first delivery

Services should target pools when they need resilience.

Examples:

- VPN should target an egress pool, not a single node
- future RDP should target a pool of reachable adapters when that service mode
  applies

The service must not need to know:

- which specific node was selected
- how many nodes are in the pool
- whether the path was direct or relayed

## 7. Recovery implications

Recovery must be separated into:

1. node survival
2. transport survival
3. service channel survival
4. ingress survival

It is not enough for the node to recover if the service channel model still
depends on a hidden compat carrier.

## 8. TCP clarification

TCP is allowed only in these roles:

- external user ingress
- operator/API ingress
- temporary compatibility recovery overlap
- artifact/control delivery at the service edge

TCP is not allowed as the normal inter-node fabric transport.

If TCP is still visible in the live system, it must be classified explicitly as
one of the roles above.

## 9. Relationship to area stability

The transport layer must maintain resilient peer diversity across areas, but the
service layer must not need to understand those details.

See
[FABRIC_AREA_AND_PEER_STABILITY_MODEL.md](\\nas\\MST\\codex\\rdp-proxy\\docs\\architecture\\FABRIC_AREA_AND_PEER_STABILITY_MODEL.md)
for the current peer diversity model and
[FABRIC_LIVE_AUDIT_2026-05-18.md](\\nas\\MST\\codex\\rdp-proxy\\docs\\architecture\\FABRIC_LIVE_AUDIT_2026-05-18.md)
for the live operational gaps.