InfoGrab DocsInfoGrab Docs

애플리케이션 제한 개발

요약

이 문서는 GitLab에 애플리케이션 제한을 추가하려는 기여자를 위한 개발 가이드입니다. 먼저 GitLab 티어별로 어떤 제한이 설정되는지 정보를 모으고 결정해야 합니다. 제한 유형에 맞는 페이지에 문서를 추가합니다. 애플리케이션 제한 도입에 관한 가이드도 있습니다.

이 문서는 GitLab에 애플리케이션 제한을 추가하려는 기여자를 위한 개발 가이드입니다.

문서화#

먼저 GitLab 티어별로 어떤 제한이 설정되는지 정보를 모으고 결정해야 합니다. 다른 구성원과 협의해 그 제한을 문서화하고 공유합니다.

제한 유형에 맞는 페이지에 문서를 추가합니다.

애플리케이션 제한 도입에 관한 가이드도 있습니다.

플랜 제한 구현#

plan_limits 테이블은 셀 범위 구성입니다. 각 셀은 이 테이블의 사본을 따로 가지며 제한은 셀 간에 이전되지 않습니다. 새 셀은 각 제한의 칼럼 기본값으로 시작하고, 관리자는 관리자 Plan Limits API로 셀별 제한을 조정합니다. 따라서 모든 새 플랜 제한은 그 API로 설정할 수 있어야 합니다. 그렇지 않으면 새 제한은 각 셀에서 칼럼 기본값만 갖게 됩니다.

셀 간에 값이 일관되게 유지되어야 하는 플랜 제한은 도입하지 않습니다. plan_limits는 셀 로컬이므로 동기화를 유지할 방법이 없습니다.

데이터베이스 플랜 제한 삽입#

plan_limits 테이블에 새 칼럼을 만들고 제한 값을 삽입합니다. 마이그레이션 스크립트 파일은 두 개로 나누어 만들기를 권장합니다.

  1. plan_limits 테이블에 원하는 제한을 나타내는 null 이 아닌 기본값을 가진 새 칼럼을 추가합니다. 예를 들면 다음과 같습니다.

    add_column(:plan_limits, :project_hooks, :integer, default: 100, null: false)
    

    플랜 제한 항목이 0 이면 제한이 활성화되지 않았다는 뜻입니다. 이 설정은 특별하고 문서화된 상황에서만 사용합니다.

  2. (선택 사항) create_or_update_plan_limit 마이그레이션 헬퍼를 사용해 각 수준을 원하는 제한으로 조정하는 데이터베이스 마이그레이션을 만듭니다. 이 마이그레이션의 플랜은 GitLab.com의 플랜과 일치해야 합니다. 플랜이 누락되면 해당 플랜 고객은 기본 제한을 적용받게 되며, 그 값은 0(무제한)일 수 있습니다.

    예를 들면 다음과 같습니다.

    class InsertProjectHooksPlanLimits < Gitlab::Database::Migration[2.1]
      def up
        create_or_update_plan_limit('project_hooks', 'default', 0)
        create_or_update_plan_limit('project_hooks', 'free', 10)
        create_or_update_plan_limit('project_hooks', 'premium', 30)
        create_or_update_plan_limit('project_hooks', 'premium_trial', 30)
        create_or_update_plan_limit('project_hooks', 'ultimate', 100)
        create_or_update_plan_limit('project_hooks', 'ultimate_trial', 100)
        create_or_update_plan_limit('project_hooks', 'ultimate_trial_paid_customer', 100)
        create_or_update_plan_limit('project_hooks', 'opensource', 100)
      end
    
      def down
        create_or_update_plan_limit('project_hooks', 'default', 0)
        create_or_update_plan_limit('project_hooks', 'free', 0)
        create_or_update_plan_limit('project_hooks', 'premium', 0)
        create_or_update_plan_limit('project_hooks', 'premium_trial', 0)
        create_or_update_plan_limit('project_hooks', 'ultimate', 0)
        create_or_update_plan_limit('project_hooks', 'ultimate_trial', 0)
        create_or_update_plan_limit('project_hooks', 'ultimate_trial_paid_customer', 0)
        create_or_update_plan_limit('project_hooks', 'opensource', 0)
      end
    end
    

    일부 플랜은 GitLab.com 에만 존재합니다. 존재하지 않는 플랜에 대해서는 아무 동작도 하지 않습니다.

    마이그레이션에서 GitLab.com 에만 제한을 설정하고 다른 인스턴스는 기본 제한을 사용하게 하려면 #up과 #down 메서드 시작 부분에 return unless Gitlab.com?을 추가해 다른 인스턴스에서는 마이그레이션이 아무 동작도 하지 않도록 합니다.

  3. 관리자 Plan Limits API를 통해 새 칼럼을 노출합니다.

플랜 제한 유효성 검사#

현재 제한 가져오기#

현재 제한은 프로젝트나 네임스페이스를 통해 확인할 수 있습니다. 예를 들면 다음과 같습니다.

project.actual_limits.project_hooks

현재 제한 확인#

현재 제한을 초과했는지 확인하는 메서드로 PlanLimits#exceeded?가 있습니다. ActiveRecord 객체나 Integer 중 하나를 사용할 수 있습니다.

레코드 수가 정의된 제한을 초과하지 않는지 확인합니다. 예를 들면 다음과 같습니다.

project.actual_limits.exceeded?(:project_hooks, ProjectHook.where(project: project))

숫자가 정의된 제한을 초과하지 않는지 확인합니다. 예를 들면 다음과 같습니다.

project.actual_limits.exceeded?(:project_hooks, 10)

Limitable concern#

Limitable concern 을 사용하면 모델이 제한을 초과하지 않는지 검증할 수 있습니다. 현재 모델의 레코드 수가 정의된 제한을 초과하지 않도록 보장합니다.

검증 대상 객체의 제한 범위를 지정해야 하며, 제한 이름이 모델 이름의 복수형과 다르면 제한 이름도 지정해야 합니다.

class ProjectHook
  include Limitable

  self.limit_name = 'project_hooks' # Optional as ProjectHook corresponds with project_hooks
  self.limit_scope = :project
end

모델을 테스트하려면 공유 예제를 포함할 수 있습니다.

it_behaves_like 'includes Limitable concern' do
  subject { build(:project_hook, project: create(:project)) }
end

인스턴스 전역 제한 테스트#

인스턴스 전역 기능에는 라이선스가 할당되지 않으므로 항상 default 플랜을 사용합니다.

class InstanceVariable
  include Limitable

  self.limit_name = 'instance_variables' # Optional as InstanceVariable corresponds with instance_variables
  self.limit_scope = Limitable::GLOBAL_SCOPE
end

구독 플랜#

GitLab Self-Managed:

  • default: 모든 사용자.

GitLab.com:

  • default: 시스템 전역 기능 전체.
  • free: Free 구독을 사용하는 네임스페이스와 프로젝트.
  • premium: Premium 구독을 사용하는 네임스페이스와 프로젝트.
  • premium_trial: Premium Trial 구독을 사용하는 네임스페이스와 프로젝트.
  • ultimate: Ultimate 구독을 사용하는 네임스페이스와 프로젝트.
  • ultimate_trial: Ultimate Trial 구독을 사용하는 네임스페이스와 프로젝트.
  • ultimate_trial_paid_customer: Premium 구독 상태에서 Ultimate를 30일간 체험 중인 네임스페이스와 프로젝트.
  • opensource: GitLab Open Source 프로그램에 참여 중인 네임스페이스와 프로젝트.

GitLab.com에는 구독이 없는 early_adopter 플랜이 있습니다.

test 환경에는 플랜이 없습니다.

속도 제한 추가#

GitLab에는 애플리케이션 코드용 속도 제한기가 두 가지 있습니다. 둘 다 LabKit 속도 제한 SDK를 사용하며, 카운터를 속도 제한용 Redis 인스턴스에 저장합니다.

속도 제한을 추가하는 절차는 다음과 같습니다.

  1. 속도 제한기를 선택합니다.
  2. 속도 제한을 구성 가능하게 만듭니다. 새 속도 제한에는 모두 애플리케이션 설정이 필요합니다.
  3. 제한을 LabKit 요청 속도 제한 또는 Gitlab::ApplicationRateLimiter 키로 등록합니다.
  4. Gitlab::ApplicationRateLimiter 키라면 동작을 수행하는 코드에서 속도 제한을 확인합니다.
  5. 기능 플래그 뒤에서 속도 제한을 롤아웃합니다.
  6. 속도 제한을 문서화합니다.

속도 제한기 선택#

다음에 해당하면 LabKit으로 요청 속도 제한을 추가합니다.

  • 제한이 각 요청이 수행하는 동작과 관계없이 요청량으로부터 라우트 그룹을 보호합니다. 예를 들어 패키지 API, 파일 API, HTTP를 통한 Git이 있습니다.
  • 제한이 IP 주소 또는 인증된 요청자를 기준으로 집계합니다.
  • 컨트롤러나 Grape 엔드포인트에 도달하기 전에 요청을 차단해야 합니다.

다음에 해당하면 Gitlab::ApplicationRateLimiter 키를 추가합니다.

  • 제한이 이슈 생성이나 이메일 전송처럼 하나의 동작에 적용됩니다.
  • 제한이 프로젝트, 그룹, 네임스페이스 같은 리소스 또는 값의 조합을 기준으로 집계합니다.
  • 제한이 서로 다른 리소스를 집계하거나, Sidekiq 워커처럼 웹 요청 밖에서 작업이 실행됩니다.

두 속도 제한기 중 어느 쪽이든 쓸 수 있다면 Gitlab::ApplicationRateLimiter를 사용합니다. 이 제한은 그것을 호출하는 동작에만 적용됩니다.

속도 제한을 구성 가능하게 만들기#

속도 제한에는 관리자가 코드 변경 없이 제한을 높이거나 낮추거나 비활성화할 수 있도록 애플리케이션 설정이 필요합니다. 제한을 구성할 수 없게 해야 한다면 머지 리퀘스트에 그 이유를 적고 해당 제한을 구성할 수 없는 속도 제한으로 문서화합니다.

새 속도 제한 설정은 ApplicationSetting의 rate_limits JSONB 칼럼에 있는 필드입니다. 이전 스로틀 설정은 테이블 칼럼입니다. 설정을 추가하는 절차는 다음과 같습니다.

  1. app/models/application_setting.rb의 ApplicationSetting.rate_limits_definition에 필드와 기본값을 추가합니다. EE 전용 제한이라면 ee/app/models/ee/application_setting.rb의 EE 재정의에 추가합니다.

    • Gitlab::ApplicationRateLimiter 키에는 정수 필드가 하나 있습니다.

      discussions_resolve_limit: [:integer, { default: 120 }],
      
    • LabKit 요청 스로틀에는 불리언 필드 하나와 정수 필드 둘이 있습니다.

      throttle_authenticated_mcp_enabled: [:boolean, { default: false }],
      throttle_authenticated_mcp_requests_per_period: [:integer, { default: 600 }],
      throttle_authenticated_mcp_period_in_seconds: [:integer, { default: 60 }],
      
  2. 같은 모델에서 정수 필드를 검증합니다. 이 모델에는 with_options(numericality: ...) 블록이 둘 있습니다.

    • Gitlab::ApplicationRateLimiter 제한은 0이 키를 비활성화하므로 greater_than_or_equal_to: 0 블록에 추가합니다.
    • LabKit의 requests_per_period와 period_in_seconds 필드는 greater_than: 0 블록에 추가합니다.
  3. app/validators/json_schemas/application_setting_rate_limits.json의 JSON 스키마에 필드를 추가합니다.

    • Gitlab::ApplicationRateLimiter 제한은 "minimum": 0인 integer입니다.
    • LabKit의 requests_per_period와 period_in_seconds 필드는 "minimum": 1인 integer이고, enabled 필드는 boolean입니다.
  4. app/helpers/application_settings_helper.rb의 ApplicationSettingsHelper#visible_attributes에 설정을 추가합니다. EE 전용 제한이라면 ee/app/helpers/ee/application_settings_helper.rb의 EE 재정의에 추가합니다. 이 목록은 애플리케이션 설정 API에서 설정을 읽고 쓸 수 있도록 노출하고, Admin 영역 컨트롤러에서 허용합니다. 전체 절차는 애플리케이션 설정을 참고합니다.

  5. lib/api/settings.rb에 type:과 desc:가 있는 optional 매개변수를 추가합니다. EE 전용 제한이라면 ee/lib/ee/api/helpers/settings_helpers.rb에 추가합니다. 그러면 API가 값을 검증하고 OpenAPI 문서가 이를 설명합니다. 애플리케이션 설정 API에 속성을 문서화합니다.

  6. 선택 사항입니다. app/views/admin/application_settings/의 해당 부분 템플릿에 양식 필드를 추가합니다.

  7. 제한에서 설정을 읽습니다.

    • Gitlab::ApplicationRateLimiter 키에서는 limit을 설정을 읽는 람다로 지정합니다.

      limit: -> { Gitlab::CurrentSettings.current_application_settings.discussions_resolve_limit },
      
    • LabKit 요청 스로틀에서는 스로틀 정의에서 Gitlab::Throttle.settings를 통해 설정을 읽습니다.

LabKit으로 요청 속도 제한 구현#

Gitlab::Middleware::LabkitRackRateLimit 미들웨어는 Rails 컨트롤러, Grape 엔드포인트, 그 밖의 모든 Rack 요청에 속도 제한을 적용합니다. 이 미들웨어는 Warden이 요청을 인증한 뒤, 요청이 애플리케이션에 도달하기 전에 실행됩니다. 제한을 넘은 요청은 429 Too Many Requests 응답을 받습니다.

이 속도 제한은 LabKit이 적용합니다. Rack::Attack은 여전히 미들웨어 스택에 있지만 요청을 스로틀링하지 않습니다. LabKit은 Gitlab::RackAttack의 스로틀 정의에서 각 제한과 기간을 읽으므로, 새 스로틀도 여전히 그곳에서 시작합니다.

요청 속도 제한을 추가하는 절차는 다음과 같습니다.

  1. 속도 제한을 구성 가능하게 만듭니다.
  2. 제한과 기간을 담는 스로틀 정의를 추가합니다.
    • 단일 스로틀은 Gitlab::RackAttack.throttle_definitions에 추가하고, Gitlab::RackAttack::Request에 대응하는 조건자를 추가합니다.
    • 인증된 요청과 인증되지 않은 요청 쌍은 Gitlab::Throttle::REGULAR_THROTTLES에 항목 하나를 추가합니다. Gitlab::RackAttack.regular_throttle_definitions가 이 항목에서 throttle_unauthenticated_<name>과 throttle_authenticated_<name>을 생성합니다.
  3. ThrottleRegistry에 스로틀을 등록합니다. 자세한 내용은 스로틀 등록을 참고합니다.
  4. app/views/admin/application_settings/_ip_limits.html.haml의 Admin 영역 양식에 새 설정을 추가합니다.
  5. 선택 사항입니다. 스로틀이 요청을 차단하기 전에 관찰하려면 GITLAB_THROTTLE_DRY_RUN 환경 변수에 스로틀 이름을 지정합니다. 드라이 런 모드의 스로틀은 :limit 규칙 대신 :log 규칙으로 빌드되며, 클레임 이름은 <rule_name>_claim 대신 <rule_name>_dry_run_bypass가 됩니다.
  6. User and IP rate limits에 새 설정을 문서화합니다.
  7. GitLab.com의 속도 제한을 구성하고 GitLab.com의 속도 제한에 문서화합니다.

스로틀 등록#

각 스로틀은 Gitlab::RackAttack::LabkitRateLimit::ThrottleRegistry의 LabKit 규칙 하나에 대응합니다. 이 레지스트리는 lib/gitlab/rack_attack/labkit_rate_limit/throttle_registry.rb에 정의되어 있으며, EE 스로틀은 ee/lib/ee/gitlab/rack_attack/labkit_rate_limit/throttle_registry.rb에 정의되어 있습니다. Gitlab::RackAttack.all_throttle_definitions에 있는 스로틀에 레지스트리 항목이 없으면 스펙이 실패합니다.

각 항목은 다음을 선언합니다.

  • limiter: 규칙을 소유하는 제한기입니다. 일반 제한기의 규칙도 집계하는 요청을 스로틀이 집계해야 하는 경우가 아니라면 ThrottleRegistry::GENERAL을 사용합니다. 하나의 제한기에서는 요청을 처음 클레임한 규칙이 그 요청을 집계하므로, 다른 규칙과 같은 요청을 집계하는 스로틀에는 자체 제한기가 필요합니다. 보호된 경로와 EE 인시던트 관리 스로틀은 이 이유로 자체 제한기를 가집니다.
  • characteristics: 규칙이 집계하는 기준입니다. 예를 들어 인증되지 않은 스로틀은 [:ip], 인증된 스로틀은 [:requester_type, :requester_id]입니다.
  • match: 규칙이 적용되려면 요청이 가져야 하는 팩트입니다.
  • cohort: 규칙의 적용 여부를 기능 플래그로 제어하는 롤아웃 코호트입니다. 기존 코호트를 사용합니다. 새 코호트에는 자체 기능 플래그 정의가 필요하며, 새 코호트의 두 플래그가 모두 활성화될 때까지 Rack::Attack이 요청을 다시 스로틀링합니다.
  • claims: 규칙이 요청을 집계한 뒤 평가를 중단할지 여부입니다. 모든 항목이 이를 선언해야 합니다.

LabKit은 건너뛰기 규칙(예: 우회 헤더와 사용자 허용 목록)을 먼저 평가하고, 그다음 GitLab.com 플랜 규칙, 그다음 레지스트리 규칙을 평가합니다. 레지스트리 규칙은 레지스트리 순서대로 평가됩니다. 특화된 API, Git, 웹, 일반 API 순입니다. claims: true인 스로틀은 요청을 집계하고 평가를 중단하므로, 목록 뒤쪽의 더 일반적인 규칙은 같은 요청을 집계하지 않습니다.

클레임에는 스로틀의 setting_* 팩트가 포함되므로, 순서에 따른 제외는 클레임하는 스로틀이 활성화되어 있는 동안에만 요청을 제외합니다. 항상 적용되어야 하는 제외에는 웹 및 API 규칙이 path: { nre: <regex> }, git_http_non_lfs: false, frontend: false로 하듯이 match에 부정 팩트를 추가합니다.

match에서는 다음을 따릅니다.

  • nil일 수 있는 각 특성의 존재 여부를 규칙의 조건으로 둡니다. 인증된 규칙은 requester_id: /./를 조건으로 하고, [:aid]로 집계하는 규칙은 aid: /./를 조건으로 합니다. 이 조건이 없으면 값이 없는 요청이 하나의 카운터를 공유합니다.
  • 인증되지 않은 규칙은 requester_id: nil, runner_id: nil을 조건으로 합니다.
  • 스로틀의 setting_* 팩트를 포함해, Admin 영역에서 스로틀을 비활성화하면 규칙이 더 이상 일치하지 않도록 합니다.
  • path: 정규식은 마지막에 둡니다. 조건은 순서대로 검사하고 처음 실패한 조건에서 평가를 중단하므로, 비용이 낮은 조건을 먼저 두면 정규식 실행을 피할 수 있습니다.

규칙은 Gitlab::RackAttack::LabkitRateLimit::ClassifiedRequest#labkit_facts가 반환하는 팩트에서 일치 여부를 판단하며, 이 팩트는 ID 팩트와 분류 팩트를 병합한 것입니다. 스로틀의 setting_* 팩트를 ClassifiedRequest#classification_facts에 추가하고, EE 스로틀이라면 EE 모듈에 추가합니다. 경로 정규식으로 표현할 수 없는 조건에만 분류 팩트를 추가합니다.

등급별 요청 속도 제한#

GitLab.com에서 Gitlab::RateLimit::PlanRules는 요청자의 구독 플랜에 따라 달라지는 요청 속도 제한을 추가합니다. 이 규칙은 ee/lib/ee/gitlab/rate_limit/plan_rules.rb에 정의되어 있으며 GitLab.com에만 적용됩니다.

  • 각 제한에는 규칙이 둘 있습니다. 요청을 집계하는 :log 규칙과 요청을 차단하는 :limit 규칙입니다. 접미사가 _info와 _enforce인 기능 플래그가 어느 규칙이 일치할지 결정합니다.
  • 인증된 사용자는 직접 또는 공유 그룹을 통해 멤버로 속한 최상위 그룹 중 가장 높은 플랜을 적용받습니다. 유료 그룹이 없는 사용자는 Free 제한을 적용받습니다.

Gitlab::ApplicationRateLimiter를 사용한 속도 제한 구현#

Gitlab::ApplicationRateLimiter는 단일 동작을 제한합니다. 컨트롤러, API 엔드포인트, 서비스, 워커처럼 동작을 수행하는 코드에서 호출합니다. 각 속도 제한 키는 LabKit 규칙입니다.

속도 제한 키 추가#

  1. Gitlab::ApplicationRateLimiter::LabkitAdapter::SupportedRateLimits에 키에 대한 Labkit::RateLimit::Rule을 추가합니다. CE 키는 lib/gitlab/application_rate_limiter/labkit_adapter/supported_rate_limits.rb에 있고, EE 전용 키와 EE 재정의는 ee/lib/ee/gitlab/application_rate_limiter/labkit_adapter/supported_rate_limits.rb에 있습니다. 규칙이 없는 키는 Gitlab::ApplicationRateLimiter::InvalidKeyError를 발생시킵니다.

    issues_create: ::Labkit::RateLimit::Rule.new(
      name: 'limit_issues_by_project_user_external_author',
      characteristics: %i[project user external_author],
      limit: -> { Gitlab::CurrentSettings.current_application_settings.issues_create_limit },
      period: 1.minute,
      action: :limit
    ),
    
  2. 규칙 속성을 설정합니다. 각 속성의 역할은 LabKit 문서의 Rule을 참고합니다. GitLab에서는 다음을 따릅니다.

    • name은 limit_로 시작해야 합니다. 접두사가 없는 이름은 스펙이 실패합니다.
    • action은 :limit이어야 합니다. 새 키를 로그 모드로 먼저 롤아웃하려면 대신 staged_rule로 정의합니다. staged_rule은 action을 직접 설정합니다. 로그 모드로 키 롤아웃을 참고합니다.
    • limit은 제한에 대한 애플리케이션 설정을 읽는 람다입니다.
    • characteristics는 특성 이름에 있는 이름을 사용합니다.
    • count_distinct는 선택 사항입니다. 호출 횟수를 집계하는 대신 resource:로 전달된 서로 다른 리소스를 집계하려면 :project_id로 설정합니다. 예시는 ee/lib/ee/gitlab/application_rate_limiter/labkit_adapter/supported_rate_limits.rb의 EE unique_project_downloads_for_application 키를 참고합니다.
  3. 동작을 수행하는 코드에서 키를 확인합니다.

모든 키가 제한과 기간을 정의해야 한다는 것이 스펙의 요구 사항입니다. 제한을 호출자로부터 받거나 호출 횟수 대신 비용을 집계하는 키는 spec/lib/gitlab/application_rate_limiter/labkit_adapter/supported_rate_limits_spec.rb에 예외로 나열되어 있습니다.

속도 제한 확인#

동작을 수행하는 코드에서 속도 제한을 확인합니다. 코드 경로마다 진입점이 하나씩 있습니다.

코드 경로 진입점
Rails 컨트롤러 ApplicationController가 포함하는 CheckRateLimit concern의 check_rate_limit!입니다.
Grape API 엔드포인트 API::API가 포함하는 API::Helpers::RateLimiter의 check_rate_limit!입니다.
서비스 RateLimitedService concern의 rate_limit입니다.
GraphQL 뮤테이션 Gitlab::ApplicationRateLimiter.throttled?를 호출한 뒤 RateLimitedService::RateLimitedError를 발생시킵니다.
Sidekiq 워커, 모델, 라이브러리 코드 Gitlab::ApplicationRateLimiter.throttled?입니다.

모든 진입점은 키와, 키가 SupportedRateLimits에 등록한 특성(characteristic) 이름을 키로 하는 scope: 해시를 받습니다.

Gitlab::ApplicationRateLimiter.throttled?(:issues_create, scope: { project: project, user: current_user })

ActiveRecord 값은 기본 키를, 기본 자료형은 문자열 형태를 사용합니다. 생략했거나 nil인 특성은 labkit의 _unknown_ 센티널을 키로 사용하며, 규칙의 특성이 아닌 스코프 키는 개발 및 테스트 환경에서 오류를 발생시킵니다.

Rails 컨트롤러#

check_rate_limit!는 Gitlab::ApplicationRateLimiter.throttled_request?를 호출하며, 이 메서드는 속도 제한 우회 헤더를 존중하고 제한된 요청을 메시지 Application_Rate_Limiter_Request와 함께 auth.log에 기록합니다. 동작이 제한을 넘으면 이 메서드는 429 Too Many Requests로 오류 메시지를 렌더링합니다. 대신 메시지를 알림으로 표시하며 이전 페이지로 리디렉션하려면 redirect_back: true를 전달합니다. 블록을 전달하면 응답을 대체합니다.

check_rate_limit!(:raw_blob, scope: { project: @project, path: @path }) do
  render plain: _('You cannot access the raw file. Please wait a minute.'), status: :too_many_requests
end

Grape API 엔드포인트#

Grape의 check_rate_limit!도 throttled_request?를 호출합니다. 동작이 제한을 넘으면 이 메서드는 429 Too Many Requests와 함께 키로 설정한 RateLimit-Name 헤더로 응답합니다. Retry-After 헤더는 호출이 interval: 옵션을 전달한 경우 그 값이고, 그렇지 않으면 키의 기간입니다. 오류 메시지를 대체하려면 message:를 전달합니다. 블록은 응답 전에 실행되며 응답을 대체하지 않습니다.

check_rate_limit_by_user_or_ip!는 인증된 요청이면 current_user를 기준으로, 그렇지 않으면 IP 주소를 기준으로 제한의 범위를 지정합니다.

check_rate_limit_by_user_or_ip!(:<key>)

서비스#

RateLimitedService를 prepend하고 키를 선언합니다. opts:의 scope는 각 특성을 그 값을 제공하는 서비스 메서드에 대응시킵니다.

prepend RateLimitedService

rate_limit key: :issues_create,
  opts: { scope: { project: :project, user: :current_user } }

execute는 제한을 먼저 확인하고, 동작이 제한을 넘으면 RateLimitedService::RateLimitedError를 발생시킵니다. ApplicationController와 API::API는 이 오류를 rescue하고 요청을 기록한 뒤 429 Too Many Requests로 응답합니다. GraphqlController도 같은 상태로 응답합니다. 확인 없이 서비스를 실행하려면 execute 대신 execute_without_rate_limiting을 호출합니다.

GraphQL 뮤테이션, 워커, 라이브러리 코드#

Gitlab::ApplicationRateLimiter.throttled?를 호출합니다. 이 메서드는 동작을 집계하고 동작이 제한을 넘으면 true를 반환합니다. GraphQL 뮤테이션에서는 RateLimitedService::RateLimitedError를 발생시키며, GraphqlController가 이를 429 Too Many Requests 응답으로 바꿉니다.

def check_rate_limit!
  return unless ::Gitlab::ApplicationRateLimiter.throttled?(RATE_LIMIT_KEY, scope: { user: current_user })

  raise ::RateLimitedService::RateLimitedError.new(
    key: RATE_LIMIT_KEY, rate_limiter: ::Gitlab::ApplicationRateLimiter
  ), ::Gitlab::ApplicationRateLimiter.throttled_error_message
end

그 밖의 경우에는 작업을 건너뛰거나 이벤트를 버리는 등, 동작이 제한을 넘었을 때 코드가 무엇을 할지 직접 정합니다.

그 밖의 확인 메서드와 옵션#

Gitlab::ApplicationRateLimiter에는 진입점이 다루지 않는 경우를 위한 다른 메서드가 있습니다.

  • throttled_request?: 컨트롤러와 Grape 헬퍼가 호출하는 메서드입니다. 요청은 있지만 헬퍼를 사용할 수 없을 때 직접 호출합니다.
  • peek: 동작을 집계하지 않고 동작이 제한을 넘었는지 여부를 반환합니다.
  • resource_usage_throttled?: 호출 한 번 대신 데이터베이스 소요 시간 같은 비용을 더합니다. Sidekiq 리소스 사용량 미들웨어가 이를 사용합니다.

throttled?와 헬퍼는 다음 옵션을 받습니다.

  • threshold:와 interval:은 호출 한 번에 한해 등록된 제한과 기간을 재정의합니다. 키의 limit 또는 period는 ->(ctx) { ctx&.dig(:threshold) || 100 }처럼 컨텍스트 인수를 받는 람다여야 합니다. 그렇지 않으면 호출이 ArgumentError를 발생시킵니다.
  • users_allowlist:는 제한이 적용되지 않는 사용자 이름 목록이며, GITLAB_THROTTLE_USER_ALLOWLIST가 지정한 사용자와 병합됩니다. 스코프에 user가 포함되어야 합니다. RateLimitedService에서는 concern이 호출하므로 목록을 반환하는 람다를 전달합니다.
  • resource:는 count_distinct 키에서 집계할 레코드입니다.
  • cost:는 호출을 집계하는 키에 한 번의 호출로 여러 동작의 비용을 부과합니다.

특성 이름#

각 속도 제한 키는 순서가 있는 특성 목록을 등록합니다. 이름은 :user, :project, :ip, :group, :namespace처럼 단순한 명사입니다. ActiveRecord 값이 기본 키를 사용하더라도 _id 접미사는 붙이지 않습니다.

행위자별이 아니라 전역으로 적용되는 제한은 이름이 scope인 특성 하나를 등록하므로, 호출은 scope: { scope: :global }처럼 보입니다.

Gitlab::ApplicationRateLimiter.throttled?(:fetch_google_ip_list, scope: { scope: :global })

이 반복은 특성 이름이 키워드 인수 이름과 겹쳐서 생긴 것이며 실수가 아닙니다.

특성 이름은 Redis 키의 일부입니다. 이름을 바꾸면 새 카운터가 시작되고 이전 카운터에 누적된 값은 버려지므로, 이름 변경은 리팩터링이 아니라 동작 변경으로 취급합니다.

기능 플래그 뒤에서 속도 제한 롤아웃#

새 속도 제한은 기능 플래그 뒤에서 롤아웃하면, 먼저 일부 액터에게만 제한을 활성화하고 배포 없이 비활성화할 수 있습니다. GitLab.com의 제한 관리 프로세스는 모든 새 제한에 롤아웃 계획을 요구합니다.

해당하는 첫 번째 옵션을 선택합니다.

  1. 새 Gitlab::ApplicationRateLimiter 키. staged_rule로 정의합니다. 이 규칙은 플래그가 활성화될 때까지 키를 로그 모드로 실행하고, 호출자의 scope:에 있는 어떤 값이든 플래그 액터로 사용하므로 호출 지점은 바뀌지 않습니다. 자세한 내용은 로그 모드로 키 롤아웃을 참고합니다. 인스턴스 전역 게이트도 인수를 하나 받습니다(enforce: ->(_scope) { ::Feature.enabled?(:flag, :instance) }). staged_rule은 다른 인수 개수에 ArgumentError를 발생시키기 때문입니다.

  2. 기존 키, 인스턴스 전역 스위치. 플래그가 비활성화된 동안 limit 람다에서 0을 반환합니다. 제한이 0이면 Gitlab::ApplicationRateLimiter가 집계 전에 false를 반환하므로, 호출자를 변경하지 않고 키를 비활성화할 수 있습니다. 람다는 사용자나 프로젝트를 받지 않으므로 플래그는 :instance로만 확인하며, 액터 목록이나 액터 비율 롤아웃은 적용되지 않습니다. issuable_csv_import 키가 이 패턴을 사용합니다.

    limit: -> {
      next 0 unless ::Feature.enabled?(:issuable_csv_import_rate_limit, :instance)
    
      Gitlab::CurrentSettings.current_application_settings.issuable_csv_import_limit
    },
    
  3. 기존 키, 액터별 게이트. 속도 제한을 확인하기 전에 호출 지점에서 플래그를 확인합니다.

    def check_create_rate_limit!
      return unless Feature.enabled?(:namespace_create_rate_limit, current_user)
    
      check_rate_limit!(:groups_create, scope: { user: current_user })
    end
    

    모든 호출 지점에 이 확인이 필요합니다. RateLimitedService 키는 execute에서 확인을 실행하므로, 게이트를 서비스에 두거나 각 호출자가 execute_without_rate_limiting을 선택해야 합니다.

  4. LabKit 요청 스로틀. 플래그는 없습니다. 대신 스로틀을 드라이 런 모드로 실행할 수 있습니다. 자세한 내용은 스로틀 등록을 참고합니다.

속도 제한을 문서화할 때 플래그를 포함합니다. 자세한 내용은 기능 플래그 뒤에 배포된 기능 문서화를 참고합니다.

로그 모드로 Gitlab::ApplicationRateLimiter 키 롤아웃#

제한을 적용하기 전에 새 키가 어떤 요청을 차단할지 확인하려면 로그 모드를 사용합니다. Labkit::RateLimit::Rule.new 대신 staged_rule로 키를 정의하고, 적용 여부를 기능 플래그로 제어합니다. 플래그는 레지스트리가 확인하므로 호출 지점은 바뀌지 않으며 플래그를 확인하지 않습니다. 등급별 요청 속도 제한도 같은 :log 및 :limit 규칙 패턴을 사용합니다. 자세한 내용은 등급별 요청 속도 제한을 참고합니다.

staged_rule은 action을 제외한 규칙과 같은 속성에 enforce 람다를 더해 받습니다.

widgets_export: staged_rule(
  enforce: ->(scope) { ::Feature.enabled?(:widgets_export_rate_limit_enforce, scope[:project]) },
  name: 'limit_widgets_exports_by_project_user',
  characteristics: %i[project user],
  limit: -> { Gitlab::CurrentSettings.current_application_settings.widgets_export_limit },
  period: 1.minute
),

staged_rule은 제한, 기간, 특성이 같은 규칙 둘을 등록합니다. enforce의 반환 값이 요청에 어느 규칙이 적용될지 결정합니다.

  • true: 지정한 이름의 :limit 규칙이 요청을 집계하고, 제한을 넘으면 차단합니다.
  • 그 밖의 값: 이름에 _log 접미사가 붙은 :log 규칙이 요청을 집계하지만 차단하지는 않습니다. enforce가 오류를 발생시키면 오류가 추적되고 :log 규칙이 적용됩니다.

enforce 람다는 호출자가 전달한 scope: 해시를 받으므로, 스코프의 어떤 특성 값이든 기능 플래그 액터로 사용할 수 있습니다. 모든 호출자가 전달하는 특성을 사용합니다. 값이 nil이면 액터 없이 플래그를 확인하므로, 액터 목록이나 액터 비율 롤아웃은 그 호출에 적용되지 않습니다. 람다에서는 리터럴 기능 플래그 이름을 사용합니다. Gitlab/FeatureFlagKeyDynamic cop은 런타임에 만든 이름을 거부합니다.

키를 롤아웃하는 절차는 다음과 같습니다.

  1. staged_rule로 키를 추가하고, default_enabled: false인 기능 플래그를 추가합니다.
  2. 플래그가 비활성화된 동안 키가 차단할 요청을 모니터링합니다.
    • _log 규칙 이름과 result="log"가 있는 gitlab_labkit_rate_limiter_rule_evaluations_total 메트릭.
    • 요청 또는 Sidekiq 작업 로그 줄의 rate_limit_state 필드. 요청이 제한을 넘었으면 applimiter_<key>:<rule>_log:log, 넘지 않았으면 :allow가 들어 있습니다. 같은 줄의 meta 필드는 누가 요청했는지 알려 줍니다.
  3. 기능 플래그를 활성화해 제한을 적용합니다. 플래그를 비활성화하면 로그 모드로 돌아갑니다.
  4. 롤아웃이 끝나면 staged_rule을 Labkit::RateLimit::Rule.new와 action: :limit으로 바꾸고 기능 플래그를 제거합니다.

스테이지된 키만 rate_limit_state에 항목을 추가하며, 확인 한 번에 항목 하나를 추가하고 peek에는 추가하지 않습니다. 요청 속도 제한이 :log 규칙을 기록하는 방식과 같습니다. 별도의 로그 줄은 없습니다.

_log 규칙과 :limit 규칙은 서로 다른 Redis 카운터를 사용합니다. 플래그를 활성화하면 :limit 규칙은 0부터 집계를 시작합니다. 정리 후에도 :limit 규칙은 이름을 유지하므로 :limit 규칙 카운터는 다시 초기화되지 않습니다.

staged_rule은 새 키에만 사용합니다. GitLab Self-Managed 인스턴스처럼 플래그가 비활성화된 인스턴스는 플래그를 제거할 때까지 제한을 적용하지 않습니다.

속도 제한 아키텍처#

LabKit 속도 제한의 설계와 제안된 변경 사항은 Unified rate limiting architecture를 참고합니다.

애플리케이션 제한 개발

GitLab v19.6
원문 보기

요약

이 문서는 GitLab에 애플리케이션 제한을 추가하려는 기여자를 위한 개발 가이드입니다. 먼저 GitLab 티어별로 어떤 제한이 설정되는지 정보를 모으고 결정해야 합니다. 제한 유형에 맞는 페이지에 문서를 추가합니다. 애플리케이션 제한 도입에 관한 가이드도 있습니다.

이 문서는 GitLab에 애플리케이션 제한을 추가하려는 기여자를 위한 개발 가이드입니다.

문서화#

먼저 GitLab 티어별로 어떤 제한이 설정되는지 정보를 모으고 결정해야 합니다. 다른 구성원과 협의해 그 제한을 문서화하고 공유합니다.

제한 유형에 맞는 페이지에 문서를 추가합니다.

애플리케이션 제한 도입에 관한 가이드도 있습니다.

플랜 제한 구현#

plan_limits 테이블은 셀 범위 구성입니다. 각 셀은 이 테이블의 사본을 따로 가지며 제한은 셀 간에 이전되지 않습니다. 새 셀은 각 제한의 칼럼 기본값으로 시작하고, 관리자는 관리자 Plan Limits API로 셀별 제한을 조정합니다. 따라서 모든 새 플랜 제한은 그 API로 설정할 수 있어야 합니다. 그렇지 않으면 새 제한은 각 셀에서 칼럼 기본값만 갖게 됩니다.

셀 간에 값이 일관되게 유지되어야 하는 플랜 제한은 도입하지 않습니다. plan_limits는 셀 로컬이므로 동기화를 유지할 방법이 없습니다.

데이터베이스 플랜 제한 삽입#

plan_limits 테이블에 새 칼럼을 만들고 제한 값을 삽입합니다. 마이그레이션 스크립트 파일은 두 개로 나누어 만들기를 권장합니다.

  1. plan_limits 테이블에 원하는 제한을 나타내는 null 이 아닌 기본값을 가진 새 칼럼을 추가합니다. 예를 들면 다음과 같습니다.

    add_column(:plan_limits, :project_hooks, :integer, default: 100, null: false)
    

    플랜 제한 항목이 0 이면 제한이 활성화되지 않았다는 뜻입니다. 이 설정은 특별하고 문서화된 상황에서만 사용합니다.

  2. (선택 사항) create_or_update_plan_limit 마이그레이션 헬퍼를 사용해 각 수준을 원하는 제한으로 조정하는 데이터베이스 마이그레이션을 만듭니다. 이 마이그레이션의 플랜은 GitLab.com의 플랜과 일치해야 합니다. 플랜이 누락되면 해당 플랜 고객은 기본 제한을 적용받게 되며, 그 값은 0(무제한)일 수 있습니다.

    예를 들면 다음과 같습니다.

    class InsertProjectHooksPlanLimits < Gitlab::Database::Migration[2.1]
      def up
        create_or_update_plan_limit('project_hooks', 'default', 0)
        create_or_update_plan_limit('project_hooks', 'free', 10)
        create_or_update_plan_limit('project_hooks', 'premium', 30)
        create_or_update_plan_limit('project_hooks', 'premium_trial', 30)
        create_or_update_plan_limit('project_hooks', 'ultimate', 100)
        create_or_update_plan_limit('project_hooks', 'ultimate_trial', 100)
        create_or_update_plan_limit('project_hooks', 'ultimate_trial_paid_customer', 100)
        create_or_update_plan_limit('project_hooks', 'opensource', 100)
      end
    
      def down
        create_or_update_plan_limit('project_hooks', 'default', 0)
        create_or_update_plan_limit('project_hooks', 'free', 0)
        create_or_update_plan_limit('project_hooks', 'premium', 0)
        create_or_update_plan_limit('project_hooks', 'premium_trial', 0)
        create_or_update_plan_limit('project_hooks', 'ultimate', 0)
        create_or_update_plan_limit('project_hooks', 'ultimate_trial', 0)
        create_or_update_plan_limit('project_hooks', 'ultimate_trial_paid_customer', 0)
        create_or_update_plan_limit('project_hooks', 'opensource', 0)
      end
    end
    

    일부 플랜은 GitLab.com 에만 존재합니다. 존재하지 않는 플랜에 대해서는 아무 동작도 하지 않습니다.

    마이그레이션에서 GitLab.com 에만 제한을 설정하고 다른 인스턴스는 기본 제한을 사용하게 하려면 #up과 #down 메서드 시작 부분에 return unless Gitlab.com?을 추가해 다른 인스턴스에서는 마이그레이션이 아무 동작도 하지 않도록 합니다.

  3. 관리자 Plan Limits API를 통해 새 칼럼을 노출합니다.

플랜 제한 유효성 검사#

현재 제한 가져오기#

현재 제한은 프로젝트나 네임스페이스를 통해 확인할 수 있습니다. 예를 들면 다음과 같습니다.

project.actual_limits.project_hooks

현재 제한 확인#

현재 제한을 초과했는지 확인하는 메서드로 PlanLimits#exceeded?가 있습니다. ActiveRecord 객체나 Integer 중 하나를 사용할 수 있습니다.

레코드 수가 정의된 제한을 초과하지 않는지 확인합니다. 예를 들면 다음과 같습니다.

project.actual_limits.exceeded?(:project_hooks, ProjectHook.where(project: project))

숫자가 정의된 제한을 초과하지 않는지 확인합니다. 예를 들면 다음과 같습니다.

project.actual_limits.exceeded?(:project_hooks, 10)

Limitable concern#

Limitable concern 을 사용하면 모델이 제한을 초과하지 않는지 검증할 수 있습니다. 현재 모델의 레코드 수가 정의된 제한을 초과하지 않도록 보장합니다.

검증 대상 객체의 제한 범위를 지정해야 하며, 제한 이름이 모델 이름의 복수형과 다르면 제한 이름도 지정해야 합니다.

class ProjectHook
  include Limitable

  self.limit_name = 'project_hooks' # Optional as ProjectHook corresponds with project_hooks
  self.limit_scope = :project
end

모델을 테스트하려면 공유 예제를 포함할 수 있습니다.

it_behaves_like 'includes Limitable concern' do
  subject { build(:project_hook, project: create(:project)) }
end

인스턴스 전역 제한 테스트#

인스턴스 전역 기능에는 라이선스가 할당되지 않으므로 항상 default 플랜을 사용합니다.

class InstanceVariable
  include Limitable

  self.limit_name = 'instance_variables' # Optional as InstanceVariable corresponds with instance_variables
  self.limit_scope = Limitable::GLOBAL_SCOPE
end

구독 플랜#

GitLab Self-Managed:

  • default: 모든 사용자.

GitLab.com:

  • default: 시스템 전역 기능 전체.
  • free: Free 구독을 사용하는 네임스페이스와 프로젝트.
  • premium: Premium 구독을 사용하는 네임스페이스와 프로젝트.
  • premium_trial: Premium Trial 구독을 사용하는 네임스페이스와 프로젝트.
  • ultimate: Ultimate 구독을 사용하는 네임스페이스와 프로젝트.
  • ultimate_trial: Ultimate Trial 구독을 사용하는 네임스페이스와 프로젝트.
  • ultimate_trial_paid_customer: Premium 구독 상태에서 Ultimate를 30일간 체험 중인 네임스페이스와 프로젝트.
  • opensource: GitLab Open Source 프로그램에 참여 중인 네임스페이스와 프로젝트.

GitLab.com에는 구독이 없는 early_adopter 플랜이 있습니다.

test 환경에는 플랜이 없습니다.

속도 제한 추가#

GitLab에는 애플리케이션 코드용 속도 제한기가 두 가지 있습니다. 둘 다 LabKit 속도 제한 SDK를 사용하며, 카운터를 속도 제한용 Redis 인스턴스에 저장합니다.

속도 제한을 추가하는 절차는 다음과 같습니다.

  1. 속도 제한기를 선택합니다.
  2. 속도 제한을 구성 가능하게 만듭니다. 새 속도 제한에는 모두 애플리케이션 설정이 필요합니다.
  3. 제한을 LabKit 요청 속도 제한 또는 Gitlab::ApplicationRateLimiter 키로 등록합니다.
  4. Gitlab::ApplicationRateLimiter 키라면 동작을 수행하는 코드에서 속도 제한을 확인합니다.
  5. 기능 플래그 뒤에서 속도 제한을 롤아웃합니다.
  6. 속도 제한을 문서화합니다.

속도 제한기 선택#

다음에 해당하면 LabKit으로 요청 속도 제한을 추가합니다.

  • 제한이 각 요청이 수행하는 동작과 관계없이 요청량으로부터 라우트 그룹을 보호합니다. 예를 들어 패키지 API, 파일 API, HTTP를 통한 Git이 있습니다.
  • 제한이 IP 주소 또는 인증된 요청자를 기준으로 집계합니다.
  • 컨트롤러나 Grape 엔드포인트에 도달하기 전에 요청을 차단해야 합니다.

다음에 해당하면 Gitlab::ApplicationRateLimiter 키를 추가합니다.

  • 제한이 이슈 생성이나 이메일 전송처럼 하나의 동작에 적용됩니다.
  • 제한이 프로젝트, 그룹, 네임스페이스 같은 리소스 또는 값의 조합을 기준으로 집계합니다.
  • 제한이 서로 다른 리소스를 집계하거나, Sidekiq 워커처럼 웹 요청 밖에서 작업이 실행됩니다.

두 속도 제한기 중 어느 쪽이든 쓸 수 있다면 Gitlab::ApplicationRateLimiter를 사용합니다. 이 제한은 그것을 호출하는 동작에만 적용됩니다.

속도 제한을 구성 가능하게 만들기#

속도 제한에는 관리자가 코드 변경 없이 제한을 높이거나 낮추거나 비활성화할 수 있도록 애플리케이션 설정이 필요합니다. 제한을 구성할 수 없게 해야 한다면 머지 리퀘스트에 그 이유를 적고 해당 제한을 구성할 수 없는 속도 제한으로 문서화합니다.

새 속도 제한 설정은 ApplicationSetting의 rate_limits JSONB 칼럼에 있는 필드입니다. 이전 스로틀 설정은 테이블 칼럼입니다. 설정을 추가하는 절차는 다음과 같습니다.

  1. app/models/application_setting.rb의 ApplicationSetting.rate_limits_definition에 필드와 기본값을 추가합니다. EE 전용 제한이라면 ee/app/models/ee/application_setting.rb의 EE 재정의에 추가합니다.

    • Gitlab::ApplicationRateLimiter 키에는 정수 필드가 하나 있습니다.

      discussions_resolve_limit: [:integer, { default: 120 }],
      
    • LabKit 요청 스로틀에는 불리언 필드 하나와 정수 필드 둘이 있습니다.

      throttle_authenticated_mcp_enabled: [:boolean, { default: false }],
      throttle_authenticated_mcp_requests_per_period: [:integer, { default: 600 }],
      throttle_authenticated_mcp_period_in_seconds: [:integer, { default: 60 }],
      
  2. 같은 모델에서 정수 필드를 검증합니다. 이 모델에는 with_options(numericality: ...) 블록이 둘 있습니다.

    • Gitlab::ApplicationRateLimiter 제한은 0이 키를 비활성화하므로 greater_than_or_equal_to: 0 블록에 추가합니다.
    • LabKit의 requests_per_period와 period_in_seconds 필드는 greater_than: 0 블록에 추가합니다.
  3. app/validators/json_schemas/application_setting_rate_limits.json의 JSON 스키마에 필드를 추가합니다.

    • Gitlab::ApplicationRateLimiter 제한은 "minimum": 0인 integer입니다.
    • LabKit의 requests_per_period와 period_in_seconds 필드는 "minimum": 1인 integer이고, enabled 필드는 boolean입니다.
  4. app/helpers/application_settings_helper.rb의 ApplicationSettingsHelper#visible_attributes에 설정을 추가합니다. EE 전용 제한이라면 ee/app/helpers/ee/application_settings_helper.rb의 EE 재정의에 추가합니다. 이 목록은 애플리케이션 설정 API에서 설정을 읽고 쓸 수 있도록 노출하고, Admin 영역 컨트롤러에서 허용합니다. 전체 절차는 애플리케이션 설정을 참고합니다.

  5. lib/api/settings.rb에 type:과 desc:가 있는 optional 매개변수를 추가합니다. EE 전용 제한이라면 ee/lib/ee/api/helpers/settings_helpers.rb에 추가합니다. 그러면 API가 값을 검증하고 OpenAPI 문서가 이를 설명합니다. 애플리케이션 설정 API에 속성을 문서화합니다.

  6. 선택 사항입니다. app/views/admin/application_settings/의 해당 부분 템플릿에 양식 필드를 추가합니다.

  7. 제한에서 설정을 읽습니다.

    • Gitlab::ApplicationRateLimiter 키에서는 limit을 설정을 읽는 람다로 지정합니다.

      limit: -> { Gitlab::CurrentSettings.current_application_settings.discussions_resolve_limit },
      
    • LabKit 요청 스로틀에서는 스로틀 정의에서 Gitlab::Throttle.settings를 통해 설정을 읽습니다.

LabKit으로 요청 속도 제한 구현#

Gitlab::Middleware::LabkitRackRateLimit 미들웨어는 Rails 컨트롤러, Grape 엔드포인트, 그 밖의 모든 Rack 요청에 속도 제한을 적용합니다. 이 미들웨어는 Warden이 요청을 인증한 뒤, 요청이 애플리케이션에 도달하기 전에 실행됩니다. 제한을 넘은 요청은 429 Too Many Requests 응답을 받습니다.

이 속도 제한은 LabKit이 적용합니다. Rack::Attack은 여전히 미들웨어 스택에 있지만 요청을 스로틀링하지 않습니다. LabKit은 Gitlab::RackAttack의 스로틀 정의에서 각 제한과 기간을 읽으므로, 새 스로틀도 여전히 그곳에서 시작합니다.

요청 속도 제한을 추가하는 절차는 다음과 같습니다.

  1. 속도 제한을 구성 가능하게 만듭니다.
  2. 제한과 기간을 담는 스로틀 정의를 추가합니다.
    • 단일 스로틀은 Gitlab::RackAttack.throttle_definitions에 추가하고, Gitlab::RackAttack::Request에 대응하는 조건자를 추가합니다.
    • 인증된 요청과 인증되지 않은 요청 쌍은 Gitlab::Throttle::REGULAR_THROTTLES에 항목 하나를 추가합니다. Gitlab::RackAttack.regular_throttle_definitions가 이 항목에서 throttle_unauthenticated_<name>과 throttle_authenticated_<name>을 생성합니다.
  3. ThrottleRegistry에 스로틀을 등록합니다. 자세한 내용은 스로틀 등록을 참고합니다.
  4. app/views/admin/application_settings/_ip_limits.html.haml의 Admin 영역 양식에 새 설정을 추가합니다.
  5. 선택 사항입니다. 스로틀이 요청을 차단하기 전에 관찰하려면 GITLAB_THROTTLE_DRY_RUN 환경 변수에 스로틀 이름을 지정합니다. 드라이 런 모드의 스로틀은 :limit 규칙 대신 :log 규칙으로 빌드되며, 클레임 이름은 <rule_name>_claim 대신 <rule_name>_dry_run_bypass가 됩니다.
  6. User and IP rate limits에 새 설정을 문서화합니다.
  7. GitLab.com의 속도 제한을 구성하고 GitLab.com의 속도 제한에 문서화합니다.

스로틀 등록#

각 스로틀은 Gitlab::RackAttack::LabkitRateLimit::ThrottleRegistry의 LabKit 규칙 하나에 대응합니다. 이 레지스트리는 lib/gitlab/rack_attack/labkit_rate_limit/throttle_registry.rb에 정의되어 있으며, EE 스로틀은 ee/lib/ee/gitlab/rack_attack/labkit_rate_limit/throttle_registry.rb에 정의되어 있습니다. Gitlab::RackAttack.all_throttle_definitions에 있는 스로틀에 레지스트리 항목이 없으면 스펙이 실패합니다.

각 항목은 다음을 선언합니다.

  • limiter: 규칙을 소유하는 제한기입니다. 일반 제한기의 규칙도 집계하는 요청을 스로틀이 집계해야 하는 경우가 아니라면 ThrottleRegistry::GENERAL을 사용합니다. 하나의 제한기에서는 요청을 처음 클레임한 규칙이 그 요청을 집계하므로, 다른 규칙과 같은 요청을 집계하는 스로틀에는 자체 제한기가 필요합니다. 보호된 경로와 EE 인시던트 관리 스로틀은 이 이유로 자체 제한기를 가집니다.
  • characteristics: 규칙이 집계하는 기준입니다. 예를 들어 인증되지 않은 스로틀은 [:ip], 인증된 스로틀은 [:requester_type, :requester_id]입니다.
  • match: 규칙이 적용되려면 요청이 가져야 하는 팩트입니다.
  • cohort: 규칙의 적용 여부를 기능 플래그로 제어하는 롤아웃 코호트입니다. 기존 코호트를 사용합니다. 새 코호트에는 자체 기능 플래그 정의가 필요하며, 새 코호트의 두 플래그가 모두 활성화될 때까지 Rack::Attack이 요청을 다시 스로틀링합니다.
  • claims: 규칙이 요청을 집계한 뒤 평가를 중단할지 여부입니다. 모든 항목이 이를 선언해야 합니다.

LabKit은 건너뛰기 규칙(예: 우회 헤더와 사용자 허용 목록)을 먼저 평가하고, 그다음 GitLab.com 플랜 규칙, 그다음 레지스트리 규칙을 평가합니다. 레지스트리 규칙은 레지스트리 순서대로 평가됩니다. 특화된 API, Git, 웹, 일반 API 순입니다. claims: true인 스로틀은 요청을 집계하고 평가를 중단하므로, 목록 뒤쪽의 더 일반적인 규칙은 같은 요청을 집계하지 않습니다.

클레임에는 스로틀의 setting_* 팩트가 포함되므로, 순서에 따른 제외는 클레임하는 스로틀이 활성화되어 있는 동안에만 요청을 제외합니다. 항상 적용되어야 하는 제외에는 웹 및 API 규칙이 path: { nre: <regex> }, git_http_non_lfs: false, frontend: false로 하듯이 match에 부정 팩트를 추가합니다.

match에서는 다음을 따릅니다.

  • nil일 수 있는 각 특성의 존재 여부를 규칙의 조건으로 둡니다. 인증된 규칙은 requester_id: /./를 조건으로 하고, [:aid]로 집계하는 규칙은 aid: /./를 조건으로 합니다. 이 조건이 없으면 값이 없는 요청이 하나의 카운터를 공유합니다.
  • 인증되지 않은 규칙은 requester_id: nil, runner_id: nil을 조건으로 합니다.
  • 스로틀의 setting_* 팩트를 포함해, Admin 영역에서 스로틀을 비활성화하면 규칙이 더 이상 일치하지 않도록 합니다.
  • path: 정규식은 마지막에 둡니다. 조건은 순서대로 검사하고 처음 실패한 조건에서 평가를 중단하므로, 비용이 낮은 조건을 먼저 두면 정규식 실행을 피할 수 있습니다.

규칙은 Gitlab::RackAttack::LabkitRateLimit::ClassifiedRequest#labkit_facts가 반환하는 팩트에서 일치 여부를 판단하며, 이 팩트는 ID 팩트와 분류 팩트를 병합한 것입니다. 스로틀의 setting_* 팩트를 ClassifiedRequest#classification_facts에 추가하고, EE 스로틀이라면 EE 모듈에 추가합니다. 경로 정규식으로 표현할 수 없는 조건에만 분류 팩트를 추가합니다.

등급별 요청 속도 제한#

GitLab.com에서 Gitlab::RateLimit::PlanRules는 요청자의 구독 플랜에 따라 달라지는 요청 속도 제한을 추가합니다. 이 규칙은 ee/lib/ee/gitlab/rate_limit/plan_rules.rb에 정의되어 있으며 GitLab.com에만 적용됩니다.

  • 각 제한에는 규칙이 둘 있습니다. 요청을 집계하는 :log 규칙과 요청을 차단하는 :limit 규칙입니다. 접미사가 _info와 _enforce인 기능 플래그가 어느 규칙이 일치할지 결정합니다.
  • 인증된 사용자는 직접 또는 공유 그룹을 통해 멤버로 속한 최상위 그룹 중 가장 높은 플랜을 적용받습니다. 유료 그룹이 없는 사용자는 Free 제한을 적용받습니다.

Gitlab::ApplicationRateLimiter를 사용한 속도 제한 구현#

Gitlab::ApplicationRateLimiter는 단일 동작을 제한합니다. 컨트롤러, API 엔드포인트, 서비스, 워커처럼 동작을 수행하는 코드에서 호출합니다. 각 속도 제한 키는 LabKit 규칙입니다.

속도 제한 키 추가#

  1. Gitlab::ApplicationRateLimiter::LabkitAdapter::SupportedRateLimits에 키에 대한 Labkit::RateLimit::Rule을 추가합니다. CE 키는 lib/gitlab/application_rate_limiter/labkit_adapter/supported_rate_limits.rb에 있고, EE 전용 키와 EE 재정의는 ee/lib/ee/gitlab/application_rate_limiter/labkit_adapter/supported_rate_limits.rb에 있습니다. 규칙이 없는 키는 Gitlab::ApplicationRateLimiter::InvalidKeyError를 발생시킵니다.

    issues_create: ::Labkit::RateLimit::Rule.new(
      name: 'limit_issues_by_project_user_external_author',
      characteristics: %i[project user external_author],
      limit: -> { Gitlab::CurrentSettings.current_application_settings.issues_create_limit },
      period: 1.minute,
      action: :limit
    ),
    
  2. 규칙 속성을 설정합니다. 각 속성의 역할은 LabKit 문서의 Rule을 참고합니다. GitLab에서는 다음을 따릅니다.

    • name은 limit_로 시작해야 합니다. 접두사가 없는 이름은 스펙이 실패합니다.
    • action은 :limit이어야 합니다. 새 키를 로그 모드로 먼저 롤아웃하려면 대신 staged_rule로 정의합니다. staged_rule은 action을 직접 설정합니다. 로그 모드로 키 롤아웃을 참고합니다.
    • limit은 제한에 대한 애플리케이션 설정을 읽는 람다입니다.
    • characteristics는 특성 이름에 있는 이름을 사용합니다.
    • count_distinct는 선택 사항입니다. 호출 횟수를 집계하는 대신 resource:로 전달된 서로 다른 리소스를 집계하려면 :project_id로 설정합니다. 예시는 ee/lib/ee/gitlab/application_rate_limiter/labkit_adapter/supported_rate_limits.rb의 EE unique_project_downloads_for_application 키를 참고합니다.
  3. 동작을 수행하는 코드에서 키를 확인합니다.

모든 키가 제한과 기간을 정의해야 한다는 것이 스펙의 요구 사항입니다. 제한을 호출자로부터 받거나 호출 횟수 대신 비용을 집계하는 키는 spec/lib/gitlab/application_rate_limiter/labkit_adapter/supported_rate_limits_spec.rb에 예외로 나열되어 있습니다.

속도 제한 확인#

동작을 수행하는 코드에서 속도 제한을 확인합니다. 코드 경로마다 진입점이 하나씩 있습니다.

코드 경로 진입점
Rails 컨트롤러 ApplicationController가 포함하는 CheckRateLimit concern의 check_rate_limit!입니다.
Grape API 엔드포인트 API::API가 포함하는 API::Helpers::RateLimiter의 check_rate_limit!입니다.
서비스 RateLimitedService concern의 rate_limit입니다.
GraphQL 뮤테이션 Gitlab::ApplicationRateLimiter.throttled?를 호출한 뒤 RateLimitedService::RateLimitedError를 발생시킵니다.
Sidekiq 워커, 모델, 라이브러리 코드 Gitlab::ApplicationRateLimiter.throttled?입니다.

모든 진입점은 키와, 키가 SupportedRateLimits에 등록한 특성(characteristic) 이름을 키로 하는 scope: 해시를 받습니다.

Gitlab::ApplicationRateLimiter.throttled?(:issues_create, scope: { project: project, user: current_user })

ActiveRecord 값은 기본 키를, 기본 자료형은 문자열 형태를 사용합니다. 생략했거나 nil인 특성은 labkit의 _unknown_ 센티널을 키로 사용하며, 규칙의 특성이 아닌 스코프 키는 개발 및 테스트 환경에서 오류를 발생시킵니다.

Rails 컨트롤러#

check_rate_limit!는 Gitlab::ApplicationRateLimiter.throttled_request?를 호출하며, 이 메서드는 속도 제한 우회 헤더를 존중하고 제한된 요청을 메시지 Application_Rate_Limiter_Request와 함께 auth.log에 기록합니다. 동작이 제한을 넘으면 이 메서드는 429 Too Many Requests로 오류 메시지를 렌더링합니다. 대신 메시지를 알림으로 표시하며 이전 페이지로 리디렉션하려면 redirect_back: true를 전달합니다. 블록을 전달하면 응답을 대체합니다.

check_rate_limit!(:raw_blob, scope: { project: @project, path: @path }) do
  render plain: _('You cannot access the raw file. Please wait a minute.'), status: :too_many_requests
end

Grape API 엔드포인트#

Grape의 check_rate_limit!도 throttled_request?를 호출합니다. 동작이 제한을 넘으면 이 메서드는 429 Too Many Requests와 함께 키로 설정한 RateLimit-Name 헤더로 응답합니다. Retry-After 헤더는 호출이 interval: 옵션을 전달한 경우 그 값이고, 그렇지 않으면 키의 기간입니다. 오류 메시지를 대체하려면 message:를 전달합니다. 블록은 응답 전에 실행되며 응답을 대체하지 않습니다.

check_rate_limit_by_user_or_ip!는 인증된 요청이면 current_user를 기준으로, 그렇지 않으면 IP 주소를 기준으로 제한의 범위를 지정합니다.

check_rate_limit_by_user_or_ip!(:<key>)

서비스#

RateLimitedService를 prepend하고 키를 선언합니다. opts:의 scope는 각 특성을 그 값을 제공하는 서비스 메서드에 대응시킵니다.

prepend RateLimitedService

rate_limit key: :issues_create,
  opts: { scope: { project: :project, user: :current_user } }

execute는 제한을 먼저 확인하고, 동작이 제한을 넘으면 RateLimitedService::RateLimitedError를 발생시킵니다. ApplicationController와 API::API는 이 오류를 rescue하고 요청을 기록한 뒤 429 Too Many Requests로 응답합니다. GraphqlController도 같은 상태로 응답합니다. 확인 없이 서비스를 실행하려면 execute 대신 execute_without_rate_limiting을 호출합니다.

GraphQL 뮤테이션, 워커, 라이브러리 코드#

Gitlab::ApplicationRateLimiter.throttled?를 호출합니다. 이 메서드는 동작을 집계하고 동작이 제한을 넘으면 true를 반환합니다. GraphQL 뮤테이션에서는 RateLimitedService::RateLimitedError를 발생시키며, GraphqlController가 이를 429 Too Many Requests 응답으로 바꿉니다.

def check_rate_limit!
  return unless ::Gitlab::ApplicationRateLimiter.throttled?(RATE_LIMIT_KEY, scope: { user: current_user })

  raise ::RateLimitedService::RateLimitedError.new(
    key: RATE_LIMIT_KEY, rate_limiter: ::Gitlab::ApplicationRateLimiter
  ), ::Gitlab::ApplicationRateLimiter.throttled_error_message
end

그 밖의 경우에는 작업을 건너뛰거나 이벤트를 버리는 등, 동작이 제한을 넘었을 때 코드가 무엇을 할지 직접 정합니다.

그 밖의 확인 메서드와 옵션#

Gitlab::ApplicationRateLimiter에는 진입점이 다루지 않는 경우를 위한 다른 메서드가 있습니다.

  • throttled_request?: 컨트롤러와 Grape 헬퍼가 호출하는 메서드입니다. 요청은 있지만 헬퍼를 사용할 수 없을 때 직접 호출합니다.
  • peek: 동작을 집계하지 않고 동작이 제한을 넘었는지 여부를 반환합니다.
  • resource_usage_throttled?: 호출 한 번 대신 데이터베이스 소요 시간 같은 비용을 더합니다. Sidekiq 리소스 사용량 미들웨어가 이를 사용합니다.

throttled?와 헬퍼는 다음 옵션을 받습니다.

  • threshold:와 interval:은 호출 한 번에 한해 등록된 제한과 기간을 재정의합니다. 키의 limit 또는 period는 ->(ctx) { ctx&.dig(:threshold) || 100 }처럼 컨텍스트 인수를 받는 람다여야 합니다. 그렇지 않으면 호출이 ArgumentError를 발생시킵니다.
  • users_allowlist:는 제한이 적용되지 않는 사용자 이름 목록이며, GITLAB_THROTTLE_USER_ALLOWLIST가 지정한 사용자와 병합됩니다. 스코프에 user가 포함되어야 합니다. RateLimitedService에서는 concern이 호출하므로 목록을 반환하는 람다를 전달합니다.
  • resource:는 count_distinct 키에서 집계할 레코드입니다.
  • cost:는 호출을 집계하는 키에 한 번의 호출로 여러 동작의 비용을 부과합니다.

특성 이름#

각 속도 제한 키는 순서가 있는 특성 목록을 등록합니다. 이름은 :user, :project, :ip, :group, :namespace처럼 단순한 명사입니다. ActiveRecord 값이 기본 키를 사용하더라도 _id 접미사는 붙이지 않습니다.

행위자별이 아니라 전역으로 적용되는 제한은 이름이 scope인 특성 하나를 등록하므로, 호출은 scope: { scope: :global }처럼 보입니다.

Gitlab::ApplicationRateLimiter.throttled?(:fetch_google_ip_list, scope: { scope: :global })

이 반복은 특성 이름이 키워드 인수 이름과 겹쳐서 생긴 것이며 실수가 아닙니다.

특성 이름은 Redis 키의 일부입니다. 이름을 바꾸면 새 카운터가 시작되고 이전 카운터에 누적된 값은 버려지므로, 이름 변경은 리팩터링이 아니라 동작 변경으로 취급합니다.

기능 플래그 뒤에서 속도 제한 롤아웃#

새 속도 제한은 기능 플래그 뒤에서 롤아웃하면, 먼저 일부 액터에게만 제한을 활성화하고 배포 없이 비활성화할 수 있습니다. GitLab.com의 제한 관리 프로세스는 모든 새 제한에 롤아웃 계획을 요구합니다.

해당하는 첫 번째 옵션을 선택합니다.

  1. 새 Gitlab::ApplicationRateLimiter 키. staged_rule로 정의합니다. 이 규칙은 플래그가 활성화될 때까지 키를 로그 모드로 실행하고, 호출자의 scope:에 있는 어떤 값이든 플래그 액터로 사용하므로 호출 지점은 바뀌지 않습니다. 자세한 내용은 로그 모드로 키 롤아웃을 참고합니다. 인스턴스 전역 게이트도 인수를 하나 받습니다(enforce: ->(_scope) { ::Feature.enabled?(:flag, :instance) }). staged_rule은 다른 인수 개수에 ArgumentError를 발생시키기 때문입니다.

  2. 기존 키, 인스턴스 전역 스위치. 플래그가 비활성화된 동안 limit 람다에서 0을 반환합니다. 제한이 0이면 Gitlab::ApplicationRateLimiter가 집계 전에 false를 반환하므로, 호출자를 변경하지 않고 키를 비활성화할 수 있습니다. 람다는 사용자나 프로젝트를 받지 않으므로 플래그는 :instance로만 확인하며, 액터 목록이나 액터 비율 롤아웃은 적용되지 않습니다. issuable_csv_import 키가 이 패턴을 사용합니다.

    limit: -> {
      next 0 unless ::Feature.enabled?(:issuable_csv_import_rate_limit, :instance)
    
      Gitlab::CurrentSettings.current_application_settings.issuable_csv_import_limit
    },
    
  3. 기존 키, 액터별 게이트. 속도 제한을 확인하기 전에 호출 지점에서 플래그를 확인합니다.

    def check_create_rate_limit!
      return unless Feature.enabled?(:namespace_create_rate_limit, current_user)
    
      check_rate_limit!(:groups_create, scope: { user: current_user })
    end
    

    모든 호출 지점에 이 확인이 필요합니다. RateLimitedService 키는 execute에서 확인을 실행하므로, 게이트를 서비스에 두거나 각 호출자가 execute_without_rate_limiting을 선택해야 합니다.

  4. LabKit 요청 스로틀. 플래그는 없습니다. 대신 스로틀을 드라이 런 모드로 실행할 수 있습니다. 자세한 내용은 스로틀 등록을 참고합니다.

속도 제한을 문서화할 때 플래그를 포함합니다. 자세한 내용은 기능 플래그 뒤에 배포된 기능 문서화를 참고합니다.

로그 모드로 Gitlab::ApplicationRateLimiter 키 롤아웃#

제한을 적용하기 전에 새 키가 어떤 요청을 차단할지 확인하려면 로그 모드를 사용합니다. Labkit::RateLimit::Rule.new 대신 staged_rule로 키를 정의하고, 적용 여부를 기능 플래그로 제어합니다. 플래그는 레지스트리가 확인하므로 호출 지점은 바뀌지 않으며 플래그를 확인하지 않습니다. 등급별 요청 속도 제한도 같은 :log 및 :limit 규칙 패턴을 사용합니다. 자세한 내용은 등급별 요청 속도 제한을 참고합니다.

staged_rule은 action을 제외한 규칙과 같은 속성에 enforce 람다를 더해 받습니다.

widgets_export: staged_rule(
  enforce: ->(scope) { ::Feature.enabled?(:widgets_export_rate_limit_enforce, scope[:project]) },
  name: 'limit_widgets_exports_by_project_user',
  characteristics: %i[project user],
  limit: -> { Gitlab::CurrentSettings.current_application_settings.widgets_export_limit },
  period: 1.minute
),

staged_rule은 제한, 기간, 특성이 같은 규칙 둘을 등록합니다. enforce의 반환 값이 요청에 어느 규칙이 적용될지 결정합니다.

  • true: 지정한 이름의 :limit 규칙이 요청을 집계하고, 제한을 넘으면 차단합니다.
  • 그 밖의 값: 이름에 _log 접미사가 붙은 :log 규칙이 요청을 집계하지만 차단하지는 않습니다. enforce가 오류를 발생시키면 오류가 추적되고 :log 규칙이 적용됩니다.

enforce 람다는 호출자가 전달한 scope: 해시를 받으므로, 스코프의 어떤 특성 값이든 기능 플래그 액터로 사용할 수 있습니다. 모든 호출자가 전달하는 특성을 사용합니다. 값이 nil이면 액터 없이 플래그를 확인하므로, 액터 목록이나 액터 비율 롤아웃은 그 호출에 적용되지 않습니다. 람다에서는 리터럴 기능 플래그 이름을 사용합니다. Gitlab/FeatureFlagKeyDynamic cop은 런타임에 만든 이름을 거부합니다.

키를 롤아웃하는 절차는 다음과 같습니다.

  1. staged_rule로 키를 추가하고, default_enabled: false인 기능 플래그를 추가합니다.
  2. 플래그가 비활성화된 동안 키가 차단할 요청을 모니터링합니다.
    • _log 규칙 이름과 result="log"가 있는 gitlab_labkit_rate_limiter_rule_evaluations_total 메트릭.
    • 요청 또는 Sidekiq 작업 로그 줄의 rate_limit_state 필드. 요청이 제한을 넘었으면 applimiter_<key>:<rule>_log:log, 넘지 않았으면 :allow가 들어 있습니다. 같은 줄의 meta 필드는 누가 요청했는지 알려 줍니다.
  3. 기능 플래그를 활성화해 제한을 적용합니다. 플래그를 비활성화하면 로그 모드로 돌아갑니다.
  4. 롤아웃이 끝나면 staged_rule을 Labkit::RateLimit::Rule.new와 action: :limit으로 바꾸고 기능 플래그를 제거합니다.

스테이지된 키만 rate_limit_state에 항목을 추가하며, 확인 한 번에 항목 하나를 추가하고 peek에는 추가하지 않습니다. 요청 속도 제한이 :log 규칙을 기록하는 방식과 같습니다. 별도의 로그 줄은 없습니다.

_log 규칙과 :limit 규칙은 서로 다른 Redis 카운터를 사용합니다. 플래그를 활성화하면 :limit 규칙은 0부터 집계를 시작합니다. 정리 후에도 :limit 규칙은 이름을 유지하므로 :limit 규칙 카운터는 다시 초기화되지 않습니다.

staged_rule은 새 키에만 사용합니다. GitLab Self-Managed 인스턴스처럼 플래그가 비활성화된 인스턴스는 플래그를 제거할 때까지 제한을 적용하지 않습니다.

속도 제한 아키텍처#

LabKit 속도 제한의 설계와 제안된 변경 사항은 Unified rate limiting architecture를 참고합니다.