s3uri: AWS S3 URIs in Rust

s3uri is a Rust library with structs and functions for building and parsing Amazon Web Services S3 URIs.

Installation

cargo add s3uri

Examples

Parsing a URI

s3uri::from_uri parses a string URI and returns a s3uri::S3Uri struct with the bucket name and key set.

let uri = s3uri::from_uri("s3://circus/images/clowns.jpg").unwrap();

assert_eq!(uri.bucket, "circus");
assert!(uri.key.is_some_and(|k| k == "images/clowns.jpg"));

Creating a new URI

To create a new URI from scratch, pass the bucket name to s3uri::from_bucket to get a s3uri::S3Uri struct.

let uri = s3uri::from_bucket("circus");

assert_eq!(uri, "s3://circus/");
assert_eq!(uri.bucket, "circus");
assert!(uri.key.is_none());

Joining keys and key prefixes

Call s3uri::S3Uri::join() to build up the key. Separators will be normalised and added between each segment as-needed.

let images_prefix = s3uri::from_bucket("circus")
    .join("images/");

assert_eq!(images_prefix, "s3://circus/images/");

let clowns_uri = images_prefix
    .join("staff")
    .join("clowns.jpg");

assert_eq!(clowns_uri, "s3://circus/images/staff/clowns.jpg");

Check if a key is a prefix

Call s3uri::S3Key::is_prefix() to check if a key is a prefix (i.e. ends with a /) or not.

let images_uri = s3uri::from_bucket("circus")
    .join("images/");

assert!(images_uri.is_prefix());

let clowns_uri = images_uri.join("clowns.jpg");
assert!(!clowns_uri.is_prefix());

Key leaf

Call s3uri::S3Key::leaf() to get the segment of the key after the final separator.

let images_uri = s3uri::from_bucket("circus")
    .join("images/");

assert_eq!(images_uri.leaf(), Some("images/"));

let clowns_uri = images_uri
    .join("staff")
    .join("clowns.jpg");

assert_eq!(clowns_uri.leaf(), Some("clowns.jpg"));

Author

Hello! 👋 I'm Cariad Eccleston. You can find me at cariad.earth, github.com/cariad, linkedin.com/in/cariad and @cariad.earth on Bluesky.