Logging in to the API Server
============================

This document is being written because every time I need to look at how
logging in to the API server works, I have to step through all the code and
remind myself. Once I have done that, everything seems obvious and not worth
writing down... until next time I need to think about the login process.

Intended work is to add the ability to have a user log in to the root of the
API server in order to get access to the model manager and user manager
facades. This allows the user to change their password, create models
and list the models that they are able to connect to.

The intended way that this is going to work is that the API client code will
attempt to login to the server using a versioned login command. There is
already a login-v1 that introduced new return values and a reauth request
field. We will build on that behaviour to add a login-v2. If and only if the
version 2 login is used the facades that are available at the apiserver will
be restricted.  Logging in using version 1 or the original will continue to
act as if you are logging into the controller model - the original one
and only model that would exist before the Juju Model Server work.

This work then needs to look at the API connection workflow from both ends,
the API client side, and the server side.

apiserver.Server
----------------

apiserver.go

Server struct has a map of adminApiFactories. This currently has keys of
0 and 1.  We will need to add a 2 here.

The Server instance is created with NewServer, and listens on the API port.

The incoming socket connection is handled inside the (*Server).run method.
 - "/model/:modeluuid/api" -> srv.apiHandler
 - "/" -> srv.apiHandler

The apiHandler creates a go routine for handling the socket connection, and
extracts the modelUUID from the path, and calls the (*Server).serveConn method.

serveConn validates the model UUID and gets an appropiate *state.State
for the model specified.  An empty model UUID is treated as the
controller model here.  One thing that will need to change is passing
through whether or not we were given an model UUID, as this is the last
place that cares, but we will need to know later when the appropriate login
method is called. The various admin API instances are created here and passed
through to the newAnonRoot object.  This is passed in as the method finder for
the websocket connection.

root.go

newAnonRoot only responds to calls on the "Admin" rootName.  The version of
the FindMethod is used to determine whether the version 0 or 1 login API is
used.

The Login methods on the adminV0 and adminV1 instances call into the doLogin
method.  It is here where we want to wrap the authedApi with something that
limits the rootName objects that can be called.  In order to do this, we need
to pass the modelUUID from the path (remember this is either a valid uuid or the
empty string), and the version of the login command used.

In order to get the modelUUID from the path into the Login method, we need to
capture it in *Server.serveConn, where it is passed in as an argument.  We
should pass it through to the newApiHandler function and store it on the
apiHandler struct.  This handler is passed through as an arg to the
newAnonRoot, and to the factory methods for the admin APIs.


Implementation Notes:

The login process for both v0 and v1 logins are handled in the method
*admin.doLogin (in admin.go).  The method *Conn.ServeFinder on the *rpc.Conn
attribute of the apiHandler is initially given the anonymous root here:

```go
func (srv *Server) serveConn(wsConn *websocket.Conn, reqNotifier *requestNotifier, modelUUID string) error {
	// ...
		conn.ServeFinder(newAnonRoot(h, adminApis), serverError)
	// ...
```

If login is successful, the doLogin method changes out the method finder that
is used for the RPC connection just before the end of the return statement at
the end of the method.

```go
	// a *admin
	//
	// root is `*apiHander` from the admin struct.
	a.root.rpcConn.ServeFinder(authedApi, serverError)
```

In order to supply a restricted api at the root, the doLogin method will need
to take a version number.  Just before we replace the method finder for the
RPC connection, we check the version number and the modelUUID of the api
handler, and wrap the authedApi in a restricted root method finder implemented
in a similar manner to the upgradingRoot method finder.

