pos-system/services/storage-service-net/docs/en

Storage Service

A .NET 10 microservice for file storage management supporting MinIO and Aliyun OSS.

Features

• Multi-provider Storage: MinIO (S3-compatible) and Aliyun OSS
• Runtime Provider Switching: Switch between MinIO and Aliyun via environment variable
• Complete File CRUD: Upload, download, delete, list files
• Pre-signed URLs: Secure time-limited download/upload URLs
• User Quotas: Storage capacity and file count limits per user
• Inter-service Communication: JWT validation via IAM Service with caching

Quick Start

Prerequisites

• .NET 10 SDK
• Docker & Docker Compose
• PostgreSQL (or Neon)
• MinIO (or Aliyun OSS account)

Run with Docker

cd services/storage-service-net
docker-compose up -d

Access: http://localhost:5002/swagger

Run Locally

cd services/storage-service-net

# Install dependencies
dotnet restore

# Run migrations (first time)
dotnet ef database update --project src/StorageService.Infrastructure --startup-project src/StorageService.API

# Start the service
dotnet run --project src/StorageService.API

Configuration

Environment Variables

Variable	Description	Default
Storage__Provider	Provider selection: minio or aliyun	minio
Storage__DefaultBucket	Default bucket name	storage
Storage__MaxFileSizeBytes	Maximum file size	104857600 (100MB)
Storage__PreSignedUrlExpirationSeconds	Pre-signed URL expiration	3600

MinIO Configuration

Variable	Description	Default
Storage__MinIO__Endpoint	MinIO server endpoint	localhost:9000
Storage__MinIO__AccessKey	Access key	-
Storage__MinIO__SecretKey	Secret key	-
Storage__MinIO__UseSSL	Enable SSL	false

Aliyun OSS Configuration

Variable	Description	Default
Storage__AliyunOSS__Endpoint	OSS endpoint	-
Storage__AliyunOSS__AccessKeyId	Access key ID	-
Storage__AliyunOSS__AccessKeySecret	Access key secret	-
Storage__AliyunOSS__Region	OSS region	-

IAM Service Configuration

Variable	Description	Default
IamService__BaseUrl	IAM Service URL	http://localhost:5001
IamService__ServiceName	Service identifier	storage-service
IamService__TimeoutSeconds	Request timeout	30
IamService__CacheDurationSeconds	User info cache TTL	300
IamService__HealthCheckCacheDurationSeconds	Health check cache TTL	60

API Endpoints

Files

Method	Endpoint	Description
POST	/api/v1/files/upload	Upload a file (max 100MB)
GET	/api/v1/files	List user's files with pagination
GET	/api/v1/files/{id}	Get file metadata by ID
GET	/api/v1/files/{id}/download-url	Get pre-signed download URL
DELETE	/api/v1/files/{id}	Delete a file (soft delete)

Quota

Method	Endpoint	Description
GET	/api/v1/quota	Get current user's storage quota

Upload Example

curl -X POST "http://localhost:5002/api/v1/files/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf"

Inter-Service Communication

The service communicates with IAM Service for user validation:

• Headers: Authorization: Bearer <token>, X-Service-Name: storage-service
• Caching: User info cached for 5 minutes
• Resilience: Polly retry (3x) + circuit breaker
• Methods:
  • ValidateUserAsync - Validate JWT and get user info
  • GetUserRolesAsync - Get user roles
  • HasPermissionAsync - Check specific permission

Database Migrations

# Create new migration
dotnet ef migrations add MigrationName \
  --project src/StorageService.Infrastructure \
  --startup-project src/StorageService.API

# Apply migrations
dotnet ef database update \
  --project src/StorageService.Infrastructure \
  --startup-project src/StorageService.API

Testing

# Run all tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

Project Structure

services/storage-service-net/
├── src/
│   ├── StorageService.API/           # Controllers, Commands, Queries
│   ├── StorageService.Domain/        # Entities, Repository interfaces
│   └── StorageService.Infrastructure/# Providers, DbContext, Repositories
├── tests/
│   ├── StorageService.UnitTests/
│   └── StorageService.FunctionalTests/
├── docs/
│   ├── en/                           # English documentation
│   └── vi/                           # Vietnamese documentation
├── docker-compose.yml
├── Dockerfile
└── README.md

License

MIT