Promote several APIs to v1

buf.lock

@@ -5,5 +5,5 @@ deps:
     commit: e35f9b6674434a41aea0359ee056d083
     digest: b5:0d2579c1953b5b20bfa5c9d183f17af030bd3e594e2de5ba11d12a12091e64257cb2d82ca0f2234a01085b26d7b9905a472723e40db94b6c925b1360d1a7b44a
   - name: buf.build/bufbuild/protovalidate
-    commit: 6c6e0d3c608e4549802254a2eee81bc8
-    digest: b5:a7ca081f38656fc0f5aaa685cc111d3342876723851b47ca6b80cbb810cbb2380f8c444115c495ada58fa1f85eff44e68dc54a445761c195acdb5e8d9af675b6
+    commit: 50325440f8f24053b047484a6bf60b76
+    digest: b5:74cb6f5c0853c3c10aafc701614194bbd63326bdb8ef4068214454b8894b03ba4113e04b3a33a8321cdf05336e37db4dc14a5e2495db8462566914f36086ba31

buf/registry/admin/v1/instance_service.proto

@@ -0,0 +1,174 @@
+// Copyright 2023-2025 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.admin.v1;
+
+import "buf/registry/admin/v1/instance_settings.proto";
+import "buf/registry/admin/v1/recommended_sdk.proto";
+import "buf/registry/plugin/v1beta1/plugin.proto";
+import "buf/registry/resource/v1/resource_visibility_control.proto";
+import "buf/validate/validate.proto";
+
+option go_package = "buf.build/gen/go/bufbuild/registry/protocolbuffers/go/buf/registry/instance_settings/v1";
+
+// Operate on the instance-wide settings of a BSR instance.
+service InstanceService {
+  // Get the instance-wide settings.
+  rpc GetInstanceSettings(GetInstanceSettingsRequest) returns (GetInstanceSettingsResponse) {
+    option idempotency_level = NO_SIDE_EFFECTS;
+  }
+  // Update the instance-wide settings.
+  //
+  // Only the settings present on the request are updated; settings that are not set are
+  // left unchanged. This operation is atomic: either all of the present settings are
+  // updated or an error is returned and none are.
+  rpc UpdateInstanceSettings(UpdateInstanceSettingsRequest) returns (UpdateInstanceSettingsResponse) {
+    option idempotency_level = IDEMPOTENT;
+  }
+  // Get the instance-wide uniqueness policy.
+  rpc GetUniquenessPolicy(GetUniquenessPolicyRequest) returns (GetUniquenessPolicyResponse) {
+    option idempotency_level = NO_SIDE_EFFECTS;
+  }
+  // Update the instance-wide uniqueness policy.
+  //
+  // Enabling the uniqueness policy triggers a backfill that indexes every Module on the
+  // instance and scans for collisions; this may take a significant amount of time and
+  // briefly blocks pushes across the instance. If existing collisions are found, the
+  // policy is not enabled and a failed-precondition error is returned.
+  rpc UpdateUniquenessPolicy(UpdateUniquenessPolicyRequest) returns (UpdateUniquenessPolicyResponse) {
+    option idempotency_level = IDEMPOTENT;
+  }
+  // Add an SDK to the list of recommended SDKs at a given level.
+  //
+  // Returns an error with code ALREADY_EXISTS if the SDK is already recommended at the
+  // same level.
+  rpc AddRecommendedSDK(AddRecommendedSDKRequest) returns (AddRecommendedSDKResponse) {
+    option idempotency_level = IDEMPOTENT;
+  }
+  // Remove an SDK from the list of recommended SDKs at a given level.
+  rpc RemoveRecommendedSDK(RemoveRecommendedSDKRequest) returns (RemoveRecommendedSDKResponse) {
+    option idempotency_level = IDEMPOTENT;
+  }
+  // List the recommended SDKs at a given level.
+  //
+  // Because the same SDK can be recommended at more than one level at once, callers can
+  // make a request per level to determine whether an SDK is recommended at a higher level.
+  rpc ListRecommendedSDKs(ListRecommendedSDKsRequest) returns (ListRecommendedSDKsResponse) {
+    option idempotency_level = NO_SIDE_EFFECTS;
+  }
+}
+
+message GetInstanceSettingsRequest {}
+
+message GetInstanceSettingsResponse {
+  // The instance-wide settings.
+  InstanceSettings instance_settings = 1 [(buf.validate.field).required = true];
+}
+
+message UpdateInstanceSettingsRequest {
+  // The breaking change policy to set.
+  //
+  // If unset, the breaking change policy is left unchanged.
+  BreakingChangePolicy breaking_change_policy = 1;
+  // The review flow settings to set.
+  //
+  // If unset, the review flow settings are left unchanged.
+  ReviewFlowSettings review_flow_settings = 2;
+  // The instance-wide visibility control for Modules to set.
+  //
+  // If unset, the Module visibility control is left unchanged.
+  buf.registry.resource.v1.ResourceVisibilityControl module_visibility_control = 3;
+  // The instance-wide visibility control for Plugins to set.
+  //
+  // If unset, the Plugin visibility control is left unchanged.
+  buf.registry.resource.v1.ResourceVisibilityControl plugin_visibility_control = 4;
+  // The instance-wide visibility control for Policies to set.
+  //
+  // If unset, the Policy visibility control is left unchanged.
+  buf.registry.resource.v1.ResourceVisibilityControl policy_visibility_control = 5;
+}
+
+message UpdateInstanceSettingsResponse {
+  // The full instance-wide settings after the update was applied.
+  InstanceSettings instance_settings = 1 [(buf.validate.field).required = true];
+}
+
+message GetUniquenessPolicyRequest {}
+
+message GetUniquenessPolicyResponse {
+  // The uniqueness policy.
+  UniquenessPolicy uniqueness_policy = 1 [(buf.validate.field).required = true];
+  // Whether the uniqueness backfill task has completed.
+  //
+  // The uniqueness policy cannot be enforced until the backfill task has completed.
+  bool backfill_task_complete = 2;
+}
+
+message UpdateUniquenessPolicyRequest {
+  // The uniqueness policy to set.
+  UniquenessPolicy uniqueness_policy = 1 [(buf.validate.field).required = true];
+}
+
+message UpdateUniquenessPolicyResponse {
+  // The uniqueness policy after the update was applied.
+  UniquenessPolicy uniqueness_policy = 1 [(buf.validate.field).required = true];
+  // Whether the uniqueness backfill task has completed.
+  //
+  // The uniqueness policy cannot be enforced until the backfill task has completed.
+  bool backfill_task_complete = 2;
+}
+
+message AddRecommendedSDKRequest {
+  // The Plugin that generates the SDK to recommend.
+  buf.registry.plugin.v1beta1.PluginRef plugin_ref = 1 [(buf.validate.field).required = true];
+  // The level at which to recommend the SDK.
+  SDKRecommendationLevelRef recommendation_level = 2 [(buf.validate.field).required = true];
+}
+
+message AddRecommendedSDKResponse {}
+
+message RemoveRecommendedSDKRequest {
+  // The Plugin that generates the SDK to stop recommending.
+  buf.registry.plugin.v1beta1.PluginRef plugin_ref = 1 [(buf.validate.field).required = true];
+  // The level at which to stop recommending the SDK.
+  SDKRecommendationLevelRef recommendation_level = 2 [(buf.validate.field).required = true];
+}
+
+message RemoveRecommendedSDKResponse {}
+
+message ListRecommendedSDKsRequest {
+  // The maximum number of items to return on a page.
+  //
+  // 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 level at which to list recommended SDKs.
+  //
+  // Only SDKs recommended at this level are included in the response.
+  SDKRecommendationLevelRef recommendation_level = 3 [(buf.validate.field).required = true];
+}
+
+message ListRecommendedSDKsResponse {
+  // 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 recommended SDKs, all at the level given on the request.
+  repeated RecommendedSDK recommended_sdks = 2;
+}

buf/registry/admin/v1/instance_settings.proto

@@ -0,0 +1,109 @@
+// Copyright 2023-2025 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.admin.v1;
+
+import "buf/registry/priv/extension/v1beta1/extension.proto";
+import "buf/registry/resource/v1/resource_visibility_control.proto";
+import "buf/validate/validate.proto";
+
+option go_package = "buf.build/gen/go/bufbuild/registry/protocolbuffers/go/buf/registry/instance_settings/v1";
+
+// The instance-wide settings for a BSR instance.
+//
+// There is exactly one InstanceSettings per BSR instance. It is administered by Users
+// with instance-level administrative permissions, but is readable by any authenticated
+// User, as the settings affect how every Module on the instance behaves.
+//
+// The uniqueness policy is intentionally not part of this message. Because enabling it
+// triggers a potentially long-running, instance-wide backfill and collision scan, it is
+// managed through the dedicated GetUniquenessPolicy and UpdateUniquenessPolicy RPCs
+// rather than folded into the batched settings.
+message InstanceSettings {
+  option (buf.registry.priv.extension.v1beta1.message).response_only = true;
+
+  // The policy controlling whether breaking changes are enforced when Commits are pushed.
+  BreakingChangePolicy breaking_change_policy = 1 [(buf.validate.field).required = true];
+  // The settings controlling whether Commits with breaking changes are held for review.
+  ReviewFlowSettings review_flow_settings = 2 [(buf.validate.field).required = true];
+  // The instance-wide visibility control for Modules.
+  //
+  // If unset, new Modules fall through to the owning Organization's control, and default to
+  // private if no control applies at any level.
+  buf.registry.resource.v1.ResourceVisibilityControl module_visibility_control = 3;
+  // The instance-wide visibility control for Plugins.
+  //
+  // If unset, new Plugins fall through to the owning Organization's control, and default to
+  // private if no control applies at any level.
+  buf.registry.resource.v1.ResourceVisibilityControl plugin_visibility_control = 4;
+  // The instance-wide visibility control for Policies.
+  //
+  // If unset, new Policies fall through to the owning Organization's control, and default to
+  // private if no control applies at any level.
+  buf.registry.resource.v1.ResourceVisibilityControl policy_visibility_control = 5;
+}
+
+// The policy controlling enforcement of breaking changes when Commits are pushed to the
+// instance.
+message BreakingChangePolicy {
+  // Whether breaking change enforcement is enabled.
+  bool enabled = 1;
+  // Whether breaking changes in unstable packages are ignored.
+  //
+  // A package is unstable if its last component is a version that is not a stable
+  // release, for example a v1alpha1 or v1beta1 package.
+  bool ignore_unstable_packages = 2;
+  // The category of breaking change detection to enforce.
+  //
+  // If unset, the server defaults to BREAKING_CHANGE_CATEGORY_FILE.
+  BreakingChangeCategory category = 3 [(buf.validate.field).enum.defined_only = true];
+}
+
+// The category of breaking change detection enforced by a BreakingChangePolicy.
+enum BreakingChangeCategory {
+  BREAKING_CHANGE_CATEGORY_UNSPECIFIED = 0;
+  // Enforce that changes do not break compatibility at the file level.
+  //
+  // This is the strictest category. It detects changes that could break generated code,
+  // such as moving a type to a different file.
+  BREAKING_CHANGE_CATEGORY_FILE = 1;
+  // Enforce that changes do not break compatibility on the wire for both binary and JSON
+  // encoding.
+  //
+  // This is a less strict category than BREAKING_CHANGE_CATEGORY_FILE; it permits changes
+  // that affect generated code but preserve wire and JSON compatibility.
+  BREAKING_CHANGE_CATEGORY_WIRE_JSON = 2;
+}
+
+// The policy controlling whether fully-qualified names and file paths must be unique
+// across all Modules on the instance.
+message UniquenessPolicy {
+  // Whether uniqueness enforcement is enabled.
+  //
+  // When enabled, a Commit cannot be pushed if it introduces a fully-qualified name or
+  // file path that collides with one already present in another Module on the instance.
+  bool enabled = 1;
+}
+
+// The settings controlling the instance review flow.
+//
+// When both the BreakingChangePolicy and the review flow are enabled, Commits that
+// introduce breaking changes are held in a pending state until an administrator reviews
+// them.
+message ReviewFlowSettings {
+  // Whether the review flow is enabled.
+  bool enabled = 1;
+}

buf/registry/admin/v1/recommended_sdk.proto

@@ -0,0 +1,83 @@
+// Copyright 2023-2025 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.admin.v1;
+
+import "buf/registry/module/v1/module.proto";
+import "buf/registry/owner/v1/organization.proto";
+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/instance_settings/v1";
+
+// An SDK that is recommended at a given SDKRecommendationLevel.
+//
+// A recommended SDK signals to Users that a particular Plugin should be used to generate
+// code, and causes eager generation to be enqueued for the SDK at the recommended level.
+message RecommendedSDK {
+  option (buf.registry.priv.extension.v1beta1.message).response_only = true;
+
+  // The id of the Plugin that generates the recommended SDK.
+  string sdk_plugin_id = 1 [
+    (buf.validate.field).required = true,
+    (buf.validate.field).string.tuuid = true
+  ];
+
+  // The level at which the SDK is recommended.
+  SDKRecommendationLevel recommendation_level = 2 [(buf.validate.field).required = true];
+}
+
+// The level at which an SDK is recommended.
+//
+// An SDK can be recommended at more than one level at once; for example, an SDK
+// recommended at the instance level may also be recommended for a specific Module.
+message SDKRecommendationLevel {
+  // The SDK is recommended across the entire instance.
+  //
+  // Eager generation is enqueued for the SDK across all Modules on the instance.
+  message Instance {}
+
+  oneof level {
+    option (buf.validate.oneof).required = true;
+    // The SDK is recommended across the entire instance.
+    Instance instance = 1;
+    // The SDK is recommended across a single Organization.
+    string organization_id = 2 [(buf.validate.field).string.tuuid = true];
+    // The SDK is recommended for a single Module.
+    string module_id = 3 [(buf.validate.field).string.tuuid = true];
+  }
+}
+
+// The level at which an SDK is recommended.
+//
+// An SDK can be recommended at more than one level at once; for example, an SDK
+// recommended at the instance level may also be recommended for a specific Module.
+message SDKRecommendationLevelRef {
+  // The SDK is recommended across the entire instance.
+  //
+  // Eager generation is enqueued for the SDK across all Modules on the instance.
+  message Instance {}
+
+  oneof level {
+    option (buf.validate.oneof).required = true;
+    // The SDK is recommended across the entire instance.
+    Instance instance = 1;
+    // The SDK is recommended across a single Organization.
+    buf.registry.owner.v1.OrganizationRef organization_ref = 2;
+    // The SDK is recommended for a single Module.
+    buf.registry.module.v1.ModuleRef module_ref = 3;
+  }
+}