InfoGrab DocsInfoGrab Docs

새 패키지 형식 개발

요약

이 문서는 새로운 패키지 관리 시스템에 대한 지원을 GitLab에 추가하는 방법을 안내합니다. 이미 지원되는 형식은 패키지 및 레지스트리 문서에서 확인할 수 있습니다. 새 형식은 백엔드 변경만으로 추가할 수 있습니다. Maven 리포지터리의 인스턴스 수준 API

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

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

새 형식은 백엔드 변경만으로 추가할 수 있습니다. 이 가이드는 개략적이며 코드를 작성하는 방식을 구체적으로 다루지 않습니다. 하지만 다음 머지 리퀘스트를 통해 좋은 예시를 찾을 수 있습니다:

일반 정보#

기존 데이터베이스 모델에는 다음 조건이 필요합니다:

  • 모든 패키지는 프로젝트에 속합니다.

  • 모든 패키지 파일은 패키지에 속합니다.

  • 패키지는 하나 이상의 패키지 파일을 가질 수 있습니다.

  • 패키지 모델은 패키지와 해당 버전에 대한 정보를 저장하는 것을 기반으로 합니다.

API 엔드포인트#

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

  • GET 패키지 정보.

  • GET 패키지 파일 콘텐츠.

  • 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 고객용)

인스턴스 수준 엔드포인트를 사용하려면 더 엄격한 명명 규칙이 필요합니다.

Composer 패키지 명명 범위는 인스턴스 수준입니다.

명명 규칙#

인스턴스 수준 엔드포인트에서 이름 충돌을 방지하려면 패키지가 속한 프로젝트를 식별할 수 있는 패키지 명명 규칙을 정의해야 합니다. 이는 일반적으로 패키지 이름에 프로젝트 ID나 전체 프로젝트 경로를 사용하는 방식입니다. 예시가 포함된 자세한 내용은 인스턴스 리모트에 대한 패키지 레시피 명명 규칙을 참고하세요.

그룹 및 프로젝트 수준 엔드포인트의 경우 명명 제약이 덜하며, 그룹 및 프로젝트 구성원이 두 패키지 이름 간의 충돌이 없도록 확인하면 됩니다. 하지만 시스템은 사용자가 주어진 범위 내에서 기존 이름을 재사용하는 것을 방지해야 합니다.

그 외에는 패키지 관리자의 명명 규칙을 따르고 해당 패키지 유형의 package.md 모델에 유효성 검사를 포함해야 합니다.

서비스 및 파인더#

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

구성#

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

패키지는 오브젝트 스토리지를 사용하도록 구성할 수 있으므로, 코드가 이를 지원해야 합니다.

MVC 접근 방식#

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

  • GitLab job 토큰, 개인 액세스 토큰, 프로젝트 액세스 토큰 또는 배포 토큰을 통한 인증

  • 패키지 업로드 및 사용자 인터페이스에서 기본 메타데이터 표시

  • 패키지 가져오기

  • 필수 작업

필수 작업은 GitLab이 처리해야 하는 모든 추가 요청으로, 해당 패키지 관리자 CLI가 올바르게 작동할 수 있도록 합니다. 검색 기능이나 패키지에 대한 메타 정보를 제공하는 엔드포인트일 수 있습니다. 예를 들어:

  • NuGet의 경우, Visual Studio를 지원하기 위해 첫 번째 MVC 반복에서 검색 요청이 구현되었습니다.

  • npm의 경우, npm이 타볼 URL을 가져오는 데 사용하는 메타데이터 엔드포인트가 있습니다.

첫 번째 MVC 반복에서는 리모트 계층 구조의 프로젝트 수준에 머무르는 것을 권장합니다. 다른 수준은 향후 머지 리퀘스트로 처리할 수 있습니다.

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

반복을 작게 유지하기#

새 패키지 관리자를 구현할 때 기본 사용에 필요한 모든 엔드포인트와 서비스를 포함하는 하나의 큰 머지 리퀘스트를 만들고 싶어지는 경향이 있습니다. 대신 다음을 권장합니다:

  • API 엔드포인트를 기능 플래그 뒤에 배치합니다.

  • 리뷰 프로세스를 단축하기 위해 각 엔드포인트나 동작(다운로드, 업로드 등)을 서로 다른 머지 리퀘스트로 제출합니다.

분석#

이 단계에서는 패키지 시스템이 사용하는 API에 대해 가능한 한 많은 정보를 수집하는 것이 목표입니다. 다음과 같은 측면을 포함하면 유용합니다:

  • 인증: 어떤 인증 메커니즘을 사용할 수 있는지(OAuth, Basic Authorization, 기타). GitLab 사용자들은 종종 개인 액세스 토큰을 사용하고 싶어 한다는 점을 기억하세요. MVC 첫 번째 반복에서는 필요하지 않더라도, CI/CD job 토큰은 나중에 지원되어야 합니다.

  • 요청: 작동하는 MVC를 위해 필요한 요청이 무엇인지. 이상적으로는 MVC에 필요한 모든 요청 목록(필수 작업 포함)을 작성하고, 추가 조사를 통해 각 요청의 요청 및 응답 본문 예시를 제공합니다.

  • 업로드: 업로드 프로세스의 작동 방식을 신중하게 분석합니다. 이 요청은 구현하기 가장 복잡할 가능성이 높습니다. 업로드는 다양한 방식(body 또는 multipart)으로 인코딩될 수 있으며, 완전히 다른 형식(예: 패키지 파일이 특정 필드의 Base64 값인 JSON 구조)일 수도 있기 때문에 상세한 분석이 필요합니다. 이러한 다양한 인코딩 방식으로 인해 GitLab과 GitLab Workhorse에서의 구현이 약간씩 달라집니다. 자세한 정보는 파일 업로드를 검토하세요.

  • 엔드포인트: GitLab에 구현할 엔드포인트 URL 목록을 제안합니다.

  • 작업 분할: MVC를 점진적으로 구축하기 위한 변경 사항 목록을 제안합니다. 이를 통해 수행해야 할 작업의 양을 파악할 수 있습니다. 다음은 사례에 따라 조정해야 하는 예시 목록입니다:

빈 파일 구조 (API 파일, 이 패키지의 기본 서비스)

  • 패키지 관리자에 "로그인"하기 위한 인증 시스템

  • 메타데이터 식별 및 해당 테이블 생성

  • 오브젝트 스토리지 다이렉트 업로드를 위한 Workhorse 라우트

  • 업로드/게시에 필요한 엔드포인트

  • 설치/다운로드에 필요한 엔드포인트

  • 필수 작업에 필요한 엔드포인트

분석에는 보통 전체 마일스톤이 소요되지만, 같은 마일스톤 내에서 구현을 시작하는 것이 불가능하지는 않습니다.

특히 업로드 요청은 GitLab Workhorse 프로젝트에 요구사항이 있을 수 있습니다. 이 프로젝트는 Rails 백엔드와 다른 릴리즈 주기를 가집니다. 업로드 요청 분석이 완료되는 즉시 해당 프로젝트에 이슈를 열 것을 강력히 권장합니다. 이렇게 하면 Rails 백엔드에서 업로드 요청을 구현할 때 GitLab Workhorse가 이미 준비되어 있을 것입니다.

구현#

다양한 머지 리퀘스트의 구현 방식은 패키지 시스템 통합마다 다릅니다. 기여자들은 구현 단계의 몇 가지 중요한 측면을 고려해야 합니다.

인증#

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

OAuth 인증은 이미 지원됩니다. npm API에서 예시를 확인할 수 있습니다.

Basic Access 인증 지원은 Conan API의 이 예시처럼 API 헬퍼의 특정 함수를 오버라이드하여 구현합니다. 이 인증 메커니즘에서는 일부 클라이언트가 먼저 인증되지 않은 요청을 보내고, WWW-Authenticate 필드가 포함된 401 Unauthorized 응답을 기다린 후, 업데이트된(인증된) 요청을 보낼 수 있다는 점을 기억하세요. 이 경우 GitLab이 401 Unauthorized 응답을 처리해야 하므로 더 복잡합니다. NuGet API에서 이 경우를 지원합니다.

인가#

read_package, create_package, destroy_package에 대한 프로젝트 권한과 그룹 권한이 있습니다. 각 엔드포인트는 계속 진행하기 전에 프로젝트나 그룹에 대해 요청하는 사용자를 인가해야 합니다.

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

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

하나의 패키지 시스템 지원에만 필요한 특정 데이터를 저장해야 하는 경우, 별도의 메타데이터 모델 생성을 고려하세요. 패키지별 데이터의 예시로 packages_maven_metadata 테이블과 Packages::Maven::Metadatum 모델을, 패키지 파일별 데이터의 예시로 packages_conan_file_metadata 테이블과 Packages::Conan::FileMetadatum 모델을 참고하세요.

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

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

파일 업로드#

파일 업로드는 오브젝트 가속 업로드를 사용하여 GitLab Workhorse가 처리해야 합니다. 즉, GitLab에 들어오는 모든 요청을 확인하는 workhorse 프록시가 업로드 요청을 가로채서 파일을 업로드하고, 파일 자체가 아닌 메타데이터와 파일 위치만 포함하는 요청을 메인 GitLab 코드베이스에 전달합니다. 이 프로세스의 개요는 개발 문서에서 확인할 수 있습니다.

코드 측면에서, 이는 추가되는 각 업로드 엔드포인트(인스턴스, 그룹, 프로젝트)에 대해 GitLab Workhorse 프로젝트에 라우트를 추가해야 함을 의미합니다. 이 머지 리퀘스트는 workhorse에 Conan의 인스턴스 수준 엔드포인트를 추가하는 방법을 보여줍니다. 동일한 파일에서 구현된 Maven 프로젝트 수준 엔드포인트도 확인할 수 있습니다.

라우트가 추가된 후에는 API 파일에 업로드 엔드포인트의 추가 /authorize 버전을 추가해야 합니다. 이 예시는 Maven에 추가된 추가 엔드포인트를 보여줍니다. /authorize 엔드포인트는 workhorse의 요청을 검증하고 인가한 다음, 일반적인 업로드 엔드포인트가 아래에 구현되어 Workhorse가 제공하는 메타데이터를 소비하여 패키지 레코드를 생성합니다. Workhorse는 유형, 크기, 다양한 체크섬 형식과 같은 다양한 파일 메타데이터를 제공합니다.

테스트 목적으로, 로컬 개발 환경에서 오브젝트 스토리지를 활성화할 수 있습니다.

파일 크기 제한#

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

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에 시딩

  • Grafana 차트용 런북 업데이트

  • (최소한) 패키지 게시 및 설치에 대한 엔드투엔드 기능 테스트

향후 작업#

MVC를 진행하는 동안 기여자들은 MVC에 필수적이지는 않지만 더 나은 사용자 경험을 제공할 수 있는 기능을 발견할 수 있습니다. 이러한 기능에 주의를 기울이고 이슈를 여는 것이 일반적으로 좋은 생각입니다.

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

  • 검색에 필요한 엔드포인트

  • 추가 패키지 정보 및 메타데이터를 표시하기 위한 프런트엔드 업데이트

  • 파일 크기 제한

  • 메트릭 추적

  • 패키지에서 더 많은 메타데이터 필드를 읽어 프런트엔드에서 사용할 수 있도록 합니다. 예를 들어, 패키지에 태그를 지정할 수 있는 것이 일반적입니다. 해당 태그는 백엔드에서 읽고 저장한 다음 패키지 UI에 표시할 수 있습니다.

  • 리모트 계층 구조의 상위 수준에 대한 엔드포인트. 이 단계에서는 명명 규칙을 만들어야 할 수 있습니다.

예외#

이 문서는 GitLab에 이미 존재하는 구조와 로직에 맞게 패키지 관리자를 구현하는 방법에 대한 가이드라인일 뿐입니다. 구조는 어떤 패키지 관리자도 수용할 수 있을 만큼 확장 가능하고 유연하도록 의도되었지만, 특정 패키지 관리자의 제약이나 요구사항으로 인해 벗어날 타당한 이유가 있다면, 가장 효율적인 결과를 위해 구현 이슈 또는 머지 리퀘스트에서 제기하고 논의해야 합니다.

새 패키지 형식 개발

GitLab v19.1
원문 보기
요약

이 문서는 새로운 패키지 관리 시스템에 대한 지원을 GitLab에 추가하는 방법을 안내합니다. 이미 지원되는 형식은 패키지 및 레지스트리 문서에서 확인할 수 있습니다. 새 형식은 백엔드 변경만으로 추가할 수 있습니다. Maven 리포지터리의 인스턴스 수준 API

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

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

새 형식은 백엔드 변경만으로 추가할 수 있습니다. 이 가이드는 개략적이며 코드를 작성하는 방식을 구체적으로 다루지 않습니다. 하지만 다음 머지 리퀘스트를 통해 좋은 예시를 찾을 수 있습니다:

일반 정보#

기존 데이터베이스 모델에는 다음 조건이 필요합니다:

  • 모든 패키지는 프로젝트에 속합니다.

  • 모든 패키지 파일은 패키지에 속합니다.

  • 패키지는 하나 이상의 패키지 파일을 가질 수 있습니다.

  • 패키지 모델은 패키지와 해당 버전에 대한 정보를 저장하는 것을 기반으로 합니다.

API 엔드포인트#

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

  • GET 패키지 정보.

  • GET 패키지 파일 콘텐츠.

  • 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 고객용)

인스턴스 수준 엔드포인트를 사용하려면 더 엄격한 명명 규칙이 필요합니다.

Composer 패키지 명명 범위는 인스턴스 수준입니다.

명명 규칙#

인스턴스 수준 엔드포인트에서 이름 충돌을 방지하려면 패키지가 속한 프로젝트를 식별할 수 있는 패키지 명명 규칙을 정의해야 합니다. 이는 일반적으로 패키지 이름에 프로젝트 ID나 전체 프로젝트 경로를 사용하는 방식입니다. 예시가 포함된 자세한 내용은 인스턴스 리모트에 대한 패키지 레시피 명명 규칙을 참고하세요.

그룹 및 프로젝트 수준 엔드포인트의 경우 명명 제약이 덜하며, 그룹 및 프로젝트 구성원이 두 패키지 이름 간의 충돌이 없도록 확인하면 됩니다. 하지만 시스템은 사용자가 주어진 범위 내에서 기존 이름을 재사용하는 것을 방지해야 합니다.

그 외에는 패키지 관리자의 명명 규칙을 따르고 해당 패키지 유형의 package.md 모델에 유효성 검사를 포함해야 합니다.

서비스 및 파인더#

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

구성#

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

패키지는 오브젝트 스토리지를 사용하도록 구성할 수 있으므로, 코드가 이를 지원해야 합니다.

MVC 접근 방식#

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

  • GitLab job 토큰, 개인 액세스 토큰, 프로젝트 액세스 토큰 또는 배포 토큰을 통한 인증

  • 패키지 업로드 및 사용자 인터페이스에서 기본 메타데이터 표시

  • 패키지 가져오기

  • 필수 작업

필수 작업은 GitLab이 처리해야 하는 모든 추가 요청으로, 해당 패키지 관리자 CLI가 올바르게 작동할 수 있도록 합니다. 검색 기능이나 패키지에 대한 메타 정보를 제공하는 엔드포인트일 수 있습니다. 예를 들어:

  • NuGet의 경우, Visual Studio를 지원하기 위해 첫 번째 MVC 반복에서 검색 요청이 구현되었습니다.

  • npm의 경우, npm이 타볼 URL을 가져오는 데 사용하는 메타데이터 엔드포인트가 있습니다.

첫 번째 MVC 반복에서는 리모트 계층 구조의 프로젝트 수준에 머무르는 것을 권장합니다. 다른 수준은 향후 머지 리퀘스트로 처리할 수 있습니다.

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

반복을 작게 유지하기#

새 패키지 관리자를 구현할 때 기본 사용에 필요한 모든 엔드포인트와 서비스를 포함하는 하나의 큰 머지 리퀘스트를 만들고 싶어지는 경향이 있습니다. 대신 다음을 권장합니다:

  • API 엔드포인트를 기능 플래그 뒤에 배치합니다.

  • 리뷰 프로세스를 단축하기 위해 각 엔드포인트나 동작(다운로드, 업로드 등)을 서로 다른 머지 리퀘스트로 제출합니다.

분석#

이 단계에서는 패키지 시스템이 사용하는 API에 대해 가능한 한 많은 정보를 수집하는 것이 목표입니다. 다음과 같은 측면을 포함하면 유용합니다:

  • 인증: 어떤 인증 메커니즘을 사용할 수 있는지(OAuth, Basic Authorization, 기타). GitLab 사용자들은 종종 개인 액세스 토큰을 사용하고 싶어 한다는 점을 기억하세요. MVC 첫 번째 반복에서는 필요하지 않더라도, CI/CD job 토큰은 나중에 지원되어야 합니다.

  • 요청: 작동하는 MVC를 위해 필요한 요청이 무엇인지. 이상적으로는 MVC에 필요한 모든 요청 목록(필수 작업 포함)을 작성하고, 추가 조사를 통해 각 요청의 요청 및 응답 본문 예시를 제공합니다.

  • 업로드: 업로드 프로세스의 작동 방식을 신중하게 분석합니다. 이 요청은 구현하기 가장 복잡할 가능성이 높습니다. 업로드는 다양한 방식(body 또는 multipart)으로 인코딩될 수 있으며, 완전히 다른 형식(예: 패키지 파일이 특정 필드의 Base64 값인 JSON 구조)일 수도 있기 때문에 상세한 분석이 필요합니다. 이러한 다양한 인코딩 방식으로 인해 GitLab과 GitLab Workhorse에서의 구현이 약간씩 달라집니다. 자세한 정보는 파일 업로드를 검토하세요.

  • 엔드포인트: GitLab에 구현할 엔드포인트 URL 목록을 제안합니다.

  • 작업 분할: MVC를 점진적으로 구축하기 위한 변경 사항 목록을 제안합니다. 이를 통해 수행해야 할 작업의 양을 파악할 수 있습니다. 다음은 사례에 따라 조정해야 하는 예시 목록입니다:

빈 파일 구조 (API 파일, 이 패키지의 기본 서비스)

  • 패키지 관리자에 "로그인"하기 위한 인증 시스템

  • 메타데이터 식별 및 해당 테이블 생성

  • 오브젝트 스토리지 다이렉트 업로드를 위한 Workhorse 라우트

  • 업로드/게시에 필요한 엔드포인트

  • 설치/다운로드에 필요한 엔드포인트

  • 필수 작업에 필요한 엔드포인트

분석에는 보통 전체 마일스톤이 소요되지만, 같은 마일스톤 내에서 구현을 시작하는 것이 불가능하지는 않습니다.

특히 업로드 요청은 GitLab Workhorse 프로젝트에 요구사항이 있을 수 있습니다. 이 프로젝트는 Rails 백엔드와 다른 릴리즈 주기를 가집니다. 업로드 요청 분석이 완료되는 즉시 해당 프로젝트에 이슈를 열 것을 강력히 권장합니다. 이렇게 하면 Rails 백엔드에서 업로드 요청을 구현할 때 GitLab Workhorse가 이미 준비되어 있을 것입니다.

구현#

다양한 머지 리퀘스트의 구현 방식은 패키지 시스템 통합마다 다릅니다. 기여자들은 구현 단계의 몇 가지 중요한 측면을 고려해야 합니다.

인증#

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

OAuth 인증은 이미 지원됩니다. npm API에서 예시를 확인할 수 있습니다.

Basic Access 인증 지원은 Conan API의 이 예시처럼 API 헬퍼의 특정 함수를 오버라이드하여 구현합니다. 이 인증 메커니즘에서는 일부 클라이언트가 먼저 인증되지 않은 요청을 보내고, WWW-Authenticate 필드가 포함된 401 Unauthorized 응답을 기다린 후, 업데이트된(인증된) 요청을 보낼 수 있다는 점을 기억하세요. 이 경우 GitLab이 401 Unauthorized 응답을 처리해야 하므로 더 복잡합니다. NuGet API에서 이 경우를 지원합니다.

인가#

read_package, create_package, destroy_package에 대한 프로젝트 권한과 그룹 권한이 있습니다. 각 엔드포인트는 계속 진행하기 전에 프로젝트나 그룹에 대해 요청하는 사용자를 인가해야 합니다.

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

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

하나의 패키지 시스템 지원에만 필요한 특정 데이터를 저장해야 하는 경우, 별도의 메타데이터 모델 생성을 고려하세요. 패키지별 데이터의 예시로 packages_maven_metadata 테이블과 Packages::Maven::Metadatum 모델을, 패키지 파일별 데이터의 예시로 packages_conan_file_metadata 테이블과 Packages::Conan::FileMetadatum 모델을 참고하세요.

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

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

파일 업로드#

파일 업로드는 오브젝트 가속 업로드를 사용하여 GitLab Workhorse가 처리해야 합니다. 즉, GitLab에 들어오는 모든 요청을 확인하는 workhorse 프록시가 업로드 요청을 가로채서 파일을 업로드하고, 파일 자체가 아닌 메타데이터와 파일 위치만 포함하는 요청을 메인 GitLab 코드베이스에 전달합니다. 이 프로세스의 개요는 개발 문서에서 확인할 수 있습니다.

코드 측면에서, 이는 추가되는 각 업로드 엔드포인트(인스턴스, 그룹, 프로젝트)에 대해 GitLab Workhorse 프로젝트에 라우트를 추가해야 함을 의미합니다. 이 머지 리퀘스트는 workhorse에 Conan의 인스턴스 수준 엔드포인트를 추가하는 방법을 보여줍니다. 동일한 파일에서 구현된 Maven 프로젝트 수준 엔드포인트도 확인할 수 있습니다.

라우트가 추가된 후에는 API 파일에 업로드 엔드포인트의 추가 /authorize 버전을 추가해야 합니다. 이 예시는 Maven에 추가된 추가 엔드포인트를 보여줍니다. /authorize 엔드포인트는 workhorse의 요청을 검증하고 인가한 다음, 일반적인 업로드 엔드포인트가 아래에 구현되어 Workhorse가 제공하는 메타데이터를 소비하여 패키지 레코드를 생성합니다. Workhorse는 유형, 크기, 다양한 체크섬 형식과 같은 다양한 파일 메타데이터를 제공합니다.

테스트 목적으로, 로컬 개발 환경에서 오브젝트 스토리지를 활성화할 수 있습니다.

파일 크기 제한#

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

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에 시딩

  • Grafana 차트용 런북 업데이트

  • (최소한) 패키지 게시 및 설치에 대한 엔드투엔드 기능 테스트

향후 작업#

MVC를 진행하는 동안 기여자들은 MVC에 필수적이지는 않지만 더 나은 사용자 경험을 제공할 수 있는 기능을 발견할 수 있습니다. 이러한 기능에 주의를 기울이고 이슈를 여는 것이 일반적으로 좋은 생각입니다.

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

  • 검색에 필요한 엔드포인트

  • 추가 패키지 정보 및 메타데이터를 표시하기 위한 프런트엔드 업데이트

  • 파일 크기 제한

  • 메트릭 추적

  • 패키지에서 더 많은 메타데이터 필드를 읽어 프런트엔드에서 사용할 수 있도록 합니다. 예를 들어, 패키지에 태그를 지정할 수 있는 것이 일반적입니다. 해당 태그는 백엔드에서 읽고 저장한 다음 패키지 UI에 표시할 수 있습니다.

  • 리모트 계층 구조의 상위 수준에 대한 엔드포인트. 이 단계에서는 명명 규칙을 만들어야 할 수 있습니다.

예외#

이 문서는 GitLab에 이미 존재하는 구조와 로직에 맞게 패키지 관리자를 구현하는 방법에 대한 가이드라인일 뿐입니다. 구조는 어떤 패키지 관리자도 수용할 수 있을 만큼 확장 가능하고 유연하도록 의도되었지만, 특정 패키지 관리자의 제약이나 요구사항으로 인해 벗어날 타당한 이유가 있다면, 가장 효율적인 결과를 위해 구현 이슈 또는 머지 리퀘스트에서 제기하고 논의해야 합니다.