Add module level documentation

CONTRIBUTING.md

@@ -1,16 +1,16 @@
 # Contributing to `rust-s3`
-We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
+I love your input! I want to make contributing to this project as easy and transparent as possible, whether it's:
 
 - Reporting a bug
 - Discussing the current state of the code
 - Submitting a fix
 - Proposing new features
 
-## We Develop With GitHub
-We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.
+## I Develop With GitHub
+I use GitHub to host code, to track issues and feature requests, as well as accept pull requests.
 
-## We Use [GitHub Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests
-Pull requests are the best way to propose changes to the codebase (we use [GitHub flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests:
+## I Use [GitHub Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests
+Pull requests are the best way to propose changes to the codebase (I use [GitHub flow](https://guides.github.com/introduction/flow/index.html)). I actively welcome your pull requests:
 
 1. Fork the repo and create your branch from `master`.
 2. If you've added code that should be tested, add tests.
@@ -23,7 +23,7 @@ Pull requests are the best way to propose changes to the codebase (we use [GitHu
 In short, when you submit code changes, your submissions are understood to be under the same [MIT License](https://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern.
 
 ## Report Bugs Using GitHub's [Issues](https://github.com/durch/rust-s3/issues)
-We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/durch/rust-s3/issues/new); it's that easy!
+I use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/durch/rust-s3/issues/new).
 
 ## Write Bug Reports With Detail, Background, and Sample Code
 

s3/src/bucket.rs

@@ -1,3 +1,38 @@
+//! # Rust S3 Bucket Operations
+//!
+//! This module provides functionality for interacting with S3 buckets and objects,
+//! including creating, listing, uploading, downloading, and deleting objects. It supports
+//! various features such as asynchronous and blocking operations, multipart uploads,
+//! presigned URLs, and tagging objects.
+//!
+//! ## Features
+//!
+//! The module supports the following features:
+//!
+//! - **blocking**: Enables blocking (synchronous) operations using the `block_on` macro.
+//! - **tags**: Adds support for managing S3 object tags.
+//! - **with-tokio**: Enables asynchronous operations using the Tokio runtime.
+//! - **with-async-std**: Enables asynchronous operations using the async-std runtime.
+//! - **sync**: Enables synchronous (blocking) operations using standard Rust synchronization primitives.
+//!
+//! ## Constants
+//!
+//! - `CHUNK_SIZE`: Defines the chunk size for multipart uploads (8 MiB).
+//! - `DEFAULT_REQUEST_TIMEOUT`: The default request timeout (60 seconds).
+//!
+//! ## Types
+//!
+//! - `Query`: A type alias for `HashMap<String, String>`, representing query parameters for requests.
+//!
+//! ## Structs
+//!
+//! - `Bucket`: Represents an S3 bucket, providing methods to interact with the bucket and its contents.
+//! - `Tag`: Represents a key-value pair used for tagging S3 objects.
+//!
+//! ## Errors
+//!
+//! - `S3Error`: Represents various errors that can occur during S3 operations.
+
 #[cfg(feature = "blocking")]
 use block_on_proc::block_on;
 #[cfg(feature = "tags")]

s3/src/bucket_ops.rs

@@ -1,3 +1,41 @@
+//! This module provides utilities for configuring and managing Amazon S3 buckets, focusing on access control, bucket configuration, and handling responses from the S3 service.
+//! It includes structures for defining bucket access policies (both canned and custom), configuring various bucket properties, and parsing responses from S3 API calls like `ListBuckets`.
+//!
+//! ## Key Components
+//!
+//! - **CannedBucketAcl Enum**
+//!   - Represents standard predefined Amazon S3 access control lists (ACLs) for buckets.
+//!   - Variants include:
+//!     - `Private`: Only the owner has full control.
+//!     - `PublicRead`: Anyone can read objects in the bucket.
+//!     - `PublicReadWrite`: Anyone can read and write objects in the bucket.
+//!     - `AuthenticatedRead`: Only authenticated AWS users can read objects.
+//!     - `Custom(String)`: A custom ACL specified as a string.
+//!   - The `fmt::Display` trait is implemented to easily convert ACL variants into their corresponding string representations for HTTP headers.
+//!
+//! - **BucketAcl Enum**
+//!   - Represents more granular access controls using different types of identifiers:
+//!     - `Id`: A unique user ID.
+//!     - `Uri`: A URI specifying the group granted access.
+//!     - `Email`: An email address specifying the user granted access.
+//!   - The `fmt::Display` implementation allows these ACLs to be formatted as strings suitable for use in HTTP headers.
+//!
+//! - **BucketConfiguration Struct**
+//!   - Encapsulates the configuration for an S3 bucket, including:
+//!     - Optional ACL (`CannedBucketAcl`)
+//!     - Object lock settings
+//!     - Permissions for full control, read, write, and their respective ACLs.
+//!     - The region in which the bucket is located.
+//!   - Provides methods for setting default configurations, setting the region, and adding relevant headers to HTTP requests.
+//!
+//! - **CreateBucketResponse Struct**
+//!   - Represents the response from a bucket creation request, including the bucket reference and HTTP response details.
+//!   - Includes a method `success` to check if the bucket creation was successful (i.e., HTTP status code 200).
+//!
+//! - **ListBucketsResponse Struct**
+//!   - This structure is used to parse and hold the response from the `ListBuckets` API call.
+//!   - Provides methods for retrieving the list of bucket names from the response.
+
 use crate::error::S3Error;
 use crate::{Bucket, Region};
 

s3/src/command.rs

@@ -1,3 +1,24 @@
+//! This module defines and manages various commands used for interacting with Amazon S3, encapsulating common operations such as creating buckets, uploading objects, and managing multipart uploads.
+//! It also provides utilities for calculating necessary metadata (like content length and SHA-256 hashes) required for secure and efficient communication with the S3 service.
+//!
+//! ## Key Components
+//!
+//! - **HttpMethod Enum**
+//!   - Represents HTTP methods used in S3 operations, including `GET`, `PUT`, `DELETE`, `POST`, and `HEAD`.
+//!   - Implements `fmt::Display` for easy conversion to string representations suitable for HTTP requests.
+//!
+//! - **Multipart Struct**
+//!   - Represents a part of a multipart upload, containing the part number and the associated upload ID.
+//!   - Provides methods for constructing a new multipart part and generating a query string for the S3 API.
+//!
+//! - **Command Enum**
+//!   - The core of this module, encapsulating various S3 operations, such as:
+//!     - Object management (`GetObject`, `PutObject`, `DeleteObject`, etc.)
+//!     - Bucket management (`CreateBucket`, `DeleteBucket`, etc.)
+//!     - Multipart upload management (`InitiateMultipartUpload`, `UploadPart`, `CompleteMultipartUpload`, etc.)
+//!   - For each command, you can determine the associated HTTP method using `http_verb()` and calculate the content length or content type using `content_length()` and `content_type()` respectively.
+//!   - The `sha256()` method computes the SHA-256 hash of the request payload, a critical part of S3's security features.
+//!
 use std::collections::HashMap;
 
 use crate::error::S3Error;

s3/src/post_policy.rs

@@ -1,3 +1,31 @@
+//! This module provides functionality for creating and managing S3 POST policies, which are used to generate presigned URLs for securely uploading files to S3 with specific conditions and metadata. It handles the generation of necessary conditions, expiration policies, and signing of the POST policy.
+//!
+//! ## Key Components
+//!
+//! - **PostPolicy Struct**
+//!   - Represents a POST policy that specifies conditions and expiration for an S3 upload.
+//!   - Can be constructed with an expiration time and modified by adding conditions for fields like `key`, `acl`, and more.
+//!   - Supports building a policy with AWS credentials and signing it to generate a `PresignedPost` object.
+//!
+//! - **PostPolicyField Enum**
+//!   - Enumerates various fields that can be included in a POST policy, such as `key`, `acl`, `content-length-range`, and AWS-specific fields like `x-amz-meta-*`.
+//!   - Allows for the addition of custom fields not predefined in the enum.
+//!
+//! - **PostPolicyValue Enum**
+//!   - Represents the value type associated with a `PostPolicyField`, including exact matches, start-with conditions, ranges, and wildcard matches.
+//!
+//! - **PostPolicyExpiration Enum**
+//!   - Defines the expiration of the POST policy, either as a duration from the current time or a specific timestamp.
+//!
+//! - **PresignedPost Struct**
+//!   - Contains the URL and fields necessary for making a POST request to S3, generated after signing a `PostPolicy`.
+//!   - Includes dynamic fields for conditions that vary at upload time, such as the key or content length.
+//!
+//! ## Error Handling
+//!
+//! - **PostPolicyError Enum**
+//!   - Contains error variants that can occur when constructing a POST policy, particularly when there is a mismatch between the expected and provided condition types.
+
 use crate::error::S3Error;
 use crate::utils::now_utc;
 use crate::{signing, Bucket, LONG_DATETIME};

s3/src/signing.rs

@@ -1,6 +1,33 @@
 //! Implementation of [AWS V4 Signing][link]
 //!
 //! [link]: https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html
+//! //! This module implements AWS Signature Version 4 signing, which is used to authenticate requests to Amazon S3 and other AWS services. AWS Signature V4 is a process for adding authentication information to AWS requests. The module provides functions to generate canonical requests, sign them using HMAC-SHA256, and construct the necessary headers or query parameters to authorize requests.
+//!
+//! ## Key Functions
+//!
+//! - **uri_encode**: Encodes a URI according to AWS-specific rules, handling characters that must be percent-encoded.
+//!
+//! - **canonical_uri_string**: Generates a canonical URI string from a given URL, decoding and re-encoding the URL path as required by AWS.
+//!
+//! - **canonical_query_string**: Creates a canonical query string from the query parameters in a URL, ensuring they are sorted and encoded correctly.
+//!
+//! - **canonical_header_string**: Constructs a canonical header string from provided HTTP headers, ensuring they are sorted and formatted as required by AWS.
+//!
+//! - **signed_header_string**: Generates a string of signed headers from the provided headers, which is required for creating the authorization header.
+//!
+//! - **canonical_request**: Assembles the complete canonical request, which is a combination of the HTTP method, URI, query string, headers, and payload hash. This is the core of the AWS signing process.
+//!
+//! - **scope_string**: Generates the AWS scope string, which is used in the signing process to specify the AWS region, service, and request type.
+//!
+//! - **string_to_sign**: Constructs the string to sign, which is a key component in the AWS V4 signing process. This string is hashed and signed with the AWS secret key.
+//!
+//! - **signing_key**: Derives the AWS signing key using the secret key, date, region, and service name. This key is used to sign the string-to-sign.
+//!
+//! - **authorization_header**: Generates the Authorization header value, which includes the credential scope, signed headers, and the request signature. This header must be included in the signed AWS requests.
+//!
+//! - **authorization_query_params_no_sig**: Constructs query parameters for presigned URLs, excluding the final signature. This is used when creating presigned URLs for temporary access to S3 objects.
+//!
+//! - **flatten_queries**: Flattens a map of query parameters into a single query string, ensuring proper encoding.
 
 use std::collections::HashMap;
 use std::str;