From 4a069e2cb3ec2798726670c69389d3929a085228 Mon Sep 17 00:00:00 2001 From: pouchrobot Date: Mon, 12 Aug 2019 01:24:47 +0000 Subject: [PATCH] docs: auto generate Dragonfly cli/api docs via code Signed-off-by: pouchrobot --- CONTRIBUTORS | 1 + docs/api_reference/apis.md | 10 ++++++---- docs/cli_reference/dfget.md | 2 ++ 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTORS b/CONTRIBUTORS index dff74121f..b123f2f89 100644 --- a/CONTRIBUTORS +++ b/CONTRIBUTORS @@ -52,6 +52,7 @@ Yizheng Jiao yuansmin yunfeiyangbuaa zhangyue +zhouchencheng zhouhaibing089 zhoulin xie zou sheng diff --git a/docs/api_reference/apis.md b/docs/api_reference/apis.md index 38b3275d4..fee28399d 100644 --- a/docs/api_reference/apis.md +++ b/docs/api_reference/apis.md @@ -854,11 +854,11 @@ The returned information from supernode. |Name|Description|Schema| |---|---|---| -|**cID**
*optional*|CID means the client ID. It maps to the specific dfget process.
When user wishes to download an image/file, user would start a dfget process to do this.
This dfget is treated a client and carries a client ID.
Thus, multiple dfget processes on the same peer have different CIDs.|string| +|**cID**
*optional*|CID means the client ID. It maps to the specific dfget process.
When user wishes to download an image/file, user would start a dfget process to do this.
This dfget is treated a client and carries a client ID.
Thus, multiple dfget processes on the same peer have different CIDs.|string| |**callSystem**
*optional*|This attribute represents where the dfget requests come from. Dfget will pass
this field to supernode and supernode can do some checking and filtering via
black/white list mechanism to guarantee security, or some other purposes like debugging.
**Minimum length** : `1`|string| |**dfdaemon**
*optional*|tells whether it is a call from dfdaemon. dfdaemon is a long running
process which works for container engines. It translates the image
pulling request into raw requests into those dfget recognizes.|boolean| -|**filter**
*optional*|filter is used to filter request queries in URL.
For example, when a user wants to start to download a task which has a remote URL of
a.b.com/fileA?user=xxx&auth=yyy, user can add a filter parameter ["user", "auth"]
to filter the url to a.b.com/fileA. Then this parameter can potentially avoid repeatable
downloads, if there is already a task a.b.com/fileA.|< string > array| -|**headers**
*optional*|extra HTTP headers sent to the rawURL.
This field is carried with the request to supernode.
Supernode will extract these HTTP headers, and set them in HTTP downloading requests
from source server as user's wish.|< string, string > map| +|**filter**
*optional*|filter is used to filter request queries in URL.
For example, when a user wants to start to download a task which has a remote URL of
a.b.com/fileA?user=xxx&auth=yyy, user can add a filter parameter ["user", "auth"]
to filter the url to a.b.com/fileA. Then this parameter can potentially avoid repeatable
downloads, if there is already a task a.b.com/fileA.|< string > array| +|**headers**
*optional*|extra HTTP headers sent to the rawURL.
This field is carried with the request to supernode.
Supernode will extract these HTTP headers, and set them in HTTP downloading requests
from source server as user's wish.|< string, string > map| |**identifier**
*optional*|special attribute of remote source file. This field is used with taskURL to generate new taskID to
identify different downloading task of remote source file. For example, if user A and user B uses
the same taskURL and taskID to download file, A and B will share the same peer network to distribute files.
If user A additionally adds an identifier with taskURL, while user B still carries only taskURL, then A's
generated taskID is different from B, and the result is that two users use different peer networks.|string| |**md5**
*optional*|md5 checksum for the resource to distribute. dfget catches this parameter from dfget's CLI
and passes it to supernode. When supernode finishes downloading file/image from the source location,
it will validate the source file with this md5 value to check whether this is a valid file.|string| |**path**
*optional*|path is used in one peer A for uploading functionality. When peer B hopes
to get piece C from peer A, B must provide a URL for piece C.
Then when creating a task in supernode, peer A must provide this URL in request.|string| @@ -890,7 +890,7 @@ detailed information about task in supernode. |**ID**
*optional*|ID of the task.|string| |**cdnStatus**
*optional*|The status of the created task related to CDN functionality.|enum (WAITING, RUNNING, FAILED, SUCCESS, SOURCE_ERROR)| |**fileLength**
*optional*|The length of the file dfget requests to download in bytes
which including the header and the trailer of each piece.|integer (int64)| -|**headers**
*optional*|extra HTTP headers sent to the rawURL.
This field is carried with the request to supernode.
Supernode will extract these HTTP headers, and set them in HTTP downloading requests
from source server as user's wish.|< string, string > map| +|**headers**
*optional*|extra HTTP headers sent to the rawURL.
This field is carried with the request to supernode.
Supernode will extract these HTTP headers, and set them in HTTP downloading requests
from source server as user's wish.|< string, string > map| |**httpFileLength**
*optional*|The length of the source file in bytes.|integer (int64)| |**identifier**
*optional*|special attribute of remote source file. This field is used with taskURL to generate new taskID to
identify different downloading task of remote source file. For example, if user A and user B uses
the same taskURL and taskID to download file, A and B will share the same peer network to distribute files.
If user A additionally adds an identifier with taskURL, while user B still carries only taskURL, then A's
generated taskID is different from B, and the result is that two users use different peer networks.|string| |**md5**
*optional*|md5 checksum for the resource to distribute. dfget catches this parameter from dfget's CLI
and passes it to supernode. When supernode finishes downloading file/image from the source location,
it will validate the source file with this md5 value to check whether this is a valid file.|string| @@ -913,10 +913,12 @@ detailed information about task in supernode. |**headers**
*optional*|extra HTTP headers sent to the rawURL.
This field is carried with the request to supernode.
Supernode will extract these HTTP headers, and set them in HTTP downloading requests
from source server as user's wish.|< string > array| |**hostName**
*optional*|host name of peer client node.
**Minimum length** : `1`|string| |**identifier**
*optional*|special attribute of remote source file. This field is used with taskURL to generate new taskID to
identify different downloading task of remote source file. For example, if user A and user B uses
the same taskURL and taskID to download file, A and B will share the same peer network to distribute files.
If user A additionally adds an identifier with taskURL, while user B still carries only taskURL, then A's
generated taskID is different from B, and the result is that two users use different peer networks.|string| +|**insecure**
*optional*|tells whether skip secure verify when supernode download the remote source file.|boolean| |**md5**
*optional*|md5 checksum for the resource to distribute. dfget catches this parameter from dfget's CLI
and passes it to supernode. When supernode finishes downloading file/image from the source location,
it will validate the source file with this md5 value to check whether this is a valid file.|string| |**path**
*optional*|path is used in one peer A for uploading functionality. When peer B hopes
to get piece C from peer A, B must provide a URL for piece C.
Then when creating a task in supernode, peer A must provide this URL in request.|string| |**port**
*optional*|when registering, dfget will setup one uploader process.
This one acts as a server for peer pulling tasks.
This port is which this server listens on.
**Minimum value** : `15000`
**Maximum value** : `65000`|integer (int32)| |**rawURL**
*optional*|The is the resource's URL which user uses dfget to download. The location of URL can be anywhere, LAN or WAN.
For image distribution, this is image layer's URL in image registry.
The resource url is provided by command line parameter.|string| +|**rootCAs**
*optional*|The root ca cert from client used to download the remote source file.|< string (byte) > array| |**superNodeIp**
*optional*|The address of supernode that the client can connect to|string| |**taskURL**
*optional*|taskURL is generated from rawURL. rawURL may contains some queries or parameter, dfget will filter some queries via
--filter parameter of dfget. The usage of it is that different rawURL may generate the same taskID.|string| |**version**
*optional*|version number of dfget binary.|string| diff --git a/docs/cli_reference/dfget.md b/docs/cli_reference/dfget.md index 3bf5f0389..7f2eaaab4 100644 --- a/docs/cli_reference/dfget.md +++ b/docs/cli_reference/dfget.md @@ -33,6 +33,7 @@ download SUCCESS(0) cost:0.026s length:141898 reason:0 ``` --alivetime duration Alive duration for which uploader keeps no accessing by any uploading requests, after this period uploader will automically exit (default 5m0s) + --cacerts strings The cacert file which is used to verify remote server when supernode interact with the source. --callsystem string The name of dfget caller which is for debugging. Once set, it will be passed to all components around the request to make debugging easy --clientqueue int specify the size of client queue which controls the number of pieces that can be processed simultaneously (default 6) --console show log on console, it's conflict with '--showbar' @@ -44,6 +45,7 @@ download SUCCESS(0) cost:0.026s length:141898 reason:0 --header strings http header, eg: --header='Accept: *' --header='Host: abc' -h, --help help for dfget -i, --identifier string The usage of identifier is making different downloading tasks generate different downloading task IDs even if they have the same URLs. conflict with --md5. + --insecure identify whether supernode should skip secure verify when interact with the source. --ip string IP address that server will listen on -s, --locallimit string network bandwidth rate limit for single download task, in format of 20M/m/K/k -m, --md5 string md5 value input from user for the requested downloading file to enhance security