gostorage

type Client interface {
	// GetPresignedUploadURL returns a URL that lets a client upload the
	// object at key without holding credentials, using an HTTP PUT request.
	//
	// For S3, MinIO and OSS a signed PUT URL for bucket/key is returned.
	// contentType, when non-empty, is bound into the signature so the
	// provider rejects uploads with a mismatched Content-Type; expiry is
	// honored with one-second precision.
	//
	// For Supabase a server-side signed upload URL is returned instead.
	// contentType is not part of the Supabase contract and its lifetime is
	// governed by the provider, so expiry is ignored; keep the default
	// (DefaultPresignUploadExpiry) so the browser has enough time to
	// complete the PUT.
	//
	// Returns an error only when the provider rejects the signing
	// operation, e.g. because the credentials are invalid.
	GetPresignedUploadURL(key, contentType string, expiry time.Duration) (string, error)

	// GetPresignedGetURL returns a signed URL that lets a client download
	// the object at key without holding credentials.
	//
	// For S3, MinIO and OSS the returned URL is an HTTP GET request for
	// bucket/key. For Supabase a signed download URL is returned instead;
	// expiry is honored at one-second precision. For local, when
	// Config.PublicBaseURL is set, an expiring GET URL under that base is
	// returned; otherwise the on-disk path is returned (see GetPresignedUploadURL).
	//
	// Returns an error only when the provider rejects the signing
	// operation.
	GetPresignedGetURL(key string, expiry time.Duration) (string, error)

	// GetPublicURL returns the public (unsigned) URL of the object at key.
	//
	// The object must be publicly readable through the provider's bucket
	// policy; no signing or credentials are involved and this method never
	// returns an error. An empty key yields a URL ending with the bucket
	// path. For local, when Config.PublicBaseURL is set, the returned URL is
	// an unsigned URL under that base; otherwise the on-disk path is
	// returned.
	GetPublicURL(key string) string

	// GetSize returns the total size in bytes of every object stored under
	// prefix. Prefixes that expand to nothing (or to only empty objects)
	// return zero. The error is non-nil only when listing the provider
	// fails, in which case the returned size may be incomplete.
	GetSize(prefix string) (int64, error)

	// ListObjects returns the objects stored under prefix, listed
	// recursively. Keys are relative to the bucket and their order is
	// unspecified. The error is non-nil only when listing the provider
	// fails, in which case the returned slice may be incomplete.
	ListObjects(prefix string) ([]ObjectInfo, error)

	// DeleteObject permanently removes the object at key. Providers treat
	// deleting an already-missing object as a no-op or an error depending
	// on their semantics; the error is non-nil only when the deletion could
	// not be performed.
	DeleteObject(key string) error

	// Type returns the full storage type as configured, e.g. "acme-s3".
	Type() string

	// Name returns the logical storage name as configured.
	Name() string

	// Kind returns the resolved provider kind.
	Kind() Kind
}

type Config struct {
	// Type is the fully qualified type such as "acme-s3".
	// The qualifier before the first "-" is arbitrary and is stripped when
	// Kind is not set; a plain kind such as "s3" is also accepted.
	Type string

	// Kind is the raw provider kind: one of KindS3, KindMinio, KindSupabase,
	// KindOSS or KindGCS. Derived from Type when empty.
	Kind Kind

	// Name is the user-facing storage name (e.g. "chum-bucket").
	Name string

	// Bucket is the bucket inside the provider. Defaults to Name when empty.
	Bucket string

	// Endpoint is the provider endpoint. It may include a scheme
	// (http:// or https://); otherwise TLS is assumed.
	Endpoint string

	// Region is the provider region. For Supabase it holds the project
	// reference id that maps to "<ref>.supabase.co".
	Region string

	// AccessKey is the provider access key. For Supabase it is the anon or
	// service_role API key used as the Bearer token.
	AccessKey string

	// SecretKey is the provider secret key. For local storage it is the HMAC
	// key used to sign local presigned URLs (see PublicBaseURL).
	SecretKey string

	// PublicBaseURL is the externally reachable HTTP base under which local
	// filesystem objects are served and uploaded, e.g.
	// "https://files.example.com/storages".
	//
	// It is only used by the local provider. When set, GetPresignedUploadURL
	// and GetPresignedGetURL return expiring URLs into PublicBaseURL signed
	// with LocalSign, and GetPublicURL returns an unsigned URL under the same
	// base; otherwise all three return the absolute on-disk path of the
	// object, preserving the legacy behavior.
	PublicBaseURL string

	// Context is the base context used for storage operations. Defaults to
	// context.Background() when nil.
	Context context.Context

	// Timeout bounds HTTP requests made directly by this library (OSS raw
	// calls). Defaults to DefaultTimeout.
	Timeout time.Duration
}

type Kind string

type ObjectInfo struct {
	// Key is the object key, relative to the bucket.
	Key string

	// Size is the object size in bytes.
	Size int64

	// LastModified is the object modification time when known.
	LastModified time.Time
}