For testing and benchmarking how NEO/py & NEO/go interact with each
other we need corresponding test driver. Neotest will be that driver and
present patch begins it:

- neotest can deploy NEO/{go,py} checkout either locally or on remote node;
- it can run NEO/{go,py} unit tests either locally or on remote node;
- it can also show information about a system - either local or remote.

Examples in action. Banner:

    x/src/lab.nexedi.com/kirr/neo/go/neo/t$ ./neotest
    Neotest is a tool to test and benchmark NEO.

    Usage:

            neotest command [arguments]

    The commands are:

            test            run all tests on a remote host
            test-local      run all tests locally

            test-go         run NEO/go unit tests   (part of test-local)
            test-py         run NEO/py unit tests   (part of test-local)

            deploy          deploy NEO & needed software for tests to remote host
            deploy-local    deploy NEO & needed software for tests locally

            info            print information about a node
            info-local      print information about local deployment

Deploy to another node:

    x/src/lab.nexedi.com/kirr/neo/go/neo/t$ ./neotest deploy neotest@rio.kirr.nexedi.com:3
    *** deploying to neotest@rio.kirr.nexedi.com:3 ...
    ...
    # deployed ok

Print information about that node:

    x/lab.nexedi.com/kirr/neo/go/neo/t$ ./neotest info neotest@rio.kirr.nexedi.com:3
    date:   Sun, 08 Jul 2018 21:30:43 +0300
    xnode:  neotest@rio.kirr.nexedi.com (2401:5180:0:2a::1 192.168.0.8)
    uname:  Linux rio 4.16.0-2-amd64 #1 SMP Debian 4.16.16-2 (2018-06-22) x86_64 GNU/Linux
    sw/python:          Python 2.7.15
    sw/go:              go version go1.10.3 linux/amd64
    sw/sqlite:          sqlite 3.24.0 (py mod 2.6.0)
    sw/mysqld:          mysqld  Ver 10.1.29-MariaDB-6+b1 for debian-linux-gnu on x86_64 (Debian buildd-unstable)
    sw/neo:             v1.9-42-g972ff5f9
    sw/zodb:            5.4.0
    sw/zeo:             5.2.0
    sw/mysqlclient:     1.3.13

Run NEO/{py,go} unit tests there:

    x/src/lab.nexedi.com/kirr/neo/go/neo/t$ ./neotest test neotest@rio.kirr.nexedi.com:4
    ?       lab.nexedi.com/kirr/neo/go/internal/packed      [no test files]
    ok      lab.nexedi.com/kirr/neo/go/neo/neonet   (cached)
    ok      lab.nexedi.com/kirr/neo/go/neo/proto    (cached)
    ok      lab.nexedi.com/kirr/neo/go/zodb (cached)
    ?       lab.nexedi.com/kirr/neo/go/zodb/cmd/zodb        [no test files]
    ?       lab.nexedi.com/kirr/neo/go/zodb/internal/pickletools    [no test files]
    ?       lab.nexedi.com/kirr/neo/go/zodb/storage [no test files]
    ok      lab.nexedi.com/kirr/neo/go/zodb/storage/fs1     (cached)
    ?       lab.nexedi.com/kirr/neo/go/zodb/storage/fs1/cmd/fs1     [no test files]
    ok      lab.nexedi.com/kirr/neo/go/zodb/storage/fs1/fs1tools    (cached)
    ?       lab.nexedi.com/kirr/neo/go/zodb/storage/fs1/fsb [no test files]
    ?       lab.nexedi.com/kirr/neo/go/zodb/storage/zeo     [no test files]
    ?       lab.nexedi.com/kirr/neo/go/zodb/wks     [no test files]
    ok      lab.nexedi.com/kirr/neo/go/zodb/zodbtools       (cached)
    ...........................................................................E.EE....c....^C

Neotest will be the driver that was used to prepare benchmarks in
http://navytux.spb.ru/~kirr/neo.html and http://navytux.spb.ru/~kirr/misc/neo·P4.html .

Some draft history related to this patch:

lab.nexedi.com/kirr/neo/commit/d46afb3e		X neotest: Teach it to also run go & py unit tests; hook it into nxd/runTestSuite
lab.nexedi.com/kirr/neo/commit/f694d643		X neotest: Don't fail silently if network address detection fails
lab.nexedi.com/kirr/neo/commit/fa78290a		X neotest: FQDN host name might be not configured
lab.nexedi.com/kirr/neo/commit/56faccad		X neotest/info-local: Don't crash if a prog could not be found
lab.nexedi.com/kirr/neo/commit/f2932247		X neotest/info-local: Don't crash if an egg could not be found
lab.nexedi.com/kirr/neo/commit/f06b7302		X neotest: Determine machine IP addresses via `ip ...` directly, not `getent ...`
lab.nexedi.com/kirr/neo/commit/42e5fe71		X neotest info

In particular try to support ZEO4:

- during handshake we now first wait for remote server to announce its
  preferred protocol, and only then send the version we select to use.
  This is the procedure original ZEO server-client do.

- teach rpc.call to decode exceptions not only for how ZEO5 encodes them
  (marking via 2 flag in "async" field), but also on how ZEO4 and
  earlier encode them: via replying with (exc_type, exc_inst) and
  expecting client to dynamically check exc_type is a subtype of
  Exception.

- handle other protocol differences - e.g. ZEO5 returns last_tid on
  register(), while earlier versions return nothing there.

Tests pending.

For the reference on deco (performance, frequency not fixed):

	name                           time/object
	deco/fs1/zhash.py              15.8µs ± 2%
	deco/fs1/zhash.py-P16           116µs ±12%
	deco/fs1/zhash.go              2.60µs ± 0%
	deco/fs1/zhash.go+prefetch128  3.70µs ±11%
	deco/fs1/zhash.go-P16          13.4µs ±43%
	deco/zeo/zhash.py               316µs ± 7%
	deco/zeo/zhash.py-P16          2.68ms ± 7%
	deco/zeo/zhash.go               111µs ± 2%
	deco/zeo/zhash.go+prefetch128  57.7µs ± 2%
	deco/zeo/zhash.go-P16          1.23ms ± 5%

and in particular it shows that with the same ZEO/py server, the latency
to load an object via py client is ~ 3x worse compared to the latency to
load the same object via hereby Go client.

The performance was obtained via forthcoming neotest, and in particular
ZEO/go client will be also used in forthcoming zwrk (no analog on python side).

See http://navytux.spb.ru/~kirr/neo.html#performance-tests for details.

Tests: pending.

As the first step factor-out int64 Xint64 checker from zodb/storagefs1/index.go
into there.  We'll need the checker in the next patch.

In situations when created connections are used to only send/receive 1
request/response, the overhead to create/shutdown full connections could be
too much. Unfortunately this is exactly the mode that is currently
primarily used for compatibility with NEO/py. To help mitigate the overhead
in such scenarios, lightweight connections mode is provided:

At requester side, one message can be sent over node link with link.Send1 .
Inside a connection will be created and then shut down, but since the
code manages whole process internally and does not show the connection to
user, it can optimize those operations significantly. Similarly link.Ask1
sends 1 request, receives 1 response, and then puts the connection back into
pool for later reuse.

At receiver side, link.Recv1 accepts a connection with the first message
remote peer sent us when establishing it, and wraps the result into Request
object. The Request contains the message received and internally the
connection. A response can be sent back via Request.Reply. Then once
Request.Close is called the connection object that was accepted is
immediately put back into pool for later reuse.

Some history of lightweight mode:

lab.nexedi.com/kirr/neo/commit/0fa96338	X Clarified Request.Close semantics - tests working again
lab.nexedi.com/kirr/neo/commit/a5ac1652	X Ask1: switch to sending directly over link
lab.nexedi.com/kirr/neo/commit/755e3654	X Request.Reply: switch to replying directly over link
lab.nexedi.com/kirr/neo/commit/c643ba53	X Send1: switch to sending directly over link
lab.nexedi.com/kirr/neo/commit/7dcbc9c5	X Send1: switch to lightClose
lab.nexedi.com/kirr/neo/commit/851864a9	X chan RTT benchmark which simulates Recv1 = Accept + Recv
lab.nexedi.com/kirr/neo/commit/099bfc29	X freelist for PktBuf
lab.nexedi.com/kirr/neo/commit/58c2e39a	X Benchmark for link Ask1/Recv1 over TCP loopback

Provide Conn.Send and Conn.Recv which work on NEO messages and
automatically encode/decode them into packets on the fly.

Similarly to NEO/py also provide Ask to send a request and receive
expected reply and Expect which does only the latter half of Ask.

Implement NEO protocol handshaking and use it in newly provided DialLink
and ListenLink which correspondingly first do regular network dial or
listen and than perform the handshake on just established TCP
connection. If handshake goes ok, the result is wrapped into NodeLink.

Some history:

	lab.nexedi.com/kirr/neo/commit/8d0a1469	X Handshake draftly done

See also http://navytux.spb.ru/~kirr/neo.html#development-overview
(starting from "The neonet module also provides DialLink and ListenLink
...")

Continue NEO/go with neonet - the layer to exchange messages in between
NEO nodes.

NEO/go shifts from thinking about NEO protocol logic as RPC to thinking
of it as more general network protocol and so settles to provide general
connection-oriented message exchange service. This way neonet provides
generic connection multiplexing on top of a single TCP node-node link.

Neonet compatibility with NEO/py depends on the following small NEO/py patch:

    kirr/neo@dd3bb8b4

which adjusts message ID a bit so it behaves like stream_id in HTTP/2:

    - always even for server initiated streams
    - always odd  for client initiated streams

and is incremented by += 2, instead of += 1 to maintain above invariant.

See http://navytux.spb.ru/~kirr/neo.html#development-overview (starting from
"Then comes the link layer which provides service to exchange messages over
network...") for the rationale.

Unfortunately current NEO/py maintainer is very much against merging that patch.

This patch brings in the core of neonet. Next patches will add initial
handshaking, user-level Send/Recv + Ask/Expect and "lightweight mode".

Some neonet core history:

lab.nexedi.com/kirr/neo/commit/6b9ed46d	X neonet: Avoid integer overflow on max packet length check
lab.nexedi.com/kirr/neo/commit/8eac771c	X neo/connection: Fix race between link.shutdown() and conn.lightClose()
lab.nexedi.com/kirr/neo/commit/8021a1d5	X rxghandoff
lab.nexedi.com/kirr/neo/commit/68738036	X ... but negative impact on separate client / server processes, strange ...
lab.nexedi.com/kirr/neo/commit/b0dda9d2	X serveRecv: help Go scheduler to switch to receiving G sooner
lab.nexedi.com/kirr/neo/commit/4989918a	X remove defer from rx/tx hot paths
lab.nexedi.com/kirr/neo/commit/e055406a	X no select for acceptq - similarly for rxq path
lab.nexedi.com/kirr/neo/commit/c28ad4d0	X Conn.Recv: receive without select
lab.nexedi.com/kirr/neo/commit/496bd425	X add benchmark RTT over plain net.Conn with serveRecv-style RX handler
lab.nexedi.com/kirr/neo/commit/9fa79958	X draft how to mark RX down without reallocating .rxdown
lab.nexedi.com/kirr/neo/commit/4324c812	X restore all Conn functionality
lab.nexedi.com/kirr/neo/commit/a8e61d2f	X serveSend is not needed
lab.nexedi.com/kirr/neo/commit/9d047b36	X recvPkt via only 1 syscall
lab.nexedi.com/kirr/neo/commit/b555a507	X baseline net RTT benchmark
lab.nexedi.com/kirr/neo/commit/91be5cdd	X everyone is listening from start; CloseAccept to disable listening - works
lab.nexedi.com/kirr/neo/commit/c2a1b63a	X naming: Packet = raw data; Message = meaningful object
lab.nexedi.com/kirr/neo/commit/6fd0c9be	X connection: Adding context to errors from NodeLink and Conn operations
lab.nexedi.com/kirr/neo/commit/65b17bdc	X rework Conn acceptance to be explicit via NodeLink.Accept

This brings some go/py compatibility checks that verify go and python
treat a message code equally. Although messages encoding are tested in
the previous patch there is no explicit tests for go/py compatibility on
messages encoding.

Provide a way for every message to be encoded/decoded to/from NEO wire
encoding. For this introduce Msg interface with wire coding methods and
provide such methods for all message types.

For selected types the methods are implemented manually.
For most of the types the methods are generated automatically by protogen.go program.

protogen.go was mentioned in http://navytux.spb.ru/~kirr/neo.html#development-overview
in "On server-side NEO/go work started by first implementing messages
serialization in exactly the same wire format as NEO/py does ..." paragraph.

A bit of late protogen fixups history:

	lab.nexedi.com/kirr/neo/commit/c884bfd5
	lab.nexedi.com/kirr/neo/commit/385d813a
	lab.nexedi.com/kirr/neo/commit/0f7e0b00
	lab.nexedi.com/kirr/neo/commit/de3ef2c0

Also a message type can be reverse-looked up by message code via MsgType().
This will be later used in network receive code path.

Provide routines to convert selected types to string and also for
UUID and Address <-> string  encoding/decoding.

Start NEO/go code with protocol package that defines message that NEO
nodes exchange in between each other. The definition is based on
neo/lib/protocol.py and is kept in sync with that file.

This commit brings only messages definition. Messages serialization will
come in the follow-up patch.

We will need to use BE16 and BE32 in the next patch.

See zodbtools@b1163449 for details.

Tomáš Peterka noticed that gotos in dump.go are not actually needed because
the same functionality could be achieved with defer in more clean and
structured way.

Do it.

This brings ~ 5% performance hit

	name        old time/op  new time/op  delta
	ZodbDump-4   148µs ± 1%   155µs ± 2%  +4.69%  (p=0.000 n=9+10)

because defer implementation is currently not great
(https://github.com/golang/go/issues/14939)

If we absolutely need those 5% back it could be worked around similar to
e.g. FileStorage.Load:

https://lab.nexedi.com/kirr/neo/blob/6faed528/go/zodb/storage/fs1/filestorage.go#L133
https://lab.nexedi.com/kirr/neo/blob/6faed528/go/zodb/storage/fs1/filestorage.go#L141

/suggested-by @katomaso

Before, it waited for upstream activity until all partitions are touched.
However, when upstream is idle the backup cluster could remain stuck forever
if it was interrupted whereas some cells were still late.

The 'min_tid < new_tid' assertion failed when jumping to the past.

Given that:
- read locks are only taken by transactions (not replication)
- in backup mode, storage nodes stay in UP_TO_DATE state, even if partitions
  are synchronized up to different tids

there was a race condition with the master node replying to LastTransaction
with a TID that may not be replicated yet by all replicas, potentially causing
such replicas to reply OidDoesNotExist or OidNotFound if a client asks it data
too early.

IOW, even if the cluster does contain the data up to `getBackupTid(max)`,
it is only readable by NEO clients up to `getBackupTid(min)` as long as the
cluster is in BACKINGUP state.

Usage of supportsTransactionalUndo() was removed from ZODB in 2007 - see
e.g. the following commits:

https://github.com/zopefoundation/ZODB/commit/a06bfc03
https://github.com/zopefoundation/ZODB/commit/e667b022
https://github.com/zopefoundation/ZODB/commit/f595f7e7
...

/reviewed-by @vpelletier
/reviewed-on nexedi/neoppod!8

`zodb catobj` command to dump content of an object - similarly to `git
cat-file`. Two modes: raw and verbose with `zodb dump` like headers for
the object present.

There is no such command currently in zodbtools/py.

Command to print general information about a ZODB database.
Same as `zodb info` in zodbtools/py.

Add `zodb dump` command to dump arbitrary ZODB database in generic
format. The actual dump protocol being used here is the same as in
zodbtools/py with

	zodbtools!3

applied. (the MR there is OK and is just waiting for upstream ZODB to
negotiate a way to retrieve transaction extension data in raw form).

Add zodbtools which is generic (contrast to fs1tools) set of ZODB
managing utilities. Only package and command infrastructure here -
actual commands will follow up in the next patches.

Add commands for FileStorage index maintainance: manually rebuild the
index and to performe index verification.

Add various FileStorage-specific dump commands with output being
bit-to-bit exact with the following ZODB/py FileStorage tools:

- fsdump.py
- fsdump.py (verbose dumper)
- fstail.py

Please see the patch for links about this dump formats.

Build FileStorage ZODB driver out of format record loading/decoding
and index routines we just added in previous patches.

The driver supports only read-only mode so far.

Promised tests for data format interoperability with ZODB/py are added.

Build index type on top of fsb.Tree introduced in the previous patch and
add routines to save and load it to/from disk.

We ensure ZODB/py compatibility via generating test FileStorage database
+ its index and checking we can load index from it and also that if we
save an index ZODB/py can load it back. FileStorage index is hard to get
bit-to-bit identical since this index uses python pickles which can
encode the same objects in several different ways.

FileStorage index maps oid to file position storing latest data record
for this oid. This index is naturally to implement via BTree as e.g.
ZODB/py does.

In Go world there is github.com/cznic/b BTree library but without
specialization and working via interface{} it is slower than it could be
and allocates a lot. So generate specialized version of that code with
key and value types exactly suitable for FileStorage indexing.

We use a bit patched b version with speed ups for bulk-loading data via
regular point-ingestion BTree entry point:

	https://lab.nexedi.com/kirr/b x/refill

The patches has not been upstreamed because it slows down general case a
bit (only a bit, but still this is a "no" to me), and because with
dedicated bulk-loading API it could be possible to still load data
several times faster. Still current version is enough for not very-huge
indices.

Btw ZODB/py does the same (see fsBucket + friends).

Start implementing FileStorage support by adding code to load/decode
FileStorage records and way to iterate a FileStorage.

Tests will come in a later patch together with ZODB-level loading
support.

Storage drivers can register themselves via zodb.RegisterDriver.

Later cliens can request to open a storage by URL via zodb.OpenStorage.
The opener will lookup driver registry and wrap created driver instance
with common layer with cache etc to turn an IStorageDriver into fully
working IStorage.

The cache is needed so that we can provide IStorage.Prefetch
functionality generally wrapped on top of a storage driver: when an
object is loaded, the loading itself consists of steps:

1. start loading object into cache,
2. wait for the loading to complete.

This way Prefetch is naturally only "1" - start loading object into
cache but do not wait for the loading to be complete. Go's goroutines
naturally help here where we can spawn every such loading into its own
goroutine instead of explicitly programming loading in terms of a state
machine.

Since this cache is mainly needed for Prefetch to work, not to actually
cache data (though it works as cache for repeating access too), the goal
when writing it was to add minimal overhead for "data-not-yet-in-cache"
case. Current state we are not completely there yet but the latency is
acceptable - depending on the workload the cache layer adds ~

	0.5 - 1 - 3µs

to loading times.

ZODB/py serializes data using python pickles. Basically every serialized
object has two parts: class description and object state. Here we
start by providing minimal functionality to extract class-name from
serialized data.

The library used for pickle decoding (and in later patches encoding) is

	github.com/kisielk/og-rek

It was audited by me for security flaws to some extent.

Contrary to Python pickle module it does not run arbitrary code on
decoding.