Add initial Plugin specification

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 Label 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/commit.proto

@@ -0,0 +1,70 @@
+// 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/digest.proto";
+import "buf/registry/plugin/v1beta1/plugin_info.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 license of the Plugin Commit.
+  License license = 7;
+  // The documentation of the Plugin Commit.
+  Doc doc = 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;
+}

buf/registry/plugin/v1beta1/digest.proto

@@ -0,0 +1,41 @@
+// 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/validate/validate.proto";
+
+option go_package = "buf.build/gen/go/bufbuild/registry/protocolbuffers/go/buf/registry/plugin/v1beta1";
+
+// A digest of a Commit's content.
+//
+// A digest represents all content for a single Commit.
+message Digest {
+  // The type of the Digest.
+  DigestType type = 1 [
+    (buf.validate.field).required = true,
+    (buf.validate.field).enum.defined_only = true
+  ];
+  // The value of the Digest.
+  bytes value = 2 [(buf.validate.field).required = true];
+}
+
+// The type of Digest.
+enum DigestType {
+  DIGEST_TYPE_UNSPECIFIED = 0;
+  // The p1 digest function.
+  DIGEST_TYPE_P1 = 1;
+}

buf/registry/plugin/v1beta1/download_service.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/plugin/v1beta1/commit.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";
+
+// Download contents.
+service DownloadService {
+  // Download contents for given set of Plugins.
+  //
+  // Contents are WASM modules that are compiled and executed within a suitable runtime.
+  rpc Download(DownloadRequest) returns (DownloadResponse) {
+    option idempotency_level = NO_SIDE_EFFECTS;
+  }
+}
+
+message DownloadRequest {
+  // A request for content for a single version of a Plugin.
+  message Value {
+    // The reference to get content for.
+    //
+    // See the documentation on Reference for reference resolution details.
+    //
+    // Once the resource is resolved, the following content is returned:
+    //   - If a Plugin is referenced, the content of the latest commit of the default label is
+    //     returned.
+    //   - If a Label is referenced, the content of the Commit of this Label is returned.
+    //   - If a Commit is referenced, the content for this Commit is returned.
+    ResourceRef resource_ref = 1 [(buf.validate.field).required = true];
+  }
+  // The references to get contents for.
+  repeated Value values = 1 [
+    (buf.validate.field).repeated.min_items = 1,
+    (buf.validate.field).repeated.max_items = 250
+  ];
+}
+
+message DownloadResponse {
+  // Content for a single version of a Plugin.
+  message Content {
+    // The Commit associated with the Content.
+    Commit commit = 1 [(buf.validate.field).required = true];
+    // The content.
+    bytes content = 2 [(buf.validate.field).required = true];
+  }
+  repeated Content contents = 1 [(buf.validate.field).repeated.min_items = 1];
+}