Merge pull request #10693 from patriot1burke/funqy-improvements

funqy docs disclaimers and usage improvements

docs/src/main/asciidoc/funqy-amazon-lambda-http.adoc

@@ -8,14 +8,21 @@ https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc
 
 include::./attributes.adoc[]
 
-If you like link:funqy-http[Funqy HTTP], you can use it on AWS Lambda.  Quarkus allows you to expose multiple
-Funqy functions through HTTP deployed as one AWS Lambda.
+If you want to allow HTTP clients to invoke on your Funqy functions on AWS Lambda, Quarkus allows you to expose multiple
+Funqy functions through HTTP deployed as one AWS Lambda.  This approach does add overhead over the
+regular Funqy AWS Lambda integration and also requires you to use AWS API Gateway.
 
 include::./status-include.adoc[]
 
 Follow the link:amazon-lambda-http[Amazon Lambda Http Guide].  It walks through using a variety of HTTP
 frameworks on Amazon Lambda, including Funqy.
 
+WARNING: The Funqy HTTP + AWS Lambda binding is not a replacement for REST over HTTP.  Because Funqy
+needs to be portable across a lot of different protocols and function providers its HTTP binding
+is very minimalistic and you will lose REST features like linking and the ability to leverage
+HTTP features like cache-control and conditional GETs.  You may want to consider using Quarkus's
+JAX-RS, Spring MVC, or Vert.x Web Reactive Route link:amazon-lambda-http[support] instead.  They also work with Quarkus and AWS Lambda.
+
 == An additional Quickstart
 
 Beyond generating an AWS project that is covered in the link:amazon-lambda-http[Amazon Lambda Http Guide],

docs/src/main/asciidoc/funqy-amazon-lambda.adoc

@@ -20,6 +20,7 @@ include::./status-include.adoc[]
 To complete this guide, you need:
 
 * less than 30 minutes
+* Read about link:funqy[Funqy Basics].  This is a short read!
 * JDK 11 (AWS requires JDK 1.8 or 11)
 * Apache Maven {maven-version}
 * https://aws.amazon.com[An Amazon AWS account]

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

@@ -11,6 +11,13 @@ include::./attributes.adoc[]
 You can use link:funqy-http[Funqy HTTP] on Azure Functions.  This allows you to invoke on multiple Funqy functions
 using HTTP deployed as one Azure Function.
 
+WARNING: The Funqy HTTP + Azure Functions binding is not a replacement for REST over HTTP.  Because Funqy
+needs to be portable cross a lot of different protocols and function providers its HTTP binding
+is very minimalistic and you will lose REST features like linking and the ability to leverage
+HTTP features like cache-control and conditional GETs.  You may want to consider using Quarkus's
+JAX-RS, Spring MVC, or Vert.x Web Reactive Route link:azure-functions-http[support] instead.  They also work with Quarkus and Azure Functions.
+
+
 include::./status-include.adoc[]
 
 Follow the link:azure-functions-http[Azure Functions Http Guide].  It walks through using a variety of HTTP

docs/src/main/asciidoc/funqy-http.adoc

@@ -11,6 +11,13 @@ include::./attributes.adoc[]
 The guide walks through quickstart code to show you how you can deploy Funqy as a
 standalone service and invoke on Funqy functions using HTTP.
 
+WARNING: The Funqy HTTP binding is not a replacement for REST over HTTP.  Because Funqy
+needs to be portable across a lot of different protocols and function providers its HTTP binding
+is very minimalistic and you will lose REST features like linking and the ability to leverage
+HTTP features like cache-control and conditional GETs.  You may want to consider using Quarkus's
+JAX-RS, Spring MVC, or Vert.x Web Reactive Routes support instead, although Funqy will have less overhead
+than these alternatives (except Vert.x which is still super fast).
+
 == Prerequisites
 
 To complete this guide, you need:

docs/src/main/asciidoc/funqy.adoc

@@ -12,9 +12,11 @@ Quarkus Funqy is part of Quarkus's serverless strategy and aims to provide a por
 deployable to various FaaS environments like AWS Lambda, Azure Functions, Knative, and Knative Events (Cloud Events).  It is also
 usable as a standalone service.
 
-Another goal of Funqy is to create an RPC framework that is as small and as optimized as possible for the
-Quarkus runtime.  This means sacrificing a little bit on flexibility to provide a runtime that has little to no overhead.  Funqy
-should never become more complicated than you see in this initial doc.
+Because Funqy is an abstraction that spans multiple different cloud/function providers
+and protocols it has to be a very simple API and thus, might not have all the features you are used
+to in other remoting abstractions.  A nice side effect though is that Funqy is as optimized and
+as small as possible.  This means that because Funqy sacrifices a little bit on flexibility, you'll
+get a framework that has little to no overhead.
 
 == Funqy Basics
 
@@ -135,13 +137,16 @@ public class GreetingFunction {
 
 == Context injection
 
-You can inject contextual information that is specific to the Funqy runtime or specific to the
-Funqy binding you are using (lambda, azure, cloud events, etc.).
+The Funqy API will usually not allow you to inject or use abstractions that
+are specific to a protocol (i.e. HTTP) or function API (i.e. AWS Lambda).  There are
+exceptions to the rule though and you may be able to inject
+contextual information that is specific to the environment you are deploying in.
 
 NOTE: We do not recommend injecting contextual information specific to a runtime.  Keep your functions portable.
 
 Contextual information is injected via the `@Context` annotation which can be used on a function parameter
-or a class field.
+or a class field.  A good example is the `CloudEvent` interface that comes with our Funqy
+Knative Cloud Events integration:
 
 [source, java]
 ----
@@ -151,13 +156,33 @@ import io.quarkus.funqy.Context;
 public class GreetingFunction {
 
     @Funq
-    public Greeting greet(Friend friend, @Context AwsContext ctx) {
+    public Greeting greet(Friend friend, @Context CloudEvent eventInfo) {
+        System.out.println("Received greeting request from: " eventInfo.getSource());
+
         Greeting greeting = new Greeting();
-        greeting.setMessage(service.greet(friend.getName()));
+        greeting.setMessage("Hello " + friend.getName()));
         return greeting;
     }
 }
 ----
 
-
+== Should I Use Funqy?
+
+REST over HTTP has become a very common way to write services over the past decade.  While Funqy
+has an HTTP binding it is not a replacement for REST.  Because Funqy has to work across a variety
+of protocols and function cloud platforms, it is very minimalistic and constrained.  For example, if you
+use Funqy you lose the ability to link (think URIs) to the data your functions spit out.  You also
+lose the ability to leverage cool HTTP features like `cache-control` and conditional GETs.  Many
+developers will be ok with that as many won't be using these REST/HTTP features or styles. You'll
+have to make the decision on what camp you are in.  Quarkus does support REST integration (through JAX-RS,
+ Spring MVC, Vert.x Web, and Servlet) with
+various cloud/function providers, but there are some disadvantages of using that approach as well.  For example,
+if you want to do link:amazon-lambda-http[HTTP with AWS Lambda], this requires you to use the AWS API Gateway which may
+slow down deployment and cold start time or even cost you more.
+
+The purpose of Funqy is to allow you to write cross-provider functions so that you can move
+off of your current function provider if, for instance, they start charging you a lot more for their
+service.  Another reason you might not want to use Funqy is if you need access specific APIs of the
+target function environment.  For example, developers often want access to the AWS Context on
+Lambda.  In this case, we tell them they may be better off using the link:amazon-lambda[Quarkus Amazon Lambda] integration instead.