Crate aws_arn

Provides types, builders, and other helpers to manipulate AWS Amazon Resource Name (ResourceName) strings.

The ResourceName is a key component of all AWS service APIs and yet nearly all client toolkits treat it simply as a string. While this may be a reasonable and expedient decision, it seems there might be a need to not only ensure correctness of ResourceNames with validators but also constructors that allow making these strings correclt in the first place.

ResourceName Types

This crate provides a number of levels of ResourceName manipulation, the first is the direct construction of an ResourceName type using the core ResourceName, Identifier, AccountIdentifier, and ResourceIdentifier types.

use aws_arn::{ResourceName, ResourceIdentifier};
use aws_arn::known::{Partition, Service};
use std::str::FromStr;

let arn = ResourceName {
    partition: Some(Partition::default().into()),
    service: Service::S3.into(),
    region: None,
    account_id: None,
    resource: ResourceIdentifier::from_str("mythings/thing-1").unwrap()
};

In the example above, as we are defining a minimal ResourceName we could use one of the defined constructor functions.

use aws_arn::{ResourceName, ResourceIdentifier};
use aws_arn::known::Service;
use std::str::FromStr;

let arn = ResourceName::aws(
    Service::S3.into(),
    ResourceIdentifier::from_str("mythings/thing-1").unwrap()
);

Alternatively, using FromStr, you can parse an existing ResourceName string into an ResourceName value.

use aws_arn::ResourceName;
use std::str::FromStr;

let arn: ResourceName = "arn:aws:s3:::mythings/thing-1"
    .parse()
    .expect("didn't look like an ResourceName");

Another approach is to use a more readable builder which also allows you to ignore those fields in the ResourceName you don’t always need and uses a more fluent style of ResourceName construction.

use aws_arn::builder::{ArnBuilder, ResourceBuilder};
use aws_arn::known::{Partition, Service};
use aws_arn::{ResourceName, Identifier, IdentifierLike};
use std::str::FromStr;

let arn: ResourceName = ArnBuilder::service_id(Service::S3.into())
    .resource(ResourceBuilder::named(Identifier::from_str("mythings").unwrap())
        .resource_name(Identifier::new_unchecked("my-layer"))
        .build_resource_path())
    .in_partition_id(Partition::Aws.into())
    .into();

Finally, it is possible to use resource-type specific functions that allow an even more direct and simple construction (module aws_arn::builder::{service} - service builder functions, although at this time there are few supported services.

use aws_arn::builder::s3;
use aws_arn::Identifier;
use std::str::FromStr;

let arn = s3::object(
    Identifier::from_str("mythings").unwrap(),
    Identifier::from_str("thing-1").unwrap(),
);

For more, see the AWS documentation for Amazon Resource Name (ResourceName) documentation.

Optional Features

This crate has attempted to be as lean as possible, with a really minimal set of dependencies, we have include the following capabilities as optional features.

• builders adds the builder module. This feature is enabled by default, it also requires the known feature.
• known adds a module containing enums for partitions, regions, and services. This feature is enabled by default.
• serde_support adds derived Serialize and Deserialize implementations for the ResourceName and Resource types. This feature is enabled by default.

Modules

builder

Provides a more natural builder interface for constructing ResourceNames.

known

Provides enums that represent known values for ARN partition, region, and service identifiers.

Structs

AccountIdentifier

A string value that is used to capture the account ID component of an ResourceName. These are ASCII digits only and a fixed length of 12 characters.

Identifier

A string value that is used to capture the partition, service, and region components of an ResourceName. These are ASCII only, may not include control characters, spaces, ‘/’, or ‘:’.

ResourceIdentifier

A string value that is used to capture the resource component of an ResourceName. These are ASCII only, may not include control characters but unlike Identifier they may include spaces, ‘/’, and ‘:’.

ResourceName

Amazon Resource Names (ResourceNames) uniquely identify AWS resources. We require an ResourceName when you need to specify a resource unambiguously across all of AWS, such as in IAM policies, Amazon Relational Database Service (Amazon RDS) tags, and API calls.

Enums

Error

Errors that may arise parsing an ResourceName with FromStr::from_str().

Traits

IdentifierLike

This trait is implemented by the ResourceName component types. It represents a string-based identifier that is generally constructed using FromStr::from_str.