Merge pull request #32539 from abrennan89/godocs

[srvls][SRVOCF-278] Adding golang functions docs

Author: bergerhoffer

_topic_map.yml

@@ -2944,15 +2944,17 @@ Topics:
   - Name: Using a Kafka source
     File: serverless-kafka-source
 # Functions - uncomment at tech preview
-# - Name: OpenShift Serverless Functions
-#   Dir: functions
+#- Name: Functions
+#  Dir: functions
 #  Topics:
 #  - Name: About OpenShift Serverless Functions
 #    File: serverless-functions-about
 #  - Name: Getting started
 #    File: serverless-functions-getting-started
 #  - Name: Setting up OpenShift Serverless Functions
 #    File: serverless-functions-setup
+#  - Name: Developing Golang functions
+#    File: serverless-developing-go-functions
 #  - Name: Developing Python functions
 #    File: serverless-developing-python-functions
 # Networking

modules/serverless-create-func-kn.adoc

@@ -34,8 +34,8 @@ envVars: {}
 ----
 $ kn func create <path> -r <registry> -l <runtime> -t <trigger> -i <image> -n <namespace>
 ----
-+
-If the image is unspecified, you are prompted for a registry name. The image name is derived from this registry and the function name.
+** Supported runtimes include `node`, `go`, `python`, and `quarkus`.
+** If the image is unspecified, you are prompted for a registry name. The image name is derived from this registry and the function name.
 +
 .Example command
 [source,terminal]

modules/serverless-go-function-return-values.adoc

@@ -0,0 +1,50 @@
+// Module included in the following assemblies
+//
+// * /serverless/functions/serverless-developing-go-functions.adoc
+
+[id="serverless-go-function-return-values_{context}"]
+= Golang function return values
+
+HTTP triggered functions can set the response directly by using the Golang link:https://golang.org/pkg/net/http/#ResponseWriter[http.ResponseWriter].
+
+.Example HTTP response
+[source,go]
+----
+func Handle(ctx context.Context, res http.ResponseWriter, req *http.Request) {
+  // Set response
+  res.Header().Add("Content-Type", "text/plain")
+  res.Header().Add("Content-Length", "3")
+  res.WriteHeader(200)
+  _, err := fmt.Fprintf(res, "OK\n")
+  if err != nil {
+	fmt.Fprintf(os.Stderr, "error or response write: %v", err)
+  }
+}
+----
+
+Functions triggered by a CloudEvent might return nothing, `error`, or `CloudEvent` in order to push events into the Knative Eventing system. In this case, you must set a unique `ID`, proper `Source`, and a `Type` for the CloudEvent. The data can be populated from a defined structure, or from a `map`.
+
+.Example CloudEvent response
+[source,go]
+----
+func Handle(ctx context.Context, event cloudevents.Event) (resp *cloudevents.Event, err error) {
+  // ...
+  response := cloudevents.NewEvent()
+  response.SetID("example-uuid-32943bac6fea")
+  response.SetSource("purchase/getter")
+  response.SetType("purchase")
+  // Set the data from Purchase type
+  response.SetData(cloudevents.ApplicationJSON, Purchase{
+	CustomerId: custId,
+	ProductId:  prodId,
+  })
+  // OR set the data directly from map
+  response.SetData(cloudevents.ApplicationJSON, map[string]string{"customerId": custId, "productId": prodId})
+  // Validate the response
+  resp = &response
+  if err = resp.Validate(); err != nil {
+	fmt.Printf("invalid event created. %v", err)
+  }
+  return
+}
+----

modules/serverless-go-template.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies
+//
+// * /serverless/functions/serverless-developing-go-functions.adoc
+
+[id="serverless-go-template_{context}"]
+= Golang function template structure
+
+When you create a Golang function using the `kn` CLI, the project directory looks like a typical Go project, with the exception of an additional `func.yaml` configuration file.
+
+Golang functions have few restrictions. The only requirements are that your project must be defined in a `function` module, and must export the function `Handle()`.
+
+Both `http` and `event` trigger functions have the same template structure:
+
+.Template structure
+[source,terminal]
+----
+fn
+├── README.md
+├── func.yaml <1>
+├── go.mod <2>
+├── go.sum
+├── handle.go
+└── handle_test.go
+----
+<1> The `func.yaml` configuration file is used to determine the image name and registry.
+<2> You can add any required dependencies to the `go.mod` file, which can include additional local Golang files. When the project is built for deployment, these dependencies are included in the resulting runtime container image.
++
+.Example of adding dependencies
+[source,terminal]
+----
+$ go get gopkg.in/[email protected]
+----

modules/serverless-invoking-go-functions-cloudevent.adoc

@@ -0,0 +1,69 @@
+// Module included in the following assemblies
+//
+// * /serverless/functions/serverless-developing-go-functions.adoc
+
+[id="serverless-invoking-go-functions-cloudevent_{context}"]
+= Functions triggered by a CloudEvent
+
+When an incoming CloudEvent is received, the event is invoked by the link:https://cloudevents.github.io/sdk-go/[CloudEvents Golang SDK] and the `Event` type as a parameter.
+
+You can leverage the Golang link:https://golang.org/pkg/context/[Context] as an optional parameter in the function contract, as shown in the list of supported function signatures:
+
+.Supported function signatures
+[source,go]
+----
+Handle()
+Handle() error
+Handle(context.Context)
+Handle(context.Context) error
+Handle(cloudevents.Event)
+Handle(cloudevents.Event) error
+Handle(context.Context, cloudevents.Event)
+Handle(context.Context, cloudevents.Event) error
+Handle(cloudevents.Event) *cloudevents.Event
+Handle(cloudevents.Event) (*cloudevents.Event, error)
+Handle(context.Context, cloudevents.Event) *cloudevents.Event
+Handle(context.Context, cloudevents.Event) (*cloudevents.Event, error)
+----
+
+[id="serverless-invoking-go-functions-cloudevent-example_{context}"]
+== CloudEvent trigger example
+
+A CloudEvent is received which contains a JSON string in the data property:
+
+[source,json]
+----
+{
+  "customerId": "0123456",
+  "productId": "6543210"
+}
+----
+
+To access this data, a structure must be defined which maps properties in the CloudEvent data, and retrieves the data from the incoming event. The following example uses the `Purchase` structure:
+
+[source,go]
+----
+type Purchase struct {
+  CustomerId string `json:"customerId"`
+  ProductId  string `json:"productId"`
+}
+func Handle(ctx context.Context, event cloudevents.Event) (err error) {
+
+  purchase := &Purchase{}
+  if err = event.DataAs(purchase); err != nil {
+	fmt.Fprintf(os.Stderr, "failed to parse incoming CloudEvent %s\n", err)
+	return
+  }
+  // ...
+}
+----
+
+Alternatively, a Golang `encoding/json` package could be used to access the CloudEvent directly as JSON in the form of a bytes array:
+
+[source,go]
+----
+func Handle(ctx context.Context, event cloudevents.Event) {
+  bytes, err := json.Marshal(event)
+  // ...
+}
+----

modules/serverless-invoking-go-functions-http.adoc

@@ -0,0 +1,29 @@
+// Module included in the following assemblies
+//
+// * /serverless/functions/serverless-developing-go-functions.adoc
+
+[id="serverless-invoking-go-functions-http_{context}"]
+= Functions triggered by an HTTP request
+
+When an incoming HTTP request is received, your function is invoked with a standard Golang link:https://golang.org/pkg/context/[Context] as the first parameter, followed by two more parameters:
+
+* link:https://golang.org/pkg/net/http/#ResponseWriter[`http.ResponseWriter`]
+* link:https://golang.org/pkg/net/http/#Request[`http.Request`]
+
+You can use standard Golang techniques to access the request, and set a proper HTTP response of your function.
+
+.Example HTTP response
+[source,go]
+----
+func Handle(ctx context.Context, res http.ResponseWriter, req *http.Request) {
+  // Read body
+  body, err := ioutil.ReadAll(req.Body)
+  defer req.Body.Close()
+  if err != nil {
+	http.Error(res, err.Error(), 500)
+	return
+  }
+  // Process body and function logic
+  // ...
+}
+----

modules/serverless-python-function-return-values.adoc

@@ -5,7 +5,7 @@
 [id="serverless-python-function-return-values_{context}"]
 = Python function return values
 
-Functions can return any value supported by https://flask.palletsprojects.com/en/1.1.x/quickstart/#about-responses[Flask] because the invocation framework proxies these values directly to the Flask server.
+Functions can return any value supported by link:https://flask.palletsprojects.com/en/1.1.x/quickstart/#about-responses[Flask] because the invocation framework proxies these values directly to the Flask server.
 
 .Example
 [source,python]
@@ -34,4 +34,4 @@ def main(context):
     return data
 ----
 
-This example sends a CloudEvent as the response value, with a type of `"my.type"` and a source of `"/my/function"`. The CloudEvent [`data` property](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#event-data) is set to the returned `data` variable. The `event_source` and `event_type` decorator attributes are both optional.
+This example sends a CloudEvent as the response value, with a type of `"my.type"` and a source of `"/my/function"`. The CloudEvent link:https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#event-data[`data` property] is set to the returned `data` variable. The `event_source` and `event_type` decorator attributes are both optional.

modules/serverless-python-template.adoc

@@ -5,7 +5,7 @@
 [id="serverless-python-template_{context}"]
 = Python function template structure
 
-When you create a Python function by using the `kn func` CLI, the project directory looks similar to a typical Python project.
+When you create a Python function by using the `kn` CLI, the project directory looks similar to a typical Python project.
 
 Python functions have very few restrictions. The only requirements are that your project contains a `func.py` file that contains a `main()` function, and a `func.yaml` configuration file.
 

modules/serverless-testing-go-functions.adoc

@@ -0,0 +1,17 @@
+// Module included in the following assemblies
+//
+// * /serverless/functions/serverless-developing-go-functions.adoc
+
+[id="serverless-testing-go-functions_{context}"]
+= Testing Golang functions
+
+Golang functions can be tested locally on your computer. In the default project that is created when you create a function using `kn func create`, there is a `handle_test.go` file which contains some basic tests. These tests can be extended as needed.
+
+.Procedure
+
+* Run the tests:
++
+[source,terminal]
+----
+$ go test
+----

serverless/functions/serverless-developing-go-functions.adoc

@@ -0,0 +1,35 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-developing-go-functions"]
+= Developing Golang functions
+:context: serverless-developing-go-functions
+include::modules/common-attributes.adoc[]
+
+toc::[]
+
+:FeatureName: {FunctionsProductName}
+include::modules/technology-preview.adoc[leveloffset=+2]
+
+After you have xref:../../serverless/functions/serverless-functions-getting-started.adoc#serverless-create-func-kn_serverless-functions-getting-started[created a Golang function project], you can modify the template files provided to add business logic to your function.
+
+[id="prerequisites_serverless-developing-go-functions"]
+== Prerequisites
+
+* Before you can develop functions, you must complete the steps in xref:../../serverless/functions/serverless-functions-setup.adoc#serverless-functions-setup[Setting up {FunctionsProductName}].
+
+include::modules/serverless-go-template.adoc[leveloffset=+1]
+
+[id="serverless-developing-go-functions-about-invoking_{context}"]
+== About invoking Golang functions
+
+Golang functions are invoked by using different methods, depending on whether they are triggered by a HTTP request or a CloudEvent.
+
+include::modules/serverless-invoking-go-functions-http.adoc[leveloffset=+2]
+include::modules/serverless-invoking-go-functions-cloudevent.adoc[leveloffset=+2]
+
+include::modules/serverless-go-function-return-values.adoc[leveloffset=+1]
+include::modules/serverless-testing-go-functions.adoc[leveloffset=+1]
+
+[id="next-steps_serverless-developing-go-functions"]
+== Next steps
+
+* xref:../../serverless/functions/serverless-functions-getting-started.adoc#serverless-build-func-kn_serverless-functions-getting-started[Build] and xref:../../serverless/functions/serverless-functions-getting-started.adoc#serverless-deploy-func-kn_serverless-functions-getting-started[deploy] a function.