📝 Add docstrings to fix/aws-msk-iam-optimization

Docstrings generation was requested by @kalavt.

* #11211 (comment)

The following files were modified:

* `src/aws/flb_aws_credentials_ec2.c`
* `src/aws/flb_aws_credentials_http.c`
* `src/aws/flb_aws_credentials_profile.c`
* `src/aws/flb_aws_credentials_sts.c`
* `src/aws/flb_aws_msk_iam.c`

Author: coderabbitai[bot]

src/aws/flb_aws_credentials_ec2.c

@@ -125,12 +125,26 @@ struct flb_aws_credentials *get_credentials_fn_ec2(struct flb_aws_provider
     return creds;
 }
 
+/**
+ * Force an immediate refresh of EC2 IMDS credentials for the given provider.
+ *
+ * Attempts to acquire the provider lock and, if successful, triggers an immediate
+ * credentials refresh from the EC2 Instance Metadata Service. If the lock cannot
+ * be acquired the function does not perform a refresh.
+ *
+ * @param provider The AWS provider whose EC2 IMDS credentials should be refreshed.
+ * @returns `0` on successful credential refresh, `-1` if the refresh failed or did not occur.
+ */
 int refresh_fn_ec2(struct flb_aws_provider *provider) {
     struct flb_aws_provider_ec2 *implementation = provider->implementation;
     int ret = -1;
 
     flb_debug("[aws_credentials] Refresh called on the EC2 IMDS provider");
+    
     if (try_lock_provider(provider)) {
+        /* Set to 1 (epoch start) to trigger immediate refresh via time check */
+        implementation->next_refresh = 1;
+        
         ret = get_creds_ec2(implementation);
         unlock_provider(provider);
     }
@@ -379,4 +393,4 @@ static int ec2_credentials_request(struct flb_aws_provider_ec2
 
     flb_sds_destroy(credentials_response);
     return 0;
-}
+}

src/aws/flb_aws_credentials_http.c

@@ -152,12 +152,26 @@ struct flb_aws_credentials *get_credentials_fn_http(struct flb_aws_provider
     return NULL;
 }
 
+/**
+ * Trigger an immediate credentials refresh for an HTTP provider.
+ *
+ * If the provider can be locked, forces an immediate refresh and performs a
+ * credential fetch using the provider's HTTP implementation; the lock is
+ * released after the fetch completes. If the provider lock cannot be
+ * acquired, no refresh is attempted.
+ *
+ * @param provider AWS provider that contains the HTTP implementation to refresh.
+ * @returns `0` on successful credential retrieval and update, `-1` on failure or if the provider lock could not be acquired.
+ */
 int refresh_fn_http(struct flb_aws_provider *provider) {
     struct flb_aws_provider_http *implementation = provider->implementation;
     int ret = -1;
     flb_debug("[aws_credentials] Refresh called on the http provider");
 
     if (try_lock_provider(provider)) {
+        /* Set to 1 (epoch start) to trigger immediate refresh via time check */
+        implementation->next_refresh = 1;
+        
         ret = http_credentials_request(implementation);
         unlock_provider(provider);
     }
@@ -690,4 +704,4 @@ struct flb_aws_credentials *flb_parse_json_credentials(char *response,
     flb_aws_credentials_destroy(creds);
     flb_free(tokens);
     return NULL;
-}
+}

src/aws/flb_aws_credentials_profile.c

@@ -643,6 +643,19 @@ static int get_shared_config_credentials(char* config_path,
     return result;
 }
 
+/**
+ * Load AWS credentials for the given profile from the shared credentials file.
+ *
+ * Allocates and fills a flb_aws_credentials structure pointed to by `*creds` when a matching
+ * profile is found in the file at `credentials_path`. On failure the function frees any
+ * allocated resources and sets `*creds` to NULL.
+ *
+ * @param credentials_path Path to the shared credentials file.
+ * @param profile Name of the profile to load.
+ * @param creds Output pointer that will receive an allocated credentials structure on success.
+ * @param debug_only If non-zero, suppresses warning-level messages in favor of debug-level logging.
+ * @return `0` on success (credentials populated in `*creds`), `-1` on failure (`*creds` is set to NULL).
+ */
 static int get_shared_credentials(char* credentials_path,
                                   char* profile,
                                   struct flb_aws_credentials** creds,
@@ -663,8 +676,7 @@ static int get_shared_credentials(char* credentials_path,
 
     if (flb_read_file(credentials_path, &buf, &size) < 0) {
         if (errno == ENOENT) {
-            AWS_CREDS_ERROR_OR_DEBUG(debug_only, "Shared credentials file %s does not exist",
-                                     credentials_path);
+            AWS_CREDS_DEBUG("Shared credentials file %s does not exist", credentials_path);
         } else {
             flb_errno();
             AWS_CREDS_ERROR_OR_DEBUG(debug_only, "Could not read shared credentials file %s",
@@ -750,4 +762,4 @@ static int refresh_credentials(struct flb_aws_provider_profile *implementation,
 error:
     flb_aws_credentials_destroy(creds);
     return -1;
-}
+}

src/aws/flb_aws_credentials_sts.c

@@ -170,13 +170,25 @@ struct flb_aws_credentials *get_credentials_fn_sts(struct flb_aws_provider
     return NULL;
 }
 
+/**
+ * Trigger an immediate refresh of STS credentials for the given provider.
+ *
+ * Sets the provider's next_refresh to epoch start to force an immediate AssumeRole
+ * request and attempts to perform the STS AssumeRole call to update cached credentials.
+ *
+ * @param provider The AWS provider instance whose STS implementation will be refreshed.
+ * @returns `0` if the credentials were successfully refreshed; `-1` on failure or if the provider lock could not be acquired.
+ */
 int refresh_fn_sts(struct flb_aws_provider *provider) {
     int ret = -1;
     struct flb_aws_provider_sts *implementation = provider->implementation;
 
     flb_debug("[aws_credentials] Refresh called on the STS provider");
-
+    
     if (try_lock_provider(provider)) {
+        /* Set to 1 (epoch start) to trigger immediate refresh via time check */
+        implementation->next_refresh = 1;
+        
         ret = sts_assume_role_request(implementation->sts_client,
                                       &implementation->creds, implementation->uri,
                                       &implementation->next_refresh);
@@ -475,12 +487,24 @@ struct flb_aws_credentials *get_credentials_fn_eks(struct flb_aws_provider
     return NULL;
 }
 
+/**
+ * Trigger a credentials refresh for the EKS provider.
+ *
+ * Attempts to acquire the provider lock, forces an immediate refresh window, and requests new credentials using the web-identity flow.
+ *
+ * @param provider EKS provider instance.
+ * @returns 0 on success, -1 on failure or if the provider lock could not be acquired.
+ */
 int refresh_fn_eks(struct flb_aws_provider *provider) {
     int ret = -1;
     struct flb_aws_provider_eks *implementation = provider->implementation;
 
     flb_debug("[aws_credentials] Refresh called on the EKS provider");
+    
     if (try_lock_provider(provider)) {
+        /* Set to 1 (epoch start) to trigger immediate refresh via time check */
+        implementation->next_refresh = 1;
+        
         ret = assume_with_web_identity(implementation);
         unlock_provider(provider);
     }
@@ -955,4 +979,4 @@ static flb_sds_t get_node(char *cred_node, char* node_name, int node_name_len, c
     }
 
     return val;
-}
+}