v1.0.0

Author: lpil

CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## v1.0.0 - 2024-09-04
+
+- Initial release with create_bucket, delete_bucket, delete_object,
+  delete_objects, get_object, head_bucket, head_object, list_buckets,
+  list_objects, and put_object.

README.md

@@ -1,24 +1,58 @@
 # bucket
 
+Gleam S3 API client, suitable for AWS S3, Garage, Minio, Storj,
+Backblaze B2, Cloudflare R2, Ceph, Wasabi, and so on!
+
 [![Package Version](https://img.shields.io/hexpm/v/bucket)](https://hex.pm/packages/bucket)
 [![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/bucket/)
 
+This package uses the _sans-io_ approach, meaning it does not send HTTP requests
+itself, instead it gives you functions for creating HTTP requests for and
+decoding HTTP responses from an S3 API, and you send the requests with a HTTP
+client of your choosing.
+
+This HTTP client independence gives you full control over HTTP, and means this
+library can be used on both the Erlang and JavaScript runtimes.
+
 ```sh
 gleam add bucket@1
 ```
 ```gleam
 import bucket
+import bucket/get_object.{Found}
+import gleam/bit_array
+import gleam/http.{Https}
+import gleam/io
+import httpc
 
+/// This program downloads an object and prints the string contents.
+///
+/// It uses `let assert` to handle errors, but in a real program you'd most
+/// likely want to use pattern matching or the `gleam/result` module to handle
+/// the error values gracefully.
+///
 pub fn main() {
-  // TODO: An example of the project in use
-}
-```
+  let creds = bucket.credentials(
+    host: "s3-api-host.example.com",
+    access_key_id: "YOUR_ACCESS_KEY",
+    secret_access_key: "YOUR_SECRET_ACCESS_KEY",
+  )
 
-Further documentation can be found at <https://hexdocs.pm/bucket>.
+  // Create a HTTP request to download an object
+  let request =
+    get_object.request(bucket: "my-bucket", key: "my/key.txt")
+    |> get_object.build()
 
-## Development
+  // Send the HTTP request
+  let assert Ok(response) = httpc.send_bits(request)
 
-```sh
-gleam run   # Run the project
-gleam test  # Run the tests
+  // Decode the response from the API
+  let assert Ok(Found(object)) = get_object.response(response)
+
+  // Print the string contents
+  let assert Ok(text) = bit_array.from_string(object)
+  io.println(text)
+}
 ```
+
+Further documentation can be found at <https://hexdocs.pm/bucket>.

gleam.toml

@@ -1,16 +1,11 @@
 name = "bucket"
 version = "1.0.0"
-
-# Fill out these fields if you intend to generate HTML documentation or publish
-# your project to the Hex package manager.
-#
-# description = ""
-# licences = ["Apache-2.0"]
-# repository = { type = "github", user = "", repo = "" }
-# links = [{ title = "Website", href = "" }]
-#
-# For a full reference of all the available options, you can have a look at
-# https://gleam.run/writing-gleam/gleam-toml/.
+description = "Gleam S3 API client, suitable for AWS S3, Garage, Minio, Storj, Backblaze B2, Cloudflare R2, Ceph, Wasabi, and so on!"
+licences = ["Apache-2.0"]
+repository = { type = "github", user = "lpil", repo = "antigone" }
+links = [
+  { title = "Sponsor", href = "https://github.com/sponsors/lpil" },
+]
 
 [dependencies]
 gleam_stdlib = ">= 0.34.0 and < 2.0.0"

src/bucket.gleam

@@ -9,6 +9,7 @@ pub type BucketError {
   S3Error(http_status: Int, error: ErrorObject)
 }
 
+/// An error from S3.
 pub type ErrorObject {
   ErrorObject(
     code: String,
@@ -18,6 +19,7 @@ pub type ErrorObject {
   )
 }
 
+/// The creds used to connect to an S3 API.
 pub type Credentials {
   Credentials(
     scheme: Scheme,
@@ -29,6 +31,36 @@ pub type Credentials {
   )
 }
 
+pub fn credentials(
+  host: String,
+  access_key_id: String,
+  secret_access_key: String,
+) -> Credentials {
+  Credentials(
+    host:,
+    access_key_id:,
+    secret_access_key:,
+    region: "eu-west-1",
+    port: option.None,
+    scheme: http.Https,
+  )
+}
+
+/// Set the region for the credentials.
+pub fn with_region(creds: Credentials, region: String) -> Credentials {
+  Credentials(..creds, region:)
+}
+
+/// Set the port for the credentials.
+pub fn with_port(creds: Credentials, port: Int) -> Credentials {
+  Credentials(..creds, port: option.Some(port))
+}
+
+/// Set the scheme for the credentials. You should use HTTPS unless not possible.
+pub fn with_scheme(creds: Credentials, scheme: http.Scheme) -> Credentials {
+  Credentials(..creds, scheme:)
+}
+
 pub type Bucket {
   Bucket(name: String, creation_date: String)
 }

src/bucket/create_bucket.gleam

@@ -8,6 +8,7 @@ import gleam/option.{type Option}
 import gleam/string_builder
 import xmb
 
+/// The parameters for the API request
 pub type RequestBuilder {
   RequestBuilder(name: String, region: Option(String))
 }

src/bucket/delete_bucket.gleam

@@ -5,6 +5,7 @@ import gleam/http/request.{type Request, Request}
 import gleam/http/response.{type Response}
 import gleam/option.{type Option}
 
+/// The parameters for the API request
 pub type RequestBuilder {
   RequestBuilder(name: String, expected_bucket_owner: Option(String))
 }

src/bucket/delete_object.gleam

@@ -4,6 +4,7 @@ import gleam/http
 import gleam/http/request.{type Request, Request}
 import gleam/http/response.{type Response}
 
+/// The parameters for the API request
 pub type RequestBuilder {
   RequestBuilder(bucket: String, key: String)
 }

src/bucket/delete_objects.gleam

@@ -12,6 +12,7 @@ import gleam/result
 import gleam/string_builder
 import xmb
 
+/// The parameters for the API request
 pub type RequestBuilder {
   RequestBuilder(bucket: String, objects: List(ObjectIdentifier))
 }

src/bucket/get_object.gleam

@@ -6,6 +6,7 @@ import gleam/http
 import gleam/http/request.{type Request, Request}
 import gleam/http/response.{type Response}
 
+/// The parameters for the API request
 pub type RequestBuilder {
   RequestBuilder(bucket: String, key: String)
 }

src/bucket/head_bucket.gleam

@@ -7,6 +7,7 @@ import gleam/http/request.{type Request, Request}
 import gleam/http/response.{type Response}
 import gleam/option.{type Option}
 
+/// The parameters for the API request
 pub type RequestBuilder {
   RequestBuilder(name: String, expected_bucket_owner: Option(String))
 }

src/bucket/head_object.gleam

@@ -7,6 +7,7 @@ import gleam/http/request.{type Request, Request}
 import gleam/http/response.{type Response}
 import gleam/option.{type Option}
 
+/// The parameters for the API request
 pub type RequestBuilder {
   RequestBuilder(
     bucket: String,

src/bucket/list_buckets.gleam

@@ -14,6 +14,7 @@ pub type ListAllMyBucketsResult {
   )
 }
 
+/// The parameters for the API request
 pub type RequestBuilder {
   RequestBuilder(continuation_token: Option(String), max_buckets: Option(Int))
 }

src/bucket/list_objects.gleam

@@ -15,6 +15,7 @@ pub type Object {
   Object(key: String, last_modified: String, etag: String, size: Int)
 }
 
+/// The parameters for the API request
 pub type RequestBuilder {
   RequestBuilder(
     bucket: String,

src/bucket/put_object.gleam

@@ -10,6 +10,7 @@ pub type PutObjectResult {
   PutObjectResult(etag: String)
 }
 
+/// The parameters for the API request
 pub type RequestBuilder {
   RequestBuilder(bucket: String, key: String, body: BitArray)
 }