Add buf.registry.descriptor.v1 package

buf/registry/descriptor/v1/file_descriptor_proto_extension.proto

@@ -0,0 +1,74 @@
+// Copyright 2023-2024 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.registry.descriptor.v1;
+
+import "buf/registry/priv/extension/v1beta1/extension.proto";
+import "buf/validate/validate.proto";
+
+option go_package = "buf.build/gen/go/bufbuild/registry/protocolbuffers/go/buf/registry/descriptor/v1";
+
+// Additional information about a FileDescriptorProto.
+//
+// FileDescriptoProtos are not extendable, so we choose to sideband this information as opposed
+// to creating a new FileDescriptoProto type, so that the FileDescriptorProtoService can return
+// standard FileDescriptorProtos that most expect.
+message FileDescriptorProtoExtension {
+  option (buf.registry.priv.extension.v1beta1.message).response_only = true;
+
+  // The id of the Commit that the file was created from.
+  //
+  // If the file was created from a Well-Known Type, this will point to
+  // a Commit within a Module that contains only the Well-Known Types. For the public BSR,
+  // this is currently buf.build/protocolbuffers/wellknowntypes.
+  string commit_id = 1 [
+    (buf.validate.field).required = true,
+    (buf.validate.field).string.tuuid = true
+  ];
+  // Whether or not the file is an import.
+  //
+  // A file is an import if:
+  //
+  //   - It comes from a dependency of the Module specified via the ResourceRef used in the request.
+  //     For example, if the ResourceRef specifies "buf.build/foo/bar", which depends on
+  //     "buf.build/foo/baz", all files from "buf.build/foo/baz" will be imports.
+  //   - It is a Well-Known Type, and the Well-Known Type was not part of the Module specified
+  //     via the ResourceRef used in the request. Well-Known Types are special in the Protobuf ecosystem,
+  //     and can be imported without being contained in a specified module.
+  //   - It contains symbols that are referenced by symbols specified in the request. For example,
+  //     if the request specified symbol "foo.v1.Foo" contained within "foo.proto", , which has a message
+  //     field of type "baz.v1.Baz", which is contained within "baz.proto", the the file "baz.proto"
+  //     will be marked as an import, regardless of which Module it derived from. If the symbols field
+  //     is not specified on the request, this situation will never occur.
+  //
+  // If exclude_imports was specified on the request, no FileDescriptorProtos will be imports.
+  bool is_import = 2;
+  // The explicitly-specified syntax within the file.
+  //
+  // If the syntax field is not set within a file, this is interpreted as the syntax "proto2".
+  // The protoc compiler does not set the syntax field if the syntax was "proto2", regardless of if
+  // the syntax was explicitly specified or not. This prevents programs (such as linters) from
+  // determining whether or not a syntax was explicitly specified within a file
+  //
+  // As opposed to syntax on a FileDescriptorProto, this field will be empty if no syntax was
+  // explicitly specified, and "proto2" if "proto2" was explicitly specified. Otherwise, this
+  // field matches the semantics of the syntax field on FileDescriptorProtos.
+  string specified_syntax = 3;
+  // The indexes within the dependency field on the FileDescriptorProto that are not used.
+  //
+  // The matches the shape of the public_dependency and weak_dependency fields on FileDescriptorProto.
+  repeated int32 unused_dependency = 4;
+}

buf/registry/descriptor/v1/file_descriptor_proto_service.proto

@@ -0,0 +1,130 @@
+// Copyright 2023-2024 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.registry.descriptor.v1;
+
+import "buf/registry/descriptor/v1/file_descriptor_proto_extension.proto";
+import "buf/registry/module/v1/resource.proto";
+import "buf/validate/validate.proto";
+import "google/protobuf/compiler/plugin.proto";
+import "google/protobuf/descriptor.proto";
+import "google/protobuf/field_mask.proto";
+
+option go_package = "buf.build/gen/go/bufbuild/registry/protocolbuffers/go/buf/registry/descriptor/v1";
+
+// Provide compiled FileDescriptorProtos for Modules, Labels, or Commits.
+service FileDescriptorProtoService {
+  // Get compiled FileDescriptorProtos for the given Module, Label, or Commit.
+  rpc GetFileDescriptorProtos(GetFileDescriptorProtosRequest) returns (GetFileDescriptorProtosResponse) {
+    option idempotency_level = NO_SIDE_EFFECTS;
+  }
+}
+
+message GetFileDescriptorProtosRequest {
+  // The reference to get FileDescriptorProtos for.
+  //
+  // See the documentation on ResourceRef for resource resolution details.
+  //
+  // Once the resource is resolved, the following content is returned:
+  //   - If a Module is referenced, the FileDescriptorProtos for the Commit of the default Label is returned.
+  //   - If a Label is referenced, the FileDescriptorProtos for the Commit of this Label is returned.
+  //   - If a Commit is referenced, the FileDescriptorProtos for this Commit is returned.
+  buf.registry.module.v1.ResourceRef resource_ref = 1 [(buf.validate.field).required = true];
+  // Exclude imports from the returned FileDescriptorProtos.
+  //
+  // A file is an import if:
+  //
+  //   - It comes from a dependency of the Module specified via the ResourceRef used in the request.
+  //     For example, if the ResourceRef specifies "buf.build/foo/bar", which depends on
+  //     "buf.build/foo/baz", all files from "buf.build/foo/baz" will be imports.
+  //   - It is a Well-Known Type, and the Well-Known Type was not part of the Module specified
+  //     via the ResourceRef used in the request. Well-Known Types are special in the Protobuf ecosystem,
+  //     and can be imported without being contained in a specified module.
+  //   - It contains symbols that are referenced by symbols specified in the request. For example,
+  //     if the request specified symbol "foo.v1.Foo" contained within "foo.proto", , which has a message
+  //     field of type "baz.v1.Baz", which is contained within "baz.proto", the the file "baz.proto"
+  //     will be marked as an import, regardless of which Module it derived from. If the symbols field
+  //     is not specified on the request, this situation will never occur.
+  //
+  // Note that if imports are excluded, the returned FileDescriptorProtos may not (and likely will not)
+  // be self-contained. If imports are included, all symbols referenced within the FileDescriptorProtos
+  // are contained within the returned FileDescriptorProtos.
+  bool exclude_imports = 2;
+  // Exclude SourceCodeInfo from the returned FileDescriptorProtos.
+  //
+  // SourceCodeInfo is optional additional information that is not required to describe a set
+  // of Protobuf APIs.
+  bool exclude_source_code_info = 3;
+  // Exclude source-retention options from the returned FileDescriptorProtos.
+  //
+  // With the new Editions work, options are either runtime-retention or source-retention.
+  // Setting this option will exclude the latter.
+  bool exclude_source_retention_options = 4;
+  // Exclude FileDescriptorProtoExtensions from the response.
+  //
+  // FileDescriptorProtoExtensions contain additional information about FileDescriptorProtos.
+  // We include this information in a separate message as FileDescriptorProtos are not
+  // extendable, and we do not want to modify the FileDescriptorProto shape.
+  bool exclude_file_descriptor_proto_extensions = 5;
+  // Only include specific symbols (and symbols that they reference, if exclude_imports is not set).
+  //
+  // A symbol is a package, message, enum, service, method, or extension.
+  //
+  // Symbols are referenced by their fully-qualified name. For example, if "Foo" is a message within
+  // the package "foo.v1", the fully-qualified name is "foo.v1.Foo". Fully-qualfied names should
+  // not start with a period, that is specify "foo.v1.Foo", not ".foo.v1.Foo".
+  //
+  // If no symbols are provided, all symbols are returned.
+  repeated string symbols = 6;
+  // An explicit, opt-in field mask for the fields populated on the returned FileDescriptorProtos.
+  //
+  // For example, if you would only like to return the names of messages, use the mask:
+  //
+  //   {
+  //     paths: [
+  //       "message_type.name",
+  //       "message_type.nested_type.name"
+  //     ]
+  //   }
+  //
+  // The filters exclude_imports, exclude_source_code_info, exclude_source_retention_options and
+  // symbols continue to be respected even if this field is set. Specifically, if exclude_source_code_info
+  // is set, but this mask includes source_code_info, SourceCodeInfo will continue to be excludeded.
+  google.protobuf.FieldMask field_mask = 7;
+}
+
+message GetFileDescriptorProtosResponse {
+  option (buf.validate.message).cel = {
+    id: "len_file_descriptor_protos_equals_len_extensions",
+    message: "the length of file_descriptor_protos must equal the length of file_descriptor_proto_extensions if file_descriptor_proto_extensions is present",
+    expression: "this.file_descriptor_proto_extensions.size() == 0 || this.file_descriptor_protos.size() == this.file_descriptor_proto_extensions.size()"
+  };
+
+  // The FileDescriptorProtos representing the referenced Module, Label, or Commit.
+  repeated google.protobuf.FileDescriptorProto file_descriptor_protos = 1 [(buf.validate.field).required = true];
+  // Additional information about each FileDescriptorProto.
+  //
+  // We include this information in a separate message as FileDescriptorProtos are not
+  // extendable, and we do not want to modify the FileDescriptorProto shape.
+  //
+  // If present, the length of this field will be equal to the length of the file_descriptor_protos field, and each
+  // value corresponds to its corresponding value at the same index within file_descriptor_protos.
+  repeated FileDescriptorProtoExtension file_descriptor_proto_extensions = 2;
+  // The version of the compiler used to create the FileDescriptorProtos.
+  //
+  // This will match the semantics used within CodeGeneratorRequests.
+  google.protobuf.compiler.Version compiler_version = 3 [(buf.validate.field).required = true];
+}