Proto Contracts

1. Status

This document defines the target protobuf contract after the breaking model alignment.

Current generated proto files still contain old resources. They must be regenerated from the target contracts during implementation. Do not preserve old messages as compatibility aliases during this development phase.

2. Target Files

orbitmesh/v1/
  common.proto
  errors.proto
  auth.proto
  tenant.proto
  node.proto
  capability.proto
  runtime.proto
  endpoint.proto
  deployment.proto
  desired_state.proto
  traffic_policy.proto
  subscription.proto
  usage.proto
  health.proto
  edge_runtime.proto

3. Common Enums

Target common values:

enum CapabilityKind {
  CAPABILITY_KIND_UNSPECIFIED = 0;
  CAPABILITY_KIND_TRAFFIC = 1;
  CAPABILITY_KIND_MESH = 2;
  CAPABILITY_KIND_GATEWAY = 3;
  CAPABILITY_KIND_TUNNEL = 4;
}

enum NodeStatus {
  NODE_STATUS_UNSPECIFIED = 0;
  NODE_STATUS_PENDING = 1;
  NODE_STATUS_REGISTERED = 2;
  NODE_STATUS_ONLINE = 3;
  NODE_STATUS_DEGRADED = 4;
  NODE_STATUS_OFFLINE = 5;
  NODE_STATUS_DISABLED = 6;
  NODE_STATUS_DELETED = 7;
}

enum RuntimeBindingStatus {
  RUNTIME_BINDING_STATUS_UNSPECIFIED = 0;
  RUNTIME_BINDING_STATUS_PENDING = 1;
  RUNTIME_BINDING_STATUS_INSTALLING = 2;
  RUNTIME_BINDING_STATUS_RUNNING = 3;
  RUNTIME_BINDING_STATUS_DEGRADED = 4;
  RUNTIME_BINDING_STATUS_FAILED = 5;
  RUNTIME_BINDING_STATUS_DISABLED = 6;
  RUNTIME_BINDING_STATUS_DELETED = 7;
}

Capability role is a string value such as traffic.entry, traffic.exit, mesh.node, gateway.http, or tunnel.endpoint.

4. Node Service

service NodeService {
  rpc ListNodes(ListNodesRequest) returns (ListNodesResponse);
  rpc GetNode(GetNodeRequest) returns (Node);
  rpc DeleteNode(DeleteNodeRequest) returns (Node);
}

message Node {
  string id = 1;
  string tenant_id = 2;
  string name = 3;
  string source_type = 4;
  string status = 5;
  string provider = 6;
  string region = 7;
  string reported_address = 8;
  string last_seen_at = 9;
  repeated CapabilityBinding capability_bindings = 10;
  repeated RuntimeBinding runtime_bindings = 11;
}

5. Capability Service

service CapabilityService {
  rpc ListCapabilityBindings(ListCapabilityBindingsRequest) returns (ListCapabilityBindingsResponse);
  rpc CreateCapabilityBinding(CreateCapabilityBindingRequest) returns (CapabilityBinding);
  rpc UpdateCapabilityBinding(UpdateCapabilityBindingRequest) returns (CapabilityBinding);
}

message CapabilityBinding {
  string id = 1;
  string tenant_id = 2;
  string node_id = 3;
  string capability = 4;
  string role = 5;
  string status = 6;
  string values_json = 7;
}

6. Runtime Service

service RuntimeService {
  rpc ListRuntimeCatalog(ListRuntimeCatalogRequest) returns (ListRuntimeCatalogResponse);
  rpc ListRuntimeBindings(ListRuntimeBindingsRequest) returns (ListRuntimeBindingsResponse);
  rpc CreateRuntimeBinding(CreateRuntimeBindingRequest) returns (RuntimeBinding);
  rpc UpdateRuntimeBinding(UpdateRuntimeBindingRequest) returns (RuntimeBinding);
}

message RuntimeBinding {
  string id = 1;
  string tenant_id = 2;
  string node_id = 3;
  string capability_binding_id = 4;
  string runtime = 5;
  string role = 6;
  string status = 7;
  string values_json = 8;
  string runtime_version = 9;
}

7. Endpoint Service

service EndpointService {
  rpc ListEndpoints(ListEndpointsRequest) returns (ListEndpointsResponse);
  rpc GetEndpoint(GetEndpointRequest) returns (Endpoint);
}

message Endpoint {
  string id = 1;
  string tenant_id = 2;
  string node_id = 3;
  string capability_binding_id = 4;
  string runtime_binding_id = 5;
  string capability = 6;
  string role = 7;
  string protocol = 8;
  string domain = 9;
  int32 port = 10;
  string status = 11;
}

8. Subscription Service

service SubscriptionService {
  rpc ListProtocolCatalog(ListProtocolCatalogRequest) returns (ListProtocolCatalogResponse);
  rpc ListSubscriptionTargetCatalog(ListSubscriptionTargetCatalogRequest) returns (ListSubscriptionTargetCatalogResponse);
  rpc ListSubscriptions(ListSubscriptionsRequest) returns (ListSubscriptionsResponse);
  rpc CreateSubscription(CreateSubscriptionRequest) returns (Subscription);
  rpc RotateSubscription(RotateSubscriptionRequest) returns (Subscription);
  rpc RevokeSubscription(RevokeSubscriptionRequest) returns (Subscription);
  rpc DeleteSubscription(DeleteSubscriptionRequest) returns (Subscription);
}

service PublicSubscriptionService {
  rpc FetchSubscription(FetchSubscriptionRequest) returns (PublicSubscription);
  rpc FetchTargetSubscription(FetchTargetSubscriptionRequest) returns (PublicSubscription);
}

SubscriptionTargetCatalogEntry exposes renderer metadata and profile presets:

message SubscriptionTargetCatalogEntry {
  string target = 1;
  string display_name = 2;
  string description = 3;
  string renderer_kind = 4;
  string content_kind = 5;
  bool default_enabled = 6;
  repeated string supported_protocols = 7;
  string parameter_schema_json = 8;
  repeated SubscriptionTargetProfile profiles = 9;
}

message SubscriptionTargetProfile {
  string label = 1;
  string description = 2;
  map<string, string> params = 3;
  bool default_profile = 4;
}

9. Edge Runtime Service

service EdgeRuntimeService {
  rpc Register(RegisterRequest) returns (EdgeRuntimeRegisterResponse);
  rpc Heartbeat(HeartbeatRequest) returns (Ack);
  rpc PullDesiredState(PullDesiredStateRequest) returns (PullDesiredStateResponse);
  rpc ReportApplyResult(ReportApplyResultRequest) returns (Ack);
  rpc ReportTrafficUsage(ReportTrafficUsageRequest) returns (Ack);
  rpc ReportHealth(ReportHealthRequest) returns (Ack);
}

All Edge Runtime requests except register use node-scoped request signing.

10. Breaking Rules

• Remove target use of GatewayType.
• Remove target use of generic GatewayService.
• Remove target use of ClientConfigurationService.
• Replace public client config routes with subscription routes.
• Regenerate OpenAPI after proto migration.