Before this patch, the 'KnownMasterList' field of the 'NotPrimaryMaster'
was expected to be structured in the following way:

	ArrayHeader (KnownMasterList)

	    ArrayHeader (KnownMaster)

		ArrayHeader (Address)

		    Host (string)
		    Port (uint16)

However NEO/py sends the following structure:

	ArrayHeader (KnownMasterList)

	    ArrayHeader (Address)

		Host (string)
		Port (uint16)

This also makes sense, as 'KnownMaster' doesn't need to add another
nesting, because it only includes the address.

This patch amends the NEO/go protocol definition to transparently
represent the nesting as it's send by NEO/py. See also
18287612 for a similar issue.

It was already 'int' before the migration to msgpack:

https://lab.nexedi.com/nexedi/neoppod/-/blob/6332112cb/neo/lib/protocol.py#L653

It is 'int' after the migration to msgpack:

https://lab.nexedi.com/nexedi/neoppod/-/blob/9d0bf97a1/neo/lib/protocol.py#L842

(it's explicitly cast into an integer here)

Another verification that 'ErrorCode' is 'int' on the wire can be found
here:

https://lab.nexedi.com/nexedi/neoppod/-/blob/3ddb6663b/neo/tests/protocol#L76

In the Nexedi NEO protocol specification document v1 this is however not
specified (or I couldn't find it):

https://neo.nexedi.com/P-NEO-Protocol.Specification.2019

'Compression' is py type 'Optional[int]'. Before this patch only 'int' was
supported. Now NEO/go also understands 'Compression' with value 'Nil'.

With nexedi/neoppod@fd80cc30 NEO/py added support to encode the compression
algorithm with the 'Compression' parameter. Before this, compression could
only be true (= with compression) or false (= without compression). Now
the absence of compression is encoded with 0. Any other number than 0
encodes a compression algorithm. The mapping is currently:

	1 = zlib

In the future, 2 could mean zstd [1].

[1] https://github.com/facebook/zstd/issues/1134

In pre-msgpack protocol an 'INVALID_{TID,OID}' was always
decoded as 'None' in NEO/py [1]. But in msgpack protocol
this isn't true anymore. An `INVALID_TID` is now decoded
as an `INVALID_TID`. And this then leads to errors later [2].
We fix this by encoding 'INVALID_{TID,OID}' to NIL on the
wire and by decoding NIL to 'INVALID_{TID,OID}'.

---

[1] https://lab.nexedi.com/nexedi/neoppod/-/blob/6332112cba979dfd29b40fe9f98d097911fde696/neo/lib/protocol.py#L579-583
[2] With SQLite backend we can see the following exception:

Traceback (most recent call last):
  File "/home/levin/neo/neo/tests/functional/__init__.py", line 192, in start
    self.run()
  File "/home/levin/neo/neo/tests/functional/__init__.py", line 288, in run
    getattr(neo.scripts,  self.command).main()
  File "/home/levin/neo/neo/scripts/neostorage.py", line 32, in main
    app.run()
  File "/home/levin/neo/neo/storage/app.py", line 196, in run
    self._run()
  File "/home/levin/neo/neo/storage/app.py", line 227, in _run
    self.doOperation()
  File "/home/levin/neo/neo/storage/app.py", line 301, in doOperation
    poll()
  File "/home/levin/neo/neo/storage/app.py", line 145, in _poll
    self.em.poll(1)
  File "/home/levin/neo/neo/lib/event.py", line 160, in poll
    to_process.process()
  File "/home/levin/neo/neo/lib/connection.py", line 508, in process
    self._handlers.handle(self, self._queue.pop(0))
  File "/home/levin/neo/neo/lib/connection.py", line 93, in handle
    self._handle(connection, packet)
  File "/home/levin/neo/neo/lib/connection.py", line 108, in _handle
    pending[0][1].packetReceived(connection, packet)
  File "/home/levin/neo/neo/lib/handler.py", line 125, in packetReceived
    self.dispatch(*args)
  File "/home/levin/neo/neo/lib/handler.py", line 75, in dispatch
    method(conn, *args, **kw)
  File "/home/levin/neo/neo/storage/handlers/client.py", line 67, in askObject
    o = app.dm.getObject(oid, at, before)
  File "/home/levin/neo/neo/storage/database/manager.py", line 484, in getObject
    before_tid and u64(before_tid))
  File "/home/levin/neo/neo/storage/database/sqlite.py", line 336, in _getObject
    r = q(sql + ' AND tid=?', (partition, oid, tid))
OverflowError: Python int too large to convert to SQLite INTEGER

Some NEO protocol packets have the field 'RowList'. This field contains
information about each row of a partition table. In NEO/go the information
of each row is represented with the 'RowInfo' type [1]. This type is defined
as a struct with the field ‘CellList’. ‘CellList’ is defined as a list of
'CellInfo' [1] (e.g. an entry for each cell).

NEO/go {en,de}codes struct types with ‘genStructHead’ (structures in
golang are encoded as arrays in msgpack) [2]. From the 'RowList'
definition, the msgpack decoder currently expects the following msgpack
array structure:

    ArrayHeader (RowList)

        ArrayHeader (RowInfo)

            ArrayHeader (CellList)

                ArrayHeader (CellInfo)

                    int32 (NID)
                    enum (State)

However NEO/py actually sends:

    ArrayHeader (RowList)

        ArrayHeader (CellList)

            ArrayHeader (CellInfo)

                int32 (NID)
                enum (State)

In other words, currently the NEO/go msgpack encoder expects one more
nesting, which NEO/py doesn’t provide (and which also doesn’t seem to
be necessary as the outer nesting would always only contain one
element). We could adjust the msgpack {en,de}coder to introduce an
exception for the 'RowInfo' type, however as the protocol definition in
'proto.go' aims to transparently reflect the structure of the packets on
the wire, it seems to be more appropriate to fix this straight in the
protocol definition. This is also less error-prone as we don't have to
fix all the different positions of the encoder, decoder & sizer and it's
less code (particularly if 'RowInfo' doesn't stay the only case for such
an issue).

[1] https://lab.nexedi.com/kirr/neo/-/blob/1ad088c8/go/neo/proto/proto.go#L391-394
[2] https://lab.nexedi.com/kirr/neo/-/blob/1ad088c8/go/neo/proto/protogen.go#L1770-1775

The data type of IdTime is 'Optional[float]' [1], [2]. Before this patch the
msgpack decoder could only decode 'IdTime' in case its data type was
'float'. Now it also supports the decoding of IdTime in case it is NIL.

Besides the changes in 'protogen.go', this patch also relaxes the
overflow check test in 'proto_test.go', which fails in its previous form
after adjusting the decoding. However I don't think the exact error
type should matter here: in real-usage cases we don't mind about the
particular error type [3].

[1] See here, the fifth argument is IdTime:

    https://lab.nexedi.com/nexedi/neoppod/-/blob/3ddb6663/neo/master/handlers/identification.py#L26-27

    This is found to be 'Optional[float]':

    https://lab.nexedi.com/nexedi/neoppod/-/blob/3ddb6663/neo/tests/protocol#L98

[2] This seems to be true for both, pre-msgpack and post-msgpack
    protocol, because in the pre-msgpack NEO/go there is already this
    note:

    https://lab.nexedi.com/kirr/neo/-/blob/1ad088c8/go/neo/proto/proto.go#L352-357

[3] See https://lab.nexedi.com/kirr/neo/-/blob/6fb93a60/go/neo/neonet/connection.go#L1531-1534
    and https://lab.nexedi.com/kirr/neo/-/blob/6fb93a60/go/neo/neonet/connection.go#L1588-1591

In NEO/go protocol, we describe some parameters that can
be send via NEO packages with structures. On the wire all of
these structures are encoded as msgpack arrays [1]. Msgpack
arrays can have 1 or more bytes as a header [2]. Therefore
it's better to use "ReadArrayHeaderBytes" than using

  >>> data = data[1:]

which fails in case we have array with 3 or 5 header bytes.

[1] One could also declare a protocol where these parameters aren't
    send as msgpack arrays but as msgpack maps. See here for the
    msgpack map specification:

    https://github.com/msgpack/msgpack/blob/9aa092d6ca81/spec.md?plain=1#L338

[2] https://github.com/msgpack/msgpack/blob/9aa092d6ca81/spec.md?plain=1#L315

In pre-msgpack protocol, the msgcode increment logic is like this:

Notify 	 add +1 to next msgcode
Request  add +0 to next msgcode   (next msg is answer & should therefore be the same)
Answer 	 add +1 to next msgcode

('Answer' msgcode is adjusted by 'AnswerBit')

In post-msgpack protocol, the logic is a bit different:

Notify 	 add +1 to next msgcode
Request  add +0 to next msgcode   (next msg is answer & should therefore be the same)
Answer 	 add +2 to next msgcode

So here we produce gaps after Request/Answer pairs.

The enum order has changed in the migration to the msgpack encoded
protocol.

See here for pre-msgpack order:

https://lab.nexedi.com/nexedi/neoppod/-/blob/6332112cb/neo/lib/protocol.py#L62-141

And here for post-msgpack order:

https://lab.nexedi.com/nexedi/neoppod/-/blob/9d0bf97a1327182ac29e95d65fd9e18742c43d1f/neo/lib/protocol.py#L102-181

As this order defines the encoding of the enum values, this needs to be
strictly followed to be compatible (to follow the protocol declaration).

nexedi/neoppod@9d0bf97a
changed the msgcode increment logic, therefore we have to re-create the
test data.

With the switch to the msgpack encoding, the NEO/py server
now only supports the M encoding.

Not only for performance reasons (at least 3% faster) but also because of
several ugly things in the way packets were defined:
- packet field names, which are only documentary; for roots fields,
  they even just duplicate the packet names
- a lot of repetitions for packet names, and even confusion between the name
  of the packet definition and the name of the actual notify/request packet
- the need to implement field types for anything, like PByte to support new
  compression formats, since PBoolean is not enough

neo/lib/protocol.py is now much smaller.

* master:
  go/neo/neonet: DialLink: Fix SIGSEGV in case client handshake fails
  go/neo/neonet: Demonstrate DialLink misbehaviour when all handshake attempts fail

In case the last 'handshakeClient' call returns an error, 'DialLink'
returns 'link = nil, err = nil'. Callers of 'DialLink' then don't
recognize that 'link' is 'nil', as it's the convention to only check if
'err' is 'nil', which leads to a 'segmentation violation' as soon as
subsequent code tries to access fields of 'link':

```
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x14 pc=0x7087ae]

goroutine 5 [running]:
lab.nexedi.com/kirr/neo/go/neo/neonet.(*NodeLink).NewConn(0x0)
	/srv/slapgrid/slappart82/srv/runner/instance/slappart6/software_release/parts/wendelin.core/wcfs/neo/go/neo/neonet/connection.go:404 +0x4e
lab.nexedi.com/kirr/neo/go/neo/xneo.Dial.func1()
	/srv/slapgrid/slappart82/srv/runner/instance/slappart6/software_release/parts/wendelin.core/wcfs/neo/go/neo/xneo/connect.go:138 +0x52
lab.nexedi.com/kirr/neo/go/internal/xio.WithCloseOnErrCancel.func2()
	/srv/slapgrid/slappart82/srv/runner/instance/slappart6/software_release/parts/wendelin.core/wcfs/neo/go/internal/xio/xio.go:114 +0x6a
created by lab.nexedi.com/kirr/neo/go/internal/xio.WithCloseOnErrCancel in goroutine 21
	/srv/slapgrid/slappart82/srv/runner/instance/slappart6/software_release/parts/wendelin.core/wcfs/neo/go/internal/xio/xio.go:109 +0x1ad
```

This patch fixes this issue so that now 'err' and 'link' are never both
'nil' again.

/reviewed-by @kirr
/reviewed-on !10

Levin found that when all handshake attempts fail DialLink returns
both link=nil and err=nil which breaks what callers expect and lead to
segmentation fault when accessing that nil link.

-> Add test to demonstrate the problem.

With xfail removed that test currently fails as

    --- FAIL: TestDialLink_AllHandshakeErr (0.00s)
    panic: lab.nexedi.com/kirr/neo/go/neo/neonet.TestDialLink_AllHandshakeErr.gox.func4.1: lab.nexedi.com/kirr/neo/go/neo/neonet.TestDialLink_AllHandshakeErr.func2: DialLink to handshake-rejecting server:
    have: link=<nil> err=<nil>
    want: link=<nil> err=client:1 - server:2: handshake (client): unexpected EOF [recovered]

We will fix the problem in the next patch.

/reported-by @levin.zimmermann
/reported-at !10

I realized a minor mistake I did in writing the tests that needs to
be fixed in order to have reliable test results.

/reviewed-by @kirr
/reviewed-on kirr/neo!9

During our work on 'wendelin.core' URI normalization, Kirill Smelkov
noted a inconsistency between NEO/py and NEO/go URI parser [1]: NEO/py
drops empty query options, while NEO/go preserves them. Let's fix this
inconsistency by adjusting NEO/go to NEO/py behaviour.

[1] nexedi/wendelin.core!28 (comment 212447)

/reviewed-by @kirr
/reviewed-on !9

Hello Kirill,

in nexedi/neoppod!18 and nexedi/neoppod!21 we could find a common solution for a zurl format that previously diverged between NEOgo and NEOpy. The purpose of this MR is to sync again NEOgo and NEOpy zurl format. After merging this, we can continue to sync NEO zurl format in 'wendelin.core' & 'slapos'. Then we finally have unified approach again, which simplifies understanding and reduces unnecessary mental overhead.

As this is strongly related to nexedi/neoppod!21 I thought it'd be a good idea to generally reduce difference and to replace WIP commits with merged NEOpy upstream commits.

Best, Levin

/reviewed-by @kirr
/reviewed-on kirr/neo!7

* lev/sync-zurl:
  client: Don't allow oPtion_nAme in zurl
  app: Remember SSL credentials so that it is possible to retrieve them
  client: Allow to force TLS via neos:// scheme
  client: Don't allow master_nodes and name to be present in options
  Revert "."
  Revert "Y client: Fix URI scheme to move credentials out of query"
  Revert "X Adjust NEO/go to neo:// URL change + py fixups"
  Revert "fixup! Y client: Fix URI scheme to move credentials out of query"
  Revert "Y client: Don't allow master_nodes and name to be present in options"
  go/client/zurl: Sync format to py upstream

Julien notes this is very likely unneeded:
nexedi/neoppod!21 (diffs, comment 195929)

We had it like this since 01a01c8c (client: Add support for zodburi),
but I rechecked zodburi codebase now and it does not do any similar
lowering anywhere.

So drop support for case normalization in zurl options.

/cc @levin.zimmermann
/reviewed-by @jm
/reviewed-on nexedi/neoppod!21

(cherry-picked from commit 798c9f25)

Unfortunately after creating SSL context it is not possible, or at least
I could not find how, to retrieve original credentials with which the
context was created. However wendelin.core needs to be able to take a
client storage, reconstruct zurl to refer to that particular storage,
and pass that zurl to wcfs, so that wcfs, in turn, could access the same
ZODB database.

Given a NEO client instance, it is already possible to retrieve
master_nodes, cluster name, and detect whether SSL is being in use.
However without being able to retrieve original SSL credentials,
reconstructed zurl will not be full and wcfs won't be able to use
exactly the same secrets as python part does.

-> Help wendelin.core by remembering which ca/cert/key were used to
build SSL context.

This information is used by zstor_2zurl in wendelin.core here:

https://lab.nexedi.com/nexedi/wendelin.core/blob/885b3556/lib/zodb.py#L390-418

/cc @levin.zimmermann
/reviewed-by @jm
/reviewed-on nexedi/neoppod!21

Similarly to how it is done with e.g. http:// and https:// - if neos://
is given TLS usage is forced and ca/cert/key must be there either in the
URI itself, or in $NEO_CA, $NEO_CERT and $NEO_KEY environment variables
mimicking the way how e.g. for https:// TLS credentials are taken from
host environment, not from the uri.

The latter might be usability convenience, but is also useful for WCFS
which needs to be able to remove secrets from uri on zurl normalization.

Please see discussion at nexedi/neoppod!18 (comment 184439)
for details.

/cc @levin.zimmermann
/reviewed-by @jm
/reviewed-on nexedi/neoppod!21

(cherry-picked from commit bc3e38ea)

Because list of masters and cluster name must be already present in
netloc and path. Previously e.g.

	neo://db@α,β,γ?master_nodes=a,b,c"

would mean to use master nodes {a,b,c} not {α,β,γ}. Now it is treated as
invalid URI to remove ambiguity. Same for cluster name.

/cc @levin.zimmermann
/reviewed-by @jm
/reviewed-on nexedi/neoppod!21

(cherry-picked from commit 22ccebd6)

This reverts commit a2f192cb. This has
been merged upstream with nexedi/neoppod@17af7f27.
We should rather cherry-pick upstream commit.

This reverts commit b9a42957. In
nexedi/neoppod!18 and
nexedi/neoppod!21 a common
solution for a zurl format was found. This common format keeps
credentials in the query, therefore we should revert patch
b9a42957.

This reverts the py part of kirr/neo@8c974485.
go parts of this patch are handled in 70c0a984.

This reverts commit cf685fb5. This used
to be a divergence between NEO/py and NEO/go, however in nexedi/neoppod!18 and
nexedi/neoppod!21 a common
solution for a zurl format was found. This common format keeps
credentials in the query, therefore we should revert patch
cf685fb5.

This reverts commit 6047f893 in order to
replace it with py upstream commit nexedi/neoppod@22ccebd6.

NEO/go and NEO/py zurl format diverged over time:

- kirr/neo@8c974485

However with nexedi/neoppod!21 a
common solution was found. From there, this patch aims to adjust NEO/go zurl
format to be in sync with NEO/py zurl format again.

* master:
  go/zodb: Handle common options in zurl in generic layer

/reviewed-by @kirr
/reviewed-on kirr/neo!4

* kirr/t+new-uri:
  Revert "Y client: Adjust URI scheme to move client-specific options to fragment"
  fixup! client.go: Fix URI client option parsing for supported + unsupported options
  client.go: Fix URI client option parsing for supported + unsupported options
  fixup! client_test: Add tests for NEO URI parser
  client_test: Add tests for NEO URI parser
  fixup! client: Refactor openClientByURL for easier testing
  client: Refactor openClientByURL for easier testing
  Y go/zodb: Handle common options in zurl in generic layer

Offload drivers from handling options such as ?read-only=1 and force
them to deal with such options only via DriverOptions, never zurl.

See added comment for details.

/reviewed-by @levin.zimmermann
/reviewed-on kirr/neo!4

This reverts commit kirr/neo@4c9414ea.
This patch was added at a time when nexedi/neoppod!18 wasn't
resolved yet, but we already wanted to proceed with WCFS. Now the NEO MR
is resolved and we decided to mostly leave the NEO zurl as it was
originally implemented in nexedi/neoppod!6.
This means we don't need this patch anymore which changed the NEO
zurl format.

readonly is handled by common zodb.OpenDriver.

Before this patch, the parser ignored options which were already supported
by the client (for instance 'read-only') and even raised an error. But the
client can already use this option: as a9246333 describes this should happen in the
local storage URL parser.

Furthermore not-yet-supported client options (for instance compress) broke
the NEO client before this patch. Now these options only raise a warning which
informs the user that they are ignored. Why? We want to use pre-complete NEO
in real-world projects together with NEO/py clusters. Those real-world projects
may already specify options which aren't supported by our NEO/go client yet.
But it doesn't matters so much, because those options are mostly
relevant for other NEO/py cluster clients (e.g. zope nodes). Instead of
filtering those parameters before parsing them to NEO/go in a higher
level (e.g. SlapOS), NEO/go should already support any valid NEO URL
and raise warnings for not yet implemented features.

- use simplified parseURL signature - DriverOptions are not passed nor changed there.
- read-only is handled by generic zodb layer not neo.parseURL .

This test was missing so far. Particularly recent changes of the
NEO URI scheme [1], but also problems with valid old URI [2] stressed
out the necessity for comprehensive NEO URI parser tests.

[1] kirr/neo@4c9414ea
[2] 573514c6 (comment 184417)

- no need to pass DriverOptions into parseURL - it is only zurl that is
  parsed, and also DriverOptions should not be changed by the opener.

- no need to document "If anything fails within this process an error
  and nil are returned." because that is standard omnipresent Go convention.