Traffic Exit Role

1. Status

This document replaces the old Egress Gateway concept.

Egress Gateway is no longer a top-level OrbitMesh resource. The correct model is:

Node
  Capability Binding: traffic.exit
  Runtime Binding: sing-box

No compatibility semantics should be added for the old model. Existing database rows must be migrated with SQL when the schema changes.

2. Positioning

traffic.exit is the outbound role inside Traffic Capability.

It is responsible for reaching target services such as GitHub, Claude, OpenAI, Docker, npm, and PyPI with predictable quality, cost, and policy.

It is a role, not a runtime and not a generic Gateway.

3. Runtime Implementation

Current MVP runtime:

• sing-box.

Current MVP internal path:

• Traffic Entry forwards to Traffic Exit through Shadowsocks 2022.
• Traffic Exit sends target traffic through direct outbound.

Future Traffic runtimes:

• Xray.
• Hysteria.
• Shadowsocks.
• custom traffic runtime.

Runtime selection must happen through Runtime Binding and Runtime Plugin metadata.

4. Exit Selection

Traffic Policy selects exit roles based on:

• target service.
• domain.
• region.
• health.
• cost.
• tenant policy.
• quota or enforcement state.

The policy result should reference capability bindings or endpoint candidates, not legacy egress gateway types.

5. Desired State Shape

Desired state should use capability role terms:

{
  "capability": "traffic",
  "role": "traffic.exit",
  "runtime": "sing-box",
  "provider": "aws",
  "region": "ap-northeast-1",
  "internal_listener": {
    "protocol": "shadowsocks",
    "listen": "0.0.0.0",
    "port": 8388,
    "credential_ref": "secret_ref"
  },
  "outbound": {
    "type": "direct"
  }
}

Do not use role: egress in new desired state.

6. Network Exposure

The internal Traffic Entry to Traffic Exit listener must not be exposed as an unauthenticated public service.

Requirements:

• authorize only selected Traffic Entry roles.
• do not expose management ports.
• restrict SSH independently from OrbitMesh runtime ports.
• model reachability explicitly instead of assuming public_ip.

7. Health

Traffic Exit should probe important targets:

• github.com.
• api.github.com.
• registry-1.docker.io.
• registry.npmjs.org.
• pypi.org.
• api.openai.com.
• api.anthropic.com.

Metrics:

• connect time.
• TLS time.
• total time.
• HTTP status.
• failure reason.

8. Acceptance

• Traffic Entry can forward traffic to selected Traffic Exit.
• Traffic Exit can reach target services.
• Control Plane can observe Traffic Exit health.
• Traffic Policy avoids unhealthy exits.
• Runtime configuration updates can be reconciled by Edge Runtime.