• 일반 정보
  • API 엔드포인트
    • 원격 계층 구조
  • 명명 규칙
  • 서비스 및 파인더
  • 구성
• MVC 접근 방식
  • 작은 단계로 유지
  • 분석
  • 구현
    • 인증
    • 권한 부여
    • 데이터베이스 및 메타데이터 처리
    • 파일 업로드
    • 파일 크기 제한
    • GitLab.com의 요청 속도 제한
  • MVC 체크리스트
  • 향후 작업
• 예외

새 패키지 형식 지원 개발

이 문서는 GitLab에 새로운 패키지 관리 시스템을 지원하기 위한 가이드를 제공합니다.

이미 지원되는 형식은 패키지 및 레지스트리 문서에서 확인할 수 있습니다.

새로운 형식을 백엔드 변경만으로 추가하는 것이 가능합니다. 본 안내서는 표면적이며 코드 작성 방법에 대해서는 다루지 않습니다. 그러나 다음 병합 요청을 살펴봄으로써 좋은 예제를 찾을 수 있습니다:

• npm 레지스트리 지원
• Maven 저장소
• 인스턴스 수준 Maven 저장소용 API
• NuGet 그룹 수준 API

일반 정보

기존 데이터베이스 모델은 다음을 요구합니다:

• 각 패키지는 프로젝트에 속합니다.
• 각 패키지 파일은 패키지에 속합니다.
• 패키지는 하나 이상의 패키지 파일을 가질 수 있습니다.
• 패키지 모델은 패키지와 해당 버전에 대한 정보를 저장하는 것을 기반으로 합니다.

API 엔드포인트

패키지 시스템은 GitLab과 API를 통해 작동합니다. 예를 들어, lib/api/npm_project_packages.rb에서는 npm 클라이언트와 상호 작용하기 위한 API 엔드포인트를 구현합니다. 따라서 먼저 패키지 시스템 클라이언트가 작동하는 데 필요한 새로운 lib/api/your_name_project_packages.rb 파일을 추가해야 합니다. 일반적으로 다음과 같은 엔드포인트가 있는 것이 일반적입니다:

• 패키지 정보 가져오기.
• 패키지 파일 내용 가져오기.
• 패키지 업로드.

패키지가 프로젝트에 속하기 때문에, 제품화된 상태에 있는 프로젝트 단계 엔드포인트가 있어야 할 것으로 예상됩니다.

예를 들어:

GET https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/
PUT https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/

그룹 수준 및 인스턴스 수준의 엔드포인트는 프로젝트 수준 엔드포인트가 생산에 있을 때 고려해야 합니다.

원격 계층 구조

패키지는 다양한 접근 수준 내에서 범위가 지정되며, 일반적으로 원격을 설정함으로써 구성됩니다.
프로젝트 수준에서 원격 엔드포인트가 설정될 수 있으며, 이는 패키지를 설치할 때 해당 프로젝트에 속한 패키지만 표시됨을 의미합니다.
대조적으로, 그룹 수준의 엔포인트는 주어진 그룹의 모든 패키지에 대한 표시를 가능하게 하기 위해 사용될 수 있습니다. 마지막으로, 인스턴스 수준 엔드포인트는 전체 GitLab 인스턴스 내의 모든 패키지에 대한 가시성을 허용하기 위해 사용될 수 있습니다.

MVC로서, 프로젝트 수준 엔드포인트부터 시작하는 것을 권장합니다. 원격 계층에 대한 전형적인 반복 계획은 다음과 같습니다:

• 프로젝트에서 발행하고 설치합니다.
• 그룹에서 설치합니다.
• 인스턴스에서 발행하고 설치합니다(셀프 관리 고객용).

인스턴스 수준 엔드포인트의 사용은 더 엄격한 명명 규칙을 필요로 합니다.

명명 규칙

인스턴스 수준 엔드포인트의 이름 충돌을 피하기 위해 패키지 명명 규칙을 정의하여야 합니다.
이는 일반적으로 패키지가 속한 프로젝트 ID나 전체 프로젝트 경로를 패키지 이름에 사용하여 프로젝트를 식별할 수 있는 방법을 제공합니다.
예를 들어 Conan의 명명 규칙을 살펴보세요.

그룹 및 프로젝트 수준 엔드포인트의 경우, 명명은 덜 제약적일 수 있으며, 두 패키지 이름 간의 충돌이 없도록 하는 것은 그룹 및 프로젝트 구성원에 달려 있습니다. 그러나 시스템은 특정 범위 내에서 기존 이름 재사용을 방지해야 합니다.

그 외의 경우, 패키지 관리자의 명명 규칙을 따르고 해당 패키지 유형의 package.md 모델에서 유효성을 확인해야 합니다.

서비스 및 파인더

패키지나 패키지 파일 레코드를 만드는 등의 작업을 수행하는 로직이 API 파일에 살지 않고, 서비스 및 파인더에 존재하여야 합니다. 가능하다면 기존 서비스와 파인더를 사용하거나 확장하여 공통 패키지 논리를 최대한 그룹화해야 합니다.

구성

GitLab은 설정 파일(gitlab.rb 또는 gitlab.yml)에 packages 섹션을 가지고 있습니다. 이는 GitLab이 지원하는 모든 패키지 시스템에 적용됩니다. 일반적으로 여기에는 추가할 필요가 없습니다.

패키지는 개체 저장소를 사용하도록 구성될 수 있으므로 코드도 지원해야 합니다.

MVC 접근 방식

새로운 패키지 시스템이 GitLab에 통합되는 방식은 MVC를 사용합니다. 따라서 첫 번째 반복은 최소한의 사용자 동작을 지원해야 합니다:

• GitLab 작업과의 인증, 개인 액세스, 프로젝트 액세스 또는 배포 토큰
• 패키지 업로드와 사용자 인터페이스에서 기본 메타데이터 표시
• 패키지 다운로드
• 필요한 동작

필요한 동작은 GitLab이 해당 패키지 관리자 CLI가 올바르게 작동할 수 있도록 처리해야 하는 모든 추가 요청입니다. 검색 기능 또는 패키지에 대한 메타 정보를 제공하는 엔드포인트와 같을 수 있습니다.

예를 들어:

• NuGet의 경우, 첫 번째 MVC 반복에서 Visual Studio를 지원하기 위해 검색 요청을 구현했습니다.
• npm의 경우, npm이 tarball URL을 가져오기 위해 사용하는 메타데이터 엔드포인트가 있습니다.

첫 번째 MVC 반복에서는 원격 계층 프로젝트 수준에서만 작업하는 것이 권장됩니다. 다른 계층은 향후 병합 요청로 다룰 수 있습니다.

MVC에는 일반적으로 두 단계가 있습니다:

• 분석
• 구현

작은 단계로 유지

새로운 패키지 관리자를 구현할 때 기본 사용을 지원하기 위해 필요한 모든 엔드포인트와 서비스를 포함한 큰 병합 요청을 만드는 것이 유혹스러울 수 있습니다. 그 대신에:

1. API 엔드포인트를 기능 플래그 뒤에 둡니다.
2. 각 엔드포인트나 동작(다운로드, 업로드 등)을 다른 병합 요청으로 제출하여 검토 과정을 단축합니다.

분석

이 단계에서는 패키지 시스템에서 사용하는 API에 대한 최대한 많은 정보를 수집하는 것을 목표로 합니다. 여기에 포함될 수 있는 유용한 측면 몇 가지를 소개합니다:

• 인증: 사용 가능한 인증 메커니즘은 무엇입니까(OAuth, 기본 인증, 기타)? GitLab 사용자들은 자주 개인 액세스 토큰을 사용하고 싶어합니다.
  SVN은 MVC의 첫 번째 반복에는 필요하지 않지만, CI/CD 작업 토큰은 앞으로 언젠가 지원되어야 합니다.
• 요청: 작동하는 MVC에 필요한 요청은 무엇입니까? 이상적으로는 MVC에 필요한 모든 요청(필요한 동작 포함)의 목록을 작성하는 것이 좋습니다. 추가 조사를 통해 각 요청에 대한 예시 및 요청 및 응답 본문이 포함된 목록을 작성할 수 있습니다.
• 업로드: 업로드 프로세스가 어떻게 작동하는지 주의 깊게 분석합니다. 이 요청은 구현하기 가장 복잡할 것입니다. 여기에 상세한 분석이 필요합니다. 업로드는 다양한 방식으로 인코딩될 수 있습니다(본문 또는 멀티파트)하며 때로는 패키지 파일이 특정 필드의 Base64 값인 JSON 구조와 같은 완전히 다른 형식일 수도 있습니다. 이러한 다른 인코딩은 GitLab과 GitLab Workhorse에서 약간 다른 구현으로 이어질 수 있습니다. 더 자세한 정보는 파일 업로드를 참조하십시오.
• 엔드포인트: GitLab에 구현할 엔드포인트 URL 목록을 제안합니다.
• 작업 분리: MVC를 점진적으로 구축하기 위해 수행할 변경 작업 목록을 제안합니다. 이로써 어느 정도의 작업을 수행해야 하는지에 대한 좋은 아이디어를 얻을 수 있습니다. 이 항목은 케이스별로 조정되어야 하는 케이스별로 기반을 야합되어야 합니다:
  1. 파일 구조(이 패키지를 위한 API 파일, 기본 서비스)가 없는 상태
  2. 패키지 관리자에 대한 “로그인” 인증 시스템
  3. 메타데이터 식별 및 적용 가능한 테이블 만들기
  4. 개체 저장소 직접 업로드를 위한 Workhorse 경로
  5. 업로드/발행을 위해 필요한 엔드포인트
  6. 설치/다운로드를 위해 필요한 엔드포인트
  7. 필요한 동작을 위해 필요한 엔드포인트

분석은 보통 완전한 마일스톤을 소요하지만, 구현을 시작하는 것은 불가능하지는 않습니다.

특히, 업로드 요청에 대한 몇 가지 요구 사항이 GitLab Workhorse 프로젝트에 있을 수 있습니다. 이 프로젝트는 레일즈 백엔드보다 다른 릴리스 주기를 가지고 있습니다. 이러한 이유로 업로드 요청 분석이 완료되자마자 거기에 이슈를 오픈하는 것이 강력히 권장됩니다. 이렇게 하면 업로드 요청이 레일즈 백엔드에 구현될 때 GitLab Workhorse가 이미 준비가 되어 있습니다.

구현

다양한 병합 요청 구현은 서로 다른 패키지 시스템 통합에 따라 다릅니다. 기여자는 구현 단계의 몇 가지 중요한 측면을 고려해야 합니다.

인증

MVC는 개인 액세스 토큰을 처음부터 지원해야 합니다. 이러한 토큰에 대해 OAuth와 기본 액세스 두 가지 옵션을 지원합니다.

OAuth 인증은 이미 지원되고 있습니다. npm API 예제에서 확인할 수 있습니다.

기본 액세스 인증은 API 도우미에서 특정 함수를 오버라이드하여 지원됩니다. Conan API의 예를 참고하세요. 이 인증 메커니즘의 경우, 일부 클라이언트는 인증되지 않은 요청을 먼저 보낸 후, WWW-Authenticate 필드가 포함된 401 Unauthorized 응답을 기다린 다음 업데이트된(인증된) 요청을 보낼 수 있습니다. 이 경우 GitLab은 401 Unauthorized 응답을 처리해야 합니다. NuGet API는 이 경우를 지원합니다.

권한 부여

프로젝트 권한과 그룹 권한은 read_package, create_package, destroy_package에 대해 존재합니다. 각 엔드포인트는 계속하기 전에 프로젝트나 그룹에 대해 요청한 사용자를 권한 부여해야 합니다.

데이터베이스 및 메타데이터 처리

현재 데이터베이스 모델을 사용하여 각 패키지의 이름과 버전을 저장할 수 있습니다. 새로운 패키지를 업로드할 때마다 Package의 새 레코드를 만들거나 기존 레코드에 파일을 추가할 수 있습니다. PackageFile은 파일 이름, 사이즈, sha1 등과 같은 모든 파일 관련 정보를 저장할 수 있어야 합니다.

특정 패키지 시스템 지원에만 저장해야 하는 특정 데이터가 있는 경우 별도의 메타데이터 모델을 만들어야 합니다. 패키지별 데이터의 예로 packages_maven_metadata 테이블과 Packages::Maven::Metadatum 모델, 그리고 패키지 파일별 데이터의 예로 packages_conan_file_metadata 테이블과 Packages::Conan::FileMetadatum 모델을 참고하세요.

특정 패키지 관리자에 대한 패키지별 동작이 있는 경우 해당 메서드를 메타데이터 모델에 추가하고 패키지 모델에서 델리게이션하세요.

기존 패키지 UI는 packages_packages 및 packages_package_files 테이블에있는 정보 만 표시합니다. 메타데이터 테이블에 저장된 데이터를 표시해야하는 경우 ~frontend 변경이 필요합니다.

파일 업로드

파일 업로드는 GitLab Workhorse를 사용하여 처리되어야 합니다. 이것은 작업 말단 프록시가 GitLab로 들어오는 모든 요청을 확인하고 업로드 요청을 가로채고 파일을 업로드한 다음 파일 자체가 아닌 메타데이터 및 파일 위치만을 포함하는 주요 GitLab 코드베이스로 요청을 전달해야 함을 의미합니다. 이 프로세스 개요는 개발 문서에서 찾을 수 있습니다.

코드 측면에서, 이는 각 업로드 엔드포인트(인스턴스, 그룹, 프로젝트)에 대한 GitLab Workhorse 프로젝트에 경로를 추가해야 함을 의미합니다. 이 마지막 예제에서 Conan을 위해 작업말 프록시에 인스턴스 수준 엔드포인트를 추가하는 것을 볼 수 있습니다. 같은 파일에서 구현된 Maven 프로젝트 레벨 엔드포인트도 확인할 수 있습니다.

경로를 추가한 후에 API 파일에 추가적인 /authorize 버전의 업로드 엔드포인트를 추가해야 합니다. 이 예제에서 Maven을 위해 추가된 엔드포인트를 볼 수 있습니다. /authorize 엔드포인트는 Workhorse로부터의 요청을 확인하고 인가한 후 일반적인 업로드 엔드포인트가 아래에 구현되어 Workhorse가 제공하는 메타데이터를 사용하여 패키지 레코드를 생성합니다. Workhorse는 유형, 크기, 다양한 체크섬 형식과 같은 다양한 파일 메타데이터를 제공합니다.

테스트 목적으로 로컬 개발 환경에서 객체 저장소를 활성화할 수도 있습니다.

파일 크기 제한

GitLab 패키지 레지스트리에 업로드된 파일은 형식별로 제한됩니다. GitLab.com에서는 일반적으로 타임아웃 문제 및 남용을 방지하기 위해 5GB로 설정됩니다.

새로운 패키지 유형이 Packages::Package 모델에 추가되면 이 예와 유사한 크기 제한이 추가되어야 합니다. 파일 크기 제한이 적용되지 않는 경우 관련 테스트를 업데이트해야 합니다. 파일 크기 제한이 적용되지 않는 유일한 이유는 패키지 형식이 파일을 업로드 및 저장하지 않는 경우뿐입니다.

GitLab.com의 요청 속도 제한

패키지 관리자 클라이언트는 GitLab.com 특정 API 속도 제한을 초과하는 빠른 요청을 수행할 수 있습니다. 이로 인해 429 Too Many Requests 오류가 발생합니다.

우리는 높은 요청 속도를 허용하기 위해 일련의 경로를 열었습니다. 가능하다면 새로운 패키지 관리자는 이러한 관습을 따라야 하므로 확장된 패키지 속도 제한을 활용할 수 있습니다.

이 경로 접두어는 더 높은 요청 속도를 보장합니다:

/api/v4/packages/
/api/v4/projects/:project_id/packages/
/api/v4/groups/:group_id/-/packages/

MVC 체크리스트

새로운 패키지 관리자를 위해 GitLab에 지원을 추가할 때, 첫 번째 이터레이션에 다음 기능들이 포함되어야 합니다. 필요에 따라 여러 병합 요청을 통해 기능을 추가할 수 있지만, 피쳐 플래그가 제거될 때 모든 기능이 구현되어 있어야 합니다.

• 프로젝트 수준 API
• 푸시 이벤트 추적
• 풀 이벤트 추적
• 개인 액세스 토큰을 사용한 인증
• Job 토큰을 사용한 인증
• 배포 토큰을 사용한 인증 (그룹 및 프로젝트)
• 파일 크기 제한
• 파일 형식 가드 (패키지 유형에 대해 유효한 파일 형식만 허용)
• 유효성을 갖춘 이름 정규식
• 유효성을 갖춘 버전 정규식
• 가속화된 업로드를 위한 Workhorse 경로
• 패키지 메타데이터 추출을 위한 백그라운드 워커 (적용 가능한 경우)
• 문서 (기능 사용 방법)
• API 문서 (curl 예제와 개별 엔드포인트)
• db/fixtures/development/26_packages.rb에 시딩
• 그라파나 차트를 위한 런북 업데이트
• 엔드-투-엔드 기능 테스트 (최소한 패키지 공개 및 설치)

향후 작업

MVC 작업 중에 기여자들은 MVC에 필수가 아니지만 사용자 경험을 향상시킬 수 있는 기능을 발견할 수 있습니다. 일반적으로 이러한 기능을 주시하고 이슈를 오픈하는 것이 좋은 아이디어입니다.

다음은 몇 가지 예시입니다.

1. 검색에 필요한 엔드포인트
2. 추가 패키지 정보 및 메타데이터를 표시하기 위한 프론트엔드 업데이트
3. 파일 크기 제한
4. 메트릭 추적
5. 패키지에서 더 많은 메타데이터 필드를 읽어와 프론트엔드에서 사용할 수 있도록 함. 예를 들어, 패키지에 태그를 달 수 있는 것이 일반적입니다. 이러한 태그는 백엔드에서 읽혀 저장되어 패키지 UI에서 표시될 수 있습니다.
6. 원격 계층구조의 상위 수준을 위한 엔드포인트. 이 단계에서는 네이밍 규칙을 생성해야 할 수도 있습니다.

예외

본 문서는 기존 구조와 논리와 일치하는 패키지 관리자를 구현하는 방법에 대한 지침일 뿐입니다. 구조는 어떠한 패키지 관리자에도 대응할 수 있도록 확장 가능하고 유연하게 의도되었지만, 특정 패키지 관리자의 제약 사항 또는 요구 사항으로 인해 벗어나야 하는 합당한 이유가 있다면, 이러한 사항은 구현 이슈나 병합 요청에서 제기되어 가장 효율적인 결과를 위해 논의되어야 합니다.