// Copyright 2020-2026 Buf Technologies, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package buf.alpha.registry.v1alpha1;

import "buf/alpha/registry/v1alpha1/repository_branch.proto";
import "buf/alpha/registry/v1alpha1/repository_commit.proto";
import "buf/alpha/registry/v1alpha1/repository_tag.proto";
import "google/protobuf/timestamp.proto";

message Reference {
  reserved 4;
  reserved "track";

  oneof reference {
    // The requested reference is a branch.
    RepositoryBranch branch = 1;
    // The requested reference is a tag.
    RepositoryTag tag = 2;
    // The requested reference is a commit.
    RepositoryCommit commit = 3;
    // The requested reference is the default reference.
    RepositoryMainReference main = 5;
    // The requested reference is a draft commit.
    RepositoryDraft draft = 6;
    // The requested reference is a VCS commit.
    RepositoryVCSCommit vcs_commit = 7;
  }
}

message RepositoryMainReference {
  // Name is the configured default_branch for the repository (default: 'main').
  string name = 1;
  // The latest commit in this repository. If the repository has no commits,
  // this will be empty.
  RepositoryCommit commit = 2;
}

message RepositoryDraft {
  // The name of the draft
  string name = 1;
  // The commit this draft points to.
  RepositoryCommit commit = 2;
}

message RepositoryVCSCommit {
  // primary key, unique.
  string id = 1;
  // immutable
  google.protobuf.Timestamp create_time = 2;
  // The name of the VCS commit, e.g. for Git, it would be the Git hash.
  string name = 3;
  // The name of the BSR commit this VCS commit belongs to.
  string commit_name = 4;
}

// ReferenceService is a service that provides RPCs that allow the BSR to query
// for reference information.
service ReferenceService {
  // GetReferenceByName takes a reference name and returns the
  // reference either as main, a tag, or a commit.
  rpc GetReferenceByName(GetReferenceByNameRequest) returns (GetReferenceByNameResponse) {
    option idempotency_level = NO_SIDE_EFFECTS;
  }
}

message GetReferenceByNameRequest {
  // Optional name (if unspecified, will use the repository's default_branch).
  string name = 1;
  // Owner of the repository the reference belongs to.
  string owner = 2;
  // Name of the repository the reference belongs to.
  string repository_name = 3;
}

message GetReferenceByNameResponse {
  Reference reference = 1;
}
