Crate s3s 

S3 Service Adapter

s3s is an ergonomic adapter for building S3-compatible services. It implements the Amazon S3 REST API as a generic hyper service, allowing S3-compatible services to focus on the S3 API itself without worrying about the HTTP layer.

Features

• S3 REST API Implementation: Comprehensive support for Amazon S3 REST API
• HTTP Layer Abstraction: Built on top of hyper and tower
• Type Safety: Generated data types from AWS Smithy models
• Authentication: Support for AWS Signature Version 4 and Version 2
• Flexible Configuration: Customizable service configuration with hot-reload support
• Extensibility: Custom routes, access control, and validation

Architecture

The s3s crate converts HTTP requests to S3 operation inputs, calls user-defined services, and converts operation outputs or errors back to HTTP responses. This allows you to implement just the S3 business logic while s3s handles all the HTTP protocol details.

Getting Started

To build an S3-compatible service:

1. Implement the S3 trait for your service
2. Create an S3Service using S3ServiceBuilder
3. Configure optional components (auth, access control, etc.)
4. Serve the service using hyper or your favorite HTTP framework

Example

use s3s::{S3, S3Request, S3Response, S3Result};
use s3s::service::S3ServiceBuilder;
use s3s::dto::{GetObjectInput, GetObjectOutput};

// 1. Implement the S3 trait
#[derive(Clone)]
struct MyS3Service;

#[async_trait::async_trait]
impl S3 for MyS3Service {
    async fn get_object(
        &self,
        req: S3Request<GetObjectInput>
    ) -> S3Result<S3Response<GetObjectOutput>> {
        // Your implementation here
        Err(s3s::s3_error!(NotImplemented))
    }
    // Implement other S3 operations as needed
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 2. Create the S3 service
    let service = S3ServiceBuilder::new(MyS3Service).build();

    // 3. Serve it (example with hyper)
    // See the examples directory for complete server implementations
    Ok(())
}

Modules

• service: Core service implementation and builder
• auth: S3 authentication (Signature V4, Signature V2)
• access: Access control and authorization
• config: Service configuration and settings
• dto: Data transfer objects (generated from AWS Smithy models)
• host: Virtual host parsing and handling
• route: Custom route support
• validation: Bucket and object name validation
• stream: Streaming utilities
• checksum: Checksum algorithms
• crypto: Cryptographic utilities
• header: HTTP header handling
• path: S3 path handling
• post_policy: POST object policy support
• region: AWS region name type
• xml: XML serialization/deserialization

Security

⚠️ Important: S3Service and other adapters in this crate have no built-in security protection. If exposed to the Internet directly, they may be vulnerable to attacks.

It is the user’s responsibility to implement security enhancements such as:

• HTTP body length limits
• Rate limiting
• Back pressure
• Network-level security (firewalls, VPNs, etc.)

Examples

The crate includes several examples demonstrating different use cases:

• axum: Integration with the Axum web framework
• https: Running an S3 service with HTTPS/TLS
• See the examples directory for more

Integration with aws-sdk-s3

For integration with the official AWS SDK and useful types, see the s3s-aws crate.

Sample Implementation

For a sample implementation and testing, see the s3s-fs crate, which implements the S3 API on top of a file system.

Modules

access

Access control and authorization

auth

S3 Authentication

checksum

Multi-algorithm checksum computation for S3 objects.

config

S3 Service Configuration

crypto

Checksum and hash primitives used by S3 signature verification and checksum computation.

dto

S3 data transfer objects (DTOs).

header

S3-specific HTTP header name constants.

host

Virtual-host parsing for S3 request routing.

path

A path in the S3 storage.

post_policy

POST Object policy parsing and validation.

region

S3 region handling

route

Custom route support

service

S3 Service and Builder

stream

Byte-stream types for S3 request and response bodies.

validation

Validation API for S3 bucket names.

xml

XML serialization and deserialization for S3 request and response bodies.

Macros

s3_error

Structs

Body

HttpError

An error that indicates a failure of an HTTP request. Passing this error to hyper will cause it to abort the connection.

S3Error

S3Operation

S3Request

S3 request

S3Response

S3 response

TrailingHeaders

Trailing headers handle (newtype)

Enums

S3ErrorCode

Traits

S3

An async trait which represents the S3 API

Type Aliases

HttpRequest

HttpResponse

S3Result

StdError