awskit-s3

AWS S3 client surface for bucket/object storage operations, multipart uploads, S3 presigned URLs, and opaque bucket policy documents.

See awskit for the pure core and runtime adapter overview.

The public entrypoint is Awskit_s3. Implementation modules, XML codecs, request builders, and response parsers are private.

Client Surface

awskit-s3 provides an AWS S3 client surface for bucket and object storage applications:

• object put, get, head, delete, copy, list, metadata, tags, ranges, checksums, conditional requests, version IDs, and version listings
• multipart upload, multipart part listing, and local-file transfer helpers in Unix-capable adapters
• S3 presigned URLs for object and multipart upload-part workflows
• bucket lifecycle needed to create, locate, inspect, and remove buckets
• bucket configuration helpers for policy, CORS, encryption, tagging, and versioning
• endpoint configuration, credentials, retries, pagination, streaming contracts, and structured error classifiers

Bucket policy operations use opaque JSON policy documents, which lets applications provision bucket-level access rules while keeping policy document construction in application code.

API Shape

Object APIs are split into explicit layers:

• primitive streaming operations under Object
• bounded in-memory helpers under Object
• local-path helpers under Object.Transfer in Unix-capable adapter packages

Primitive operations never expose string bodies as the primary API. Request bodies and response body readers come from the selected runtime adapter.

Libraries

awskit-s3

Awskit_s3 contains pure types, S3 endpoint configuration, standalone presigned URL helpers, and the runtime functor.

Main modules:

• Awskit_s3.Object — object types, options, metadata records, checksums, preconditions, object versioning, and object tagging result types
• Awskit_s3.Bucket — bucket result types and bucket configuration records
• Awskit_s3.Multipart — multipart upload identifiers, parts, options, and result records
• Awskit_s3.Transfer — high-level upload/download options, limits, strategy results, and multipart transfer result records
• Awskit_s3.Presigned — pure presigned URL generation
• Awskit_s3.Policy — validated opaque bucket policy JSON payloads
• Awskit_s3.Make — functor for wiring S3 operations to a custom Awskit.Runtime.S implementation

awskit-s3-sim

Awskit_s3_sim provides a deterministic in-memory S3 implementation for tests. It implements the same synchronous S3 operation shape as runtime-backed clients and adds a controllable clock, store inspection, operation history, and fault injection.

awskit-s3-eio

Awskit_s3_eio provides a direct-style Eio adapter. Operations return plain results. It also exposes local-path helpers under Object.Transfer.

awskit-s3-lwt

Awskit_s3_lwt provides a functor over Cohttp_lwt.S.Client. Operations return Lwt.t.

awskit-s3-lwt-unix

Awskit_s3_lwt_unix provides the ready-to-use Lwt + Unix adapter. It can read credentials and region from the standard AWS environment variables through the underlying awskit-lwt-unix runtime.

Minimal Eio Example

open Eio.Std

let run env =
  Switch.run @@ fun sw ->
  let credentials =
    Awskit.Credentials.create_exn
      ~access_key_id:"AKIAIOSFODNN7EXAMPLE"
      ~secret_access_key:"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
      ()
  in
  let region = Awskit.Region.of_string_exn "us-east-1" in
  let s3 = Awskit_s3_eio.create ~sw ~env ~region ~credentials () in
  match
    Awskit_s3_eio.Object.put_string s3
      ~bucket:"my-bucket"
      ~key:"hello.txt"
      "Hello, S3!"
  with
  | Ok _ -> ()
  | Error err -> Fmt.epr "%a@." Awskit_s3.Error.pp err

Minimal Lwt Unix Example

let run () =
  let open Lwt.Syntax in
  match Awskit_s3_lwt_unix.create () with
  | Error err ->
      Lwt_io.eprintf "%s\n" (Awskit_s3.Error.to_string_hum err)
  | Ok s3 ->
      let* result =
        Awskit_s3_lwt_unix.Object.get_as_string s3
          ~bucket:"my-bucket"
          ~key:"hello.txt"
          ~max_bytes:1_048_576L
          ()
      in
      match result with
      | Ok (_info, body) -> Lwt_io.printl body
      | Error err -> Lwt_io.eprintf "%a\n" Awskit_s3.Error.pp err

Guides

• S3 Guides — objects, buffers, transfers, endpoint setup, buckets, multipart, presigning, and errors