[codex] generate polling helpers from vendor metadata (#269)

* feat(csharp): generate polling helpers from vendor metadata

* fix(csharp): gate polling runtime support generation

* fix(ci): stabilize generator support and snapshots

* fix(ci): unify generated cookie header handling

* fix(ci): remove duplicate webhook source entry

Author: HavenDV

src/libs/AutoSDK.CSharp/Operations/CSharpEndPointFactory.cs

@@ -165,6 +165,10 @@ public static EndPoint CreateEndPoint(
             streamFormat = streamFormatValue;
         }
 
+        var pollingOperations = streamFormat == StreamFormat.None
+            ? operation.Operation.GetPollingOperations()
+            : ImmutableArray<PollingOperation>.Empty.AsEquatableArray();
+
         var endPointId = string.IsNullOrWhiteSpace(methodNameSuffix)
             ? operation.MethodName
             : operation.MethodName + methodNameSuffix;
@@ -174,6 +178,7 @@ public static EndPoint CreateEndPoint(
         var notAsyncMethodName = endPointId.ToPropertyName();
         var generateResponseWrapper =
             responses.Any(x => x.HasHeaders && (x.Is2XX || x.IsDefault)) ||
+            !pollingOperations.IsEmpty ||
             OpenApiExtensions.GetExtensionBooleanValue(
                 operation.Operation.Extensions,
                 "x-autosdk-response-wrapper");
@@ -229,6 +234,7 @@ public static EndPoint CreateEndPoint(
                 : string.Empty,
             Remarks: GetCodeSamplesRemarks(operation.Operation),
             GenerateResponseWrapper: generateResponseWrapper,
+            PollingOperations: pollingOperations,
             Servers: servers,
             HasServerOverride: operation.HasServerOverride);
     }

src/libs/AutoSDK.CSharp/Pipeline/CSharpPipeline.cs

@@ -158,7 +158,10 @@ public static IReadOnlyList<FileWithName> GenerateFiles(
                             data.Methods.Any(static x => x.ClientUsesServerSelectionSupport)
                         ? [Sources.ServerSelectionSupport(settings, cancellationToken)]
                         : [])
-                    .Concat([Sources.OptionsSupport(settings, cancellationToken)])
+                    .Concat([Sources.OptionsSupport(
+                        settings,
+                        includePollingSupport: data.Methods.Any(static x => !x.PollingOperations.IsEmpty),
+                        cancellationToken: cancellationToken)])
                     .Concat(!data.Authorizations.IsEmpty
                         ? [Sources.SecuritySupport(settings, cancellationToken)]
                         : [])

src/libs/AutoSDK.CSharp/Sources/Sources.Methods.cs

@@ -97,6 +97,7 @@ public partial class {endPoint.ClassName}
 
 {GenerateMethod(endPoint)}
 {(ShouldGenerateResponseWrapperMethod(endPoint) ? GenerateMethod(endPoint, returnResponseWrapper: true) : TrimmedLine)}
+{GeneratePollingMethods(endPoint)}
 {GenerateExtensionMethod(endPoint)}
     }}
 }}".RemoveBlankLinesWhereOnlyWhitespaces();
@@ -121,6 +122,7 @@ public partial interface I{endPoint.ClassName}
     {{
 {GenerateMethod(endPoint, isInterface: true)}
 {(ShouldGenerateResponseWrapperMethod(endPoint) ? GenerateMethod(endPoint, isInterface: true, returnResponseWrapper: true) : TrimmedLine)}
+{GeneratePollingMethods(endPoint, isInterface: true)}
 {GenerateExtensionMethod(endPoint, isInterface: true)}
     }}
 }}".RemoveBlankLinesWhereOnlyWhitespaces();
@@ -272,6 +274,170 @@ private static string GetResponseWrapperMethodName(EndPoint endPoint)
         return $"{endPoint.NotAsyncMethodName}AsResponseAsync";
     }
 
+    private static string GetPollingMethodName(
+        EndPoint endPoint,
+        PollingOperation pollingOperation)
+    {
+        return $"{endPoint.NotAsyncMethodName}{pollingOperation.Name.ToPropertyName()}Async";
+    }
+
+    private static bool SupportsPollingOperation(
+        EndPoint endPoint,
+        PollingOperation pollingOperation)
+    {
+        if (string.IsNullOrWhiteSpace(pollingOperation.Name) ||
+            pollingOperation.SuccessCriteria.IsEmpty ||
+            endPoint.RawStream ||
+            endPoint.EnumerableStream)
+        {
+            return false;
+        }
+
+        if (!string.IsNullOrWhiteSpace(endPoint.SuccessResponse.Type.CSharpType))
+        {
+            return true;
+        }
+
+        return !pollingOperation.SuccessCriteria.Any(static x => x.ContextType == PollingCriterionContextType.ResponseBody) &&
+               !pollingOperation.FailureCriteria.Any(static x => x.ContextType == PollingCriterionContextType.ResponseBody);
+    }
+
+    private static string GeneratePollingMethods(
+        EndPoint endPoint,
+        bool isInterface = false)
+    {
+        return endPoint.PollingOperations
+            .Where(x => SupportsPollingOperation(endPoint, x))
+            .Select(x => GeneratePollingMethod(endPoint, x, isInterface))
+            .Inject();
+    }
+
+    private static string GeneratePollingMethod(
+        EndPoint endPoint,
+        PollingOperation pollingOperation,
+        bool isInterface = false)
+    {
+        var methodName = GetPollingMethodName(endPoint, pollingOperation);
+        var hasBody = !string.IsNullOrWhiteSpace(endPoint.SuccessResponse.Type.CSharpType);
+        var bodyReturnType = hasBody
+            ? $"global::System.Threading.Tasks.Task<{endPoint.SuccessResponse.Type.CSharpTypeWithoutNullability}>"
+            : "global::System.Threading.Tasks.Task";
+        var successExpression = GeneratePollingCriteriaExpression(endPoint, pollingOperation.SuccessCriteria, "__pollingResponse");
+        var failureExpression = GeneratePollingCriteriaExpression(endPoint, pollingOperation.FailureCriteria, "__pollingResponse");
+        var body = isInterface
+            ? ";"
+            : $@"
+        {{
+            var __pollingOptions = global::{endPoint.Settings.Namespace}.AutoSDKPollingSupport.ResolvePollingOptions(
+                pollingOptions: pollingOptions,
+                defaultInitialDelay: global::System.TimeSpan.FromSeconds({pollingOperation.DelaySeconds}),
+                defaultInterval: global::System.TimeSpan.FromSeconds({pollingOperation.IntervalSeconds}),
+                defaultMaxAttempts: {pollingOperation.LimitCount});
+            global::{endPoint.Settings.Namespace}.AutoSDKHttpResponse? __lastResponse = null;
+
+            if (__pollingOptions.InitialDelay > global::System.TimeSpan.Zero)
+            {{
+                await global::{endPoint.Settings.Namespace}.AutoSDKPollingSupport.DelayAsync(
+                    delay: __pollingOptions.InitialDelay,
+                    cancellationToken: cancellationToken).ConfigureAwait(false);
+            }}
+
+            for (var __pollAttempt = 1; __pollAttempt <= __pollingOptions.MaxAttempts; __pollAttempt++)
+            {{
+                var __pollingResponse = await {GetResponseWrapperMethodName(endPoint)}(
+{GenerateMethodInvocationArguments(endPoint)}
+                ).ConfigureAwait(false);
+                __lastResponse = __pollingResponse;
+
+{(!pollingOperation.FailureCriteria.IsEmpty ? $@"                if ({failureExpression})
+                {{
+                    throw new global::{endPoint.Settings.Namespace}.AutoSDKPollingException(
+                        message: $""Polling helper '{methodName}' matched a configured failure criterion on attempt {{__pollAttempt}}."",
+                        response: __pollingResponse);
+                }}
+" : TrimmedLine)}
+                if ({successExpression})
+                {{
+{(hasBody ? "                    return __pollingResponse.Body;" : "                    return;")}
+                }}
+
+                if (__pollAttempt == __pollingOptions.MaxAttempts)
+                {{
+                    break;
+                }}
+
+                await global::{endPoint.Settings.Namespace}.AutoSDKPollingSupport.DelayAsync(
+                    delay: __pollingOptions.Interval,
+                    cancellationToken: cancellationToken).ConfigureAwait(false);
+            }}
+
+            throw new global::{endPoint.Settings.Namespace}.AutoSDKPollingException(
+                message: $""Polling helper '{methodName}' did not satisfy its success criteria after {{__pollingOptions.MaxAttempts}} attempts."",
+                response: __lastResponse);
+        }}";
+
+        return $@"
+        {"Polls the endpoint until the configured polling criteria are satisfied.".ToXmlDocumentationSummary(level: 8)}
+{endPoint.Parameters.Where(x => x.Location != null).Select(x => $@"
+        {x.Summary.ToXmlDocumentationForParam(x.ParameterName, level: 8)}").Inject()}
+{(string.IsNullOrWhiteSpace(endPoint.RequestType.CSharpType) ? TrimmedLine : @"
+        /// <param name=""request""></param>")}
+        /// <param name=""pollingOptions"">Overrides the generated polling delay, interval, and attempt limit.</param>
+        /// <param name=""requestOptions"">Per-request overrides applied to each poll attempt.</param>
+        /// <param name=""cancellationToken"">The token to cancel the polling operation with</param>
+        /// <exception cref=""global::{endPoint.Settings.Namespace}.AutoSDKPollingException""></exception>
+        {(isInterface ? "" : "public async ")}{bodyReturnType} {methodName}(
+{endPoint.Parameters.Where(x => x is { Location: not null, IsRequired: true } && !x.HasSchemaDefault).Select(x => $@"
+            {x.Type.CSharpType} {x.ParameterName},").Inject()}
+{(string.IsNullOrWhiteSpace(endPoint.RequestType.CSharpType) ? TrimmedLine : $@"
+            {endPoint.RequestType.CSharpTypeWithoutNullability} request,")}
+{endPoint.Parameters.Where(x => x is { Location: not null } && (!x.IsRequired || x.HasSchemaDefault)).Select(x => $@"
+            {x.Type.CSharpType} {x.ParameterName} = {x.ParameterDefaultValue},").Inject()}
+            global::{endPoint.Settings.Namespace}.AutoSDKPollingOptions? pollingOptions = default,
+            global::{endPoint.Settings.Namespace}.AutoSDKRequestOptions? requestOptions = default,
+            global::System.Threading.CancellationToken cancellationToken = default){body}
+".RemoveBlankLinesWhereOnlyWhitespaces();
+    }
+
+    private static string GeneratePollingCriteriaExpression(
+        EndPoint endPoint,
+        EquatableArray<PollingCriterion> criteria,
+        string responseVariableName)
+    {
+        return criteria.IsEmpty
+            ? "false"
+            : string.Join(
+                " && ",
+                criteria.Select(x => GeneratePollingCriterionExpression(endPoint, x, responseVariableName)));
+    }
+
+    private static string GeneratePollingCriterionExpression(
+        EndPoint endPoint,
+        PollingCriterion criterion,
+        string responseVariableName)
+    {
+        return criterion switch
+        {
+            { Type: PollingCriterionType.Simple, ContextType: PollingCriterionContextType.StatusCode } => $@"global::{endPoint.Settings.Namespace}.AutoSDKPollingSupport.MatchesStatusCode(
+                    statusCode: {responseVariableName}.StatusCode,
+                    @operator: {criterion.Operator.ToCSharpStringLiteral()},
+                    expectedValue: {criterion.ExpectedValue.ToCSharpStringLiteral()})",
+            { Type: PollingCriterionType.Regex, ContextType: PollingCriterionContextType.StatusCode } => $@"global::{endPoint.Settings.Namespace}.AutoSDKPollingSupport.MatchesRegexValue(
+                    value: global::{endPoint.Settings.Namespace}.AutoSDKPollingSupport.GetStatusCodeValue({responseVariableName}.StatusCode),
+                    pattern: {criterion.Pattern.ToCSharpStringLiteral()})",
+            { Type: PollingCriterionType.Simple, ContextType: PollingCriterionContextType.ResponseBody } => $@"global::{endPoint.Settings.Namespace}.AutoSDKPollingSupport.MatchesSimpleCondition(
+                    body: {responseVariableName}{(string.IsNullOrWhiteSpace(endPoint.SuccessResponse.Type.CSharpType) ? string.Empty : ".Body")},
+                    jsonPointer: {criterion.JsonPointer.ToCSharpStringLiteral()},
+                    @operator: {criterion.Operator.ToCSharpStringLiteral()},
+                    expectedValue: {criterion.ExpectedValue.ToCSharpStringLiteral()})",
+            { Type: PollingCriterionType.Regex, ContextType: PollingCriterionContextType.ResponseBody } => $@"global::{endPoint.Settings.Namespace}.AutoSDKPollingSupport.MatchesRegexCondition(
+                    body: {responseVariableName}{(string.IsNullOrWhiteSpace(endPoint.SuccessResponse.Type.CSharpType) ? string.Empty : ".Body")},
+                    jsonPointer: {criterion.JsonPointer.ToCSharpStringLiteral()},
+                    pattern: {criterion.Pattern.ToCSharpStringLiteral()})",
+            _ => "false",
+        };
+    }
+
     private static string GetSendExpression(
         EndPoint endPoint,
         string requestVariableName,