Enum cfn_resource_provider::CfnRequest

pub enum CfnRequest<P> where
    P: Clone,  {
    Create {
        request_id: String,
        response_url: String,
        resource_type: String,
        logical_resource_id: String,
        stack_id: String,
        resource_properties: P,
    },
    Delete {
        request_id: String,
        response_url: String,
        resource_type: String,
        logical_resource_id: String,
        stack_id: String,
        physical_resource_id: String,
        resource_properties: P,
    },
    Update {
        request_id: String,
        response_url: String,
        resource_type: String,
        logical_resource_id: String,
        stack_id: String,
        physical_resource_id: String,
        resource_properties: P,
        old_resource_properties: P,
    },
}

On stack modification, AWS CloudFormation sends out a request for custom resources. This enum can represent such a request, encapsulating the three request variants:

1. Creation of a custom resource.
2. Update of a custom resource.
3. Deletion of a custom resource.

(For more information on AWS CloudFormation custom resource requests, see docs.aws.amazon.com.)

When creating/updating a custom resource, AWS CloudFormation forwards any additional key-value pairs the template designer provided with the request. To enable strict typing on this data, CfnRequest has the generic type parameter P which the caller provides. This has to be a deserializable type.

Example

The following is an example on how one can create a type that is deserializable through Serde, such that the untyped JSON map object provided by AWS CloudFormation can be converted into a strongly typed struct. (If the JSON is not compatible with the struct, deserialization and thus modification of the custom resource fails.)

#[derive(Debug, PartialEq, Clone, Deserialize)]
struct MyResourceProperties {
    parameter1: String,
    parameter2: Vec<String>,
}
let actual = serde_json::from_value(json!(
    {
        "parameter1": "example for the first parameter",
        "parameter2": ["list", "of", "values"]
    }
)).unwrap();

let expected = MyResourceProperties {
    parameter1: "example for the first parameter".to_owned(),
    parameter2: vec!["list".to_owned(), "of".to_owned(), "values".to_owned()],
};

assert_eq!(expected, actual);

Required presence of resource properties

If you have read the AWS CloudFormation documentation on custom resource requests, you might have seen that the ResourceProperties field on a request sent by AWS CloudFormation can be optional, whereas all variants in this enum seem to require the field to be present.

The reason for the field being optional is (presumably) that AWS CloudFormation wants to support custom resources that do not require additional parameters besides the ones automatically sent by AWS CloudFormation, i.e. a custom resource might be just fine with only the stack ID.

Where this reasoning falls short, and where the documentation contradicts itself, is when it comes to updating resources. For update requests it is documented that the OldResourceProperties field is mandatory. Now, what happens if you update a resource that previously didn't have any properties? Will the OldResourceProperties field be present as the documentation requires it to be, although it cannot have any (reasonable) content?

For this reason, and for the sake of simplicity in usage and implementation, the user of this library can decide whether they want all property fields to be required or optional. You have at least four options:

1. If your custom resource requires additional properties to function correctly, simply provide your type T as-is.

2. If you want your resource to support custom resource properties, but not to depend on them, you can provide an Option<T> instead.

3. Should you not need custom resource properties at all, but want the deserialization of the request to fail if any are provided, you can specify Option<()>.

4. If you don't need custom resource properties and don't want to fail should they have been provided, you can specify Ignored as the type. This is a custom struct included in this library that deserializes any and no data into itself. This means that any data provided by AWS CloudFormation will be discarded, but it will also not fail if no data was present.

License attribution

The documentation for the CfnRequest enum-variants and their fields has been taken unmodified from the AWS CloudFormation Custom Resource Reference, which is licensed under CC BY-SA 4.0.

Variants

Create

Custom resource provider requests with RequestType set to "Create" are sent when the template developer creates a stack that contains a custom resource. See docs.aws.amazon.com for more information.

Fields of Create

request_id: String

A unique ID for the request.

response_url: String

The response URL identifies a presigned S3 bucket that receives responses from the custom resource provider to AWS CloudFormation.

resource_type: String

The template developer-chosen resource type of the custom resource in the AWS CloudFormation template. Custom resource type names can be up to 60 characters long and can include alphanumeric and the following characters: _@-.

logical_resource_id: String

The template developer-chosen name (logical ID) of the custom resource in the AWS CloudFormation template.

stack_id: String

The Amazon Resource Name (ARN) that identifies the stack that contains the custom resource.

resource_properties: P

This field contains the contents of the Properties object sent by the template developer. Its contents are defined by the custom resource provider.

Delete

Custom resource provider requests with RequestType set to "Delete" are sent when the template developer deletes a stack that contains a custom resource. To successfully delete a stack with a custom resource, the custom resource provider must respond successfully to a delete request. See docs.aws.amazon.com for more information.

Fields of Delete

request_id: String

A unique ID for the request.

response_url: String

The response URL identifies a presigned S3 bucket that receives responses from the custom resource provider to AWS CloudFormation.

resource_type: String

The template developer-chosen resource type of the custom resource in the AWS CloudFormation template. Custom resource type names can be up to 60 characters long and can include alphanumeric and the following characters: _@-.

logical_resource_id: String

The template developer-chosen name (logical ID) of the custom resource in the AWS CloudFormation template.

stack_id: String

The Amazon Resource Name (ARN) that identifies the stack that contains the custom resource.

physical_resource_id: String

A required custom resource provider-defined physical ID that is unique for that provider.

resource_properties: P

This field contains the contents of the Properties object sent by the template developer. Its contents are defined by the custom resource provider.

Update

Custom resource provider requests with RequestType set to "Update" are sent when there's any change to the properties of the custom resource within the template. Therefore, custom resource code doesn't have to detect changes because it knows that its properties have changed when Update is being called. See docs.aws.amazon.com for more information.

Fields of Update

request_id: String

A unique ID for the request.

response_url: String

The response URL identifies a presigned S3 bucket that receives responses from the custom resource provider to AWS CloudFormation.

resource_type: String

The template developer-chosen resource type of the custom resource in the AWS CloudFormation template. Custom resource type names can be up to 60 characters long and can include alphanumeric and the following characters: _@-.

logical_resource_id: String

The template developer-chosen name (logical ID) of the custom resource in the AWS CloudFormation template.

stack_id: String

The Amazon Resource Name (ARN) that identifies the stack that contains the custom resource.

physical_resource_id: String

A required custom resource provider-defined physical ID that is unique for that provider.

resource_properties: P

This field contains the contents of the Properties object sent by the template developer. Its contents are defined by the custom resource provider.

old_resource_properties: P

The resource property values that were previously declared by the template developer in the AWS CloudFormation template.

Implementations

impl<P> CfnRequest<P> where
    P: PhysicalResourceIdSuffixProvider + Clone, 

pub fn request_id(&self) -> String

The request ID field exists for all variants of the CfnRequest enum. This is a helper method to access this field without requiring you to match for the variant yourself.

pub fn response_url(&self) -> String

The response URL field exists for all variants of the CfnRequest enum. This is a helper method to access this field without requiring you to match for the variant yourself.

pub fn resource_type(&self) -> String

The resource type field exists for all variants of the CfnRequest enum. This is a helper method to access this field without requiring you to match for the variant yourself.

pub fn logical_resource_id(&self) -> String

The logical resource ID field exists for all variants of the CfnRequest enum. This is a helper method to access this field without requiring you to match for the variant yourself.

pub fn stack_id(&self) -> String

The stack ID field exists for all variants of the CfnRequest enum. This is a helper method to access this field without requiring you to match for the variant yourself.

pub fn physical_resource_id(&self) -> String

The physical resource ID field either exists or has to be (re)generated for all variants of the CfnRequest enum. This is a helper method to access this field without requiring you to match for the variant yourself, while always getting the correct and up-to-date physical resource ID.

pub fn resource_properties(&self) -> &P

The resource properties field exists for all variants of the CfnRequest enum. This is a helper method to access this field without requiring you to match for the variant yourself.

pub fn into_response<S>(self, result: &Result<Option<S>, Error>) -> CfnResponse where
    S: Serialize, 

This method turns a CfnRequest into a CfnResponse, choosing one of the Success or Failed variants based on a Result. A CfnResponse should always be created through this method to ensure that all the relevant response-fields that AWS CloudFormation requires are populated correctly.

Trait Implementations

impl<P: Clone> Clone for CfnRequest<P> where
    P: Clone, 

fn clone(&self) -> CfnRequest<P>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<P: Debug> Debug for CfnRequest<P> where
    P: Clone, 

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, P> Deserialize<'de> for CfnRequest<P> where
    P: Clone,
    P: Deserialize<'de>, 

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<P: PartialEq> PartialEq<CfnRequest<P>> for CfnRequest<P> where
    P: Clone, 

fn eq(&self, other: &CfnRequest<P>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &CfnRequest<P>) -> bool

This method tests for !=.

impl<P> StructuralPartialEq for CfnRequest<P> where
    P: Clone,