implemented the basics of an extendible feedback architecture

TUM-Dev · Jun 5, 2023 · a597159 · a597159
1 parent c65c077
commit a597159
Show file tree

Hide file tree

Showing 10 changed files with 647 additions and 72 deletions.
diff --git a/openapi.yaml b/openapi.yaml
@@ -742,20 +742,87 @@ paths:
         - feedback
   /api/feedback/feedback:
     post:
-      operationId: feedback
+      operationId: post_feedback
       summary: Post feedback
       description: |
         ***Do not abuse this endpoint.***
 
         This posts the actual feedback to github and returns the github link.
+        This API will create issues instead of pull-requests => all feedback is allowed, but `/api/feedback/propose_edit` is prefered, if it can be posted there.
         For this Endpoint to work, you need to generate a token via the `/api/feedback/get_token` endpoint.
 
         ***Important Note:*** Tokens are only used if we return a 201 Created response. Otherwise, they are still valid
       requestBody:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/TokenRequest'
+              $ref: '#/components/schemas/PostFeedbackRequest'
+      responses:
+        '201':
+          description: |
+            The feedback has been successfully posted to GitHub.
+            We return the link to the GitHub issue.
+          content:
+            text/plain:
+              schema:
+                type: string
+                example: 'https://github.com/TUM-Dev/navigatum/issues/9'
+        '400':
+          description: If not all fields in the body are present as defined above
+        '403':
+          description: |
+            Forbidden. Causes are (delivered via the body):
+
+              - `Invalid token`: You have not supplied a token generated via the `gen_token`-Endpoint.
+              - `Token not old enough, please wait`: Tokens are only valid after 10s.
+              - `Token expired`: Tokens are only valid for 12h.
+              - `Token already used`: Tokens are non reusable/refreshable single-use items.
+          content:
+            text/plain:
+              schema:
+                type: string
+                enum:
+                  - Invalid token
+                  - 'Token not old enough, please wait'
+                  - Token expired
+                  - Token already used
+        '422':
+          description: |
+            Unprocessable Entity
+            Subject or body missing or too short.
+        '451':
+          description: |
+            Unavailable for legal reasons.
+            Using this endpoint without accepting the privacy policy is not allowed.
+            For us to post to GitHub, this has to be true
+        '500':
+          description: |
+            Internal Server Error.  
+            We have a problem communicating with GitHubs servers. Please try again later.
+        '503':
+          description: |
+            Service unavailable.  
+            We have not configured a GitHub Access Token.  
+            This could be because we are experiencing technical difficulties or intentional. Please try again later.
+      tags:
+        - feedback
+  /api/feedback/propose_edit:
+    post:
+      operationId: propose_edit
+      summary: Post Edit-Requests
+      description: |
+        ***Do not abuse this endpoint.***
+
+        This posts the actual feedback to github and returns the github link.
+        This API will create pull-requests instead of issues => only a subset of feedback is allowed.
+        For this Endpoint to work, you need to generate a token via the `/api/feedback/get_token` endpoint.
+
+        ***Important Note:*** Tokens are only used if we return a 201 Created response. Otherwise, they are still valid
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ProposeEditsRequest'
       responses:
         '201':
           description: |
@@ -1842,45 +1909,71 @@ components:
         - rank_combined
         - rank_type
         - rank_usage
+    ProposeEditsRequest:
+      allOf:
+        - $ref: '#/components/schemas/TokenRequest'
+        - type: object
+          properties:
+            edits:
+              description:
+                The edits to be made to the room.  
+                The keys are the ID of the props to be edited, the values are the proposed Edits.
+              type: object
+            additional_context:
+              type: string
+              description: |
+                Additional context for the edit.  
+                Will be displayed in the discription field of the PR
+              example: I have a picture of the room, please add it to the roomfinder
+          required:
+            - edits
+            - additional_context
+    PostFeedbackRequest:
+      allOf:
+        -   $ref: '#/components/schemas/TokenRequest'
+        -   type: object
+            properties:
+              category:
+                type: string
+                description: |-
+                  The category of the feedback.  
+                  Enum attribute is softly enforced: Any value not listed below will be replaced by "other"
+                enum:
+                  - bug
+                  - feature
+                  - search
+                  - entry
+                  - general
+                  - other
+                example: bug
+              subject:
+                type: string
+                description: The subject/title of the feedback
+                example: A catchy title
+                minLength: 4
+                maxLength: 512
+              body:
+                type: string
+                description: The body/description of the feedback
+                example: A clear description what happened where and how we should improve it
+                maxLength: 1048576
+                minLength: 4
+              privacy_checked:
+                type: boolean
+                example: true
+                description: Whether the user has checked the privacy-checkbox. We are posting the feedback publicly on GitHub (not a EU-Company). You have to also include such a checkmark.
+            required:
+              - category
+              - subject
+              - body
+              - privacy_checked
     TokenRequest:
       type: object
       properties:
         token:
           description: 'The JWT token, that can be used to generate feedback'
           type: string
           example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2Njk2MzczODEsImlhdCI6MTY2OTU5NDE4MSwibmJmIjoxNjY5NTk0MTkxLCJraWQiOjE1ODU0MTUyODk5MzI0MjU0Mzg2fQ.sN0WwXzsGhjOVaqWPe-Fl5x-gwZvh28MMUM-74MoNj4
-        category:
-          description: |
-            The category of the feedback.  
-            Enum attribute is softly enforced: Any value not listed below will be replaced by "other"
-          type: string
-          example: bug
-          enum:
-            - general
-            - bug
-            - feature
-            - search
-            - entry
-            - other
-        subject:
-          description: The subject/title of the feedback
-          type: string
-          example: A catchy title
-          maxLength: 512
-          minLength: 4
-        body:
-          description: The body/description of the feedback
-          type: string
-          example: A clear description what happened where and how we should improve it
-          maxLength: 1048576
-          minLength: 4
-        privacy_checked:
-          description: |
-            Whether the user has checked the privacy-checkbox.
-            We are posting the feedback publicly on GitHub (not a EU-Company). You have to also include such a checkmark.
-            For inspiration on how to do this, see our website.
-          type: boolean
-          example: true
         deletion_requested:
           description: |
             Whether the user has requested to delete the issue.
@@ -1890,10 +1983,6 @@ components:
           example: true
       required:
         - token
-        - category
-        - subject
-        - body
-        - privacy_checked
         - deletion_requested
 tags:
   - name: core

diff --git a/server/Cargo.lock b/server/Cargo.lock
diff --git a/server/feedback/Cargo.toml b/server/feedback/Cargo.toml
@@ -33,5 +33,8 @@ jsonwebtoken = "8.3.0"
 chrono= { version = "0.4.26", default-features = false }
 actix-governor = { version = "0.4.0", features = ["log"] }
 
+# proposing feedback
+tempfile = "3.5.0"
+
 [dev-dependencies]
 pretty_assertions.workspace = true