mirror of
https://github.com/fnproject/fn.git
synced 2022-10-28 21:29:17 +03:00
4421c151c5
* WIP on writing functions and the functions format. * Added more docs on writing functions. * Running on windows docs. * Linked README to writing.md * Minor fixes from PR feedback.
109 lines
3.3 KiB
Markdown
109 lines
3.3 KiB
Markdown
# Open Function Format
|
|
|
|
This document will describe the details of how a function works, inputs/outputs, etc.
|
|
|
|
## Input
|
|
|
|
### STDIN and Environment Variables
|
|
|
|
While wanting to keep things simple, flexible and expandable, we decided to go back to the basics, using Unix input and output. Standard in is easy to use in any
|
|
language and doesn't require anything extra. It also allows streaming input so we can do things like keeping a container running some time and stream
|
|
requests into the container.
|
|
|
|
Configuration values, environment information and other things will be passed in through environment variables.
|
|
|
|
### Input Formats
|
|
|
|
The goals of the input format are the following:
|
|
|
|
* Very easy to use and parse
|
|
* Streamable for increasing performance (more than one call per container execution)
|
|
* Ability to build higher level abstractions on top (ie: Lambda syntax compatible)
|
|
|
|
The format is still up for discussion and in order to move forward and remain flexible, it's likely we will just allow different input formats and the
|
|
function creator can decide what they want, on a per function basis. Default being the simplest format to use.
|
|
|
|
#### Default Input Format
|
|
|
|
The default input format is simply the request body itself plus some environment variables. For instance, if someone were to post a JSON body, the unmodified body would
|
|
be sent in via STDIN.
|
|
|
|
Pros:
|
|
|
|
* Very simple to use
|
|
|
|
Cons:
|
|
|
|
* Not streamable
|
|
|
|
#### HTTP/1 Input Format (Not implemented)
|
|
|
|
`--input-format http`
|
|
|
|
HTTP format could be a good option as it is in very common use obviously, most languages have some semi-easy way to parse it, and it's streamable. The basic format
|
|
is:
|
|
|
|
```
|
|
REQUEST LINE
|
|
HEADER
|
|
BLANK LINE
|
|
BODY
|
|
```
|
|
|
|
The header keys and values would be populated with information about the function call such as the request URL and query parameters.
|
|
|
|
Body length is determined by the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.3) header, which is mandatory.
|
|
|
|
Pros:
|
|
|
|
* Streamable
|
|
* Common format
|
|
|
|
Cons:
|
|
|
|
* Requires a parsing library or fair amount of code to parse headers properly
|
|
* Double parsing - headers + body (if body is to be parsed, such as json)
|
|
|
|
#### JSON/HTTP Input Format (Not implemented)
|
|
|
|
`--input-format json-http`
|
|
|
|
The idea here is to keep the HTTP base structure, but make it a bit easier to parse by making the `request line` and `headers` a JSON struct.
|
|
Eg:
|
|
|
|
```
|
|
{
|
|
"request_url":"http://....",
|
|
"params": {
|
|
"blog_name": "yeezy"
|
|
}
|
|
}
|
|
BLANK LINE
|
|
BODY
|
|
```
|
|
|
|
Pros:
|
|
|
|
* Streamable
|
|
* Easy to parse headers
|
|
|
|
Cons:
|
|
|
|
* New, unknown format
|
|
|
|
## Output
|
|
|
|
### STDOUT
|
|
|
|
For synchronous: True to form, whatever is written to standard out is returned as the response. If you want to return some JSON output, just write it directly to STDOUT.
|
|
|
|
TODO: How to change response headers? Perhaps a similar style as input? Headers, then body. Default headers can be defined on the route and overridden on output.
|
|
|
|
For asynchronous: STDOUT will be written to /dev/null until [further notice](https://github.com/iron-io/functions/issues/173). We do not want to write this
|
|
to the logs now, then change it later, otherwise people will start to depend on it.
|
|
|
|
### STDERR
|
|
|
|
Standard error is reserved for logging, like it was meant to be. Anything you output to STDERR will show up in the logs. And if you use a log
|
|
collector like logspout, you can collect those logs in a central location. See [logging](logging.md).
|