refactor: Remove dead code from client package and document remaining (part 1 of many)

client/collection.go

@@ -0,0 +1,168 @@
+// Copyright 2022 Democratized Data Foundation
+//
+// Use of this software is governed by the Business Source License
+// included in the file licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with
+// the Business Source License, use of this software will be governed
+// by the Apache License, Version 2.0, included in the file
+// licenses/APL.txt.
+
+package client
+
+import (
+	"context"
+
+	"github.com/sourcenetwork/defradb/datastore"
+)
+
+// Collection represents a defradb collection.
+//
+// A Collection is mostly analogous to a SQL table, however a collection is specific to its
+// host, and many collections may share the same schema.
+//
+// Many functions on this object will interact with the underlying datastores.
+type Collection interface {
+	// Description returns the CollectionDescription of this Collection.
+	Description() CollectionDescription
+	// Name returns the name of this collection.
+	Name() string
+	// Schema returns the SchemaDescription used to define this Collection.
+	Schema() SchemaDescription
+	// ID returns the ID of this Collection.
+	ID() uint32
+	// SchemaID returns the ID of the Schema used to define this Collection.
+	SchemaID() string
+
+	// Indexes returns all the indexes defined on this Collection.
+	Indexes() []IndexDescription
+	// PrimaryIndex returns the primary index for the this Collection.
+	PrimaryIndex() IndexDescription
+	// Index returns the index with the given index ID.
+	//
+	// If no index is found with the given ID an ErrIndexNotFound error will be returned.
+	Index(uint32) (IndexDescription, error)
+
+	// Create a new document.
+	//
+	// Will verify the DocKey/CID to ensure that the new document is correctly formatted.
+	Create(context.Context, *Document) error
+	// CreateMany new documents.
+	//
+	// Will verify the DocKeys/CIDs to ensure that the new documents are correctly formatted.
+	CreateMany(context.Context, []*Document) error
+	// Update an existing document with the new values.
+	//
+	// Any field that needs to be removed or cleared should call doc.Clear(field) before.
+	// Any field that is nil/empty that hasn't called Clear will be ignored.
+	//
+	// Will return a ErrDocumentNotFound error if the given document is not found.
+	Update(context.Context, *Document) error
+	// Save the given document in the database.
+	//
+	// If a document exists with the given DocKey it will update it. Otherwise a new document
+	// will be created.
+	Save(context.Context, *Document) error
+	// Delete will attempt to delete a document by key.
+	//
+	// Will return true if a deletion is successful, and return false along with an error
+	// if it cannot. If the document doesn't exist, then it will return false and a ErrDocumentNotFound error.
+	// This operation will hard-delete all state relating to the given DocKey. This includes data, block, and head storage.
+	Delete(context.Context, DocKey) (bool, error)
+	// Exists checks if a given document exists with supplied DocKey.
+	//
+	// Will return true if a matching document exists, otherwise will return false.
+	Exists(context.Context, DocKey) (bool, error)
+
+	// UpdateWith updates a target document using the given updater type.
+	//
+	// Target can be a Filter statement, a single docKey, a single document,
+	// an array of docKeys, or an array of documents.
+	// It is recommened to use the respective typed versions of Update
+	// (e.g. UpdateWithFilter or UpdateWithKey) over this function if you can.
+	//
+	// Returns an ErrInvalidUpdateTarget error if the target type is not supported.
+	// Returns an ErrInvalidUpdater error if the updater type is not supported.
+	UpdateWith(ctx context.Context, target interface{}, updater interface{}) (*UpdateResult, error)
+	// UpdateWithFilter updates using a filter to target documents for update.
+	//
+	// The provided updater must be a string Patch, string Merge Patch, a parsed Patch, or parsed Merge Patch
+	// else an ErrInvalidUpdater will be returned.
+	UpdateWithFilter(ctx context.Context, filter interface{}, updater interface{}) (*UpdateResult, error)
+	// UpdateWithKey updates using a DocKey to target a single document for update.
+	//
+	// The provided updater must be a string Patch, string Merge Patch, a parsed Patch, or parsed Merge Patch
+	// else an ErrInvalidUpdater will be returned.
+	//
+	// Returns an ErrDocumentNotFound if a document matching the given DocKey is not found.
+	UpdateWithKey(ctx context.Context, key DocKey, updater interface{}) (*UpdateResult, error)
+	// UpdateWithKeys updates documents matching the given DocKeys.
+	//
+	// The provided updater must be a string Patch, string Merge Patch, a parsed Patch, or parsed Merge Patch
+	// else an ErrInvalidUpdater will be returned.
+	//
+	// Returns an ErrDocumentNotFound if a document is not found for any given DocKey.
+	UpdateWithKeys(context.Context, []DocKey, interface{}) (*UpdateResult, error)
+
+	// DeleteWith deletes a target document.
+	//
+	// Target can be a Filter statement, a single docKey, a single document, an array of docKeys,
+	// or an array of documents. It is recommened to use the respective typed versions of Delete
+	// (e.g. DeleteWithFilter or DeleteWithKey) over this function if you can.
+	// This operation will hard-delete all state relating to the given DocKey. This includes data, block, and head storage.
+	//
+	// Returns an ErrInvalidDeleteTarget if the target type is not supported.
+	DeleteWith(ctx context.Context, target interface{}) (*DeleteResult, error)
+	// DeleteWithFilter deletes documents matching the given filter.
+	//
+	// This operation will hard-delete all state relating to the given DocKey. This includes data, block, and head storage.
+	DeleteWithFilter(ctx context.Context, filter interface{}) (*DeleteResult, error)
+	// DeleteWithKey deletes using a DocKey to target a single document for delete.
+	//
+	// This operation will hard-delete all state relating to the given DocKey. This includes data, block, and head storage.
+	//
+	// Returns an ErrDocumentNotFound if a document matching the given DocKey is not found.
+	DeleteWithKey(context.Context, DocKey) (*DeleteResult, error)
+	// DeleteWithKeys deletes documents matching the given DocKeys.
+	//
+	// This operation will hard-delete all state relating to the given DocKey. This includes data, block, and head storage.
+	//
+	// Returns an ErrDocumentNotFound if a document is not found for any given DocKey.
+	DeleteWithKeys(context.Context, []DocKey) (*DeleteResult, error)
+
+	// Get returns the document with the given DocKey.
+	//
+	// Returns an ErrDocumentNotFound if a document matching the given DocKey is not found.
+	Get(context.Context, DocKey) (*Document, error)
+
+	// WithTxn returns a new instance of the collection, with a transaction
+	// handle instead of a raw DB handle.
+	WithTxn(datastore.Txn) Collection
+
+	// GetAllDocKeys returns all the document keys that exist in the collection.
+	GetAllDocKeys(ctx context.Context) (<-chan DocKeysResult, error)
+}
+
+// DocKeysResult wraps the result of an attempt at a DocKey retrieval operation.
+type DocKeysResult struct {
+	// If a DocKey was successfully retrieved, this will be that key.
+	Key DocKey
+	// If an error was generated whilst attempting to retrieve the DocKey, this will be the error.
+	Err error
+}
+
+// UpdateResult wraps the result of an update call.
+type UpdateResult struct {
+	// Count contains the number of documents updated by the update call.
+	Count int64
+	// DocKeys contains the DocKeys of all the documents updated by the update call.
+	DocKeys []string
+}
+
+// DeleteResult wraps the result of an delete call.
+type DeleteResult struct {
+	// Count contains the number of documents deleted by the delete call.
+	Count int64
+	// DocKeys contains the DocKeys of all the documents deleted by the delete call.
+	DocKeys []string
+}

client/ctype.go

@@ -13,8 +13,11 @@ package client
 // CType indicates CRDT type
 type CType byte
 
+// Available CRDT types.
+//
+// If a CRDT type is not declared here, we do not support it!  CRDT types here
+// may not be valid in all contexts.
 const (
-	//no lint
 	NONE_CRDT = CType(iota) // reserved none type
 	LWW_REGISTER
 	OBJECT

client/db.go

@@ -0,0 +1,45 @@
+// Copyright 2022 Democratized Data Foundation
+//
+// Use of this software is governed by the Business Source License
+// included in the file licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with
+// the Business Source License, use of this software will be governed
+// by the Apache License, Version 2.0, included in the file
+// licenses/APL.txt.
+
+package client
+
+import (
+	"context"
+
+	"github.com/sourcenetwork/defradb/datastore"
+
+	ds "github.com/ipfs/go-datastore"
+	blockstore "github.com/ipfs/go-ipfs-blockstore"
+)
+
+type DB interface {
+	AddSchema(context.Context, string) error
+
+	CreateCollection(context.Context, CollectionDescription) (Collection, error)
+	GetCollectionByName(context.Context, string) (Collection, error)
+	GetCollectionBySchemaID(context.Context, string) (Collection, error)
+	GetAllCollections(ctx context.Context) ([]Collection, error)
+	GetRelationshipIdField(fieldName, targetType, thisType string) (string, error)
+
+	Root() ds.Batching
+	Blockstore() blockstore.Blockstore
+
+	NewTxn(context.Context, bool) (datastore.Txn, error)
+	ExecQuery(context.Context, string) *QueryResult
+	ExecTransactionalQuery(ctx context.Context, query string, txn datastore.Txn) *QueryResult
+	Close(context.Context)
+
+	PrintDump(ctx context.Context)
+}
+
+type QueryResult struct {
+	Errors []interface{} `json:"errors,omitempty"`
+	Data   interface{}   `json:"data"`
+}

db/errors.go → client/doc.go

@@ -8,11 +8,11 @@
 // by the Apache License, Version 2.0, included in the file
 // licenses/APL.txt.
 
-package db
+/*
+The client package provides public members for interacting with a Defra DB instance.
 
-import "errors"
-
-// errors
-var (
-	ErrDocumentNotFound = errors.New("No document for the given key exists")
-)
+Only calls made via the `DB` and `Collection` interfaces interact with the underlying datastores.
+Currently the only provided implementation of `DB` is found in the `defra/db` package and can be
+instantiated via the `NewDB` function.
+*/
+package client

client/dockey.go

@@ -24,24 +24,25 @@ import (
 
 // Key Versions
 const (
-	V0 = 0x01
+	v0 = 0x01
 )
 
 var validVersions = map[uint16]bool{
-	V0: true,
+	v0: true,
 }
 
 var (
 	// NamespaceSDNDocKeyV0 reserved domain namespace for Source Data Network (SDN)
 	// Design a more appropriate system for future proofing doc key versions, ensuring
 	// backwards compatability. RE: CID
 	// *At the moment this is an random uuidV4
-	NamespaceSDNDocKeyV0 = uuid.Must(uuid.FromString("c94acbfa-dd53-40d0-97f3-29ce16c333fc"))
+	namespaceSDNDocKeyV0 = uuid.Must(uuid.FromString("c94acbfa-dd53-40d0-97f3-29ce16c333fc"))
 )
 
-// VersionToNamespace is a convenience for mapping between Version number and its UUID Namespace
-var VersionToNamespace = map[uint16]uuid.UUID{
-	V0: NamespaceSDNDocKeyV0,
+// versionToNamespace is a convenience for mapping between Version number and its UUID Namespace
+// nolint
+var versionToNamespace = map[uint16]uuid.UUID{
+	v0: namespaceSDNDocKeyV0,
 }
 
 // DocKey is the root key identifier for documents in DefraDB
@@ -51,16 +52,13 @@ type DocKey struct {
 	cid     cid.Cid
 }
 
-// Undef can be defined to be a nil like DocKey
-var Undef = DocKey{}
-
 // NewDocKeyV0 creates a new doc key identified by the root data CID, peer ID, and
 // namespaced by the versionNS
 // TODO: Parameterize namespace Version
 func NewDocKeyV0(dataCID cid.Cid) DocKey {
 	return DocKey{
-		version: V0,
-		uuid:    uuid.NewV5(NamespaceSDNDocKeyV0, dataCID.String()),
+		version: v0,
+		uuid:    uuid.NewV5(namespaceSDNDocKeyV0, dataCID.String()),
 		cid:     dataCID,
 	}
 }