OKR: Admin Area - User and IP Rate Limits- UI text

app/views/admin/application_settings/_ip_limits.html.haml

@@ -2,60 +2,55 @@
   = form_errors(@application_setting)
 
   %fieldset
-    %legend.h5.gl-border-none
-      = _('Unauthenticated API request rate limit')
+    = _("Rate limits can help reduce request volume (like from crawlers or abusive bots).")
+
+  %fieldset
     .form-group
       = f.gitlab_ui_checkbox_component :throttle_unauthenticated_api_enabled,
         _("Enable unauthenticated API request rate limit"),
-        help_text: _("Helps reduce request volume (e.g. from crawlers or abusive bots)"),
-        checkbox_options: { data: { qa_selector: 'throttle_unauthenticated_api_checkbox' } }
+        checkbox_options: { data: { qa_selector: 'throttle_unauthenticated_api_checkbox' } },
+        label_options: { class: 'label-bold' }
     .form-group
-      = f.label :throttle_unauthenticated_api_requests_per_period, _('Max unauthenticated API requests per period per IP'), class: 'label-bold'
+      = f.label :throttle_unauthenticated_api_requests_per_period, _('Maximum unauthenticated API requests per rate limit period per IP'), class: 'label-bold'
       = f.number_field :throttle_unauthenticated_api_requests_per_period, class: 'form-control gl-form-input'
     .form-group
       = f.label :throttle_unauthenticated_api_period_in_seconds, _('Unauthenticated API rate limit period in seconds'), class: 'label-bold'
       = f.number_field :throttle_unauthenticated_api_period_in_seconds, class: 'form-control gl-form-input'
 
   %fieldset
-    %legend.h5.gl-border-none
-      = _('Unauthenticated web request rate limit')
     .form-group
       = f.gitlab_ui_checkbox_component :throttle_unauthenticated_enabled,
         _("Enable unauthenticated web request rate limit"),
-        help_text: _("Helps reduce request volume (e.g. from crawlers or abusive bots)"),
-        checkbox_options: { data: { qa_selector: 'throttle_unauthenticated_web_checkbox' } }
+        checkbox_options: { data: { qa_selector: 'throttle_unauthenticated_web_checkbox' } },
+        label_options: { class: 'label-bold' }
     .form-group
-      = f.label :throttle_unauthenticated_requests_per_period, _('Max unauthenticated web requests per period per IP'), class: 'label-bold'
+      = f.label :throttle_unauthenticated_requests_per_period, _('Maximum unauthenticated web requests per rate limit period per IP'), class: 'label-bold'
       = f.number_field :throttle_unauthenticated_requests_per_period, class: 'form-control gl-form-input'
     .form-group
       = f.label :throttle_unauthenticated_period_in_seconds, _('Unauthenticated web rate limit period in seconds'), class: 'label-bold'
       = f.number_field :throttle_unauthenticated_period_in_seconds, class: 'form-control gl-form-input'
 
   %fieldset
-    %legend.h5.gl-border-none
-      = _('Authenticated API request rate limit')
     .form-group
       = f.gitlab_ui_checkbox_component :throttle_authenticated_api_enabled,
         _("Enable authenticated API request rate limit"),
-        help_text: _("Helps reduce request volume (e.g. from crawlers or abusive bots)"),
-        checkbox_options: { data: { qa_selector: 'throttle_authenticated_api_checkbox' }}
+        checkbox_options: { data: { qa_selector: 'throttle_authenticated_api_checkbox' }},
+        label_options: { class: 'label-bold' }
     .form-group
-      = f.label :throttle_authenticated_api_requests_per_period, _('Max authenticated API requests per period per user'), class: 'label-bold'
+      = f.label :throttle_authenticated_api_requests_per_period, _('Maximum authenticated API requests per rate limit period per user'), class: 'label-bold'
       = f.number_field :throttle_authenticated_api_requests_per_period, class: 'form-control gl-form-input'
     .form-group
       = f.label :throttle_authenticated_api_period_in_seconds, _('Authenticated API rate limit period in seconds'), class: 'label-bold'
       = f.number_field :throttle_authenticated_api_period_in_seconds, class: 'form-control gl-form-input'
 
   %fieldset
-    %legend.h5.gl-border-none
-      = _('Authenticated web request rate limit')
     .form-group
       = f.gitlab_ui_checkbox_component :throttle_authenticated_web_enabled,
         _("Enable authenticated web request rate limit"),
-        help_text: _("Helps reduce request volume (e.g. from crawlers or abusive bots)"),
-        checkbox_options: { data: { qa_selector: 'throttle_authenticated_web_checkbox' } }
+        checkbox_options: { data: { qa_selector: 'throttle_authenticated_web_checkbox' } },
+        label_options: { class: 'label-bold' }
     .form-group
-      = f.label :throttle_authenticated_web_requests_per_period, _('Max authenticated web requests per period per user'), class: 'label-bold'
+      = f.label :throttle_authenticated_web_requests_per_period, _('Maximum authenticated web requests per rate limit period per user'), class: 'label-bold'
       = f.number_field :throttle_authenticated_web_requests_per_period, class: 'form-control gl-form-input'
     .form-group
       = f.label :throttle_authenticated_web_period_in_seconds, _('Authenticated web rate limit period in seconds'), class: 'label-bold'
@@ -66,7 +61,9 @@
       = _('Response text')
     .form-group
       = f.label :rate_limiting_response_text, class: 'label-bold' do
-        = _('A plain-text response to show to clients that hit the rate limit.')
+        = _('Plain-text response to send to clients that hit a rate limit')
       = f.text_area :rate_limiting_response_text, placeholder: ::Gitlab::Throttle::DEFAULT_RATE_LIMITING_RESPONSE_TEXT, class: 'form-control gl-form-input', rows: 5
+      .form-text.text-muted
+        = html_escape(_("If blank, defaults to %{code_open}Retry later%{code_close}.")) % { code_open: '<code>'.html_safe, code_close: '</code>'.html_safe }
 
   = f.submit _('Save changes'), class: "gl-button btn btn-confirm", data: { qa_selector: 'save_changes_button' }

app/views/admin/application_settings/network.html.haml

@@ -16,11 +16,12 @@
 %section.settings.as-ip-limits.no-animate#js-ip-limits-settings{ class: ('expanded' if expanded_by_default?), data: { qa_selector: 'ip_limits_content' } }
   .settings-header
     %h4
-      = _('User and IP Rate Limits')
+      = _('User and IP rate limits')
     %button.btn.gl-button.btn-default.js-settings-toggle{ type: 'button' }
       = expanded_by_default? ? _('Collapse') : _('Expand')
     %p
-      = _('Configure limits for web and API requests.')
+      = _('Set limits for web and API requests.')
+      = link_to _('Learn more.'), help_page_path('user/admin_area/settings/user_and_ip_rate_limits.md'), target: '_blank', rel: 'noopener noreferrer'
   .settings-content
     = render 'ip_limits'
 

doc/user/admin_area/settings/user_and_ip_rate_limits.md

@@ -13,31 +13,78 @@ of a web application. For more details, see
 
 The following limits are disabled by default:
 
-- Unauthenticated API requests
-- Unauthenticated web requests
-- Authenticated API requests
-- Authenticated web requests
+- [Unauthenticated API requests (per IP)](#enable-unauthenticated-api-request-rate-limit).
+- [Unauthenticated web requests (per IP)](#enable-unauthenticated-web-request-rate-limit).
+- [Authenticated API requests (per user)](#enable-authenticated-api-request-rate-limit).
+- [Authenticated web requests (per user)](#enable-authenticated-web-request-rate-limit).
 
-To enforce any or all of them:
+NOTE:
+By default, all Git operations are first tried unauthenticated. Because of this, HTTP Git operations
+may trigger the rate limits configured for unauthenticated requests.
+
+## Enable unauthenticated API request rate limit
+
+To enable the unauthenticated request rate limit:
+
+1. On the top bar, select **Menu > Admin**.
+1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**.
+1. Select **Enable unauthenticated API request rate limit**.
+
+   - Optional. Update the **Maximum unauthenticated API requests per rate limit period per IP** value.
+     Defaults to `3600`.
+   - Optional. Update the **Unauthenticated rate limit period in seconds** value.
+     Defaults to `3600`.
+
+## Enable unauthenticated web request rate limit
+
+To enable the unauthenticated request rate limit:
+
+1. On the top bar, select **Menu > Admin**.
+1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**.
+1. Select **Enable unauthenticated web request rate limit**.
+
+   - Optional. Update the **Maximum unauthenticated web requests per rate limit period per IP** value.
+     Defaults to `3600`.
+   - Optional. Update the **Unauthenticated rate limit period in seconds** value.
+     Defaults to `3600`.
+
+## Enable authenticated API request rate limit
+
+To enable the authenticated API request rate limit:
 
 1. On the top bar, select **Menu > Admin**.
-1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**:
-   ![user-and-ip-rate-limits](img/user_and_ip_rate_limits_v14_3.png)
+1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**.
+1. Select **Enable authenticated API request rate limit**.
 
-   NOTE:
-   By default, all Git operations are first tried unauthenticated. Because of this, HTTP Git operations
-   may trigger the rate limits configured for unauthenticated requests.
+   - Optional. Update the **Maximum authenticated API requests per rate limit period per user** value.
+     Defaults to `7200`.
+   - Optional. Update the **Authenticated API rate limit period in seconds** value.
+     Defaults to `3600`.
 
-## Response text
+## Enable authenticated web request rate limit
+
+To enable the unauthenticated request rate limit:
+
+1. On the top bar, select **Menu > Admin**.
+1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**.
+1. Select **Enable authenticated web request rate limit**.
+
+   - Optional. Update the **Maximum authenticated web requests per rate limit period per user** value.
+     Defaults to `7200`.
+   - Optional. Update the **Authenticated web rate limit period in seconds** value.
+     Defaults to `3600`.
+
+## Use a custom rate limit response
 
 A request that exceeds a rate limit returns a 429 response code and a
-plain-text body, which by default is:
+plain-text body, which by default is `Retry later`.
 
-```plaintext
-Retry later
-```
+To use a custom response:
 
-It is possible to customize this response text in the Admin Area.
+1. On the top bar, select **Menu > Admin**.
+1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**.
+1. In the **Plain-text response to send to clients that hit a rate limit** text box,
+   add the plain-text response message.
 
 ## Response headers
 

doc/user/gitlab_com/index.md

@@ -305,7 +305,7 @@ endpoints](../../user/admin_area/settings/rate_limits_on_raw_endpoints.md).
 For information on rate limiting responses, see:
 
 - [List of headers on responses to blocked requests](../admin_area/settings/user_and_ip_rate_limits.md#response-headers).
-- [Customizable response text](../admin_area/settings/user_and_ip_rate_limits.md#response-text).
+- [Customizable response text](../admin_area/settings/user_and_ip_rate_limits.md#use-a-custom-rate-limit-response).
 
 ### Protected paths throttle
 

locale/gitlab.pot

@@ -1495,9 +1495,6 @@ msgstr ""
 msgid "A plain HTML site that uses Netlify for CI/CD instead of GitLab, but still with all the other great GitLab features"
 msgstr ""
 
-msgid "A plain-text response to show to clients that hit the rate limit."
-msgstr ""
-
 msgid "A platform value can be web, mob or app."
 msgstr ""
 
@@ -4783,9 +4780,6 @@ msgstr ""
 msgid "Authenticated web rate limit period in seconds"
 msgstr ""
 
-msgid "Authenticated web request rate limit"
-msgstr ""
-
 msgid "Authenticated web requests"
 msgstr ""
 
@@ -8559,9 +8553,6 @@ msgstr ""
 msgid "Configure existing installation"
 msgstr ""
 
-msgid "Configure limits for web and API requests."
-msgstr ""
-
 msgid "Configure paths to be protected by Rack Attack."
 msgstr ""
 
@@ -16931,6 +16922,9 @@ msgstr ""
 msgid "If any indexed field exceeds this limit it will be truncated to this number of characters and the rest will not be indexed or searchable. This does not apply to repository and wiki indexing. Setting this to 0 means it is unlimited."
 msgstr ""
 
+msgid "If blank, defaults to %{code_open}Retry later%{code_close}."
+msgstr ""
+
 msgid "If blank, set allowable lifetime to %{instance_level_policy_in_words}, as defined by the instance admin. Once set, existing tokens for users in this group may be revoked."
 msgstr ""
 
@@ -20756,15 +20750,9 @@ msgstr ""
 msgid "Max 20 characters"
 msgstr ""
 
-msgid "Max authenticated API requests per period per user"
-msgstr ""
-
 msgid "Max authenticated Git LFS requests per period per user"
 msgstr ""
 
-msgid "Max authenticated web requests per period per user"
-msgstr ""
-
 msgid "Max file size is 200 KB."
 msgstr ""
 
@@ -20774,12 +20762,6 @@ msgstr ""
 msgid "Max session time"
 msgstr ""
 
-msgid "Max unauthenticated API requests per period per IP"
-msgstr ""
-
-msgid "Max unauthenticated web requests per period per IP"
-msgstr ""
-
 msgid "MaxBuilds"
 msgstr ""
 
@@ -20819,6 +20801,9 @@ msgstr ""
 msgid "Maximum authenticated API requests per rate limit period per user"
 msgstr ""
 
+msgid "Maximum authenticated web requests per rate limit period per user"
+msgstr ""
+
 msgid "Maximum bulk request size (MiB)"
 msgstr ""
 
@@ -20972,6 +20957,9 @@ msgstr ""
 msgid "Maximum unauthenticated API requests per rate limit period per IP"
 msgstr ""
 
+msgid "Maximum unauthenticated web requests per rate limit period per IP"
+msgstr ""
+
 msgid "May"
 msgstr ""
 
@@ -25162,6 +25150,9 @@ msgstr ""
 msgid "Plain diff"
 msgstr ""
 
+msgid "Plain-text response to send to clients that hit a rate limit"
+msgstr ""
+
 msgid "Plan:"
 msgstr ""
 
@@ -27679,6 +27670,9 @@ msgstr ""
 msgid "Rate limit"
 msgstr ""
 
+msgid "Rate limits can help reduce request volume (like from crawlers or abusive bots)."
+msgstr ""
+
 msgid "Raw blob request rate limit per minute"
 msgstr ""
 
@@ -30781,6 +30775,9 @@ msgstr ""
 msgid "Set limit to 0 to allow any file size."
 msgstr ""
 
+msgid "Set limits for web and API requests."
+msgstr ""
+
 msgid "Set max session time for web terminal."
 msgstr ""
 
@@ -36011,9 +36008,6 @@ msgstr ""
 msgid "Unauthenticated web rate limit period in seconds"
 msgstr ""
 
-msgid "Unauthenticated web request rate limit"
-msgstr ""
-
 msgid "Undo"
 msgstr ""
 
@@ -36713,7 +36707,7 @@ msgstr ""
 msgid "User Settings"
 msgstr ""
 
-msgid "User and IP Rate Limits"
+msgid "User and IP rate limits"
 msgstr ""
 
 msgid "User does not have a pending request"

spec/features/admin/admin_settings_spec.rb

@@ -551,22 +551,22 @@ RSpec.describe 'Admin updates settings' do
 
         page.within('.as-ip-limits') do
           check 'Enable unauthenticated API request rate limit'
-          fill_in 'Max unauthenticated API requests per period per IP', with: 100
+          fill_in 'Maximum unauthenticated API requests per rate limit period per IP', with: 100
           fill_in 'Unauthenticated API rate limit period in seconds', with: 200
 
           check 'Enable unauthenticated web request rate limit'
-          fill_in 'Max unauthenticated web requests per period per IP', with: 300
+          fill_in 'Maximum unauthenticated web requests per rate limit period per IP', with: 300
           fill_in 'Unauthenticated web rate limit period in seconds', with: 400
 
           check 'Enable authenticated API request rate limit'
-          fill_in 'Max authenticated API requests per period per user', with: 500
+          fill_in 'Maximum authenticated API requests per rate limit period per user', with: 500
           fill_in 'Authenticated API rate limit period in seconds', with: 600
 
           check 'Enable authenticated web request rate limit'
-          fill_in 'Max authenticated web requests per period per user', with: 700
+          fill_in 'Maximum authenticated web requests per rate limit period per user', with: 700
           fill_in 'Authenticated web rate limit period in seconds', with: 800
 
-          fill_in 'A plain-text response to show to clients that hit the rate limit.', with: 'Custom message'
+          fill_in 'Plain-text response to send to clients that hit a rate limit', with: 'Custom message'
 
           click_button 'Save changes'
         end