First attempt at an async refactoring of the SciTokens library.

This splits operations that may block on network access into a "start"
and "continue" portion.  The start portion returns a status object
which may be queried for information about whether the operation is
finished and information about file descriptors that are useful for
select.

Completely untested but it compiles and is roughly the top-to-bottom
outline of what the async code will look like.

Author: bbockelm

src/scitokens.cpp

@@ -338,7 +338,7 @@ int validator_validate(Validator validator, SciToken scitoken, char **err_msg) {
     auto real_scitoken = reinterpret_cast<scitokens::SciToken*>(scitoken);
 
     try {
-        real_validator->verify(*real_scitoken);
+        real_validator->verify(*real_scitoken, time(NULL) + 20);
     } catch (std::exception &exc) {
         if (err_msg) {*err_msg = strdup(exc.what());}
         return -1;
@@ -388,6 +388,35 @@ void enforcer_set_validate_profile(Enforcer enf, SciTokenProfile profile) {
 }
 
 
+namespace {
+
+Acl *convert_acls(scitokens::Enforcer::AclsList &acls_list, char **err_msg)
+{
+    Acl *acl_result = static_cast<Acl*>(malloc((acls_list.size() + 1)*sizeof(Acl)));
+    size_t idx = 0;
+    for (const auto &acl : acls_list) {
+        acl_result[idx].authz = strdup(acl.first.c_str());
+        acl_result[idx].resource = strdup(acl.second.c_str());
+        if (acl_result[idx].authz == nullptr) {
+            enforcer_acl_free(acl_result);
+            if (err_msg) {*err_msg = strdup("ACL was generated without an authorization set.");}
+            return nullptr;
+        }
+        if (acl_result[idx].resource == nullptr) {
+            enforcer_acl_free(acl_result);
+            if (err_msg) {*err_msg = strdup("ACL was generated without a resource set.");}
+            return nullptr;
+        }
+        idx++;
+    }
+    acl_result[idx].authz = nullptr;
+    acl_result[idx].resource = nullptr;
+    return acl_result;
+}
+
+}
+
+
 int enforcer_generate_acls(const Enforcer enf, const SciToken scitoken, Acl **acls, char **err_msg) {
     if (enf == nullptr) {
         if (err_msg) {*err_msg = strdup("Enforcer may not be a null pointer");}
@@ -407,26 +436,78 @@ int enforcer_generate_acls(const Enforcer enf, const SciToken scitoken, Acl **ac
         if (err_msg) {*err_msg = strdup(exc.what());}
         return -1;
     }
-    Acl *acl_result = static_cast<Acl*>(malloc((acls_list.size() + 1)*sizeof(Acl)));
-    size_t idx = 0;
-    for (const auto &acl : acls_list) {
-        acl_result[idx].authz = strdup(acl.first.c_str());
-        acl_result[idx].resource = strdup(acl.second.c_str());
-        if (acl_result[idx].authz == nullptr) {
-            enforcer_acl_free(acl_result);
-            if (err_msg) {*err_msg = strdup("ACL was generated without an authorization set.");}
-            return -1;
-        }
-        if (acl_result[idx].resource == nullptr) {
-            enforcer_acl_free(acl_result);
-            if (err_msg) {*err_msg = strdup("ACL was generated without a resource set.");}
-            return -1;
-        }
-        idx++;
+    auto result_acls = convert_acls(acls_list, err_msg);
+    if (!result_acls) {return -1;}
+    *acls = result_acls;
+    return 0;
+}
+
+
+int enforcer_generate_acls_start(const Enforcer enf, const SciToken scitoken,
+    SciTokenStatus *status_out, Acl **acls, char **err_msg)
+{
+    if (enf == nullptr) {
+        if (err_msg) {*err_msg = strdup("Enforcer may not be a null pointer");}
+        return -1;
     }
-    acl_result[idx].authz = nullptr;
-    acl_result[idx].resource = nullptr;
-    *acls = acl_result;
+    auto real_enf = reinterpret_cast<scitokens::Enforcer*>(enf);
+    if (scitoken == nullptr) {
+        if (err_msg) {*err_msg = strdup("SciToken may not be a null pointer");}
+        return -1;
+    }
+    auto real_scitoken = reinterpret_cast<scitokens::SciToken*>(scitoken);
+
+    scitokens::Enforcer::AclsList acls_list;
+    std::unique_ptr<scitokens::Validator::AsyncStatus> status;
+    try {
+         status = real_enf->generate_acls_start(*real_scitoken, acls_list);
+    } catch (std::exception &exc) {
+        if (err_msg) {*err_msg = strdup(exc.what());}
+        return -1;
+    }
+    if (status->m_done) {
+        auto result_acls = convert_acls(acls_list, err_msg);
+        if (!result_acls) {return -1;}
+        *acls = result_acls;
+        *status_out = nullptr;
+        return 0;
+    }
+    *status_out = status.release();
+    return 0;
+}
+
+
+int enforcer_generate_acls_continue(const Enforcer enf, SciTokenStatus *status,
+    Acl **acls, char **err_msg)
+{   
+    if (enf == nullptr) {
+        if (err_msg) {*err_msg = strdup("Enforcer may not be a null pointer");}
+        return -1;
+    }
+    auto real_enf = reinterpret_cast<scitokens::Enforcer*>(enf);
+    if (status == nullptr) { 
+        if (err_msg) {*err_msg = strdup("Status may not be a null pointer");}
+        return -1;
+    }
+    
+    scitokens::Enforcer::AclsList acls_list;
+    std::unique_ptr<scitokens::Validator::AsyncStatus> status_internal(
+        reinterpret_cast<scitokens::Validator::AsyncStatus*>(*status));
+    try {
+        status_internal = real_enf->generate_acls_continue(std::move(status_internal), acls_list);
+    } catch (std::exception &exc) {
+        *status = nullptr;
+        if (err_msg) {*err_msg = strdup(exc.what());}
+        return -1;
+    }
+    if (status_internal->m_done) {
+        auto result_acls = convert_acls(acls_list, err_msg);
+        if (!result_acls) {return -1;}
+        *acls = result_acls;
+        *status = nullptr;
+        return 0;
+    }
+    *status = status_internal.release();
     return 0;
 }
 
@@ -455,3 +536,97 @@ int enforcer_test(const Enforcer enf, const SciToken scitoken, const Acl *acl, c
     }
     return 0;
 }
+
+
+void scitoken_status_free(SciTokenStatus status) {
+    std::unique_ptr<scitokens::Validator::AsyncStatus> status_real(
+        reinterpret_cast<scitokens::Validator::AsyncStatus*>(status));
+}
+
+
+int scitoken_status_get_timeout_val(const SciTokenStatus *status, time_t expiry_time, struct timeval *timeout, char **err_msg)
+{
+    if (status == nullptr) {
+        if (err_msg) {*err_msg = strdup("Status object may not be a null pointer");}
+        return -1;
+    }
+    if (timeout == nullptr) {
+        if (err_msg) {*err_msg = strdup("Timeout object may not be a null pointer");}
+        return -1;
+    }
+
+    auto real_status = reinterpret_cast<const scitokens::Validator::AsyncStatus*>(status);
+    struct timeval timeout_internal = real_status->get_timeout_val(expiry_time);
+    timeout->tv_sec = timeout_internal.tv_sec;
+    timeout->tv_usec = timeout_internal.tv_usec;
+
+    return 0;
+}
+
+
+int scitoken_status_get_read_fd_set(SciTokenStatus *status, fd_set **read_fd_set, char **err_msg)
+{
+    if (status == nullptr) {
+        if (err_msg) {*err_msg = strdup("Status object may not be a null pointer");}
+        return -1;
+    }
+    if (read_fd_set == nullptr) {
+        if (err_msg) {*err_msg = strdup("Read fd_set object may not be a null pointer");}
+        return -1;
+    }
+
+    auto real_status = reinterpret_cast<scitokens::Validator::AsyncStatus*>(status);
+    *read_fd_set = real_status->get_read_fd_set();
+    return 0;
+}
+
+
+int scitoken_status_get_write_fd_set(SciTokenStatus *status, fd_set **write_fd_set, char **err_msg)
+{
+    if (status == nullptr) {
+        if (err_msg) {*err_msg = strdup("Status object may not be a null pointer");}
+        return -1;
+    }
+    if (write_fd_set == nullptr) {
+        if (err_msg) {*err_msg = strdup("Write fd_set object may not be a null pointer");}
+        return -1;
+    }
+
+    auto real_status = reinterpret_cast<scitokens::Validator::AsyncStatus*>(status);
+    *write_fd_set = real_status->get_write_fd_set();
+    return 0;
+}
+
+
+int scitoken_status_get_exc_fd_set(SciTokenStatus *status, fd_set **exc_fd_set, char **err_msg)
+{
+    if (status == nullptr) {
+        if (err_msg) {*err_msg = strdup("Status object may not be a null pointer");}
+        return -1;
+    }
+    if (exc_fd_set == nullptr) {
+        if (err_msg) {*err_msg = strdup("Read fd_set object may not be a null pointer");}
+        return -1;
+    }
+
+    auto real_status = reinterpret_cast<scitokens::Validator::AsyncStatus*>(status);
+    *exc_fd_set = real_status->get_exc_fd_set();
+    return 0;
+}
+
+
+int scitoken_status_get_max_fd(const SciTokenStatus *status, int *max_fd, char **err_msg)
+{
+    if (status == nullptr) {
+        if (err_msg) {*err_msg = strdup("Status object may not be a null pointer");}
+        return -1;
+    }
+    if (max_fd == nullptr) {
+        if (err_msg) {*err_msg = strdup("Max FD may not be a null pointer");}
+        return -1;
+    }
+
+    auto real_status = reinterpret_cast<const scitokens::Validator::AsyncStatus*>(status);
+    *max_fd = real_status->get_max_fd();
+    return 0;
+}

src/scitokens.h

@@ -4,6 +4,9 @@
  * 
  */
 
+#include <time.h>
+#include <sys/select.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -12,6 +15,7 @@ typedef void * SciTokenKey;
 typedef void * SciToken;
 typedef void * Validator;
 typedef void * Enforcer;
+typedef void * SciTokenStatus;
 
 typedef int (*StringValidatorFunction)(const char *value, char **err_msg);
 typedef struct Acl_s {
@@ -123,10 +127,58 @@ void enforcer_set_validate_profile(Enforcer, SciTokenProfile profile);
 
 int enforcer_generate_acls(const Enforcer enf, const SciToken scitokens, Acl **acls, char **err_msg);
 
+/**
+ * The asynchronous versions of enforcer_generate_acls.
+ */
+int enforcer_generate_acls_start(const Enforcer enf, const SciToken scitokens,
+    SciTokenStatus *status, Acl **acls, char **err_msg);
+int enforcer_generate_acls_continue(const Enforcer enf, SciTokenStatus *status,
+    Acl **acls, char **err_msg);
+
 void enforcer_acl_free(Acl *acls);
 
 int enforcer_test(const Enforcer enf, const SciToken sci, const Acl *acl, char **err_msg);
 
+void scitoken_status_free(SciTokenStatus *status);
+
+/**
+ * Get the suggested timeout val.  After the timeout value has passed, the asynchronous operation should continue.
+ *
+ * - `expiry_time`: the expiration time (in Unix epoch seconds) for the operation in total.
+ *   The returned timeout value will never take the operation past the expiration time.
+ */
+int scitoken_status_get_timeout_val(const SciTokenStatus *status, time_t expiry_time, struct timeval *timeout, char **err_msg);
+
+/**
+ * Get the set of read file descriptors.  This will return a borrowed pointer (whose lifetime matches the
+ * status object) pointing at a fd_set array of size FD_SETSIZE.  Any file descriptors owned by the status
+ * operation will be set and the returned fd_set can be used for select() operations.
+ *
+ * IMPLEMENTATION NOTE: If the file descriptor monitored by libcurl are too high to be stored in this set,
+ * libcurl should give a corresponding low timeout val (100ms) and effectively switch to polling.  See:
+ * <https://curl.se/libcurl/c/curl_multi_fdset.html> for more information.
+ */
+int scitoken_status_get_read_fd_set(SciTokenStatus *status, fd_set **read_fd_set, char **err_msg);
+
+/**
+ * Get the set of write FDs; see documentation for scitoken_status_get_read_fd_set.
+ */
+int scitoken_status_get_write_fd_set(SciTokenStatus *status, fd_set **write_fd_set, char **err_msg);
+
+/**
+ * Get the set of exception FDs; see documentation for scitoken_status_get_exc_fd_set.
+ */
+int scitoken_status_get_exc_fd_set(SciTokenStatus *status, fd_set **exc_fd_set, char **err_msg);
+
+/**
+ * Get the maximum FD in the status set.
+ *
+ * IMPLEMENTATION NOTE: If the max FD is -1 then it implies libcurl is something that cannot be modelled
+ * by a socket.  In such a case, the libcurl docs suggest using a 100ms timeout for select operations.
+ * See <https://curl.se/libcurl/c/curl_multi_fdset.html>.
+ */
+int scitoken_status_get_max_fd(const SciTokenStatus *status, int *max_fd, char **err_msg);
+
 #ifdef __cplusplus
 }
 #endif