feat(sidekick/rust): Support overriding the service for the package QuickStart (#4319)

This is useful in several cases. including if the service selected by
the heuristic is under a feature flag, or not generated in Rust, or even
if it's a very secondary/minor service in the package.

Author: amanda-tarafa

doc/config-schema.md

@@ -188,6 +188,7 @@ This document describes the schema for the librarian.yaml.
 | `pagination_overrides` | list of [RustPaginationOverride](#rustpaginationoverride-configuration) | Contains overrides for pagination configuration. |
 | `name_overrides` | string | Contains codec-level overrides for type and service names. |
 | `discovery` | [RustDiscovery](#rustdiscovery-configuration) (optional) | Contains discovery-specific configuration for LRO polling. |
+| `quickstart_service_override` | string | Overrides the default heuristically selected service for the package-level quickstart. |
 
 ## RustDefault Configuration
 

internal/config/language.go

@@ -221,6 +221,9 @@ type RustCrate struct {
 
 	// Discovery contains discovery-specific configuration for LRO polling.
 	Discovery *RustDiscovery `yaml:"discovery,omitempty"`
+
+	// QuickstartServiceOverride overrides the default heuristically selected service for the package-level quickstart.
+	QuickstartServiceOverride string `yaml:"quickstart_service_override,omitempty"`
 }
 
 // RustPackageDependency represents a package dependency configuration.

internal/librarian/rust/codec.go

@@ -155,6 +155,9 @@ func buildCodec(library *config.Library) map[string]string {
 	if rust.NameOverrides != "" {
 		codec["name-overrides"] = rust.NameOverrides
 	}
+	if rust.QuickstartServiceOverride != "" {
+		codec["quickstart-service-override"] = rust.QuickstartServiceOverride
+	}
 	return codec
 }
 

internal/librarian/rust/codec_test.go

@@ -1077,6 +1077,7 @@ func TestBuildCodec(t *testing.T) {
 					HasVeneer:                 true,
 					RoutingRequired:           true,
 					NameOverrides:             "foo=bar",
+					QuickstartServiceOverride: "OverriddenService",
 					DefaultFeatures:           []string{"feature1", "feature2"},
 					DisabledClippyWarnings:    []string{"clippy1", "clippy2"},
 				},
@@ -1093,6 +1094,7 @@ func TestBuildCodec(t *testing.T) {
 				"generate-setter-samples":     "true",
 				"generate-rpc-samples":        "true",
 				"name-overrides":              "foo=bar",
+				"quickstart-service-override": "OverriddenService",
 				"default-features":            "feature1,feature2",
 				"disabled-rustdoc-warnings":   "warning1,warning2",
 				"disabled-clippy-warnings":    "clippy1,clippy2",

internal/sidekick/rust/annotate.go

@@ -689,14 +689,20 @@ func annotateModel(model *api.API, codec *codec) (*modelAnnotations, error) {
 	}()
 
 	var quickstartService *api.Service
-	if model.QuickstartService != nil {
+	if codec.quickstartServiceOverride != "" {
+		idx := slices.IndexFunc(servicesSubset, func(s *api.Service) bool {
+			return strings.EqualFold(codec.ServiceName(s), codec.quickstartServiceOverride) || strings.EqualFold(s.Name, codec.quickstartServiceOverride)
+		})
+		if idx != -1 {
+			quickstartService = servicesSubset[idx]
+		} else {
+			return nil, fmt.Errorf("quickstart_service_override %q not found in generated services for package %q", codec.quickstartServiceOverride, codec.packageName(model))
+		}
+	} else if model.QuickstartService != nil {
 		if slices.ContainsFunc(servicesSubset, func(s *api.Service) bool { return s == model.QuickstartService }) {
 			quickstartService = model.QuickstartService
 		}
 	}
-	if quickstartService == nil && len(servicesSubset) > 0 {
-		quickstartService = servicesSubset[0]
-	}
 
 	ann := &modelAnnotations{
 		PackageName:      codec.packageName(model),

internal/sidekick/rust/annotate_model_test.go

@@ -235,16 +235,48 @@ func TestQuickstartServiceAnnotation(t *testing.T) {
 			t.Fatal(err)
 		}
 
+		if got.QuickstartService != nil {
+			t.Errorf("expected QuickstartService to be nil because it was filtered out and there is no override, got %v", got.QuickstartService.Name)
+		}
+	})
+
+	t.Run("with override", func(t *testing.T) {
+		model := newTestAnnotateModelAPI()
+		model.QuickstartService = model.Services[0] // Set default to 0
+
+		codec := newTestCodec(t, libconfig.SpecProtobuf, "", nil)
+		// Set override to Service1
+		codec.quickstartServiceOverride = "Service1"
+
+		got, err := annotateModel(model, codec)
+		if err != nil {
+			t.Fatal(err)
+		}
+
 		if got.QuickstartService == nil {
 			t.Fatal("QuickstartService should not be nil")
 		}
-		// It should have fallen back to the first non-filtered service (Service0).
-		if got.QuickstartService != model.Services[0] {
-			t.Errorf("expected QuickstartService to fall back to Service0, got %v", got.QuickstartService.Name)
+		if got.QuickstartService != model.Services[1] {
+			t.Errorf("expected QuickstartService to be overridden to Service1, got %v", got.QuickstartService.Name)
 		}
 	})
-}
 
+	t.Run("with missing override", func(t *testing.T) {
+		model := newTestAnnotateModelAPI()
+
+		codec := newTestCodec(t, libconfig.SpecProtobuf, "", nil)
+		codec.quickstartServiceOverride = "NonExistentService"
+
+		_, err := annotateModel(model, codec)
+		if err == nil {
+			t.Fatal("expected error, got nil")
+		}
+		expectedErr := `quickstart_service_override "NonExistentService" not found in generated services for package "google-cloud-Test"`
+		if err.Error() != expectedErr {
+			t.Errorf("expected error %q, got %q", expectedErr, err.Error())
+		}
+	})
+}
 func newTestAnnotateModelAPI() *api.API {
 	service0 := &api.Service{
 		Name: "Service0",

internal/sidekick/rust/codec.go

@@ -181,6 +181,8 @@ func newCodec(specificationFormat string, options map[string]string) (*codec, er
 				return nil, fmt.Errorf("cannot convert `internal-builders` value %q to boolean: %w", definition, err)
 			}
 			codec.internalBuilders = value
+		case key == "quickstart-service-override":
+			codec.quickstartServiceOverride = definition
 		default:
 			return nil, fmt.Errorf("unknown Rust codec option %q", key)
 		}
@@ -329,6 +331,8 @@ type codec struct {
 	generateRpcSamples bool
 	// If true, the generator will set the internal builder's visibility to public (crate).
 	internalBuilders bool
+	// Overrides the default heuristically selected service for the package-level quickstart.
+	quickstartServiceOverride string
 }
 
 type systemParameter struct {

internal/sidekick/rust/codec_test.go

@@ -324,6 +324,15 @@ func TestParseOptions(t *testing.T) {
 				c.internalBuilders = true
 			},
 		},
+		{
+			Format: libconfig.SpecProtobuf,
+			Options: map[string]string{
+				"quickstart-service-override": "OverriddenService",
+			},
+			Update: func(c *codec) {
+				c.quickstartServiceOverride = "OverriddenService"
+			},
+		},
 	} {
 		want, err := newCodec(test.Format, map[string]string{})
 		if err != nil {