Add initial Plugin specification (#132)

buf.lock

@@ -1,6 +1,9 @@
 # Generated by buf. DO NOT EDIT.
 version: v2
 deps:
+  - name: buf.build/bufbuild/bufplugin
+    commit: 42bdb4b676254830a221d52d10bf17be
+    digest: b5:c9fb96550e52b1b899f667d2371d2aee37b4b5b0d8e21d83dd620207d466f3a95b96fc072fe9a49785da293f1fe379f0b4ac8ce054b6a1cedcafba8f2145d086
   - name: buf.build/bufbuild/protovalidate
     commit: b983156c5e994cc9892e0ce3e64e17e0
     digest: b5:a02a4a5a0a9306cf1391d17e8811bbd6a0dbd0e0e29ddfc34b9d103311164974472d43627c3d63e6a8abaffd6c7a301c4f7965bbab2dc56f7f7812429a84b812

buf.yaml

@@ -1,6 +1,7 @@
 version: v2
 name: buf.build/bufbuild/registry
 deps:
+  - buf.build/bufbuild/bufplugin
   - buf.build/bufbuild/protovalidate
 lint:
   use:

buf/registry/plugin/v1beta1/collection.proto

@@ -0,0 +1,65 @@
+// 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.plugin.v1beta1;
+
+import "buf/registry/priv/extension/v1beta1/extension.proto";
+import "buf/validate/validate.proto";
+import "google/protobuf/timestamp.proto";
+
+option go_package = "buf.build/gen/go/bufbuild/registry/protocolbuffers/go/buf/registry/plugin/v1beta1";
+
+// A collection for a Plugin.
+//
+// These collections help organize plugins based on their functionality or ecosystem.
+message Collection {
+  option (buf.registry.priv.extension.v1beta1.message).response_only = true;
+
+  // The id of the Collection.
+  string id = 1 [
+    (buf.validate.field).required = true,
+    (buf.validate.field).string.tuuid = true
+  ];
+  // The time the Collection was created on the BSR.
+  google.protobuf.Timestamp create_time = 2 [(buf.validate.field).required = true];
+  // The last time the Collection was updated on the BSR.
+  google.protobuf.Timestamp update_time = 3 [(buf.validate.field).required = true];
+  // The name of the Collection.
+  //
+  // Unique within a BSR instance.
+  string name = 4 [
+    (buf.validate.field).required = true,
+    (buf.validate.field).string.max_len = 250
+  ];
+  // The configurable description of the Collection.
+  string description = 5 [(buf.validate.field).string.max_len = 350];
+}
+
+// CollectionRef is a reference to a Collection, either an id or a name.
+message CollectionRef {
+  option (buf.registry.priv.extension.v1beta1.message).request_only = true;
+
+  oneof value {
+    option (buf.validate.oneof).required = true;
+    // The id of the Collection.
+    string id = 1 [(buf.validate.field).string.tuuid = true];
+    // The name of the Collection.
+    string name = 2 [(buf.validate.field).string = {
+      min_len: 2
+      max_len: 100
+    }];
+  }
+}

buf/registry/plugin/v1beta1/collection_service.proto

@@ -0,0 +1,104 @@
+// 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.plugin.v1beta1;
+
+import "buf/registry/plugin/v1beta1/collection.proto";
+import "buf/registry/plugin/v1beta1/plugin.proto";
+import "buf/validate/validate.proto";
+
+option go_package = "buf.build/gen/go/bufbuild/registry/protocolbuffers/go/buf/registry/plugin/v1beta1";
+
+// Operate on Collections.
+service CollectionService {
+  // Get Collections.
+  rpc GetCollections(GetCollectionsRequest) returns (GetCollectionsResponse) {
+    option idempotency_level = NO_SIDE_EFFECTS;
+  }
+  // List Collections for a given Plugin.
+  rpc ListCollections(ListCollectionsRequest) returns (ListCollectionsResponse) {
+    option idempotency_level = NO_SIDE_EFFECTS;
+  }
+  // Get the Collections for the given Plugins.
+  rpc GetPluginCollectionAssociations(GetPluginCollectionAssociationsRequest) returns (GetPluginCollectionAssociationsResponse) {
+    option idempotency_level = NO_SIDE_EFFECTS;
+  }
+}
+
+message GetCollectionsRequest {
+  // The Collections to request.
+  repeated CollectionRef collection_refs = 1 [
+    (buf.validate.field).repeated.min_items = 1,
+    (buf.validate.field).repeated.max_items = 250
+  ];
+}
+
+message GetCollectionsResponse {
+  // The retrieved Collections in the same order as requested.
+  repeated Collection collections = 1 [(buf.validate.field).repeated.min_items = 1];
+}
+
+message ListCollectionsRequest {
+  // The list order.
+  enum Order {
+    ORDER_UNSPECIFIED = 0;
+    // Order by create_time newest to oldest.
+    ORDER_CREATE_TIME_DESC = 1;
+    // Order by create_time oldest to newest.
+    ORDER_CREATE_TIME_ASC = 2;
+  }
+  // The maximum number of items to return.
+  //
+  // The default value is 10.
+  uint32 page_size = 1 [(buf.validate.field).uint32.lte = 250];
+  // The page to start from.
+  //
+  // If empty, the first page is returned.
+  string page_token = 2 [(buf.validate.field).string.max_len = 4096];
+  // The order to return the Plugins.
+  //
+  // If not specified, defaults to ORDER_CREATE_TIME_DESC.
+  Order order = 3 [(buf.validate.field).enum.defined_only = true];
+}
+
+message ListCollectionsResponse {
+  // The next page token.
+  //
+  // If empty, there are no more pages.
+  string next_page_token = 1 [(buf.validate.field).string.max_len = 4096];
+  // The listed Collections.
+  repeated Collection collections = 2;
+}
+
+message GetPluginCollectionAssociationsRequest {
+  // The Plugins to request Collections for.
+  repeated PluginRef plugin_refs = 1 [
+    (buf.validate.field).repeated.min_items = 1,
+    (buf.validate.field).repeated.max_items = 250
+  ];
+}
+
+message GetPluginCollectionAssociationsResponse {
+  // The Associations for the requested Plugins.
+  message Association {
+    // The id of the Plugin.
+    string plugin_id = 1;
+    // The collection ids associated with the Plugin.
+    repeated string collection_ids = 2;
+  }
+  // The Associations for the requested Plugins in the same order as requested.
+  repeated Association associations = 1;
+}

buf/registry/plugin/v1beta1/commit.proto

@@ -0,0 +1,78 @@
+// 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.plugin.v1beta1;
+
+import "buf/plugin/info/v1/plugin_info.proto";
+import "buf/registry/plugin/v1beta1/digest.proto";
+import "buf/registry/priv/extension/v1beta1/extension.proto";
+import "buf/validate/validate.proto";
+import "google/protobuf/timestamp.proto";
+
+option go_package = "buf.build/gen/go/bufbuild/registry/protocolbuffers/go/buf/registry/plugin/v1beta1";
+
+// A commit on a specific Plugin.
+//
+// Commits are immutable.
+//
+// Many Commits may be associated with one Digest.
+//
+// Not that the Digest returned on a Commit depends on the requested DigestType in the RPC that
+// returned the Commit.
+message Commit {
+  option (buf.registry.priv.extension.v1beta1.message).response_only = true;
+
+  // The id of the Commit.
+  string id = 1 [
+    (buf.validate.field).required = true,
+    (buf.validate.field).string.tuuid = true
+  ];
+  // The time the Commit was pushed to the BSR.
+  //
+  // Commits are immutable, so there is no corresponding update_time.
+  google.protobuf.Timestamp create_time = 2 [(buf.validate.field).required = true];
+  // The id of the Organization that owns the Plugin that the Commit is associated with.
+  string owner_id = 3 [
+    (buf.validate.field).required = true,
+    (buf.validate.field).string.tuuid = true
+  ];
+  // The id of the Plugin that the Commit is associated with.
+  string plugin_id = 4 [
+    (buf.validate.field).required = true,
+    (buf.validate.field).string.tuuid = true
+  ];
+  // The Digest of the Commit's contents.
+  Digest digest = 5 [(buf.validate.field).required = true];
+  // The id of the User that created this Commit on the BSR.
+  //
+  // May be empty if the User is no longer available.
+  string created_by_user_id = 6 [
+    (buf.validate.field).string.tuuid = true,
+    (buf.validate.field).ignore = IGNORE_IF_UNPOPULATED
+  ];
+  // The URL of the source control commit that is associated with the Commit.
+  //
+  // BSR users can navigate to this link to find source control information that is relevant to this Commit
+  // (e.g. commit description, PR discussion, authors, approvers, etc.).
+  string source_control_url = 7 [
+    (buf.validate.field).string.uri = true,
+    (buf.validate.field).string.max_len = 255,
+    (buf.validate.field).ignore = IGNORE_IF_UNPOPULATED
+  ];
+  // The plugin information as stored directly within the plugin. This is part of the Bufplugin API,
+  // and can be returned from a plugin's GetPluginInfo implementation.
+  buf.plugin.info.v1.PluginInfo plugin_info = 8;
+}

buf/registry/plugin/v1beta1/commit_service.proto

@@ -0,0 +1,114 @@
+// 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.plugin.v1beta1;
+
+import "buf/registry/plugin/v1beta1/commit.proto";
+import "buf/registry/plugin/v1beta1/digest.proto";
+import "buf/registry/plugin/v1beta1/resource.proto";
+import "buf/validate/validate.proto";
+
+option go_package = "buf.build/gen/go/bufbuild/registry/protocolbuffers/go/buf/registry/plugin/v1beta1";
+
+// Operate on Commits.
+service CommitService {
+  // Get Commits.
+  rpc GetCommits(GetCommitsRequest) returns (GetCommitsResponse) {
+    option idempotency_level = NO_SIDE_EFFECTS;
+  }
+  // List Commits for a given Plugin, Label, or Commit.
+  rpc ListCommits(ListCommitsRequest) returns (ListCommitsResponse) {
+    option idempotency_level = NO_SIDE_EFFECTS;
+  }
+}
+
+message GetCommitsRequest {
+  // References to request a Commit for.
+  //
+  // See the documentation on ResourceRef for resource resolution details.
+  //
+  // Resolution is as follows:
+  //   - If a Plugin is referenced, the Commit of the default Label is returned.
+  //   - If a Label is referenced, the Commit of this Label is returned.
+  //   - If a Commit is referenced, this Commit is returned.
+  repeated ResourceRef resource_refs = 1 [
+    (buf.validate.field).repeated.min_items = 1,
+    (buf.validate.field).repeated.max_items = 250
+  ];
+  // The DigestType to use for Digests returned on Commits.
+  //
+  // If this DigestType is not available, an error is returned.
+  // Note that certain DigestTypes may be deprecated over time.
+  //
+  // If not set, the latest DigestType is used, currently p1.
+  DigestType digest_type = 2 [(buf.validate.field).enum.defined_only = true];
+}
+
+message GetCommitsResponse {
+  // The found Commits in the same order as requested.
+  repeated Commit commits = 1 [(buf.validate.field).repeated.min_items = 1];
+}
+
+message ListCommitsRequest {
+  // The list order.
+  enum Order {
+    ORDER_UNSPECIFIED = 0;
+    // Order by create_time newest to oldest.
+    ORDER_CREATE_TIME_DESC = 1;
+    // Order by create_time oldest to newest.
+    ORDER_CREATE_TIME_ASC = 2;
+  }
+  // The maximum number of items to return.
+  //
+  // The default value is 10.
+  uint32 page_size = 1 [(buf.validate.field).uint32.lte = 250];
+  // The page to start from.
+  //
+  // If empty, the first page is returned.
+  string page_token = 2 [(buf.validate.field).string.max_len = 4096];
+  // The reference to list Commits for.
+  //
+  // See the documentation on Ref for resource resolution details.
+  //
+  // Once the resource is resolved, the following Commits are listed (subject to any additional filters in the request):
+  //   - If a Plugin is referenced, all Commits for the Plugin are returned.
+  //   - If a Label is referenced, the Commit the Label points to is returned.
+  //     Use ListLabelHistory to get the history of Commits for a Label.
+  //   - If a Commit is referenced, this Commit is returned.
+  ResourceRef resource_ref = 3 [(buf.validate.field).required = true];
+  // The order to return the Commits.
+  //
+  // If not specified, defaults to ORDER_CREATE_TIME_DESC.
+  Order order = 4 [(buf.validate.field).enum.defined_only = true];
+  // The DigestType to use for Digests returned on Commits.
+  //
+  // If this DigestType is not available, an error is returned.
+  // Note that certain DigestTypes may be deprecated over time.
+  //
+  // If not set, the latest DigestType is used, currently p1.
+  DigestType digest_type = 5 [(buf.validate.field).enum.defined_only = true];
+  // Only return Commits with an id that contains this string using a case-insensitive comparison.
+  string id_query = 6 [(buf.validate.field).string.max_len = 36];
+}
+
+message ListCommitsResponse {
+  // The next page token.
+  //
+  // If empty, there are no more pages.
+  string next_page_token = 1 [(buf.validate.field).string.max_len = 4096];
+  // The listed Commits.
+  repeated Commit commits = 2;
+}