From f6f0e6fc7ea0f3e94fa8af13d69b665a3c722584 Mon Sep 17 00:00:00 2001 From: pouchrobot Date: Sat, 18 Apr 2020 01:24:46 +0000 Subject: [PATCH] docs: auto generate Dragonfly cli/api docs via code Signed-off-by: pouchrobot --- CONTRIBUTORS | 1 + docs/api_reference/apis.md | 116 +++++++++++++++++++++++++++++++++++++ 2 files changed, 117 insertions(+) diff --git a/CONTRIBUTORS b/CONTRIBUTORS index a083a8df1..3ef952f07 100644 --- a/CONTRIBUTORS +++ b/CONTRIBUTORS @@ -49,6 +49,7 @@ longfei.shang@daocloud.io lowzj Lu Fengqi lurenjia528 <37833630+lurenjia528@users.noreply.github.com> +moyasu Nguyen Hai Truong Nguyen Hai Truong pouchrobot diff --git a/docs/api_reference/apis.md b/docs/api_reference/apis.md index e86657af3..af860a778 100644 --- a/docs/api_reference/apis.md +++ b/docs/api_reference/apis.md @@ -549,6 +549,60 @@ json : ``` + +### report the heart beat to super node. +``` +POST /peer/heartbeat +``` + + +#### Description +This endpoint is mainly for reporting the heart beat to supernode. +And supernode could know if peer is alive in strem mode. + + +#### Parameters + +|Type|Name|Description|Schema| +|---|---|---|---| +|**Body**|**body**
*optional*|request body which contains base info of peer|[HeartBeatRequest](#heartbeatrequest)| + + +#### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|no error|[ResultInfo](#resultinfo)| +|**500**|An unexpected server error occurred.|[Error](#error)| + + + +### peer request the p2p network info from supernode. +``` +POST /peer/network +``` + + +#### Description +In the new mode which dfdaemon will provide the seed file so that other peers +could download. This endpoint is mainly for fetching the p2p network info. + + +#### Parameters + +|Type|Name|Description|Schema| +|---|---|---|---| +|**Body**|**body**
*optional*|request body which filter urls.|[NetworkInfoFetchRequest](#networkinfofetchrequest)| + + +#### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|no error|[NetworkInfoFetchResponse](#networkinfofetchresponse)| +|**500**|An unexpected server error occurred.|[Error](#error)| + + ### report a piece has been success ``` @@ -792,6 +846,51 @@ It contains a code that identify which error occurred for client processing and |**message**
*optional*|detailed error message|string| + +### HeartBeatRequest +The request is to report peer to supernode to keep alive. + + +|Name|Description|Schema| +|---|---|---| +|**IP**
*optional*|IP address which peer client carries|string (ipv4)| +|**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| +|**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)| + + + +### NetworkInfoFetchRequest +The request is to fetch p2p network info from supernode. + + +|Name|Description|Schema| +|---|---|---| +|**urls**
*optional*|The urls is to filter the peer node, the url should be match with taskURL in TaskInfo.|< string > array| + + + +### NetworkInfoFetchResponse +The response is from supernode to peer which is requested to fetch p2p network info. + + +|Name|Schema| +|---|---| +|**nodes**
*optional*|< [Node](#node) > array| + + + +### Node +The object shows the basic info of node and the task belongs to the node. + + +|Name|Description|Schema| +|---|---|---| +|**basic**
*optional*|Basic node info|[PeerInfo](#peerinfo)| +|**extra**
*optional*||< string, string > map| +|**load**
*optional*|The load of node, which as the schedule weight in peer schedule.|integer| +|**tasks**
*optional*||< [TaskFetchInfo](#taskfetchinfo) > array| + + ### PeerCreateRequest PeerCreateRequest is used to create a peer instance in supernode. @@ -948,6 +1047,7 @@ The returned information from supernode. |**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| +|**fileLength**
*optional*|This attribute represents the length of resource, dfdaemon or dfget catches and calculates
this parameter from the headers of request URL. If fileLength is vaild, the supernode need
not get the length of resource by accessing the rawURL.|integer (int64)| |**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| @@ -956,6 +1056,7 @@ The returned information from supernode. |**peerID**
*optional*|PeerID is used to uniquely identifies a peer which will be used to create a dfgetTask.
The value must be the value in the response after registering a peer.|string| |**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| |**supernodeIP**
*optional*|IP address of supernode which the peer connects to|string| +|**taskId**
*optional*|This attribute represents the digest of resource, dfdaemon or dfget catches this parameter
from the headers of request URL. The digest will be considered as the taskID if not null.|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| @@ -972,6 +1073,17 @@ response get from task creation request. |**pieceSize**
*optional*|The size of pieces which is calculated as per the following strategy
1. If file's total size is less than 200MB, then the piece size is 4MB by default.
2. Otherwise, it equals to the smaller value between totalSize/100MB + 2 MB and 15MB.|integer (int32)| + +### TaskFetchInfo +It shows the task info and pieces info. + + +|Name|Description|Schema| +|---|---|---| +|**pieces**
*optional*|The pieces which should belong to the peer node|< [PieceInfo](#pieceinfo) > array| +|**task**
*optional*||[TaskInfo](#taskinfo)| + + ### TaskInfo detailed information about task in supernode. @@ -980,6 +1092,7 @@ detailed information about task in supernode. |Name|Description|Schema| |---|---|---| |**ID**
*optional*|ID of the task.|string| +|**asSeed**
*optional*|This attribute represents the node as a seed node for the taskURL.|boolean| |**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| @@ -1015,9 +1128,11 @@ detailed information about task in supernode. |Name|Description|Schema| |---|---|---| |**IP**
*optional*|IP address which peer client carries|string (ipv4)| +|**asSeed**
*optional*|This attribute represents the node as a seed node for the taskURL.|boolean| |**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| +|**fileLength**
*optional*|This attribute represents the length of resource, dfdaemon or dfget catches and calculates
this parameter from the headers of request URL. If fileLength is vaild, the supernode need
not get the length of resource by accessing the rawURL.|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 > 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| @@ -1028,6 +1143,7 @@ detailed information about task in supernode. |**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| +|**taskId**
*optional*|Dfdaemon or dfget could specific the taskID which will represents the key of this resource
in supernode.|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|