aws-s3

AWS S3 client for Kit

Files

Architecture

Request Flow

Package Dependencies

Dependencies

• aws-core

Installation

kit add gitlab.com/kit-lang/packages/kit-aws-s3.git

Usage

import Kit.AwsS3

License

MIT License - see LICENSE for details.

Exported Functions & Types

AWSS3Error

S3 error type with specific variants for different failure modes.

S3Client

S3 client configuration.

Fields: - credentials: AWS credentials for authentication - region: AWS region for the S3 service - endpoint: Custom endpoint URL (empty string for AWS S3) - path-style: Whether to use path-style URLs (bucket/key) instead of virtual-hosted-style (bucket.s3.region.amazonaws.com/key)

ObjectInfo

Metadata for an S3 object.

Fields: - key: The object's key (path) in the bucket - size: Size of the object in bytes - last-modified: ISO 8601 timestamp of last modification - etag: Entity tag (version identifier) of the object

ListObjectsResponse

Response from listing objects in a bucket.

Fields: - objects: List of objects matching the query - is-truncated: Whether more results are available - next-continuation-token: Token for fetching next page (empty if none)

client

Create S3 client for AWS.

Creates a client configured for standard AWS S3 service using virtual-hosted-style URLs.

Parameters:

Returns:

AWS.Credentials -> AWS.Region -> S3Client

creds = AWS.credentials "AKIAIOSFODNN7EXAMPLE" "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
region = {name: "us-west-2"}
s3 = S3.client creds region

client-with-endpoint

Create S3 client with custom endpoint.

Creates a client for S3-compatible storage services like MinIO or LocalStack. Supports both path-style and virtual-hosted-style URLs.

Parameters:

Returns:

AWS.Credentials -> AWS.Region -> String -> Bool -> S3Client

creds = AWS.credentials "minioadmin" "minioadmin"
region = {name: "us-east-1"}
s3 = S3.client-with-endpoint creds region "http://localhost:9000" true

client-from-env

Create client from environment variables.

Reads credentials and configuration from: - AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY: AWS credentials - AWS_REGION: AWS region - AWS_ENDPOINT_URL: Custom endpoint (optional) - AWS_S3_PATH_STYLE: "true" or "1" for path-style URLs (optional)

Returns:

() -> Result S3Client String

match S3.client-from-env()
  | Ok client -> print "Client created successfully"
  | Err err -> print "Failed: ${err}"

get-object

Get object from S3.

Downloads the content of an object from an S3 bucket.

Parameters:

Returns:

S3Client -> String -> String -> Result String AWSS3Error

match S3.get-object client "my-bucket" "data/file.txt"
  | Ok content -> print content
  | Err err -> print "Error: ${err}"

put-object

Put object to S3.

Uploads content to an S3 bucket with default content type.

Parameters:

Returns:

S3Client -> String -> String -> String -> Result () AWSS3Error

match S3.put-object client "my-bucket" "data.txt" "Hello, S3!"
  | Ok _ -> print "Upload successful"
  | Err err -> print "Error: ${err}"

put-object-with-type

Put object with specific content type.

Uploads content to an S3 bucket with a custom content type header.

Parameters:

Returns:

S3Client -> String -> String -> String -> String -> Result () AWSS3Error

json = "{\"name\": \"example\"}"
match S3.put-object-with-type client "my-bucket" "data.json" json "application/json"
  | Ok _ -> print "Upload successful"
  | Err err -> print "Error: ${err}"

delete-object

Delete object from S3.

Removes an object from an S3 bucket. Returns success even if the object doesn't exist (S3 DELETE is idempotent).

Parameters:

Returns:

S3Client -> String -> String -> Result () AWSS3Error

match S3.delete-object client "my-bucket" "old-file.txt"
  | Ok _ -> print "Deleted successfully"
  | Err err -> print "Error: ${err}"

head-object

Check if object exists using HEAD request.

Performs a HEAD request to check for object existence without downloading the content.

Parameters:

Returns:

S3Client -> String -> String -> Result Bool AWSS3Error

match S3.head-object client "my-bucket" "test.txt"
  | Ok true -> print "Object exists"
  | Ok false -> print "Object not found"
  | Err err -> print "Error: ${err}"

exists?

Check if object exists (convenience function).

Simplified wrapper around head-object that returns a boolean.

Parameters:

Returns:

S3Client -> String -> String -> Bool

if S3.exists? client "my-bucket" "test.txt" then
  print "File exists"
else
  print "File not found"

list-objects

List objects in bucket.

Retrieves a list of objects from an S3 bucket with optional prefix filtering. Uses S3 ListObjectsV2 API.

Parameters:

Returns:

S3Client -> String -> String -> Int -> Result ListObjectsResponse AWSS3Error

match S3.list-objects client "my-bucket" "logs/" 100
  | Ok response ->
    print "Found ${List.length response.objects} objects"
    if response.is-truncated then
      print "More results available"
  | Err err -> print "Error: ${err}"

list-objects-continue

List objects with continuation token (for pagination).

Continues a previous list-objects call using a pagination token.

Parameters:

Returns:

S3Client -> String -> String -> Int -> String -> Result ListObjectsResponse AWSS3Error

# Get first page
match S3.list-objects client "my-bucket" "" 1000
  | Ok response ->
    if response.is-truncated then
      # Get next page
      match S3.list-objects-continue client "my-bucket" "" 1000 response.next-continuation-token
        | Ok next-page -> print "Got next page"
        | Err err -> print "Error: ${err}"
  | Err err -> print "Error: ${err}"

create-bucket

Create S3 bucket.

Creates a new S3 bucket in the configured region. For regions other than us-east-1, includes a LocationConstraint in the request body.

Parameters:

Returns:

S3Client -> String -> Result () AWSS3Error

match S3.create-bucket client "my-new-bucket"
  | Ok _ -> print "Bucket created"
  | Err "Bucket already exists" -> print "Bucket exists"
  | Err err -> print "Error: ${err}"

delete-bucket

Delete S3 bucket.

Deletes an S3 bucket. The bucket must be empty before deletion.

Parameters:

Returns:

S3Client -> String -> Result () AWSS3Error

match S3.delete-bucket client "old-bucket"
  | Ok _ -> print "Bucket deleted"
  | Err "Bucket not empty" -> print "Delete objects first"
  | Err err -> print "Error: ${err}"

upload-file

Upload file from local filesystem to S3.

Reads a file from the local filesystem and uploads it to S3 with default content type (application/octet-stream).

Parameters:

Returns:

S3Client -> String -> String -> String -> Result () AWSS3Error

match S3.upload-file client "my-bucket" "data/report.pdf" "/tmp/report.pdf"
  | Ok _ -> print "File uploaded"
  | Err err -> print "Error: ${err}"

download-file

Download file from S3 to local filesystem.

Downloads an object from S3 and writes it to the local filesystem.

Parameters:

Returns:

S3Client -> String -> String -> String -> Result () AWSS3Error

match S3.download-file client "my-bucket" "data/report.pdf" "/tmp/report.pdf"
  | Ok _ -> print "File downloaded"
  | Err err -> print "Error: ${err}"

copy-object

Copy object within S3.

Copies an object from one location to another within S3. The source and destination can be in the same or different buckets. This is a server-side operation that doesn't download the object.

Parameters:

Returns:

S3Client -> String -> String -> String -> String -> Result () AWSS3Error

match S3.copy-object client "src-bucket" "old/file.txt" "dest-bucket" "new/file.txt"
  | Ok _ -> print "Object copied"
  | Err err -> print "Error: ${err}"