Awskit

Awskit is AWS infrastructure for OCaml.

The core packages are pure: they define credentials, regions, endpoints, Signature Version 4 signing, request and response metadata, retry policy, structured errors, service wire types, and request builders. Runtime packages sit at the edge and provide concrete HTTP execution for Eio or Lwt applications.

The current service surface is AWS S3.

Package Split

Awskit follows a Cohttp-style package split. Install only the runtime adapter you need.

• awskit — pure AWS core: credentials, regions, endpoints, signing, retries, request/response types, errors, and the runtime module type
• awskit-unix — Unix helpers for clocks, environment variables, shared AWS credentials, and config files
• awskit-lwt — generic Lwt runtime adapter over a caller-supplied Cohttp Lwt client
• awskit-lwt-unix — ready-to-use Lwt + Unix runtime adapter
• awskit-eio — ready-to-use direct-style Eio runtime adapter
• awskit-s3 — pure AWS S3 core: buckets, objects, multipart upload, presigned URLs, policies, and endpoint resolution
• awskit-s3-sim — deterministic in-memory S3 implementation for tests
• awskit-s3-lwt — S3 adapter over the generic Awskit Lwt runtime
• awskit-s3-lwt-unix — ready-to-use S3 client for Lwt + Unix
• awskit-s3-eio — ready-to-use S3 client for Eio

The core awskit and awskit-s3 packages do not depend on Unix, Eio, Lwt, or Cohttp runtime packages. awskit-s3-sim is for tests and does not perform HTTP requests. Adapter packages carry runtime dependencies.

Quick Start

For Eio applications:

opam install awskit-s3-eio eio_main

For Lwt + Unix applications:

opam install awskit-s3-lwt-unix

Eio

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 error -> Fmt.epr "%a@." Awskit_s3.Error.pp error

Lwt + Unix

let run () =
  let open Lwt.Syntax in
  match Awskit_s3_lwt_unix.create () with
  | Error error ->
      Lwt_io.eprintf "%a\n" Awskit_s3.Error.pp error
  | 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 error -> Lwt_io.eprintf "%a\n" Awskit_s3.Error.pp error

When arguments are omitted, Unix adapters read standard AWS configuration sources such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION, AWS_DEFAULT_REGION, AWS_PROFILE, AWS_SHARED_CREDENTIALS_FILE, and AWS_CONFIG_FILE. The Lwt Unix runtime also supports ECS/container and EC2 instance metadata credential providers.

Endpoint overrides are explicit. S3-specific endpoint and addressing options are exposed by the S3 adapter create functions.

Package Documentation

• awskit — pure AWS core and runtime adapters
• awskit guides — credentials, endpoints, signing, errors, retries, and adapter selection
• awskit-s3 — AWS S3 objects, buckets, multipart upload, presigned URLs, and policies
• awskit-s3-sim — deterministic in-memory S3 tests
• awskit-s3 guides — S3 operations in depth