Traffic Entry Role

1. Status

This document replaces the old Ingress Gateway concept.

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

Node
  Capability Binding: traffic.entry
  Runtime Binding: sing-box
  Endpoint: client-facing Traffic endpoint

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.entry is the client-facing access role inside Traffic Capability.

It receives client connections, authenticates subscription credentials, applies Traffic policies, and forwards traffic through the selected Traffic path.

It is a role, not a runtime and not a software package.

3. Runtime Implementation

Current MVP runtime:

• sing-box.

Current MVP protocol:

• Trojan + TLS + 443.

Future Traffic runtimes or protocols:

• Xray.
• VLESS.
• Hysteria2.
• TUIC.
• Shadowsocks.

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

4. Endpoint Model

A Traffic Entry endpoint owns:

• domain.
• DNS target.
• protocol.
• port.
• certificate binding.
• runtime binding.
• readiness.

Example endpoint:

capability_role: traffic.entry
runtime: sing-box
protocol: trojan
domain: <endpoint>.traffic.orbitmesh.dev
port: 443
certificate_ref: cert_xxx

5. Desired State Shape

Desired state should use capability role terms:

{
  "capability": "traffic",
  "role": "traffic.entry",
  "runtime": "sing-box",
  "endpoint": {
    "protocol": "trojan",
    "listen": "::",
    "port": 443,
    "domain": "tenant.example.com",
    "certificate_ref": "cert_xxx"
  },
  "subscriptions": [
    {
      "id": "sub_001",
      "credential_ref": "secret_ref"
    }
  ],
  "traffic_policy_id": "tp_default"
}

Do not use role: ingress in new desired state.

6. Certificates

ACME, certificates, and domain allocation are endpoint infrastructure.

System domains:

<endpoint-id>.traffic.orbitmesh.dev
<tenant-slug>--<endpoint-slug>.traffic.orbitmesh.dev

Requirements:

• Control Plane allocates default domains.
• Control Plane reconciles DNS for ready endpoints.
• Certificate status participates in endpoint readiness.
• Subscriptions only include certificate-ready entry endpoints.
• Runtime adapters consume local certificate paths, not ACME business logic.

7. Acceptance

• Client can connect through a traffic.entry endpoint.
• Subscription credential is enforced.
• Traffic policy changes recompile affected desired state.
• Runtime restart is recovered by Edge Runtime.
• Certificate readiness gates subscription output.