임포터 설계 원칙

GitLab 임포터 개발 시 보안, 로깅, 성능, 복원력, 일관성 측면에서 따라야 할 설계 원칙을 설명합니다.

보안 # 업로드된 파일은 반드시 유효성을 검사해야 합니다. 예시: BulkImports::FileDownloadService ImportExport::CommandLineUtil 임포터는 HTTP 호출을 수행하는 서드파티 Ruby gem을 추가해서는 안 됩니다. 임포터는 통합과 동일한 Ruby gem 정책 을 사용하며, 임포터에서의 Ruby gem 사용에 대한 자세한 내용은 해당 페이지를 참고하세요. 모든 HTTP 호출은 반드시 Import::Clients::HTTP 를 사용해야 합니다. 이 클라이언트는: HTTP 호출에 네트워크 설정 이 적용되도록 보장합니다. 추가적인 보안 강화 기능을 제공합니다. 안전한 HTTP 호출을 위한 단일 진실 공급원(Single Source Of Truth, SSOT)입니다. 모든 응답 크기는 반드시 유효성을 검사해야 합니다. 로깅 # 로그에는 github , bitbucket , bitbucket_server 와 같은 임포터 유형이 포함되어야 합니다. 임포트 소스의 전체 목록은 Gitlab::ImportSources 에서 확인할 수 있습니다. 로그에는 디버깅에 도움이 될 수 있는 정보가 포함되어야 합니다: id , iid 와 같은 객체 식별자 및 객체 유형 오류 또는 상태 메시지 로그에는 다음을 포함하여 민감하거나 개인적인 정보가 포함되어서는 안 됩니다: 사용자명 이메일 주소 해당하는 경우, UI에서 오류를 표시하는 데 도움이 되도록 Gitlab::Import::ImportFailureService 에서 오류를 추적해야 합니다. 개발 환경에서 주요 식별자가 누락된 경우 로깅이 오류를 발생시켜야 합니다. 이는 이 머지 리퀘스트 에서 시연되어 있습니다. 각 레코드를 임포트하기 전후에 해당 레코드의 식별자를 포함한 로그 라인을 생성해야 합니다. 성능 # 중복 데이터베이스 쿼리 및 API 호출을 방지하기 위해 기본 TTL이 24시간인 캐시를 사용해야 합니다. 컬렉션을 순회하는 Worker는 중단된 경우 중단된 지점부터 다시 시작할 수 있는 진행 포인터를 갖추어야 합니다. ID 추적을 사용한 예시 페이지 카운터를 사용한 예시 쓰기 작업이 많은 Worker는 데이터베이스 과부하를 방지하기 위해 defer_on_database_health_signal 을 구현해야 합니다. 다만, 작성 시점 기준으로 알려진 이슈 로 인해 현재 이를 사용할 수 없습니다. 리소스 포화를 방지하기 위해 Worker 동시성에 제한을 적용해야 합니다. Bitbucket의 ParallelScheduling 클래스 에서 예시를 확인할 수 있습니다. 임포터는 특히 새로운 기능을 구현하거나 기능 플래그를 활성화할 때 스테이징 환경에서 대규모로 테스트해야 합니다. 복원력 # Worker는 실패 시 안전하게 재시도할 수 있도록 멱등성을 가져야 합니다. Worker는 동시 배치 제한을 준수하는 지연을 두고 재큐(re-enqueue)되어야 합니다. 개별 Worker는 오랫동안 실행되어서는 안 됩니다. 오랫동안 실행되는 Worker는 배포로 인해 Sidekiq