Merge pull request #33784 from patriot1burke/azf-http

Azure Function HTTP refactored

devtools/project-core-extension-codestarts/src/main/resources/codestarts/quarkus/extension-codestarts/azure-functions-http-codestart/base/src/main/resources/application.tpl.qute.yml

@@ -0,0 +1,5 @@
+quarkus:
+  http:
+    root-path: {root-context-path}
+  azure-functions:
+    app-name: {project.artifact-id}-{gen-info.time}

devtools/project-core-extension-codestarts/src/main/resources/codestarts/quarkus/examples/azure-functions-http-example/codestart.yml → devtools/project-core-extension-codestarts/src/main/resources/codestarts/quarkus/extension-codestarts/azure-functions-http-codestart/codestart.yml

@@ -1,9 +1,7 @@
 name: azure-functions-http-example
 ref: azure-functions-http
 type: code
-tags:
-  - example
-  - maven-only
+tags: extension-codestart
 metadata:
   title: Azure Functions HTTP Integration example
   description: This example contains a HTTP function ready for Azure.
@@ -15,12 +13,6 @@ language:
     data:
       # /api is the default root context azure functions will prepend
       root-context-path: "/api"
-      app-region:
-        eastus
-      resource-group:
-        quarkus-examples
-      function-os:
-        linux
     dependencies:
       - io.quarkus:quarkus-azure-functions-http
       - io.quarkus:quarkus-resteasy-reactive

devtools/project-core-extension-codestarts/src/main/resources/codestarts/quarkus/extension-codestarts/azure-functions-http-codestart/java/src/integrationTest/java/org/acme/GreetingIT.java

@@ -0,0 +1,19 @@
+package org.acme;
+
+import io.quarkus.test.junit.QuarkusIntegrationTest;
+import org.junit.jupiter.api.Test;
+import static io.restassured.RestAssured.given;
+import static org.hamcrest.CoreMatchers.is;
+
+@QuarkusIntegrationTest
+public class GreetingIT {
+
+    @Test
+    public void testIt() {
+        given()
+                .when().get("/hello")
+                .then()
+                .statusCode(200)
+                .body(is("hello"));
+    }
+}

docs/src/main/asciidoc/azure-functions-http.adoc

@@ -11,7 +11,8 @@ include::_attributes.adoc[]
 
 The `quarkus-azure-functions-http` extension allows you to write microservices with RESTEasy Reactive (our Jakarta REST implementation),
 Undertow (servlet), Reactive Routes, or xref:funqy-http.adoc[Funqy HTTP] and make these microservices deployable to the Azure Functions runtime.
-
+In other words, this extension is a bridge from the Azure Functions HttpTrigger and the Quarkus family
+of HTTP APIs.
 One azure function deployment can represent any number of Jakarta REST, servlet, Reactive Routes, or xref:funqy-http.adoc[Funqy HTTP] endpoints.
 
 include::{includes}/extension-status.adoc[]
@@ -30,9 +31,9 @@ include::{includes}/prerequisites.adoc[]
 This guide walks you through running a maven project that can deploy a Resteasy Reactive endpoint to Azure Functions.
 While only Jakarta REST is provided as an example, you can easily replace it with the HTTP framework of your choice.
 
-== Creating the Maven Deployment Project
+== Creating the Maven/Gradle Project
 
-You can download the example code from Quarkus's application generator at https://code.quarkus.io/d?e=azure-functions-http&cn=code.quarkus.io[this link].
+You can generate the example code from Quarkus's online application generator at https://code.quarkus.io/d?e=azure-functions-http&cn=code.quarkus.io[this link].
 
 You can also generate this example with the Quarkus CLI:
 
@@ -41,6 +42,8 @@ You can also generate this example with the Quarkus CLI:
 quarkus create app --extension=quarkus-azure-functions-http
 ----
 
+Add the `--gradle` switch if you want to generate a gradle project.
+
 == Login to Azure
 
 If you don't log in to Azure you won't be able to deploy.
@@ -52,66 +55,139 @@ az login
 
 == Quarkus dev mode
 
-Quarkus dev mode works by just running your application as a HTTP endpoint.
+Quarkus dev mode works by just running your application as a HTTP endpoint.  In dev mode
+there is no special interaction with the Azure Functions local runtime.
 
 [source,bash,subs=attributes+]
 ----
 ./mvnw clean package quarkus:dev
 ----
 
+== Examining the project
+
+If you open the `pom.xml` or `build.gradle` build file of the generated project you'll see that
+the project is similar to any other Quarkus project.
+The `quarkus-azure-functions-http` extension is the integration point between
+Quarkus and Azure Functions.
+
+The current implementation of the `quarkus-azure-functions-http` extension no longer requires the
+`azure-functions-maven-plugin` or gradle equivalent.  Local development and Azure Functions packaging and
+deployment is now all done by Quarkus.
+
+Build configuration is now all within `application.properties`.  The only required configuration switch
+is `quarkus.azure-functions.app-name`.
+
+== Azure Deployment Descriptors
+
+The Azure Functions `host.json` deployment descriptor is automatically
+generated, but if you need to override it, declare it in the root directory of the project and
+rerun the build when you are ready.
+
+[#config-azure-paths]
+== Configuring Root Paths
+
+The default route prefix for an Azure Function is `/api`.  All of your Jakarta REST, Servlet, Reactive Routes, and xref:funqy-http.adoc[Funqy HTTP] endpoints must
+explicitly take this into account.  In the generated project this is handled by the
+`quarkus.http.root-path` switch in `application.properties`
+
+== Login to Azure
+
+If you don't log in to Azure you won't be able to deploy.
+
+[source,bash,subs=attributes+]
+----
+az login
+----
+
+== Quarkus dev mode
 
+Quarkus dev mode does not work currently with Azure Functions.
 
-== Run locally in Azure Functions simulated environment
+== Run locally in Azure Functions local environment
 
-If you want to try your app with a simulated local Azure Functions environment, you can
+If you want to try this example within the local Azure Functions environment, you can
 use this command
 
 [source,bash,subs=attributes+]
 ----
-./mvnw clean package azure-functions:run
+./mvnw quarkus:run
+----
+
+or
+
+[source,bash,subs=attributes+]
+----
+./gradlew --info --no-daemon quarkusRun
 ----
 
+Gradle is a bit quirky with process management, so you need the `--no-daemon` switch or control-c will not
+destroy the process cleanly and you'll have open ports.
+
 Note that you must have the https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local#v2[Azure Functions Core Tools]
 installed for this to work!
 
-== Deploy to Azure
+The URL to access the example would be:
+
+http://localhost:8081/api/hello
+
+== Quarkus Integration Testing
+
+You can implement integration tests using `@QuarkusIntegrationTest` functionality.  When these
+integration tests run, the local Azure Functions environment will be spun up for the duration of integration testing.
 
-The `pom.xml` you generated in the previous step pulls in the `azure-functions-maven-plugin`.  Running maven package
-generates config files and a staging directory required by the `azure-functions-maven-plugin`.  Here's
-how to execute it.
 
+For maven:
 [source,bash,subs=attributes+]
 ----
-./mvnw clean package azure-functions:deploy
+./mvnw -DskipITs=false verify
 ----
 
-If deployment is a success, the azure plugin will tell you the base URL to access your function.
+Make sure any integration tests you execute with maven use the `*IT.java` file pattern so that regular builds do not execute
+the test.
 
-i.e.
-[source]
+For Gradle:
+[source,bash,subs=attributes+]
 ----
-[INFO] HTTP Trigger Urls:
-[INFO] 	 QuarkusHttp : https://{appName}.azurewebsites.net/api/{*path}
+./gradlew --info quarkusIntTest
 ----
 
-The URL to access the service would be
+Make sure any integration tests you execute with Gradle are located within `src/integrationTest/java`.  Integration
+tests that exist in `src/test` will run with normal build and fail.
 
-https://{appName}.azurewebsites.net/api/hello
+== Deploy to Azure
 
-== Extension maven dependencies
+The `quarkus-azure-functions-http` extension handles all the work to deploy to Azure.  By default,
+Quarkus will use the Azure CLI in the background to authenticate and deploy to Azure.  If you have
+multiple subscriptions associated with your account, you must set the `quarkus.azure-functions.subscription-id`
+property in your `application.properties` file to the subscription you want to use.
+For other authentication mechanisms and deployment options see our config properties https://quarkus.io/guides/all-config[here].
 
-You must include the `quarkus-azure-functions-http` extension as this is a generic bridge between the Azure Functions
-runtime and the HTTP framework you are writing your microservices in.
+To run the deploy, after you build your project execute:
 
-== Azure Deployment Descriptors
+[source,bash,subs=attributes+]
+----
+./mvnw quarkus:deploy
+----
 
-Templates for Azure Functions deployment descriptors (`host.json`, `function.json`) are within
-the base directory of the project. Edit them as you need to.  Rerun the build when you are ready.
+or
 
-[#config-azure-paths]
-== Configuring Root Paths
+[source,bash,subs=attributes+]
+----
+./gradlew --info deploy
+----
+
+If deployment is a success, Quarkus will output the endpoint URL of the example function to the console
+For Gradle, you must use the `--info` switch to see this output!
+
+i.e.
+[source]
+----
+[INFO] HTTP Trigger Urls:
+[INFO] 	 HttpExample : https://{appName}.azurewebsites.net/api/{*path}
+----
+
+The URL to access the service would be something like
+
+https://{appName}.azurewebsites.net/api/hello
 
-The default route prefix for an Azure Function is `/api`.  All of your Jakarta REST, Servlet, Reactive Routes, and xref:funqy-http.adoc[Funqy HTTP] endpoints must
-explicitly take this into account.  In the generated project this is handled by the
-`quarkus.http.root-path` switch in `application.properties`
 

docs/src/main/asciidoc/azure-functions.adoc

@@ -100,15 +100,11 @@ deployment is now all done by Quarkus.
 Build configuration is now all within `application.properties`.  The only required configuration switch
 is `quarkus.azure-functions.app-name`.
 
+== Azure Deployment Descriptors
 
-== Login to Azure
-
-If you don't log in to Azure you won't be able to deploy.
-
-[source,bash,subs=attributes+]
-----
-az login
-----
+The Azure Functions `host.json` deployment descriptor is automatically
+generated, but if you need to override it, declare it in the root directory of the project and
+rerun the build when you are ready.
 
 == Quarkus dev mode
 
@@ -137,6 +133,11 @@ destroy the process cleanly and you'll have open ports.
 Note that you must have the https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local#v2[Azure Functions Core Tools]
 installed for this to work!
 
+The URL to access the example would be:
+
+https://localhost:8081/HttpExample?name=Bill
+
+
 == Quarkus Integration Testing
 
 You can implement integration tests using `@QuarkusIntegrationTest` functionality.  When these
@@ -161,6 +162,15 @@ For Gradle:
 Make sure any integration tests you execute with Gradle are located within `src/integrationTest/java`.  Integration
 tests that exist in `src/test` will run with normal build and fail.
 
+== Login to Azure
+
+If you don't log in to Azure you won't be able to deploy.
+
+[source,bash,subs=attributes+]
+----
+az login
+----
+
 == Deploy to Azure
 
 The `quarkus-azure-functions` extension handles all the work to deploy to Azure.  By default,
@@ -197,9 +207,5 @@ The URL to access the service would be
 
 https://{appName}.azurewebsites.net/api/HttpExample
 
-== Azure Deployment Descriptors
-
-Templates for Azure Functions deployment descriptors (`host.json`, `function.json`) are within
-base directory of the project.  Edit them as you need to.  Rerun the build when you are ready.