Merge pull request dragonflyoss#266 from allencloud/polish-api

feature: polish API definition in swagger
yourmoonlight · Dec 20, 2018 · 24d6eec · 24d6eec
2 parents 54410e3 + 5f15cfc
commit 24d6eec
Show file tree

Hide file tree

Showing 15 changed files with 356 additions and 164 deletions.
diff --git a/apis/swagger.yml b/apis/swagger.yml
@@ -160,7 +160,8 @@ paths:
     put:
       summary: "update a task"
       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. 
       consumes:
           - "application/json"
       produces:
@@ -185,30 +186,13 @@ paths:
         500:
             $ref: "#/responses/500ErrorResponse"
 
-    delete:
-      summary: "delete a task"
-      description: |
-        delete a peer-to-peer task in supernode.
-      parameters:
-        - name: id
-          in: path
-          required: true
-          description: "ID of task"
-          type: string
-      responses:
-        204:
-          description: "no error"
-        404:
-          description: "no such peer"
-          schema:
-            $ref: '#/responses/404ErrorResponse'
-        500:
-          $ref: "#/responses/500ErrorResponse"
-
   /tasks/{id}/pieces:
     get:
       summary: "Get pieces in task"
-      description: "Get fixed number of pieces in a task. The number is set in query."
+      description: |
+        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.
       produces:
         - "application/json"
       parameters:
@@ -269,7 +253,11 @@ paths:
     put:
       summary: "Update a piece"
       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.
       consumes:
         - "application/json"
       produces:
@@ -397,27 +385,12 @@ definitions:
           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.
-        format: "int64"
-        minimum: 30000
-        maximum: 65535
-      callSystem:
-        type: "string"
-        description: |
-          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.
-        minLength: 1
+        format: "int32"
+        minimum: 15000
+        maximum: 65000
       version: 
         type: "string"
-        description: "version number of dfget binary"
-      dfdaemon:
-        type: "boolean"
-        description: "tells whether it is a call from dfdaemon."
-      path:
-        type: "string"
-        description: |
-          This is actually an HTTP URLPATH of dfget. 
-          Other peers can access the source file via this PATH.
+        description: "version number of dfget binary."
 
   PeerCreateResponse:
     type: "object"
@@ -449,27 +422,12 @@ definitions:
           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.
-        format: "int64"
-        minimum: 30000
-        maximum: 65535
-      callSystem:
-        type: "string"
-        description: |
-          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.
-        minLength: 1
+        minimum: 15000
+        maximum: 65000
+        format: "int32"
       version: 
         type: "string"
         description: "version number of dfget binary"
-      dfdaemon:
-        type: "boolean"
-        description: "tells whether it is a call from dfdaemon."
-      path:
-        type: "string"
-        description: |
-          This is actually an HTTP URLPATH of dfget. 
-          Other peers can access the source file via this PATH.
 
   TaskCreateRequest:
     type: "object"
@@ -500,6 +458,12 @@ definitions:
           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.
+      path:
+        type: "string"
+        description: |
+          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.
       headers:
         type: "object"
         description: |
@@ -509,6 +473,19 @@ definitions:
           from source server as user's wish.
         additionalProperties:
           type: "string"
+      dfdaemon:
+        type: "boolean"
+        description: |
+          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.
+      callSystem:
+        type: "string"
+        description: |
+          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.
+        minLength: 1
 
   TaskCreateResponse:
     type: "object"
@@ -517,22 +494,109 @@ definitions:
       ID:
         type: "string"
         description: "ID of the created task."
-
+      FileLength:
+        type: "integer"
+        description: |
+          The length of the file dfget requests to download in bytes.
+        format: int64
+      PieceSize:
+        type: "integer"
+        description: |
+          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.
+        format: int32
+
   TaskInfo:
     type: "object"
     description: "detailed information about task in supernode."
     properties:
       ID:
         type: "string"
         description: "ID of the task."
+      FileLength:
+        type: "integer"
+        description: |
+          The length of the file dfget requests to download in bytes.
+        format: "int64"
+      PieceSize:
+        type: "integer"
+        description: |
+          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.
+        format: "int32"
+      PieceTotal:
+        type: "integer"
+        description: ""
+        format: "int32"
+      CdnStatus:
+        type: "string"
+        description: |
+          The status of the created task related to CDN functionality.
+        enum: ["WAITING", "RUNNING", "FAILED", "SUCCESS", "SOURCE_ERROR"]
+      rawURL:
+        type: "string"
+        description: |
+          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.
+      taskURL:
+        type: "string"
+        description: |
+          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.
+      md5:
+        type: "string"
+        description: |
+          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.
+      identifier:
+        type: "string"
+        description: |
+          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.
+      path:
+        type: "string"
+        description: |
+          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.
+      headers:
+        type: "object"
+        description: |
+          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.
+        additionalProperties:
+          type: "string"
+      dfdaemon:
+        type: "boolean"
+        description: |
+          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.
+      callSystem:
+        type: "string"
+        description: |
+          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.
+        minLength: 1
+
 
   TaskUpdateRequest:
     type: "object"
     description: "request used to update task attributes."
     properties:
-      ID:
+      PeerID:
         type: "string"
-        description: "ID of the created task."
+        description: "ID of the peer which has finished to download the whole task."
 
   PieceInfo:
     type: "object"
@@ -544,11 +608,12 @@ definitions:
 
   PieceUpdateRequest:
     type: "object"
-    description: ""
+    description: "request peer uses to update its status of downloading piece in supernode."
     properties:
-      ID:
+      PeerID:
         type: "string"
-        description: ""
+        description: |
+          contains the peer ID.
 
   PreheatInfo:
     type: "object"

diff --git a/apis/types/error.go b/apis/types/error.go
diff --git a/apis/types/error_response.go b/apis/types/error_response.go
diff --git a/apis/types/peer_create_request.go b/apis/types/peer_create_request.go