service.proto raw

   1  syntax = "proto3";
   2  package orlysync.distributed.v1;
   3  option go_package = "next.orly.dev/pkg/proto/orlysync/distributed/v1;distributedv1";
   4  
   5  import "orlysync/common/v1/types.proto";
   6  
   7  // DistributedSyncService provides serial-based peer-to-peer synchronization
   8  // between relay instances using HTTP polling
   9  service DistributedSyncService {
  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    // GetInfo returns current sync service information
  16    rpc GetInfo(orlysync.common.v1.Empty) returns (orlysync.common.v1.SyncInfo);
  17  
  18    // === Sync Operations ===
  19  
  20    // GetCurrentSerial returns this relay's current serial number
  21    rpc GetCurrentSerial(CurrentRequest) returns (CurrentResponse);
  22  
  23    // GetEventIDs returns event IDs for a serial range
  24    rpc GetEventIDs(EventIDsRequest) returns (EventIDsResponse);
  25  
  26    // === HTTP Proxy Handlers ===
  27    // These allow the main relay to delegate HTTP sync endpoints to this service
  28  
  29    // HandleCurrentRequest proxies /api/sync/current HTTP requests
  30    rpc HandleCurrentRequest(orlysync.common.v1.HTTPRequest) returns (orlysync.common.v1.HTTPResponse);
  31  
  32    // HandleEventIDsRequest proxies /api/sync/event-ids HTTP requests
  33    rpc HandleEventIDsRequest(orlysync.common.v1.HTTPRequest) returns (orlysync.common.v1.HTTPResponse);
  34  
  35    // === Peer Management ===
  36  
  37    // GetPeers returns the current list of sync peers
  38    rpc GetPeers(orlysync.common.v1.Empty) returns (PeersResponse);
  39  
  40    // UpdatePeers updates the peer list
  41    rpc UpdatePeers(UpdatePeersRequest) returns (orlysync.common.v1.Empty);
  42  
  43    // IsAuthorizedPeer checks if a peer is authorized by validating its NIP-11 pubkey
  44    rpc IsAuthorizedPeer(AuthorizedPeerRequest) returns (AuthorizedPeerResponse);
  45  
  46    // GetPeerPubkey fetches the pubkey for a peer relay via NIP-11
  47    rpc GetPeerPubkey(PeerPubkeyRequest) returns (PeerPubkeyResponse);
  48  
  49    // === Serial Tracking ===
  50  
  51    // UpdateSerial updates the current serial from database
  52    rpc UpdateSerial(orlysync.common.v1.Empty) returns (orlysync.common.v1.Empty);
  53  
  54    // NotifyNewEvent notifies the service of a new event being stored
  55    rpc NotifyNewEvent(NewEventNotification) returns (orlysync.common.v1.Empty);
  56  
  57    // === Sync Control ===
  58  
  59    // TriggerSync manually triggers a sync cycle with all peers
  60    rpc TriggerSync(orlysync.common.v1.Empty) returns (orlysync.common.v1.Empty);
  61  
  62    // GetSyncStatus returns current sync status for all peers
  63    rpc GetSyncStatus(orlysync.common.v1.Empty) returns (SyncStatusResponse);
  64  }
  65  
  66  // === Request/Response Messages ===
  67  
  68  // CurrentRequest is sent to request current serial number
  69  message CurrentRequest {
  70    string node_id = 1;     // Requesting node's identity
  71    string relay_url = 2;   // Requesting relay's URL
  72  }
  73  
  74  // CurrentResponse contains the current serial number
  75  message CurrentResponse {
  76    string node_id = 1;     // Responding node's identity
  77    string relay_url = 2;   // Responding relay's URL
  78    uint64 serial = 3;      // Current serial number
  79  }
  80  
  81  // EventIDsRequest requests event IDs in a serial range
  82  message EventIDsRequest {
  83    string node_id = 1;     // Requesting node's identity
  84    string relay_url = 2;   // Requesting relay's URL
  85    uint64 from = 3;        // Start serial (inclusive)
  86    uint64 to = 4;          // End serial (inclusive)
  87  }
  88  
  89  // EventIDsResponse contains event IDs mapped to serial numbers
  90  message EventIDsResponse {
  91    map<string, uint64> event_map = 1;  // event_id (hex) -> serial
  92  }
  93  
  94  // PeersResponse contains the list of sync peers
  95  message PeersResponse {
  96    repeated string peers = 1;  // List of peer relay URLs
  97  }
  98  
  99  // UpdatePeersRequest updates the peer list
 100  message UpdatePeersRequest {
 101    repeated string peers = 1;  // New list of peer relay URLs
 102  }
 103  
 104  // AuthorizedPeerRequest checks if a peer is authorized
 105  message AuthorizedPeerRequest {
 106    string peer_url = 1;
 107    string expected_pubkey = 2;  // Expected NIP-11 pubkey
 108  }
 109  
 110  // AuthorizedPeerResponse indicates if the peer is authorized
 111  message AuthorizedPeerResponse {
 112    bool authorized = 1;
 113  }
 114  
 115  // PeerPubkeyRequest requests the pubkey for a peer
 116  message PeerPubkeyRequest {
 117    string peer_url = 1;
 118  }
 119  
 120  // PeerPubkeyResponse contains the peer's pubkey
 121  message PeerPubkeyResponse {
 122    string pubkey = 1;  // Peer's NIP-11 pubkey (hex or npub)
 123  }
 124  
 125  // NewEventNotification notifies of a new event
 126  message NewEventNotification {
 127    bytes event_id = 1;   // 32 bytes event ID
 128    uint64 serial = 2;    // Assigned serial number
 129  }
 130  
 131  // SyncStatusResponse contains sync status for all peers
 132  message SyncStatusResponse {
 133    uint64 current_serial = 1;
 134    repeated orlysync.common.v1.PeerInfo peers = 2;
 135  }
 136