Dual-Stack Endpoints and IPv6 ICE Candidates

.github/workflows/samples.yaml

@@ -17,6 +17,10 @@ jobs:
     env:
       AWS_KVS_LOG_LEVEL: 2
 
+    strategy:
+      matrix:
+        endpoint-type: [ "legacy", "dual-stack" ]
+
     permissions:
       id-token: write
       contents: read
@@ -36,6 +40,15 @@ jobs:
           role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
           aws-region: ${{ secrets.AWS_REGION }}
 
+      - name: Set endpoint type
+        run: |
+          if [ "${{ matrix.endpoint-type }}" = "dual-stack" ]; then
+            echo "Using dual-stack endpoints"
+            echo "USE_DUAL_STACK_ENDPOINTS=ON" >> $GITHUB_ENV
+          else
+            echo "Using legacy endpoints"
+          fi
+
       - name: Build repository
         run: |
           mkdir build && cd build

CMake/Dependencies/libkvsCommonLws-CMakeLists.txt

@@ -6,7 +6,7 @@ include(ExternalProject)
 
 ExternalProject_Add(libkvsCommonLws-download
     GIT_REPOSITORY    https://github.com/awslabs/amazon-kinesis-video-streams-producer-c.git
-    GIT_TAG           v1.5.4
+    GIT_TAG           v1.6.0
     GIT_PROGRESS      TRUE
     GIT_SHALLOW       TRUE
     PREFIX            ${CMAKE_CURRENT_BINARY_DIR}/build

CMake/Dependencies/libwebsockets-CMakeLists.txt

@@ -63,6 +63,7 @@ ExternalProject_Add(project_libwebsockets
         -DLWS_EXT_PTHREAD_LIBRARIES=${LWS_EXT_PTHREAD_LIBRARIES}
         -DLWS_OPENSSL_INCLUDE_DIRS=${LWS_OPENSSL_INCLUDE_DIRS}
         -DLWS_OPENSSL_LIBRARIES=${LWS_OPENSSL_LIBRARIES}
+        -DLWS_WITH_IPV6=ON
     BUILD_ALWAYS      TRUE
     TEST_COMMAND      ""
 )

README.md

@@ -573,6 +573,8 @@ Similar to the heap profile, you only need to specify the following environment
 
 More information about what environment variables you can configure can be found [here](https://gperftools.github.io/gperftools/cpuprofile.html)
 
+## Additional Features
+
 ### Filtering network interfaces
 
 This is useful to reduce candidate gathering time when it is known for certain network interfaces to not work well. A sample callback is available in `Common.c`. The `iceSetInterfaceFilterFunc` in `KvsRtcConfiguration` must be set to the required callback. In the sample, it can be done this way in `initializePeerConnection()`: 
@@ -632,6 +634,20 @@ The SDK enables generating these stats by default. To control whether the SDK ca
 `configuration.kvsRtcConfiguration.enableIceStats = FALSE`.
 Disabling these stats may lead to reductions in memory use.
 
+### Enabling dual-stack mode
+To use dual-stack AWS KVS endpoints and attempt to gather IPv6 ICE candidates, set the following environment variable:
+```
+export KVS_DUALSTACK_ENDPOINTS=ON
+```
+
+In dual-stack mode, ICE gathering will attempt to include IPv6 candidates, but compatibility ultimately depends on the local network configuration and the capabilities of the receiving peers.
+
+
+To disable dual-stack mode, unset the environment variable:
+```
+unset KVS_DUALSTACK_ENDPOINTS
+```
+
 ## Documentation
 All Public APIs are documented in our [Include.h](https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-c/blob/main/src/include/com/amazonaws/kinesis/video/webrtcclient/Include.h), we also generate a [Doxygen](https://awslabs.github.io/amazon-kinesis-video-streams-webrtc-sdk-c/) each commit for easier navigation.
 

samples/Common.c

@@ -370,11 +370,23 @@ STATUS initializePeerConnection(PSampleConfiguration pSampleConfiguration, PRtcP
 #endif
 
     // Set the  STUN server
-    PCHAR pKinesisVideoStunUrlPostFix = KINESIS_VIDEO_STUN_URL_POSTFIX;
-    // If region is in CN, add CN region uri postfix
-    if (STRSTR(pSampleConfiguration->channelInfo.pRegion, "cn-")) {
-        pKinesisVideoStunUrlPostFix = KINESIS_VIDEO_STUN_URL_POSTFIX_CN;
+    PCHAR pKinesisVideoStunUrlPostFix = NULL;
+    if (GETENV(USE_DUAL_STACK_ENDPOINTS_ENV_VAR) != NULL) {
+        DLOGD("Using dual-stack STUN endpoint");
+        if (STRSTR(pSampleConfiguration->channelInfo.pRegion, "cn-")) {
+            pKinesisVideoStunUrlPostFix = KINESIS_VIDEO_DUALSTACK_STUN_URL_POSTFIX_CN;
+        } else {
+            pKinesisVideoStunUrlPostFix = KINESIS_VIDEO_DUALSTACK_STUN_URL_POSTFIX;
+        }
+    } else {
+        DLOGD("Using legacy STUN endpoint");
+        if (STRSTR(pSampleConfiguration->channelInfo.pRegion, "cn-")) {
+            pKinesisVideoStunUrlPostFix = KINESIS_VIDEO_STUN_URL_POSTFIX_CN;
+        } else {
+            pKinesisVideoStunUrlPostFix = KINESIS_VIDEO_STUN_URL_POSTFIX;
+        }
     }
+
     SNPRINTF(configuration.iceServers[0].urls, MAX_ICE_CONFIG_URI_LEN, KINESIS_VIDEO_STUN_URL, pSampleConfiguration->channelInfo.pRegion,
              pKinesisVideoStunUrlPostFix);
 
@@ -398,6 +410,8 @@ STATUS initializePeerConnection(PSampleConfiguration pSampleConfiguration, PRtcP
                  * It's recommended to not pass too many TURN iceServers to configuration because it will slow down ice gathering in non-trickle mode.
                  */
 
+                DLOGD("TURN server %d urls: %s", j + 1, pIceConfigInfo->uris[j]);
+
                 STRNCPY(configuration.iceServers[uriCount + 1].urls, pIceConfigInfo->uris[j], MAX_ICE_CONFIG_URI_LEN);
                 STRNCPY(configuration.iceServers[uriCount + 1].credential, pIceConfigInfo->password, MAX_ICE_CONFIG_CREDENTIAL_LEN);
                 STRNCPY(configuration.iceServers[uriCount + 1].username, pIceConfigInfo->userName, MAX_ICE_CONFIG_USER_NAME_LEN);

src/include/com/amazonaws/kinesis/video/webrtcclient/Include.h

@@ -475,6 +475,11 @@ extern "C" {
  */
 #define MAX_SIGNALING_ENDPOINT_URI_LEN 512
 
+/**
+ * Maximum allowed Control Plane URI length
+ */
+#define MAX_CONTROL_PLANE_URI_CHAR_LEN 256
+
 /**
  * Maximum allowed correlation ID length
  */
@@ -690,6 +695,11 @@ extern "C" {
  */
 #define WEBRTC_THREADPOOL_MAX_THREADS_ENV_VAR (PCHAR) "AWS_KVS_WEBRTC_THREADPOOL_MAX_THREADS"
 
+/**
+ * Env to control whether to use dual stack endpoints, unset means false
+ */
+#define USE_DUAL_STACK_ENDPOINTS_ENV_VAR ((PCHAR) "KVS_DUALSTACK_ENDPOINTS")
+
 #ifdef _WIN32
 /**
  * Default timeout for sending data
@@ -737,12 +747,14 @@ extern "C" {
 /**
  * Parameterized string for KVS STUN Server
  */
-#define KINESIS_VIDEO_STUN_URL_POSTFIX       "amazonaws.com"
-#define KINESIS_VIDEO_STUN_URL_POSTFIX_CN    "amazonaws.com.cn"
-#define KINESIS_VIDEO_STUN_URL_PREFIX        "stun."
-#define KINESIS_VIDEO_STUN_URL_PREFIX_LENGTH 5
-#define KINESIS_VIDEO_STUN_URL               "stun:stun.kinesisvideo.%s.%s:443"
-#define KINESIS_VIDEO_STUN_URL_WITHOUT_PORT  "stun.kinesisvideo.%s.%s"
+#define KINESIS_VIDEO_STUN_URL_POSTFIX              "amazonaws.com"
+#define KINESIS_VIDEO_STUN_URL_POSTFIX_CN           "amazonaws.com.cn"
+#define KINESIS_VIDEO_STUN_URL_PREFIX               "stun."
+#define KINESIS_VIDEO_STUN_URL_PREFIX_LENGTH        5
+#define KINESIS_VIDEO_STUN_URL                      "stun:stun.kinesisvideo.%s.%s:443"
+#define KINESIS_VIDEO_STUN_URL_WITHOUT_PORT         "stun.kinesisvideo.%s.%s"
+#define KINESIS_VIDEO_DUALSTACK_STUN_URL_POSTFIX    "api.aws"
+#define KINESIS_VIDEO_DUALSTACK_STUN_URL_POSTFIX_CN "api.amazonwebservices.com.cn"
 
 /**
  * Default signaling SSL port