API Reference

S3Config

Configuration for creating an S3Client.

Fields

• host::String: S3 endpoint hostname (e.g. "s3.amazonaws.com").
• region::String: AWS region.
• access_key::String: Access key ID.
• secret_key::String: Secret access key.
• user_agent::String: User agent string (default "AWSCS3.jl").
• connect_timeout_ms::Int: Connection timeout in milliseconds (default 3000).
• tls::Bool: Whether to use TLS (default true).

S3Client

Client for AWS S3-compatible storage. Manages connections, credentials, and request lifecycle via the AWS C SDK.

Constructors

• S3Client(; host, region, access_key, secret_key, ...) — create from keyword arguments.
• S3Client(cfg::S3Config) — create from an S3Config.
• S3Client(f::Function; kwargs...) — executes f(client) then calls shutdown!.

Examples

S3Client(
    host = "s3.amazonaws.com",
    region = "us-east-1",
    access_key = ENV["AWS_ACCESS_KEY_ID"],
    secret_key = ENV["AWS_SECRET_ACCESS_KEY"],
) do client
    put_object(client, "my-bucket", "hello.txt", "Hello, World!")
    body = get_object(client, "my-bucket", "hello.txt") |> String
    objects = list_objects(client, "my-bucket"; prefix = "hello")
    delete_object(client, "my-bucket", "hello.txt")
end

Base.isopen(client::S3Client) -> Bool

Check whether client has not been shut down.

shutdown!(client::S3Client)

Release all resources held by client. Safe to call multiple times.

create_bucket(client::S3Client, bucket::String; ignore_existing::Bool = false)

Create a bucket. When ignore_existing is true, an existing bucket is treated as success.

delete_bucket(client::S3Client, bucket::String; force::Bool = false)

Delete a bucket. When force is true, all objects are deleted first via delete_all_objects!.

bucket_exists(client::S3Client, bucket::String) -> Bool

Check whether a bucket exists.

list_buckets(client::S3Client) -> Vector{String}

List all bucket names accessible by the client.

set_bucket_versioning(client::S3Client, bucket::String; enabled::Bool = true)

Enable or suspend versioning for a bucket.

put_object(client::S3Client, bucket::String, key::String, body; headers = [], metadata = [])

Upload an object to bucket under key. The body can be a String, Vector{UInt8}, IOStream, or any IO.

Keyword Arguments

• headers: Additional HTTP headers.
• metadata: User-defined metadata stored as x-amz-meta-<key>.

get_object(client::S3Client, bucket::String, key::String) -> Vector{UInt8}
get_object(client::S3Client, bucket::String, key::String, dest_path::AbstractString)

Download an object. Returns the body as bytes, or saves it to a file at dest_path.

delete_object(client::S3Client, bucket::String, key::String; version_id = nothing)

Delete an object. Pass version_id to delete a specific version when versioning is enabled.

delete_objects(client::S3Client, bucket::String, keys::Vector{String})

Delete a list of objects from bucket using S3's batched DeleteObjects API. Keys are split into batches of up to 1000 per request. Throws on the first per-object failure reported by the service.

copy_object(client, src_bucket, src_key, dest_bucket, dest_key; kwargs...) -> S3CopyResult

Copy an object from src_bucket/src_key to dest_bucket/dest_key.

Keyword Arguments

• src_version_id: Copy a specific source version.
• headers: Additional HTTP headers.
• metadata: User-defined metadata to set on the destination object.

object_exists(client::S3Client, bucket::String, key::String) -> Bool

Check whether an object exists.

list_objects(client::S3Client, bucket::String; kwargs...) -> Vector{S3Object}

List objects in a bucket.

Keyword Arguments

• prefix: Restrict results to keys with this prefix.
• delimiter: Group keys by delimiter to return common prefixes.
• continuation_token: Token from a previous listing to continue.
• max_keys: Maximum number of keys to return.

list_objects_detailed(client::S3Client, bucket::String; kwargs...) -> S3ListResult

List objects with pagination info.

Keyword Arguments

• prefix: Restrict results to keys with this prefix.
• delimiter: Group keys by delimiter to return common prefixes.
• continuation_token: Token from a previous listing to continue.
• max_keys: Maximum number of keys to return.

delete_all_objects!(client::S3Client, bucket::String)

Delete all objects in a bucket using batched multi-object delete requests.

S3Object

S3 object metadata returned by list operations.

Fields

• key::String: Object key.
• size::Int: Object size in bytes.
• last_modified::String: Last modification timestamp.
• etag::String: Entity tag.

S3ListResult

Result from list_objects_detailed with pagination info.

Fields

• objects::Vector{S3Object}: Listed objects.
• common_prefixes::Vector{String}: Common prefixes when using a delimiter.
• is_truncated::Bool: Whether more results are available.
• continuation_token::Union{Nothing,String}: Token for the next page.

S3CopyResult

Result from copy_object.

Fields

• etag::String: Entity tag of copied object.
• last_modified::String: Last modification timestamp.

AbstractS3Error <: Exception

Abstract base type for all S3-related exceptions.

Concrete subtypes:

• S3Error: Generic S3 error response.
• S3AccessDeniedError: Access denied (HTTP 403).
• S3BucketAlreadyExistsError: Bucket already exists (HTTP 409).
• S3BucketNotFoundError: Bucket not found (HTTP 404).
• S3BucketNotEmptyError: Bucket is not empty (HTTP 409).
• S3ObjectNotFoundError: Object not found (HTTP 404).
• S3InvalidRequestError: Invalid request (HTTP 400).
• S3ServerError: Server error (HTTP 5xx).
• S3ConnectionError: Connection failure.
• S3AuthenticationError: Authentication failure (HTTP 401/403).

S3Error <: AbstractS3Error

Represents a generic S3 error response when a more specific subtype is not applicable.

Fields

• operation::String: Operation name.
• status::Int: HTTP status code, or 0 if unavailable.
• error_code::Int: AWS SDK error code, or 0.
• code::Union{Nothing,String}: S3 error code.
• message::String: Human-readable error message.
• request_id::Union{Nothing,String}: Request ID from the service.
• resource::Union{Nothing,String}: Resource associated with the error.
• raw_body::Vector{UInt8}: Raw response body.

S3AccessDeniedError <: AbstractS3Error

Access denied while performing an operation on a resource.

Fields

• operation::String: Operation name.
• resource::String: Resource path.
• message::String: Error message.

S3BucketAlreadyExistsError <: AbstractS3Error

Bucket already exists.

Fields

• bucket::String: Bucket name.

S3BucketNotFoundError <: AbstractS3Error

Bucket was not found.

Fields

• bucket::String: Bucket name.
• operation::String: Operation name.

S3BucketNotEmptyError <: AbstractS3Error

Bucket is not empty.

Fields

• bucket::String: Bucket name.

S3ObjectNotFoundError <: AbstractS3Error

Object was not found in a bucket.

Fields

• bucket::String: Bucket name.
• key::String: Object key.
• operation::String: Operation name.

S3InvalidRequestError <: AbstractS3Error

The request was rejected as invalid.

Fields

• operation::String: Operation name.
• message::String: Error message.

S3ServerError <: AbstractS3Error

The server returned a 5xx error.

Fields

• operation::String: Operation name.
• status::Int: HTTP status code.
• message::String: Error message.

S3ConnectionError <: AbstractS3Error

Failed to connect to the S3 endpoint.

Fields

• host::String: Endpoint hostname.
• message::String: Error message.

S3AuthenticationError <: AbstractS3Error

Authentication failed for the request.

Fields

• operation::String: Operation name.
• message::String: Error message.