|
| 1 | +# -*- coding: utf-8 -*- |
| 2 | +# Copyright 2026 Google LLC |
| 3 | +# |
| 4 | +# Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | +# you may not use this file except in compliance with the License. |
| 6 | +# You may obtain a copy of the License at |
| 7 | +# |
| 8 | +# http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | +# |
| 10 | +# Unless required by applicable law or agreed to in writing, software |
| 11 | +# distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | +# See the License for the specific language governing permissions and |
| 14 | +# limitations under the License. |
| 15 | +# |
| 16 | + |
| 17 | +"""Helpers for GAPIC client initialization.""" |
| 18 | + |
| 19 | +import os |
| 20 | +import re |
| 21 | +from typing import Optional |
| 22 | + |
| 23 | +from google.auth.exceptions import MutualTLSChannelError # type: ignore |
| 24 | +from google.auth.transport import mtls # type: ignore |
| 25 | + |
| 26 | + |
| 27 | + |
| 28 | +def get_default_mtls_endpoint(api_endpoint: Optional[str]) -> Optional[str]: |
| 29 | + """Converts api endpoint to mTLS endpoint. |
| 30 | +
|
| 31 | + Convert "*.sandbox.googleapis.com" and "*.googleapis.com" to |
| 32 | + "*.mtls.sandbox.googleapis.com" and "*.mtls.googleapis.com" respectively. |
| 33 | + Args: |
| 34 | + api_endpoint (Optional[str]): the api endpoint to convert. |
| 35 | + Returns: |
| 36 | + Optional[str]: converted mTLS api endpoint. |
| 37 | + """ |
| 38 | + if not api_endpoint: |
| 39 | + return api_endpoint |
| 40 | + |
| 41 | + mtls_endpoint_re = re.compile( |
| 42 | + r"(?P<name>[^.]+)(?P<mtls>\.mtls)?(?P<sandbox>\.sandbox)?(?P<googledomain>\.googleapis\.com)?" |
| 43 | + ) |
| 44 | + |
| 45 | + m = mtls_endpoint_re.match(api_endpoint) |
| 46 | + if m is None: |
| 47 | + # Could not parse api_endpoint; return as-is. |
| 48 | + return api_endpoint |
| 49 | + |
| 50 | + name, mtls_group, sandbox, googledomain = m.groups() |
| 51 | + if mtls_group or not googledomain: |
| 52 | + return api_endpoint |
| 53 | + |
| 54 | + if sandbox: |
| 55 | + return api_endpoint.replace( |
| 56 | + "sandbox.googleapis.com", "mtls.sandbox.googleapis.com" |
| 57 | + ) |
| 58 | + |
| 59 | + return api_endpoint.replace(".googleapis.com", ".mtls.googleapis.com") |
| 60 | + |
| 61 | + |
| 62 | +def use_client_cert_effective() -> bool: |
| 63 | + """Returns whether client certificate should be used for mTLS if the |
| 64 | + google-auth version supports should_use_client_cert automatic mTLS enablement. |
| 65 | +
|
| 66 | + Alternatively, read from the GOOGLE_API_USE_CLIENT_CERTIFICATE env var. |
| 67 | +
|
| 68 | + Returns: |
| 69 | + bool: whether client certificate should be used for mTLS |
| 70 | + Raises: |
| 71 | + ValueError: (If using a version of google-auth without should_use_client_cert and |
| 72 | + GOOGLE_API_USE_CLIENT_CERTIFICATE is set to an unexpected value.) |
| 73 | + """ |
| 74 | + # check if google-auth version supports should_use_client_cert for automatic mTLS enablement |
| 75 | + if hasattr(mtls, "should_use_client_cert"): # pragma: NO COVER |
| 76 | + return mtls.should_use_client_cert() |
| 77 | + else: # pragma: NO COVER |
| 78 | + # if unsupported, fallback to reading from env var |
| 79 | + use_client_cert_str = os.getenv( |
| 80 | + "GOOGLE_API_USE_CLIENT_CERTIFICATE", "false" |
| 81 | + ).lower() |
| 82 | + if use_client_cert_str not in ("true", "false"): |
| 83 | + raise ValueError( |
| 84 | + "Environment variable `GOOGLE_API_USE_CLIENT_CERTIFICATE` must be" |
| 85 | + " either `true` or `false`" |
| 86 | + ) |
| 87 | + return use_client_cert_str == "true" |
| 88 | + |
| 89 | + |
| 90 | +def get_api_endpoint( |
| 91 | + api_override: Optional[str], |
| 92 | + client_cert_source: Optional[bytes], |
| 93 | + universe_domain: str, |
| 94 | + use_mtls_endpoint: str, |
| 95 | + default_universe: str, |
| 96 | + default_mtls_endpoint: Optional[str], |
| 97 | + default_endpoint_template: str, |
| 98 | +) -> str: |
| 99 | + """Return the API endpoint used by the client. |
| 100 | +
|
| 101 | + Args: |
| 102 | + api_override (Optional[str]): The API endpoint override. |
| 103 | + client_cert_source (Optional[bytes]): The client certificate source. |
| 104 | + universe_domain (str): The universe domain. |
| 105 | + use_mtls_endpoint (str): How to use the mTLS endpoint. |
| 106 | + default_universe (str): The default universe. |
| 107 | + default_mtls_endpoint (Optional[str]): The default mTLS endpoint. |
| 108 | + default_endpoint_template (str): The default endpoint template. |
| 109 | +
|
| 110 | + Returns: |
| 111 | + str: The API endpoint to be used by the client. |
| 112 | + """ |
| 113 | + if api_override is not None: |
| 114 | + api_endpoint = api_override |
| 115 | + elif use_mtls_endpoint == "always" or ( |
| 116 | + use_mtls_endpoint == "auto" and client_cert_source |
| 117 | + ): |
| 118 | + if universe_domain != default_universe: |
| 119 | + raise MutualTLSChannelError( |
| 120 | + f"mTLS is not supported in any universe other than {default_universe}." |
| 121 | + ) |
| 122 | + api_endpoint = default_mtls_endpoint |
| 123 | + else: |
| 124 | + api_endpoint = default_endpoint_template.format( |
| 125 | + UNIVERSE_DOMAIN=universe_domain |
| 126 | + ) |
| 127 | + return api_endpoint |
| 128 | + |
0 commit comments