forked from sourcenetwork/defradb
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
refactor: Remove dead code from client package and document remaining (…
…sourcenetwork#356) * Remove unneeded no-lint comment * Extract errors to own file We should declare all our public errors here * Declare IndexNotFound error * Declare ErrDocumentNotFound error No good declaring it internally if it is publicly accessable * Declare ErrInvalidUpdateTarget error * Declare ErrInvalidUpdater error * Declare ErrInvalidDeleteTarget error * Make dockey version constant private * Make namespaceSDNDocKeyV0 private * Make versionToNamespace private * Remove Undef DocKey I cant spot anywhere where we would want users to provide one of these, and don't want to encourage it * Remove unused CreateOpt struct * Remove unused UpdateOpt struct * Remove unused DeleteOpt struct * Move DB interface to own file core.go is ambiguous with the newer types added to the package, and this file will get hard to read once documention expands the line count * Rename core.go to collection.go Having moved the DB interface out, this name makes sense * Remove unimplemented CreateIndex function from public interface This function is unlikely to be implemented for quite a while and as it modifies an existing collection, it comes with a load of synchronization questions that should be answered properly before we can assume it will exist in the currently declared form * Return result from UpdateWith Note: this function is untested * Return result from DeleteWith * Add package level documentation * Document CType consts * Document errors * Document Collection interface * Document DocKeysResult * Document UpdateResult * Document DeleteResult * Tweak error messages
- Loading branch information
1 parent
a21eb00
commit c940e83
Showing
13 changed files
with
301 additions
and
193 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| } |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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"` | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.