새 패키지 형식 지원 개발

이 문서는 GitLab에 패키지 관리 시스템을 추가하는 방법을 안내합니다.

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

백엔드 변경만으로도 새 형식을 추가할 수 있습니다. 이 안내서는 겉으로만 보고 코드 작성 방법을 다루지 않습니다. 하지만, 다음 Merge Request을 참고할 수 있습니다.

일반 정보

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

  • 모든 패키지는 프로젝트에 속합니다.
  • 모든 패키지 파일은 패키지에 속합니다.
  • 패키지에는 하나 이상의 패키지 파일이 포함될 수 있습니다.
  • 패키지 모델은 패키지와 해당 버전에 관한 정보를 저장합니다.

API 엔드포인트

패키지 시스템은 GitLab과 API를 통해 작동합니다. 예를 들어 lib/api/npm_project_packages.rb은 npm 클라이언트와 작동하기 위한 API 엔드포인트를 구현합니다. 따라서 패키지 시스템 클라이언트가 작동하는 데 필요한 새 lib/api/your_name_project_packages.rb 파일을 추가해야 합니다. 보통 다음과 같은 엔드포인트가 필요합니다.

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

패키지가 프로젝트에 속하기 때문에, 프로젝트 수준(원격)의 엔드포인트(을)를 배포하여 패키지를 업로드 및 다운로드할 수 있어야 합니다. 예를 들어: 

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로써, 우리는 프로젝트 수준 엔드포인트로 시작하는 것을 권장합니다. 원격 계층에 대한 전형적인 반복 계획은 다음과 같습니다:

  • 프로젝트에서 발행 및 설치
  • 그룹에서 설치
  • 인스턴스에서 발행 및 설치(Self-Managed형 고객용)

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

네이밍 규칙

인스턴스 수준 엔드포인트에서 이름 충돌을 피하기 위해, 패키지 네이밍 규칙을 정의해야 합니다. 이는 일반적으로 패키지가 속한 프로젝트를 식별할 수 있는 방법을 제공하여야 한다. 대개 프로젝트 ID나 전체 프로젝트 경로를 사용하는 것을 포함합니다. Conan의 네이밍 규칙을 참고하세요.

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

그 외에도, 네이밍은 패키지 관리자의 네이밍 규칙을 따라야 하며, 해당 패키지 유형에 대한package.md 모델에서 유효성 검사를 포함해야 합니다.

서비스 및 파인더

패키지나 패키지 파일 레코드를 생성하거나 패키지를 찾는 등의 작업을 수행하는 논리는 API 파일에 존재해서는 안 되지만, 서비스와 파인더에 존재하여야 합니다. 가능한 경우 기존 서비스와 파인더를 사용하거나 확장하여 공통 패키지 논리를 최대한 그룹화해야합니다.

설정

GitLab은 구성 파일(gitlab.rb 또는 gitlab.yml)에 packages 섹션을 갖고 있습니다. 이는 GitLab에서 지원하는 모든 패키지 시스템에 적용됩니다. 보통 여기에 추가해야 할 것은 없습니다.

패키지는 객체 리포지터리를 사용하도록 구성될 수 있으므로, 코드는 이를 지원해야 합니다.

MVC 방식

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

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

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

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

첫 번째 MVC 반복에서는 원격 계층의 프로젝트 수준에 머물 것을 권장합니다. 다른 수준은 미래의 Merge Request으로 처리할 수 있습니다.

일반적으로 MVC는 두 단계로 구성됩니다:

작은 단위로 반복 유지

새 패키지 관리자를 구현할 때, 기본 사용을 지원하는 데 필요한 모든 엔드포인트와 서비스를 포함하는 큰 Merge Request을 생성하는 것이 유혹적일 수 있습니다. 대신에:

  1. API 엔드포인트를 피처 플래그 뒤에 둡니다.
  2. 각 엔드포인트 또는 동작(다운로드, 업로드 등)을 다른 Merge Request으로 제출하여 리뷰 프로세스를 단축합니다.

분석

이 단계에서는 패키지 시스템에서 사용되는 API에 관해 가능한 많은 정보를 수집하는 것이 목적입니다. 여기에는 다음과 같은 측면이 유용할 수 있습니다:

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

분석은 일반적으로 완료되기까지 한 마일스톤이 소요되지만, 구현을 동시에 시작하는 것이 불가능한 것은 아닙니다.

특히, 업로드 요청은 GitLab Workhorse 프로젝트에서 일부 요구 사항을 가질 수 있습니다. 이 프로젝트는 Rails 백엔드와는 다른 릴리스 주기를 갖고 있습니다. 따라서, 업로드 요청 분석이 완료되면, 강력하게 권장하고 릴리즈 사이클이 다른 GitLab Workhorse에 이미 준비되어 있도록 하기 위해 이슈를 즉시 열어야 합니다.

Future Work Overview

**에 대한 작업 계획

https://gitlab.com/gitlab-org/gitlab-foss/-/wikis/ Acknowledgements GitLab Documentation Team 2022.

구현

다양한 Merge Request(Merge Requests)의 구현은 다른 패키지 시스템 통합에 따라 다릅니다. 기여자들은 구현 단계의 몇 가지 중요한 측면을 고려해야 합니다.

인증

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

OAuth 인증은 이미 지원되고 있습니다. npm API의 예시를 볼 수 있습니다.

기본 액세스 인증은 API 도우미의 특정 기능을 무시함으로써 지원됩니다. Conan API의 경우를 보세요. 이러한 인증 메커니즘의 경우, 일부 클라이언트는 인증되지 않은 요청을 먼저 보낼 수 있고, 401 Unauthorized 응답과 함께 WWW-Authenticate 필드를 받은 후 업데이트된(인증된) 요청을 보낼 수 있습니다. GitLab은 401 Unauthorized 응답을 처리해야 하므로 이 경우가 더 복잡합니다. NuGet API가 이러한 경우를 지원합니다.

권한

프로젝트 및 그룹 레벨 권한은 read_package, create_package, destroy_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를 사용하여 처리되어야 합니다. 즉, Workhorse 프록시는 GitLab로의 모든 들어오는 요청을 확인하여 업로드 요청을 가로채고, 파일을 업로드한 후 파일 자체가 아닌 메타데이터 및 파일 위치만 포함된 주요 GitLab 코드베이스에 요청을 전달해야 합니다. 이 프로세스에 대한 개요는 개발 문서에서 찾을 수 있습니다.

코드 측면에서, 이는 각 업로드 엔드포인트에 대한 GitLab Workhorse 프로젝트에 경로를 추가해야 한다는 것을 의미합니다. 이 MR(Merge Request)는 Conan을 위한 인스턴스 레벨 엔드포인트를 Workhorse에 추가하는 것을 보여줍니다. 동일한 파일에서 구현된 Maven 프로젝트 레벨 엔드포인트도 볼 수 있습니다.

경로가 추가된 후, API 파일에 추가적인 /authorize 버전의 업로드 엔드포인트를 추가해야 합니다. 이 예시는 Maven을 위해 추가된 추가 엔드포인트를 보여줍니다. /authorize 엔드포인트는 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에 대한 지원을 추가할 때, 첫 번째 반복은 다음 기능을 포함해야 합니다. 필요에 따라 여러 개의 Merge Request을 통해 기능을 추가할 수 있지만, 피처 플래그가 제거될 때 모든 기능이 구현되어 있어야 합니다.

  • 프로젝트 레벨 API
  • Push 이벤트 추적
  • Pull 이벤트 추적
  • 개인 액세스 토큰을 사용한 인증
  • Job 토큰을 사용한 인증
  • 배포 토큰을 사용한 인증 (그룹 및 프로젝트)
  • 파일 크기 제한
  • 파일 형식 가드(패키지 유형에 대해 유효한 파일 형식만 허용)
  • 검증을 포함한 이름 정규식
  • 검증을 포함한 버전 정규식
  • 가속화된 업로드를 위한 Workhorse 라우트
  • 패키지 메타데이터를 추출하는 백그라운드 워커(해당하는 경우)
  • 문서(기능 사용 방법)
  • API 문서(Curl 예제를 포함한 개별 엔드포인트)
  • db/fixtures/development/26_packages.rb에 묘화 데이터(seeding)
  • Grafana 차트용 런북 업데이트
  • (최소한) 패키지 게시 및 설치에 대한 종단간 기능 테스트

향후 작업

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

다음은 일부 예시입니다

  1. 검색에 필요한 엔드포인트
  2. 추가적인 패키지 정보 및 메타데이터를 표시하기 위한 프론트엔드 업데이트
  3. 파일 크기 제한
  4. 지표 추적
  5. 패키지에서 더 많은 메타데이터 필드 읽기. 예를 들어 패키지에 태그를 지정할 수 있다면, 해당 태그는 백엔드에서 읽고 저장한 후 패키지 UI에 표시될 수 있습니다.
  6. 원격 계층의 상위 수준을 위한 엔드포인트. 이 단계는 이름짓기 규칙을 생성하는 것을 필요로 할 수 있습니다

예외

이 설명서는 기존 GitLab의 구조와 로직에 맞는 패키지 관리자를 구현하는 지침일 뿐입니다. 이 구조는 일반적인 패키지 관리자를 허용할 수 있을 만큼 확장 가능하고 유연하도록 의도되었지만, 특정 패키지 관리자의 제약 조건이나 요구 사항으로 인해 벗어나야 하는 좋은 이유가 있다면, 가장 효율적인 결과를 위해 구현 이슈나 Merge Request에서 제기하고 논의되어야 합니다.