swarm/storage/mru: refactor and documentation

Author: jpeletier

swarm/api/client/client.go

@@ -617,7 +617,7 @@ func (c *Client) UpdateResource(manifestAddressOrDomain string, data []byte, sig
 }
 
 func (c *Client) updateResource(mruRequest *mru.UpdateRequest, manifestAddressOrDomain string) (io.ReadCloser, error) {
-	body, err := mru.EncodeMruRequest(mruRequest)
+	body, err := mru.EncodeUpdateRequest(mruRequest)
 	if err != nil {
 		return nil, err
 	}
@@ -665,7 +665,7 @@ func (c *Client) GetResourceMetadata(manifestAddressOrDomain string) (*mru.Updat
 		return nil, err
 	}
 
-	metadata, err := mru.DecodeMruRequest(body)
+	metadata, err := mru.DecodeUpdateRequest(body)
 	if err != nil {
 		return nil, err
 	}

swarm/api/http/server.go

@@ -410,7 +410,7 @@ func (s *Server) HandlePostResource(w http.ResponseWriter, r *Request) {
 		Respond(w, r, err.Error(), http.StatusInternalServerError)
 		return
 	}
-	mruRequest, err := mru.DecodeMruRequest(body) // decodes request JSON
+	mruRequest, err := mru.DecodeUpdateRequest(body) // decodes request JSON
 	if err != nil {
 		Respond(w, r, err.Error(), http.StatusBadRequest) //TODO: send different status response depending on error
 		return
@@ -550,7 +550,7 @@ func (s *Server) handleGetResource(w http.ResponseWriter, r *Request) {
 				Respond(w, r, fmt.Sprintf("cannot retrieve resource metadata for rootAddr=%s: %s", rootAddr.Hex(), err), http.StatusNotFound)
 				return
 			}
-			rawResponse, err := mru.EncodeMruRequest(unsignedMruRequest)
+			rawResponse, err := mru.EncodeUpdateRequest(unsignedMruRequest)
 			if err != nil {
 				Respond(w, r, fmt.Sprintf("cannot encode unsigned MruRequest: %v", err), http.StatusInternalServerError)
 				return

swarm/api/http/server_test.go

@@ -141,7 +141,7 @@ func TestBzzResourceMultihash(t *testing.T) {
 	updateRequest.Sign(signer)
 	log.Info("added data", "manifest", string(b), "data", common.ToHex(mh))
 
-	body, err := mru.EncodeMruRequest(updateRequest)
+	body, err := mru.EncodeUpdateRequest(updateRequest)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -213,7 +213,7 @@ func TestBzzResource(t *testing.T) {
 	}
 	updateRequest.Sign(signer)
 
-	body, err := mru.EncodeMruRequest(updateRequest)
+	body, err := mru.EncodeUpdateRequest(updateRequest)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -334,7 +334,7 @@ func TestBzzResource(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	updateRequest, err = mru.DecodeMruRequest(b)
+	updateRequest, err = mru.DecodeUpdateRequest(b)
 	if err != nil {
 		t.Fatalf("Error decoding resource metadata: %s", err)
 	}
@@ -343,7 +343,7 @@ func TestBzzResource(t *testing.T) {
 	if err = updateRequest.Sign(signer); err != nil {
 		t.Fatal(err)
 	}
-	body, err = mru.EncodeMruRequest(updateRequest)
+	body, err = mru.EncodeUpdateRequest(updateRequest)
 	if err != nil {
 		t.Fatal(err)
 	}

swarm/storage/mru/doc.go

@@ -3,50 +3,57 @@
 // The update scheme is built on swarm chunks with chunk keys following
 // a predictable, versionable pattern.
 //
-// Updates are defined to be periodic in nature, where periods are
-// expressed in terms of number of blocks.
-//
-// The root entry of a mutable resource is tied to a unique identifier,
-// typically - but not necessarily - an ens name.  The identifier must be
-// an valid IDNA string. It also contains the block number
-// when the resource update was first registered, and
-// the block frequency with which the resource will be updated, both of
+// Updates are defined to be periodic in nature, where the update frequency
+// is expressed in seconds.
+//
+// The root entry of a mutable resource is tied to a unique identifier that
+// is deterministically generated out of the metadata content that describes
+// the resource. This metadata includes a user-defined resource name, a resource
+// start time that indicates when the resource becomes valid,
+// the frequency in seconds with which the resource is expected to be updated, both of
 // which are stored as little-endian uint64 values in the database (for a
-// total of 16 bytes). It also contains the unique identifier.
+// total of 16 bytes). It also contains the owner's address (ownerAddr)
 // This MRU info is stored in a separate content-addressed chunk
 // (call it the metadata chunk), with the following layout:
 //
-// (startblock|frequency|address|identifier)
+// (00|length|startTime|frequency|name|ownerAddr)
 //
 // (The two first zero-value bytes are used for disambiguation by the chunk validator,
 // and update chunk will always have a value > 0 there.)
 //
+// Each metadata chunk is identified by its rootAddr, calculated as follows:
+// metaHash=H(len(metadata), startTime, frequency,name)
+// rootAddr = H(metaHash, ownerAddr).
+// where H is the SHA3 hash function
+// This scheme effectively locks the root chunk so that only the owner of the private key
+// that ownerAddr was derived from can sign updates.
+//
 // The root entry tells the requester from when the mutable resource was
-// first added (block number) and in which block number to look for the
+// first added (Unix time in seconds) and in which moments to look for the
 // actual updates. Thus, a resource update for identifier "føø.bar"
-// starting at block 4200 with frequency 42 will have updates on block 4242,
-// 4284, 4326 and so on.
+// starting at unix time 1528800000 with frequency 300 (every 5 mins) will have updates on 1528800300,
+// 1528800600, 1528800900 and so on.
 //
 // Actual data updates are also made in the form of swarm chunks. The keys
 // of the updates are the hash of a concatenation of properties as follows:
 //
-// sha256(period|version|address|namehash)
-//
-// The period is (currentblock - startblock) / frequency
+// updateAddr = H(period, version, rootAddr)
+// where H is the SHA3 hash function
+// The period is (currentTime - startTime) / frequency
 //
-// Using our previous example, this means that a period 3 will have 4326 as
-// the block number.
+// Using our previous example, this means that a period 3 will happen when the
+// clock hits 1528800900
 //
-// If more than one update is made to the same block number, incremental
+// If more than one update is made in the same period, incremental
 // version numbers are used successively.
 //
-// A lookup agent need only know the identifier name in order to get the versions
+// A lookup agent need only know the rootAddr in order to get the versions
 //
-// the resourcedata is:
-// headerlength|period|version|identifier|data
+// the resource update data is:
+// resourcedata = headerlength|period|version|metaHash|rootAddr|data
 //
 // the full update data that goes in the chunk payload is:
 // resourcedata|sign(resourcedata)
 //
-// headerlength is a 16 bit value containing the byte length of period|version|name
+// headerlength is a 16 bit value containing the byte length of period|version|rootAddr|metaHash
 package mru