[−][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 '_'.
Type | Field | Tests |
---|---|---|
ARN | partition | Either "aws" or "aws-{identifier}". |
ARN | service | Must be an identifier. |
ARN | region | Must be an identifier. |
ARN | account_id | A 12 character, ASCII digit, String. |
ARN | resource | Below. |
Resource | id | Must not contain ':', '/', or '*' |
Resource | path | Must not contain ':' |
Resource | the_type | Must not contain ':', '/' |
Resource | qualifier | Must 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 derivedSerialize
andDeserialize
implementations for theARN
andResource
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.
Name | Type | Required | Comments |
---|---|---|---|
name | identifier | Yes | Service name, e.g. "s3" |
resource_type | identifier | No | Resource type, optional |
partition_required | boolean | Yes | Must you specify a partition |
region_required | boolean | Yes | Must you specify a region |
region_wc_allowed | boolean | No | Wildcard, '*' character is allowed in a region string, default is false |
account_id_required | boolean | Yes | Must you specify an account ID |
account_wc_allowed | boolean | No | Wildcard, '*' character is allowed in a region string, default is false |
resource_format | enum | Yes | Defines the required format for the resource portion |
resource_wc_allowed | boolean | No | Wildcard, '*' 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 |
Resource | Contains the resource part of the ARN. There must be a |