feat(oauth2): add quickstart, README, etc. (#12754)

coryan · web-flow · commit e68c72e0a2a8 · 2023-09-28T22:34:21.000Z
This will make the library more usable (I think) by including a
quickstart, README, landing page for Doxygen, etc.
diff --git a/BUILD.bazel b/BUILD.bazel
@@ -30,6 +30,8 @@ TRANSITION_LIBRARIES = GOOGLE_CLOUD_CPP_TRANSITION_LIBRARIES
 
 GA_LIBRARIES = GOOGLE_CLOUD_CPP_GA_LIBRARIES
 
+NO_MOCK_LIBRARIES = ["oauth2"]
+
 [cc_library(
     name = "experimental-{library}".format(library = library),
     deps = [
@@ -49,7 +51,7 @@ GA_LIBRARIES = GOOGLE_CLOUD_CPP_GA_LIBRARIES
             library_dir = google_cloud_cpp_library_dir_name(library),
         ),
     ],
-) for library in EXPERIMENTAL_LIBRARIES]
+) for library in EXPERIMENTAL_LIBRARIES if library not in NO_MOCK_LIBRARIES]
 
 [cc_library(
     name = "experimental-{library}".format(library = library),
@@ -95,7 +97,7 @@ GA_LIBRARIES = GOOGLE_CLOUD_CPP_GA_LIBRARIES
             library_dir = google_cloud_cpp_library_dir_name(library),
         ),
     ],
-) for library in GA_LIBRARIES + TRANSITION_LIBRARIES]
+) for library in GA_LIBRARIES + TRANSITION_LIBRARIES if library not in NO_MOCK_LIBRARIES]
 
 cc_library(
     name = "bigquery-mocks",
@@ -162,14 +164,6 @@ cc_library(
     ],
 )
 
-cc_library(
-    name = "oauth2",
-    testonly = True,
-    deps = [
-        "//google/cloud/oauth2:google_cloud_cpp_oauth2",
-    ],
-)
-
 cc_library(
     name = "experimental-opentelemetry",
     deprecation = "this library is now GA, please use //:opentelemetry instead.",
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -259,7 +259,6 @@ if (GOOGLE_CLOUD_CPP_USE_INSTALLED_COMMON)
     endif ()
     if (GOOGLE_CLOUD_CPP_ENABLE_REST)
         find_package(google_cloud_cpp_rest_internal CONFIG REQUIRED)
-        find_package(google_cloud_cpp_oauth2 CONFIG REQUIRED)
     endif ()
     if (GOOGLE_CLOUD_CPP_ENABLE_REST AND GOOGLE_CLOUD_CPP_ENABLE_GRPC)
         find_package(google_cloud_cpp_rest_protobuf_internal CONFIG REQUIRED)
diff --git a/README.md b/README.md
@@ -301,6 +301,9 @@ See each library's `README.md` file for more information about:
 - [Notebooks API](google/cloud/notebooks/README.md)
   [\[quickstart\]](google/cloud/notebooks/quickstart/README.md)
   [\[reference\]](https://cloud.google.com/cpp/docs/reference/notebooks/latest)
+- [OAuth2 Access Token Generation](google/cloud/oauth2/README.md)
+  [\[quickstart\]](google/cloud/oauth2/quickstart/README.md)
+  [\[reference\]](https://cloud.google.com/cpp/docs/reference/oauth2/latest)
 - [Cloud Optimization API](google/cloud/optimization/README.md)
   [\[quickstart\]](google/cloud/optimization/quickstart/README.md)
   [\[reference\]](https://cloud.google.com/cpp/docs/reference/optimization/latest)
diff --git a/ci/cloudbuild/builds/check-api.sh b/ci/cloudbuild/builds/check-api.sh
@@ -34,7 +34,7 @@ else
   readonly ENABLED_FEATURES="__ga_libraries__,opentelemetry"
   mapfile -t library_list < <(cmake -DCMAKE_MODULE_PATH="${PWD}/cmake" -P cmake/print-ga-libraries.cmake 2>&1)
   # These libraries are not "features", but they are part of the public API
-  library_list+=("common" "grpc_utils" "oauth2")
+  library_list+=("common" "grpc_utils")
   # This is a GA library, not included in __ga_libraries__
   library_list+=("opentelemetry")
 fi
diff --git a/ci/cloudbuild/builds/checkers.sh b/ci/cloudbuild/builds/checkers.sh
@@ -203,7 +203,7 @@ time {
   done
 
   mapfile -t libraries < <(features::libraries)
-  for library in "${libraries[@]}" opentelemetry; do
+  for library in "${libraries[@]}" opentelemetry oauth2; do
     ci/generate-markdown/update-library-readme.sh "${library}"
   done
 }
diff --git a/ci/cloudbuild/builds/cmake-install.sh b/ci/cloudbuild/builds/cmake-install.sh
@@ -96,8 +96,9 @@ expected_dirs+=(
   # no RPC services in google/cloud/metastore/logging
   ./include/google/cloud/metastore/logging
   ./include/google/cloud/metastore/logging/v1
-  # mocks and opentelemetry/* are hand-crafted directories
+  # mocks, oauth2, and opentelemetry/* are hand-crafted directories
   ./include/google/cloud/mocks
+  ./include/google/cloud/oauth2
   ./include/google/cloud/opentelemetry
   ./include/google/cloud/opentelemetry/internal
   # orgpolicy/v1 is not automatically added. It is used by
@@ -200,8 +201,8 @@ env -C "${out_dir}" ctest "${ctest_args[@]}"
 # Tests the installed artifacts by building and running the quickstarts.
 # shellcheck disable=SC2046
 feature_list="$(printf "%s;" $(features::libraries))"
-# GCS+gRPC and OpenTelemetry also have quickstarts.
-feature_list="${feature_list}experimental-storage_grpc;opentelemetry"
+# GCS+gRPC, OAuth2, and OpenTelemetry also have quickstarts.
+feature_list="${feature_list}experimental-storage_grpc;oauth2;opentelemetry"
 cmake -G Ninja \
   -S "${PROJECT_ROOT}/ci/verify_quickstart" \
   -B "${PROJECT_ROOT}/cmake-out/quickstart" \
diff --git a/ci/cloudbuild/builds/lib/features.sh b/ci/cloudbuild/builds/lib/features.sh
@@ -59,13 +59,28 @@ function features::libraries() {
   printf "%s\n" "${feature_list[@]}" | sort -u
 }
 
+function features::_internal_extra() {
+  local list=(
+    experimental-bigquery_rest
+    experimental-storage_grpc
+    oauth2
+    opentelemetry
+  )
+  printf "%s\n" "${list[@]}"
+}
+
 function features::list_full() {
   local feature_list
   mapfile -t feature_list < <(features::libraries)
-  feature_list+=(opentelemetry experimental-storage_grpc grafeas)
-  printf "%s\n" "${feature_list[@]}" | sort -u
+  local extra_list
+  mapfile -t extra_list < <(features::_internal_extra)
+  printf "%s\n" "${feature_list[@]}" "${extra_list[@]}" | sort -u
 }
 
 function features::list_full_cmake() {
-  echo "__ga_libraries__,__experimental_libraries__,experimental-storage_grpc,opentelemetry,experimental-bigquery_rest"
+  local feature_list
+  mapfile -t feature_list < <(features::list_full)
+  local concat
+  concat="$(printf ",%s" "${feature_list[@]}" "${extra_list[@]}")"
+  echo "${concat:1}"
 }
diff --git a/ci/generate-markdown/generate-readme.sh b/ci/generate-markdown/generate-readme.sh
@@ -37,7 +37,11 @@ file="README.md"
   mapfile -t features < <(cmake -DCMAKE_MODULE_PATH="${PWD}/cmake" -P cmake/print-ga-features.cmake 2>&1 | LC_ALL=C sort)
   sed '/<!-- inject-GA-features-start -->/q' "${file}"
   for feature in "${features[@]}"; do
-    description="$(sed -n '1 s/# \(.*\) C++ Client Library/\1/p' "google/cloud/${feature}/README.md")"
+    if [[ "${feature}" == "oauth2" ]]; then
+      description="OAuth2 Access Token Generation"
+    else
+      description="$(sed -n '1 s/# \(.*\) C++ Client Library/\1/p' "google/cloud/${feature}/README.md")"
+    fi
     printf -- '- [%s](google/cloud/%s/README.md)\n' "${description}" "${feature}"
     printf -- '  [[quickstart]](google/cloud/%s/quickstart/README.md)\n' "${feature}"
     printf -- '  [[reference]](https://cloud.google.com/cpp/docs/reference/%s/latest)\n' "${feature}"
diff --git a/cmake/GoogleCloudCppFeatures.cmake b/cmake/GoogleCloudCppFeatures.cmake
@@ -27,7 +27,8 @@ set(GOOGLE_CLOUD_CPP_LEGACY_FEATURES
 # Protobuf messages. We do not bother to have an internal library that depends
 # on Protobuf but not gRPC. So these libraries must depend on
 # `google_cloud_cpp_grpc_utils`.
-set(GOOGLE_CLOUD_CPP_REST_ONLY_FEATURES "storage;experimental-bigquery_rest")
+set(GOOGLE_CLOUD_CPP_REST_ONLY_FEATURES
+    "oauth2;storage;experimental-bigquery_rest")
 
 set(GOOGLE_CLOUD_CPP_EXPERIMENTAL_LIBRARIES # cmake-format: sorted
     # This is WIP, it needs a number of hand-crafted APIs.
@@ -110,6 +111,7 @@ set(GOOGLE_CLOUD_CPP_GA_LIBRARIES
     "networksecurity"
     "networkservices"
     "notebooks"
+    "oauth2"
     "optimization"
     "orgpolicy"
     "osconfig"
@@ -365,11 +367,17 @@ macro (google_cloud_cpp_enable_cleanup)
         OR (compute IN_LIST GOOGLE_CLOUD_CPP_ENABLE)
         OR (compute_features)
         OR (experimental-bigquery_rest IN_LIST GOOGLE_CLOUD_CPP_ENABLE)
+        OR (oauth2 IN_LIST GOOGLE_CLOUD_CPP_ENABLE)
         OR (opentelemetry IN_LIST GOOGLE_CLOUD_CPP_ENABLE)
         OR (sql IN_LIST GOOGLE_CLOUD_CPP_ENABLE)
         OR (generator IN_LIST GOOGLE_CLOUD_CPP_ENABLE))
         set(GOOGLE_CLOUD_CPP_ENABLE_REST ON)
+        # Backwards compatibility. In the original release of `oauth2` we
+        # automatically compiled the library if REST was enabled
+        list(APPEND GOOGLE_CLOUD_CPP_ENABLE oauth2)
     endif ()
+
+    list(REMOVE_DUPLICATES GOOGLE_CLOUD_CPP_ENABLE)
 endmacro ()
 
 # Configure CMake to build the features listed in `GOOGLE_CLOUD_CPP_ENABLE`.
diff --git a/google/cloud/CMakeLists.txt b/google/cloud/CMakeLists.txt
@@ -60,7 +60,6 @@ endif ()
 
 if (GOOGLE_CLOUD_CPP_ENABLE_REST)
     include("${CMAKE_CURRENT_SOURCE_DIR}/google_cloud_cpp_rest_internal.cmake")
-    add_subdirectory(oauth2)
 endif ()
 
 if (GOOGLE_CLOUD_CPP_ENABLE_REST AND GOOGLE_CLOUD_CPP_ENABLE_GRPC)
diff --git a/google/cloud/oauth2/CMakeLists.txt b/google/cloud/oauth2/CMakeLists.txt
@@ -19,8 +19,12 @@ set(DOXYGEN_PROJECT_NAME "OAuth2 Access Token Generation Library")
 set(DOXYGEN_PROJECT_BRIEF
     "Create OAuth2 Access Tokens for any GCP authentication mechanism")
 set(DOXYGEN_PROJECT_NUMBER "${PROJECT_VERSION}")
+set(DOXYGEN_EXAMPLE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/quickstart)
 set(DOXYGEN_EXCLUDE_SYMBOLS "internal")
 
+include(GoogleCloudCppDoxygen)
+google_cloud_cpp_doxygen_targets("oauth2" DEPENDS cloud-docs)
+
 add_library(google_cloud_cpp_oauth2 # cmake-format: sort
             access_token_generator.cc access_token_generator.h)
 target_link_libraries(
@@ -58,7 +62,8 @@ install(
     ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
             COMPONENT google_cloud_cpp_development)
 
-google_cloud_cpp_install_headers(google_cloud_cpp_oauth2 include/google/cloud)
+google_cloud_cpp_install_headers(google_cloud_cpp_oauth2
+                                 include/google/cloud/oauth2)
 
 google_cloud_cpp_add_pkgconfig(
     oauth2 "${DOXYGEN_PROJECT_NAME}" "${DOXYGEN_PROJECT_BRIEF}"
@@ -105,3 +110,16 @@ foreach (fname IN LISTS google_cloud_cpp_oauth2_unit_tests)
     google_cloud_cpp_add_common_options(${target})
     add_test(NAME ${target} COMMAND ${target})
 endforeach ()
+
+if (NOT GOOGLE_CLOUD_CPP_ENABLE_CXX_EXCEPTIONS)
+    return()
+endif ()
+
+add_executable(oauth2_quickstart "quickstart/quickstart.cc")
+target_link_libraries(oauth2_quickstart PRIVATE google-cloud-cpp::oauth2)
+google_cloud_cpp_add_common_options(oauth2_quickstart)
+add_test(NAME oauth2_quickstart
+         COMMAND cmake -P "${PROJECT_SOURCE_DIR}/cmake/quickstart-runner.cmake"
+                 $<TARGET_FILE:oauth2_quickstart>)
+set_tests_properties(oauth2_quickstart PROPERTIES LABELS
+                                                  "integration-test;quickstart")
diff --git a/google/cloud/oauth2/README.md b/google/cloud/oauth2/README.md
@@ -0,0 +1,62 @@
+# OAuth2 Access Token Generation Library
+
+This library contains helpers to create OAuth2 access tokens. This may be useful
+when trying to access customer services deployed to Cloud Run, or when using
+Google APIs that lack a client library in `google-cloud-cpp`.
+
+While this library is **GA**, please note that the Google Cloud C++ client
+libraries do **not** follow [Semantic Versioning](https://semver.org/).
+
+## Quickstart
+
+The [quickstart/](quickstart/README.md) directory contains a minimal environment
+to get started using this client library in a larger project. The following
+"Hello World" program is used in this quickstart, and should give you a taste of
+this library.
+
+For detailed instructions on how to build and install this library, see the
+top-level [README](/README.md#building-and-installing).
+
+<!-- inject-quickstart-start -->
+
+```cc
+#include "google/cloud/oauth2/access_token_generator.h"
+#include <iostream>
+
+int main(int argc, char* argv[]) try {
+  if (argc != 1) {
+    std::cerr << "Usage: " << argv[0] << "\n";
+    return 1;
+  }
+
+  // Use Application Default Credentials to initialize an AccessTokenGenerator
+  // retrieve the access token.
+  auto credentials = google::cloud::MakeGoogleDefaultCredentials();
+  auto generator =
+      google::cloud::oauth2::MakeAccessTokenGenerator(*credentials);
+  auto token = generator->GetToken();
+  if (!token) throw std::move(token).status();
+  // Only print the first few characters to avoid leaking tokens in test logs.
+  std::cout << "The access token starts with " << token->token.substr(0, 16)
+            << "\n";
+
+  return 0;
+} catch (google::cloud::Status const& status) {
+  std::cerr << "google::cloud::Status thrown: " << status << "\n";
+  return 1;
+}
+```
+
+<!-- inject-quickstart-end -->
+
+## More Information
+
+- [Using OAuth 2.0 to Access Google APIs]: for general information around OAuth2
+  and their use in Google APIs.
+- [Reference doxygen documentation][doxygen-link] for each release of this
+  client library
+- Detailed header comments in our [public `.h`][source-link] files
+
+[doxygen-link]: https://cloud.google.com/cpp/docs/reference/oauth2/latest/
+[source-link]: https://github.com/googleapis/google-cloud-cpp/tree/main/google/cloud/oauth2
+[using oauth 2.0 to access google apis]: https://developers.google.com/identity/protocols/oauth2
diff --git a/google/cloud/oauth2/doc/main.dox b/google/cloud/oauth2/doc/main.dox
@@ -0,0 +1,32 @@
+/*!
+
+@mainpage OAuth2 Access Token Generation Library
+
+This library contains helpers to create OAuth2 access tokens. This may be useful
+when trying to access customer services deployed to Cloud Run, or when using
+Google APIs that lack a client library in `google-cloud-cpp`.
+
+@tableofcontents{HTML:2}
+
+## Quickstart
+
+The following shows the code that you'll run in the
+`google/cloud/oauth2/quickstart/` directory.
+This is the typical usage of the library in applications.
+
+@snippet quickstart.cc all
+
+## Main interfaces
+
+- [\c oauth2::AccessTokenGenerator](@ref google::cloud::oauth2::AccessTokenGenerator)
+- [\c oauth2::MakeAccessTokenGenerator()](@ref google::cloud::oauth2::MakeAccessTokenGenerator)
+
+## More Information
+
+- @ref common-error-handling - describes how the library reports errors.
+- [Authentication methods at Google] - has more information about authentication
+  and the Application Default credentials
+
+[Authentication methods at Google]: https://cloud.google.com/docs/authentication
+
+*/
diff --git a/google/cloud/oauth2/quickstart/BUILD.bazel b/google/cloud/oauth2/quickstart/BUILD.bazel
@@ -0,0 +1,25 @@
+# Copyright 2023 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
+#
+#     https://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.
+
+licenses(["notice"])  # Apache 2.0
+
+cc_binary(
+    name = "quickstart",
+    srcs = [
+        "quickstart.cc",
+    ],
+    deps = [
+        "@google_cloud_cpp//:oauth2",
+    ],
+)
diff --git a/google/cloud/oauth2/quickstart/CMakeLists.txt b/google/cloud/oauth2/quickstart/CMakeLists.txt
@@ -0,0 +1,32 @@
+# Copyright 2023 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
+#
+# https://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.
+
+# This file shows how to use the OAuth2 Access Token Generation library from a
+# larger CMake project.
+
+cmake_minimum_required(VERSION 3.10...3.24)
+project(google-cloud-cpp-oauth2-quickstart CXX)
+
+find_package(google_cloud_cpp_oauth2 REQUIRED)
+
+# MSVC requires some additional code to select the correct runtime library
+if (VCPKG_TARGET_TRIPLET MATCHES "-static$")
+    set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+else ()
+    set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
+endif ()
+
+# Define your targets.
+add_executable(quickstart quickstart.cc)
+target_link_libraries(quickstart google-cloud-cpp::oauth2)
diff --git a/google/cloud/oauth2/quickstart/Makefile b/google/cloud/oauth2/quickstart/Makefile
diff --git a/google/cloud/oauth2/quickstart/README.md b/google/cloud/oauth2/quickstart/README.md
diff --git a/google/cloud/oauth2/quickstart/WORKSPACE.bazel b/google/cloud/oauth2/quickstart/WORKSPACE.bazel
diff --git a/google/cloud/oauth2/quickstart/quickstart.cc b/google/cloud/oauth2/quickstart/quickstart.cc
diff --git a/libraries.bzl b/libraries.bzl

Original file line number	Diff line number	Diff line change
`@@ -203,7 +203,7 @@ time {`
`203`	`203`	`done`
`204`	`204`
`205`	`205`	`mapfile -t libraries < <(features::libraries)`
`206`		`- for library in "${libraries[@]}" opentelemetry; do`
	`206`	`+ for library in "${libraries[@]}" opentelemetry oauth2; do`
`207`	`207`	`ci/generate-markdown/update-library-readme.sh "${library}"`
`208`	`208`	`done`
`209`	`209`	`}`