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 for the current peer diversity model and FABRIC_LIVE_AUDIT_2026-05-18.md for the live operational gaps.