Crate aws-arn

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

The ARN 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 ARNs with validators but also constructors that allow making these strings correclt in the first place.

ARN Types

This crate provides a number of levels of ARN manipulation, the first is the direct construction of an ARN 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 ARN string into an ARN 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 ARN you don't always need and uses a more fluent style of ARN 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 (ARN) 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 ARN and Resource types. This feature is enabled by default.

Changes

Version 0.3.1

• Added unit tests for AccountIdentifier.

Version 0.3.0

• Breaking Change: Renamed ARN to ResourceName.
• Breaking Change: Renamed ArnError to Error.
• Added interface for common Identifier operations.
• Added variable expansion for ResourceIdentifier and ResourceName.
• Added more unit tests.

Version 0.2.1

• Created a new AccountIdentifier type for the 12-digit value.
• consts feature renamed known.

Version 0.2.0

• Relaxed validation of identifiers and resource identifiers.
• Removed Resource type which added a lot of the validation confusion.
• Using new Identifier and ResourceIdentifier types to construct correct ARN values without the need for any external validation methods.
• Replaced ResourceBuilder with one for ResourceIdentifier values.
• Removed ext_validation feature
• Added consts feature
• Placed builder module into new builders feature.
• Added a lot more tests including an examples.txt file that is just a long list to be parsed.
• Fixed Github issue-2.

Version 0.1.1

• Documentation additions and fixes, in both README and Rustdoc.
• Renamed service builder functions, added a parent/child pattern for s3.
• Added Serde feature.
• Made external validation optional.

Version 0.1.0

• Initial commit.
• Provides basic ARN type with Display and FromStr.
• Provides scaffolding for service-specific validation.
• Provides initial set of service builder, make_{format}, functions for ARN construction.

TODO

• More tests!
• More service formats for validation.
• More service builder functions.