|
| 1 | +// Copyright 2026 Google LLC |
| 2 | +// |
| 3 | +// Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 | +// you may not use this file except in compliance with the License. |
| 5 | +// You may obtain a copy of the License at |
| 6 | +// |
| 7 | +// https://www.apache.org/licenses/LICENSE-2.0 |
| 8 | +// |
| 9 | +// Unless required by applicable law or agreed to in writing, software |
| 10 | +// distributed under the License is distributed on an "AS IS" BASIS, |
| 11 | +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 | +// See the License for the specific language governing permissions and |
| 13 | +// limitations under the License. |
| 14 | + |
| 15 | +//! Compile-time canary for `gaxi::prost::ToProto` and `FromProto`. |
| 16 | +//! |
| 17 | +//! Crate versions already published on crates.io call `.to_proto()` and |
| 18 | +//! `.cnv()` without naming the target type. They compile only while each |
| 19 | +//! source type has exactly one matching impl. Applications pick up new |
| 20 | +//! `google-cloud-gax-internal` 0.7.x releases automatically, so adding a second |
| 21 | +//! impl upstream (in `gaxi`, or in a crate that defines a shared model type) |
| 22 | +//! would break those published versions. |
| 23 | +//! |
| 24 | +//! The tests in this crate mirror the published call sites. They fail to |
| 25 | +//! compile (`E0283` or `E0284`, "type annotations needed") if such an impl is |
| 26 | +//! added. |
| 27 | +//! |
| 28 | +//! Keep the dependencies minimal. Do not depend on any crate that implements |
| 29 | +//! `ToProto` or `FromProto` for the types checked here (e.g. storage, |
| 30 | +//! logging-v2, aiplatform-v1). Those impls are legitimate, and depending on |
| 31 | +//! them would make this canary fail. |
| 32 | +//! |
| 33 | +//! The canary only sees impls added by crates in its own dependency graph. So |
| 34 | +//! do depend on every crate that a published converter depends on and that can |
| 35 | +//! reach `gaxi::prost`, today or by enabling `_internal-grpc-client` (e.g. |
| 36 | +//! `google-cloud-lro`, `google-cloud-longrunning`, `google-cloud-iam-v1`, |
| 37 | +//! `google-cloud-location`). If such a crate defines none of the checked |
| 38 | +//! types, also load it with `extern crate` below. |
| 39 | +//! |
| 40 | +//! # If this canary fails |
| 41 | +//! |
| 42 | +//! The change adds a second impl that published crate versions cannot resolve. |
| 43 | +//! Those versions stop compiling once users pick up the new release of the |
| 44 | +//! crate that adds the impl. That is not automatically a blocker. It is a |
| 45 | +//! judgment call: weigh how recent and widely used the affected versions are |
| 46 | +//! against the cost of the alternatives (avoid the impl, ship it in a |
| 47 | +//! semver-breaking release, or ship as-is and ask affected customers to |
| 48 | +//! upgrade). Whatever we decide, document it in the release notes (the affected |
| 49 | +//! crate versions and the upgrade path), then update this canary so it keeps |
| 50 | +//! guarding the rest. |
| 51 | +//! |
| 52 | +//! See <https://github.com/googleapis/google-cloud-rust/issues/7284>. |
| 53 | +
|
| 54 | +// rustc only loads dependencies that the source references, and only sees |
| 55 | +// impls from loaded crates. These crates define none of the checked types, so |
| 56 | +// load them explicitly. |
| 57 | +#[cfg(test)] |
| 58 | +extern crate google_cloud_location as _; |
| 59 | +#[cfg(test)] |
| 60 | +extern crate google_cloud_lro as _; |
| 61 | + |
| 62 | +/// External model types that published crates convert with their own |
| 63 | +/// `ToProto` impl. |
| 64 | +/// |
| 65 | +/// For example, aiplatform-v1 1.18.0 implements `ToProto` for |
| 66 | +/// `google_cloud_rpc::model::Status`, targeting its own prost type, and calls |
| 67 | +/// `.to_proto()` on it unqualified. Each type gets a local |
| 68 | +/// `ToProto<LocalProst>` impl, which stands in for the published one. If an |
| 69 | +/// upstream crate adds another impl, the unqualified call below no longer |
| 70 | +/// compiles. |
| 71 | +/// |
| 72 | +/// This list is frozen. Code generated after #7374 and handwritten code after |
| 73 | +/// #7437 qualify these calls, so only crate versions published before those |
| 74 | +/// changes need coverage. |
| 75 | +#[cfg(test)] |
| 76 | +mod external_model_to_proto { |
| 77 | + use gaxi::prost::{ConvertError, ToProto}; |
| 78 | + |
| 79 | + struct LocalProst; |
| 80 | + |
| 81 | + macro_rules! assert_single_upstream_impl { |
| 82 | + ($($ty:ty),* $(,)?) => { |
| 83 | + $( |
| 84 | + impl ToProto<LocalProst> for $ty { |
| 85 | + type Output = LocalProst; |
| 86 | + fn to_proto(self) -> Result<LocalProst, ConvertError> { |
| 87 | + Ok(LocalProst) |
| 88 | + } |
| 89 | + } |
| 90 | + )* |
| 91 | + |
| 92 | + #[test] |
| 93 | + fn no_upstream_impl() -> Result<(), ConvertError> { |
| 94 | + $( |
| 95 | + let _: LocalProst = <$ty>::default().to_proto()?; |
| 96 | + )* |
| 97 | + Ok(()) |
| 98 | + } |
| 99 | + }; |
| 100 | + } |
| 101 | + |
| 102 | + assert_single_upstream_impl!( |
| 103 | + // Converted in aiplatform-v1 1.18.0, apigeeconnect-v1 1.12.0, |
| 104 | + // dialogflow-cx-v3 2.11.0, dialogflow-v2 1.18.0, |
| 105 | + // google-maps-routes-v1 1.1.0, and google-maps-routing-v2 1.2.0. |
| 106 | + google_cloud_rpc::model::Status, |
| 107 | + // Converted in storage 1.21.0 and aiplatform-v1 1.18.0. |
| 108 | + google_cloud_type::model::Date, |
| 109 | + // Converted in storage 1.21.0. |
| 110 | + google_cloud_type::model::Expr, |
| 111 | + // Converted in storage 1.21.0 and datacatalog-lineage-v1 1.15.0. |
| 112 | + google_cloud_type::model::Interval, |
| 113 | + // Converted in aiplatform-v1 1.18.0, dialogflow-cx-v3 2.11.0, |
| 114 | + // dialogflow-v2 1.18.0, google-maps-routes-v1 1.1.0, and |
| 115 | + // google-maps-routing-v2 1.2.0. |
| 116 | + google_cloud_type::model::LatLng, |
| 117 | + // Converted in google-maps-routing-v2 1.2.0. |
| 118 | + google_cloud_type::model::LocalizedText, |
| 119 | + // Converted in google-maps-routes-v1 1.1.0 and |
| 120 | + // google-maps-routing-v2 1.2.0. |
| 121 | + google_cloud_type::model::Money, |
| 122 | + // Converted in aiplatform-v1 1.18.0. |
| 123 | + google_cloud_api::model::HttpBody, |
| 124 | + // Converted in logging-v2 1.15.0. |
| 125 | + google_cloud_api::model::MonitoredResource, |
| 126 | + google_cloud_logging_type::model::HttpRequest, |
| 127 | + google_cloud_logging_type::model::LogSeverity, |
| 128 | + // Converted in storage 1.21.0. |
| 129 | + google_cloud_iam_v1::model::AuditConfig, |
| 130 | + google_cloud_iam_v1::model::AuditConfigDelta, |
| 131 | + google_cloud_iam_v1::model::AuditLogConfig, |
| 132 | + google_cloud_iam_v1::model::Binding, |
| 133 | + google_cloud_iam_v1::model::BindingDelta, |
| 134 | + google_cloud_iam_v1::model::GetIamPolicyRequest, |
| 135 | + google_cloud_iam_v1::model::GetPolicyOptions, |
| 136 | + google_cloud_iam_v1::model::Policy, |
| 137 | + google_cloud_iam_v1::model::PolicyDelta, |
| 138 | + google_cloud_iam_v1::model::SetIamPolicyRequest, |
| 139 | + google_cloud_iam_v1::model::TestIamPermissionsRequest, |
| 140 | + google_cloud_iam_v1::model::TestIamPermissionsResponse, |
| 141 | + google_cloud_iam_v1::model::audit_config_delta::Action, |
| 142 | + google_cloud_iam_v1::model::audit_log_config::LogType, |
| 143 | + google_cloud_iam_v1::model::binding_delta::Action, |
| 144 | + // Converted in storage 1.21.0. The `Operation` impl is handwritten, in |
| 145 | + // `src/control/convert.rs`. |
| 146 | + google_cloud_longrunning::model::CancelOperationRequest, |
| 147 | + google_cloud_longrunning::model::DeleteOperationRequest, |
| 148 | + google_cloud_longrunning::model::GetOperationRequest, |
| 149 | + google_cloud_longrunning::model::ListOperationsRequest, |
| 150 | + google_cloud_longrunning::model::ListOperationsResponse, |
| 151 | + google_cloud_longrunning::model::Operation, |
| 152 | + google_cloud_longrunning::model::OperationInfo, |
| 153 | + google_cloud_longrunning::model::WaitOperationRequest, |
| 154 | + ); |
| 155 | +} |
| 156 | + |
| 157 | +/// Types that `gaxi` itself converts with `ToProto`. |
| 158 | +/// |
| 159 | +/// Published code calls `.to_proto()` on these types unqualified, e.g. storage |
| 160 | +/// 1.21.0 `generated/convert/control/convert.rs:62`: |
| 161 | +/// `create_time: self.create_time.map(|v| v.to_proto())`. |
| 162 | +/// |
| 163 | +/// A local impl would itself be a second impl, so these checks have none. |
| 164 | +/// Nothing in the call constrains the `ToProto<T>` parameter, so each call |
| 165 | +/// compiles only while `gaxi` provides exactly one impl. |
| 166 | +#[cfg(test)] |
| 167 | +mod gaxi_to_proto { |
| 168 | + use gaxi::prost::{ConvertError, ToProto}; |
| 169 | + |
| 170 | + macro_rules! assert_single_impl { |
| 171 | + ($($ty:ty),* $(,)?) => { |
| 172 | + #[test] |
| 173 | + fn single_impl() -> Result<(), ConvertError> { |
| 174 | + $( |
| 175 | + let _ = <$ty>::default().to_proto()?; |
| 176 | + )* |
| 177 | + Ok(()) |
| 178 | + } |
| 179 | + }; |
| 180 | + } |
| 181 | + |
| 182 | + assert_single_impl!( |
| 183 | + google_cloud_wkt::Duration, |
| 184 | + google_cloud_wkt::FieldMask, |
| 185 | + google_cloud_wkt::Timestamp, |
| 186 | + google_cloud_wkt::Struct, |
| 187 | + google_cloud_wkt::Value, |
| 188 | + google_cloud_wkt::ListValue, |
| 189 | + google_cloud_wkt::NullValue, |
| 190 | + google_cloud_wkt::Empty, |
| 191 | + (), |
| 192 | + bool, |
| 193 | + f32, |
| 194 | + i32, |
| 195 | + u32, |
| 196 | + f64, |
| 197 | + i64, |
| 198 | + u64, |
| 199 | + String, |
| 200 | + bytes::Bytes, |
| 201 | + ); |
| 202 | +} |
| 203 | + |
| 204 | +/// Prost types that `gaxi` converts with `FromProto`. |
| 205 | +/// |
| 206 | +/// Published code passes the result of an unqualified `.cnv()` to a setter |
| 207 | +/// that accepts any `Into<Model>`, e.g. storage 1.21.0 |
| 208 | +/// `generated/convert/control/convert.rs:75`: |
| 209 | +/// `.set_or_clear_create_time(self.create_time.map(|v| v.cnv()).transpose()?)`. |
| 210 | +/// |
| 211 | +/// `set_or_clear()` has the same shape as that setter, and the calls below |
| 212 | +/// copy the `map(...).transpose()?` expression. The `Into` bound does not pin |
| 213 | +/// the `FromProto<T>` parameter, so each call compiles only while `gaxi` |
| 214 | +/// provides exactly one impl. |
| 215 | +#[cfg(test)] |
| 216 | +mod gaxi_from_proto { |
| 217 | + use gaxi::prost::{ConvertError, FromProto}; |
| 218 | + |
| 219 | + fn set_or_clear<M, T: Into<M>>(_: Option<T>) {} |
| 220 | + |
| 221 | + macro_rules! assert_single_impl { |
| 222 | + ($($prost:ty => $model:ty),* $(,)?) => { |
| 223 | + #[test] |
| 224 | + fn single_impl() -> Result<(), ConvertError> { |
| 225 | + $( |
| 226 | + set_or_clear::<$model, _>( |
| 227 | + Some(<$prost>::default()).map(|v| v.cnv()).transpose()?, |
| 228 | + ); |
| 229 | + )* |
| 230 | + Ok(()) |
| 231 | + } |
| 232 | + }; |
| 233 | + } |
| 234 | + |
| 235 | + assert_single_impl!( |
| 236 | + prost_types::Duration => google_cloud_wkt::Duration, |
| 237 | + prost_types::FieldMask => google_cloud_wkt::FieldMask, |
| 238 | + prost_types::Timestamp => google_cloud_wkt::Timestamp, |
| 239 | + prost_types::Struct => google_cloud_wkt::Struct, |
| 240 | + prost_types::Value => google_cloud_wkt::Value, |
| 241 | + prost_types::ListValue => google_cloud_wkt::ListValue, |
| 242 | + prost_types::NullValue => google_cloud_wkt::NullValue, |
| 243 | + gaxi::prost::Empty => google_cloud_wkt::Empty, |
| 244 | + () => (), |
| 245 | + bool => bool, |
| 246 | + f32 => f32, |
| 247 | + i32 => i32, |
| 248 | + u32 => u32, |
| 249 | + f64 => f64, |
| 250 | + i64 => i64, |
| 251 | + u64 => u64, |
| 252 | + String => String, |
| 253 | + bytes::Bytes => bytes::Bytes, |
| 254 | + ); |
| 255 | +} |
0 commit comments