// SPDX-License-Identifier: MIT

syntax = "proto3";

package ermite;

import "google/protobuf/field_mask.proto";
import "ermite/types.proto";
import "google/protobuf/timestamp.proto";

// Visibility says who may read a repository.
enum Visibility {
  // Not set. In requests, the server applies its default (private on create,
  // unchanged on update). Never returned by the server.
  VISIBILITY_UNSPECIFIED = 0;
  // Anyone, including anonymous callers, may read the repository.
  VISIBILITY_PUBLIC = 1;
  // Only callers holding the repo:read scope on the repository may read it.
  // Everyone else gets not_found, never permission_denied.
  VISIBILITY_PRIVATE = 2;
}

// IssuesMode says who may write issues in a repository.
enum IssuesMode {
  // Not set.
  ISSUES_MODE_UNSPECIFIED = 0;
  // Issues are disabled.
  ISSUES_MODE_OFF = 1;
  // Only the owner may write issues.
  ISSUES_MODE_OWNER = 2;
  // Issues are open to public participation.
  ISSUES_MODE_PUBLIC = 3;
}

// RepoSettings are the settings of a repository that govern its merge
// requests and issues.
message RepoSettings {
  // AllowedMergeModes are the modes with which a merge request of the
  // repository may be merged. It is never empty in a response and has no
  // duplicate. Every mode is allowed by default. MERGE_MODE_UNSPECIFIED is
  // rejected.
  repeated MergeMode allowed_merge_modes = 1;
  // FailingChecksBlock is unused: servers ignore it and never set it. A merge
  // needs passing checks unless MergeMergeRequestRequest.ignore_checks is set.
  bool failing_checks_block = 2 [deprecated = true];
  // Issues is the issue participation mode of the repository.
  IssuesMode issues = 3;
  // AllowAutoMerge says whether auto-merge can be enabled on the merge requests
  // of the repository (see MergeRequestService.EnableAutoMerge). It is false by
  // default. Set only by servers with the "merge_requests.auto_merge" feature.
  bool allow_auto_merge = 4;
}

// Repo is the metadata of a repository. Git-owned state (refs, trees, history)
// is read through GitService.
message Repo {
  // Name is the unique, lowercase repository name: 1-100 characters from
  // [a-z0-9._-], without a ".git" suffix. It is also the URL path: /<name>.
  string name = 1;
  // Description is a free one-line description. It may be empty.
  string description = 2;
  // Visibility is who may read the repository.
  Visibility visibility = 3;
  // DefaultBranch is the short name of the branch HEAD points to, for example
  // "main". It is set even when the branch does not exist yet (empty
  // repository).
  string default_branch = 4;
  // CreatedAt is when the repository was created.
  google.protobuf.Timestamp created_at = 5;
  // PushedAt is the time of the last push. It is unset until the first push.
  google.protobuf.Timestamp pushed_at = 6;
  // Settings are the settings of the repository. Always set in a
  // response, with the defaults for a repository that never changed them.
  RepoSettings settings = 7;
  // Topics classify the repository, as on GitHub: at most 20, each 1-50
  // characters from [a-z0-9-], starting with a letter or a digit, sorted
  // and without duplicates.
  repeated string topics = 8;
}

// RepoService manages repositories and their metadata.
//
// Anonymous callers see public repositories only. A private repository that the
// caller cannot read is reported as not_found.
service RepoService {
  // ListRepos lists the repositories the caller may see, ordered by name.
  rpc ListRepos(ListReposRequest) returns (ListReposResponse);
  // GetRepo returns one repository. Fails with not_found if it does not exist
  // or is private and not readable by the caller.
  rpc GetRepo(GetRepoRequest) returns (GetRepoResponse);
  // CreateRepo creates an empty repository with the default settings. Needs
  // the repo:write scope. Fails
  // with already_exists if the name is taken and invalid_argument if the name
  // is not valid.
  rpc CreateRepo(CreateRepoRequest) returns (CreateRepoResponse);
  // UpdateRepo changes the fields named in update_mask, including the merge
  // settings. Needs the repo:admin scope.
  rpc UpdateRepo(UpdateRepoRequest) returns (UpdateRepoResponse);
  // DeleteRepo deletes a repository. Needs the repo:admin scope. The server
  // moves the data aside rather than destroying it; there is no undelete RPC.
  rpc DeleteRepo(DeleteRepoRequest) returns (DeleteRepoResponse);
}

// ListReposRequest selects a page of repositories.
message ListReposRequest {
  // PageSize is the maximum number of repositories to return. 0 means the
  // server default; values above the server maximum are lowered to it.
  int32 page_size = 1;
  // PageToken is the next_page_token of a previous response, to get the page
  // after it. Empty for the first page.
  string page_token = 2;
}

// ListReposResponse is one page of repositories.
message ListReposResponse {
  // Repos are the repositories of this page, ordered by name.
  repeated Repo repos = 1;
  // NextPageToken is passed as page_token to get the next page. Empty when
  // there is no next page.
  string next_page_token = 2;
}

// GetRepoRequest names the repository to read.
message GetRepoRequest {
  // Repo is the repository name.
  string repo = 1;
}

// GetRepoResponse holds the repository.
message GetRepoResponse {
  // Repo is the repository metadata.
  Repo repo = 1;
}

// CreateRepoRequest describes the repository to create.
message CreateRepoRequest {
  // Name is the name of the new repository. Names are lowercase; an uppercase
  // name is rejected with invalid_argument.
  string name = 1;
  // Description is an optional one-line description.
  string description = 2;
  // Visibility of the new repository. VISIBILITY_UNSPECIFIED means private.
  Visibility visibility = 3;
  // Topics are the optional topics of the new repository (see Repo.topics);
  // they are lowercased, sorted and deduplicated.
  repeated string topics = 4;
}

// CreateRepoResponse holds the new repository.
message CreateRepoResponse {
  // Repo is the created repository.
  Repo repo = 1;
}

// UpdateRepoRequest changes some fields of a repository.
message UpdateRepoRequest {
  // Repo is the name of the repository to change. Repositories cannot be
  // renamed.
  string repo = 1;
  // Description is the new description. Used only if update_mask contains
  // "description"; an empty value then clears it.
  string description = 2;
  // Visibility is the new visibility. Used only if update_mask contains
  // "visibility"; it must not be VISIBILITY_UNSPECIFIED then.
  Visibility visibility = 3;
  // DefaultBranch is the short name of the new default branch. Used only if
  // update_mask contains "default_branch". The branch must exist, otherwise
  // the call fails with failed_precondition.
  string default_branch = 4;
  // UpdateMask lists the fields to change: "description", "visibility",
  // "default_branch", "topics", "settings.allowed_merge_modes" and/or
  // "settings.allow_auto_merge". "settings" stands for the two merge settings
  // paths. It must not be empty unless issues is set. Other paths are
  // invalid_argument, including "settings.issues" and "issues": the issues
  // field is applied outside the mask.
  google.protobuf.FieldMask update_mask = 5;
  // Settings holds the new merge settings. Only the fields named in
  // update_mask are used. allowed_merge_modes must then not be empty nor
  // contain MERGE_MODE_UNSPECIFIED, otherwise the call fails with
  // invalid_argument. Changing settings needs the repo:admin scope, like any
  // other field.
  RepoSettings settings = 6;
  // Topics replace the topics of the repository (see Repo.topics). Used only
  // if update_mask contains "topics"; an empty list then clears them.
  repeated string topics = 7;
  // Issues is the new issue participation mode. When absent it is unchanged.
  // It is applied whatever update_mask contains, and may be the only change
  // (an empty update_mask is then valid). When present it must not be
  // ISSUES_MODE_UNSPECIFIED: that is invalid_argument. Changing it needs the
  // repo:admin scope and a token with no branch limit, like any other field.
  optional IssuesMode issues = 8;
}

// UpdateRepoResponse holds the repository after the update.
message UpdateRepoResponse {
  // Repo is the updated repository.
  Repo repo = 1;
}

// DeleteRepoRequest names the repository to delete.
message DeleteRepoRequest {
  // Repo is the repository name.
  string repo = 1;
}

// DeleteRepoResponse is empty.
message DeleteRepoResponse {}