GitLab

Port 2021 07 21

See merge request !1

This CID has not been verified - dag-json w/ sha2-512 capped at 4 bytes for
a block that's non-trivial to reconstruct manually.

After experimenting with quip and qp for a few months, we seem to agree
that qp is a bit nicer to use. Remove quip, since it's largely redundant
going forward.

Since the qp docs referenced quip, redo that to stand on its own ground.

Fixes #185.

Moving from bindnode, and adding a Type method for consistency with
TypedNode.

Fixes #181.

Before, we envisioned exposing the following APIs:

	Prototype
	PrototypeNoSchema
	PrototypeOnlySchema
	Wrap
	WrapNoSchema

The names were long, though, and perhaps a bit confusing too. Instead,
just expose Prototype and Wrap, and allow either of the parameters to be
nil to infer its value. This makes the API easier to navigate, and we
can concentrate documentation in fewer places.

Now there's two main entrypoints: Prototype if one wants a high-level
prototype to create nodes of a certain shape, and Wrap if one wants to
expose an existing Go value as an IPLD node. Whether one supplies only
an IPLD Schema, only a Go type/value, or both, is their choice. The only
exception is Wrap, which always requires a Go value by definition.

Wrap works now, too, and gains an example. It's the same idea as the
previous Prototype example, but it builds the value via a Go composite
literal rather than fluent/qp on the IPLD side.

Another noteworthy change is that we now return TypedPrototype and
TypedNode rather than the regular NodePrototype and Node interfaces,
since bindnode always works with a schema - even when it's inferred.
The big advantage here is that one can call the Representation method
directly on the result without having to type assert, like the example
does.

Including LookupBySegment and LookupByNode for both maps and lists, but
also As<T> for the representation form of all scalar kinds.

While at it, expand the interface implementation assertions, too.

Note that we had to make the node/basic tests external,
for the sake of testing LookupByNode without inserting an import cycle.

In particular, calling non-scalar Node and Assembler methods should
always fail.

While at it, remove some unused code, since unions always have
representation strategies.

Brings up code coverage in bindnode from 72.7% to 75%.

It covers AssignKind, AssignNode, and AsKind for every combination of
assembler kind and method.

We also verify that a constructed scalar node behaves the same with
AsKind when using its representation, like the old test.

There's effectively a triple loop as a test table, so the subtest name
has up to three components separated by dashes, such as:

	TestSchema/Scalars/Bytes-AssignNode-String

We also use this test as a demo of quicktest instead of go-wish.

Finally, adapt bindnode to pass these tests just like codegen. This was
mainly a bunch of TODOs in the relevant methods.

We add node/tests.SchemaTestAll to simplify this task, meaning we don't
need to duplicate all test func declarations in node/bindnode.
SchemaTestAll is also flexible enough to allow running multiple
sub-tests per schema test in the future.

There were two remaining places in node/tests that still weren't using
ipld.DeepEqual, so fix those.

Finally, bindnode needed a couple of changes to fully support
ipld.DeepEqual. Most notable is iteration over maps, which required a
bit of a refactor to keep ordered keys.

Along with a generic Engine interface, so that they can be reused for
other ipld.Node implementations, such as bindnode.

node/bindnode will start using these in a follow-up commit, since this
one is large enough as is.

Tested that all three forms of testing schema/gen/go still work:

	go test

	CGO_ENABLED=0 go test

	go test -tags=skipgenbehavtests

Per https://github.com/ipld/go-ipld-prime/issues/175 and some discussions today.

Also touched up the docs for Next vs Done a bit while I was in the area;
they're not significantly changed, but there were some dangling antecedents
that didn't read very well, and now it's a bit better.

Lots of TODOs and polishing to do, but it passes the schema/gen/go tests
with minimal changes.

Follow-up commits will continue filling in the gaps and adding
documentation, notably examples. We'll also make the tests run by
default, after a bit of refactoring.

The funciton is carefully documented via godoc, so I'm not going to
attempt to document it here again. But as a high-level summary, it's
like a reflect.DeepEqual applied to the ipld.Node interface rather than
reflect.Value.

The only other two noteworthy details are that errors are treated as
panics, and Links are compared directly via ==.

Finally, we add table-driven tests to ensure all edge cases work.

Fixes #173.

Add enumerate methods to the multicodec registries.

Make a multicodec.Registry type available.

(This is a logical port of
https://github.com/ipld/go-ipld-prime/pull/169 to follow
https://github.com/ipld/go-ipld-prime/pull/172 .)

I've added more documentation -- particularly, cautionary notes on the
package-scope functions which read the global shared state.

The hope is that this might be helpful if you want to build a
multicodec registry other than the global one, but are still buying
into the idea of the registry being keyed by indicator numbers.

(I'm... not actually sure how useful this is, because I'd think if
you're building something other than the default, there's also a good
chance you'd want *more* features than a primitive numerical mapping,
which are probably going to be related to whatever your application
logic in the area is, and therefore not possible for this library
to usefully anticipate.  But, I dunno.  I'm doing this because
people are proposing attaching more features to the global, and
I'm not comfortable with it, and I'm hoping this will provide a
pressure release valve.)

The current interfaces are functionally unchanged.

The multicodec.Registry type can now be used when constructing
a cidlink.LinkSystem.  (This saves you from having to write the
glue functions to unbox cidlink and then do the LookupEncoder
and LookupDecode calls.)

For where this relates to LinkSystem, I considered a mechanism like:
`func (r *Registry) InstallOn(lsys *ipld.LinkSystem)` ...
and probably would've found that a bit cleaner.
However, it doesn't jive with the way we've isolated the CID types
into a package with a LinkSystem just for them (sigh; that really is
the gift of complexity that just keeps giving); you can see how the
EncoderChooser and DecoderChooser funcs need a tiny bit of type
assertions in order to figure out how to extract the multicodec
indicator from the Link/LinkPrototype types?  That bit is a bit
that we still want to keep cordoned off the rest of the import tree.

DefaultRegistry is also now an exported variable, in addition to the
functions which already worked with the global data.
I probably would've preferred to keep the DefaultRegistry variable
unexported, because I can't imagine any good coming of touching it,
but the relationship to LinkSystem detailed in the above paragraph
requires some access to it.

Since qp uses panics as an error mechanism, the top-level functions
recover those errors to return them normally.

However, this blows up if, internally, an ipld.Node implementation
panics with a value whose type is not error. For example, with:

	panic("some panic message")

One gets:

	panic: some panic message [recovered]
		panic: interface conversion: string is not error: missing method Error

Fix this by having a fallback for non-error panic values.

Allow emitting & parsing of bytes per dagjson codec spec