storage: transactional, package documentation

mcuadros · mcuadros · commit 96317743391a · 2019-02-02T10:14:24.000+01:00
Signed-off-by: Máximo Cuadros &lt;mcuadros@gmail.com&gt;
diff --git a/storage/transactional/config.go b/storage/transactional/config.go
@@ -2,17 +2,21 @@ package transactional
 
 import "gopkg.in/src-d/go-git.v4/config"
 
+// ConfigStorage implements the storer.ConfigStorage for the transactional package.
 type ConfigStorage struct {
 	config.ConfigStorer
 	temporal config.ConfigStorer
 
 	set bool
 }
 
+// NewConfigStorage returns a new ConfigStorer based on a base storer and a
+// temporal storer.
 func NewConfigStorage(s, temporal config.ConfigStorer) *ConfigStorage {
 	return &ConfigStorage{ConfigStorer: s, temporal: temporal}
 }
 
+// SetConfig honors the storer.ConfigStorer interface.
 func (c *ConfigStorage) SetConfig(cfg *config.Config) error {
 	if err := c.temporal.SetConfig(cfg); err != nil {
 		return err
@@ -22,6 +26,7 @@ func (c *ConfigStorage) SetConfig(cfg *config.Config) error {
 	return nil
 }
 
+// Config honors the storer.ConfigStorer interface.
 func (c *ConfigStorage) Config() (*config.Config, error) {
 	if !c.set {
 		return c.ConfigStorer.Config()
@@ -30,6 +35,7 @@ func (c *ConfigStorage) Config() (*config.Config, error) {
 	return c.temporal.Config()
 }
 
+// Commit it copies the config from the temporal storage into the base storage.
 func (c *ConfigStorage) Commit() error {
 	if !c.set {
 		return nil
diff --git a/storage/transactional/doc.go b/storage/transactional/doc.go
@@ -0,0 +1,7 @@
+// Package transactional is a transactional implementation of git.Storer, it
+// demux the write and read operation of two separate storers, allowing to merge
+// content calling Storage.Commit.
+//
+// The API and functionality of this package are considered EXPERIMENTAL and is
+// not considered stable nor production ready.
+package transactional
diff --git a/storage/transactional/index.go b/storage/transactional/index.go
@@ -5,20 +5,24 @@ import (
 	"gopkg.in/src-d/go-git.v4/plumbing/storer"
 )
 
+// IndexStorage implements the storer.IndexStorage for the transactional package.
 type IndexStorage struct {
 	storer.IndexStorer
 	temporal storer.IndexStorer
 
 	set bool
 }
 
+// NewIndexStorage returns a new IndexStorer based on a base storer and a
+// temporal storer.
 func NewIndexStorage(s, temporal storer.IndexStorer) *IndexStorage {
 	return &IndexStorage{
 		IndexStorer: s,
 		temporal:    temporal,
 	}
 }
 
+// SetIndex honors the storer.IndexStorer interface.
 func (s *IndexStorage) SetIndex(idx *index.Index) (err error) {
 	if err := s.temporal.SetIndex(idx); err != nil {
 		return err
@@ -28,6 +32,7 @@ func (s *IndexStorage) SetIndex(idx *index.Index) (err error) {
 	return nil
 }
 
+// Index honors the storer.IndexStorer interface.
 func (s *IndexStorage) Index() (*index.Index, error) {
 	if !s.set {
 		return s.IndexStorer.Index()
@@ -36,15 +41,16 @@ func (s *IndexStorage) Index() (*index.Index, error) {
 	return s.temporal.Index()
 }
 
-func (c *IndexStorage) Commit() error {
-	if !c.set {
+// Commit it copies the index from the temporal storage into the base storage.
+func (s *IndexStorage) Commit() error {
+	if !s.set {
 		return nil
 	}
 
-	idx, err := c.temporal.Index()
+	idx, err := s.temporal.Index()
 	if err != nil {
 		return err
 	}
 
-	return c.IndexStorer.SetIndex(idx)
+	return s.IndexStorer.SetIndex(idx)
 }
diff --git a/storage/transactional/module.go b/storage/transactional/module.go
diff --git a/storage/transactional/object.go b/storage/transactional/object.go
@@ -5,19 +5,24 @@ import (
 	"gopkg.in/src-d/go-git.v4/plumbing/storer"
 )
 
+// ObjectStorage implements the storer.EncodedObjectStorer for the transactional package.
 type ObjectStorage struct {
 	storer.EncodedObjectStorer
 	temporal storer.EncodedObjectStorer
 }
 
-func NewObjectStorage(s, temporal storer.EncodedObjectStorer) *ObjectStorage {
-	return &ObjectStorage{EncodedObjectStorer: s, temporal: temporal}
+// NewObjectStorage returns a new EncodedObjectStorer based on a base storer and
+// a temporal storer.
+func NewObjectStorage(base, temporal storer.EncodedObjectStorer) *ObjectStorage {
+	return &ObjectStorage{EncodedObjectStorer: base, temporal: temporal}
 }
 
+// SetEncodedObject honors the storer.EncodedObjectStorer interface.
 func (o *ObjectStorage) SetEncodedObject(obj plumbing.EncodedObject) (plumbing.Hash, error) {
 	return o.temporal.SetEncodedObject(obj)
 }
 
+// HasEncodedObject honors the storer.EncodedObjectStorer interface.
 func (o *ObjectStorage) HasEncodedObject(h plumbing.Hash) error {
 	err := o.EncodedObjectStorer.HasEncodedObject(h)
 	if err == plumbing.ErrObjectNotFound {
@@ -27,6 +32,7 @@ func (o *ObjectStorage) HasEncodedObject(h plumbing.Hash) error {
 	return err
 }
 
+// EncodedObjectSize honors the storer.EncodedObjectStorer interface.
 func (o *ObjectStorage) EncodedObjectSize(h plumbing.Hash) (int64, error) {
 	sz, err := o.EncodedObjectStorer.EncodedObjectSize(h)
 	if err == plumbing.ErrObjectNotFound {
@@ -36,6 +42,7 @@ func (o *ObjectStorage) EncodedObjectSize(h plumbing.Hash) (int64, error) {
 	return sz, err
 }
 
+// EncodedObject honors the storer.EncodedObjectStorer interface.
 func (o *ObjectStorage) EncodedObject(t plumbing.ObjectType, h plumbing.Hash) (plumbing.EncodedObject, error) {
 	obj, err := o.EncodedObjectStorer.EncodedObject(t, h)
 	if err == plumbing.ErrObjectNotFound {
@@ -45,6 +52,7 @@ func (o *ObjectStorage) EncodedObject(t plumbing.ObjectType, h plumbing.Hash) (p
 	return obj, err
 }
 
+// IterEncodedObjects honors the storer.EncodedObjectStorer interface.
 func (o *ObjectStorage) IterEncodedObjects(t plumbing.ObjectType) (storer.EncodedObjectIter, error) {
 	baseIter, err := o.EncodedObjectStorer.IterEncodedObjects(t)
 	if err != nil {
@@ -62,6 +70,7 @@ func (o *ObjectStorage) IterEncodedObjects(t plumbing.ObjectType) (storer.Encode
 	}), nil
 }
 
+// Commit it copies the objects of the temporal storage into the base storage.
 func (o *ObjectStorage) Commit() error {
 	iter, err := o.temporal.IterEncodedObjects(plumbing.AnyObject)
 	if err != nil {
diff --git a/storage/transactional/reference.go b/storage/transactional/reference.go
@@ -6,6 +6,7 @@ import (
 	"gopkg.in/src-d/go-git.v4/storage"
 )
 
+// ReferenceStorage implements the storer.ReferenceStorage for the transactional package.
 type ReferenceStorage struct {
 	storer.ReferenceStorer
 	temporal storer.ReferenceStorer
@@ -19,20 +20,24 @@ type ReferenceStorage struct {
 	packRefs bool
 }
 
-func NewReferenceStorage(s, temporal storer.ReferenceStorer) *ReferenceStorage {
+// NewReferenceStorage returns a new ReferenceStorer based on a base storer and
+// a temporal storer.
+func NewReferenceStorage(base, temporal storer.ReferenceStorer) *ReferenceStorage {
 	return &ReferenceStorage{
-		ReferenceStorer: s,
+		ReferenceStorer: base,
 		temporal:        temporal,
 
 		deleted: make(map[plumbing.ReferenceName]struct{}, 0),
 	}
 }
 
+// SetReference honors the storer.ReferenceStorer interface.
 func (r *ReferenceStorage) SetReference(ref *plumbing.Reference) error {
 	delete(r.deleted, ref.Name())
 	return r.temporal.SetReference(ref)
 }
 
+// SetReference honors the storer.ReferenceStorer interface.
 func (r *ReferenceStorage) CheckAndSetReference(ref, old *plumbing.Reference) error {
 	if old == nil {
 		return r.SetReference(ref)
@@ -54,6 +59,7 @@ func (r *ReferenceStorage) CheckAndSetReference(ref, old *plumbing.Reference) er
 	return r.SetReference(ref)
 }
 
+// Reference honors the storer.ReferenceStorer interface.
 func (r ReferenceStorage) Reference(n plumbing.ReferenceName) (*plumbing.Reference, error) {
 	if _, deleted := r.deleted[n]; deleted {
 		return nil, plumbing.ErrReferenceNotFound
@@ -67,6 +73,7 @@ func (r ReferenceStorage) Reference(n plumbing.ReferenceName) (*plumbing.Referen
 	return ref, err
 }
 
+// IterReferences honors the storer.ReferenceStorer interface.
 func (r ReferenceStorage) IterReferences() (storer.ReferenceIter, error) {
 	baseIter, err := r.ReferenceStorer.IterReferences()
 	if err != nil {
@@ -84,6 +91,7 @@ func (r ReferenceStorage) IterReferences() (storer.ReferenceIter, error) {
 	}), nil
 }
 
+// CountLooseRefs honors the storer.ReferenceStorer interface.
 func (r ReferenceStorage) CountLooseRefs() (int, error) {
 	tc, err := r.temporal.CountLooseRefs()
 	if err != nil {
@@ -98,16 +106,20 @@ func (r ReferenceStorage) CountLooseRefs() (int, error) {
 	return tc + bc, nil
 }
 
+// PackRefs honors the storer.ReferenceStorer interface.
 func (r ReferenceStorage) PackRefs() error {
 	r.packRefs = true
 	return nil
 }
 
+// RemoveReference honors the storer.ReferenceStorer interface.
 func (r ReferenceStorage) RemoveReference(n plumbing.ReferenceName) error {
 	r.deleted[n] = struct{}{}
 	return r.temporal.RemoveReference(n)
 }
 
+// Commit it copies the reference information of the temporal storage into the
+// base storage.
 func (r ReferenceStorage) Commit() error {
 	for name := range r.deleted {
 		if err := r.ReferenceStorer.RemoveReference(name); err != nil {
diff --git a/storage/transactional/shallow.go b/storage/transactional/shallow.go
@@ -5,22 +5,27 @@ import (
 	"gopkg.in/src-d/go-git.v4/plumbing/storer"
 )
 
+// ShallowStorage implements the storer.ShallowStorer for the transactional package.
 type ShallowStorage struct {
 	storer.ShallowStorer
 	temporal storer.ShallowStorer
 }
 
-func NewShallowStorage(s, temporal storer.ShallowStorer) *ShallowStorage {
+// NewShallowStorage returns a new ShallowStorage based on a base storer and
+// a temporal storer.
+func NewShallowStorage(base, temporal storer.ShallowStorer) *ShallowStorage {
 	return &ShallowStorage{
-		ShallowStorer: s,
+		ShallowStorer: base,
 		temporal:      temporal,
 	}
 }
 
+// SetShallow honors the storer.ShallowStorer interface.
 func (s *ShallowStorage) SetShallow(commits []plumbing.Hash) error {
 	return s.temporal.SetShallow(commits)
 }
 
+// Shallow honors the storer.ShallowStorer interface.
 func (s *ShallowStorage) Shallow() ([]plumbing.Hash, error) {
 	shallow, err := s.temporal.Shallow()
 	if err != nil {
@@ -34,6 +39,8 @@ func (s *ShallowStorage) Shallow() ([]plumbing.Hash, error) {
 	return s.ShallowStorer.Shallow()
 }
 
+// Commit it copies the shallow information of the temporal storage into the
+// base storage.
 func (s *ShallowStorage) Commit() error {
 	commits, err := s.temporal.Shallow()
 	if err != nil || len(commits) == 0 {
diff --git a/storage/transactional/storage.go b/storage/transactional/storage.go
@@ -4,9 +4,12 @@ import (
 	"gopkg.in/src-d/go-git.v4/storage"
 )
 
-// Storage is an implementation of git.Storer that stores data on disk in the
-// standard git format (this is, the .git directory). Zero values of this type
-// are not safe to use, see the NewStorage function below.
+// Storage is a transactional implementation of git.Storer, it demux the write
+// and read operation of two separate storers, allowing to merge content calling
+// Storage.Commit.
+//
+// The API and functionality of this package are considered EXPERIMENTAL and is
+// not considered stable nor production ready.
 type Storage struct {
 	s, temporal storage.Storer
 
@@ -17,19 +20,23 @@ type Storage struct {
 	*ConfigStorage
 }
 
-func NewStorage(s, temporal storage.Storer) *Storage {
+// NewStorage returns a new Storage based on two repositories, base is the base
+// repository where the read operations are read and temportal is were all
+// the write operations are stored.
+func NewStorage(base, temporal storage.Storer) *Storage {
 	return &Storage{
-		s:        s,
+		s:        base,
 		temporal: temporal,
 
-		ObjectStorage:    NewObjectStorage(s, temporal),
-		ReferenceStorage: NewReferenceStorage(s, temporal),
-		IndexStorage:     NewIndexStorage(s, temporal),
-		ShallowStorage:   NewShallowStorage(s, temporal),
-		ConfigStorage:    NewConfigStorage(s, temporal),
+		ObjectStorage:    NewObjectStorage(base, temporal),
+		ReferenceStorage: NewReferenceStorage(base, temporal),
+		IndexStorage:     NewIndexStorage(base, temporal),
+		ShallowStorage:   NewShallowStorage(base, temporal),
+		ConfigStorage:    NewConfigStorage(base, temporal),
 	}
 }
 
+// Module it honors the storage.ModuleStorer interface.
 func (s *Storage) Module(name string) (storage.Storer, error) {
 	base, err := s.s.Module(name)
 	if err != nil {
@@ -44,6 +51,7 @@ func (s *Storage) Module(name string) (storage.Storer, error) {
 	return NewStorage(base, temporal), nil
 }
 
+// Commit it copies the content of the temporal storage into the base storage.
 func (s *Storage) Commit() error {
 	for _, c := range []interface{ Commit() error }{
 		s.ObjectStorage,

Original file line number	Diff line number	Diff line change
`@@ -5,20 +5,24 @@ import (`
`5`	`5`	`"gopkg.in/src-d/go-git.v4/plumbing/storer"`
`6`	`6`	`)`
`7`	`7`
	`8`	`+// IndexStorage implements the storer.IndexStorage for the transactional package.`
`8`	`9`	`type IndexStorage struct {`
`9`	`10`	`storer.IndexStorer`
`10`	`11`	`temporal storer.IndexStorer`
`11`	`12`
`12`	`13`	`set bool`
`13`	`14`	`}`
`14`	`15`
	`16`	`+// NewIndexStorage returns a new IndexStorer based on a base storer and a`
	`17`	`+// temporal storer.`
`15`	`18`	`func NewIndexStorage(s, temporal storer.IndexStorer) *IndexStorage {`
`16`	`19`	`return &IndexStorage{`
`17`	`20`	`IndexStorer: s,`
`18`	`21`	`temporal: temporal,`
`19`	`22`	`}`
`20`	`23`	`}`
`21`	`24`
	`25`	`+// SetIndex honors the storer.IndexStorer interface.`
`22`	`26`	`func (s IndexStorage) SetIndex(idx index.Index) (err error) {`
`23`	`27`	`if err := s.temporal.SetIndex(idx); err != nil {`
`24`	`28`	`return err`
`@@ -28,6 +32,7 @@ func (s IndexStorage) SetIndex(idx index.Index) (err error) {`
`28`	`32`	`return nil`
`29`	`33`	`}`
`30`	`34`
	`35`	`+// Index honors the storer.IndexStorer interface.`
`31`	`36`	`func (s IndexStorage) Index() (index.Index, error) {`
`32`	`37`	`if !s.set {`
`33`	`38`	`return s.IndexStorer.Index()`
`@@ -36,15 +41,16 @@ func (s IndexStorage) Index() (index.Index, error) {`
`36`	`41`	`return s.temporal.Index()`
`37`	`42`	`}`
`38`	`43`
`39`		`-func (c *IndexStorage) Commit() error {`
`40`		`- if !c.set {`
	`44`	`+// Commit it copies the index from the temporal storage into the base storage.`
	`45`	`+func (s *IndexStorage) Commit() error {`
	`46`	`+ if !s.set {`
`41`	`47`	`return nil`
`42`	`48`	`}`
`43`	`49`
`44`		`- idx, err := c.temporal.Index()`
	`50`	`+ idx, err := s.temporal.Index()`
`45`	`51`	`if err != nil {`
`46`	`52`	`return err`
`47`	`53`	`}`
`48`	`54`
`49`		`- return c.IndexStorer.SetIndex(idx)`
	`55`	`+ return s.IndexStorer.SetIndex(idx)`
`50`	`56`	`}`
Original file line number	Diff line number	Diff line change
`@@ -5,22 +5,27 @@ import (`
`5`	`5`	`"gopkg.in/src-d/go-git.v4/plumbing/storer"`
`6`	`6`	`)`
`7`	`7`
	`8`	`+// ShallowStorage implements the storer.ShallowStorer for the transactional package.`
`8`	`9`	`type ShallowStorage struct {`
`9`	`10`	`storer.ShallowStorer`
`10`	`11`	`temporal storer.ShallowStorer`
`11`	`12`	`}`
`12`	`13`
`13`		`-func NewShallowStorage(s, temporal storer.ShallowStorer) *ShallowStorage {`
	`14`	`+// NewShallowStorage returns a new ShallowStorage based on a base storer and`
	`15`	`+// a temporal storer.`
	`16`	`+func NewShallowStorage(base, temporal storer.ShallowStorer) *ShallowStorage {`
`14`	`17`	`return &ShallowStorage{`
`15`		`- ShallowStorer: s,`
	`18`	`+ ShallowStorer: base,`
`16`	`19`	`temporal: temporal,`
`17`	`20`	`}`
`18`	`21`	`}`
`19`	`22`
	`23`	`+// SetShallow honors the storer.ShallowStorer interface.`
`20`	`24`	`func (s *ShallowStorage) SetShallow(commits []plumbing.Hash) error {`
`21`	`25`	`return s.temporal.SetShallow(commits)`
`22`	`26`	`}`
`23`	`27`
	`28`	`+// Shallow honors the storer.ShallowStorer interface.`
`24`	`29`	`func (s *ShallowStorage) Shallow() ([]plumbing.Hash, error) {`
`25`	`30`	`shallow, err := s.temporal.Shallow()`
`26`	`31`	`if err != nil {`
`@@ -34,6 +39,8 @@ func (s *ShallowStorage) Shallow() ([]plumbing.Hash, error) {`
`34`	`39`	`return s.ShallowStorer.Shallow()`
`35`	`40`	`}`
`36`	`41`
	`42`	`+// Commit it copies the shallow information of the temporal storage into the`
	`43`	`+// base storage.`
`37`	`44`	`func (s *ShallowStorage) Commit() error {`
`38`	`45`	`commits, err := s.temporal.Shallow()`
`39`	`46`	`if err != nil \|\| len(commits) == 0 {`