From 1f6a275668334b72ac0f8c1d6d82e585edcbae36 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 | 46 ++++++++++ docs/cli/defradb_client_acp_policy.md | 42 +++++++++ docs/cli/defradb_client_acp_policy_add.md | 90 ++++++++++++++++++++ docs/cli/defradb_client_collection_create.md | 18 ++-- docs/cli/defradb_client_collection_delete.md | 18 ++-- docs/cli/defradb_client_collection_docIDs.md | 10 ++- 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 | 5 ++ 11 files changed, 240 insertions(+), 31 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 9fb8e87990..1b5532ac9f 100644 --- a/docs/cli/defradb_client.md +++ b/docs/cli/defradb_client.md @@ -39,6 +39,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..ab4ac22d6d --- /dev/null +++ b/docs/cli/defradb_client_acp.md @@ -0,0 +1,46 @@ +## defradb client acp + +Interact with the access control system of a DefraDB node + +### Synopsis + +Interact with the access control system of a DefraDB node + +Learn more about [ACP](/acp/README.md) + + + +### Options + +``` + -h, --help help for acp +``` + +### Options inherited from parent commands + +``` + --allowed-origins stringArray List of origins to allow for CORS requests + --log-format string Log format to use. Options are text or json (default "text") + --log-level string Log level to use. Options are debug, info, error, fatal (default "info") + --log-output string Log output path. Options are stderr or stdout. (default "stderr") + --log-overrides string Logger config overrides. Format ,=,...;,... + --log-source Include source location in logs + --log-stacktrace 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..ef6d02e3dc --- /dev/null +++ b/docs/cli/defradb_client_acp_policy.md @@ -0,0 +1,42 @@ +## 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 + --log-format string Log format to use. Options are text or json (default "text") + --log-level string Log level to use. Options are debug, info, error, fatal (default "info") + --log-output string Log output path. Options are stderr or stdout. (default "stderr") + --log-overrides string Logger config overrides. Format ,=,...;,... + --log-source Include source location in logs + --log-stacktrace 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..322842a962 --- /dev/null +++ b/docs/cli/defradb_client_acp_policy_add.md @@ -0,0 +1,90 @@ +## defradb client acp policy add + +Add new policy + +### Synopsis + +Add new policy + +Notes: + - Can not add a policy without specifying an identity. + - ACP must be available (i.e. ACP can not be disabled). + - A non-DPI policy will be accepted (will be registered with acp system). + - But only a valid DPI policyID & resource can be specified on a schema. + - DPI validation happens when attempting to add a schema with '@policy'. + - Learn more about [ACP & DPI Rules](/acp/README.md) + +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 - + + + +``` +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 + --log-format string Log format to use. Options are text or json (default "text") + --log-level string Log level to use. Options are debug, info, error, fatal (default "info") + --log-output string Log output path. Options are stderr or stdout. (default "stderr") + --log-overrides string Logger config overrides. Format ,=,...;,... + --log-source Include source location in logs + --log-stacktrace 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 8049362250..492bb6a060 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 be7c24a858..ce2f6ff8ab 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_docIDs.md b/docs/cli/defradb_client_collection_docIDs.md index d15a7c453a..1ee91d7462 100644 --- a/docs/cli/defradb_client_collection_docIDs.md +++ b/docs/cli/defradb_client_collection_docIDs.md @@ -6,18 +6,22 @@ List all document IDs (docIDs). List all document IDs (docIDs). -Example: +Example: list all docID(s): defradb client collection docIDs --name User + +Example: list all docID(s), with an identity: + defradb client collection docIDs -i cosmos1f2djr7dl9vhrk3twt3xwqp09nhtzec9mdkf70j --name User ``` -defradb client collection docIDs [flags] +defradb client collection docIDs [-i --identity] [flags] ``` ### Options ``` - -h, --help help for docIDs + -h, --help help for docIDs + -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 432754b5e2..a73228829b 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 3b910d1a76..dd2d1864c3 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 d14886a59b..cd320e9de6 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 c0b4aa853a..dc72a6a354 100644 --- a/docs/cli/defradb_client_schema_add.md +++ b/docs/cli/defradb_client_schema_add.md @@ -6,6 +6,11 @@ Add new schema Add new schema. +Schema Object with a '@policy(id:".." resource: "..")' linked will only be accepted if: + - ACP is available (i.e. ACP is not disabled). + - The specified resource adheres to the Document Access Control DPI Rules. + - Learn more about [ACP & DPI Rules](/acp/README.md) + Example: add from an argument string: defradb client schema add 'type Foo { ... }'