From e2e760f020b4042f4b86371f6883ffe39f78e20b Mon Sep 17 00:00:00 2001 From: pouchrobot Date: Fri, 21 Dec 2018 01:28:27 +0000 Subject: [PATCH] docs: auto generate pouch cli docs via code Signed-off-by: pouchrobot --- docs/apis.md | 79 ++++++++++++++++++++++++---------------------------- 1 file changed, 36 insertions(+), 43 deletions(-) diff --git a/docs/apis.md b/docs/apis.md index fb7d91788..d0ad3f4ce 100644 --- a/docs/apis.md +++ b/docs/apis.md @@ -197,7 +197,11 @@ PUT /pieces/{id} #### Description -Update some information of piece, like status of piece. +Update some information of piece. When peer A finishes to download +piece B, A must send request to supernode to update piece B's info +to mark that peer A has the complete piece B. Then when other peers +request to download this piece B, supernode could schedule peer A +to those peers. #### Parameters @@ -378,7 +382,8 @@ PUT /tasks/{id} #### Description -update information of a task. +update information of a task. When a peer finishes to download all pieces of a task, +it must update peer downloading status of this task in supernode. #### Parameters @@ -408,33 +413,6 @@ update information of a task. * `application/json` - -### delete a task -``` -DELETE /tasks/{id} -``` - - -#### Description -delete a peer-to-peer task in supernode. - - -#### Parameters - -|Type|Name|Description|Schema| -|---|---|---|---| -|**Path**|**id**
*required*|ID of task|string| - - -#### Responses - -|HTTP Code|Description|Schema| -|---|---|---| -|**204**|no error|No Content| -|**404**|no such peer|[4ErrorResponse](#4errorresponse)| -|**500**|An unexpected server error occurred.|[Error](#error)| - - ### Get pieces in task ``` @@ -443,7 +421,9 @@ GET /tasks/{id}/pieces #### Description -Get fixed number of pieces in a task. The number is set in query. +When dfget starts to download pieces of a task, it should get fixed +number of pieces in a task and the use pieces information to download +the pirces. The request piece number is set in query. #### Parameters @@ -503,12 +483,9 @@ it will send PeerCreateRequest to supernode. |---|---|---| |**ID**
*optional*|Peer ID of dfget client. Every peer has a unique ID among peer network.|string| |**IP**
*optional*|IP address which peer client carries|string (ipv4)| -|**callSystem**
*optional*|This field is for debugging. When caller of dfget is using it to files, he can pass callSystem
name to dfget. When this field is passing to supernode, supernode has ability to filter them via
some black/white list to guarantee security, or some other purposes.
**Minimum length** : `1`|string| -|**dfdaemon**
*optional*|tells whether it is a call from dfdaemon.|boolean| |**hostName**
*optional*|host name of peer client node, as a valid RFC 1123 hostname.
**Minimum length** : `1`|string (hostname)| -|**path**
*optional*|This is actually an HTTP URLPATH of dfget.
Other peers can access the source file via this PATH.|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** : `30000`
**Maximum value** : `65535`|integer (int64)| -|**version**
*optional*|version number of dfget binary|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)| +|**version**
*optional*|version number of dfget binary.|string| @@ -530,11 +507,8 @@ The detailed information of a peer in supernode. |---|---|---| |**ID**
*optional*|ID of peer|string| |**IP**
*optional*|IP address which peer client carries|string (ipv4)| -|**callSystem**
*optional*|This field is for debugging. When caller of dfget is using it to files, he can pass callSystem
name to dfget. When this field is passing to supernode, supernode has ability to filter them via
some black/white list to guarantee security, or some other purposes.
**Minimum length** : `1`|string| -|**dfdaemon**
*optional*|tells whether it is a call from dfdaemon.|boolean| |**hostName**
*optional*|host name of peer client node, as a valid RFC 1123 hostname.
**Minimum length** : `1`|string (hostname)| -|**path**
*optional*|This is actually an HTTP URLPATH of dfget.
Other peers can access the source file via this PATH.|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** : `30000`
**Maximum value** : `65535`|integer (int64)| +|**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)| |**version**
*optional*|version number of dfget binary|string| @@ -550,10 +524,12 @@ Peer's detailed information in supernode. ### PieceUpdateRequest +request peer uses to update its status of downloading piece in supernode. -|Name|Schema| -|---|---| -|**ID**
*optional*|string| + +|Name|Description|Schema| +|---|---|---| +|**PeerID**
*optional*|contains the peer ID.|string| @@ -599,9 +575,12 @@ task because that an image may have more than one layer. |Name|Description|Schema| |---|---|---| +|**callSystem**
*optional*|This field is for debugging. When caller of dfget is using it to files, he can pass callSystem
name to dfget. When this field is passing to supernode, supernode has ability to filter them via
some black/white list to guarantee security, or some other purposes.
**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 recganises.|boolean| |**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
indetify 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 indentifier 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| |**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| |**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| @@ -613,7 +592,9 @@ response get from task creation request. |Name|Description|Schema| |---|---|---| +|**FileLength**
*optional*|The length of the file dfget requests to download in bytes.|integer (int64)| |**ID**
*optional*|ID of the created task.|string| +|**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)| @@ -623,7 +604,19 @@ detailed information about task in supernode. |Name|Description|Schema| |---|---|---| +|**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.|integer (int64)| |**ID**
*optional*|ID of the task.|string| +|**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)| +|**PieceTotal**
*optional*||integer (int32)| +|**callSystem**
*optional*|This field is for debugging. When caller of dfget is using it to files, he can pass callSystem
name to dfget. When this field is passing to supernode, supernode has ability to filter them via
some black/white list to guarantee security, or some other purposes.
**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 recganises.|boolean| +|**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
indetify 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 indentifier 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| +|**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| +|**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| @@ -633,7 +626,7 @@ request used to update task attributes. |Name|Description|Schema| |---|---|---| -|**ID**
*optional*|ID of the created task.|string| +|**PeerID**
*optional*|ID of the peer which has finished to download the whole task.|string|