[][src]Crate aws_arn

Provides 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 three levels of ARN manipulation, the first is the direct construction of an ARN type (module aws_arn - the core Resource and ARN types).

use aws_arn::{ARN, Resource};

let arn = ARN {
    partition: Some("aws".to_string()),
    service: "s3".to_string(),
    region: None,
    account_id: None,
    resource: Resource::Path("".to_string())};

One issue with the code above is that, unless you subsequently call arn.validate() the resulting ARN could be garbage. Alternatively, using FromStr, you can parse a string into an ARN which will call validate() for you.

use aws_arn::ARN;
use std::str::FromStr;

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

The next is to use a more readable builder which also allows you to ignore those fields in the ARN you don't always need (module aws_arn::builder - the ResourceBuilder and ArnBuilder types providing a more fluent style of ARN construction).

use aws_arn::builder::{ArnBuilder, ResourceBuilder};

let arn = ArnBuilder::new("s3")
    .resource(ResourceBuilder::new(&format!("{}/{}", "mythings", "thing-1")).build().unwrap())
    .in_partition("aws")
    .build().unwrap();

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.

use aws_arn::builder::s3;

let arn = s3::object("mythings", "thing-1");

For more, see the AWS documentation for Amazon Resource Name (ARN). In a lot of cases the documentation for elements of the ARN and Resource types use descriptions taken directly from the AWS documentation.

Validation

As mentioned above, both the ARN and Resource types have a validate() function that will test for consistency. Also, this validation is optional if you construction these types directly. The validation supported by these two resources is limited to syntactic values, described in the following table. This table mentions identifier as a type, this is a pattern where a string starts with an alphabetic character, then zero or more alphanumeric characters and the characters '-' and '_'.

TypeFieldTests
ARNpartitionEither "aws" or "aws-{identifier}".
ARNserviceMust be an identifier.
ARNregionMust be an identifier.
ARNaccount_idA 12 character, ASCII digit, String.
ARNresourceBelow.
ResourceidMust not contain ':', '/', or '*'
ResourcepathMust not contain ':'
Resourcethe_typeMust not contain ':', '/'
ResourcequalifierMust not contain ':', '/'

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.

  • serde_support adds derived Serialize and Deserialize implementations for the ARN and Resource types.
  • ext_validation adds extended, service specific, validation using an external configuration file.

Extended Validation

The feature ext_validation extends the capability of the ARN::validate() by applying a set of rules for service and resource type pairs, for example S3 buckets or lambda functions. The rules are defined in a configuration file, service-formats.toml in the crate and which is read and the rules applied if a matching configuration is found. The file is structured as a list of [[format]] maps and the following table summarizes the fields in this map.

NameTypeRequiredComments
nameidentifierYesService name, e.g. "s3"
resource_typeidentifierNoResource type, optional
partition_requiredbooleanYesMust you specify a partition
region_requiredbooleanYesMust you specify a region
region_wc_allowedbooleanNoWildcard, '*' character is allowed in a region string, default is false
account_id_requiredbooleanYesMust you specify an account ID
account_wc_allowedbooleanNoWildcard, '*' character is allowed in a region string, default is false
resource_formatenumYesDefines the required format for the resource portion
resource_wc_allowedbooleanNoWildcard, '*' character is allowed in a region string, default is false

Modules

builder

Provides a more natural builder interface for constructing ARNs.

Structs

ARN

Amazon Resource Names (ARNs) uniquely identify AWS resources. We require an ARN 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

ArnError

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

Resource

Contains the resource part of the ARN. There must be a resource-id, there may be a resource-type, and there may be a qualifier. The separator between type and id may be prefix-like (':') or path-like (PATH_SEPARATOR).