feat: add AddIpOverride RPC (#26975)

feat: add `express_settings` to `Key`
docs: clarify `Event.express` field
docs: fix billing, quota, and usecase links

google-cloud-recaptcha_enterprise-v1/.owlbot-manifest.json

@@ -36,6 +36,7 @@
     "proto_docs/google/protobuf/timestamp.rb",
     "proto_docs/google/rpc/status.rb",
     "snippets/Gemfile",
+    "snippets/recaptcha_enterprise_service/add_ip_override.rb",
     "snippets/recaptcha_enterprise_service/annotate_assessment.rb",
     "snippets/recaptcha_enterprise_service/create_assessment.rb",
     "snippets/recaptcha_enterprise_service/create_firewall_policy.rb",

google-cloud-recaptcha_enterprise-v1/gapic_metadata.json

@@ -55,6 +55,11 @@
                 "migrate_key"
               ]
             },
+            "AddIpOverride": {
+              "methods": [
+                "add_ip_override"
+              ]
+            },
             "GetMetrics": {
               "methods": [
                 "get_metrics"

google-cloud-recaptcha_enterprise-v1/lib/google/cloud/recaptcha_enterprise/v1/recaptcha_enterprise_service/client.rb

@@ -941,11 +941,11 @@ def delete_key request, options = nil
             #     Optional. If true, skips the billing check.
             #     A reCAPTCHA Enterprise key or migrated key behaves differently than a
             #     reCAPTCHA (non-Enterprise version) key when you reach a quota limit (see
-            #     https://cloud.google.com/recaptcha-enterprise/quotas#quota_limit). To avoid
+            #     https://cloud.google.com/recaptcha/quotas#quota_limit). To avoid
             #     any disruption of your usage, we check that a billing account is present.
             #     If your usage of reCAPTCHA is under the free quota, you can safely skip the
             #     billing check and proceed with the migration. See
-            #     https://cloud.google.com/recaptcha-enterprise/docs/billing-information.
+            #     https://cloud.google.com/recaptcha/docs/billing-information.
             #
             # @yield [response, operation] Access the result along with the RPC operation
             # @yieldparam response [::Google::Cloud::RecaptchaEnterprise::V1::Key]
@@ -1012,6 +1012,98 @@ def migrate_key request, options = nil
               raise ::Google::Cloud::Error.from_error(e)
             end
 
+            ##
+            # Adds an IP override to a key. The following restrictions hold:
+            # * The maximum number of IP overrides per key is 100.
+            # * For any conflict (such as IP already exists or IP part of an existing
+            #   IP range), an error will be returned.
+            #
+            # @overload add_ip_override(request, options = nil)
+            #   Pass arguments to `add_ip_override` via a request object, either of type
+            #   {::Google::Cloud::RecaptchaEnterprise::V1::AddIpOverrideRequest} or an equivalent Hash.
+            #
+            #   @param request [::Google::Cloud::RecaptchaEnterprise::V1::AddIpOverrideRequest, ::Hash]
+            #     A request object representing the call parameters. Required. To specify no
+            #     parameters, or to keep all the default parameter values, pass an empty Hash.
+            #   @param options [::Gapic::CallOptions, ::Hash]
+            #     Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
+            #
+            # @overload add_ip_override(name: nil, ip_override_data: nil)
+            #   Pass arguments to `add_ip_override` via keyword arguments. Note that at
+            #   least one keyword argument is required. To specify no parameters, or to keep all
+            #   the default parameter values, pass an empty Hash as a request object (see above).
+            #
+            #   @param name [::String]
+            #     Required. The name of the key to which the IP override is added, in the
+            #     format `projects/{project}/keys/{key}`.
+            #   @param ip_override_data [::Google::Cloud::RecaptchaEnterprise::V1::IpOverrideData, ::Hash]
+            #     Required. IP override added to the key.
+            #
+            # @yield [response, operation] Access the result along with the RPC operation
+            # @yieldparam response [::Google::Cloud::RecaptchaEnterprise::V1::AddIpOverrideResponse]
+            # @yieldparam operation [::GRPC::ActiveCall::Operation]
+            #
+            # @return [::Google::Cloud::RecaptchaEnterprise::V1::AddIpOverrideResponse]
+            #
+            # @raise [::Google::Cloud::Error] if the RPC is aborted.
+            #
+            # @example Basic example
+            #   require "google/cloud/recaptcha_enterprise/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::RecaptchaEnterprise::V1::RecaptchaEnterpriseService::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::RecaptchaEnterprise::V1::AddIpOverrideRequest.new
+            #
+            #   # Call the add_ip_override method.
+            #   result = client.add_ip_override request
+            #
+            #   # The returned object is of type Google::Cloud::RecaptchaEnterprise::V1::AddIpOverrideResponse.
+            #   p result
+            #
+            def add_ip_override request, options = nil
+              raise ::ArgumentError, "request must be provided" if request.nil?
+
+              request = ::Gapic::Protobuf.coerce request, to: ::Google::Cloud::RecaptchaEnterprise::V1::AddIpOverrideRequest
+
+              # Converts hash and nil to an options object
+              options = ::Gapic::CallOptions.new(**options.to_h) if options.respond_to? :to_h
+
+              # Customize the options with defaults
+              metadata = @config.rpcs.add_ip_override.metadata.to_h
+
+              # Set x-goog-api-client, x-goog-user-project and x-goog-api-version headers
+              metadata[:"x-goog-api-client"] ||= ::Gapic::Headers.x_goog_api_client \
+                lib_name: @config.lib_name, lib_version: @config.lib_version,
+                gapic_version: ::Google::Cloud::RecaptchaEnterprise::V1::VERSION
+              metadata[:"x-goog-api-version"] = API_VERSION unless API_VERSION.empty?
+              metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
+
+              header_params = {}
+              if request.name
+                header_params["name"] = request.name
+              end
+
+              request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
+              metadata[:"x-goog-request-params"] ||= request_params_header
+
+              options.apply_defaults timeout:      @config.rpcs.add_ip_override.timeout,
+                                     metadata:     metadata,
+                                     retry_policy: @config.rpcs.add_ip_override.retry_policy
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
+                                     retry_policy: @config.retry_policy
+
+              @recaptcha_enterprise_service_stub.call_rpc :add_ip_override, request, options: options do |response, operation|
+                yield response, operation if block_given?
+                return response
+              end
+            rescue ::GRPC::BadStatus => e
+              raise ::Google::Cloud::Error.from_error(e)
+            end
+
             ##
             # Get some aggregated metrics for a Key. This data can be used to build
             # dashboards.
@@ -2163,6 +2255,11 @@ class Rpcs
                 #
                 attr_reader :migrate_key
                 ##
+                # RPC-specific configuration for `add_ip_override`
+                # @return [::Gapic::Config::Method]
+                #
+                attr_reader :add_ip_override
+                ##
                 # RPC-specific configuration for `get_metrics`
                 # @return [::Gapic::Config::Method]
                 #
@@ -2233,6 +2330,8 @@ def initialize parent_rpcs = nil
                   @delete_key = ::Gapic::Config::Method.new delete_key_config
                   migrate_key_config = parent_rpcs.migrate_key if parent_rpcs.respond_to? :migrate_key
                   @migrate_key = ::Gapic::Config::Method.new migrate_key_config
+                  add_ip_override_config = parent_rpcs.add_ip_override if parent_rpcs.respond_to? :add_ip_override
+                  @add_ip_override = ::Gapic::Config::Method.new add_ip_override_config
                   get_metrics_config = parent_rpcs.get_metrics if parent_rpcs.respond_to? :get_metrics
                   @get_metrics = ::Gapic::Config::Method.new get_metrics_config
                   create_firewall_policy_config = parent_rpcs.create_firewall_policy if parent_rpcs.respond_to? :create_firewall_policy

google-cloud-recaptcha_enterprise-v1/proto_docs/google/cloud/recaptchaenterprise/v1/recaptchaenterprise.rb

@@ -472,8 +472,7 @@ class Assessment
         # @!attribute [rw] express
         #   @return [::Boolean]
         #     Optional. Flag for a reCAPTCHA express request for an assessment without a
-        #     token. If enabled, `site_key` must reference a SCORE key with WAF feature
-        #     set to EXPRESS.
+        #     token. If enabled, `site_key` must reference an Express site key.
         # @!attribute [rw] requested_uri
         #   @return [::String]
         #     Optional. The URI resource the user requested that triggered an assessment.
@@ -1197,11 +1196,11 @@ class ReorderFirewallPoliciesResponse
         #     Optional. If true, skips the billing check.
         #     A reCAPTCHA Enterprise key or migrated key behaves differently than a
         #     reCAPTCHA (non-Enterprise version) key when you reach a quota limit (see
-        #     https://cloud.google.com/recaptcha-enterprise/quotas#quota_limit). To avoid
+        #     https://cloud.google.com/recaptcha/quotas#quota_limit). To avoid
         #     any disruption of your usage, we check that a billing account is present.
         #     If your usage of reCAPTCHA is under the free quota, you can safely skip the
         #     billing check and proceed with the migration. See
-        #     https://cloud.google.com/recaptcha-enterprise/docs/billing-information.
+        #     https://cloud.google.com/recaptcha/docs/billing-information.
         class MigrateKeyRequest
           include ::Google::Protobuf::MessageExts
           extend ::Google::Protobuf::MessageExts::ClassMethods
@@ -1270,10 +1269,13 @@ class RetrieveLegacySecretKeyResponse
         # @!attribute [rw] ios_settings
         #   @return [::Google::Cloud::RecaptchaEnterprise::V1::IOSKeySettings]
         #     Settings for keys that can be used by iOS apps.
+        # @!attribute [rw] express_settings
+        #   @return [::Google::Cloud::RecaptchaEnterprise::V1::ExpressKeySettings]
+        #     Settings for keys that can be used by reCAPTCHA Express.
         # @!attribute [rw] labels
         #   @return [::Google::Protobuf::Map{::String => ::String}]
         #     Optional. See [Creating and managing labels]
-        #     (https://cloud.google.com/recaptcha-enterprise/docs/labels).
+        #     (https://cloud.google.com/recaptcha/docs/labels).
         # @!attribute [r] create_time
         #   @return [::Google::Protobuf::Timestamp]
         #     Output only. The timestamp corresponding to the creation of this key.
@@ -1429,6 +1431,12 @@ class IOSKeySettings
           extend ::Google::Protobuf::MessageExts::ClassMethods
         end
 
+        # Settings specific to keys that can be used for reCAPTCHA Express.
+        class ExpressKeySettings
+          include ::Google::Protobuf::MessageExts
+          extend ::Google::Protobuf::MessageExts::ClassMethods
+        end
+
         # Contains fields that are required to perform Apple-specific integrity checks.
         # @!attribute [rw] private_key
         #   @return [::String]
@@ -1777,6 +1785,25 @@ class SearchRelatedAccountGroupMembershipsResponse
           extend ::Google::Protobuf::MessageExts::ClassMethods
         end
 
+        # The AddIpOverride request message.
+        # @!attribute [rw] name
+        #   @return [::String]
+        #     Required. The name of the key to which the IP override is added, in the
+        #     format `projects/{project}/keys/{key}`.
+        # @!attribute [rw] ip_override_data
+        #   @return [::Google::Cloud::RecaptchaEnterprise::V1::IpOverrideData]
+        #     Required. IP override added to the key.
+        class AddIpOverrideRequest
+          include ::Google::Protobuf::MessageExts
+          extend ::Google::Protobuf::MessageExts::ClassMethods
+        end
+
+        # Response for AddIpOverride.
+        class AddIpOverrideResponse
+          include ::Google::Protobuf::MessageExts
+          extend ::Google::Protobuf::MessageExts::ClassMethods
+        end
+
         # A membership in a group of related accounts.
         # @!attribute [rw] name
         #   @return [::String]
@@ -1823,7 +1850,7 @@ class WafSettings
           extend ::Google::Protobuf::MessageExts::ClassMethods
 
           # Supported WAF features. For more information, see
-          # https://cloud.google.com/recaptcha-enterprise/docs/usecase#comparison_of_features.
+          # https://cloud.google.com/recaptcha/docs/usecase#comparison_of_features.
           module WafFeature
             # Undefined feature.
             WAF_FEATURE_UNSPECIFIED = 0
@@ -1858,6 +1885,34 @@ module WafService
             CLOUDFLARE = 4
           end
         end
+
+        # Information about the IP or IP range override.
+        # @!attribute [rw] ip
+        #   @return [::String]
+        #     Required. The IP address to override (can be IPv4, IPv6 or CIDR).
+        #     The IP override must be a valid IPv4 or IPv6 address, or a CIDR range.
+        #     The IP override must be a public IP address.
+        #     Example of IPv4: 168.192.5.6
+        #     Example of IPv6: 2001:0000:130F:0000:0000:09C0:876A:130B
+        #     Example of IPv4 with CIDR: 168.192.5.0/24
+        #     Example of IPv6 with CIDR: 2001:0DB8:1234::/48
+        # @!attribute [rw] override_type
+        #   @return [::Google::Cloud::RecaptchaEnterprise::V1::IpOverrideData::OverrideType]
+        #     Required. Describes the type of IP override.
+        class IpOverrideData
+          include ::Google::Protobuf::MessageExts
+          extend ::Google::Protobuf::MessageExts::ClassMethods
+
+          # Enum that represents the type of IP override.
+          module OverrideType
+            # Default override type that indicates this enum hasn't been specified.
+            OVERRIDE_TYPE_UNSPECIFIED = 0
+
+            # Allowlist the IP address; i.e. give a `risk_analysis.score` of 0.9 for
+            # all valid assessments.
+            ALLOW = 1
+          end
+        end
       end
     end
   end

google-cloud-recaptcha_enterprise-v1/snippets/recaptcha_enterprise_service/add_ip_override.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Copyright 2024 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.
+
+# Auto-generated by gapic-generator-ruby. DO NOT EDIT!
+
+# [START recaptchaenterprise_v1_generated_RecaptchaEnterpriseService_AddIpOverride_sync]
+require "google/cloud/recaptcha_enterprise/v1"
+
+##
+# Snippet for the add_ip_override call in the RecaptchaEnterpriseService service
+#
+# This snippet has been automatically generated and should be regarded as a code
+# template only. It will require modifications to work:
+# - It may require correct/in-range values for request initialization.
+# - It may require specifying regional endpoints when creating the service
+# client as shown in https://cloud.google.com/ruby/docs/reference.
+#
+# This is an auto-generated example demonstrating basic usage of
+# Google::Cloud::RecaptchaEnterprise::V1::RecaptchaEnterpriseService::Client#add_ip_override.
+#
+def add_ip_override
+  # Create a client object. The client can be reused for multiple calls.
+  client = Google::Cloud::RecaptchaEnterprise::V1::RecaptchaEnterpriseService::Client.new
+
+  # Create a request. To set request fields, pass in keyword arguments.
+  request = Google::Cloud::RecaptchaEnterprise::V1::AddIpOverrideRequest.new
+
+  # Call the add_ip_override method.
+  result = client.add_ip_override request
+
+  # The returned object is of type Google::Cloud::RecaptchaEnterprise::V1::AddIpOverrideResponse.
+  p result
+end
+# [END recaptchaenterprise_v1_generated_RecaptchaEnterpriseService_AddIpOverride_sync]

google-cloud-recaptcha_enterprise-v1/snippets/snippet_metadata_google.cloud.recaptchaenterprise.v1.json

@@ -371,6 +371,46 @@
         }
       ]
     },
+    {
+      "region_tag": "recaptchaenterprise_v1_generated_RecaptchaEnterpriseService_AddIpOverride_sync",
+      "title": "Snippet for the add_ip_override call in the RecaptchaEnterpriseService service",
+      "description": "This is an auto-generated example demonstrating basic usage of Google::Cloud::RecaptchaEnterprise::V1::RecaptchaEnterpriseService::Client#add_ip_override.",
+      "file": "recaptcha_enterprise_service/add_ip_override.rb",
+      "language": "RUBY",
+      "client_method": {
+        "short_name": "add_ip_override",
+        "full_name": "::Google::Cloud::RecaptchaEnterprise::V1::RecaptchaEnterpriseService::Client#add_ip_override",
+        "async": false,
+        "parameters": [
+          {
+            "type": "::Google::Cloud::RecaptchaEnterprise::V1::AddIpOverrideRequest",
+            "name": "request"
+          }
+        ],
+        "result_type": "::Google::Cloud::RecaptchaEnterprise::V1::AddIpOverrideResponse",
+        "client": {
+          "short_name": "RecaptchaEnterpriseService::Client",
+          "full_name": "::Google::Cloud::RecaptchaEnterprise::V1::RecaptchaEnterpriseService::Client"
+        },
+        "method": {
+          "short_name": "AddIpOverride",
+          "full_name": "google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseService.AddIpOverride",
+          "service": {
+            "short_name": "RecaptchaEnterpriseService",
+            "full_name": "google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseService"
+          }
+        }
+      },
+      "canonical": true,
+      "origin": "API_DEFINITION",
+      "segments": [
+        {
+          "start": 20,
+          "end": 46,
+          "type": "FULL"
+        }
+      ]
+    },
     {
       "region_tag": "recaptchaenterprise_v1_generated_RecaptchaEnterpriseService_GetMetrics_sync",
       "title": "Snippet for the get_metrics call in the RecaptchaEnterpriseService service",