Controller architecture

sdk/go/arvados (Apache2) provides http endpoints (method/path), request/response structs (Collection, CreateOptions, UpdateOptions).

lib/controller/federation provides an Interface with a method for each Arvados API action, e.g., CollectionList(context.Context, ListOptions) (CollectionListResponse, error).

lib/controller/federation provides Conn, which implements federation.Interface by fanning out to multiple backends (typically one local and several remotes, to suit cluster config). Federation-unaware APIs just call through to the default (local) backend.

lib/controller/rpc provides Conn, implements federation.Interface by calling an Arvados controller's http server.

lib/controller/railsproxy implements federation.Interface using an rpc.Conn whose target is the local RailsAPI server.

lib/controller/router provides an http.Handler that maps each HTTP request to a backend (federation.Interface) method: deserialize the request to a Provider call signature, check auth scope, call the backend method, and serialize the return values as an HTTP response.

lib/controller provides an http service consisting of a router with a federation.Conn backend.

Diagram: https://docs.google.com/drawings/d/1Qsj7Re4kE1tNMy7RaNR_dc9U5t6vswMJOhCI2YlbsCM/edit?usp=sharing

The rpc, federation, and (future) localdb packages offer backends with a common interface, so any given program can switch easily between using the federation and model logic built into its own binary and calling out to a different process or host.