From a85ed89b07dd62b668663c17b70c6cf82b4a87c0 Mon Sep 17 00:00:00 2001 From: Shahzad Lone Date: Tue, 27 Feb 2024 00:27:13 -0500 Subject: [PATCH] PR(ACP-DOCS): Generate CLI Docs With Identity --- docs/cli/defradb_client.md | 1 + docs/cli/defradb_client_acp.md | 41 +++++++++ docs/cli/defradb_client_acp_policy.md | 41 +++++++++ docs/cli/defradb_client_acp_policy_add.md | 96 ++++++++++++++++++++ docs/cli/defradb_client_collection_create.md | 18 ++-- docs/cli/defradb_client_collection_delete.md | 18 ++-- docs/cli/defradb_client_collection_get.md | 10 +- docs/cli/defradb_client_collection_update.md | 21 +++-- docs/cli/defradb_client_query.md | 10 +- docs/cli/defradb_client_schema_add.md | 11 +++ 10 files changed, 239 insertions(+), 28 deletions(-) create mode 100644 docs/cli/defradb_client_acp.md create mode 100644 docs/cli/defradb_client_acp_policy.md create mode 100644 docs/cli/defradb_client_acp_policy_add.md diff --git a/docs/cli/defradb_client.md b/docs/cli/defradb_client.md index 30e8c804ee..b9a8157e91 100644 --- a/docs/cli/defradb_client.md +++ b/docs/cli/defradb_client.md @@ -38,6 +38,7 @@ Execute queries, add schema types, obtain node info, etc. ### SEE ALSO * [defradb](defradb.md) - DefraDB Edge Database +* [defradb client acp](defradb_client_acp.md) - Interact with the access control system of a DefraDB node * [defradb client backup](defradb_client_backup.md) - Interact with the backup utility * [defradb client collection](defradb_client_collection.md) - Interact with a collection. * [defradb client dump](defradb_client_dump.md) - Dump the contents of DefraDB node-side diff --git a/docs/cli/defradb_client_acp.md b/docs/cli/defradb_client_acp.md new file mode 100644 index 0000000000..d57cbcbbcd --- /dev/null +++ b/docs/cli/defradb_client_acp.md @@ -0,0 +1,41 @@ +## defradb client acp + +Interact with the access control system of a DefraDB node + +### Synopsis + +Interact with the access control system of a DefraDB node + +### Options + +``` + -h, --help help for acp +``` + +### Options inherited from parent commands + +``` + --allowed-origins stringArray List of origins to allow for CORS requests + --logformat string Log format to use. Options are csv, json (default "csv") + --loglevel string Log level to use. Options are debug, info, error, fatal (default "info") + --lognocolor Disable colored log output + --logoutput string Log output path (default "stderr") + --logtrace Include stacktrace in error and fatal logs + --max-txn-retries int Specify the maximum number of retries per transaction (default 5) + --no-p2p Disable the peer-to-peer network synchronization system + --p2paddr strings Listen addresses for the p2p network (formatted as a libp2p MultiAddr) (default [/ip4/127.0.0.1/tcp/9171]) + --peers stringArray List of peers to connect to + --privkeypath string Path to the private key for tls + --pubkeypath string Path to the public key for tls + --rootdir string Directory for persistent data (default: $HOME/.defradb) + --store string Specify the datastore to use (supported: badger, memory) (default "badger") + --tx uint Transaction ID + --url string URL of HTTP endpoint to listen on or connect to (default "127.0.0.1:9181") + --valuelogfilesize int Specify the datastore value log file size (in bytes). In memory size will be 2*valuelogfilesize (default 1073741824) +``` + +### SEE ALSO + +* [defradb client](defradb_client.md) - Interact with a DefraDB node +* [defradb client acp policy](defradb_client_acp_policy.md) - Interact with the acp policy features of DefraDB instance + diff --git a/docs/cli/defradb_client_acp_policy.md b/docs/cli/defradb_client_acp_policy.md new file mode 100644 index 0000000000..6c65d5f768 --- /dev/null +++ b/docs/cli/defradb_client_acp_policy.md @@ -0,0 +1,41 @@ +## defradb client acp policy + +Interact with the acp policy features of DefraDB instance + +### Synopsis + +Interact with the acp policy features of DefraDB instance + +### Options + +``` + -h, --help help for policy +``` + +### Options inherited from parent commands + +``` + --allowed-origins stringArray List of origins to allow for CORS requests + --logformat string Log format to use. Options are csv, json (default "csv") + --loglevel string Log level to use. Options are debug, info, error, fatal (default "info") + --lognocolor Disable colored log output + --logoutput string Log output path (default "stderr") + --logtrace Include stacktrace in error and fatal logs + --max-txn-retries int Specify the maximum number of retries per transaction (default 5) + --no-p2p Disable the peer-to-peer network synchronization system + --p2paddr strings Listen addresses for the p2p network (formatted as a libp2p MultiAddr) (default [/ip4/127.0.0.1/tcp/9171]) + --peers stringArray List of peers to connect to + --privkeypath string Path to the private key for tls + --pubkeypath string Path to the public key for tls + --rootdir string Directory for persistent data (default: $HOME/.defradb) + --store string Specify the datastore to use (supported: badger, memory) (default "badger") + --tx uint Transaction ID + --url string URL of HTTP endpoint to listen on or connect to (default "127.0.0.1:9181") + --valuelogfilesize int Specify the datastore value log file size (in bytes). In memory size will be 2*valuelogfilesize (default 1073741824) +``` + +### SEE ALSO + +* [defradb client acp](defradb_client_acp.md) - Interact with the access control system of a DefraDB node +* [defradb client acp policy add](defradb_client_acp_policy_add.md) - Add new policy + diff --git a/docs/cli/defradb_client_acp_policy_add.md b/docs/cli/defradb_client_acp_policy_add.md new file mode 100644 index 0000000000..dba44db997 --- /dev/null +++ b/docs/cli/defradb_client_acp_policy_add.md @@ -0,0 +1,96 @@ +## defradb client acp policy add + +Add new policy + +### Synopsis + +Add new policy + +Requirements: + - Must provide a valid SourceHub Identity. + - ACP module must be available (i.e. ACP not disabled). + - Policy specified must be a valid policy (but DPI compliance is not necessary). + - Policy specified must be in a valid JSON or YAML format (detected automatically). + +Notes: + - A non-DPI policy will be accepted (will be registered with acp module). + - But only a valid DPI policyID & resource can be specified on a schema. + - DPI validation happens when attempting to add a permissioned schema. + - If DPI validation fails while adding schema, the schema is rejected. + +Example: add from an argument string: + defradb client acp policy add -i cosmos1f2djr7dl9vhrk3twt3xwqp09nhtzec9mdkf70j ' +description: A Valid DefraDB Policy Interface + +actor: + name: actor + +resources: + users: + permissions: + read: + expr: owner + reader + write: + expr: owner + + relations: + owner: + types: + - actor + reader: + types: + - actor +' + +Example: add from file: + defradb client acp policy add -i cosmos17r39df0hdcrgnmmw4mvu7qgk5nu888c7uvv37y -f policy.yml + +Example: add from file, verbose flags: + defradb client acp policy add --identity cosmos1kpw734v54g0t0d8tcye8ee5jc3gld0tcr2q473 --file policy.yml + +Example: add from stdin: + cat policy.yml | defradb client acp policy add - + +Learn more about the DefraDB Policy Interface [DPI](/acp/DPI.md) +Learn more about DefraDB ACP Terminologies [TERMINOLOGY](/acp/TERMINOLOGY.md) + + + +``` +defradb client acp policy add [-i --identity] [policy] [flags] +``` + +### Options + +``` + -f, --file string File to load a policy from + -h, --help help for add + -i, --identity string [Required] Identity of the creator +``` + +### Options inherited from parent commands + +``` + --allowed-origins stringArray List of origins to allow for CORS requests + --logformat string Log format to use. Options are csv, json (default "csv") + --loglevel string Log level to use. Options are debug, info, error, fatal (default "info") + --lognocolor Disable colored log output + --logoutput string Log output path (default "stderr") + --logtrace Include stacktrace in error and fatal logs + --max-txn-retries int Specify the maximum number of retries per transaction (default 5) + --no-p2p Disable the peer-to-peer network synchronization system + --p2paddr strings Listen addresses for the p2p network (formatted as a libp2p MultiAddr) (default [/ip4/127.0.0.1/tcp/9171]) + --peers stringArray List of peers to connect to + --privkeypath string Path to the private key for tls + --pubkeypath string Path to the public key for tls + --rootdir string Directory for persistent data (default: $HOME/.defradb) + --store string Specify the datastore to use (supported: badger, memory) (default "badger") + --tx uint Transaction ID + --url string URL of HTTP endpoint to listen on or connect to (default "127.0.0.1:9181") + --valuelogfilesize int Specify the datastore value log file size (in bytes). In memory size will be 2*valuelogfilesize (default 1073741824) +``` + +### SEE ALSO + +* [defradb client acp policy](defradb_client_acp_policy.md) - Interact with the acp policy features of DefraDB instance + diff --git a/docs/cli/defradb_client_collection_create.md b/docs/cli/defradb_client_collection_create.md index 7c2cba7487..8dea0759dc 100644 --- a/docs/cli/defradb_client_collection_create.md +++ b/docs/cli/defradb_client_collection_create.md @@ -6,28 +6,32 @@ Create a new document. Create a new document. -Example: create from string +Example: create from string: defradb client collection create --name User '{ "name": "Bob" }' -Example: create multiple from string +Example: create from string, with identity: + defradb client collection create -i cosmos1f2djr7dl9vhrk3twt3xwqp09nhtzec9mdkf70j --name User '{ "name": "Bob" }' + +Example: create multiple from string: defradb client collection create --name User '[{ "name": "Alice" }, { "name": "Bob" }]' -Example: create from file +Example: create from file: defradb client collection create --name User -f document.json -Example: create from stdin +Example: create from stdin: cat document.json | defradb client collection create --name User - ``` -defradb client collection create [flags] +defradb client collection create [-i --identity] [flags] ``` ### Options ``` - -f, --file string File containing document(s) - -h, --help help for create + -f, --file string File containing document(s) + -h, --help help for create + -i, --identity string Identity of the actor ``` ### Options inherited from parent commands diff --git a/docs/cli/defradb_client_collection_delete.md b/docs/cli/defradb_client_collection_delete.md index 33a5af4809..db199c94ff 100644 --- a/docs/cli/defradb_client_collection_delete.md +++ b/docs/cli/defradb_client_collection_delete.md @@ -6,23 +6,27 @@ Delete documents by docID or filter. Delete documents by docID or filter and lists the number of documents deleted. -Example: delete by docID(s) - defradb client collection delete --name User --docID bae-123,bae-456 +Example: delete by docID(s): + defradb client collection delete --name User --docID bae-123,bae-456 -Example: delete by filter +Example: delete by docID(s) with identity: + defradb client collection delete -i cosmos1f2djr7dl9vhrk3twt3xwqp09nhtzec9mdkf70j --name User --docID bae-123,bae-456 + +Example: delete by filter: defradb client collection delete --name User --filter '{ "_gte": { "points": 100 } }' ``` -defradb client collection delete [--filter --docID ] [flags] +defradb client collection delete [-i --identity] [--filter --docID ] [flags] ``` ### Options ``` - --docID strings Document ID - --filter string Document filter - -h, --help help for delete + --docID strings Document ID + --filter string Document filter + -h, --help help for delete + -i, --identity string Identity of the actor ``` ### Options inherited from parent commands diff --git a/docs/cli/defradb_client_collection_get.md b/docs/cli/defradb_client_collection_get.md index c2aeac17b3..0f4f39f678 100644 --- a/docs/cli/defradb_client_collection_get.md +++ b/docs/cli/defradb_client_collection_get.md @@ -8,17 +8,21 @@ View document fields. Example: defradb client collection get --name User bae-123 + +Example to get a private document we must use an identity: + defradb client collection get -i cosmos1f2djr7dl9vhrk3twt3xwqp09nhtzec9mdkf70j --name User bae-123 ``` -defradb client collection get [--show-deleted] [flags] +defradb client collection get [-i --identity] [--show-deleted] [flags] ``` ### Options ``` - -h, --help help for get - --show-deleted Show deleted documents + -h, --help help for get + -i, --identity string Identity of the actor + --show-deleted Show deleted documents ``` ### Options inherited from parent commands diff --git a/docs/cli/defradb_client_collection_update.md b/docs/cli/defradb_client_collection_update.md index 1200cc5b3e..d82cf8872e 100644 --- a/docs/cli/defradb_client_collection_update.md +++ b/docs/cli/defradb_client_collection_update.md @@ -6,29 +6,34 @@ Update documents by docID or filter. Update documents by docID or filter. -Example: update from string +Example: update from string: defradb client collection update --name User --docID bae-123 '{ "name": "Bob" }' -Example: update by filter +Example: update by filter: defradb client collection update --name User \ --filter '{ "_gte": { "points": 100 } }' --updater '{ "verified": true }' -Example: update by docIDs +Example: update by docIDs: defradb client collection update --name User \ --docID bae-123,bae-456 --updater '{ "verified": true }' + +Example: update private docIDs, with identity: + defradb client collection update -i cosmos1f2djr7dl9vhrk3twt3xwqp09nhtzec9mdkf70j --name User \ + --docID bae-123,bae-456 --updater '{ "verified": true }' ``` -defradb client collection update [--filter --docID --updater ] [flags] +defradb client collection update [-i --identity] [--filter --docID --updater ] [flags] ``` ### Options ``` - --docID strings Document ID - --filter string Document filter - -h, --help help for update - --updater string Document updater + --docID strings Document ID + --filter string Document filter + -h, --help help for update + -i, --identity string Identity of the actor + --updater string Document updater ``` ### Options inherited from parent commands diff --git a/docs/cli/defradb_client_query.md b/docs/cli/defradb_client_query.md index b23bf50553..f87bb13363 100644 --- a/docs/cli/defradb_client_query.md +++ b/docs/cli/defradb_client_query.md @@ -12,6 +12,9 @@ A query request can be sent as a single argument. Example command: Do a query request from a file by using the '-f' flag. Example command: defradb client query -f request.graphql +Do a query request from a file and with an identity. Example command: + defradb client query -i cosmos1f2djr7dl9vhrk3twt3xwqp09nhtzec9mdkf70j -f request.graphql + Or it can be sent via stdin by using the '-' special syntax. Example command: cat request.graphql | defradb client query - @@ -21,14 +24,15 @@ with the database more conveniently. To learn more about the DefraDB GraphQL Query Language, refer to https://docs.source.network. ``` -defradb client query [query request] [flags] +defradb client query [-i --identity] [request] [flags] ``` ### Options ``` - -f, --file string File containing the query request - -h, --help help for query + -f, --file string File containing the query request + -h, --help help for query + -i, --identity string Identity of the actor ``` ### Options inherited from parent commands diff --git a/docs/cli/defradb_client_schema_add.md b/docs/cli/defradb_client_schema_add.md index e0ad675241..cb78ebaf81 100644 --- a/docs/cli/defradb_client_schema_add.md +++ b/docs/cli/defradb_client_schema_add.md @@ -6,6 +6,17 @@ Add new schema Add new schema. +Terminology: + - 'DPI' means 'DefraDB Policy Interface'. + - 'Permissioned Schema' means to have a policy on the schema: @policy(id:".." resource: "..") + +Requirements: + - ACP module must be available if adding a permissioned schema (i.e. ACP not disabled). + - The specified policy and resource must be DPI compliant if adding a permissioned schema. + +Notes: + - If DPI validation fails upon adding a schema, the schema is rejected. + Example: add from an argument string: defradb client schema add 'type Foo { ... }'