Merge pull request #94 from sevenval/develop

Release 20200828

CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 
-## Unreleased
+## [20200828](https://hub.docker.com/r/sevenvaltechnologies/flatrunner/tags)
+
+### Added
+
+- [`FLAT_DEBUG_ALLOW_HEADER`](/reference/debugging.md#per-request-debugging) to enable debugging using the `Debug` request header, defaults to `false`
+- The [request option](/reference/actions/request.md#options) `force-cache-refresh`
+- The [`ldap-lookup()` function](/reference/functions/ldap-lookup.md)
+- The `cacheHit` property in the [upstream response information (`$upstream`)](/reference/variables.md#usdupstream)
+
+## Fixed
+
+- Empty objects are no longer [logged](/cookbook/custom-logging.md#adding-a-log-field) as empty arrays.
+- The [`json-to-csv()` function](/reference/functions/json-to-csv.md) allows `null` values in array entry objects.
+
+## Changed
+
+The [`log` action](/reference/actions/log.md) can no longer override [system log fields](/administration/logging.md#fields).
+
 
 ## [20200519](https://hub.docker.com/r/sevenvaltechnologies/flatrunner/tags)
 

administration/configuration.md

@@ -1,7 +1,7 @@
 # Configuration
 
 
-Certain settings of the FLAT runner can be configured using environment variables.
+Certain settings of the FLAT server can be configured using environment variables.
 The chapter [Defining Env Vars](/cookbook/envvars.md#defining-env-vars) in the Cookbook provides information on how to set environment variables.
 
 
@@ -11,7 +11,8 @@ The chapter [Defining Env Vars](/cookbook/envvars.md#defining-env-vars) in the C
 
 * `FLAT_SERVER_ROLE`: This setting is typically used to distinguish production systems from staging or development servers. Its value is accessible in the [`$server` variable](/reference/variables.md#predefined-variables) as `$server/role`.
 * `FLAT_STATUS_AUTH`: Username and password, separated by a `:` for access to the `php-fpm` and `httpd` status pages. The pages are disabled entirely if `FLAT_STATUS_AUTH` is not set. If enabled, the `httpd` status can be requested via HTTP at `/ServerStatus`, and the php-fpm status at `/FPMStatus?full`.
-
+* `FLAT_DEBUG_ALLOW_HEADER`: enable [per request debugging](/reference/debugging.md#request-debugging), defaults to `false` unless `FLAT_DEBUG_AUTH` is set.
+* `FLAT_DEBUG_AUTH`: sets a password to protect [per request debugging](/reference/debugging.md#request-debugging).
 
 ### Request Timeouts
 

cookbook/README.md

@@ -1,37 +1,39 @@
 # Cookbook
 
-## [How can I inspect the client request?](see-client-request.md)
-
-## [How can I pass an arbitrary header field to an upstream system?](pass-header-field-upstream.md)
+## [Protecting Access using JWT Tokens](x-flat-jwt.md)
 
 ## [Proxying Requests to Upstream APIs (Swagger)](proxy-requests.md)
 
-## [Forwarding a Request to an Upstream API (Flow)](forward-request-upstream.md)
+## [Testing Templates](test-templates.md)
 
-## [How can I pass response headers to the client?](pass-header-field-downstream.md)
+## [Testing API Requests](test-api-request.md)
 
-## [How can I increase the request timeout to deal with a slow upstream system?](request-timeout.md)
+## [Testing with Backend Requests](test-backend.md)
 
-## [Sending POST requests](upstream-post-requests.md)
+## [File Serving](file-serving.md)
 
-## [Working with JWT](jwt.md)
+## [Error Handling](error-flow.md)
 
-## [Auto Docs with Swagger UI](swagger-docs.md)
+## [Extracting Common Initialization Flow Tasks](init-flow.md)
 
-## [Using the Built-in Mocking](builtin-mocking.md)
+## [Using Environment Variables](envvars.md)
 
-## [Extracting Common Initialization Flow Tasks](init-flow.md)
+## [Logging Custom Fields](custom-logging.md)
 
-## [Testing Templates](test-templates.md)
+## [Forwarding a Request to an Upstream API (Flow)](forward-request-upstream.md)
 
-## [Testing API Requests](test-api-request.md)
+## [How can I pass an arbitrary header field to an upstream system?](pass-header-field-upstream.md)
 
-## [Testing with Backend Requests](test-backend.md)
+## [How can I pass response headers to the client?](pass-header-field-downstream.md)
 
-## [Using Environment Variables](envvars.md)
+## [How can I increase the request timeout to deal with a slow upstream system?](request-timeout.md)
 
-## [File Serving](file-serving.md)
+## [Sending POST requests](upstream-post-requests.md)
 
-## [Error Handling](error-flow.md)
+## [Signing JWT](jwt.md)
 
-## [Logging Custom Fields](custom-logging.md)
+## [How can I inspect the client request?](see-client-request.md)
+
+## [Auto Docs with Swagger UI](swagger-docs.md)
+
+## [Using the Built-in Mocking](builtin-mocking.md)

cookbook/custom-logging.md

@@ -17,7 +17,7 @@ We want all of that!
 
 To play with logging, you need a FLAT project. If you don't have on, yet, have a look into the [tutorial](/tutorial/README.md) to [get started](/tutorial/README.md#getting-started).
 
-## Reading logs
+## Reading Logs
 
 Before start customizing our logs, we need to setup our workplace in order to see what we are doing. Where can we inspect FLAT logs?
 
@@ -34,7 +34,7 @@ However, once you call your API with `curl` you will see JSON lines in your term
 $ curl localhost:8080/api/…
 ```
 ```json
-{"timestamp":"2019-10-15T15:49:13+00:00","type":"flat_access","requestID":"XaXqeccky00IowY@OUgG8AAAAAA","path":"/api/…","status":200,"method":"GET","agent":"curl/7.54.0","referrer":"","mime":"application/json"}
+{"timestamp":"2019-10-15T15:49:13+00:00","type":"flat_access",…}
 ```
 
 You can have the JSON colored and pretty printed by piping the output to the [`jq` command](https://stedolan.github.io/jq/):
@@ -51,17 +51,23 @@ Now, the access log will be nicely readable on your terminal:
   "timestamp": "2019-10-15T15:49:13+00:00",
   "type": "flat_access",
   "requestID": "XaXqeccky00IowY@OUgG8AAAAAA",
+  "url": "http://localhost:8080/api/…",
   "path": "/api/…",
   "status": 200,
   "method": "GET",
   "agent": "curl/7.54.0",
   "referrer": "",
-  "mime": "application/json"
+  "mime": "application/json",
+  "realtime": 0.08935,
+  "bytes": 1387,
+  "requestbytes": 0,
+  "flow": "flow.xml",
+  "requestmime": "",
+  "location": ""
 }
 ```
 
-
-## Adding a log field
+## Adding a Log Field
 
 Now that we know where our logs go, we're finally ready to add fields!
 
@@ -90,20 +96,14 @@ $ curl localhost:8080/api/…
 {
   "timestamp": "2019-10-15T15:49:13+00:00",
   "type": "flat_access",
-  "requestID": "XaXqeccky00IowY@OUgG8AAAAAA",
-  "path": "/api/…",
-  "status": 200,
-  "method": "GET",
-  "agent": "curl/7.54.0",
-  "referrer": "",
-  "mime": "application/json",
+  …
   "project": "myAPIProject"
 }
 ```
 
 Our first custom log field has hit the terminal!
 
-## Adding dynamic log fields
+## Adding Dynamic Log Fields
 
 With [JSON templates](/reference/templating/README.md) you can use expressions to dynamically set field names and values.
 
@@ -127,21 +127,15 @@ Notice, how we can provide default values for missing data. If _both_ of the var
 {
   "timestamp": "2019-10-15T15:49:13+00:00",
   "type": "flat_access",
-  "requestID": "XaXqeccky00IowY@OUgG8AAAAAA",
-  "path": "/api/…",
-  "status": 200,
-  "method": "GET",
-  "agent": "curl/7.54.0",
-  "referrer": "",
-  "mime": "application/json",
+  …
   "project": "myAPIProject",
   "stage": "unknown"
 }
 ```
 
 `stage` is always defined. But `location` is missing, because its expression has evaluated to `null`. Nulled fields don't show up in the log.
 
-## Structured log fields
+## Structured Log Fields
 
 Your custom log fields are not restricted to the top-level field-list. If you have more fields, that belong together, you can group them in an object.
 
@@ -159,19 +153,11 @@ In our case, we might want to gather information about the environment:
 </log>
 ```
 
-Notice, how we can provide default values for missing data. If _both_ of the variables are not set, a log may look like this:
-
 ```json
 {
   "timestamp": "2019-10-15T15:49:13+00:00",
   "type": "flat_access",
-  "requestID": "XaXqeccky00IowY@OUgG8AAAAAA",
-  "path": "/api/…",
-  "status": 200,
-  "method": "GET",
-  "agent": "curl/7.54.0",
-  "referrer": "",
-  "mime": "application/json",
+  …
   "project": "myAPIProject",
   "env": {
     "stage": "production",
@@ -180,9 +166,9 @@ Notice, how we can provide default values for missing data. If _both_ of the var
 }
 ```
 
-## Using request data
+## Using Request Data
 
-Client's provide a lot of useful information in the HTTP request headers. We can easily use them to augment our log:
+Clients provide a lot of useful information in the HTTP request headers. We can easily use them to augment our log:
 
 
 ```xml
@@ -209,13 +195,7 @@ $ curl -H "X-Forwarded-Proto: https" localhost:8080/api/…
 {
   "timestamp": "2019-10-15T15:49:13+00:00",
   "type": "flat_access",
-  "requestID": "XaXqeccky00IowY@OUgG8AAAAAA",
-  "path": "/api/…",
-  "status": 200,
-  "method": "GET",
-  "agent": "curl/7.54.0",
-  "referrer": "",
-  "mime": "application/json",
+  …
   "project": "myAPIProject",
   "env": {
     "stage": "production",
@@ -233,7 +213,7 @@ For logging alone, the JSON armor prevents format breakouts and log attacks. HTT
 
 ## Testing
 
-Log augmentation with the [`log`  action](/reference/actions/log.md) belongs to our project code. Therefore, we would like to test that! This can be done by using the [`get-log()` function](/reference/functions/get-log.md) in a [FLAT test](/reference/testing/README.md).
+Log augmentation with the [`log` action](/reference/actions/log.md) belongs to our project code. Therefore, we would like to test that! This can be done by using the [`get-log()` function](/reference/functions/get-log.md) in a [FLAT test](/reference/testing/README.md).
 
 Put this into `tests/loggging.xml`:
 ```xml
@@ -260,7 +240,7 @@ $ flat test tests/logging.xml
 ok 1 tests/logging.xml: 1 assertions
 ```
 
-In a real project, you would rather send a request to your FLAT API and check if the log was written as expected
+In a real project, you would rather send a request to your FLAT API and check if the log was written as expected:
 
 ```xml
 <flat-test>

cookbook/jwt.md

@@ -101,5 +101,6 @@ Note that, with `RSASSA` based algorithms, you have to specify the algorithm in
 
 ## See also
 
-* [`jwt-encode()`](/reference/functions/jwt-encode.md)
-* [`jwt-decode()`](/reference/functions/jwt-decode.md)
+* [`jwt-encode()`](/reference/functions/jwt-encode.md) (reference)
+* [`jwt-decode()`](/reference/functions/jwt-decode.md) (reference)
+* [Protecting Access using JWT Tokens](/cookbook/x-flat-jwt.md) (cookbook)