GitLab

This is a draft.  There's a LOT of hard design choices which are not
yet completely settled here.

Corresponding updates to the ipld/specs repo will be coming soon:
these implementations match a very recursive concept of selectors.
(https://github.com/ipld/specs/pull/116 is roughly this.)

There's so many things to go over, here.

- selectors at all
- selectFields is kind of a special case of unions
- selectPath as a concept is gone; is a degenerate case of selectFields
- we've added some new methods to help narrow down search spaces
- we have serial selector spec parsers...!  (very hand-rolled.)
- the idea of always reporting candidates vs definite match parents
  is dropped for now; it requires a different algo with different
  performance characteristics, so, we'll do it as such -- later.
- we ended up with unions being *in*!  They're going to be used
  internally by a bunch of other things -- see comment blocks in
  the code about that (tl;dr recursives imply a need of unions).

More docs will be coming in future commits; this is just a checkpoint
of the progress.
Signed-off-by: Eric Myhre <hash@exultant.us>

NodeBuilderChooser returned -- sorry.  There are some cases where it's
unavoidable.  (If we have schemas / typed nodes, we can do feature
detection on the node to see if it can recommend an appropriate
NodeBuilder for the far side of its link.  If we're fine using Node
implementations that have 'any' storage support, it's not an issue.
If we're using *bind* implementation Nodes -- which are constrained
by the Golang native type system, and yet not perfectly mapped onto
our own typed.Node constraint declarations -- then we need some way
to choose the NodeBuilder.  So.  NodeBuilderChooser.  Again: sorry.)

We can probably still expect the NodeBuilderChooser to be fixed
(probably returning one of the 'any' storage supporting Node impls)
in practice, since these traversal systems are generally for either
"low context" usage (e.g., dunno what the data is) or will be used
on typed/schema nodes, in which case we're again free of these issues.
And the default values will indeed do this, using our new helpful
default initialization for TraversalConfig.

TraversalConfig will now always be initialized to sensible default
values when using any of the traversal methods.  That means you can
always assume `tp.Ctx`, etc, are going to be set -- no nil checks
necssary -- even though they're optional to the caller.

Error messages from traversal.Focus are touched up a bit for both
consistency and clearer information.  There's more work to do here:
we want these to be full-on typed errors before we call it "done".
This work will probably begin soon, but be spread over quite a few
commits (we also need to go back up to the *main* ipld package and
make types for Node-level errors, and make sure tests exist to
standardize those errors across Node implementations as well).
Signed-off-by: Eric Myhre <hash@exultant.us>

Outline of Traverse* funcs; comment about link loaders in TraversalConfig; confession of working draft of Selector interface; fixed typo in AdvVisitFn return types.

Yes, that's lot of things heaped in one commit.

Yes, (unfortunately,) they're all related.  Almost the entirety of this
has to manifest *at once*, all seamlessly connected, for any part of
it to get off the ground.

Note how very much is handwaved in the comments about TraversalConfig
having linkloader tools of some kind.  There's a lot to unpack there.
Getting it to work well, and let users of the library supply functions
that customize the parts that are interesting to the user, while *not*
getting them hamstrung by a bunch of details about multicodecs and
multihashing (unless they want to!)... requires careful design work.
Signed-off-by: Eric Myhre <hash@exultant.us>