RustFS 클라이언트 개발

[kwonkwonn]

배경 및 목표

related: #60
오브젝트 스토리지 백엔드로 RustFS를 사용하기 위한 클라이언트 레이어를 구축한다.
RustFS는 S3 호환 API를 제공하므로 AWS SDK(Go) 또는 MinIO SDK 기반으로 래핑하며,
기존 프로젝트 패턴(controller → service → repository/client)을 그대로 따른다.

---

아키텍처 개요

Controller
  └─ 탐색, 파일 조회, Presigned URL 발급
       │
       ▼
Service
  └─ rustfsClient  (스토리지 I/O: 존재 여부 확인, URL 생성)
 Repository    (DB: 버킷·오브젝트 메타 관리)
       │
       ▼
Core
  └─ Presigned URL을 통해 업로드/다운로드 직접 수행

역할 분리 원칙

• Controller: 클라이언트 요청 수신, Presigned URL 반환
• Service: rustfsClient + Repository 조합, 비즈니스 로직
• Core: URL을 받아 실제 파일 전송 수행 (스토리지 직접 호출 없음)

---

버킷 네이밍 전략

리소스	버킷명	오브젝트 키 예시
OS 이미지	{os-name} (e.g. ubuntu)	{version}/{filename}(e.g., 24-04)
VM 스냅샷	{vm-uuid}	{snapshot-uuid}/{filename}

DB 설계(Repository 계층)는 별도 태스크로 분리. rustfsClient 구현 이후 논의.

---

Stories

Story 1: rustfsClient 구현

Goal: RustFS 연결 및 핵심 오퍼레이션을 제공하는 클라이언트 구조체를 구현한다.

Scope (in):

• 클라이언트 초기화 (endpoint, accessKey, secretKey, useSSL)
• 버킷 존재 여부 확인 (BucketExists)
• 버킷 생성 (CreateBucket)
• 오브젝트 존재 여부 확인 (ObjectExists)
• 오브젝트 목록 조회 (ListObjects)
• Presigned Download URL 생성
• Presigned Upload URL 생성

Scope (out):

• 직접 업로드/다운로드 (Core 담당)
• DB 메타 관리 (Repository 담당)

기술 결정:

• SDK: github.com/minio/minio-go/v7 (RustFS는 MinIO SDK 호환)
• 인증: UI 콘솔에서 발급한 Access Key / Secret Key를 환경변수로 주입
• Presigned URL 만료 시간: 환경변수로 설정 가능하게 구성 (기본값 TBD)

Acceptance Criteria:

• NewRustFSClient()로 클라이언트 생성 성공
• 잘못된 endpoint/key로 생성 시 명확한 에러 반환
• BucketExists() 결과가 실제 스토리지 상태와 일치
• Presigned URL이 Core에서 추가 인증 없이 사용 가능
• 단위 테스트 작성 (mock 또는 로컬 RustFS 인스턴스 사용)

---

Story 2: Service 레이어 구현

Goal: rustfsClient와 Repository를 조합하여 비즈니스 로직을 제공하는 Service를 구현한다.

Scope (in):

• OS 이미지 업로드 흐름: 버킷 확인/생성 → Presigned Upload URL 발급 → Core에 전달
• OS 이미지 다운로드 흐름: 오브젝트 존재 확인 → Presigned Download URL 발급
• VM 스냅샷 업로드/다운로드 흐름 (동일 패턴)
• 파일 목록 조회 (버킷 + prefix 기반)

Scope (out):

• DB 스키마 정의 (별도 태스크)
• Core 내부 전송 로직

Acceptance Criteria:

• Service가 rustfsClient와 Repository에만 의존 (Controller 미참조)
• 버킷 미존재 시 자동 생성 후 URL 발급
• 오브젝트 미존재 시 명확한 에러 반환 (다운로드 요청일 때)

---

Story 3: 동기/비동기 처리 방식 결정 (기술 검토)

Goal: OS 저장 및 VM 생성의 순서 의존성을 고려한 처리 방식을 결정한다.

배경:

• CreateVM 같은 경우 OS 설치, 가상 머신 부팅 의 긴 두가지의 오퍼레이션이 필요함.
• Core에서 VM을 생성하려면 OS가 먼저 스토리지에 저장되어 있어야 한다.
• 즉, OS 업로드 완료 → VM 생성 의 순서 의존성이 존재한다.(control 단에서의 비동기처리가 큰 의미가 없을 확률이 높음)
• Control ↔ Core는 현재 1:1 구조이므로 그렇기 때문에 메시지 큐/goroutine 도입 시 에러 처리 복잡도에 비해 효과가 미미함

검토 옵션:

방식	장점	단점
동기 (현행 유지)	에러 추적 단순, 순서 보장 명확	업로드 시간만큼 응답 지연
goroutine + 결과 채널	구조 변경 최소	에러 전파 복잡, 타임아웃 관리 필요
메시지 큐 (e.g. NATS)	재시도·확장성 우수	인프라 추가, 오버엔지니어링 우려,에러 전파 복잡, 타임아웃 관리 필요

권고안 (초안):

• 1차: 동기 처리로 구현. OS 업로드 완료 응답 이후 Core가 VM 생성 요청.
• 추후 업로드 시간이 SLA에 영향을 준다면 goroutine + 상태 폴링 방식으로 전환 검토.

Acceptance Criteria:

• 팀 논의 후 방식 확정 및 이 문서 업데이트
• 결정된 방식이 Story 2 구현에 반영

---

인증 방식

RustFS UI 콘솔에서 Access Key를 발급받아 사용한다.

• 발급 위치: 콘솔 좌측 메뉴 → Access Keys → Add Access Key
• 만료 시간·이름·설명 설정 후 발급, Export 또는 Copy로 저장
• 발급된 키는 환경변수(RUSTFS_ACCESS_KEY_ID, RUSTFS_SECRET_ACCESS_KEY)로 주입
• 키를 코드에 하드코딩 금지
• 키 교체 주기 및 권한 범위는 운영 정책에서 별도 정의

---

참고

• [RustFS Access Key 관리](https://docs.rustfs.com/administration/iam/access-token.html)
• [RustFS Golang SDK](https://docs.rustfs.com/developer/sdk/go.html)
• [rustfs-client toolkit (MinIO SDK 래퍼)
  <-- aws s3 client 랑 compatible 하다고함..

서브 테스크

• 성우군이 작성한 docker-compose.test 에 rustfs 추가
• rustFS 클라이언트 작성(여기서 테스트용 api 를 먼저 붙여볼수도 있음)
• 데이터베이스 작성 및 서비스 작성( 데이터 베이스 쓰기/읽기, 클라이언트 값 조합)
• api 및 전체 테스트 코드 작성

Notes

[kwonkwonn]

@ga111o @ukleon123 @wind5052 참고해주세용