proxy-pool/api/proto/controlplane/v1/controlplane.proto

syntax = "proto3";

package proxy_pool.controlplane.v1;

option go_package = "proxy-pool/gen/controlplane/v1;controlplanev1";

import "google/protobuf/duration.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";

// WorkerControlPlane distributes immutable, worker-specific snapshots. The
// gateway hot path does not call this service for individual requests.
service WorkerControlPlane {
  rpc RegisterWorker(RegisterWorkerRequest) returns (RegisterWorkerResponse);
  rpc WatchSnapshots(WatchSnapshotsRequest) returns (stream SnapshotEnvelope);
  rpc AcknowledgeSnapshot(AcknowledgeSnapshotRequest) returns (google.protobuf.Empty);
  rpc ReportOutcomes(stream OutcomeBatch) returns (ReportOutcomesResponse);
  rpc ReportRuntime(ReportRuntimeRequest) returns (ReportRuntimeResponse);
}

// CheckerControlPlane hands bounded check work to independently scalable
// checker processes. Observations are facts; only the Controller reducer may
// change authoritative proxy state.
service CheckerControlPlane {
  rpc StreamCheckTasks(StreamCheckTasksRequest) returns (stream CheckTask);
  rpc ReportObservations(ObservationBatch) returns (ReportObservationsResponse);
}

message RegisterWorkerRequest {
  string worker_id = 1;
  string instance_id = 2;
  string zone = 3;
  uint32 supported_protocol_version = 4;
  map<string, string> labels = 5;
}

message RegisterWorkerResponse {
  string worker_id = 1;
  string session_id = 2;
  uint64 ownership_epoch = 3;
  google.protobuf.Duration heartbeat_interval = 4;
  google.protobuf.Duration max_stale_age = 5;
}

message WatchSnapshotsRequest {
  string worker_id = 1;
  string session_id = 2;
  uint64 last_applied_version = 3;
  bytes last_checksum = 4;
}

message SnapshotEnvelope {
  oneof payload {
    WorkerSnapshot full = 1;
    SnapshotDelta delta = 2;
  }
}

message WorkerSnapshot {
  uint64 version = 1;
  uint64 ownership_epoch = 2;
  google.protobuf.Timestamp generated_at = 3;
  google.protobuf.Timestamp valid_until = 4;
  bytes checksum = 5;
  repeated RoutingRule routing = 6;
  repeated OwnedProxy proxies = 7;
  // Credential materials are protected by the WorkerControlPlane mTLS session
  // and retained only in the Gateway's current in-memory snapshot view.
  repeated SnapshotCredential credentials = 14;
}

message SnapshotCredential {
  string secret_ref = 1;
  string credential_version = 2;
  string username = 3;
  string password = 4;
}

message SnapshotDelta {
  uint64 base_version = 1;
  uint64 version = 2;
  uint64 ownership_epoch = 3;
  google.protobuf.Timestamp generated_at = 4;
  bytes checksum = 5;
  repeated RoutingRule upserted_routing = 6;
  repeated string removed_routing_names = 7;
  repeated OwnedProxy upserted_proxies = 8;
  repeated string removed_proxy_ids = 9;
}

message RoutingRule {
  string name = 1;
  bool enabled = 2;
  string host_regex = 3;
  repeated string methods = 4;
  string path_regex = 5;
  map<string, string> headers = 6;
  repeated string upstreams = 7;
  RoutingStrategy strategy = 8;
  UnavailableAction on_unavailable = 9;
  google.protobuf.Duration wait_timeout = 10;
  RoutingAction action = 11;
}

message RoutingStrategy {
  StrategyType type = 1;
  string current_upstream = 2;
  map<string, uint32> weights = 3;
}

enum StrategyType {
  STRATEGY_TYPE_UNSPECIFIED = 0;
  STRATEGY_TYPE_SEQUENTIAL = 1;
  STRATEGY_TYPE_RANDOM = 2;
  STRATEGY_TYPE_ROUND_ROBIN = 3;
  STRATEGY_TYPE_WEIGHTED = 4;
  STRATEGY_TYPE_LEAST_CONNECTIONS = 5;
}

enum UnavailableAction {
  UNAVAILABLE_ACTION_UNSPECIFIED = 0;
  UNAVAILABLE_ACTION_REJECT = 1;
  UNAVAILABLE_ACTION_WAIT = 2;
  UNAVAILABLE_ACTION_DIRECT = 3;
}

enum RoutingAction {
  ROUTING_ACTION_UNSPECIFIED = 0;
  ROUTING_ACTION_PROXY = 1;
  ROUTING_ACTION_DIRECT = 2;
  ROUTING_ACTION_REJECT = 3;
}

message OwnedProxy {
  string id = 1;
  string upstream = 2;
  ProxyProtocol protocol = 3;
  string host = 4;
  uint32 port = 5;
  string username = 6;
  string credential_version = 7;
  string secret_ref = 8;
  google.protobuf.Timestamp expires_at = 9;
  uint32 max_concurrency = 10;
  map<string, string> tags = 11;
  uint64 ownership_epoch = 12;
  google.protobuf.Timestamp usable_until = 13;
}

enum ProxyProtocol {
  PROXY_PROTOCOL_UNSPECIFIED = 0;
  PROXY_PROTOCOL_HTTP = 1;
  PROXY_PROTOCOL_HTTPS = 2;
  PROXY_PROTOCOL_SOCKS5 = 3;
}

message AcknowledgeSnapshotRequest {
  string worker_id = 1;
  string session_id = 2;
  uint64 version = 3;
  uint64 ownership_epoch = 4;
  bytes checksum = 5;
  bool applied = 6;
  string error_code = 7;
  string error_message = 8;
}

message OutcomeBatch {
  string worker_id = 1;
  string session_id = 2;
  uint64 sequence = 3;
  repeated ProxyOutcome outcomes = 4;
}

message ProxyOutcome {
  string proxy_id = 1;
  string routing_name = 2;
  OutcomeStage stage = 3;
  bool success = 4;
  google.protobuf.Duration latency = 5;
  string error_class = 6;
  google.protobuf.Timestamp observed_at = 7;
}

enum OutcomeStage {
  OUTCOME_STAGE_UNSPECIFIED = 0;
  OUTCOME_STAGE_DIAL = 1;
  OUTCOME_STAGE_PROXY_HANDSHAKE = 2;
  OUTCOME_STAGE_RESPONSE_HEADERS = 3;
  OUTCOME_STAGE_TUNNEL = 4;
}

message ReportOutcomesResponse {
  uint64 accepted_through_sequence = 1;
}

message ReportRuntimeRequest {
  string worker_id = 1;
  string session_id = 2;
  uint64 snapshot_version = 3;
  uint64 ownership_epoch = 4;
  repeated ProxyRuntime counters = 5;
  google.protobuf.Timestamp observed_at = 6;
  uint64 report_sequence = 7;
}

message ProxyRuntime {
  string proxy_id = 1;
  uint32 reserved = 2;
  uint32 active = 3;
  bool draining = 4;
}

message ReportRuntimeResponse {
  uint64 accepted_ownership_epoch = 1;
  repeated string revoke_proxy_ids = 2;
  bool require_full_snapshot = 3;
}

message StreamCheckTasksRequest {
  string checker_id = 1;
  string instance_id = 2;
  uint32 max_in_flight = 3;
  repeated CheckLevel supported_levels = 4;
}

message CheckTask {
  string task_id = 1;
  string proxy_id = 2;
  ProxyProtocol protocol = 3;
  string host = 4;
  uint32 port = 5;
  string secret_ref = 6;
  CheckLevel level = 7;
  string routing_name = 8;
  string target_url = 9;
  google.protobuf.Duration timeout = 10;
  uint32 attempt = 11;
  google.protobuf.Timestamp deadline = 12;
  // Credential material is delivered only over the authenticated Checker mTLS
  // stream and must be retained only for this task's lifetime.
  string username = 13;
  string password = 14;
  string credential_version = 15;
  uint32 max_attempts = 16;
  string lease_token = 17;
}

enum CheckLevel {
  CHECK_LEVEL_UNSPECIFIED = 0;
  CHECK_LEVEL_BASIC = 1;
  CHECK_LEVEL_EGRESS = 2;
  CHECK_LEVEL_TARGET = 3;
}

message ObservationBatch {
  string checker_id = 1;
  repeated HealthObservation observations = 2;
}

message HealthObservation {
  string task_id = 1;
  string proxy_id = 2;
  CheckLevel level = 3;
  string routing_name = 4;
  string target_url = 5;
  bool success = 6;
  string failure_class = 7;
  google.protobuf.Duration latency = 8;
  string observed_egress_ip = 9;
  google.protobuf.Timestamp observed_at = 10;
  string lease_token = 11;
}

message ReportObservationsResponse {
  uint32 accepted = 1;
  uint32 rejected = 2;
}