Runtime Adapter Specification

1. Status

This document records the planned Runtime Adapter design for post-MVP implementation.

Current mainline development remains focused on the sing-box MVP path:

• Node enrollment.
• Edge Runtime identity.
• Desired State pull.
• sing-box configuration apply.
• Console operations for existing runtime binding parameters.

Traefik and Tailscale support are intentionally deferred. Their adapters may exist as registered stubs, but they must not silently compile usable runtime configuration until the full contract below is implemented and tested.

2. Goal

Runtime Adapter separates OrbitMesh platform models from concrete data plane runtimes.

Each adapter owns:

• runtime parameter schema.
• runtime binding value normalization and validation.
• runtime endpoint templates.
• desired state runtime options.
• runtime manifest compilation.
• apply and reload expectations for Edge Runtime.
• health and version reporting expectations.

The Control Plane should route by RuntimeKind and avoid hard-coded runtime branches outside the adapter registry.

3. Current Runtime Matrix

4. Adapter Contract

Control Plane adapter responsibilities:

type RuntimeAdapter interface {
    RuntimeParameterFields(capabilityRole string) ([]RuntimeParameterField, error)
    RuntimeParameterSchemaJSON(capabilityRole string) (string, error)
    RuntimeEndpointTemplates(capabilityRole string) ([]RuntimeEndpointTemplate, error)
    DesiredStateRuntimeOptions(node *Node, binding *RuntimeBinding) (map[string]any, error)
    CompileRuntimeConfiguration(node *Node, binding *RuntimeBinding, spec map[string]any) (map[string]any, error)
    RuntimeListenPort(node *Node, binding *RuntimeBinding) (int, error)
}

Implementation notes:

• The concrete Go interface may stay package-private until runtime extension becomes public API.
• RuntimeParameterSchemaJSON is the source of truth for constraints.
• RuntimeParameterField is a UI hint only.
• Adapter registration must be explicit. Unknown runtime names should fail fast.
• A registered but deferred adapter returns an empty schema and explicit unsupported errors for compile/apply paths.

5. Runtime Endpoint Templates

Endpoint is the Control Plane resource that represents how a Node/RuntimeBinding/Capability role is reached. Runtime adapters declare endpoint templates; generic Control Plane data logic reconciles those templates into Endpoint rows.

Endpoint fields:

The compiler must consume resolved endpoints. It must not infer runtime reachability from Node hostname, public_address, or reported_address.

Current sing-box template:

runtime: sing-box
role: traffic.exit
purpose: inter_node_proxy
protocol: mixed
network: tcp
port: runtime.proxy.listen_port

When sing-box Traffic Entry compiles a route to this endpoint, it emits a sing-box socks outbound because sing-box's mixed inbound accepts SOCKS-compatible traffic. socks is a sing-box compiler mapping, not an OrbitMesh endpoint protocol.

6. Runtime Status Contract

Every Edge Runtime adapter must report a normalized heartbeat record for each runtime binding it owns.

Required heartbeat fields:

Control Plane persists these fields on runtime_bindings:

Adapters must not write binding_status. That field is desired topology state, not observed runtime state.

7. Runtime Configuration Model

Runtime configuration is split into three explicit layers:

Runtime adapters must not read runtime input from node attributes. They read only the selected runtime binding values and compile a manifest for that binding.

8. Runtime Parameter Schema

Runtime parameter constraints must be expressed through JSON Schema.

Allowed schema features for MVP extension:

• type.
• properties.
• required.
• additionalProperties.
• enum.
• default.
• minimum.
• maximum.
• minLength.
• arrays with items.
• nested objects.

Console field metadata may describe presentation:

• key/path.
• label.
• kind.
• group.
• order.
• description.
• reload or restart requirement.

It must not duplicate schema constraints such as enum options, default values, min/max, or required rules.

9. Console Dynamic Form Requirements

The current console form handles a flat runtime.* parameter set.

Before implementing Traefik or Tailscale runtime parameters, the console should support recursive rendering from JSON Schema:

• object groups.
• nested object paths.
• arrays of strings or objects.
• enum selects.
• boolean toggles.
• integer and string inputs.
• schema defaults.
• required field validation.
• unknown field preservation or explicit removal policy.

Recommended form path convention:

runtime.proxy.listen_port
runtime.metrics.listen_port
runtime.log.level
runtime.entry_points.web.address
runtime.advertise_routes[0]

The final serialization must write one values_json object owned by the selected runtime binding.

10. Traefik Adapter Plan

Traefik is the preferred Gateway Capability adapter after the Traffic MVP because it maps naturally to HTTP/TCP/UDP ingress, routing, TLS, and load balancing workflows.

Initial value groups:

runtime.entry_points.web.address
runtime.entry_points.websecure.address
runtime.providers.file.enabled
runtime.certificates_resolvers.default.acme.email
runtime.certificates_resolvers.default.acme.storage
runtime.dashboard.enabled
runtime.log.level
runtime.access_log.enabled

Open design decisions:

• Whether Traefik runtime configuration is stored as JSON, YAML, or TOML.
• Whether static and dynamic configuration are one RuntimeConfiguration document or separate files.
• How TLS certificates and ACME storage are represented as secret references.
• Whether dashboard exposure is always private or can be published through OrbitMesh policy.
• How Traefik service discovery maps to OrbitMesh traffic policies.

Deferred implementation steps:

1. Add Traefik JSON Schema.
2. Add console recursive schema rendering.
3. Compile static Traefik config.
4. Compile dynamic Traefik route/service config.
5. Add Edge Runtime apply support for Traefik.
6. Add health probes for Traefik process and dashboard/API.
7. Add end-to-end test using a local Traefik container or binary.

11. Tailscale Adapter Plan

Tailscale support should be treated as a distinct network runtime, not as a sing-box variant.

Initial value groups:

runtime.hostname
runtime.auth.key_ref
runtime.oauth.client_id_ref
runtime.oauth.client_secret_ref
runtime.accept_routes
runtime.advertise_routes
runtime.exit_node.enabled
runtime.exit_node.allow_lan_access
runtime.advertise_tags

Open design decisions:

• Whether OrbitMesh owns Tailscale auth keys or only references external secrets.
• Whether one Node maps to one Tailscale node identity.
• How Tailscale ACL tags map to OrbitMesh tenant and node ownership.
• Whether subnet router and exit node modes are mutually exclusive.
• How route approval and key expiry are represented in Node, Capability Binding, and Runtime Binding status.

Deferred implementation steps:

1. Add Tailscale JSON Schema.
2. Add secret reference support for auth key or OAuth credentials.
3. Compile Tailscale local runtime options.
4. Add Edge Runtime apply support using tailscale up.
5. Add safe logout/down behavior.
6. Add health probes for daemon status and route advertisement.
7. Add integration test with a mocked local Tailscale command first.

12. Desired State and RuntimeConfiguration

Desired State remains platform-level state.

RuntimeConfiguration is adapter output and may be runtime-specific:

{
  "runtime": "traefik",
  "format": "yaml",
  "files": [
    {
      "path": "/etc/traefik/traefik.yaml",
      "content": "..."
    },
    {
      "path": "/etc/traefik/dynamic/orbitmesh.yaml",
      "content": "..."
    }
  ],
  "commands": {
    "reload": ["systemctl", "reload", "traefik"],
    "restart": ["systemctl", "restart", "traefik"]
  }
}

This shape is illustrative, not an implementation contract.

Before introducing multi-file runtime configuration, update:

• Control Plane compiler output model.
• Edge Runtime apply logic.
• checksum calculation.
• rollback storage.
• apply result reporting.

13. Edge Runtime Apply Contract

Edge Runtime adapters should eventually own:

• installation detection.
• version detection.
• config write paths.
• config validation command.
• start/reload/restart/stop behavior.
• health status.
• rollback behavior.

Runtime daemons must not expose update commands through the daemon itself. Local CLI commands should call the daemon through local API when user interaction is needed.

14. Acceptance Criteria Before Implementation

Do not mark Traefik or Tailscale runtime support as implemented until:

• JSON Schema is versioned and tested.
• Console can render and validate required nested schema paths.
• Control Plane rejects invalid runtime binding values through schema validation.
• RuntimeConfiguration output is stable and checksummed.
• Edge Runtime can apply, reload, and roll back the runtime.
• Health and version are reported to Control Plane.
• At least one integration test covers the runtime apply path.

15. Mainline Priority

New runtime adapter work is paused until the current Traffic MVP is aligned with the new model.

Recommended mainline order:

1. Align sing-box lifecycle to Node, CapabilityBinding, RuntimeBinding, Endpoint, and Subscription.
2. Complete production-safe Edge Runtime apply and rollback under the runtime binding model.
3. Improve Console workflows for existing Node and Traffic operations.
4. Add recursive schema form support.
5. Implement the next Traffic runtime only if needed.
6. Implement EasyTier, Traefik, or Tunnel adapters after the aligned Traffic MVP is stable.