Skip to content
This repository was archived by the owner on Aug 15, 2025. It is now read-only.

Commit 0adf535

Browse files
bitfl0werbitfl0wer
committed
lots of new RawR resource manipulation routes
1 parent 6ac90cf commit 0adf535

File tree

2 files changed

+171
-4
lines changed

2 files changed

+171
-4
lines changed

‎api/src/core/main.tsp‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,31 @@ namespace models {
129129
* added if they were known to the server. An example file name might be
130130
* `2c851bfb6daffa944fa1723c7bd4d362ffbc9defe292f2daaf05e895989d179b.jxl`, referencing the file
131131
* which was hosted at `<server_url>/.p2/core/resource/2c851bfb6daffa944fa1723c7bd4d362ffbc9defe292f2daaf05e895989d179b.jxl`.
132+
* In addition, the folder `rawr` contains a file named `access_properties.p2al`. This JSON
133+
* file contains a data structure mapping each resource ID to an access properties object.
134+
* In particular, the file is structured as an array containing objects. Each object has a key which is equal
135+
* to the resource ID of a resource in the `rawr` directory and a value which is an object
136+
* representing the access properties. An example of the contents of this file is given below:
137+
*
138+
```json
139+
[
140+
{
141+
"2062a23e2a25b226ca4c546fec5ec06e0df9648281f45da8b5aaabebdf66cf4c.jxl": {
142+
"private": false,
143+
"allowlist": ["user1@example.com", "instance.example.com"],
144+
"denylist": ["user2@example.com", "otherinstance@example.com"]
145+
}
146+
},
147+
{
148+
"a9144379a161e1fcf6b07801b70db6d6c481933bd634fe2409eb713723ab1a0a": {
149+
"private": true,
150+
"allowlist": ["user1@example.com"],
151+
"denylist": []
152+
}
153+
}
154+
]
155+
```
156+
*
132157
* If the server where the data export was requested from is the actors' home server, the
133158
* archive will contain a folder `certs` and a file `crypt_certs.p2epk`. `certs` will contain all ID-Certs
134159
* the server has stored of the actor. The ID-Certs will be stored in
@@ -138,4 +163,30 @@ namespace models {
138163
* JSON file.
139164
*/
140165
model P2Export {}
166+
167+
/**
168+
* `ResourceAccessProperties` define which actors may access an uploaded resource. Actors and
169+
* entire instances can have access granted or revoked.
170+
*/
171+
model ResourceAccessProperties {
172+
@doc("Whether the resource should be private by default. Private resources can only be accessed by the uploader and by instances and actors declared in the `allowlist`.")
173+
private: boolean = false;
174+
@doc("A list of actors and/or instances allowed to access this resource.")
175+
@example(#["[email protected]", "instance.example.com"])
176+
allowlist?: string[];
177+
@doc("A list of actors and/or instances who cannot have access to this resource.")
178+
@example(#["[email protected]", "other_instance.example.com"])
179+
denylist?: string[];
180+
}
181+
182+
/**
183+
* When querying the server for a list of resources uploaded by you, you can optionally request
184+
* the resulting list to be sorted in a specific way. These are the four options you have.
185+
*/
186+
enum ResourceListSorting {
187+
SizeAsc,
188+
SizeDesc,
189+
NewestFirst,
190+
OldestFirst
191+
}
141192
}

‎api/src/core/routes/rawr.tsp‎

Lines changed: 120 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,27 @@ namespace ResourceAddressingWithRelativeRoots {
2828
* @param rid: Resource Identifier - unique identifier for a resource.
2929
* @returns
3030
* - `200`: File found and retrieved.
31+
* - `308`: URI root has changed.
3132
* - `401`: Server or resource requires authentication to access this endpoint.
3233
* - `403`: Server or resource not accessible for the actor making this request.
3334
* - `404`: Resource not found.
3435
*/
3536
op getResource(@path rid: string): {
36-
@statusCode _ : 403 | 401 | 404;
37-
} | {
3837
@statusCode _ : 200;
3938
@body body: File;
39+
} | {
40+
@statusCode _ : 308;
41+
@header({name: "Location"}) location: url;
42+
@body reason: "ROOT_CHANGED";
43+
} | {
44+
@statusCode _ : 403;
45+
@body reason: "ACCESS_FORBIDDEN"
46+
} | {
47+
@statusCode _ : 401;
48+
@body reason: "NEEDS_AUTHENTICATION"
49+
} | {
50+
@statusCode _ : 404;
51+
@body reason: "NOT_FOUND"
4052
};
4153
}
4254

@@ -47,8 +59,112 @@ namespace ResourceAddressingWithRelativeRoots {
4759
@post
4860
@added(Version.`v1.0-alpha.1`)
4961
@summary("Upload RawR resource")
50-
op postResource(@path rid: string, @header({name: "Content-Length"}) contentLength: uint64): {
51-
// TODO
62+
/**
63+
* Upload a [RawR](https://docs.polyphony.chat/Protocol%20Specifications/core/#731-resource-addressing-with-relative-roots)
64+
* resource to your home server.
65+
* @param rid: The resource ID of the resource you would like to upload.
66+
* @param resourceAccessProperties ResourceAccessProperties. See the corresponding schema definition for more information.
67+
* @param contentLength: The size of the resource in bytes.
68+
* @param file: The resource itself
69+
* @returns
70+
* - `204`: Upload successful.
71+
* - `403`: Uploading forbidden.
72+
* - `409`: RID already exists on this server. Choose a different RID.
73+
* - `411`: `Content-Length` header not specified.
74+
* - `413`: Resource too large.
75+
* - `414`: RID too long.
76+
*/
77+
op postResource(
78+
@path rid: string,
79+
@header({name: "Content-Length"}) contentLength: uint64,
80+
@query resourceAccessProperties: polyproto.core.models.ResourceAccessProperties,
81+
@body file: File;
82+
): {
83+
@statusCode _ : 403;
84+
@body reason: "UPLOAD_FORBIDDEN"
85+
} | {
86+
@statusCode _ : 409;
87+
@body reason: "DUPLICATE_RID"
88+
} | {
89+
@statusCode _ : 411;
90+
@body reason: "LENGTH_REQUIRED"
91+
} | {
92+
@statusCode _ : 413;
93+
@body body: {
94+
reason: "TOO_LARGE",
95+
@doc("The server may tell the client how much more content they are allowed to store, in bytes.")
96+
remainingStorageBytes?: uint64;
97+
}
98+
} | {
99+
@statusCode _ : 414;
100+
reason: "RID_TOO_LONG",
101+
charLimit: uint8 = 64;
102+
} | {
103+
@statusCode _ : 204;
104+
@header({name: "Content-Length"}) contentLength: 0;
105+
};
106+
107+
@route("/{rid}")
108+
@delete
109+
@added(Version.`v1.0-alpha.1`)
110+
@summary("Delete RawR resource")
111+
op deleteResource(@path rid: string): {
112+
@statusCode _ : 204;
113+
};
114+
115+
@route("/{rid}")
116+
@put
117+
@added(Version.`v1.0-alpha.1`)
118+
@summary("Update RawR resource access properties")
119+
/**
120+
* Replace the access properties of a [RawR](https://docs.polyphony.chat/Protocol%20Specifications/core/#731-resource-addressing-with-relative-roots)
121+
* resource with updated access properties.
122+
* @param rid The resource ID of the resource which the access properties should be modified of.
123+
* @param resourceAccessProperties ResourceAccessProperties. See the corresponding schema definition for more information.
124+
*/
125+
op modifyResource(@path rid: string, @body resourceAccessProperties: polyproto.core.models.ResourceAccessProperties): {
126+
@header({name: "Content-Length"}) contentLength: 0;
127+
@statusCode _ : 204;
128+
};
129+
130+
@route("/{rid}/info/")
131+
@get
132+
@added(Version.`v1.0-alpha.1`)
133+
@summary("Retrieve information about one of your RawR resources")
134+
/**
135+
* @param rid The resource ID of the resource which you'd like to query information of.
136+
*/
137+
op getResourceInfos(@path rid: string): {
138+
@statusCode statusCode : 200;
139+
@body body : {
140+
resourceId: string,
141+
size: uint64,
142+
access: polyproto.core.models.ResourceAccessProperties
143+
}[]
144+
} | {
145+
@statusCode statusCode : 404;
146+
@body reason: "NOT_FOUND";
147+
};
148+
149+
@route("/resources")
150+
@get
151+
@added(Version.`v1.0-alpha.1`)
152+
@summary("List your uploaded resources")
153+
/**
154+
* Query the server for a list of resources you've uploaded.
155+
* @param limit Optional; How many results you'd like to retrieve at maximum. Defaults to `50`.
156+
* @param sort Whether the list should be sorted in a specific way. Available options are `SizeAsc`, `SizeDesc`, `NewestFirst` and `OldestFirst`.
157+
*/
158+
op getResourceList(@query limit?: uint32 = 50, @query sort?: polyproto.core.models.ResourceListSorting): {
159+
@statusCode statusCode : 200;
160+
@body body : {
161+
resourceId: string,
162+
size: uint64,
163+
access: polyproto.core.models.ResourceAccessProperties
164+
}[]
165+
} | {
166+
@statusCode _ : 204;
167+
@header({name: "Content-Length"}) contentLength: 0;
52168
};
53169
}
54170

0 commit comments

Comments
 (0)