storage is a wrapper that turns IStorageDriver into IStorage. It will
have some logic around almost all IStorageDriver methods. So don't
automatically inherit driver methods not to miss some.

It is already not only open code there, and we are going to add more
storage wrapping functionality into storage (IStorage wrapper over
IStorageDriver). Storage.go thus seems to be a better name.

This continues 4d2c8b1d (go/zodb: Require drivers to provide
notifications for database change events) and a6580062 (go/zodb: Require
drivers to provide at₀ on open) and reworks watchq to receive not only
commit events, but also errors from watcher in storage driver.

Similarly to zodb (632c9798 "go/zodb: storageURL -> zurl")

This are equivalents of PersistentMapping and PersistentList in ZODB/py.
PersistentMapping is usually used as root ZODB object in Zope/ERP5/...

At least we should be able to load and save them now.
Tests pending...

zurl is more handy and is also used in zodbtools which have help on it
(`zodb help zurl`).

BTrees.Length.Length is used in many places in ERP5. At least we should
be able to load and save it now.

Tests pending.

This functions invoke visit callback on every BTree node they traverse.

Wendelin.core needs this to retrieve serials of not only looked up ZBlk
object, but also of every BTree nodes on the path to it.

go/zodb/btree: Bucket.Get: Don't get ctx argument and just require that the bucket must be already activated

It was scheduled to be so as described in removed TODO.

It is either BTree or Bucket.

This will allow persistency layer to do kind of copy-on-write, if e.g.
there are many connections that are sharing object's state.

Continuing previous patch also teach ZEO to decode identifies from
on-wire as both [8]str or [8]byte.

Tests pending.

Since ZODB 5.4 OID is encoded as bytes, not str:

	https://github.com/zopefoundation/ZODB/commit/12ee41c473

Try to support both str and bytes on decoding, as we need to support all
ZODB versions.

Add a way for tests to serialize and commit IPersistent objects. The
commit, for now, is implemented via calling external zodbtools/py to
commit raw data (see 7f14e2cb "go/zodb/fs1: tests: Factor-out commiting
a transaction via ZODB/py into common place). The data to commit is what
object serialization (see previous patch) gives.

For now there is no tracking of dirtiness. A test must explicitly list
objects it wants to save into database.

This functionality will soon be used to implement Persistent/DB/...
tests.

This will be used in the future to commit object changes back into
database. No test, since this functionality will be used at first to
implement tests themselves (see next patch). Hopefully after
bootstrapping we'll have full tests.

- require (Py)GetState and make it clear that it is called by
  persistency machinery only on non-ghost objects.
- make it clear that (Py)SetState is called by persistency machinery
  only on ghost objects.
- make it clear that DropState is called by persistency machinery only
  on non-ghost objects.

For btree PyGetState is marked as TODO which we'll fill incrementally
(the code is draftly ready, but there is no test for now).

We will soon need to be able to commit in tests for ZODB itself.

and to deliver to watchq only and all events in (at₀, +∞] range.

This continues 4d2c8b1d (go/zodb: Require drivers to provide
notifications for database change events) and makes initialization
semantics to process invalidations easier for both application-level ZODB
layer, and for low-level users that work with drivers directly:

- there is no possibility that an event will come from watchq with tid <
  current user head.

- there is no possibility that watcher will start delivering events
  after at₀, but not immediately after it, i.e. users can rely that they
  won't loose an event.

This correctness invariants should be easy to provide in drivers.

pool is a better name for "pool of unused connections" compared to connv.

Connection has .db and db has .stor - there is no need to keep separate
.stor on the Connection. This thinko was there from Connection beginning
(533f0c73 "go/zodb: DB - application-level handle to database (very draft)")

There was a thinko in transaction.Abort - it was spawning synchronizers
under a waitgroup, but wg.Wait() call was forgotten. This way, e.g. in
ZODB if a transaction was aborted, corresponding connection could be not
yet returned back into DB pool.

Fix it.

Test is TODO for the time when, hopefully, tracetest is generally ready.

In ZODB transaction ID is connected with time. We already have
functionality to convert tid to time (see bac6c953 "go/zodb: Tid
connection with time"), but the functionality for converting in another
way - time -> tid - was missing.

Fix it.

It is useful in situations where one need to print potentially Broken
objects properly, because %T does not print that detail and using %#v
creates too much noise.

This allows for applications to tune eviction strategy for their needs.
The interface to do so (LiveCacheControl) was defined previously in
c67ff9ea (go/zodb: Connection: Allow applications to tune live-cache
eviction policy), but so far there was no way to install cache
controller. Fix it.

Wendelin.core (wcfs) needs to check whether an object is currently
cached or not.

Following-up on 4d2c8b1d (go/zodb: Require drivers to provide
notifications for database change events) let's teach FileStorage to
support watching for database changes:

- add watcher who observes changes to data file via fsnotify.

- when we see that the file was updated - there is a tricky case to distinguish
  in-progress writes from just some garbage added at tail. See comments in
  _watcher for details.

- if the watcher sees there is indeed new transactions, the watcher
  updates index & txnh{Min,Max} and sends corresponding event to watchq.

- since index / txnh{Min,Max} can now be changed (by watcher) -> they
  are now protected by mu.

- consequently operations like LastTid, LastOid, Load, ... are all taught to
  observe index / txnh{Min,Max} state in read-snapshot way.

- add down & friends to indicate that the storage is no longer
  operational, if watcher sees there is a problem with data file.

- Open is reworked to start from loading/rebuilding index first, and then tail
  to watcher to detect whether what's after found topPos is garbage or another
  in-progress transaction. Consequently it is now possible to correctly open
  filestorage that is being currently written to and has in-progress transaction
  at tail.

The patch is a bit big, but the changes here are all tightly
interrelated.

It is already 3 places where we return zodb.OpError and it will be more.
Make a helper function to create those errors with higher signal/noise.

A ZODB database can be changed by local client as well as another
process. A notification channel is thus needed for local cache and
database view to know they have to update to current database state.

This patch builds the interface of how such notifications should be
provided by drivers. Contrary to ZODB/py it is required that every
driver provide it.

However we will be providing driver support incrementally and for now
all drivers behave as if the database is not changing.

A note on why Watchq is passed to driver as options: low-level ZODB
users, who might want to work with drivers directly, might not need it,
and this way with Watchq not present in driver options they will continue to
observe the same driver behaviour as before watchq was introduced. In
practice many low-level utilities don't need notification support, and
it would be not good to required them all to update open calls and to
provide watchq drainer not to get stuck.

TODO Watchq should be extended to also receive errors from watcher, so
that clients could be notified when there is something wrong with the
database.

OpenOptions is high-level options clients give to ZODB when they want to
open a high-level IStorage, and not all of those options apply to drivers
- for example NoCache is meaningless since cache is provided by ZODB
infrastructure, not a driver.

On the other hand we are going to introduce driver-specific options,
that either low-lever users, or ZODB infrastructure itself will use when
opening drivers.

For this reasons decouple driver-specific options from OpenOptions into
DriverOptions.

IStorage is what we give to users. IStorageDriver is what is internally
provided by drivers to common ZODB infrastructure that in turn
implements easy-to-use IStorage interface for clients.

So far those two were close to each other. However we need to decouple
them, or else every driver will have to implement the same high-level
functionality that users expect from IStorage. What we want to do is to
offload drivers from that work.

In the next patches IStorageDriver will evolve with driver
specific-bits, while IStorage will evolve with higher-level stuff
that clients will use.

We will soon need to check for Python and other modules in more tests.
Now the checking function is generic - see xtesting.NeedPy docs.

Connection options could be prepared/logged not only in DB.Open, so
instead of teaching only DB.Open how to print them, teach ConnOptions to
represent itself in human-readable form.

This syncs to nexedi/zodbtools@f7eff5fe
(*: Refer to `zodb help tidrange` about how history range should be
specified) in zodbtools/py.

Done for consistency with 313d2d78 (go/zodb/btree: Expose access to
BTree/Bucket entries as public API).

Provide functionality to query for key-range limit for all children
under a tree node.

- Refer to zodb interfaces as zodb.<name>;
- in tests bmapping is about LOBTree, not BTree. This fixes up c1ba9a90
  (go/zodb/btree: Turn it into template).

Moved here:

	nexedi/zodbtools@e973d519

- Put dot after the subject,
- Indent lists,
- ...