== (Legacy) FunctionInvoker Integration WARNING: The legacy `FunctionInvoker` programming model is deprecated and will not be supported going forward. For up to date samples, aligned with the dependency-injections https://docs.spring.io/spring-cloud-function/docs/current/reference/html/azure.html#_microsoft_azure[Azure Adapter], check the: https://github.com/spring-cloud/spring-cloud-function/tree/main/spring-cloud-function-samples/function-sample-azure-blob-trigger[Blob Trigger], https://github.com/spring-cloud/spring-cloud-function/tree/main/spring-cloud-function-samples/function-sample-azure-http-trigger[HTTP Trigger], https://github.com/spring-cloud/spring-cloud-function/tree/main/spring-cloud-function-samples/function-sample-azure-timer-trigger[Timer Trigger], https://github.com/spring-cloud/spring-cloud-function/tree/main/spring-cloud-function-samples/function-sample-azure-kafka-trigger[ Kafka Trigger & Output Binding]. For a Gradle project example check the https://github.com/spring-cloud/spring-cloud-function/tree/main/spring-cloud-function-samples/function-sample-azure-http-trigger-gradle[ HTTP Trigger with Gradle]. === Overview The https://azure.microsoft.com[Azure] adapter bootstraps a Spring Cloud Function context and channels function calls from the Azure framework into the user functions, using Spring Boot configuration where necessary. Azure Functions has quite a unique and invasive programming model, involving annotations in user code that are specific to the Azure platform. However, it is important to understand that because of the style of integration provided by Spring Cloud Function, specifically `org.springframework.cloud.function.adapter.azure.FunctionInvoker`, this annotation-based programming model is simply a type-safe way to configure your simple java function (function that has no awareness of Azure) to be recognized as Azure function. All you need to do is create a handler that extends `FunctionInvoker`, define and configure your function handler method and make a callback to `handleRequest(..)` method. This handler method provides input and output types as annotated method parameters (enabling Azure to inspect the class and create JSON bindings). [source,java] ---- public class UppercaseHandler extends FunctionInvoker, String> { @FunctionName("uppercase") public String execute(@HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage> request, ExecutionContext context) { Message message = MessageBuilder.withPayload(request.getBody().get()).copyHeaders(request.getHeaders()).build(); return handleRequest(message, context); } } ---- Note that aside form providing configuration via Azure annotation we create an instance of `Message` inside the body of this handler method and make a callback to `handleRequest(..)` method returning its result. The actual user function you're delegating to looks like this [source,java] ---- @Bean public Function uppercase() { return payload -> payload.toUpperCase(); } OR @Bean public Function, String> uppercase() { return message -> message.getPayload().toUpperCase(); } ---- Note that when creating a Message you can copy HTTP headers effectively making them available to you if necessary. The `org.springframework.cloud.function.adapter.azure.FunctionInvoker` class has two useful methods (`handleRequest` and `handleOutput`) to which you can delegate the actual function call, so mostly the function will only ever have one line. The function name (definition) will be retrieved from Azure's `ExecutionContext.getFunctionName()` method, effectively supporting multiple function in the application context. ==== Accessing Azure ExecutionContext Some time there is a need to access the target execution context provided by the Azure runtime in the form of `com.microsoft.azure.functions.ExecutionContext`. For example one of such needs is logging, so it can appear in the Azure console. For that purpose the FunctionInvoker will add an instance of the `ExecutionContext` as a Message header so you can retrieve it via `executionContext` key. ``` @Bean public Function, String> uppercase(JsonMapper mapper) { return message -> { String value = message.getPayload(); ExecutionContext context = (ExecutionContext) message.getHeaders().get("executionContext"); . . . } } ``` ==== Notes on JAR Layout You don't need the Spring Cloud Function Web at runtime in Azure, so you can exclude this before you create the JAR you deploy to Azure, but it won't be used if you include it, so it doesn't hurt to leave it in. A function application on Azure is an archive generated by the Maven plugin. The function lives in the JAR file generated by this project. The sample creates it as an executable jar, using the thin layout, so that Azure can find the handler classes. If you prefer you can just use a regular flat JAR file. The dependencies should *not* be included. ==== Build file setup In order to run Spring Cloud Function applications on Microsoft Azure, you can leverage the Maven plugin offered by the cloud platform provider. In order to use the adapter plugin for Maven, add the plugin dependency to your `pom.xml` file: [source,xml] ---- org.springframework.cloud spring-cloud-function-adapter-azure ---- Then, configure the plugin. You will need to provide Azure-specific configuration for your application, specifying the `resourceGroup`, `appName` and other optional properties, and add the `package` goal execution so that the `function.json` file required by Azure is generated for you. Full plugin documentation can be found in the https://github.com/microsoft/azure-maven-plugins[plugin repository]. [source,xml] ---- com.microsoft.azure azure-functions-maven-plugin ${functionResourceGroup} ${functionAppName} package-functions package ---- You will also have to ensure that the files to be scanned by the plugin can be found in the Azure functions staging directory (see the https://github.com/microsoft/azure-maven-plugins[plugin repository] for more details on the staging directory and it's default location). You can find the entire sample `pom.xml` file for deploying Spring Cloud Function applications to Microsoft Azure with Maven https://github.com/spring-cloud/spring-cloud-function/blob/{branch}/spring-cloud-function-samples/function-sample-azure/pom.xml[here]. NOTE: As of yet, only Maven plugin is available. Gradle plugin has not been created by the cloud platform provider. ==== Build ---- ./mvnw -U clean package ---- ==== Running the sample You can run the sample locally, just like the other Spring Cloud Function samples: --- ./mvnw spring-boot:run --- and `curl -H "Content-Type: text/plain" localhost:8080/api/uppercase -d '{"value": "hello foobar"}'`. You will need the `az` CLI app (see https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-java-maven for more detail). To deploy the function on Azure runtime: ---- $ az login $ mvn azure-functions:deploy ---- On another terminal try this: `curl https:///api/uppercase -d '{"value": "hello foobar!"}'`. Please ensure that you use the right URL for the function above. Alternatively you can test the function in the Azure Dashboard UI (click on the function name, go to the right hand side and click "Test" and to the bottom right, "Run"). The input type for the function in the Azure sample is a Foo with a single property called "value". So you need this to test it with something like below: ---- { "value": "foobar" } ---- NOTE: The Azure sample app is written in the "non-functional" style (using `@Bean`). The functional style (with just `Function` or `ApplicationContextInitializer`) is much faster on startup in Azure than the traditional `@Bean` style, so if you don't need `@Beans` (or `@EnableAutoConfiguration`) it's a good choice. Warm starts are not affected. == Running Sample Locally You can run this Azure function locally, similar to other Spring Cloud Function samples, however this time by using the Azure Maven plugin, as the Microsoft Azure functions execution context must be available. NOTE: To run locally on top of Azure Functions, and to deploy to your live Azure environment, you will need the Azure Functions Core Tools installed along with the Azure CLI (see https://docs.microsoft.com/en-us/azure/azure-functions/create-first-function-cli-java?tabs=bash%2Cazure-cli%2Cbrowser#configure-your-local-environment[here] for details). .Follow these steps to build and run locally: [source,bash] ---- ../../mvnw clean package ../../mvnw azure-functions:run ---- .console output [source,bash] ---- [INFO] Azure Function App's staging directory found at: /Users/cbono/repos/spring-cloud-function/spring-cloud-function-samples/function-sample-azure/target/azure-functions/spring-cloud-function-samples 4.0.3971 [INFO] Azure Functions Core Tools found. Azure Functions Core Tools Core Tools Version: 4.0.3971 Commit hash: d0775d487c93ebd49e9c1166d5c3c01f3c76eaaf (64-bit) Function Runtime Version: 4.0.1.16815 info: Microsoft.AspNetCore.Hosting.Diagnostics[1] Request starting HTTP/2 POST http://127.0.0.1:53836/AzureFunctionsRpcMessages.FunctionRpc/EventStream application/grpc - info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0] Executing endpoint 'gRPC - /AzureFunctionsRpcMessages.FunctionRpc/EventStream' [2022-04-11T03:04:05.143Z] OpenJDK 64-Bit Server VM warning: Options -Xverify:none and -noverify were deprecated in JDK 13 and will likely be removed in a future release. [2022-04-11T03:04:05.247Z] Worker process started and initialized. Functions: echo: [GET,POST] http://localhost:7071/api/echo echoStream: [GET,POST] http://localhost:7071/api/echoStream uppercase: [GET,POST] http://localhost:7071/api/uppercase uppercaseReactive: [GET,POST] http://localhost:7071/api/uppercaseReactive For detailed output, run func with --verbose flag. [2022-04-11T03:04:10.163Z] Host lock lease acquired by instance ID '000000000000000000000000BEFE21CF'. ---- .Test the _uppercase_ function using the following _curl_ command: [source,bash] ---- curl -H "Content-Type: application/json" localhost:7071/api/uppercase -d '{"greeting": "hello", "name": "foo"}' ---- .curl response [source,json] ---- { "greeting": "HELLO", "name": "FOO" } ---- Notice that the URL is of the format `/api/`). The `uppercase` function signature is `Function, String> uppercase()`. The implementation of `UppercaseHandler` (which extends `FunctionInvoker`) copies the HTTP headers of the incoming request into the input message's _MessageHeaders_ which makes them accessible to the function if needed. NOTE: Implementation of `FunctionInvoker` (your handler), should contain the least amount of code. It is really a type-safe way to define and configure function to be recognized as Azure Function. Everything else should be delegated to the base `FunctionInvoker` via `handleRequest(..)` callback which will invoke your function, taking care of necessary type conversion, transformation etc. One exception to this rule is when custom result handling is required. In that case, the proper post-process method can be overridden as well in order to take control of the results processing. .UppercaseHandler.java [source,java] ---- @FunctionName("uppercase") public String execute( @HttpTrigger( name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage> request, ExecutionContext context ) { Message message = MessageBuilder.withPayload(request.getBody().get()) .copyHeaders(request.getHeaders()).build(); return handleRequest(message, context); } ---- The `echo` function does the same as the `uppercase` less the actual uppercasing. However, the important difference to notice is that function itself takes primitive `String` as its input (i.e., `public Function echo()`) while the actual handler passes instance of `Message` the same way as with `uppercase`. The framework recognizes that you only care about the payload and extracts it from the `Message` before calling the function. There is also a reactive version of _uppercase_ (named _uppercaseReactive_) which will produce the same result, but demonstrates and validates the ability to use reactive functions with Azure. == Running on Azure NOTE: The Azure Java functions runtime does not yet support Java 17 but Spring Cloud Function 4.x requires it. To get around this limitation we deploy to Azure in a custom Docker container. Once https://github.com/Azure/azure-functions-java-worker/issues/548[Azure supports] Java 17 we can move back to using non-Docker deployments. ==== Custom Docker Image The steps below describe the process to create a custom Docker image which is suitable for deployment on Azure and contains the 4.x Azure Functions runtime, the MS Java 17 JVM, and the sample functions in this repo. ====== Image name Pick an image name for the Docker container (eg. `onobc/function-sample-azure-java17:1.0.0`) and update the _pom.xml_ `functionDockerImageName` property with the image name. TIP: By default it is expected that the image name is a publicly accessible image on Docker Hub. However, other registries and credentials can be configured as described https://github.com/microsoft/azure-maven-plugins/wiki/Azure-Functions:-Configuration-Details#supporte-runtime[here]. .Rebuild the functions (pom.xml was updated): [source,bash] ---- ../../mvnw clean package ---- .Build the Docker image: [source,bash] ---- docker build -t . ---- Test the Docker image locally by starting the container and issuing a request. .Start the function runtime locally in Docker: [source,bash] ---- docker run -p 8080:80 ---- .console output [source,bash] ---- cbono@cbono-a01 function-sample-azure % docker run -p 8080:80 onobc/function-sample-azure-java17:1.0.0 info: Host.Triggers.Warmup[0] Initializing Warmup Extension. info: Host.Startup[503] Initializing Host. OperationId: 'e7317c18-4daa-4d69-bf38-beaa51e1a012'. info: Host.Startup[504] Host initialization: ConsecutiveErrors=0, StartupCount=1, OperationId=e7317c18-4daa-4d69-bf38-beaa51e1a012 info: Microsoft.Azure.WebJobs.Hosting.OptionsLoggingService[0] LoggerFilterOptions { "MinLevel": "None", "Rules": [ { "ProviderName": null, "CategoryName": null, "LogLevel": null, "Filter": "b__0" }, { "ProviderName": "Microsoft.Azure.WebJobs.Script.WebHost.Diagnostics.SystemLoggerProvider", "CategoryName": null, "LogLevel": "None", "Filter": null }, { "ProviderName": "Microsoft.Azure.WebJobs.Script.WebHost.Diagnostics.SystemLoggerProvider", "CategoryName": null, "LogLevel": null, "Filter": "b__0" } ] } ... ... ... info: Microsoft.Azure.WebJobs.Script.WebHost.WebScriptHostHttpRoutesManager[0] Initializing function HTTP routes Mapped function route 'api/echo' [GET,POST] to 'echo' Mapped function route 'api/echoStream' [GET,POST] to 'echoStream' Mapped function route 'api/uppercase' [GET,POST] to 'uppercase' Mapped function route 'api/uppercaseReactive' [GET,POST] to 'uppercaseReactive' info: Host.Startup[412] Host initialized (65ms) info: Host.Startup[413] Host started (81ms) info: Host.Startup[0] Job host started Hosting environment: Production Content root path: /azure-functions-host Now listening on: http://[::]:80 Application started. Press Ctrl+C to shut down. info: Microsoft.Azure.WebJobs.Script.Workers.Rpc.RpcFunctionInvocationDispatcher[0] Worker process started and initialized. info: Host.General[337] Host lock lease acquired by instance ID '000000000000000000000000C4043012'. ---- .Test the _uppercase_ function using the following _curl_ command: [source,bash] ---- curl -H "Content-Type: application/json" localhost:8080/api/uppercase -d '{"greeting": "hello", "name": "foo"}' ---- .curl response [source,json] ---- { "greeting": "HELLO", "name": "FOO" } ---- .Push the image to Docker registry: [source,bash] ---- docker push ---- At this point the custom image has been created and pushed to the configured Docker registry. ==== Deploy to Azure To deploy the functions to your live Azure environment, including automatic provisioning of an _HTTPTrigger_ for each function, do the following. .Login to Azure: [source,bash] ---- az login ---- .Deploy to Azure: [source,bash] ---- ../../mvnw azure-functions:deploy ---- .console output [source,bash] ---- [INFO] ---------------< io.spring.sample:function-sample-azure >--------------- [INFO] Building function-sample-azure 4.0.0.RELEASE [INFO] --------------------------------[ jar ]--------------------------------- [INFO] [INFO] --- azure-functions-maven-plugin:1.16.0:deploy (default-cli) @ function-sample-azure --- Auth type: AZURE_CLI Default subscription: SCDF-Azure(b80d18******) Username: cbono@vmware.com [INFO] Subscription: SCDF-Azure(*******) [INFO] Reflections took 123 ms to scan 6 urls, producing 24 keys and 486 values [INFO] Start creating Resource Group(java-functions-group) in region (West US)... [INFO] Resource Group(java-functions-group) is successfully created. [INFO] Reflections took 1 ms to scan 3 urls, producing 12 keys and 12 values [INFO] Creating app service plan java-functions-app-service-plan... [INFO] Successfully created app service plan java-functions-app-service-plan. [INFO] Start creating Application Insight (spring-cloud-function-samples)... [INFO] Application Insight (spring-cloud-function-samples) is successfully created. You can visit https://ms.portal.azure.com/********providers/Microsoft.Insights/components/spring-cloud-function-samples to view your Application Insights component. [INFO] Creating function app spring-cloud-function-samples... [INFO] Set function worker runtime to java. [INFO] Ignoring decoding of null or empty value to:com.azure.resourcemanager.storage.fluent.models.StorageAccountInner [INFO] Successfully created function app spring-cloud-function-samples. [INFO] Skip deployment for docker app service [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 01:30 min [INFO] Finished at: 2022-04-04T19:06:24-05:00 [INFO] ------------------------------------------------------------------------ ---- TIP: When deployed as a Docker container the function urls are not written to the console. You will need to inspect the functions in the Azure Portal to find the urls. ==== Inspect in Azure Portal Navigate to the https://portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.Web%2Fsites/kind/functionapp[Function App] dashboard in the Azure portal and then: * click on your function app (`"spring-cloud-function-samples"` by default) * click the left nav `"Functions"` link * click the `"uppercase"` function ====== Function Url Click the `"Get Function Url"` link to see the function's url. ====== Test via Portal * click on the left nav `"Code and Test"` * click on `"Test/Run"` at top of page * enter the following input json in the `"Body"` section on the right-hand side: [source,json] ---- { "greeting": "hello", "name": "foo" } ---- * click "Run" and the output should look like: [source,json] ---- { "greeting": "HELLO", "name": "FOO" } ---- ===== Test via cURL Armed w/ the function url from above, issue the following curl command in another terminal: [source,bash] ---- curl -H "Content-Type: application/json" https://spring-cloud-function-samples.azurewebsites.net/api/uppercase -d '{"greeting": "hello", "name": "foo"}' ---- .curl response [source,json] ---- { "greeting": "HELLO", "name": "FOO" } ---- TIP: The Azure dashboard provides a plethora of information about your functions, including but not limited to execution count, memory consumption and execution time. ==== Custom Result Handling As noted above, the implementation of `FunctionInvoker` (your handler), should contain the least amount of code possible. However, if custom result handling needs to occur there is a set of methods (named `postProcess**`) that can be overridden in link:../../spring-cloud-function-adapters/spring-cloud-function-adapter-azure/src/main/java/org/springframework/cloud/function/adapter/azure/FunctionInvoker.java[FunctionInvoker.java]. One such example can be seen in link:src/main/java/example/ReactiveEchoCustomResultHandler.java[ReactiveEchoCustomResultHandler.java]. Once the function is deployed it can be tested using _curl_: [source,bash] ---- curl -H "Content-Type: application/json" localhost:7071/api/echoStream -d '["hello","peepz"]' ---- .result [source,bash] ---- Kicked off job for [hello, peepz] ---- The custom result handling takes the Flux returned from the `echoStream` function and adds logging, uppercase mapping, and then subscribes to the publisher. The Azure logs output the following: [source,bash] ---- [2022-03-01T01:36:57.439Z] 2022-02-28 19:36:57.439 INFO 20587 --- [pool-2-thread-2] o.s.boot.SpringApplication : Started application in 0.466 seconds (JVM running for 57.906) [2022-03-01T01:36:57.462Z] BEGIN echo post-processing work ... [2022-03-01T01:36:57.462Z] HELLO [2022-03-01T01:36:57.462Z] PEEPZ [2022-03-01T01:36:57.463Z] END echo post-processing work [2022-03-01T01:36:57.463Z] Function "echoStream" (Id: 678cff0b-d958-4fab-967b-e19e0d5d67e8) invoked by Java Worker ----