feat(linksystem): add reification to LinkSystem

adl/rot13adl/example_test.go

@@ -2,14 +2,19 @@ package rot13adl_test
 
 import (
  "bytes"
+ "context"
  "fmt"
  "strings"
 
+ "github.com/ipfs/go-cid"
  "github.com/polydawn/refmt/json"
 
+ "github.com/ipld/go-ipld-prime"
  "github.com/ipld/go-ipld-prime/adl/rot13adl"
  "github.com/ipld/go-ipld-prime/codec/dagjson"
+ cidlink "github.com/ipld/go-ipld-prime/linking/cid"
  "github.com/ipld/go-ipld-prime/must"
+ "github.com/ipld/go-ipld-prime/storage"
 )
 
 func ExampleUnmarshallingToADL() {
@@ -38,7 +43,51 @@ func ExampleUnmarshallingToADL() {
  // adl node kind: string
  // adl view value: "a cool string"
 }
+func ExampleLoadingToADL() {
 
+ // Create a NodeBuilder for the ADL's substrate.
+ // Unmarshalling into this memory structure is optimal,
+ // because it immediately puts data into the right memory layout for the ADL code to work on,
+ // but you could use any other kind of NodeBuilder just as well and still get correct results.
+ nb := rot13adl.Prototype.SubstrateRoot.NewBuilder()
+
+ // Unmarshal -- using the substrate's nodebuilder just like you'd unmarshal with any other nodebuilder.
+ err := dagjson.Unmarshal(nb, json.NewDecoder(strings.NewReader(`"n pbby fgevat"`)), true)
+ fmt.Printf("unmarshal error: %v\n", err)
+
+ substrateNode := nb.Build()
+ // now save the node to storage
+ lp := cidlink.LinkPrototype{cid.Prefix{
+ Version: 1,
+ Codec: 0x129,
+ MhType: 0x13,
+ MhLength: 4,
+ }}
+ linkSystem := cidlink.DefaultLinkSystem()
+ storage := &storage.Memory{}
+ linkSystem.StorageReadOpener = storage.OpenRead
+ linkSystem.StorageWriteOpener = storage.OpenWrite
+ linkSystem.NodeReifier = func(_ ipld.LinkContext, nd ipld.Node, _ *ipld.LinkSystem) (ipld.Node, error) {
+ return rot13adl.Reify(nd)
+ }
+ lnk, err := linkSystem.Store(ipld.LinkContext{Ctx: context.Background()}, lp, substrateNode)
+ fmt.Printf("storage error: %v\n", err)
+
+ // reload from storage, but this time the NodeReifier function should give us the ADL
+ syntheticView, err := linkSystem.Load(ipld.LinkContext{Ctx: context.Background()}, lnk, rot13adl.Prototype.SubstrateRoot)
+ fmt.Printf("load error: %v\n", err)
+
+ // We can inspect the synthetic ADL node like any other node!
+ fmt.Printf("adl node kind: %v\n", syntheticView.Kind())
+ fmt.Printf("adl view value: %q\n", must.String(syntheticView))
+
+ // Output:
+ // unmarshal error: <nil>
+ // storage error: <nil>
+ // load error: <nil>
+ // adl node kind: string
+ // adl view value: "a cool string"
+}
 func ExampleCreatingViaADL() {
  // Create a NodeBuilder for the ADL -- the high-level synthesized thing (not the substrate).
  nb := rot13adl.Prototype.Node.NewBuilder()

linking.go

@@ -24,7 +24,11 @@ func (lsys *LinkSystem) Load(lnkCtx LinkContext, lnk Link, np NodePrototype) (No
  if err := lsys.Fill(lnkCtx, lnk, nb); err != nil {
  return nil, err
  }
- return nb.Build(), nil
+ nd := nb.Build()
+ if lsys.NodeReifier == nil {
+ return nd, nil
+ }
+ return lsys.NodeReifier(lnkCtx, nd, lsys)
 }
 
 func (lsys *LinkSystem) MustLoad(lnkCtx LinkContext, lnk Link, np NodePrototype) Node {

linksystem.go

@@ -33,6 +33,7 @@ type LinkSystem struct {
  StorageWriteOpener BlockWriteOpener
  StorageReadOpener BlockReadOpener
  TrustedStorage bool
+ NodeReifier NodeReifier
 }
 
 // The following two types define the two directions of transform that a codec can be expected to perform:
@@ -206,6 +207,21 @@ type (
  // See the documentation of BlockWriteOpener for more description of this
  // and an example of how this is likely to be reduced to practice.
  BlockWriteCommitter func(Link) error
+
+ // NodeReifier defines the shape of a function that given a node with no schema
+ // or a basic schema, constructs Advanced Data Layout node
+ //
+ // The LinkSystem itself is passed to the NodeReifier along with a link context
+ // because Node interface methods on an ADL may actually traverse links to other
+ // pieces of context addressed data that need to be loaded with the Link system
+ //
+ // A NodeReifier return one of three things:
+ // - original node, no error = no reification occurred, just use original node
+ // - reified node, no error = the simple node was converted to an ADL
+ // - nil, error = the simple node should have been converted to an ADL but something
+ // went wrong when we tried to do so
+ //
+ NodeReifier func(LinkContext, Node, *LinkSystem) (Node, error)
 )
 
 // ErrLinkingSetup is returned by methods on LinkSystem when some part of the system is not set up correctly,