Initial docs commit

Documentation/Architecture.md

@@ -0,0 +1,107 @@
+
+A high level view of the internals of Fission.
+
+Components
+==========
+
+Language-neutral components:
+
+ * Controller
+ * Container Pool Manager
+ * Container Specializer
+ * Router
+
+Language-specific components:
+
+ * Language Build Container
+ * Language Run Container
+
+
+Controller
+----------
+
+Function and Trigger CRUD APIs.  APIs to watch for changes are also
+included (useful for other components that cache state).
+
+See api/swagger.json for API details.
+
+This is the only stateful component.  It needs to be configured with a
+URL to an etcd cluster and a path to a persistent volume.  The volume
+will be used to store the functions' source code.
+
+Etcd is used as the DB.
+
+
+Container Pool Manager 
+----------------------
+
+Manage pool of generic containers.
+
+Probably use K8s RCs.  Can we Use labels to move pods from one rc to
+another?  What about jobs?
+
+Container Specializer
+---------------------
+
+Inputs: a running generic language run container, a user function,
+optionally an http trigger URL.
+
+Calls Language Run Container and sets up Router to point to it.
+
+
+Router
+------
+
+- Cache trigger -> container instance mapping; implement cache miss and expiration.
+
+- Invoke Specializer, setup up k8s API 
+
+- Forward requests
+
+The Router is stateless -- it can be scaled or killed at any time.
+
+There's a lot of functionality overlap with K8S Ingress Controllers.
+We should clearly use Ingress and Ingress Controllers in some way.
+It's not exactly clear at the moment how -- should make a whole new
+Ingress Controller perhaps based on the contrib/nginx
+
+
+Autoscaler
+----------
+
+This autoscales the language run containers that are backing a
+trigger.
+
+What metrics this is based on is TBD.
+
+- Number of requests/sec
+- "Backlog" -- number of outstanding requests not yet started -- how to measure this?
+- Change in turn-around time?
+
+
+Language Build Container
+------------------------
+
+* The Language Build Container is a container that is invoked for a
+  build.  It takes one user-created function and outputs something
+  that can be run by the corresponding Language Run Container.
+
+* The Build Container must implement the Language Build Container
+  interface.
+
+
+Language Run Container
+----------------------
+
+* The Language Run Container is the container in which user functions
+  run.
+
+* The Run Container is started without the user function.  It must
+  start as a "Generic Container".  It must implement the
+  "specialization interface".  In short, it must implement an HTTP
+  server that can receive a piece of code, verify its signature, and
+  map it to an HTTP endpoint.  See
+  Documentation/specs/LanguageRunContainerSpec.md for details.
+
+
+

Documentation/ProgrammingModel.md

@@ -0,0 +1,71 @@
+Programming Model
+=================
+
+This document describes the programming model for fission functions.  
+
+See TERMINOLOGY for definitions of terms, such as _function_,
+_instance_, and _trigger_.
+
+
+Idempotency
+===========
+
+Fission assumes that functions are idempotent.  Functions whose instances
+die without a result are restarted, upto a certain restart limit.
+
+
+Time Limits
+===========
+
+By default, there is no time limit on fission functions.  
+
+Idle running instances may be killed at any time (usually after the
+default idle timeout of 10 minutes, but this is configurable).
+
+
+Mapping
+=======
+
+This section specifies the mapping between: (1) HTTP and other
+triggers, and (2) function parameters, return values, and exceptions.
+
+In other words, this section describes how a function should be called
+based on a given trigger, and how the functions behaviour affects the
+result returned from the trigger.
+
+The HTTP Trigger
+----------------
+
+NodeJS
+------
+
+NodeJS functions are called with a context object.
+
+context.request contains the nodeJS Request object.
+
+In addition,
+
+context.queryString contains the parsed querystring
+
+context.body contains the parsed body
+
+context.status sets the HTTP response status code.  If context.status
+is an invalid HTTP status, then the HTTP status is set to 500.
+
+Exceptions result in a HTTP 500 error.
+
+
+
+
+
+XXX Should we have a "context.done()"?  What are the pros and cons?
+
+XXX Who handles serialization and deserialization?  Should we do json
+    automatically based on content-type and accept headers?
+
+
+Python
+------
+
+Same as node, pretty much.
+

Documentation/TERMINOLOGY

@@ -0,0 +1,22 @@
+
+_Function_: A _function_ is the smallest unit of a program in Fission.
+It's a program with an function as an entry point -- it doesn't have
+to be just one function.
+
+_Trigger_: Triggers are what cause functions to be called.  For
+example the HTTP trigger causes functions to be called on HTTP
+requests.
+
+_Instance_: Fission creates and runs servers containing these
+functions.  The running server is called an _instance_.  You normally
+don't need to worry about instances: their management is completely
+automatic and transparent to you.  However, certain configuration
+settings allow you to tweak the behaviour of instances -- for example,
+you can configure the strategy for destroying unused instances.
+
+_Generic Instance_: An instance with no user code in it.  The process
+of including the user code to a Generic Instance is _Specialization_,
+and the resulting instance is a _Specialized Instance_.
+
+_Specialized Instance_: See _General Instance_.
+

Documentation/UserManual.md

@@ -0,0 +1,15 @@
+
+Fission is functions-as-a-service for Kubernetes.
+
+You write some functions, and setup some way for them to be invoked
+("triggers").  Triggers can be HTTP requests (HTTP Triggers) or timers
+(Time Triggers).
+
+Topics
+======
+
+Testing
+-------
+
+Function Updates
+----------------