feature: add interface for v0.3

Signed-off-by: Starnop <[email protected]>

apis/swagger.yml

@@ -44,6 +44,156 @@ paths:
         500:
           $ref: "#/responses/500ErrorResponse"
 
+  /peer/registry:
+    post:
+      summary: "registry a task"
+      description: |
+        Create a peer-to-peer downloading task in supernode.
+      parameters:
+        - name: "body"
+          in: "body"
+          description: "request body which contains task creation information"
+          schema:
+            $ref: "#/definitions/TaskRegisterRequest"
+      responses:
+        200:
+          description: "no error"
+          schema:
+            $ref: "#/definitions/ResultInfo"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: '#/definitions/Error'
+        500:
+          $ref: "#/responses/500ErrorResponse"
+
+  /peer/task:
+    get:
+      summary: "Get pieces in task"
+      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:
+        - name: taskId
+          in: query
+          required: true
+          description: "ID of task"
+          type: string
+        - name: srcCid
+          in: query
+          type: "string"
+          required: true
+          description:
+            When dfget needs to get pieces of specific task, it must mark which peer it plays role of.
+        - name: dstCid
+          in: query
+          type: "string"
+          description: |
+            the uploader cid
+        - name: status
+          type: "string"
+          in: query
+          description: |
+            dfgetTaskStatus indicates whether the dfgetTask is running.
+          enum: ["STARTED", "RUNNING", "FINISHED"]
+        - name: result
+          in: query
+          type: "string"
+          description: |
+            pieceResult It indicates whether the dfgetTask successfully download the piece. 
+            It's only useful when `status` is `RUNNING`.
+          enum: ["FAILED", "SUCCESS", "INVALID", "SEMISUC"]
+        - name: range
+          type: "string"
+          in: query
+          description: |
+            the range of specific piece in the task, example "0-45565".
+      responses:
+        200:
+          description: "no error"
+          schema:
+            $ref: "#/definitions/ResultInfo"
+        404:
+          description: "no such task"
+          schema:
+            $ref: "#/responses/404ErrorResponse"
+        500:
+          $ref: "#/responses/500ErrorResponse"
+
+  /peer/piece/suc:
+    get:
+      summary: "report a piece has been success"
+      description: |
+        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.
+      produces:
+        - "application/json"
+      parameters:
+        - name: taskId
+          in: query
+          required: true
+          description: "ID of task"
+          type: string
+        - name: pieceRange
+          in: query
+          required: true
+          description: |
+            the range of specific piece in the task, example "0-45565".
+          type: string
+        - name: cid
+          in: query
+          type: string
+          required: true
+          description: |
+            the downloader clientID
+        - name: dstCid
+          in: query
+          type: string
+          description: |
+            the uploader peerID
+      responses:
+        200:
+          description: "no error"
+          schema:
+            $ref: "#/definitions/ResultInfo"
+        404: 
+            $ref: "#/responses/404ErrorResponse"
+        500:
+            $ref: "#/responses/500ErrorResponse"
+
+  /peer/service/down:
+    get:
+      summary: "report a peer service will offline"
+      produces:
+        - "application/json"
+      parameters:
+        - name: taskId
+          in: query
+          required: true
+          description: "ID of task"
+          type: string
+        - name: cid
+          in: query
+          type: string
+          required: true
+          description: |
+            the downloader clientID
+      responses:
+        200:
+          description: "no error"
+          schema:
+            $ref: "#/definitions/ResultInfo"
+        404: 
+            $ref: "#/responses/404ErrorResponse"
+        500:
+            $ref: "#/responses/500ErrorResponse"
+
   /peers:
     post:
       summary: "register dfget in Supernode as a peer node"
@@ -417,6 +567,105 @@ definitions:
       message:
         type: string
 
+  ResultInfo: 
+    type: "object"
+    description: |
+      The returned information from supernode.
+    properties:
+      code:
+        type: "integer"
+        format: "int32"
+        description: "the result code"
+      msg:  
+        type: "string"
+        description: "the result msg"
+      data:
+        type: "object"
+        description: "the result data"
+
+  TaskRegisterRequest:
+    type: "object"
+    description: ""
+    properties:
+      IP:
+        type: "string"
+        description: "IP address which peer client carries"
+        format: "ipv4"
+      superNodeIp:
+         type: "string"
+         description: "IP address of supernode that the client can connect to"
+         format: "ipv4"
+      hostName:
+        type: "string"
+        description: "host name of peer client node, as a valid RFC 1123 hostname."
+        format: "hostname"
+        minLength: 1
+      port:
+        type: "integer"
+        description: |
+          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: "int32"
+        minimum: 15000
+        maximum: 65000
+      version: 
+        type: "string"
+        description: "version number of dfget binary."
+      cID:
+        type: "string"
+        description: |
+          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.
+      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
+          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.
+      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 recognizes.
+
   PeerCreateRequest:
     type: "object"
     description: |
@@ -493,6 +742,7 @@ definitions:
         type : "string"
         format : "date-time"
         description: "the time to join the P2P network"
+
   TaskCreateRequest:
     type: "object"
     description: ""
@@ -510,6 +760,11 @@ definitions:
           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: |