service.proto raw

   1  syntax = "proto3";
   2  package orlysync.cluster.v1;
   3  option go_package = "next.orly.dev/pkg/proto/orlysync/cluster/v1;clusterv1";
   4  
   5  import "orlysync/common/v1/types.proto";
   6  
   7  // ClusterSyncService provides cluster replication with persistent state
   8  // for multi-member relay clusters
   9  service ClusterSyncService {
  10    // === Lifecycle Methods ===
  11  
  12    // Ready returns whether the service is ready to serve requests
  13    rpc Ready(orlysync.common.v1.Empty) returns (orlysync.common.v1.ReadyResponse);
  14  
  15    // Start starts the cluster polling loop
  16    rpc Start(orlysync.common.v1.Empty) returns (orlysync.common.v1.Empty);
  17  
  18    // Stop stops the cluster polling loop
  19    rpc Stop(orlysync.common.v1.Empty) returns (orlysync.common.v1.Empty);
  20  
  21    // === HTTP Proxy Handlers ===
  22    // These allow the main relay to delegate HTTP cluster endpoints to this service
  23  
  24    // HandleLatestSerial proxies GET /cluster/latest HTTP requests
  25    rpc HandleLatestSerial(orlysync.common.v1.HTTPRequest) returns (orlysync.common.v1.HTTPResponse);
  26  
  27    // HandleEventsRange proxies GET /cluster/events HTTP requests
  28    rpc HandleEventsRange(orlysync.common.v1.HTTPRequest) returns (orlysync.common.v1.HTTPResponse);
  29  
  30    // === Cluster Management ===
  31  
  32    // GetMembers returns the current cluster members
  33    rpc GetMembers(orlysync.common.v1.Empty) returns (MembersResponse);
  34  
  35    // UpdateMembership updates cluster membership
  36    rpc UpdateMembership(UpdateMembershipRequest) returns (orlysync.common.v1.Empty);
  37  
  38    // HandleMembershipEvent processes a cluster membership event (Kind 39108)
  39    rpc HandleMembershipEvent(MembershipEventRequest) returns (orlysync.common.v1.Empty);
  40  
  41    // === Status ===
  42  
  43    // GetClusterStatus returns overall cluster status
  44    rpc GetClusterStatus(orlysync.common.v1.Empty) returns (ClusterStatusResponse);
  45  
  46    // GetMemberStatus returns status for a specific member
  47    rpc GetMemberStatus(MemberStatusRequest) returns (MemberStatusResponse);
  48  
  49    // === Data Operations ===
  50  
  51    // GetLatestSerial returns the latest serial from this relay's database
  52    rpc GetLatestSerial(orlysync.common.v1.Empty) returns (LatestSerialResponse);
  53  
  54    // GetEventsInRange returns event info for a serial range
  55    rpc GetEventsInRange(EventsRangeRequest) returns (EventsRangeResponse);
  56  }
  57  
  58  // === Request/Response Messages ===
  59  
  60  // LatestSerialResponse contains the latest serial and timestamp
  61  message LatestSerialResponse {
  62    uint64 serial = 1;
  63    int64 timestamp = 2;  // Unix timestamp
  64  }
  65  
  66  // EventsRangeRequest requests events in a serial range
  67  message EventsRangeRequest {
  68    uint64 from = 1;   // Start serial (inclusive)
  69    uint64 to = 2;     // End serial (inclusive)
  70    int32 limit = 3;   // Max events to return
  71  }
  72  
  73  // EventsRangeResponse contains events in the requested range
  74  message EventsRangeResponse {
  75    repeated EventInfo events = 1;
  76    bool has_more = 2;
  77    uint64 next_from = 3;  // Next serial if has_more is true
  78  }
  79  
  80  // EventInfo contains metadata about an event
  81  message EventInfo {
  82    uint64 serial = 1;
  83    string id = 2;       // Event ID (hex)
  84    int64 timestamp = 3; // Created timestamp
  85  }
  86  
  87  // ClusterMember represents a cluster member
  88  message ClusterMember {
  89    string http_url = 1;
  90    string websocket_url = 2;
  91    uint64 last_serial = 3;
  92    int64 last_poll = 4;    // Unix timestamp
  93    string status = 5;      // "active", "error", "unknown"
  94    int32 error_count = 6;
  95  }
  96  
  97  // MembersResponse contains the list of cluster members
  98  message MembersResponse {
  99    repeated ClusterMember members = 1;
 100  }
 101  
 102  // UpdateMembershipRequest updates cluster membership
 103  message UpdateMembershipRequest {
 104    repeated string relay_urls = 1;  // List of relay URLs to add
 105  }
 106  
 107  // MembershipEventRequest contains a cluster membership event
 108  message MembershipEventRequest {
 109    orlysync.common.v1.Event event = 1;
 110  }
 111  
 112  // ClusterStatusResponse contains overall cluster status
 113  message ClusterStatusResponse {
 114    uint64 latest_serial = 1;
 115    int32 active_members = 2;
 116    int32 total_members = 3;
 117    bool propagate_privileged_events = 4;
 118    repeated ClusterMember members = 5;
 119  }
 120  
 121  // MemberStatusRequest requests status for a specific member
 122  message MemberStatusRequest {
 123    string http_url = 1;
 124  }
 125  
 126  // MemberStatusResponse contains status for a member
 127  message MemberStatusResponse {
 128    ClusterMember member = 1;
 129    bool found = 2;
 130  }
 131