api_core: Add routing header (#4336)

* api_core: Add routing header

* Fix linting

* Review fixes

* More review fixes

* Documentation fixes

Author: evaogbe

google/api_core/gapic_v1/__init__.py

@@ -14,8 +14,10 @@
 
 from google.api_core.gapic_v1 import config
 from google.api_core.gapic_v1 import method
+from google.api_core.gapic_v1 import routing_header
 
 __all__ = [
     'config',
     'method',
+    'routing_header',
 ]

google/api_core/gapic_v1/routing_header.py

@@ -0,0 +1,53 @@
+# Copyright 2017 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Helpers for constructing routing headers.
+
+These headers are used by Google infrastructure to determine how to route
+requests, especially for services that are regional.
+
+Generally, these headers are specified as gRPC metadata.
+"""
+
+from six.moves.urllib.parse import urlencode
+
+ROUTING_METADATA_KEY = 'x-goog-header-params'
+
+
+def to_routing_header(params):
+    """Returns a routing header string for the given request parameters.
+
+    Args:
+        params (Mapping[str, Any]): A dictionary containing the request
+            parameters used for routing.
+
+    Returns:
+        str: The routing header string.
+    """
+    return urlencode(params)
+
+
+def to_grpc_metadata(params):
+    """Returns the gRPC metadata containing the routing headers for the given
+    request parameters.
+
+    Args:
+        params (Mapping[str, Any]): A dictionary containing the request
+            parameters used for routing.
+
+    Returns:
+        Tuple(str, str): The gRPC metadata containing the routing header key
+            and value.
+    """
+    return (ROUTING_METADATA_KEY, to_routing_header(params))

tests/unit/gapic/test_routing_header.py

@@ -0,0 +1,29 @@
+# Copyright 2017 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from google.api_core.gapic_v1 import routing_header
+
+
+def test_to_routing_header():
+    params = [('name', 'meep'), ('book.read', '1')]
+    value = routing_header.to_routing_header(params)
+    assert value == "name=meep&book.read=1"
+
+
+def test_to_grpc_metadata():
+    params = [('name', 'meep'), ('book.read', '1')]
+    metadata = routing_header.to_grpc_metadata(params)
+    assert metadata == (
+        routing_header.ROUTING_METADATA_KEY, "name=meep&book.read=1")