Signed-off-by: Travis Ralston <travpc@gmail.com>

... to stop us doing the cache cleanup jobs on the master.

Fixes https://github.com/matrix-org/synapse/issues/2554

Both of these functions ae known to leak logcontexts. Replace the remaining
calls to them and kill them off.

We're going to need to use this from places that aren't password auth, so let's
move it to a proper class.

Provide a hook by which auth providers can be notified of logouts.

... so that they have a way to record access tokens.

Provide a hook where password auth providers can say they know about other
login types, and get passed the relevant parameters

Provide an interface by which password auth providers can register db schema
files to be run at startup

Document the existing interface, before I start adding new stuff.

make it absolutely clear that Purge History API does not remove all traces of events and message contents

because this topic pops up too often

#890 #1621 #1730 #2260 #2315 and so on

I haven't (yet) documented all of the user-list APIs introduced in
https://github.com/matrix-org/synapse/pull/1784 because the API shape seems
very odd, given the functionality.

The cache wrappers had a habit of leaking the logcontext into the reactor while
the lookup function was running, and then not restoring it correctly when the
lookup function had completed. It's all the fault of
`preserve_context_over_{fn,deferred}` which are basically a bit broken.

This defines the low level TCP replication protocol

Apparently the github RST renderer doesn't like Note blocks.