SONARPY-3118 Rule S7614: AWS Lambda Handlers must not be an async function (#409)

GitOrigin-RevId: 1054006afc412ae857f38b454bd675c0c8e6b817

Author: Seppli11

python-checks/src/main/java/org/sonar/python/checks/AsyncAwsLambdaHandlerCheck.java

@@ -0,0 +1,45 @@
+/*
+ * SonarQube Python Plugin
+ * Copyright (C) 2011-2025 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the Sonar Source-Available License Version 1, as published by SonarSource SA.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the Sonar Source-Available License for more details.
+ *
+ * You should have received a copy of the Sonar Source-Available License
+ * along with this program; if not, see https://sonarsource.com/license/ssal/
+ */
+package org.sonar.python.checks;
+
+import org.sonar.check.Rule;
+import org.sonar.plugins.python.api.PythonSubscriptionCheck;
+import org.sonar.plugins.python.api.SubscriptionContext;
+import org.sonar.plugins.python.api.tree.FunctionDef;
+import org.sonar.plugins.python.api.tree.Tree;
+import org.sonar.python.checks.utils.AwsLambdaChecksUtils;
+
+@Rule(key = "S7614")
+public class AsyncAwsLambdaHandlerCheck extends PythonSubscriptionCheck {
+  
+  private static final String MESSAGE = "Remove the `async` keyword from this AWS Lambda handler definition.";
+  
+  @Override
+  public void initialize(Context context) {
+    context.registerSyntaxNodeConsumer(Tree.Kind.FUNCDEF, AsyncAwsLambdaHandlerCheck::checkAsyncLambdaHandler);
+  }
+  
+  private static void checkAsyncLambdaHandler(SubscriptionContext ctx) {
+    var functionDef = (FunctionDef) ctx.syntaxNode();
+
+    var asyncToken = functionDef.asyncKeyword();
+
+    if (asyncToken != null && AwsLambdaChecksUtils.isOnlyLambdaHandler(ctx, functionDef)) {
+      ctx.addIssue(asyncToken, MESSAGE);
+    }
+  }
+}

python-checks/src/main/java/org/sonar/python/checks/OpenSourceCheckList.java

@@ -125,6 +125,7 @@ public Stream<Class<?>> getChecks() {
       AsyncFunctionNotAsyncCheck.class,
       AsyncFunctionWithTimeoutCheck.class,
       AsyncioTaskNotStoredCheck.class,
+      AsyncAwsLambdaHandlerCheck.class,
       AsyncLongSleepCheck.class,
       AsyncWithContextManagerCheck.class,
       AWSLambdaReservedEnvironmentVariableCheck.class,

python-checks/src/main/java/org/sonar/python/checks/utils/AwsLambdaChecksUtils.java

@@ -28,11 +28,6 @@ public class AwsLambdaChecksUtils {
 
   private AwsLambdaChecksUtils() {
   }
-
-  public static boolean isLambdaHandler(PythonVisitorContext ctx, FunctionDef functionDef) {
-    return isLambdaHandler(ctx.projectConfiguration(), ctx.callGraph(), functionDef);
-  }
-
   public static boolean isLambdaHandler(SubscriptionContext ctx, FunctionDef functionDef) {
     return isLambdaHandler(ctx.projectConfiguration(), ctx.callGraph(), functionDef);
   }
@@ -46,6 +41,11 @@ public static boolean isLambdaHandler(ProjectConfiguration config, CallGraph cg,
     return false;
   }
 
+  public static boolean isOnlyLambdaHandler(SubscriptionContext ctx, FunctionDef functionDef) {
+    return functionDef.name().typeV2() instanceof FunctionType functionType
+      && isLambdaHandlerFqn(ctx.projectConfiguration(), functionType.fullyQualifiedName());
+  }
+
   private static boolean isLambdaHandlerFqn(ProjectConfiguration projectConfiguration, String fqn) {
     return projectConfiguration.awsProjectConfiguration()
              .awsLambdaHandlers()

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S7614.html

@@ -0,0 +1,36 @@
+<p>This rule raises an issue when the AWS Lambda handler function is declared with <code>async</code>.</p>
+<h2>Why is this an issue?</h2>
+<p>The standard AWS Lambda Python runtime is designed to invoke a synchronous handler function. While Python’s <code>asyncio</code> library can be
+used inside a synchronous handler, by calling <code>asyncio.run()</code>, the handler function itself cannot be declared with <code>async def</code>.
+Doing so will lead to a runtime error.</p>
+<h2>How to fix it</h2>
+<p>To fix this issue, remove the <code>async</code> keyword from the handler function definition. The asynchronous part of the code can be moved to
+its own <code>async</code> function.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+def some_logic():
+  ...
+
+async def lambda_handler(event, context): # Noncompliant: the handler is defined with async
+  result = some_logic()
+  return {"status": result}
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+import asyncio
+
+async def some_logic():
+  ...
+
+def lambda_handler(event, context):
+  result = asyncio.run(some_logic())
+  return {"status": result}
+</pre>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<ul>
+  <li> AWS Documentation - <a href="https://docs.aws.amazon.com/lambda/latest/dg/python-handler.html#python-handler-signature">Valid handler
+  signatures for Python handlers</a> </li>
+</ul>
+

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S7614.json

@@ -0,0 +1,21 @@
+{
+  "title": "AWS Lambda handlers must not be an async function",
+  "type": "CODE_SMELL",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "5min"
+  },
+  "tags": [],
+  "defaultSeverity": "Minor",
+  "ruleSpecification": "RSPEC-7614",
+  "sqKey": "S7614",
+  "scope": "All",
+  "quickfix": "unknown",
+  "code": {
+    "impacts": {
+      "RELIABILITY": "LOW"
+    },
+    "attribute": "CONVENTIONAL"
+  }
+}

python-checks/src/test/java/org/sonar/python/checks/AsyncAwsLambdaHandlerCheckTest.java

@@ -0,0 +1,38 @@
+/*
+ * SonarQube Python Plugin
+ * Copyright (C) 2011-2025 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the Sonar Source-Available License Version 1, as published by SonarSource SA.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the Sonar Source-Available License for more details.
+ *
+ * You should have received a copy of the Sonar Source-Available License
+ * along with this program; if not, see https://sonarsource.com/license/ssal/
+ */
+package org.sonar.python.checks;
+
+import java.util.List;
+import org.junit.jupiter.api.Test;
+import org.sonar.python.checks.utils.PythonCheckVerifier;
+import org.sonar.python.project.config.ProjectConfigurationBuilder;
+
+class AsyncAwsLambdaHandlerCheckTest {
+
+  @Test
+  void test() {
+    PythonCheckVerifier.verify(
+      List.of("src/test/resources/checks/asyncAwsLambdaHandler.py"),
+      new AsyncAwsLambdaHandlerCheck(),
+      new ProjectConfigurationBuilder()
+        .addAwsLambdaHandler("n/a", "asyncAwsLambdaHandler.lambda_handler")
+        .addAwsLambdaHandler("n/a", "asyncAwsLambdaHandler.async_lambda_handler")
+        .build()
+    );
+  }
+
+}

python-checks/src/test/java/org/sonar/python/checks/utils/AwsLambdaChecksUtilsTest.java

@@ -17,66 +17,80 @@
 package org.sonar.python.checks.utils;
 
 import static org.assertj.core.api.Assertions.assertThat;
-import static org.mockito.Mockito.mock;
 
-import java.io.IOException;
-import java.nio.file.Files;
 import org.junit.jupiter.api.Test;
 import org.mockito.Mockito;
-import org.sonar.plugins.python.api.PythonFile;
-import org.sonar.plugins.python.api.PythonVisitorContext;
+import org.sonar.plugins.python.api.SubscriptionContext;
 import org.sonar.plugins.python.api.project.configuration.AwsLambdaHandlerInfo;
 import org.sonar.plugins.python.api.project.configuration.ProjectConfiguration;
-import org.sonar.plugins.python.api.tree.FileInput;
 import org.sonar.plugins.python.api.tree.FunctionDef;
 import org.sonar.plugins.python.api.tree.Name;
 import org.sonar.plugins.python.api.types.v2.FunctionType;
 import org.sonar.plugins.python.api.types.v2.PythonType;
 import org.sonar.python.semantic.v2.callgraph.CallGraph;
-import org.sonar.python.tree.FileInputImpl;
 
 class AwsLambdaChecksUtilsTest {
   @Test
   void isLambdaHandlerTest_direct() {
-    var pythonVisitorContext = pythonVisitorContext(CallGraph.EMPTY);
+    var subscriptionContext = subscriptionContext(CallGraph.EMPTY);
 
     var functionDef = functionDef("a.b.c");
-    assertThat(AwsLambdaChecksUtils.isLambdaHandler(pythonVisitorContext, functionDef)).isFalse();
+    assertThat(AwsLambdaChecksUtils.isLambdaHandler(subscriptionContext, functionDef)).isFalse();
 
-    pythonVisitorContext.projectConfiguration().awsProjectConfiguration().awsLambdaHandlers().add(new AwsLambdaHandlerInfo("a.b.c"));
-    assertThat(AwsLambdaChecksUtils.isLambdaHandler(pythonVisitorContext, functionDef)).isTrue();
+    subscriptionContext.projectConfiguration().awsProjectConfiguration().awsLambdaHandlers()
+        .add(new AwsLambdaHandlerInfo("a.b.c"));
+    assertThat(AwsLambdaChecksUtils.isLambdaHandler(subscriptionContext, functionDef)).isTrue();
 
     var functionDefWithUnknownType = functionDef(PythonType.UNKNOWN);
-    assertThat(AwsLambdaChecksUtils.isLambdaHandler(pythonVisitorContext, functionDefWithUnknownType)).isFalse();
+    assertThat(AwsLambdaChecksUtils.isLambdaHandler(subscriptionContext, functionDefWithUnknownType)).isFalse();
   }
 
   @Test
   void isLambdaHandlerTest_callGraph() {
     var callGraph = new CallGraph.Builder()
-      .addUsage("lambda.handler", "a.b.c")
-      .addUsage("a.b.c", "e.f.g")
-      .build();
+        .addUsage("lambda.handler", "a.b.c")
+        .addUsage("a.b.c", "e.f.g")
+        .build();
 
-    var pythonVisitorContext = pythonVisitorContext(callGraph);
+    var subscriptionContext = subscriptionContext(callGraph);
 
     var functionDef = functionDef("e.f.g");
 
-    assertThat(AwsLambdaChecksUtils.isLambdaHandler(pythonVisitorContext, functionDef)).isFalse();
+    assertThat(AwsLambdaChecksUtils.isLambdaHandler(subscriptionContext, functionDef)).isFalse();
 
-    pythonVisitorContext.projectConfiguration().awsProjectConfiguration().awsLambdaHandlers().add(new AwsLambdaHandlerInfo("lambda.handler"));
-    assertThat(AwsLambdaChecksUtils.isLambdaHandler(pythonVisitorContext, functionDef)).isTrue();
+    subscriptionContext.projectConfiguration().awsProjectConfiguration().awsLambdaHandlers()
+        .add(new AwsLambdaHandlerInfo("lambda.handler"));
+    assertThat(AwsLambdaChecksUtils.isLambdaHandler(subscriptionContext, functionDef)).isTrue();
   }
 
-  private static PythonVisitorContext pythonVisitorContext(CallGraph callGraph) {
-    PythonFile pythonFile = pythonFile("test.py");
-    FileInput fileInput = mock(FileInputImpl.class);
-    
-    return new PythonVisitorContext.Builder(fileInput, pythonFile)
-      .projectConfiguration(new ProjectConfiguration())
-      .callGraph(callGraph)
-      .build();
+  @Test
+  void isOnlyLambdaHandlerTest() {
+    var callGraph = new CallGraph.Builder()
+        .addUsage("lambda.handler", "a.b.c")
+        .build();
+
+    var subscriptionContext = subscriptionContext(callGraph);
+    subscriptionContext.projectConfiguration().awsProjectConfiguration().awsLambdaHandlers()
+        .add(new AwsLambdaHandlerInfo("lambda.handler"));
+
+    var handlerFunction = functionDef("lambda.handler");
+    assertThat(AwsLambdaChecksUtils.isOnlyLambdaHandler(subscriptionContext, handlerFunction)).isTrue();
+
+    var calledFunction = functionDef("a.b.c");
+    assertThat(AwsLambdaChecksUtils.isOnlyLambdaHandler(subscriptionContext, calledFunction)).isFalse();
+    assertThat(AwsLambdaChecksUtils.isLambdaHandler(subscriptionContext, calledFunction)).isTrue();
+
+    var unknownTypeFunction = functionDef(PythonType.UNKNOWN);
+    assertThat(AwsLambdaChecksUtils.isOnlyLambdaHandler(subscriptionContext, unknownTypeFunction)).isFalse();
   }
 
+  private static SubscriptionContext subscriptionContext(CallGraph callGraph) {
+    var subscriptionContext = Mockito.mock(org.sonar.plugins.python.api.SubscriptionContext.class);
+    Mockito.when(subscriptionContext.projectConfiguration()).thenReturn(new ProjectConfiguration());
+    Mockito.when(subscriptionContext.callGraph()).thenReturn(callGraph);
+
+    return subscriptionContext;
+  }
 
   private static FunctionDef functionDef(String name) {
     FunctionType functionNameType = Mockito.mock(FunctionType.class);
@@ -92,16 +106,4 @@ private static FunctionDef functionDef(PythonType type) {
     Mockito.when(functionDef.name()).thenReturn(functionName);
     return functionDef;
   }
-
-  private static PythonFile pythonFile(String fileName) {
-    PythonFile pythonFile = Mockito.mock(PythonFile.class);
-    Mockito.when(pythonFile.fileName()).thenReturn(fileName);
-    try {
-      Mockito.when(pythonFile.uri()).thenReturn(Files.createTempFile(fileName, "py").toUri());
-    } catch (IOException e) {
-      throw new IllegalStateException("Cannot create temporary file");
-    }
-    return pythonFile;
-  }
-
 }

python-checks/src/test/resources/checks/asyncAwsLambdaHandler.py

@@ -0,0 +1,17 @@
+async def async_lambda_handler(event, context):  # Noncompliant {{Remove the `async` keyword from this AWS Lambda handler definition.}}
+#^[sc=1;ec=5]
+    result = some_logic()
+    return {"status": result}
+
+def some_logic():
+    return "some result"
+
+
+def lambda_handler(event, context):  
+    import asyncio
+    
+    result = asyncio.run(not_a_lambda_handler())
+    return {"status": result}
+
+async def not_a_lambda_entry_point():  # Compliant - not a lambda handler
+    pass

python-frontend/src/main/java/org/sonar/python/project/config/ProjectConfigurationBuilder.java

@@ -37,12 +37,14 @@ public ProjectConfigurationBuilder() {
     awsLambdaHandlersByPackage = new ConcurrentHashMap<>();
   }
 
-  public void addAwsLambdaHandler(String packageName, String fullyQualifiedName) {
+  public ProjectConfigurationBuilder addAwsLambdaHandler(String packageName, String fullyQualifiedName) {
     awsLambdaHandlersByPackage.computeIfAbsent(packageName, k -> new HashSet<>()).add(fullyQualifiedName);
+    return this;
   }
 
-  public void removePackageAwsLambdaHandlers(String packageName) {
+  public ProjectConfigurationBuilder removePackageAwsLambdaHandlers(String packageName) {
     awsLambdaHandlersByPackage.remove(packageName);
+    return this;
   }
 
   public ProjectConfiguration build() {