Updated docs on configuration and required env vars. (#285)

* Updated docs on configuration and required env vars.

* minor

docs/README.md

@@ -7,6 +7,10 @@ If you are a developer using Fn through the API, this section is for you.
 * [Quickstart](https://github.com/fnproject/fn)
 * [Usage](usage.md)
 * [Writing functions](writing.md)
+* [Testing functions](testing.md)
+* [Hot functions](hot-functions.md)
+* [Async functions](async.md)
+* [Configuration](developers/configs.md)
 * [fn (CLI Tool)](https://github.com/fnproject/cli/blob/master/README.md)
 * [Hot functions](hot-functions.md)
 * [Async functions](async.md)
@@ -15,7 +19,7 @@ If you are a developer using Fn through the API, this section is for you.
 * [Client Libraries](developers/clients.md)
 * [Packaging functions](packaging.md)
 * [Open Function Format](function-format.md)
-* API Reference (coming soon)
+* [API Reference](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/fnproject/fn/master/docs/swagger.yml)
 * [Object Model](developers/model.md)
 * [FAQ](faq.md)
 

docs/developers/configs.md

@@ -0,0 +1,20 @@
+# Function Config Vars
+
+There are three ways to get configuration variables into a function, all of which will be available as environment variables.
+These are ordered in order of preference, the later ones overriding the previous ones.
+
+## 1. Application level configuration
+
+```sh
+fn apps config set myapp LOG_LEVEL debug
+```
+
+## 2. Function configuration from func.yaml
+
+See [Function file](../function-file.md) for more info.
+
+## 3. Route level configuration
+
+```sh
+fn routes config set myapp hello2 LOG_LEVEL info
+```

docs/function-file.md

@@ -19,11 +19,16 @@ config:
   key2: value2
   keyN: valueN
 headers:
-  content-type:
+  Content-Type: text/plain
-   - text/plain
 build:
 - make
 - make test
+expects:
+  config:
+    - name: SECRET_1
+      required: true
+    - name: SECRET_2
+      required: false
 ```
 
 `name` is the name and tag to which this function will be pushed to and the
@@ -40,7 +45,7 @@ appended to the image as a tag.
 'go', 'python', 'java', etc.  The runtime 'docker' will use the existing Dockerfile if one exists.
 
 `build` (optional) is an array of local shell calls which are used to help
-building the function.
+building the function. TODO: Deprecate this?
 
 `type` (optional) allows you to set the type of the route. `sync`, for functions
 whose response are sent back to the requester; or `async`, for functions that
@@ -56,9 +61,12 @@ and error message is logged. Default: `128`.
 `headers` (optional) is a set of HTTP headers to be returned in the response of
 this function calls.
 
-`config` (optional) is a set of configurations to be passed onto the route
+`config` (optional) is a set of configuration variables to be passed onto the function as environment variables.
-setup. These configuration options shall override application configuration
+These configuration options shall override application configuration during functions execution. See [Configuration](developers/configs.md)
-during functions execution.
+for more information.
+
+`expects` (optional) a list of config/env vars that are required to run this function. These vars will be used when running/testing locally,
+if found in your local environment. If these vars are not found, local testing will fail.
 
 ## Hot functions
 
@@ -67,31 +75,4 @@ hot functions support also adds two extra options to this configuration file.
 `format` (optional) is one of the streaming formats covered at [function-format.md](function-format.md).
 
 `idle_timeout` (optional) is the time in seconds a container will remain alive without receiving any new requests; 
-hot functions will stay alive as long as they receive a request in this interval. Default: `30`. 
+hot functions will stay alive as long as they receive a request in this interval. Default: `30`.
-
-## Testing functions
-
-`tests` (optional) is an array of tests that can be used to valid functions both
-locally and remotely. It has the following structure
-
-```yaml
-tests:
-- name: envvar
-  in: "inserted stdin"
-  out: "expected stdout"
-  err: "expected stderr"
-  env:
-    envvar: trololo
-```
-
-`in` (optional) is a string that is going to be sent to the file's declared
-function.
-
-`out` (optional) is the expected output for this function test. It is present
-both in local and remote executions.
-
-`err` (optional) similar to `out`, however it read from `stderr`. It is only
-available for local machine tests.
-
-`env` (optional) is a map of environment variables that are injected during
-tests.

docs/packaging.md

@@ -20,25 +20,25 @@ The basic Dockerfile for most languages is along these lines:
 
 ```
 # Choose base image
-FROM funcy/node:dev
+FROM node:alpine
 # Set the working directory
 WORKDIR /function
 # Add your binary or code to the working directory
-ADD funcbin /function/
+ADD . /function/
 # Set what will run when a container is started for this image
-ENTRYPOINT ["./funcbin"]
+ENTRYPOINT ["node func.js"]
 ```
 
 Then build your function image:
 
 ```sh
-docker build -t $USERNAME/myfunction .
+fn build
 ```
 
 ### Push your image
 
 ```sh
-docker push $USERNAME/myfunction
+fn push
 ```
 
-Now you can use that image when creating or updating routes. 
+Now you can use that image when creating or updating routes.

examples/inputs/.gitignore

@@ -0,0 +1,6 @@
+vendor/
+/go
+/app
+/__uberscript__
+
+func.yaml

examples/inputs/README.md

@@ -0,0 +1,15 @@
+# Tutorial 1: Go Function w/ Input (3 minutes)
+
+Example for putting required vars into the func.yaml file.
+
+Try running the following:
+
+```sh
+fn run
+# > ERROR: required env var SECRET_1 not found, please set either set it in your environment or pass in `-e SECRET_1=X` flag.
+SECRET_1=YOOO fn run
+# > info: optional env var SECRET_2 not found.
+# > {"SECRET_1":"YOOO","SECRET_2":"","message":"Hello World"}
+SECRET_1=YOOO SECRET_2=DAWG fn run
+# > {"SECRET_1":"YOOO","SECRET_2":"DAWG","message":"Hello World"}
+```

examples/inputs/func.go

@@ -0,0 +1,21 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+)
+
+type Person struct {
+	Name string
+}
+
+func main() {
+	p := &Person{Name: "World"}
+	json.NewDecoder(os.Stdin).Decode(p)
+	mapD := map[string]string{"message": fmt.Sprintf("Hello %s", p.Name)}
+	mapD["SECRET_1"] = os.Getenv("SECRET_1")
+	mapD["SECRET_2"] = os.Getenv("SECRET_2")
+	mapB, _ := json.Marshal(mapD)
+	fmt.Println(string(mapB))
+}

examples/inputs/sample.payload.json

@@ -0,0 +1,3 @@
+{
+    "name": "Johnny"
+}

examples/inputs/test.json

@@ -0,0 +1,26 @@
+{
+    "tests": [
+        {
+            "input": {
+                "body": {
+                    "name": "Johnny"
+                }
+            },
+            "output": {
+                "body": {
+                    "message": "Hello Johnny"
+                }
+            }
+        },
+        {
+            "input": {
+                "body": ""
+            },
+            "output": {
+                "body": {
+                    "message": "Hello World"
+                }
+            }
+        }
+    ]
+}