Sakthivel Subramanian

This commit introduces a **new capability** to the **Spanner client** by adding an `EnableDirectAccess` field to its `ClientConfig`. This allows users to programmatically control whether the client connects to the **directpath XDS endpoint**, enhancing configuration flexibility for Spanner connections. The existing `GOOGLE_SPANNER_ENABLE_DIRECT_ACCESS` environment variable remains fully supported and takes precedence over this programmatic setting, providing a robust override mechanism. This change primarily affects the `spanner/client.go` module, specifically the `newClientWithConfig` and `allClientOpts` functions, by extending client configuration options.

This commit **fixes** and **improves** the **Spanner client library's** detection logic for **DirectPath usage**, specifically for the `directpath_used` metric. It updates the `setDirectPathUsed` function in `spanner/metrics.go` to assert the presence of **ALTS credentials** in the gRPC peer context, replacing the less reliable IP prefix matching. This change enhances the **reliability** and **accuracy** of the metric, aligning it more closely with standard gRPC practices across evolving DirectPath networks. Integration tests in `spanner/integration_test.go` and new unit tests in `spanner/metrics_test.go` have been updated to validate this new detection method.

This commit **updates the documentation** for the **Spanner** module, specifically enhancing information related to client-side metrics. It adds new sections to `spanner/README.md` that detail the functionality of **client-side metrics**, provide instructions on how to disable them, and outline the necessary **IAM permissions** for exporting this data. This **documentation improvement** helps users understand and correctly configure the monitoring and security aspects of Spanner client-side operations.

This commit implements an **observability enhancement** for the **Spanner client**, enabling **conditional logging of its configuration details** during initialization. A new function, `newClientWithConfig`, in `spanner/client.go` facilitates this by utilizing `enableLogClientOptions`. To maintain clean test output, this new logging behavior is explicitly **disabled within integration tests and in-memory Spanner server tests**. This **maintenance improvement** provides valuable insights into the client's runtime setup, aiding in debugging and operational understanding.

This commit **enhances the Spanner client library** by **configuring a default gRPC TCP keep-alive time** for its connections. It introduces a **120-second default keep-alive interval** for all gRPC connections established by the **Spanner client**, specifically within the `allClientOpts` in `spanner/client.go`. This **improves connection stability** for long-running operations by preventing idle connections from being dropped prematurely due to network intermediaries. Furthermore, this **configuration enhancement** allows customers to **override this default keep-alive setting** via client options, providing flexibility for specific network environments.

This commit introduces a **maintenance improvement** to the **Spanner client library**, specifically targeting **emulator test environments**. It modifies the `detectClientLocation` function within `spanner/metrics.go` to check for the `SPANNER_EMULATOR_HOST` environment variable. If this variable is present, the function now returns a default location, effectively **disabling connections to the metadata server** during emulator tests. This change prevents unnecessary network calls and potential failures, ensuring **more robust and efficient execution of Spanner emulator tests** by avoiding irrelevant infrastructure dependencies.

This commit **enables multiplex sessions by default for all operations** within the **Spanner client library**, fundamentally altering session management behavior. This **new capability** is implemented by modifying environment variable parsing logic in `client.go`, ensuring users automatically benefit from improved session efficiency and performance. The change required extensive **test adjustments** across numerous files, including `client_test.go` and `transaction_test.go`, to correctly handle the new default and ensure test stability. Furthermore, **documentation was updated** in `README.md` and `session.go` to reflect this change, and the **Spanner emulator version** was updated to support the new default.

This commit implements a **CI fix** to address failures in **Spanner DirectPath nightly jobs** by adjusting the behavior of integration and regression tests. It introduces helper functions like `skipDirectPathTest` in `spanner/integration_test.go` to **conditionally skip tests** when DirectPath is active, and modifies `TestAllHeadersForwardedAppropriately` in `spanner/regression_test.go` to handle headers based on DirectPath enablement. This **maintenance** work ensures the **Spanner test suite** correctly accommodates DirectPath's operational characteristics, improving the reliability of the **CI pipeline** by preventing test failures caused by DirectPath's unique operational characteristics.

This commit introduces a **conditional skip** for specific **Spanner integration tests** within `spanner/integration_test.go`. It ensures that **GFE latency tests** are automatically bypassed when the **DirectPath** feature is enabled via an environment variable. This **CI/Testing adjustment** prevents irrelevant test failures and streamlines the testing process, ensuring the stability and accuracy of **Spanner integration tests** across varying network configurations.

This commit introduces a **bug fix** to the **Spanner client library**'s **retry mechanism**, specifically addressing how `ResourceExhausted` errors are handled. The `Retry` function in `spanner/retry.go` is modified to prevent "blind" retries for these errors, ensuring that retries only occur if the server explicitly provides a valid retry delay via `RetryInfo`. This change prevents inefficient and potentially counterproductive retries, thereby improving the overall robustness and resource management of applications interacting with Spanner. New test cases in `spanner/read_test.go` have been added to thoroughly validate this corrected retry behavior.

This commit introduces a **performance optimization** for the **Cloud Spanner client library**, specifically impacting **StreamingRead** and **ExecuteStreamingSql** operations. It **refactors** the `streamed.py` module to detect the `last` flag in partial result sets, enabling early termination of iteration and **skipping gRPC trailers** to improve efficiency. The **mock Spanner server** and **test suite** have been **enhanced** with new helper functions and test cases, such as `test_execute_streaming_sql_last_field`, to thoroughly validate the correct handling of the `last` flag and the new optimization. This change reduces unnecessary processing overhead for streaming data.

This commit implements a **bug fix** within the **Spanner client library's metrics subsystem** to prevent redundant metric exports during application shutdown. It modifies the `monitoringExporter` in `metrics_monitoring_exporter.go` to track the last export time and introduces a new `stop` method that conditionally prevents metric exports if a previous export occurred less than 30 seconds ago. The `newBuiltinMetricsTracerFactory` in `metrics.go` is updated to utilize this new stop mechanism, ensuring more efficient and accurate **Spanner client library metric reporting** by avoiding unnecessary calls to monitoring services during application termination.

This commit **enhances the `civil` package** by **extending the `Scan` methods** for `civil.Date`, `civil.Time`, and `civil.DateTime` types. These methods now directly accept `civil.Date`, `civil.Time`, `civil.DateTime`, and their pointer types as arguments, resolving a previous limitation. This **new capability** improves the flexibility and usability of the `Scan` operations, allowing for more direct assignments and reducing the need for intermediate conversions when working with `civil` values. Comprehensive test cases have been added to verify this expanded functionality.

This commit provides a **bug fix** for the **Spanner client library** by addressing a **row data mismatch** in the `SelectAll` function. It ensures that struct pointers are correctly reset for each row when decoding **custom types** in `spanner/row.go`, preventing data corruption. A new test case has been added to `spanner/row_test.go` to verify the correct decoding of custom types, including null values, thereby improving the **reliability** of data retrieval for Spanner users.

This commit introduces a **performance optimization** for the **Spanner client library**, specifically impacting **`StreamingRead`** and **`ExecuteStreamingSql`** operations. It modifies the `tryRecv` method in `spanner/read.go` to **skip gRPC trailers** by immediately transitioning the stream decoder to a finished state upon receiving a partial result set with the `Last` flag. This change reduces unnecessary processing overhead by avoiding further stream processing once all data is received. Supporting changes in `spanner/internal/testutil` enable setting the `Last` flag in mock results, and new test cases confirm the correct trailer-skipping behavior.

This commit introduces **significant enhancements to the Spanner benchmarking suite**, primarily by adding **OpenTelemetry tracing support** and **flexible command-line argument parsing**. A new `spanner/benchmarks` module is integrated into the Go workspace, allowing users to configure and run performance tests with greater control. This **new capability** improves the **observability and configurability** of Spanner benchmarks, enabling detailed performance analysis and easier execution via command-line options. The `spanner/benchmarks/benchmarks.go` file now includes a new configuration struct and parsing logic, with usage instructions provided in the updated `spanner/benchmarks/README.md`.

This commit introduces a **new capability** to the **Spanner benchmarking script** (`spanner/benchmarks/benchmarks.go`), enabling the configuration of the target cloud environment. Specifically, it allows users to specify whether benchmarks should interact with production or development environments for both the Spanner client and its monitoring components. This enhancement improves the flexibility and realism of performance testing within the **CI infrastructure**, facilitating more accurate evaluation of Spanner across diverse cloud setups.

This commit **improves the reliability and user experience of the Spanner benchmarking script** by introducing **robust error handling and input validation**. It specifically **enhances the `spanner/benchmarks/benchmarks.go` script** to validate command-line arguments and adds comprehensive error handling for transaction type parsing. The `parseTransactionType` function was modified to return an error, ensuring that invalid transaction types are gracefully handled. This **maintenance update** prevents unexpected failures and provides clearer feedback to users when running benchmarks with incorrect parameters.

This commit introduces a **new capability** to the **Spanner benchmarking tool**, specifically adding **support for point reads**. It modifies `spanner/benchmarks/benchmarks.go` to include a new transaction type and corresponding execution logic, impacting functions such as `execute` and `executeRead`. This enhancement allows users to **benchmark the performance of single-row lookups** in Spanner, providing more granular and comprehensive performance metrics. The change expands the utility of the benchmarking suite, offering deeper insights into Spanner's read performance characteristics.

This commit provides a **bug fix** for the **Spanner benchmarking script** and its associated metrics collection. It **corrects percentile calculations** within `spanner/benchmarks/benchmarks.go` by adjusting the parameter type and formula, and refactors the `main` function to use `defer` for client closure. Additionally, the **Spanner metrics collection** is improved by adding `ForceFlush` to the meter provider shutdown sequence in `spanner/metrics.go`, **ensuring all metrics are properly exported** before the provider closes. This prevents potential data loss in benchmark results and ensures accurate performance reporting.