@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/storage/s3_provider.go

@@ -0,0 +1,489 @@
+package storage
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/url"
+	"time"
+
+	"github.com/aws/aws-sdk-go-v2/aws"
+	"github.com/aws/aws-sdk-go-v2/credentials"
+	"github.com/aws/aws-sdk-go-v2/service/s3"
+	s3types "github.com/aws/aws-sdk-go-v2/service/s3/types"
+	"github.com/aws/smithy-go"
+	"go.uber.org/zap"
+)
+
+// ===============================================================
+// S3 配置
+// ===============================================================
+
+// S3Config S3 Provider 配置
+type S3Config struct {
+	// AWS 区域
+	Region string
+	// 自定义端点（空 = AWS S3，非空 = R2/MinIO/OSS-S3）
+	Endpoint string
+	// 访问密钥 ID
+	AccessKeyID string
+	// 访问密钥 Secret
+	SecretAccessKey string
+	// 是否使用路径风格（MinIO 需要 true）
+	UsePathStyle bool
+}
+
+// ===============================================================
+// S3 Provider
+// ===============================================================
+
+// S3Provider 基于 AWS SDK v2 的 S3 兼容存储实现
+type S3Provider struct {
+	client        *s3.Client
+	presignClient *s3.PresignClient
+	logger        *zap.Logger
+}
+
+// NewS3Provider 创建 S3 Provider 实例
+func NewS3Provider(cfg S3Config, logger *zap.Logger) (*S3Provider, error) {
+	if cfg.Region == "" {
+		return nil, fmt.Errorf("s3 region is required")
+	}
+	if cfg.AccessKeyID == "" || cfg.SecretAccessKey == "" {
+		return nil, fmt.Errorf("s3 credentials are required")
+	}
+
+	opts := func(o *s3.Options) {
+		o.Region = cfg.Region
+		o.Credentials = credentials.NewStaticCredentialsProvider(
+			cfg.AccessKeyID,
+			cfg.SecretAccessKey,
+			"",
+		)
+		o.UsePathStyle = cfg.UsePathStyle
+		o.RequestChecksumCalculation = aws.RequestChecksumCalculationWhenRequired
+		o.ResponseChecksumValidation = aws.ResponseChecksumValidationWhenRequired
+
+		if cfg.Endpoint != "" {
+			o.BaseEndpoint = aws.String(cfg.Endpoint)
+		}
+	}
+
+	client := s3.New(s3.Options{}, opts)
+	presignClient := s3.NewPresignClient(client)
+
+	return &S3Provider{
+		client:        client,
+		presignClient: presignClient,
+		logger:        logger.Named("S3Provider"),
+	}, nil
+}
+
+// ===============================================================
+// 预签名上传 / 下载
+// ===============================================================
+
+// GeneratePresignedUploadURL 生成预签名上传 URL
+func (p *S3Provider) GeneratePresignedUploadURL(ctx context.Context, params PresignUploadParams) (*PresignUploadResult, error) {
+	expiresIn := params.ExpiresIn
+	if expiresIn == 0 {
+		expiresIn = 15 * time.Minute
+	}
+
+	input := &s3.PutObjectInput{
+		Bucket:      aws.String(params.Bucket),
+		Key:         aws.String(params.Key),
+		ContentType: aws.String(params.ContentType),
+	}
+
+	// 设置自定义元数据
+	if len(params.Metadata) > 0 {
+		input.Metadata = params.Metadata
+	}
+
+	// 限制上传文件大小
+	if params.MaxFileSize > 0 {
+		input.ContentLength = aws.Int64(params.MaxFileSize)
+	}
+
+	presigned, err := p.presignClient.PresignPutObject(ctx, input, s3.WithPresignExpires(expiresIn))
+	if err != nil {
+		p.logger.Error("presigned upload url generation failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("generate presigned upload url: %w", err)
+	}
+
+	headers := make(map[string]string)
+	for key, values := range presigned.SignedHeader {
+		if len(values) > 0 {
+			headers[key] = values[0]
+		}
+	}
+
+	return &PresignUploadResult{
+		URL:       presigned.URL,
+		Headers:   headers,
+		ExpiresAt: time.Now().UTC().Add(expiresIn),
+	}, nil
+}
+
+// GeneratePresignedDownloadURL 生成预签名下载 URL
+func (p *S3Provider) GeneratePresignedDownloadURL(ctx context.Context, params PresignDownloadParams) (*PresignDownloadResult, error) {
+	expiresIn := params.ExpiresIn
+	if expiresIn == 0 {
+		expiresIn = 15 * time.Minute
+	}
+
+	input := &s3.GetObjectInput{
+		Bucket: aws.String(params.Bucket),
+		Key:    aws.String(params.Key),
+	}
+
+	// 非安全内联类型设置 Content-Disposition 为附件下载（RFC 5987 编码支持国际化文件名）
+	if params.DownloadFilename != "" {
+		input.ResponseContentDisposition = aws.String(downloadContentDisposition(params.DownloadFilename))
+	}
+
+	presigned, err := p.presignClient.PresignGetObject(ctx, input, s3.WithPresignExpires(expiresIn))
+	if err != nil {
+		p.logger.Error("presigned download url generation failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("generate presigned download url: %w", err)
+	}
+
+	return &PresignDownloadResult{
+		URL:       presigned.URL,
+		ExpiresAt: time.Now().UTC().Add(expiresIn),
+	}, nil
+}
+
+// ===============================================================
+// 服务端上传 / 删除 / 元数据
+// ===============================================================
+
+// Upload 服务端直接上传（小文件代理）
+func (p *S3Provider) Upload(ctx context.Context, params UploadParams) (*UploadResult, error) {
+	input := &s3.PutObjectInput{
+		Bucket:      aws.String(params.Bucket),
+		Key:         aws.String(params.Key),
+		Body:        params.Body,
+		ContentType: aws.String(params.ContentType),
+	}
+
+	if params.Size > 0 {
+		input.ContentLength = aws.Int64(params.Size)
+	}
+
+	if len(params.Metadata) > 0 {
+		input.Metadata = params.Metadata
+	}
+
+	output, err := p.client.PutObject(ctx, input)
+	if err != nil {
+		p.logger.Error("upload failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("upload object: %w", err)
+	}
+
+	etag := ""
+	if output.ETag != nil {
+		etag = *output.ETag
+	}
+
+	location := fmt.Sprintf("s3://%s/%s", params.Bucket, params.Key)
+
+	return &UploadResult{
+		ETag:     etag,
+		Location: location,
+	}, nil
+}
+
+// UploadIfAbsent 通过 If-None-Match 原子创建不可变对象。
+func (p *S3Provider) UploadIfAbsent(
+	ctx context.Context,
+	params UploadParams,
+) (*UploadResult, bool, error) {
+	input := &s3.PutObjectInput{
+		Bucket:      aws.String(params.Bucket),
+		Key:         aws.String(params.Key),
+		Body:        params.Body,
+		ContentType: aws.String(params.ContentType),
+		IfNoneMatch: aws.String("*"),
+	}
+	if params.Size > 0 {
+		input.ContentLength = aws.Int64(params.Size)
+	}
+	if len(params.Metadata) > 0 {
+		input.Metadata = params.Metadata
+	}
+	output, err := p.client.PutObject(ctx, input)
+	if err != nil {
+		var apiErr smithy.APIError
+		if errors.As(err, &apiErr) && (apiErr.ErrorCode() == "PreconditionFailed" || apiErr.ErrorCode() == "ConditionalRequestConflict") {
+			return nil, false, nil
+		}
+		return nil, false, fmt.Errorf("create immutable object: %w", err)
+	}
+	etag := ""
+	if output.ETag != nil {
+		etag = *output.ETag
+	}
+	return &UploadResult{
+		ETag: etag, Location: fmt.Sprintf("s3://%s/%s", params.Bucket, params.Key),
+	}, true, nil
+}
+
+// Delete 删除对象
+func (p *S3Provider) Delete(ctx context.Context, params DeleteParams) error {
+	input := &s3.DeleteObjectInput{
+		Bucket: aws.String(params.Bucket),
+		Key:    aws.String(params.Key),
+	}
+
+	_, err := p.client.DeleteObject(ctx, input)
+	if err != nil {
+		p.logger.Error("delete failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.Error(err),
+		)
+		return fmt.Errorf("delete object: %w", err)
+	}
+
+	return nil
+}
+
+var _ ImmutableObjectProvider = (*S3Provider)(nil)
+
+// HeadObject 获取对象元数据
+func (p *S3Provider) HeadObject(ctx context.Context, params HeadObjectParams) (*ObjectMetadata, error) {
+	input := &s3.HeadObjectInput{
+		Bucket: aws.String(params.Bucket),
+		Key:    aws.String(params.Key),
+	}
+
+	output, err := p.client.HeadObject(ctx, input)
+	if err != nil {
+		p.logger.Error("head object failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("head object: %w", err)
+	}
+
+	contentType := ""
+	if output.ContentType != nil {
+		contentType = *output.ContentType
+	}
+
+	etag := ""
+	if output.ETag != nil {
+		etag = *output.ETag
+	}
+
+	var contentLength int64
+	if output.ContentLength != nil {
+		contentLength = *output.ContentLength
+	}
+
+	var lastModified time.Time
+	if output.LastModified != nil {
+		lastModified = *output.LastModified
+	}
+
+	return &ObjectMetadata{
+		ContentType:   contentType,
+		ContentLength: contentLength,
+		ETag:          etag,
+		LastModified:  lastModified,
+		Metadata:      output.Metadata,
+	}, nil
+}
+
+// ===============================================================
+// 分片上传
+// ===============================================================
+
+// InitiateMultipartUpload 发起分片上传
+func (p *S3Provider) InitiateMultipartUpload(ctx context.Context, params InitiateMultipartParams) (*InitiateMultipartResult, error) {
+	input := &s3.CreateMultipartUploadInput{
+		Bucket:      aws.String(params.Bucket),
+		Key:         aws.String(params.Key),
+		ContentType: aws.String(params.ContentType),
+	}
+
+	if len(params.Metadata) > 0 {
+		input.Metadata = params.Metadata
+	}
+
+	output, err := p.client.CreateMultipartUpload(ctx, input)
+	if err != nil {
+		p.logger.Error("initiate multipart upload failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("initiate multipart upload: %w", err)
+	}
+
+	uploadID := ""
+	if output.UploadId != nil {
+		uploadID = *output.UploadId
+	}
+
+	return &InitiateMultipartResult{
+		UploadID: uploadID,
+	}, nil
+}
+
+// GeneratePartPresignedURL 生成分片预签名上传 URL
+func (p *S3Provider) GeneratePartPresignedURL(ctx context.Context, params PresignPartParams) (*PresignPartResult, error) {
+	expiresIn := params.ExpiresIn
+	if expiresIn == 0 {
+		expiresIn = 15 * time.Minute
+	}
+
+	input := &s3.UploadPartInput{
+		Bucket:     aws.String(params.Bucket),
+		Key:        aws.String(params.Key),
+		UploadId:   aws.String(params.UploadID),
+		PartNumber: aws.Int32(params.PartNumber),
+	}
+
+	presigned, err := p.presignClient.PresignUploadPart(ctx, input, s3.WithPresignExpires(expiresIn))
+	if err != nil {
+		p.logger.Error("presigned part url generation failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.String("uploadId", params.UploadID),
+			zap.Int32("partNumber", params.PartNumber),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("generate part presigned url: %w", err)
+	}
+
+	return &PresignPartResult{
+		URL:       presigned.URL,
+		ExpiresAt: time.Now().UTC().Add(expiresIn),
+	}, nil
+}
+
+// CompleteMultipartUpload 完成分片上传
+func (p *S3Provider) CompleteMultipartUpload(ctx context.Context, params CompleteMultipartParams) (*CompleteMultipartResult, error) {
+	parts := make([]s3types.CompletedPart, len(params.Parts))
+	for i, part := range params.Parts {
+		parts[i] = s3types.CompletedPart{
+			PartNumber: aws.Int32(part.PartNumber),
+			ETag:       aws.String(part.ETag),
+		}
+	}
+
+	input := &s3.CompleteMultipartUploadInput{
+		Bucket:   aws.String(params.Bucket),
+		Key:      aws.String(params.Key),
+		UploadId: aws.String(params.UploadID),
+		MultipartUpload: &s3types.CompletedMultipartUpload{
+			Parts: parts,
+		},
+	}
+
+	output, err := p.client.CompleteMultipartUpload(ctx, input)
+	if err != nil {
+		p.logger.Error("complete multipart upload failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.String("uploadId", params.UploadID),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("complete multipart upload: %w", err)
+	}
+
+	etag := ""
+	if output.ETag != nil {
+		etag = *output.ETag
+	}
+
+	location := ""
+	if output.Location != nil {
+		location = *output.Location
+	}
+
+	return &CompleteMultipartResult{
+		ETag:     etag,
+		Location: location,
+	}, nil
+}
+
+// Download 服务端直接下载对象内容
+func (p *S3Provider) Download(ctx context.Context, params DownloadParams) (*DownloadResult, error) {
+	input := &s3.GetObjectInput{
+		Bucket: aws.String(params.Bucket),
+		Key:    aws.String(params.Key),
+	}
+
+	output, err := p.client.GetObject(ctx, input)
+	if err != nil {
+		p.logger.Error("download failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("download object: %w", err)
+	}
+
+	contentType := ""
+	if output.ContentType != nil {
+		contentType = *output.ContentType
+	}
+
+	var contentLength int64
+	if output.ContentLength != nil {
+		contentLength = *output.ContentLength
+	}
+
+	return &DownloadResult{
+		Body:          output.Body,
+		ContentType:   contentType,
+		ContentLength: contentLength,
+	}, nil
+}
+
+func downloadContentDisposition(filename string) string {
+	//nolint:gocritic // sprintfQuotedString: Content-Disposition 头需要 RFC 2616 格式的引号，%q 会引入 Go 转义序列
+	return fmt.Sprintf(`attachment; filename="%s"; filename*=UTF-8''%s`,
+		SanitizeFilename(filename),
+		url.PathEscape(filename),
+	)
+}
+
+// AbortMultipartUpload 取消分片上传
+func (p *S3Provider) AbortMultipartUpload(ctx context.Context, params AbortMultipartParams) error {
+	input := &s3.AbortMultipartUploadInput{
+		Bucket:   aws.String(params.Bucket),
+		Key:      aws.String(params.Key),
+		UploadId: aws.String(params.UploadID),
+	}
+
+	_, err := p.client.AbortMultipartUpload(ctx, input)
+	if err != nil {
+		p.logger.Error("abort multipart upload failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.String("uploadId", params.UploadID),
+			zap.Error(err),
+		)
+		return fmt.Errorf("abort multipart upload: %w", err)
+	}
+
+	return nil
+}

package/dist/resources/templates/go-backend/internal/core/storage/s3_provider_test.go

@@ -0,0 +1,60 @@
+package storage
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"go.uber.org/zap"
+)
+
+func TestS3ProviderUploadUsesRequiredChecksumMode(t *testing.T) {
+	var receivedHeader http.Header
+	var receivedPath string
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		receivedHeader = r.Header.Clone()
+		receivedPath = r.URL.Path
+		_, _ = io.Copy(io.Discard, r.Body)
+		w.Header().Set("ETag", `"local-etag"`)
+		w.WriteHeader(http.StatusOK)
+	}))
+	t.Cleanup(server.Close)
+
+	provider, err := NewS3Provider(S3Config{
+		Region:          "us-east-1",
+		Endpoint:        server.URL,
+		AccessKeyID:     "test-access-key",
+		SecretAccessKey: "test-secret-key",
+		UsePathStyle:    true,
+	}, zap.NewNop())
+	if err != nil {
+		t.Fatalf("NewS3Provider() error = %v", err)
+	}
+
+	_, err = provider.Upload(context.Background(), UploadParams{
+		Bucket:      "test-bucket",
+		Key:         "outputs/image.png",
+		Body:        strings.NewReader("image-bytes"),
+		ContentType: "image/png",
+		Size:        int64(len("image-bytes")),
+	})
+	if err != nil {
+		t.Fatalf("Upload() error = %v", err)
+	}
+	if receivedPath != "/test-bucket/outputs/image.png" {
+		t.Fatalf("request path = %q, want %q", receivedPath, "/test-bucket/outputs/image.png")
+	}
+	if got := receivedHeader.Get("X-Amz-Checksum-Crc32"); got != "" {
+		t.Fatalf("X-Amz-Checksum-Crc32 = %q, want empty", got)
+	}
+	if got := receivedHeader.Get("X-Amz-Sdk-Checksum-Algorithm"); got != "" {
+		t.Fatalf("X-Amz-Sdk-Checksum-Algorithm = %q, want empty", got)
+	}
+	if got := receivedHeader.Get("Content-Encoding"); strings.Contains(got, "aws-chunked") {
+		t.Fatalf("Content-Encoding = %q, want no aws-chunked", got)
+	}
+}