Use path allowed API for testing multipath

Author: huitema

picohttp/democlient.c

@@ -633,6 +633,9 @@ int picoquic_demo_client_callback(picoquic_cnx_t* cnx,
 
         break;
     }
+    case picoquic_callback_next_path_allowed:
+        /* This event should be handled according to the application's requirements */
+        break;
     default:
         /* unexpected */
         break;

picohttp/democlient.h

@@ -88,6 +88,10 @@ typedef struct st_picoquic_demo_client_callback_ctx_t {
     int no_print;
     int connection_ready;
     int connection_closed;
+
+    /* Context extension for handling asynchronous creation of paths */
+    void (*handle_path_allowed)(picoquic_cnx_t* cnx, void* ctx);
+    void* path_allowed_context;
 } picoquic_demo_callback_ctx_t;
 
 picoquic_alpn_enum picoquic_parse_alpn(char const * alpn);

picoquic/frames.c

@@ -498,10 +498,13 @@ const uint8_t* picoquic_decode_new_connection_id_frame(picoquic_cnx_t* cnx, cons
         else {
             uint64_t transport_error = picoquic_add_remote_cnxid_to_stash(cnx, remote_cnxid_stash, retire_before,
                 sequence, cid_length, cnxid_bytes, secret_bytes, NULL);
-            if (transport_error == 0 && remote_cnxid_stash->retire_cnxid_before < retire_before) {
-                /* retire the now deprecated CIDs */
-                remote_cnxid_stash->retire_cnxid_before = retire_before;
-                transport_error = picoquic_remove_not_before_cid(cnx, unique_path_id, retire_before, current_time);
+            if (transport_error == 0) {
+                picoquic_test_and_signal_new_path_allowed(cnx);
+                if (remote_cnxid_stash->retire_cnxid_before < retire_before) {
+                    /* retire the now deprecated CIDs */
+                    remote_cnxid_stash->retire_cnxid_before = retire_before;
+                    transport_error = picoquic_remove_not_before_cid(cnx, unique_path_id, retire_before, current_time);
+                }
             }
             if (transport_error != 0) {
                 picoquic_connection_error(cnx, transport_error,

picoquic/picoquic.h

@@ -104,6 +104,12 @@ extern "C" {
 #define PICOQUIC_ERROR_PATH_ID_INVALID (PICOQUIC_ERROR_CLASS + 60)
 #define PICOQUIC_ERROR_RETRY_NEEDED (PICOQUIC_ERROR_CLASS + 61)
 #define PICOQUIC_ERROR_SERVER_BUSY (PICOQUIC_ERROR_CLASS + 62)
+#define PICOQUIC_ERROR_PATH_DUPLICATE (PICOQUIC_ERROR_CLASS + 63)
+#define PICOQUIC_ERROR_PATH_ID_BLOCKED (PICOQUIC_ERROR_CLASS + 64)
+#define PICOQUIC_ERROR_PATH_CID_BLOCKED (PICOQUIC_ERROR_CLASS + 65)
+#define PICOQUIC_ERROR_PATH_ADDRESS_FAMILY (PICOQUIC_ERROR_CLASS + 66)
+#define PICOQUIC_ERROR_PATH_NOT_READY (PICOQUIC_ERROR_CLASS + 67)
+#define PICOQUIC_ERROR_PATH_LIMIT_EXCEEDED (PICOQUIC_ERROR_CLASS + 68)
 
 /*
  * Protocol errors defined in the QUIC spec
@@ -274,7 +280,8 @@ typedef enum {
     picoquic_callback_path_deleted, /* An existing path has been deleted */
     picoquic_callback_path_quality_changed, /* Some path quality parameters have changed */
     picoquic_callback_path_address_observed, /* The peer has reported an address for the path */
-    picoquic_callback_app_wakeup /* wakeup timer set by application has expired */
+    picoquic_callback_app_wakeup, /* wakeup timer set by application has expired */
+    picoquic_callback_next_path_allowed /* There are enough path_id and connection ID available for the next path */
 } picoquic_call_back_event_t;
 
 typedef struct st_picoquic_tp_prefered_address_t {
@@ -858,6 +865,47 @@ void picoquic_set_rejected_version(picoquic_cnx_t* cnx, uint32_t rejected_versio
  * Like all user-level networking API, the "probe new path" API assumes that the
  * port numbers in the socket addresses structures are expressed in network order.
  * 
+ * If an error occurs during a call to picoquic_probe_new_path_ex,
+ * the function returns an error code describing the issue:
+ * 
+ *   PICOQUIC_ERROR_PATH_DUPLICATE: there is already an existing path with
+ *   the same 4 tuple. This error only happens if the multipath extensions
+ *   are not negotiated, because the multipath extensions allow creation of
+ *   multiple paths with the same 4 tuple.
+ * 
+ *   PICOQUIC_ERROR_PATH_ID_BLOCKED: when using the multipath extension,
+ *   the peers manage a max_path_id value. The code cannot create a new path
+ *   if the path_id would exceed the limit negotiated with the peer. Applications
+ *   encountering that error code should wait until the peer has increased the limit.
+ *   They may want to signal the issue to the peer by queuing a PATHS_BLOCKED frame.
+ * 
+ *   PICOQUIC_ERROR_PATH_CID_BLOCKED: when using the multipath extension,
+ *   the peers use NEW_PATH_CONNECTION_ID frame to provide CIDs associated with each
+ *   valid path_id. The error occurs when the peer has not yet provided CIDs for the
+ *   next path_id. Applications encountering the error should wait until the peer
+ *   provides CID for the path. They may want to signal the issue to the peer by
+ *   queuing a PATH_CIDS_BLOCKED frame.
+ * 
+ *   PICOQUIC_ERROR_PATH_ADDRESS_FAMILY: API error. The application is trying
+ *   to use a four tuple with different address family for source and destination.
+ * 
+ *   PICOQUIC_ERROR_PATH_NOT_READY: API error. The application is trying to create
+ *   paths before the connection handshake is complete. The application should wait
+ *   until it is notified that the connection is ready.
+ * 
+ *   PICOQUIC_ERROR_PATH_LIMIT_EXCEEDED: The application is trying to create more
+ *   simultaneous paths than allowed. It will need to close one of the existing paths
+ *   before creating a new one.
+ * 
+ * The errors PICOQUIC_ERROR_PATH_ID_BLOCKED, PICOQUIC_ERROR_PATH_CID_BLOCKED.
+ * PICOQUIC_ERROR_PATH_NOT_READY and PICOQUIC_ERROR_PATH_LIMIT_EXCEEDED are transient.
+ * The application can use the `picoquic_check_new_path_allowed` API to check whether
+ * a new path may be created. This function will return 1 if the path creation
+ * can be attempted immediately, 0 otherwise. If the return code is 0, the stack
+ * will issue a callback `picoquic_callback_next_path_ready` when the transient
+ * issues are resolved and `picoquic_probe_new_path_ex` could be called
+ * again.
+ * 
  * Path event callbacks can be enabled by calling "picoquic_enable_path_callbacks".
  * This can be set as the default for new connections by calling
  * "picoquic_enable_path_callbacks_default". If enabled, the folling events
@@ -893,10 +941,9 @@ void picoquic_set_rejected_version(picoquic_cnx_t* cnx, uint32_t rejected_versio
  * maintain path data in an app specific context, it will use a call to
  * "picoquic_set_app_path_ctx" to document it. The path created during
  * the connection setup has the unique_path_id 0.
- 
- * 
+ *
  * If an error occurs, such as reference to an obsolete unique path id,
- * all the functions return -1.
+ * all the path management functions return -1.
  * 
  * The call to "refresh the connection ID" will trigger a renewal of the connection
  * ID used for sending packets on that path. This API is mostly used in test
@@ -918,6 +965,8 @@ int picoquic_abandon_path(picoquic_cnx_t* cnx, uint64_t unique_path_id,
 int picoquic_refresh_path_connection_id(picoquic_cnx_t* cnx, uint64_t unique_path_id);
 int picoquic_set_stream_path_affinity(picoquic_cnx_t* cnx, uint64_t stream_id, uint64_t unique_path_id);
 int picoquic_set_path_status(picoquic_cnx_t* cnx, uint64_t unique_path_id, picoquic_path_status_enum status);
+int picoquic_subscribe_new_path_allowed(picoquic_cnx_t* cnx, int* is_already_allowed);
+
 /* The get path addr API provides the IP addresses used by a specific path.
 * The "local" argument determines whether the APi returns the local address
 * (local == 1), the address of the peer (local == 2) or the address observed by the peer (local == 3).

picoquic/picoquic_internal.h

@@ -1313,6 +1313,8 @@ typedef struct st_picoquic_cnx_t {
     unsigned int is_forced_probe_up_required : 1; /* application wants "probe up" if CC requests it */
     unsigned int is_address_discovery_provider : 1; /* send the address discovery extension */
     unsigned int is_address_discovery_receiver : 1; /* receive the address discovery extension */
+    unsigned int is_subscribed_to_path_allowed : 1; /* application wants to be advised if it is now possible to create a path */
+    unsigned int is_notified_that_path_is_allowed : 1; /* application wants to be advised if it is now possible to create a path */
 
     /* PMTUD policy */
     picoquic_pmtud_policy_enum pmtud_policy;
@@ -2043,6 +2045,8 @@ const uint8_t* picoquic_skip_path_abandon_frame(const uint8_t* bytes, const uint
 const uint8_t* picoquic_skip_path_available_or_standby_frame(const uint8_t* bytes, const uint8_t* bytes_max);
 int picoquic_queue_path_available_or_standby_frame(
     picoquic_cnx_t* cnx, picoquic_path_t* path_x, picoquic_path_status_enum status);
+/* Internal only API, notify that next path is now allowed. */
+void picoquic_test_and_signal_new_path_allowed(picoquic_cnx_t* cnx);
 
 int picoquic_decode_closing_frames(picoquic_cnx_t* cnx, uint8_t* bytes, size_t bytes_max, int* closing_received);
 

picoquic/quicctx.c

@@ -1793,10 +1793,14 @@ void picoquic_delete_abandoned_paths(picoquic_cnx_t* cnx, uint64_t current_time,
         }
     }
 
-    while (cnx->nb_paths > path_index_good) {
-        int d_path = cnx->nb_paths - 1;
-        picoquic_dereference_stashed_cnxid(cnx, cnx->path[d_path], 0);
-        picoquic_delete_path(cnx, d_path);
+    if (cnx->nb_paths > path_index_good) {
+        do {
+            int d_path = cnx->nb_paths - 1;
+            picoquic_dereference_stashed_cnxid(cnx, cnx->path[d_path], 0);
+            picoquic_delete_path(cnx, d_path);
+        }  while (cnx->nb_paths > path_index_good);
+        /* If paths have been deleted, it may become possible to create new ones. */
+        picoquic_test_and_signal_new_path_allowed(cnx);
     }
 
     /* TODO: what if there are no paths left? */
@@ -2094,52 +2098,164 @@ int picoquic_assign_peer_cnxid_to_path(picoquic_cnx_t* cnx, int path_index)
     return ret;
 }
 
-/* Create a new path in order to trigger a migration */
-int picoquic_probe_new_path_ex(picoquic_cnx_t* cnx, const struct sockaddr* addr_peer,
-    const struct sockaddr* addr_local, int if_index, uint64_t current_time, int to_preferred_address)
+/* Check whether the connection state, number of paths, path ID and
+* available CID will allow creation of a new path
+*/
+int picoquic_check_new_path_allowed(picoquic_cnx_t* cnx, int to_preferred_address)
 {
     int ret = 0;
-    int partial_match_path = -1;
-    int path_id = -1;
 
-    if ((cnx->remote_parameters.migration_disabled && !to_preferred_address ) ||
+    if ((cnx->remote_parameters.migration_disabled && !to_preferred_address) ||
         cnx->local_parameters.migration_disabled) {
         /* Do not create new paths if migration is disabled */
-        ret = PICOQUIC_ERROR_MIGRATION_DISABLED;
         DBG_PRINTF("Tried to create probe with migration disabled = %d", cnx->remote_parameters.migration_disabled);
+        ret = PICOQUIC_ERROR_MIGRATION_DISABLED;
     }
-    else if ((path_id = picoquic_find_path_by_address(cnx, addr_local, addr_peer, &partial_match_path)) >= 0) {
-        /* This path already exists. Will not create it, but will restore it in working order if disabled. */
-        ret = -1;
-    }
-    else if (partial_match_path >= 0 && addr_peer->sa_family == 0) {
-        /* This path already exists. Will not create it, but will restore it in working order if disabled. */
-        ret = -1;
-    }
-    else if (cnx->first_remote_cnxid_stash->cnxid_stash_first == NULL) {
-        /* No CNXID available yet. */
-        ret = -1;
+    else if (cnx->cnx_state < picoquic_state_client_almost_ready) {
+        ret = PICOQUIC_ERROR_PATH_NOT_READY;
     }
     else if (cnx->nb_paths >= PICOQUIC_NB_PATH_TARGET) {
         /* Too many paths created already */
-        ret = -1;
+        ret = PICOQUIC_ERROR_PATH_LIMIT_EXCEEDED;
     }
-    else if (picoquic_create_path(cnx, current_time, addr_local, addr_peer, UINT64_MAX) > 0) {
-        path_id = cnx->nb_paths - 1;
-        ret = picoquic_assign_peer_cnxid_to_path(cnx, path_id);
+    else {
+        /* testing availability of connection ID is sufficient.
+         * If multipath is enabled, connection IDs will
+         * only be received if both peers have negotiated a sufficient path ID.
+         * In any case, connection IDs can only be received if the connection
+         * is almost ready.
+         */
+        uint64_t unique_path_id = 0;
+        if (cnx->is_multipath_enabled) {
+            unique_path_id = cnx->unique_path_id_next;
+        }
+        if (picoquic_obtain_stashed_cnxid(cnx, unique_path_id) == NULL) {
+            if (cnx->unique_path_id_next > cnx->max_path_id_remote) {
+                ret = PICOQUIC_ERROR_PATH_ID_BLOCKED;
+            }
+            else
+            {
+                ret = PICOQUIC_ERROR_PATH_CID_BLOCKED;
+            }
+        }
+    }
+    return ret;
+}
 
-        if (ret != 0) {
-            /* delete the path that was just created! */
-            picoquic_dereference_stashed_cnxid(cnx, cnx->path[path_id], 0);
-            picoquic_delete_path(cnx, path_id);
+int picoquic_subscribe_new_path_allowed(picoquic_cnx_t* cnx, int * is_already_allowed)
+{
+    int ret = picoquic_check_new_path_allowed(cnx, 0);
+
+    *is_already_allowed = 0;
+    if (ret == 0) {
+        /* is allowed. Just say so -- get return code. */
+        *is_already_allowed = 1;
+        cnx->is_subscribed_to_path_allowed = 0;
+        cnx->is_notified_that_path_is_allowed = 0;
+    }
+    else if (ret == PICOQUIC_ERROR_PATH_NOT_READY ||
+        ret == PICOQUIC_ERROR_PATH_LIMIT_EXCEEDED ||
+        ret == PICOQUIC_ERROR_PATH_ID_BLOCKED ||
+        ret == PICOQUIC_ERROR_PATH_CID_BLOCKED) {
+        /* transient error. Subscribe to the event and return 0 */
+        cnx->is_subscribed_to_path_allowed = 1;
+        cnx->is_notified_that_path_is_allowed = 0;
+        ret = 0;
+    }
+    return ret;
+}
+
+/* Internal only API, notify that next path is now allowed. */
+void picoquic_test_and_signal_new_path_allowed(picoquic_cnx_t* cnx)
+{
+    if (cnx->is_subscribed_to_path_allowed &&
+        !cnx->is_notified_that_path_is_allowed)
+    {
+        if (picoquic_check_new_path_allowed(cnx, 0) == 0) {
+            cnx->is_notified_that_path_is_allowed = 1;
+            if (cnx->callback_fn != NULL) {
+                (void)cnx->callback_fn(cnx, 0, NULL, 0, picoquic_callback_next_path_allowed, cnx->callback_ctx, NULL);
+            }
+        }
+    }
+}
+
+/* Create a new path in order to trigger a migration, or just a parallel
+* path if multipath is enabled.
+ */
+int picoquic_probe_new_path_ex(picoquic_cnx_t* cnx, const struct sockaddr* addr_peer,
+    const struct sockaddr* addr_local, int if_index, uint64_t current_time, int to_preferred_address)
+{
+    int partial_match_path = -1;
+    int path_id = -1;
+
+    int ret = picoquic_check_new_path_allowed(cnx, to_preferred_address);
+
+
+    if (ret == 0) {
+        /* verify that the peer and local addresses are correctly set */
+        if (addr_peer == NULL || addr_peer->sa_family == 0) {
+            if (addr_local == NULL || addr_local->sa_family == 0) {
+                ret = PICOQUIC_ERROR_UNEXPECTED_ERROR;
+            }
+            else {
+                /* Find the peer address from existing paths */
+                for (int i = 0; i < cnx->nb_paths; i++) {
+                    if (cnx->path[i]->peer_addr.ss_family == addr_local->sa_family) {
+                        addr_peer = (struct sockaddr*)&cnx->path[i]->peer_addr;
+                        break;
+                    }
+                }
+                if (addr_peer == NULL || addr_peer->sa_family == 0) {
+                    ret = PICOQUIC_ERROR_UNEXPECTED_ERROR;
+                }
+            }
+        }
+        else if (addr_local == NULL || addr_local->sa_family == 0) {
+            /* Find the local address from existing paths */
+            for (int i = 0; i < cnx->nb_paths; i++) {
+                if (cnx->path[i]->local_addr.ss_family == addr_peer->sa_family) {
+                    addr_local = (struct sockaddr*)&cnx->path[i]->local_addr;
+                    break;
+                }
+            }
+            if (addr_peer == NULL) {
+                ret = PICOQUIC_ERROR_UNEXPECTED_ERROR;
+            }
+        }
+        else if (addr_peer->sa_family != addr_local->sa_family) {
+            ret = PICOQUIC_ERROR_PATH_ADDRESS_FAMILY;
+        }
+    }
+
+    if (ret == 0 && !cnx->is_multipath_enabled) {
+        if ((path_id = picoquic_find_path_by_address(cnx, addr_local, addr_peer, &partial_match_path)) >= 0) {
+            /* This path already exists. Will not create it, but will restore it in working order if disabled. */
+            ret = PICOQUIC_ERROR_PATH_DUPLICATE;
+        }
+    }
+
+    if (ret == 0){
+        if (picoquic_create_path(cnx, current_time, addr_local, addr_peer, UINT64_MAX) > 0) {
+            path_id = cnx->nb_paths - 1;
+            ret = picoquic_assign_peer_cnxid_to_path(cnx, path_id);
+
+            if (ret != 0) {
+                /* delete the path that was just created! */
+                picoquic_dereference_stashed_cnxid(cnx, cnx->path[path_id], 0);
+                picoquic_delete_path(cnx, path_id);
+            }
+            else {
+                cnx->path[path_id]->path_is_published = 1;
+                picoquic_register_path(cnx, cnx->path[path_id]);
+                picoquic_set_path_challenge(cnx, path_id, current_time);
+                cnx->path[path_id]->path_is_preferred_path = to_preferred_address;
+                cnx->path[path_id]->is_nat_challenge = 0;
+                cnx->path[path_id]->if_index_dest = if_index;
+            }
         }
         else {
-            cnx->path[path_id]->path_is_published = 1;
-            picoquic_register_path(cnx, cnx->path[path_id]);
-            picoquic_set_path_challenge(cnx, path_id, current_time);
-            cnx->path[path_id]->path_is_preferred_path = to_preferred_address;
-            cnx->path[path_id]->is_nat_challenge = 0;
-            cnx->path[path_id]->if_index_dest = if_index;
+            ret = PICOQUIC_ERROR_MEMORY;
         }
     }