Adopt constructor options pattern for MixerServer and SpannerDataSource

[clincoln8]

Refactor core server constructors (NewMixerServer, NewSpannerDataSource) and embeddings resolution to adopt the Constructor Options Pattern (required parameters + options struct).

Adding optional dependencies to these core components previously broke their constructor signatures, forcing updates to dozens of files (mostly test setup boilerplate) that didn't use the new feature.

This refactor stabilizes these APIs. Essential dependencies (e.g., SpannerClient) remain direct parameters, while optional ones (e.g., caches, maps clients) are grouped into an Options struct. This allows us to add future optional dependencies without breaking existing calls, and simplifies tests by allowing them to pass nil options.

Key Aspects of the Approach

• Options Structs: Introduced SpannerDataSourceOptions, EmbeddingsServiceClientOptions, and MixerServerOptions to group optional dependencies for the respective constructors.
• Required vs Optional: Separated required dependencies (passed as direct arguments) from optional dependencies (passed via options structs). For example, SpannerClient is required for NewSpannerDataSource, while RecogPlaceStore and MapsClient are optional.
• EmbeddingsServiceClient: Encapsulated embeddings resolution logic into EmbeddingsServiceClient struct, converting package-level functions (ResolveUsingEmbeddings, SelectEmbeddingsIndex) into client methods.
• Documentation: Updated docs/architecture.md to document the constructor options pattern guidelines and the circular dependency resolution pattern (setter injection) with concrete examples.

[gemini-code-assist]

Code Review

This pull request refactors the mixer server and Spanner data source constructors to use the 'Required Parameters + Options Struct' pattern, improving API stability and test setup flexibility. It introduces an EmbeddingsServiceClient to encapsulate HTTP communication with the embeddings server, replacing direct package-level function calls. Additionally, it refactors the V2 resolve routing logic, introducing the X-V2Resolve-Indicator-Spanner header to allow request-time toggling between Spanner and legacy backends, and updates corresponding tests and architectural documentation. As there are no review comments provided, no feedback is offered on reviewer remarks.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[clincoln8]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors the constructors for SpannerDataSource and MixerServer to use the 'Required Parameters + Options Struct' pattern, which improves API stability and simplifies test configurations. It also introduces an EmbeddingsServiceClient to encapsulate embeddings resolution logic. The review feedback highlights three key areas for improvement: preventing potential information exposure by avoiding returning raw error messages from the embeddings server to clients, using url.JoinPath instead of path.Join to preserve trailing slashes for the server configuration endpoint, and configuring a sensible timeout on the default HTTP client to prevent resource exhaustion.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[n-h-diaz]

Thank you!