chore(infra): add gRPC layer, update protobufs, remove immediate module

- Add gRPC service modules: auth, channel, channel settings, member, permission - Update protobuf definitions and generated code - Remove immediate/ real-time module (superseded by IM service) - Update etcd discovery and registration - Update cache, error, config, and build infrastructure - Add ADR documentation - Update OpenAPI spec
2026-06-10 18:49:42 +08:00
parent 9eb77ab98b
commit 1000f8a80d
57 changed files with 22524 additions and 2703 deletions
@@ -0,0 +1,247 @@
+syntax = "proto3";
+
+package appks.v1;
+
+import "google/protobuf/timestamp.proto";
+
+// Repository-related services for gitshell.
+// gitshell calls these RPCs to:
+//   1. Check branch protection rules before accepting a push.
+//   2. Locate which storage node hosts a given repository.
+//   3. Verify user/agent permissions on a repository.
+//   4. Acquire / release push locks for concurrency control.
+
+// ── Enums ──────────────────────────────────────────────────────────────
+
+enum PushLockStatus {
+  PUSH_LOCK_STATUS_UNSPECIFIED = 0;
+  PUSH_LOCK_STATUS_QUEUED = 1;
+  PUSH_LOCK_STATUS_ACTIVE = 2;
+  PUSH_LOCK_STATUS_FINISHED = 3;
+  PUSH_LOCK_STATUS_FAILED = 4;
+}
+
+enum MergeStrategy {
+  MERGE_STRATEGY_UNSPECIFIED = 0;
+  MERGE_STRATEGY_MERGE = 1;
+  MERGE_STRATEGY_SQUASH = 2;
+  MERGE_STRATEGY_REBASE = 3;
+  MERGE_STRATEGY_FAST_FORWARD = 4;
+}
+
+// ── Branch Protection ──────────────────────────────────────────────────
+
+message BranchProtectionRule {
+  string id = 1;
+  string repo_id = 2;
+  string pattern = 3;
+  int32 require_approvals = 4;
+  bool require_status_checks = 5;
+  repeated string required_status_checks = 6;
+  bool require_linear_history = 7;
+  bool allow_force_pushes = 8;
+  bool allow_deletions = 9;
+  bool require_signed_commits = 10;
+  bool require_code_owner_review = 11;
+  bool dismiss_stale_reviews = 12;
+  bool restrict_pushes = 13;
+  repeated string push_allowances = 14;
+  bool restrict_review_dismissal = 15;
+  repeated string dismissal_allowances = 16;
+  bool require_conversation_resolution = 17;
+}
+
+message CheckBranchProtectionRequest {
+  string workspace_name = 1;
+  string repo_name = 2;
+  string branch_name = 3;
+  // The user attempting the push (for push-allowance checks).
+  optional string user_id = 4;
+}
+
+message CheckBranchProtectionResponse {
+  bool protected = 1;
+  BranchProtectionRule rule = 2;
+  // Human-readable reasons why the push would be blocked.
+  repeated string block_reasons = 3;
+  // Whether the given user is exempt (in push_allowances).
+  bool user_allowed = 4;
+}
+
+// ── Repository Locate ─────────────────────────────────────────────────
+
+message StorageNode {
+  string node_id = 1;
+  string address = 2;
+  // Labels for routing decisions (e.g. region, disk-type).
+  map<string, string> labels = 3;
+  bool healthy = 4;
+}
+
+message LocateRepositoryRequest {
+  string workspace_name = 1;
+  string repo_name = 2;
+}
+
+message LocateRepositoryResponse {
+  bool found = 1;
+  string repo_id = 2;
+  // The storage path on the node (e.g. "ab/cd/12345.git").
+  string storage_path = 3;
+  // Primary storage node that hosts the repository.
+  StorageNode primary_node = 4;
+  // Additional replica / failover nodes.
+  repeated StorageNode replica_nodes = 5;
+}
+
+// ── Permission Check ──────────────────────────────────────────────────
+
+message PermissionScope {
+  string scope = 1;         // e.g. "repo:read", "repo:write"
+  optional string resource = 2; // e.g. specific repo name if scoped
+}
+
+message CheckRepoPermissionRequest {
+  string workspace_name = 1;
+  string repo_name = 2;
+  // The principal to check — either a user_id or a deploy_key_id.
+  oneof principal {
+    string user_id = 3;
+    string deploy_key_id = 4;
+  }
+  // The required permission level.
+  string required_permission = 5;
+}
+
+message CheckRepoPermissionResponse {
+  bool allowed = 1;
+  // The actual resolved permission (may be higher than required).
+  string resolved_permission = 2;
+  // If not allowed, a human-readable reason.
+  string reason = 3;
+}
+
+// ── Push Lock ──────────────────────────────────────────────────────────
+
+message PushLock {
+  string id = 1;
+  string repo_id = 2;
+  string pusher_id = 3;
+  string ref_name = 4;
+  PushLockStatus status = 5;
+  int32 queue_position = 6;
+  google.protobuf.Timestamp queued_at = 7;
+  google.protobuf.Timestamp started_at = 8;
+  google.protobuf.Timestamp finished_at = 9;
+  string storage_node_id = 10;
+  string lease_token = 11;
+  string error_message = 12;
+}
+
+message AcquirePushLockRequest {
+  string workspace_name = 1;
+  string repo_name = 2;
+  string ref_name = 3;
+  string pusher_id = 4;
+}
+
+message AcquirePushLockResponse {
+  bool acquired = 1;
+  PushLock lock = 2;
+  // If not immediately acquired, estimated wait in seconds.
+  int32 estimated_wait_seconds = 3;
+  string error = 4;
+}
+
+message ReleasePushLockRequest {
+  string lock_id = 1;
+  // Must match the lease_token from AcquirePushLock.
+  string lease_token = 2;
+  // Whether the push succeeded.
+  bool success = 3;
+  optional string error_message = 4;
+}
+
+message ReleasePushLockResponse {
+  bool released = 1;
+  string error = 2;
+}
+
+message GetPushLockRequest {
+  string lock_id = 1;
+}
+
+message GetPushLockResponse {
+  PushLock lock = 1;
+}
+
+message ListPushLocksRequest {
+  string workspace_name = 1;
+  string repo_name = 2;
+  // Filter by status; if unspecified, returns all active locks.
+  optional PushLockStatus status = 3;
+}
+
+message ListPushLocksResponse {
+  repeated PushLock locks = 1;
+}
+
+// ── Repository Metadata ───────────────────────────────────────────────
+
+message RepoInfo {
+  string id = 1;
+  string workspace_id = 2;
+  string owner_id = 3;
+  string name = 4;
+  optional string description = 5;
+  string default_branch = 6;
+  string visibility = 7;
+  string status = 8;
+  bool is_fork = 9;
+  optional string forked_from_repo_id = 10;
+  string storage_path = 11;
+  string git_service = 12;
+  google.protobuf.Timestamp archived_at = 13;
+  google.protobuf.Timestamp created_at = 14;
+  google.protobuf.Timestamp updated_at = 15;
+}
+
+message GetRepoInfoRequest {
+  string workspace_name = 1;
+  string repo_name = 2;
+}
+
+message GetRepoInfoResponse {
+  bool found = 1;
+  RepoInfo repo = 2;
+}
+
+// ── Service ────────────────────────────────────────────────────────────
+
+service RepoService {
+  // ── Branch Protection ──
+  // Check whether a branch is protected and whether a push is allowed.
+  rpc CheckBranchProtection(CheckBranchProtectionRequest) returns (CheckBranchProtectionResponse);
+
+  // ── Repository Locate ──
+  // Find which storage node(s) host a repository.
+  rpc LocateRepository(LocateRepositoryRequest) returns (LocateRepositoryResponse);
+
+  // ── Permission Check ──
+  // Verify that a user or deploy key has the required permission on a repo.
+  rpc CheckRepoPermission(CheckRepoPermissionRequest) returns (CheckRepoPermissionResponse);
+
+  // ── Push Lock ──
+  // Acquire an exclusive push lock for a ref.
+  rpc AcquirePushLock(AcquirePushLockRequest) returns (AcquirePushLockResponse);
+  // Release a previously acquired push lock.
+  rpc ReleasePushLock(ReleasePushLockRequest) returns (ReleasePushLockResponse);
+  // Get the current state of a push lock.
+  rpc GetPushLock(GetPushLockRequest) returns (GetPushLockResponse);
+  // List active push locks for a repository.
+  rpc ListPushLocks(ListPushLocksRequest) returns (ListPushLocksResponse);
+
+  // ── Repository Metadata ──
+  // Get lightweight repository metadata (for gitshell to resolve repo names).
+  rpc GetRepoInfo(GetRepoInfoRequest) returns (GetRepoInfoResponse);
+}