== (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<Message<String>, String> {

	@FunctionName("uppercase")
	public String execute(@HttpTrigger(name = "req", methods = {HttpMethod.GET,
			HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
		ExecutionContext context) {
		Message<String> 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<String, String> uppercase() {
		return payload -> payload.toUpperCase();
}

OR

@Bean
public Function<Message<String>, 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<Message<String>, 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]
----
<dependencies>
	<dependency>
		<groupId>org.springframework.cloud</groupId>
		<artifactId>spring-cloud-function-adapter-azure</artifactId>
	</dependency>
</dependencies>
----

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]
----
<plugin>
	<groupId>com.microsoft.azure</groupId>
	<artifactId>azure-functions-maven-plugin</artifactId>
	<configuration>
		<resourceGroup>${functionResourceGroup}</resourceGroup>
		<appName>${functionAppName}</appName>
	</configuration>
	<executions>
		<execution>
			<id>package-functions</id>
			<goals>
				<goal>package</goal>
			</goals>
		</execution>
	</executions>
</plugin>
----

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://<azure-function-url-from-the-log>/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 `<function-base-url>/api/<function-name>`).

The `uppercase` function signature is `Function<Message<String>, 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<Optional<String>> request,
    ExecutionContext context
) {
    Message<String> 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<String, String> 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 <image-name> .
----

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 <image-name>
----

.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": "<AddFilter>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": "<AddFilter>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 <image-name>
----
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
----
