Documentation
¶
Overview ¶
Package s3 provides an S3-compatible artifact storage service implementation. It supports AWS S3, MinIO, DigitalOcean Spaces, Cloudflare R2, and other S3-compatible object storage services.
Index ¶
- Variables
- type Option
- func WithClient(client s3storage.Client) Option
- func WithCredentials(accessKeyID, secretAccessKey string) Option
- func WithEndpoint(endpoint string) Option
- func WithLogger(logger log.Logger) Option
- func WithPathStyle(enabled bool) Option
- func WithRegion(region string) Option
- func WithRetries(n int) Option
- func WithSessionToken(token string) Option
- type Service
- func (s *Service) Close() error
- func (s *Service) DeleteArtifact(ctx context.Context, sessionInfo artifact.SessionInfo, filename string) error
- func (s *Service) ListArtifactKeys(ctx context.Context, sessionInfo artifact.SessionInfo) ([]string, error)
- func (s *Service) ListVersions(ctx context.Context, sessionInfo artifact.SessionInfo, filename string) ([]int, error)
- func (s *Service) LoadArtifact(ctx context.Context, sessionInfo artifact.SessionInfo, filename string, ...) (*artifact.Artifact, error)
- func (s *Service) SaveArtifact(ctx context.Context, sessionInfo artifact.SessionInfo, filename string, ...) (int, error)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrEmptyFilename is returned when the filename is empty. ErrEmptyFilename = errors.New("s3 artifact: filename cannot be empty") // ErrInvalidFilename is returned when the filename contains invalid characters. ErrInvalidFilename = errors.New("s3 artifact: filename contains invalid characters") // ErrNilArtifact is returned when the artifact is nil. ErrNilArtifact = errors.New("s3 artifact: artifact cannot be nil") // ErrEmptySessionInfo is returned when required session info fields are empty. ErrEmptySessionInfo = errors.New("s3 artifact: session info fields cannot be empty") )
Sentinel errors for artifact validation.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*options)
Option is a function that configures the S3 artifact service.
func WithClient ¶
WithClient sets a pre-created S3 client. When provided, connection options are ignored. The caller retains ownership and must close the client separately.
func WithCredentials ¶
WithCredentials sets static AWS credentials.
func WithEndpoint ¶
WithEndpoint sets a custom endpoint URL for S3-compatible services.
func WithLogger ¶
WithLogger sets the logger for operational messages.
func WithPathStyle ¶
WithPathStyle enables path-style addressing (required for MinIO).
func WithRetries ¶
WithRetries sets the maximum number of retries (default: 3).
func WithSessionToken ¶
WithSessionToken sets the session token for temporary credentials (STS).
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is an S3-compatible implementation of the artifact service. It supports AWS S3, MinIO, DigitalOcean Spaces, Cloudflare R2, and other S3-compatible object storage services.
The object name format used depends on whether the filename has a user namespace:
- For files with user namespace (starting with "user:"): {app_name}/{user_id}/user/{filename}/{version}
- For regular session-scoped files: {app_name}/{user_id}/{session_id}/{filename}/{version}
func NewService ¶
NewService creates a new S3 artifact service. When using WithClient, the bucket parameter is ignored as the client already has one configured.
func (*Service) Close ¶
Close releases any resources held by the service. If the client was provided externally via WithClient, it is not closed.
func (*Service) DeleteArtifact ¶
func (s *Service) DeleteArtifact( ctx context.Context, sessionInfo artifact.SessionInfo, filename string, ) error
DeleteArtifact deletes all versions of an artifact from S3.
func (*Service) ListArtifactKeys ¶
func (s *Service) ListArtifactKeys( ctx context.Context, sessionInfo artifact.SessionInfo, ) ([]string, error)
ListArtifactKeys lists all artifact filenames within a session. It returns artifacts from both session scope and user scope.
func (*Service) ListVersions ¶
func (s *Service) ListVersions( ctx context.Context, sessionInfo artifact.SessionInfo, filename string, ) ([]int, error)
ListVersions lists all versions of an artifact.
func (*Service) LoadArtifact ¶
func (s *Service) LoadArtifact( ctx context.Context, sessionInfo artifact.SessionInfo, filename string, version *int, ) (*artifact.Artifact, error)
LoadArtifact loads an artifact from S3. If version is nil, the latest version is loaded.
func (*Service) SaveArtifact ¶
func (s *Service) SaveArtifact( ctx context.Context, sessionInfo artifact.SessionInfo, filename string, art *artifact.Artifact, ) (int, error)
SaveArtifact saves an artifact to S3. It automatically determines the next version number by listing existing versions.
Concurrency: This method is NOT safe for concurrent writes to the same filename. If multiple goroutines save the same artifact concurrently, they may compute the same version number, causing one write to overwrite the other. For concurrent access, use external synchronization or unique filenames.
Source Files