Merge branch 'main' of https://github.com/polyphony-chat/docs

Author: bitfl0wer

api/build/core-openapi3.yaml

@@ -84,6 +84,18 @@ paths:
           description: |-
             - `202` and a key trial, if one still needs to be passed
             - `200` and the appropriate data if the key trial has been passed and is not yet expired.
+            The data is a gzipped tarball (.tar.gz) named `[email protected]`, where
+            - `export[numbers]` is the word `export` with 20 random digits appended to it
+            - `user` is the actors' name
+            - `subdomain.example.com` is the FQDN of the server the actor is 
+            This file archive contains a file `messages.json` which is a JSON `MessageBatch` of all
+            messages sent by the user. Note the [definition of the word "message" in polyproto](https://docs.polyphony.chat/Protocol%20Specifications/core/#:~:text=software%20for%20clients.-,message%2C%20messages,-%3A%20In%20the%20context).
+            If the server where the data export was requested from has [RawR](https://docs.polyphony.chat/Protocol%20Specifications/core/#731-resource-addressing-with-relative-roots)
+            enabled, the file archive will contain a folder named `rawr`. This folder contains all
+            RawR-content uploaded by the actor to that server. The files in this folder are named after
+            the resource ID. File extensions are only added if they were known to the server. An
+            example file name might be `2c851bfb6daffa944fa1723c7bd4d362ffbc9defe292f2daaf05e895989d179b.jxl`,
+            referencing the file which was hosted at `<server_url>/.p2/core/resource/2c851bfb6daffa944fa1723c7bd4d362ffbc9defe292f2daaf05e895989d179b.jxl`.
             - `204` if the server needs time to gather the data. A `Retry-After` header is included in
             the response, indicating to the actor the point in time at which they should query this
             endpoint again. If this point in time is after the expiry timestamp of the completed key trial,
@@ -92,40 +104,23 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  type: object
-                  required:
-                    - idCert
-                    - messages
-                  properties:
-                    idCert:
-                      type: string
-                      description: The ID-Cert that the following messages' signatures correspond to.
-                    messages:
-                      type: array
-                      items:
-                        type: object
-                        properties:
-                          signature:
-                            type: string
-                            description: Signature of the whole message
-                          content:
-                            type: string
-                            description: Arbitrary content `T`. This depends on the specific implementation or extension of the protocol.
-                        required:
-                          - signature
-                          - content
-                      description: The actual message.
-                  description: |-
-                    A message batch, as received from and sent to the server in the context of re-signing messages.
-                    This type is generic over `T`, where `T` represents the content of the actual message. This
-                    means, that the specific message content depends on the concrete implementation or extension
-                    of the polyproto protocol.
+                $ref: '#/components/schemas/TypeSpec.Http.File'
         '202':
           description: |-
             - `202` and a key trial, if one still needs to be passed
             - `200` and the appropriate data if the key trial has been passed and is not yet expired.
+            The data is a gzipped tarball (.tar.gz) named `[email protected]`, where
+            - `export[numbers]` is the word `export` with 20 random digits appended to it
+            - `user` is the actors' name
+            - `subdomain.example.com` is the FQDN of the server the actor is 
+            This file archive contains a file `messages.json` which is a JSON `MessageBatch` of all
+            messages sent by the user. Note the [definition of the word "message" in polyproto](https://docs.polyphony.chat/Protocol%20Specifications/core/#:~:text=software%20for%20clients.-,message%2C%20messages,-%3A%20In%20the%20context).
+            If the server where the data export was requested from has [RawR](https://docs.polyphony.chat/Protocol%20Specifications/core/#731-resource-addressing-with-relative-roots)
+            enabled, the file archive will contain a folder named `rawr`. This folder contains all
+            RawR-content uploaded by the actor to that server. The files in this folder are named after
+            the resource ID. File extensions are only added if they were known to the server. An
+            example file name might be `2c851bfb6daffa944fa1723c7bd4d362ffbc9defe292f2daaf05e895989d179b.jxl`,
+            referencing the file which was hosted at `<server_url>/.p2/core/resource/2c851bfb6daffa944fa1723c7bd4d362ffbc9defe292f2daaf05e895989d179b.jxl`.
             - `204` if the server needs time to gather the data. A `Retry-After` header is included in
             the response, indicating to the actor the point in time at which they should query this
             endpoint again. If this point in time is after the expiry timestamp of the completed key trial,
@@ -139,6 +134,18 @@ paths:
           description: |-
             - `202` and a key trial, if one still needs to be passed
             - `200` and the appropriate data if the key trial has been passed and is not yet expired.
+            The data is a gzipped tarball (.tar.gz) named `[email protected]`, where
+            - `export[numbers]` is the word `export` with 20 random digits appended to it
+            - `user` is the actors' name
+            - `subdomain.example.com` is the FQDN of the server the actor is 
+            This file archive contains a file `messages.json` which is a JSON `MessageBatch` of all
+            messages sent by the user. Note the [definition of the word "message" in polyproto](https://docs.polyphony.chat/Protocol%20Specifications/core/#:~:text=software%20for%20clients.-,message%2C%20messages,-%3A%20In%20the%20context).
+            If the server where the data export was requested from has [RawR](https://docs.polyphony.chat/Protocol%20Specifications/core/#731-resource-addressing-with-relative-roots)
+            enabled, the file archive will contain a folder named `rawr`. This folder contains all
+            RawR-content uploaded by the actor to that server. The files in this folder are named after
+            the resource ID. File extensions are only added if they were known to the server. An
+            example file name might be `2c851bfb6daffa944fa1723c7bd4d362ffbc9defe292f2daaf05e895989d179b.jxl`,
+            referencing the file which was hosted at `<server_url>/.p2/core/resource/2c851bfb6daffa944fa1723c7bd4d362ffbc9defe292f2daaf05e895989d179b.jxl`.
             - `204` if the server needs time to gather the data. A `Retry-After` header is included in
             the response, indicating to the actor the point in time at which they should query this
             endpoint again. If this point in time is after the expiry timestamp of the completed key trial,
@@ -1240,6 +1247,18 @@ paths:
         - {}
 components:
   schemas:
+    TypeSpec.Http.File:
+      type: object
+      required:
+        - contents
+      properties:
+        contentType:
+          type: string
+        filename:
+          type: string
+        contents:
+          type: string
+          format: byte
     Version:
       type: string
       enum: