fix xsrf and added nonce

vendor/go.etcd.io/bbolt/bucket.go

@@ -4,6 +4,9 @@ import (
 	"bytes"
 	"fmt"
 	"unsafe"
+
+	"go.etcd.io/bbolt/errors"
+	"go.etcd.io/bbolt/internal/common"
 )
 
 const (
@@ -14,8 +17,6 @@ const (
 	MaxValueSize = (1 << 31) - 2
 )
 
-const bucketHeaderSize = int(unsafe.Sizeof(bucket{}))
-
 const (
 	minFillPercent = 0.1
 	maxFillPercent = 1.0
@@ -27,12 +28,12 @@ const DefaultFillPercent = 0.5
 
 // Bucket represents a collection of key/value pairs inside the database.
 type Bucket struct {
-	*bucket
-	tx       *Tx                // the associated transaction
-	buckets  map[string]*Bucket // subbucket cache
-	page     *page              // inline page reference
-	rootNode *node              // materialized node for the root page.
-	nodes    map[pgid]*node     // node cache
+	*common.InBucket
+	tx       *Tx                   // the associated transaction
+	buckets  map[string]*Bucket    // subbucket cache
+	page     *common.Page          // inline page reference
+	rootNode *node                 // materialized node for the root page.
+	nodes    map[common.Pgid]*node // node cache
 
 	// Sets the threshold for filling nodes when they split. By default,
 	// the bucket will fill to 50% but it can be useful to increase this
@@ -42,21 +43,12 @@ type Bucket struct {
 	FillPercent float64
 }
 
-// bucket represents the on-file representation of a bucket.
-// This is stored as the "value" of a bucket key. If the bucket is small enough,
-// then its root page can be stored inline in the "value", after the bucket
-// header. In the case of inline buckets, the "root" will be 0.
-type bucket struct {
-	root     pgid   // page id of the bucket's root-level page
-	sequence uint64 // monotonically incrementing, used by NextSequence()
-}
-
 // newBucket returns a new bucket associated with a transaction.
 func newBucket(tx *Tx) Bucket {
 	var b = Bucket{tx: tx, FillPercent: DefaultFillPercent}
 	if tx.writable {
 		b.buckets = make(map[string]*Bucket)
-		b.nodes = make(map[pgid]*node)
+		b.nodes = make(map[common.Pgid]*node)
 	}
 	return b
 }
@@ -67,8 +59,8 @@ func (b *Bucket) Tx() *Tx {
 }
 
 // Root returns the root of the bucket.
-func (b *Bucket) Root() pgid {
-	return b.root
+func (b *Bucket) Root() common.Pgid {
+	return b.RootPage()
 }
 
 // Writable returns whether the bucket is writable.
@@ -105,7 +97,7 @@ func (b *Bucket) Bucket(name []byte) *Bucket {
 	k, v, flags := c.seek(name)
 
 	// Return nil if the key doesn't exist or it is not a bucket.
-	if !bytes.Equal(name, k) || (flags&bucketLeafFlag) == 0 {
+	if !bytes.Equal(name, k) || (flags&common.BucketLeafFlag) == 0 {
 		return nil
 	}
 
@@ -125,8 +117,8 @@ func (b *Bucket) openBucket(value []byte) *Bucket {
 
 	// Unaligned access requires a copy to be made.
 	const unalignedMask = unsafe.Alignof(struct {
-		bucket
-		page
+		common.InBucket
+		common.Page
 	}{}) - 1
 	unaligned := uintptr(unsafe.Pointer(&value[0]))&unalignedMask != 0
 	if unaligned {
@@ -136,15 +128,15 @@ func (b *Bucket) openBucket(value []byte) *Bucket {
 	// If this is a writable transaction then we need to copy the bucket entry.
 	// Read-only transactions can point directly at the mmap entry.
 	if b.tx.writable && !unaligned {
-		child.bucket = &bucket{}
-		*child.bucket = *(*bucket)(unsafe.Pointer(&value[0]))
+		child.InBucket = &common.InBucket{}
+		*child.InBucket = *(*common.InBucket)(unsafe.Pointer(&value[0]))
 	} else {
-		child.bucket = (*bucket)(unsafe.Pointer(&value[0]))
+		child.InBucket = (*common.InBucket)(unsafe.Pointer(&value[0]))
 	}
 
 	// Save a reference to the inline page if the bucket is inline.
-	if child.root == 0 {
-		child.page = (*page)(unsafe.Pointer(&value[bucketHeaderSize]))
+	if child.RootPage() == 0 {
+		child.page = (*common.Page)(unsafe.Pointer(&value[common.BucketHeaderSize]))
 	}
 
 	return &child
@@ -153,13 +145,23 @@ func (b *Bucket) openBucket(value []byte) *Bucket {
 // CreateBucket creates a new bucket at the given key and returns the new bucket.
 // Returns an error if the key already exists, if the bucket name is blank, or if the bucket name is too long.
 // The bucket instance is only valid for the lifetime of the transaction.
-func (b *Bucket) CreateBucket(key []byte) (*Bucket, error) {
+func (b *Bucket) CreateBucket(key []byte) (rb *Bucket, err error) {
+	if lg := b.tx.db.Logger(); lg != discardLogger {
+		lg.Debugf("Creating bucket %q", key)
+		defer func() {
+			if err != nil {
+				lg.Errorf("Creating bucket %q failed: %v", key, err)
+			} else {
+				lg.Debugf("Creating bucket %q successfully", key)
+			}
+		}()
+	}
 	if b.tx.db == nil {
-		return nil, ErrTxClosed
+		return nil, errors.ErrTxClosed
 	} else if !b.tx.writable {
-		return nil, ErrTxNotWritable
+		return nil, errors.ErrTxNotWritable
 	} else if len(key) == 0 {
-		return nil, ErrBucketNameRequired
+		return nil, errors.ErrBucketNameRequired
 	}
 
 	// Insert into node.
@@ -173,21 +175,21 @@ func (b *Bucket) CreateBucket(key []byte) (*Bucket, error) {
 
 	// Return an error if there is an existing key.
 	if bytes.Equal(newKey, k) {
-		if (flags & bucketLeafFlag) != 0 {
-			return nil, ErrBucketExists
+		if (flags & common.BucketLeafFlag) != 0 {
+			return nil, errors.ErrBucketExists
 		}
-		return nil, ErrIncompatibleValue
+		return nil, errors.ErrIncompatibleValue
 	}
 
 	// Create empty, inline bucket.
 	var bucket = Bucket{
-		bucket:      &bucket{},
+		InBucket:    &common.InBucket{},
 		rootNode:    &node{isLeaf: true},
 		FillPercent: DefaultFillPercent,
 	}
 	var value = bucket.write()
 
-	c.node().put(newKey, newKey, value, 0, bucketLeafFlag)
+	c.node().put(newKey, newKey, value, 0, common.BucketLeafFlag)
 
 	// Since subbuckets are not allowed on inline buckets, we need to
 	// dereference the inline page, if it exists. This will cause the bucket
@@ -200,39 +202,108 @@ func (b *Bucket) CreateBucket(key []byte) (*Bucket, error) {
 // CreateBucketIfNotExists creates a new bucket if it doesn't already exist and returns a reference to it.
 // Returns an error if the bucket name is blank, or if the bucket name is too long.
 // The bucket instance is only valid for the lifetime of the transaction.
-func (b *Bucket) CreateBucketIfNotExists(key []byte) (*Bucket, error) {
-	child, err := b.CreateBucket(key)
-	if err == ErrBucketExists {
-		return b.Bucket(key), nil
-	} else if err != nil {
-		return nil, err
+func (b *Bucket) CreateBucketIfNotExists(key []byte) (rb *Bucket, err error) {
+	if lg := b.tx.db.Logger(); lg != discardLogger {
+		lg.Debugf("Creating bucket if not exist %q", key)
+		defer func() {
+			if err != nil {
+				lg.Errorf("Creating bucket if not exist %q failed: %v", key, err)
+			} else {
+				lg.Debugf("Creating bucket if not exist %q successfully", key)
+			}
+		}()
 	}
-	return child, nil
-}
 
-// DeleteBucket deletes a bucket at the given key.
-// Returns an error if the bucket does not exist, or if the key represents a non-bucket value.
-func (b *Bucket) DeleteBucket(key []byte) error {
 	if b.tx.db == nil {
-		return ErrTxClosed
-	} else if !b.Writable() {
-		return ErrTxNotWritable
+		return nil, errors.ErrTxClosed
+	} else if !b.tx.writable {
+		return nil, errors.ErrTxNotWritable
+	} else if len(key) == 0 {
+		return nil, errors.ErrBucketNameRequired
+	}
+
+	// Insert into node.
+	// Tip: Use a new variable `newKey` instead of reusing the existing `key` to prevent
+	// it from being marked as leaking, and accordingly cannot be allocated on stack.
+	newKey := cloneBytes(key)
+
+	if b.buckets != nil {
+		if child := b.buckets[string(newKey)]; child != nil {
+			return child, nil
+		}
 	}
 
 	// Move cursor to correct position.
 	c := b.Cursor()
-	k, _, flags := c.seek(key)
+	k, v, flags := c.seek(newKey)
+
+	// Return an error if there is an existing non-bucket key.
+	if bytes.Equal(newKey, k) {
+		if (flags & common.BucketLeafFlag) != 0 {
+			var child = b.openBucket(v)
+			if b.buckets != nil {
+				b.buckets[string(newKey)] = child
+			}
+
+			return child, nil
+		}
+		return nil, errors.ErrIncompatibleValue
+	}
+
+	// Create empty, inline bucket.
+	var bucket = Bucket{
+		InBucket:    &common.InBucket{},
+		rootNode:    &node{isLeaf: true},
+		FillPercent: DefaultFillPercent,
+	}
+	var value = bucket.write()
+
+	c.node().put(newKey, newKey, value, 0, common.BucketLeafFlag)
+
+	// Since subbuckets are not allowed on inline buckets, we need to
+	// dereference the inline page, if it exists. This will cause the bucket
+	// to be treated as a regular, non-inline bucket for the rest of the tx.
+	b.page = nil
+
+	return b.Bucket(newKey), nil
+}
+
+// DeleteBucket deletes a bucket at the given key.
+// Returns an error if the bucket does not exist, or if the key represents a non-bucket value.
+func (b *Bucket) DeleteBucket(key []byte) (err error) {
+	if lg := b.tx.db.Logger(); lg != discardLogger {
+		lg.Debugf("Deleting bucket %q", key)
+		defer func() {
+			if err != nil {
+				lg.Errorf("Deleting bucket %q failed: %v", key, err)
+			} else {
+				lg.Debugf("Deleting bucket %q successfully", key)
+			}
+		}()
+	}
+
+	if b.tx.db == nil {
+		return errors.ErrTxClosed
+	} else if !b.Writable() {
+		return errors.ErrTxNotWritable
+	}
+
+	newKey := cloneBytes(key)
+
+	// Move cursor to correct position.
+	c := b.Cursor()
+	k, _, flags := c.seek(newKey)
 
 	// Return an error if bucket doesn't exist or is not a bucket.
-	if !bytes.Equal(key, k) {
-		return ErrBucketNotFound
-	} else if (flags & bucketLeafFlag) == 0 {
-		return ErrIncompatibleValue
+	if !bytes.Equal(newKey, k) {
+		return errors.ErrBucketNotFound
+	} else if (flags & common.BucketLeafFlag) == 0 {
+		return errors.ErrIncompatibleValue
 	}
 
 	// Recursively delete all child buckets.
-	child := b.Bucket(key)
-	err := child.ForEachBucket(func(k []byte) error {
+	child := b.Bucket(newKey)
+	err = child.ForEachBucket(func(k []byte) error {
 		if err := child.DeleteBucket(k); err != nil {
 			return fmt.Errorf("delete bucket: %s", err)
 		}
@@ -243,7 +314,7 @@ func (b *Bucket) DeleteBucket(key []byte) error {
 	}
 
 	// Remove cached copy.
-	delete(b.buckets, string(key))
+	delete(b.buckets, string(newKey))
 
 	// Release all bucket pages to freelist.
 	child.nodes = nil
@@ -251,19 +322,119 @@ func (b *Bucket) DeleteBucket(key []byte) error {
 	child.free()
 
 	// Delete the node if we have a matching key.
-	c.node().del(key)
+	c.node().del(newKey)
 
 	return nil
 }
 
+// MoveBucket moves a sub-bucket from the source bucket to the destination bucket.
+// Returns an error if
+//  1. the sub-bucket cannot be found in the source bucket;
+//  2. or the key already exists in the destination bucket;
+//  3. or the key represents a non-bucket value;
+//  4. the source and destination buckets are the same.
+func (b *Bucket) MoveBucket(key []byte, dstBucket *Bucket) (err error) {
+	lg := b.tx.db.Logger()
+	if lg != discardLogger {
+		lg.Debugf("Moving bucket %q", key)
+		defer func() {
+			if err != nil {
+				lg.Errorf("Moving bucket %q failed: %v", key, err)
+			} else {
+				lg.Debugf("Moving bucket %q successfully", key)
+			}
+		}()
+	}
+
+	if b.tx.db == nil || dstBucket.tx.db == nil {
+		return errors.ErrTxClosed
+	} else if !b.Writable() || !dstBucket.Writable() {
+		return errors.ErrTxNotWritable
+	}
+
+	if b.tx.db.Path() != dstBucket.tx.db.Path() || b.tx != dstBucket.tx {
+		lg.Errorf("The source and target buckets are not in the same db file, source bucket in %s and target bucket in %s", b.tx.db.Path(), dstBucket.tx.db.Path())
+		return errors.ErrDifferentDB
+	}
+
+	newKey := cloneBytes(key)
+
+	// Move cursor to correct position.
+	c := b.Cursor()
+	k, v, flags := c.seek(newKey)
+
+	// Return an error if bucket doesn't exist or is not a bucket.
+	if !bytes.Equal(newKey, k) {
+		return errors.ErrBucketNotFound
+	} else if (flags & common.BucketLeafFlag) == 0 {
+		lg.Errorf("An incompatible key %s exists in the source bucket", newKey)
+		return errors.ErrIncompatibleValue
+	}
+
+	// Do nothing (return true directly) if the source bucket and the
+	// destination bucket are actually the same bucket.
+	if b == dstBucket || (b.RootPage() == dstBucket.RootPage() && b.RootPage() != 0) {
+		lg.Errorf("The source bucket (%s) and the target bucket (%s) are the same bucket", b, dstBucket)
+		return errors.ErrSameBuckets
+	}
+
+	// check whether the key already exists in the destination bucket
+	curDst := dstBucket.Cursor()
+	k, _, flags = curDst.seek(newKey)
+
+	// Return an error if there is an existing key in the destination bucket.
+	if bytes.Equal(newKey, k) {
+		if (flags & common.BucketLeafFlag) != 0 {
+			return errors.ErrBucketExists
+		}
+		lg.Errorf("An incompatible key %s exists in the target bucket", newKey)
+		return errors.ErrIncompatibleValue
+	}
+
+	// remove the sub-bucket from the source bucket
+	delete(b.buckets, string(newKey))
+	c.node().del(newKey)
+
+	// add te sub-bucket to the destination bucket
+	newValue := cloneBytes(v)
+	curDst.node().put(newKey, newKey, newValue, 0, common.BucketLeafFlag)
+
+	return nil
+}
+
+// Inspect returns the structure of the bucket.
+func (b *Bucket) Inspect() BucketStructure {
+	return b.recursivelyInspect([]byte("root"))
+}
+
+func (b *Bucket) recursivelyInspect(name []byte) BucketStructure {
+	bs := BucketStructure{Name: string(name)}
+
+	keyN := 0
+	c := b.Cursor()
+	for k, _, flags := c.first(); k != nil; k, _, flags = c.next() {
+		if flags&common.BucketLeafFlag != 0 {
+			childBucket := b.Bucket(k)
+			childBS := childBucket.recursivelyInspect(k)
+			bs.Children = append(bs.Children, childBS)
+		} else {
+			keyN++
+		}
+	}
+	bs.KeyN = keyN
+
+	return bs
+}
+
 // Get retrieves the value for a key in the bucket.
 // Returns a nil value if the key does not exist or if the key is a nested bucket.
 // The returned value is only valid for the life of the transaction.
+// The returned memory is owned by bbolt and must never be modified; writing to this memory might corrupt the database.
 func (b *Bucket) Get(key []byte) []byte {
 	k, v, flags := b.Cursor().seek(key)
 
 	// Return nil if this is a bucket.
-	if (flags & bucketLeafFlag) != 0 {
+	if (flags & common.BucketLeafFlag) != 0 {
 		return nil
 	}
 
@@ -278,17 +449,27 @@ func (b *Bucket) Get(key []byte) []byte {
 // If the key exist then its previous value will be overwritten.
 // Supplied value must remain valid for the life of the transaction.
 // Returns an error if the bucket was created from a read-only transaction, if the key is blank, if the key is too large, or if the value is too large.
-func (b *Bucket) Put(key []byte, value []byte) error {
+func (b *Bucket) Put(key []byte, value []byte) (err error) {
+	if lg := b.tx.db.Logger(); lg != discardLogger {
+		lg.Debugf("Putting key %q", key)
+		defer func() {
+			if err != nil {
+				lg.Errorf("Putting key %q failed: %v", key, err)
+			} else {
+				lg.Debugf("Putting key %q successfully", key)
+			}
+		}()
+	}
 	if b.tx.db == nil {
-		return ErrTxClosed
+		return errors.ErrTxClosed
 	} else if !b.Writable() {
-		return ErrTxNotWritable
+		return errors.ErrTxNotWritable
 	} else if len(key) == 0 {
-		return ErrKeyRequired
+		return errors.ErrKeyRequired
 	} else if len(key) > MaxKeySize {
-		return ErrKeyTooLarge
+		return errors.ErrKeyTooLarge
 	} else if int64(len(value)) > MaxValueSize {
-		return ErrValueTooLarge
+		return errors.ErrValueTooLarge
 	}
 
 	// Insert into node.
@@ -301,8 +482,8 @@ func (b *Bucket) Put(key []byte, value []byte) error {
 	k, _, flags := c.seek(newKey)
 
 	// Return an error if there is an existing key with a bucket value.
-	if bytes.Equal(newKey, k) && (flags&bucketLeafFlag) != 0 {
-		return ErrIncompatibleValue
+	if bytes.Equal(newKey, k) && (flags&common.BucketLeafFlag) != 0 {
+		return errors.ErrIncompatibleValue
 	}
 
 	// gofail: var beforeBucketPut struct{}
@@ -315,11 +496,22 @@ func (b *Bucket) Put(key []byte, value []byte) error {
 // Delete removes a key from the bucket.
 // If the key does not exist then nothing is done and a nil error is returned.
 // Returns an error if the bucket was created from a read-only transaction.
-func (b *Bucket) Delete(key []byte) error {
+func (b *Bucket) Delete(key []byte) (err error) {
+	if lg := b.tx.db.Logger(); lg != discardLogger {
+		lg.Debugf("Deleting key %q", key)
+		defer func() {
+			if err != nil {
+				lg.Errorf("Deleting key %q failed: %v", key, err)
+			} else {
+				lg.Debugf("Deleting key %q successfully", key)
+			}
+		}()
+	}
+
 	if b.tx.db == nil {
-		return ErrTxClosed
+		return errors.ErrTxClosed
 	} else if !b.Writable() {
-		return ErrTxNotWritable
+		return errors.ErrTxNotWritable
 	}
 
 	// Move cursor to correct position.
@@ -332,8 +524,8 @@ func (b *Bucket) Delete(key []byte) error {
 	}
 
 	// Return an error if there is already existing bucket value.
-	if (flags & bucketLeafFlag) != 0 {
-		return ErrIncompatibleValue
+	if (flags & common.BucketLeafFlag) != 0 {
+		return errors.ErrIncompatibleValue
 	}
 
 	// Delete the node if we have a matching key.
@@ -343,44 +535,46 @@ func (b *Bucket) Delete(key []byte) error {
 }
 
 // Sequence returns the current integer for the bucket without incrementing it.
-func (b *Bucket) Sequence() uint64 { return b.bucket.sequence }
+func (b *Bucket) Sequence() uint64 {
+	return b.InSequence()
+}
 
 // SetSequence updates the sequence number for the bucket.
 func (b *Bucket) SetSequence(v uint64) error {
 	if b.tx.db == nil {
-		return ErrTxClosed
+		return errors.ErrTxClosed
 	} else if !b.Writable() {
-		return ErrTxNotWritable
+		return errors.ErrTxNotWritable
 	}
 
 	// Materialize the root node if it hasn't been already so that the
 	// bucket will be saved during commit.
 	if b.rootNode == nil {
-		_ = b.node(b.root, nil)
+		_ = b.node(b.RootPage(), nil)
 	}
 
 	// Set the sequence.
-	b.bucket.sequence = v
+	b.SetInSequence(v)
 	return nil
 }
 
 // NextSequence returns an autoincrementing integer for the bucket.
 func (b *Bucket) NextSequence() (uint64, error) {
 	if b.tx.db == nil {
-		return 0, ErrTxClosed
+		return 0, errors.ErrTxClosed
 	} else if !b.Writable() {
-		return 0, ErrTxNotWritable
+		return 0, errors.ErrTxNotWritable
 	}
 
 	// Materialize the root node if it hasn't been already so that the
 	// bucket will be saved during commit.
 	if b.rootNode == nil {
-		_ = b.node(b.root, nil)
+		_ = b.node(b.RootPage(), nil)
 	}
 
 	// Increment and return the sequence.
-	b.bucket.sequence++
-	return b.bucket.sequence, nil
+	b.IncSequence()
+	return b.Sequence(), nil
 }
 
 // ForEach executes a function for each key/value pair in a bucket.
@@ -390,7 +584,7 @@ func (b *Bucket) NextSequence() (uint64, error) {
 // the bucket; this will result in undefined behavior.
 func (b *Bucket) ForEach(fn func(k, v []byte) error) error {
 	if b.tx.db == nil {
-		return ErrTxClosed
+		return errors.ErrTxClosed
 	}
 	c := b.Cursor()
 	for k, v := c.First(); k != nil; k, v = c.Next() {
@@ -403,11 +597,11 @@ func (b *Bucket) ForEach(fn func(k, v []byte) error) error {
 
 func (b *Bucket) ForEachBucket(fn func(k []byte) error) error {
 	if b.tx.db == nil {
-		return ErrTxClosed
+		return errors.ErrTxClosed
 	}
 	c := b.Cursor()
 	for k, _, flags := c.first(); k != nil; k, _, flags = c.next() {
-		if flags&bucketLeafFlag != 0 {
+		if flags&common.BucketLeafFlag != 0 {
 			if err := fn(k); err != nil {
 				return err
 			}
@@ -421,64 +615,64 @@ func (b *Bucket) Stats() BucketStats {
 	var s, subStats BucketStats
 	pageSize := b.tx.db.pageSize
 	s.BucketN += 1
-	if b.root == 0 {
+	if b.RootPage() == 0 {
 		s.InlineBucketN += 1
 	}
-	b.forEachPage(func(p *page, depth int, pgstack []pgid) {
-		if (p.flags & leafPageFlag) != 0 {
-			s.KeyN += int(p.count)
+	b.forEachPage(func(p *common.Page, depth int, pgstack []common.Pgid) {
+		if p.IsLeafPage() {
+			s.KeyN += int(p.Count())
 
 			// used totals the used bytes for the page
-			used := pageHeaderSize
+			used := common.PageHeaderSize
 
-			if p.count != 0 {
+			if p.Count() != 0 {
 				// If page has any elements, add all element headers.
-				used += leafPageElementSize * uintptr(p.count-1)
+				used += common.LeafPageElementSize * uintptr(p.Count()-1)
 
 				// Add all element key, value sizes.
 				// The computation takes advantage of the fact that the position
 				// of the last element's key/value equals to the total of the sizes
 				// of all previous elements' keys and values.
 				// It also includes the last element's header.
-				lastElement := p.leafPageElement(p.count - 1)
-				used += uintptr(lastElement.pos + lastElement.ksize + lastElement.vsize)
+				lastElement := p.LeafPageElement(p.Count() - 1)
+				used += uintptr(lastElement.Pos() + lastElement.Ksize() + lastElement.Vsize())
 			}
 
-			if b.root == 0 {
+			if b.RootPage() == 0 {
 				// For inlined bucket just update the inline stats
 				s.InlineBucketInuse += int(used)
 			} else {
 				// For non-inlined bucket update all the leaf stats
 				s.LeafPageN++
 				s.LeafInuse += int(used)
-				s.LeafOverflowN += int(p.overflow)
+				s.LeafOverflowN += int(p.Overflow())
 
 				// Collect stats from sub-buckets.
 				// Do that by iterating over all element headers
 				// looking for the ones with the bucketLeafFlag.
-				for i := uint16(0); i < p.count; i++ {
-					e := p.leafPageElement(i)
-					if (e.flags & bucketLeafFlag) != 0 {
+				for i := uint16(0); i < p.Count(); i++ {
+					e := p.LeafPageElement(i)
+					if (e.Flags() & common.BucketLeafFlag) != 0 {
 						// For any bucket element, open the element value
 						// and recursively call Stats on the contained bucket.
-						subStats.Add(b.openBucket(e.value()).Stats())
+						subStats.Add(b.openBucket(e.Value()).Stats())
 					}
 				}
 			}
-		} else if (p.flags & branchPageFlag) != 0 {
+		} else if p.IsBranchPage() {
 			s.BranchPageN++
-			lastElement := p.branchPageElement(p.count - 1)
+			lastElement := p.BranchPageElement(p.Count() - 1)
 
 			// used totals the used bytes for the page
 			// Add header and all element headers.
-			used := pageHeaderSize + (branchPageElementSize * uintptr(p.count-1))
+			used := common.PageHeaderSize + (common.BranchPageElementSize * uintptr(p.Count()-1))
 
 			// Add size of all keys and values.
 			// Again, use the fact that last element's position equals to
 			// the total of key, value sizes of all previous elements.
-			used += uintptr(lastElement.pos + lastElement.ksize)
+			used += uintptr(lastElement.Pos() + lastElement.Ksize())
 			s.BranchInuse += int(used)
-			s.BranchOverflowN += int(p.overflow)
+			s.BranchOverflowN += int(p.Overflow())
 		}
 
 		// Keep track of maximum page depth.
@@ -499,29 +693,29 @@ func (b *Bucket) Stats() BucketStats {
 }
 
 // forEachPage iterates over every page in a bucket, including inline pages.
-func (b *Bucket) forEachPage(fn func(*page, int, []pgid)) {
+func (b *Bucket) forEachPage(fn func(*common.Page, int, []common.Pgid)) {
 	// If we have an inline page then just use that.
 	if b.page != nil {
-		fn(b.page, 0, []pgid{b.root})
+		fn(b.page, 0, []common.Pgid{b.RootPage()})
 		return
 	}
 
 	// Otherwise traverse the page hierarchy.
-	b.tx.forEachPage(b.root, fn)
+	b.tx.forEachPage(b.RootPage(), fn)
 }
 
 // forEachPageNode iterates over every page (or node) in a bucket.
 // This also includes inline pages.
-func (b *Bucket) forEachPageNode(fn func(*page, *node, int)) {
+func (b *Bucket) forEachPageNode(fn func(*common.Page, *node, int)) {
 	// If we have an inline page or root node then just use that.
 	if b.page != nil {
 		fn(b.page, nil, 0)
 		return
 	}
-	b._forEachPageNode(b.root, 0, fn)
+	b._forEachPageNode(b.RootPage(), 0, fn)
 }
 
-func (b *Bucket) _forEachPageNode(pgId pgid, depth int, fn func(*page, *node, int)) {
+func (b *Bucket) _forEachPageNode(pgId common.Pgid, depth int, fn func(*common.Page, *node, int)) {
 	var p, n = b.pageNode(pgId)
 
 	// Execute function.
@@ -529,16 +723,16 @@ func (b *Bucket) _forEachPageNode(pgId pgid, depth int, fn func(*page, *node, in
 
 	// Recursively loop over children.
 	if p != nil {
-		if (p.flags & branchPageFlag) != 0 {
-			for i := 0; i < int(p.count); i++ {
-				elem := p.branchPageElement(uint16(i))
-				b._forEachPageNode(elem.pgid, depth+1, fn)
+		if p.IsBranchPage() {
+			for i := 0; i < int(p.Count()); i++ {
+				elem := p.BranchPageElement(uint16(i))
+				b._forEachPageNode(elem.Pgid(), depth+1, fn)
 			}
 		}
 	} else {
 		if !n.isLeaf {
 			for _, inode := range n.inodes {
-				b._forEachPageNode(inode.pgid, depth+1, fn)
+				b._forEachPageNode(inode.Pgid(), depth+1, fn)
 			}
 		}
 	}
@@ -561,9 +755,9 @@ func (b *Bucket) spill() error {
 			}
 
 			// Update the child bucket header in this bucket.
-			value = make([]byte, unsafe.Sizeof(bucket{}))
-			var bucket = (*bucket)(unsafe.Pointer(&value[0]))
-			*bucket = *child.bucket
+			value = make([]byte, unsafe.Sizeof(common.InBucket{}))
+			var bucket = (*common.InBucket)(unsafe.Pointer(&value[0]))
+			*bucket = *child.InBucket
 		}
 
 		// Skip writing the bucket if there are no materialized nodes.
@@ -577,10 +771,10 @@ func (b *Bucket) spill() error {
 		if !bytes.Equal([]byte(name), k) {
 			panic(fmt.Sprintf("misplaced bucket header: %x -> %x", []byte(name), k))
 		}
-		if flags&bucketLeafFlag == 0 {
+		if flags&common.BucketLeafFlag == 0 {
 			panic(fmt.Sprintf("unexpected bucket header flag: %x", flags))
 		}
-		c.node().put([]byte(name), []byte(name), value, 0, bucketLeafFlag)
+		c.node().put([]byte(name), []byte(name), value, 0, common.BucketLeafFlag)
 	}
 
 	// Ignore if there's not a materialized root node.
@@ -595,16 +789,16 @@ func (b *Bucket) spill() error {
 	b.rootNode = b.rootNode.root()
 
 	// Update the root node for this bucket.
-	if b.rootNode.pgid >= b.tx.meta.pgid {
-		panic(fmt.Sprintf("pgid (%d) above high water mark (%d)", b.rootNode.pgid, b.tx.meta.pgid))
+	if b.rootNode.pgid >= b.tx.meta.Pgid() {
+		panic(fmt.Sprintf("pgid (%d) above high water mark (%d)", b.rootNode.pgid, b.tx.meta.Pgid()))
 	}
-	b.root = b.rootNode.pgid
+	b.SetRootPage(b.rootNode.pgid)
 
 	return nil
 }
 
 // inlineable returns true if a bucket is small enough to be written inline
-// and if it contains no subbuckets. Otherwise returns false.
+// and if it contains no subbuckets. Otherwise, returns false.
 func (b *Bucket) inlineable() bool {
 	var n = b.rootNode
 
@@ -615,11 +809,11 @@ func (b *Bucket) inlineable() bool {
 
 	// Bucket is not inlineable if it contains subbuckets or if it goes beyond
 	// our threshold for inline bucket size.
-	var size = pageHeaderSize
+	var size = common.PageHeaderSize
 	for _, inode := range n.inodes {
-		size += leafPageElementSize + uintptr(len(inode.key)) + uintptr(len(inode.value))
+		size += common.LeafPageElementSize + uintptr(len(inode.Key())) + uintptr(len(inode.Value()))
 
-		if inode.flags&bucketLeafFlag != 0 {
+		if inode.Flags()&common.BucketLeafFlag != 0 {
 			return false
 		} else if size > b.maxInlineBucketSize() {
 			return false
@@ -638,14 +832,14 @@ func (b *Bucket) maxInlineBucketSize() uintptr {
 func (b *Bucket) write() []byte {
 	// Allocate the appropriate size.
 	var n = b.rootNode
-	var value = make([]byte, bucketHeaderSize+n.size())
+	var value = make([]byte, common.BucketHeaderSize+n.size())
 
 	// Write a bucket header.
-	var bucket = (*bucket)(unsafe.Pointer(&value[0]))
-	*bucket = *b.bucket
+	var bucket = (*common.InBucket)(unsafe.Pointer(&value[0]))
+	*bucket = *b.InBucket
 
 	// Convert byte slice to a fake page and write the root node.
-	var p = (*page)(unsafe.Pointer(&value[bucketHeaderSize]))
+	var p = (*common.Page)(unsafe.Pointer(&value[common.BucketHeaderSize]))
 	n.write(p)
 
 	return value
@@ -662,8 +856,8 @@ func (b *Bucket) rebalance() {
 }
 
 // node creates a node from a page and associates it with a given parent.
-func (b *Bucket) node(pgId pgid, parent *node) *node {
-	_assert(b.nodes != nil, "nodes map expected")
+func (b *Bucket) node(pgId common.Pgid, parent *node) *node {
+	common.Assert(b.nodes != nil, "nodes map expected")
 
 	// Retrieve node if it's already been created.
 	if n := b.nodes[pgId]; n != nil {
@@ -682,6 +876,12 @@ func (b *Bucket) node(pgId pgid, parent *node) *node {
 	var p = b.page
 	if p == nil {
 		p = b.tx.page(pgId)
+	} else {
+		// if p isn't nil, then it's an inline bucket.
+		// The pgId must be 0 in this case.
+		common.Verify(func() {
+			common.Assert(pgId == 0, "The page ID (%d) isn't 0 for an inline bucket", pgId)
+		})
 	}
 
 	// Read the page into the node and cache it.
@@ -696,19 +896,19 @@ func (b *Bucket) node(pgId pgid, parent *node) *node {
 
 // free recursively frees all pages in the bucket.
 func (b *Bucket) free() {
-	if b.root == 0 {
+	if b.RootPage() == 0 {
 		return
 	}
 
 	var tx = b.tx
-	b.forEachPageNode(func(p *page, n *node, _ int) {
+	b.forEachPageNode(func(p *common.Page, n *node, _ int) {
 		if p != nil {
-			tx.db.freelist.free(tx.meta.txid, p)
+			tx.db.freelist.Free(tx.meta.Txid(), p)
 		} else {
 			n.free()
 		}
 	})
-	b.root = 0
+	b.SetRootPage(0)
 }
 
 // dereference removes all references to the old mmap.
@@ -723,11 +923,11 @@ func (b *Bucket) dereference() {
 }
 
 // pageNode returns the in-memory node, if it exists.
-// Otherwise returns the underlying page.
-func (b *Bucket) pageNode(id pgid) (*page, *node) {
+// Otherwise, returns the underlying page.
+func (b *Bucket) pageNode(id common.Pgid) (*common.Page, *node) {
 	// Inline buckets have a fake page embedded in their value so treat them
 	// differently. We'll return the rootNode (if available) or the fake page.
-	if b.root == 0 {
+	if b.RootPage() == 0 {
 		if id != 0 {
 			panic(fmt.Sprintf("inline bucket non-zero page access(2): %d != 0", id))
 		}
@@ -797,3 +997,9 @@ func cloneBytes(v []byte) []byte {
 	copy(clone, v)
 	return clone
 }
+
+type BucketStructure struct {
+	Name     string            `json:"name"`              // name of the bucket
+	KeyN     int               `json:"keyN"`              // number of key/value pairs
+	Children []BucketStructure `json:"buckets,omitempty"` // child buckets
+}