Add rabbitmq_aws:api_post_request/4, README cleanup

Author: lukebakken

deps/rabbitmq_aws/README.md

@@ -5,13 +5,13 @@ A fork of [gmr/httpc-aws](https://github.com/gmr/httpc-aws) for use in building
 ## Supported Erlang Versions
 
 [Same as RabbitMQ](http://www.rabbitmq.com/which-erlang.html)
- 
+
 ## Configuration
 
 Configuration for *rabbitmq-aws* is can be provided in multiple ways. It is designed
 to behave similarly to the [AWS Command Line Interface](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)
 with respect to providing region and configuration information. Additionally it
-has two methods, ``rabbitmq_aws:set_region/1`` and ``rabbitmq_aws:set_credentials/2``
+has two methods, `rabbitmq_aws:set_region/1` and `rabbitmq_aws:set_credentials/2`
 to allow for application specific configuration, bypassing the automatic configuration
 behavior.
 
@@ -40,36 +40,36 @@ and [adds defenses against additional vulnerabilities](https://aws.amazon.com/bl
 AWS recommends adopting IMDSv2 and disabling IMDSv1 [by configuring the Instance Metadata Service on the EC2 instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html).
 
 By default *rabbitmq-aws* will attempt to use IMDSv2 first and will fallback to use IMDSv1 if calls to IMDSv2 fail. This behavior can be overridden
-by setting the ``aws.prefer_imdsv2`` setting to ``false``.
+by setting the `aws.prefer_imdsv2` setting to `false`.
 
 ### Environment Variables
 
-As with the AWS CLI, the following environment variables can be used to provide 
+As with the AWS CLI, the following environment variables can be used to provide
 configuration or to impact configuration behavior:
 
- - ``AWS_DEFAULT_PROFILE``
- - ``AWS_DEFAULT_REGION``
- - ``AWS_CONFIG_FILE``
- - ``AWS_SHARED_CREDENTIALS_FILE``
- - ``AWS_ACCESS_KEY_ID``
- - ``AWS_SECRET_ACCESS_KEY``
- 
+ - `AWS_DEFAULT_PROFILE`
+ - `AWS_DEFAULT_REGION`
+ - `AWS_CONFIG_FILE`
+ - `AWS_SHARED_CREDENTIALS_FILE`
+ - `AWS_ACCESS_KEY_ID`
+ - `AWS_SECRET_ACCESS_KEY`
+
 ## API Functions
- 
-  Method                                | Description
- ---------------------------------------|--------------------------------------------------------------------------------------------
- ``rabbitmq_aws:set_region/1``          | Manually specify the AWS region to make requests to.
- ``rabbitmq_aws:set_credentials/2``     | Manually specify the request credentials to use.
- ``rabbitmq_aws:refresh_credentials/0`` | Refresh the credentials from the environment, filesystem, or EC2 Instance Metadata Service.
- ``rabbitmq_aws:ensure_imdsv2_token_valid/0`` | Make sure EC2 IMDSv2 token is active and valid.
- ``rabbitmq_aws:api_get_request/2``           | Perform an AWS service API request.
- ``rabbitmq_aws:get/2``                 | Perform a GET request to the API specifying the service and request path.
- ``rabbitmq_aws:get/3``                 | Perform a GET request specifying the service, path, and headers.
- ``rabbitmq_aws:post/4``                | Perform a POST request specifying the service, path, headers, and body.
- ``rabbitmq_aws:request/5``             | Perform a request specifying the service, method, path, headers, and body.
- ``rabbitmq_aws:request/6``             | Perform a request specifying the service, method, path, headers, body, and ``httpc:http_options().``
- ``rabbitmq_aws:request/7``             | Perform a request specifying the service, method, path, headers, body,  ``httpc:http_options()``, and override the API endpoint. 
- 
+
+  Method                                    | Description
+ -------------------------------------------|--------------------------------------------------------------------------------------------
+ `rabbitmq_aws:set_region/1`                | Manually specify the AWS region to make requests to.
+ `rabbitmq_aws:set_credentials/2`           | Manually specify the request credentials to use.
+ `rabbitmq_aws:refresh_credentials/0`       | Refresh the credentials from the environment, filesystem, or EC2 Instance Metadata Service.
+ `rabbitmq_aws:ensure_imdsv2_token_valid/0` | Make sure EC2 IMDSv2 token is active and valid.
+ `rabbitmq_aws:get/2`                       | Perform a GET request to the API specifying the service and request path.
+ `rabbitmq_aws:get/3`                       | Perform a GET request specifying the service, path, and headers.
+ `rabbitmq_aws:post/4`                      | Perform a POST request specifying the service, path, headers, and body.
+ `rabbitmq_aws:request/5`                   | Perform a request specifying the service, method, path, headers, and body.
+ `rabbitmq_aws:request/6`                   | Perform a request specifying the service, method, path, headers, body, and `httpc:http_options().`
+ `rabbitmq_aws:request/7`                   | Perform a request specifying the service, method, path, headers, body,  `httpc:http_options()`, and override the API endpoint.
+ `rabbitmq_aws:api_get_request/2`           | Perform an AWS service API request with retries.
+ `rabbitmq_aws:api_post_request/2`          | Perform an AWS service API request with retries.
 
 ## Example Usage
 
@@ -80,8 +80,7 @@ you're using the EC2 Instance Metadata Service for credentials:
 application:start(rabbitmq_aws).
 {ok, {Headers, Response}} = rabbitmq_aws:get("ec2","/?Action=DescribeTags&Version=2015-10-01").
 ```
-
-To configure credentials, invoke ``rabbitmq_aws:set_credentials/2``:
+To configure credentials, invoke `rabbitmq_aws:set_credentials/2`:
 
 ```erlang
 application:start(rabbitmq_aws).
@@ -90,8 +89,8 @@ rabbitmq_aws:set_credentials("AKIDEXAMPLE", "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMP
 
 RequestHeaders = [{"Content-Type", "application/x-amz-json-1.0"},
                   {"X-Amz-Target", "DynamoDB_20120810.ListTables"}],
-                  
-{ok, {Headers, Response}} = rabbitmq_aws:post("dynamodb", "/", 
+
+{ok, {Headers, Response}} = rabbitmq_aws:post("dynamodb", "/",
                                               "{\"Limit\": 20}",
                                               RequestHeaders).
 ```

deps/rabbitmq_aws/src/rabbitmq_aws.erl

@@ -19,7 +19,8 @@
     has_credentials/0,
     set_region/1,
     ensure_imdsv2_token_valid/0,
-    api_get_request/2
+    api_get_request/2,
+    api_post_request/4
 ]).
 
 %% gen-server exports
@@ -622,8 +623,10 @@ ensure_credentials_valid() ->
     case has_credentials(State) of
         true ->
             case expired_credentials(State#state.expiration) of
-                true -> refresh_credentials(State);
-                _ -> ok
+                true ->
+                    refresh_credentials(State);
+                _ ->
+                    ok
             end;
         _ ->
             refresh_credentials(State)
@@ -633,19 +636,46 @@ ensure_credentials_valid() ->
 %% @doc Invoke an API call to an AWS service.
 %% @end
 api_get_request(Service, Path) ->
-    ?LOG_DEBUG("Invoking AWS request {Service: ~tp; Path: ~tp}...", [Service, Path]),
-    api_get_request_with_retries(Service, Path, ?MAX_RETRIES, ?LINEAR_BACK_OFF_MILLIS).
+    ?LOG_DEBUG("invoking AWS get request {Service: ~tp; Path: ~tp}...", [Service, Path]),
+    api_request_with_retries(Service, get, Path, "", [],
+                             ?MAX_RETRIES, ?LINEAR_BACK_OFF_MILLIS).
 
--spec api_get_request_with_retries(string(), path(), integer(), integer()) ->
+-spec api_post_request(
+    Service :: string(),
+    Path :: path(),
+    Body :: body(),
+    Headers :: headers()
+) -> result().
+%% @doc Perform a HTTP Post request to the AWS API for the specified service. The
+%%      response will automatically be decoded if it is either in JSON or XML
+%%      format.
+%% @end
+api_post_request(Service, Path, Body, Headers) ->
+    ?LOG_DEBUG("invoking AWS post request {Service: ~tp; Path: ~tp}...", [Service, Path]),
+    api_request_with_retries(Service, post, Path, Body, Headers,
+                             ?MAX_RETRIES, ?LINEAR_BACK_OFF_MILLIS).
+
+-spec api_request_with_retries(
+        Service :: string(),
+        Method :: method(),
+        Path :: path(),
+        Body :: body(),
+        Headers :: headers(),
+        Retries :: integer(),
+        WaitTime :: integer()) ->
     {'ok', list()} | {'error', term()}.
 %% @doc Invoke an API call to an AWS service with retries.
 %% @end
-api_get_request_with_retries(_, _, 0, _) ->
-    ?LOG_WARNING("Request to AWS service has failed after ~b retries", [?MAX_RETRIES]),
+api_request_with_retries(_, _, _, _, _, 0, _) ->
+    ?LOG_ERROR("Request to AWS service has failed after ~b retries", [?MAX_RETRIES]),
     {error, "AWS service is unavailable"};
-api_get_request_with_retries(Service, Path, Retries, WaitTimeBetweenRetries) ->
-    ensure_credentials_valid(),
-    case get(Service, Path) of
+api_request_with_retries(Service, Method, Path, Body, Headers, Retries, WaitTime) ->
+    case ensure_credentials_valid() of
+        ok -> ok;
+        Error ->
+            ?LOG_WARNING("error during credentials check: ~tp", [Error])
+    end,
+    case request(Service, Method, Path, Body, Headers) of
         {ok, {_Headers, Payload}} ->
             ?LOG_DEBUG("AWS request: ~ts~nResponse: ~tp", [Path, Payload]),
             {ok, Payload};
@@ -660,6 +690,6 @@ api_get_request_with_retries(Service, Path, Retries, WaitTimeBetweenRetries) ->
                     ok
             end,
             ?LOG_WARNING("Will retry AWS request, remaining retries: ~b", [Retries]),
-            timer:sleep(WaitTimeBetweenRetries),
-            api_get_request_with_retries(Service, Path, Retries - 1, WaitTimeBetweenRetries)
+            timer:sleep(WaitTime),
+            api_request_with_retries(Service, Method, Path, Body, Headers, Retries - 1, WaitTime)
     end.

deps/rabbitmq_aws/test/rabbitmq_aws_tests.erl

@@ -605,7 +605,7 @@ api_get_request_test_() ->
                 {ok, Pid} = rabbitmq_aws:start_link(),
                 rabbitmq_aws:set_region("us-east-1"),
                 rabbitmq_aws:set_credentials(State),
-                Result = rabbitmq_aws:api_get_request_with_retries("AWS", "API", 3, 1),
+                Result = rabbitmq_aws:api_request_with_retries("AWS", get, "API", "", [], 3, 1),
                 ok = gen_server:stop(Pid),
                 ?assertEqual({error, "AWS service is unavailable"}, Result),
                 meck:validate(httpc)
@@ -638,7 +638,7 @@ api_get_request_test_() ->
                 {ok, Pid} = rabbitmq_aws:start_link(),
                 rabbitmq_aws:set_region("us-east-1"),
                 rabbitmq_aws:set_credentials(State),
-                Result = rabbitmq_aws:api_get_request_with_retries("AWS", "API", 3, 1),
+                Result = rabbitmq_aws:api_request_with_retries("AWS", get, "API", "", [], 3, 1),
                 ok = gen_server:stop(Pid),
                 ?assertEqual({ok, [{"data", "value"}]}, Result),
                 meck:validate(httpc)