/** * @page http_demo coreHTTP * @brief These demos demonstrate usage of the coreHTTP library. * * @section http_demo_plaintext HTTP Plaintext Demo * @brief A demo of the coreHTTP library that establishes a plaintext TCP connection with a server, sends HTTP requests, then logs their responses. * *

* A POSIX socket-based transport interface implementation is used to establish a * plaintext connection over port 80 to an HTTP server. If a connection * failure occurs, then the connection establishment is retried with exponential and jitter backoff. * Once a connection is established, HTTP requests are sent for the following HTTP methods: * `GET`, `HEAD`, `PUT`, and `POST`. The respective responses from each of these * requests are logged. *

* *
* HTTP Plaintext Demo Workflow — Note that these steps are repeated indefinitely *
* @image html http_demo_plaintext.png width=50% * * @section http_demo_basic_tls HTTP Basic TLS Demo * @brief A demo of the coreHTTP library that establishes a TLS connection with server-only authentication, * sends HTTP requests, then logs their responses. * *

* An OpenSSL-based transport interface implementation is used to establish an encrypted * TLS connection over port 443 to an HTTP server. Only the server's certificate * is verified using its respective root CA certificate. If a connection * failure occurs, then the connection establishment is retried with exponential and jitter backoff. * Once a connection is established, HTTP requests are sent for the following HTTP methods: * `GET`, `HEAD`, `PUT`, and `POST`. The respective responses from each of these * requests are logged. *

* *
* HTTP Basic TLS Demo Workflow — Note that these steps are repeated indefinitely *
* @image html http_demo_basic_tls.png width=50% * * @section http_demo_mutual_auth HTTP Mutual Auth Demo * @brief A demo of the coreHTTP library that establishes a TLS connection with both server and client authentication, * sends HTTP requests, then logs their responses. * *

* An OpenSSL-based transport interface implementation is used to establish an encrypted * TLS connection, with both server and client authentication, over port 443 to AWS IoT Core. * Because port 443 is used, the ALPN protocol name must be set to `x-amzn-http-ca`. * If a connection failure occurs, then the connection establishment is retried * with exponential and jitter backoff. *

* *

* After the TLS session is established, a single HTTP POST request is sent that * publishes a message to a topic named `topic` in AWS IoT Core with `qos=1`. * This means that any subscribers to this topic are guaranteed to receive this * message at least once. *

* *
* HTTP Mutual Auth Demo Workflow — Note that these steps are repeated indefinitely *
* @image html http_demo_mutual_auth.png width=50% * * @section http_demo_s3_upload HTTP S3 Upload Demo * @brief A demo of the coreHTTP library that utilizes user-defined pre-signed PUT * and GET URLs to upload a file to the designated S3 object and then verify that * the sizes of the local and uploaded files are equivalent. * *

* An OpenSSL-based transport interface implementation is used to establish an * encrypted TLS connection over port 443 to S3. The host address is extracted from * the pre-signed PUT URL using the third-party http-parser library. Only the * server's certificate is verified using its respective root CA certificate. If a * connection failure occurs, then the connection establishment is retried for limited * attempts with exponential and jitter backoff. *

* *

* Once a connection is established, the PUT URL is parsed again to obtain its path * string, after which an HTTP PUT request is sent to upload a file to the S3 * object. Following the upload, the GET URL is also parsed for its path string, * and an HTTP GET request is sent to obtain and parse the content-range header * returned from the server, containing the size of the uploaded file. This size is * compared against the size of the local file uploaded by the client, to verify * their equivalence. *

* *
* HTTP S3 Upload Demo Workflow *
* @image html http_demo_s3_upload.png width=50% * * @section http_demo_s3_download HTTP S3 Download Demo * @brief A demo of the coreHTTP library that utilizes SigV4 Library to generate * the authorization header added to HTTP requests sent to S3 to download a file in * chunks from the designated S3 object, using range requests. * *

* An OpenSSL-based transport interface implementation is used to establish an encrypted * TLS connection over port 443 to AWS IoT Credential Provider to fetch the temporary * credentials needed to generate the Authorization header via SigV4 Library. * The host address is extracted from the IoT endpoint (provided by the application * as configuration parameter) using the third-party http-parser library. * If a connection failure occurs, then the connection establishment is retried for * limited attempts with exponential and jitter backoff. The HTTP response from AWS * IoT credential provider is parsed to extract credentials using coreJSON Library and passed * to SigV4 library to generate the Authorization header and Signature used to authenticate HTTP * requests sent to S3. *

* *

* Once the credentials are received, the TLS connection to AWS IoT credential provider is terminated. * Another OpenSSL-based transport interface implementation is used to establish an encrypted TLS connection * over port 443 to S3. The host address is extracted from the AWS_S3_URL * (generated with configuration parameters provided by the application) using the third-party * http-parser library. Only the server's certificate is verified using its respective root CA certificate. * If a connection failure occurs, then the connection establishment is retried for limited attempts with * exponential and jitter backoff. *

* *

* Once a connection is established, the AWS_S3_URL is parsed again to obtain its path string, * required HTTP headers including the Authorization header generated using SigV4 library are * added to the HTTP GET request which is sent to obtain and parse the content-range header returned * from the server, containing the size of the uploaded file. Then, using range headers, the application * loops until the entire file is downloaded, requesting a range of bytes (determined by the user buffer length) * on each iteration. *

* *
* HTTP S3 Download Demo Workflow *
* @image html http_demo_s3_download.png width=50% * * @section http_demo_s3_download_multithreaded HTTP Multithreaded S3 Download Demo * @brief A demo of the coreHTTP library that establishes a TLS connection with * S3, and downloads a file in parts using range requests and a pre-signed URL. * *

* An OpenSSL-based transport interface implementation is used to establish an * encrypted TLS connection over port 443 to S3. The host address is extracted * from the pre-signed GET URL using the third-party http-parser library. Only the * server's certificate is verified using its respective root CA certificate. If a * connection failure occurs, then the connection establishment is retried with * exponential and jitter backoff. *

* *

* Once a connection is established, an HTTP thread is * started which makes HTTP requests over the TLS connection. In a loop, the main * thread enqueues range requests for the S3 file on the request queue and * dequeues responses from the response queue as they are ready. The responses * from each of the requests are logged. The loop continues until the entire file * has been requested and received. The HTTP thread services requests from the * request queue and writes the responses to the response queue. *

* * *
* HTTP Multithreaded S3 Download Workflow — Note that this diagram shows an * example where the file is downloaded in three ranges. As it is multithreaded, * these steps may not occur in the same order. *
* @image html http_demo_s3_download_multithreaded.png width=50% */