implemented the basics of an extendible feedback architecture

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

Hide file tree

Showing 10 changed files with 647 additions and 80 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,59 +1909,79 @@ 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:
+              description: |
+                Additional context for the edit.  
+                Will be displayed in the discription field of the PR
+              type: string
+              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:
+              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:
+                - bug
+                - feature
+                - search
+                - entry
+                - general
+                - 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
+            deletion_requested:
+              description: |
+                Whether the user has requested to delete the issue.
+                If the user has requested to delete the issue, we will delete it from GitHub after processing it
+                If the user has not requested to delete the issue, we will not delete it from GitHub and it will remain as a closed issue.
+              type: boolean
+              example: true
+          required:
+            - category
+            - subject
+            - body
+            - deletion_requested
     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.
-            If the user has requested to delete the issue, we will delete it from GitHub after processing it
-            If the user has not requested to delete the issue, we will not delete it from GitHub and it will remain as a closed issue.
+          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.
           type: boolean
           example: true
       required:
         - token
-        - category
-        - subject
-        - body
         - privacy_checked
-        - deletion_requested
 tags:
   - name: core
     description: the API to access/search for room information

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