#aws #amazon-web-services #arn #resources #string #builder #name

aws-arn

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

6 releases

0.3.1 Jul 8, 2022
0.3.0 Jul 8, 2022
0.2.1 Jun 30, 2022
0.2.0 Apr 9, 2021
0.1.1 Nov 14, 2019

#907 in Network programming

Download history 5278/week @ 2023-12-04 3832/week @ 2023-12-11 5626/week @ 2023-12-18 2121/week @ 2023-12-25 4749/week @ 2024-01-01 5002/week @ 2024-01-08 5986/week @ 2024-01-15 5901/week @ 2024-01-22 4537/week @ 2024-01-29 4101/week @ 2024-02-05 5920/week @ 2024-02-12 4286/week @ 2024-02-19 5403/week @ 2024-02-26 5059/week @ 2024-03-04 6698/week @ 2024-03-11 5582/week @ 2024-03-18

22,886 downloads per month
Used in rops

MIT license

99KB
1.5K SLoC

Crate aws-arn

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

MIT License Minimum Rust Version crates.io docs.rs Build Audit GitHub stars

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.

45Muse aws_arn::builder::{ArnBuilder, ResourceBuilder};
use aws_arn::known::{Partition, Service};
use aws_arn::{ResourceName, Identifier};
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.

Dependencies

~2.1–3.5MB
~57K SLoC