# Environment V2 Fission-Environment API

Fission Environments are the language-specific component of fission.

They must satisfy the interface in this spec.

## Meta

This is version 2.0-alpha of the Fission-Environment API.

(It's unstable and may change without warning until 2.0-beta.)

## Overview

Fission V2 Environments consist of:

 * Metadata
 * A runtime image
 * A builder image (optional)
 * Function Interface Specification
 * User Documentation
 * Examples

### Metadata 

See EnvironmentSpec, Runtime, and Builder in types.go.

## Runtime Image

An environment runtime image is a docker container image. It must run
a server that has two jobs:

(a) Loading a "function" from a file path on demand
(b) Invoking that function on request

### Function Loading

The environment must expose a single HTTP endpoint (at the port and
URL specified in the metadata) that loads a function. The function
load request is a JSON-serialized `FunctionLoadRequest`.

The function load request contains a filepath to load the function
from. Fission does not define in any way the contents of the path; it
is completely environment-dependent. It may be a single file, or a
directory (in case of deployment packages).

The load request may contain an EntryPoint. If it does, the loader
must interpret this; usually it's the name of a function in a module
or package containing multiple functions. If there is no entrypoint,
the environment must use a default; again, the value of thsi default
is environment-specific.

The load request may contain a URL. If it does, requests to that URL
should be routed to the function. It defaults to "/".

### Function Invocation

Functions are invoked on HTTP request to the server. The port for the
request on the runtime container is defined in the Runtime metadata,
and the URL for the request is specified in the FunctionLoadRequest.

The interface of the function is environment specific; the environment
must come with a spec for this interface.

## Builder

The builder is a container image that contains tools to build a
function from source. The source may be a single file or a directory
of files.

The builder container is invoked with the specified command, with the
following params:

 1. File path of the source
 2. File path where the output should go
 3. Other env or function-specific params passed by the user

The first two parameters are file paths, and all remaining params are
environment-specific.

The output of the builder should be something that the runtime can
load and run -- there should be no intermediate steps that need user
intervention.

### Errors

## Function Interface Spec

The function interface spec is a document that specifies the interface
of functions and their semantics.  It must specify:

 * How functions are invoked (sync, async)
 * How the request context is provided to the function (URL, headers, request type, request body)
 * Function logging
 * Semantics of function errors and exceptions


## Documentation

The docs should contain everything necessary to use the environment:

 * How to add it to a fission cluster
 * How to write and build functions for this environment (link to the interface spec)
 * How to modify and rebuild the environment itself

## Examples

Suggested examples to provide:

 * A simple "Hello world"
 * A function that demonstrates use of the request context: url params,
   request headers, request body 
 * A function that does logging
 * A multi-file function package
 * A function with dependencies
 * Functions with shared code

## Compatibility with v1

V1 environment images can be used as v2 environment runtime images.