appks/proto/this/repo.proto

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);
}