diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index b50851f7..0ec56927 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -12,7 +12,7 @@ jobs: build: strategy: matrix: - go-version: [ 1.17.x ] + go-version: [ 1.18.x ] os: [ ubuntu-latest ] runs-on: ${{ matrix.os }} steps: diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml index ca0a9e7a..3d52a9df 100644 --- a/.github/workflows/publish.yaml +++ b/.github/workflows/publish.yaml @@ -9,7 +9,7 @@ jobs: publish: strategy: matrix: - go-version: [ 1.17.x ] + go-version: [ 1.18.x ] os: [ ubuntu-latest ] runs-on: ${{ matrix.os }} permissions: diff --git a/README.md b/README.md index 2a38207a..dac33466 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,13 @@ Reverse proxy for HTTP microservices and STDIO [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![OpenFaaS](https://img.shields.io/badge/openfaas-serverless-blue.svg)](https://www.openfaas.com) -The `of-watchdog` implements a HTTP server listening on port 8080, and acts as a reverse proxy for running functions and microservices. It can be used independently, or as the entrypoint for a container with OpenFaaS. - -This version of the OpenFaaS watchdog adds support for HTTP proxying as well as STDIO, which enables re-use of memory and very fast serving of requests. It does not aim to replace the [Classic Watchdog](https://github.com/openfaas/faas/tree/master/watchdog), but offers another option for those who need these features. +The `of-watchdog` implements an HTTP server listening on port 8080, and acts as a reverse proxy for running functions +and microservices. It can be used independently, or as the entrypoint for a container with OpenFaaS. +This version of the OpenFaaS watchdog adds support for HTTP proxying as well as STDIO, which enables re-use of memory +and very fast serving of requests. It does not aim to replace +the [Classic Watchdog](https://github.com/openfaas/classic-watchdog), but offers another option for those who +need these features. ### Goals: @@ -19,11 +22,13 @@ This version of the OpenFaaS watchdog adds support for HTTP proxying as well as ## Modes -There are several modes available for the of-watchdog which changes how it interacts with your microservice or function code. +There are several modes available for the of-watchdog which changes how it interacts with your microservice or function +code. ![](https://docs.openfaas.com/architecture/watchdog-modes.png) -> A comparison of three watchdog modes. Top left - Classic Watchdog, top right: afterburn (deprecated), bottom left HTTP mode from of-watchdog. +> A comparison of three watchdog modes. Top left - Classic Watchdog, top right: afterburn (deprecated), bottom left HTTP +> mode from of-watchdog. ### 1. HTTP (mode=http) @@ -33,20 +38,21 @@ The HTTP mode is stable. See example templates: -| Template | HTTP framework | Repo | -|------------------------|---------------------|--------------------------------------------------------------------| -| Node.js 12 (LTS) | Express.js | https://github.com/openfaas/templates/ | -| Python 3 & 2.7 | Flask | https://github.com/openfaas-incubator/python-flask-template | -| Golang | Go HTTP (stdlib) | https://github.com/openfaas-incubator/golang-http-template | -| Golang | (http.HandlerFunc) | https://github.com/openfaas-incubator/golang-http-template | -| Ruby | Sinatra | https://github.com/openfaas-incubator/ruby-http | -| Java 11 | Sun HTTP / Gradle | https://github.com/openfaas/templates/ | +| Template | HTTP framework | Repo | +|------------------|--------------------|-------------------------------------------------------------| +| Node.js 12 (LTS) | Express.js | https://github.com/openfaas/templates/ | +| Python 3 & 2.7 | Flask | https://github.com/openfaas-incubator/python-flask-template | +| Golang | Go HTTP (stdlib) | https://github.com/openfaas-incubator/golang-http-template | +| Golang | (http.HandlerFunc) | https://github.com/openfaas-incubator/golang-http-template | +| Ruby | Sinatra | https://github.com/openfaas-incubator/ruby-http | +| Java 11 | Sun HTTP / Gradle | https://github.com/openfaas/templates/ | Unofficial: [.NET Core / C# and Kestrel](https://github.com/burtonr/csharp-kestrel-template) #### 1.2 Description -A process is forked when the watchdog starts, we then forward any request incoming to the watchdog to a HTTP port within the container. +A process is forked when the watchdog starts, we then forward any request incoming to the watchdog to a HTTP port within +the container. Pros: @@ -56,9 +62,11 @@ Pros: * Database connections can be persisted for the lifetime of the container -* Files or models can be fetched and stored in `/tmp/` as a one-off initialization task and used for all requests after that +* Files or models can be fetched and stored in `/tmp/` as a one-off initialization task and used for all requests after + that -* Does not require new/custom client libraries like afterburn but makes use of a long-running daemon such as Express.js for Node or Flask for Python +* Does not require new/custom client libraries like afterburn but makes use of a long-running daemon such as Express.js + for Node or Flask for Python Example usage for testing: @@ -96,9 +104,11 @@ Forks one process per request. Multi-threaded. Ideal for retro-fitting a CGI app Limited to processing files sized as per available memory. -Reads entire request into memory from the HTTP request. At this point we serialize or modify if required. That is then written into the stdin pipe. +Reads entire request into memory from the HTTP request. At this point we serialize or modify if required. That is then +written into the stdin pipe. -* Stdout pipe is read into memory and then serialized or modified if necessary before being written back to the HTTP response. +* Stdout pipe is read into memory and then serialized or modified if necessary before being written back to the HTTP + response. * A static Content-type can be set ahead of time. @@ -108,9 +118,12 @@ Reads entire request into memory from the HTTP request. At this point we seriali ### 3. Streaming fork (mode=streaming) - default. -Forks a process per request and can deal with a request body larger than memory capacity - i.e. 512mb VM can process multiple GB of video. +Forks a process per request and can deal with a request body larger than memory capacity - i.e. 512mb VM can process +multiple GB of video. -HTTP headers cannot be sent after function starts executing due to input/output being hooked-up directly to response for streaming efficiencies. Response code is always 200 unless there is an issue forking the process. An error mid-flight will have to be picked up on the client. Multi-threaded. +HTTP headers cannot be sent after function starts executing due to input/output being hooked-up directly to response for +streaming efficiencies. Response code is always 200 unless there is an issue forking the process. An error mid-flight +will have to be picked up on the client. Multi-threaded. * Input is sent back to client as soon as it's printed to stdout by the executing process. @@ -126,37 +139,38 @@ See an example in the [Hugo blog post](https://www.openfaas.com/blog/serverless- ## Metrics -| Name | Description | Type | -|---------------------------------|-------------------------|------------------------| -| http_requests_total | Total number of requests | Counter | -| http_request_duration_seconds | Duration of requests | Histogram | -| http_requests_in_flight | Number of requests in-flight | Gauge | +| Name | Description | Type | +|-------------------------------|------------------------------|-----------| +| http_requests_total | Total number of requests | Counter | +| http_request_duration_seconds | Duration of requests | Histogram | +| http_requests_in_flight | Number of requests in-flight | Gauge | ## Configuration Environmental variables: -> Note: timeouts should be specified as Golang durations i.e. `1m` or `20s`. - -| Option | Implemented | Usage | -|-----------------------------|--------------|-------------------------------| -| `function_process` | Yes | Process to execute a server in `http` mode or to be executed for each request in the other modes. For non `http` mode the process must accept input via STDIN and print output via STDOUT. Also known as "function process". Alias: `fprocess` | -| `static_path` | Yes | Absolute or relative path to the directory that will be served if `mode="static"` | -| `read_timeout` | Yes | HTTP timeout for reading the payload from the client caller (in seconds) | -| `write_timeout` | Yes | HTTP timeout for writing a response body from your function (in seconds) | -| `healthcheck_interval` | Yes | Interval (in seconds) for HTTP healthcheck by container orchestrator i.e. kubelet. Used for graceful shutdowns. | -| `exec_timeout` | Yes | Exec timeout for process exec'd for each incoming request (in seconds). Disabled if set to 0. | -| `port` | Yes | Specify an alternative TCP port for testing. Default: `8080` | -| `write_debug` | No | Write all output, error messages, and additional information to the logs. Default is `false`. | -| `content_type` | Yes | Force a specific Content-Type response for all responses - only in forking/serializing modes. | -| `suppress_lock` | Yes | When set to `false` the watchdog will attempt to write a lockfile to /tmp/ for healthchecks. Default `false` | -| `http_upstream_url` | Yes | `http` mode only - where to forward requests i.e. `127.0.0.1:5000` | -| `upstream_url` | Yes | alias for `http_upstream_url` | -| `http_buffer_req_body` | Yes | `http` mode only - buffers request body in memory before forwarding upstream to your template's `upstream_url`. Use if your upstream HTTP server does not accept `Transfer-Encoding: chunked`, for example WSGI tends to require this setting. Default: `false` | -| `buffer_http` | Yes | deprecated alias for `http_buffer_req_body`, will be removed in future version | -| `max_inflight` | Yes | Limit the maximum number of requests in flight | -| `mode` | Yes | The mode which of-watchdog operates in, Default `streaming` [see doc](#3-streaming-fork-modestreaming---default). Options are [http](#1-http-modehttp), [serialising fork](#2-serializing-fork-modeserializing), [streaming fork](#3-streaming-fork-modestreaming---default), [static](#4-static-modestatic) | -| `prefix_logs` | Yes | When set to `true` the watchdog will add a prefix of "Date Time" + "stderr/stdout" to every line read from the function process. Default `true` | -| `log_buffer_size` | The amount of bytes to read from stderr/stdout for log lines. When exceeded, the user will see an "bufio.Scanner: token too long" error. The default value is `bufio.MaxScanTokenSize` | - -> Note: the .lock file is implemented for health-checking, but cannot be disabled yet. You must create this file in /tmp/. +> Note: timeouts should be specified as Golang durations i.e. `1m` or `20s`. + +| Option | Implemented | Usage | +|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `function_process` | Yes | Process to execute a server in `http` mode or to be executed for each request in the other modes. For non `http` mode the process must accept input via STDIN and print output via STDOUT. Also known as "function process". Alias: `fprocess` | +| `static_path` | Yes | Absolute or relative path to the directory that will be served if `mode="static"` | +| `read_timeout` | Yes | HTTP timeout for reading the payload from the client caller (in seconds) | +| `write_timeout` | Yes | HTTP timeout for writing a response body from your function (in seconds) | +| `healthcheck_interval` | Yes | Interval (in seconds) for HTTP healthcheck by container orchestrator i.e. kubelet. Used for graceful shutdowns. | +| `exec_timeout` | Yes | Exec timeout for process exec'd for each incoming request (in seconds). Disabled if set to 0. | +| `port` | Yes | Specify an alternative TCP port for testing. Default: `8080` | +| `write_debug` | No | Write all output, error messages, and additional information to the logs. Default is `false`. | +| `content_type` | Yes | Force a specific Content-Type response for all responses - only in forking/serializing modes. | +| `suppress_lock` | Yes | When set to `false` the watchdog will attempt to write a lockfile to /tmp/ for healthchecks. Default `false` | +| `http_upstream_url` | Yes | `http` mode only - where to forward requests i.e. `127.0.0.1:5000` | +| `upstream_url` | Yes | alias for `http_upstream_url` | +| `http_buffer_req_body` | Yes | `http` mode only - buffers request body in memory before forwarding upstream to your template's `upstream_url`. Use if your upstream HTTP server does not accept `Transfer-Encoding: chunked`, for example WSGI tends to require this setting. Default: `false` | +| `buffer_http` | Yes | deprecated alias for `http_buffer_req_body`, will be removed in future version | +| `max_inflight` | Yes | Limit the maximum number of requests in flight | +| `mode` | Yes | The mode which of-watchdog operates in, Default `streaming` [see doc](#3-streaming-fork-modestreaming---default). Options are [http](#1-http-modehttp), [serialising fork](#2-serializing-fork-modeserializing), [streaming fork](#3-streaming-fork-modestreaming---default), [static](#4-static-modestatic) | +| `prefix_logs` | Yes | When set to `true` the watchdog will add a prefix of "Date Time" + "stderr/stdout" to every line read from the function process. Default `true` | +| `log_buffer_size` | The amount of bytes to read from stderr/stdout for log lines. When exceeded, the user will see an "bufio.Scanner: token too long" error. The default value is `bufio.MaxScanTokenSize` | + +> Note: the .lock file is implemented for health-checking, but cannot be disabled yet. You must create this file in +> /tmp/. diff --git a/go.mod b/go.mod index f1e1d9a9..85c7f8b8 100644 --- a/go.mod +++ b/go.mod @@ -1,6 +1,6 @@ module github.com/openfaas/of-watchdog -go 1.17 +go 1.18 require ( github.com/openfaas/faas-middleware v1.0.0