4.17.11 Amazon S3 Client

4.17.11.1 Creating a Client

The primary way to interact with S3 via this library is with the S3 interface.

To create an instance of an S3 client, use the S3Client constructor:

(S3Client
  endpoint: (endpoint "s3.amazonaws.com")
  access-key: (access-key (getenv "AWS_ACCESS_KEY_ID" #f))
  secret-key: (secret-key (getenv "AWS_SECRET_KEY" #f))
  region: (region (getenv "AWS_DEFAULT_REGION" "us-east-1")))

If access-key or secret-key aren’t passed in and cannot be retrieved from the environment (via AWS_ACCESS_KEY_ID and AWS_SECRET_KEY respectively) a S3Error is raised.

4.17.11.2 Client

The S3 interface has the following signature:

(interface S3
  (get-bucket (name :~ string?))
  (create-bucket! (name :~ string?))
  (delete-bucket! (name :~ string?))
  (bucket-exists? (name :~ string?))
  (list-buckets))

4.17.11.3 S3-get-bucket

(S3-get-bucket client bucket-name) -> S3Bucket

S3-get-bucket retrieves a S3Bucket instance by name. If the bucket does not exist, a S3Error is raised. Buckets are searched for in the service and region provided to S3Client’s endpoint and region arguments.

4.17.11.4 S3-create-bucket!

(S3-create-bucket! client bucket-name) -> S3Bucket

S3-create-bucket! creates a new bucket in the service and region the client was instantiated with. If a bucket with the name already exists, a S3Error is raised indicating there was a conflict. If the bucket is successfully created, an instance of S3Bucket corresponding to the newly created bucket is returned.

4.17.11.5 S3-delete-bucket!

(S3-delete-bucket! client bucket-name) -> void

S3-delete-bucket! attempts to delete a bucket with the given name. delete-bucket! is idempotent and will not error if the bucket does not exist.

4.17.11.6 S3-bucket-exists?

(S3-bucket-exists? client bucket-name) -> bool

S3-bucket-exists? checks if a bucket with the provided name exists in the client’s configured region and endpoint. It returns #t if a bucket exists and #f otherwise.

4.17.11.7 S3-list-buckets

(S3-list-buckets client) -> list : S3Bucket

S3-list-buckets returns a list of all buckets available to the client as configured. If none are available, an empty list is returned. All buckets are instances of S3Bucket.

4.17.11.8 S3Bucket

The S3Bucket interface provides a consistent way to interact with buckets.

(interface S3Bucket
  (get  (name :~ string?))
  (exists? (name :~ string?))
  (put! (name :~ string?)
        (data :~ u8vector?))
  (delete! (name :~ string?))
  (copy-to! (src :~ string?) (dest :~ string?))
  (list-objects))

4.17.11.9 S3Bucket-get

(S3Bucket-get bucket object-name) -> u8vector

S3Bucket-get retrieves a object by name. If the object does not exist or the client does not have permission to retrieve the object, an S3Error is raised.

4.17.11.10 S3Bucket-exists?

(S3Bucket-exists? bucket object-name) -> bool

S3Bucket-exists? checks if an object with the provided name exists within the bucket. It returns #t if an object exists and #f otherwise.

4.17.11.11 S3Bucket-put!

(S3Bucket-put! bucket object-name) -> void

S3Bucket-put! stores data in a object with the provided name. Any failures result in a S3Error being raised. All data is stored with content-type: "octet-stream" MIME type.

4.17.11.12 S3Bucket-delete!

(S3Bucket-delete! bucket object-name) -> void

S3Bucket-delete! delete’s an object with the provided name. If the object does not exist, an S3Error is raised.

4.17.11.13 S3Bucket-copy-to!

(S3Bucket-copy-to! bucket src dest) -> void

S3Bucket-copy-to! performs server-side copy of object described by src. The src format is <bucket>/<objectname>. The dest is the same as if performing a put! and will store the object in the current S3Bucket. Copies must be within a region and otherwise possible to perform using the S3 client this bucket was created with. Any failures result in a S3Error being raised.

4.17.11.14 S3Bucket-list-objects

(S3Bucket-list-objects bucket) -> list : string

S3Bucket-list-objects enumerates all objects in the bucket, returning their names as strings.