File sharing server for small files
https://postit.piggo.space
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
131 lines
3.8 KiB
131 lines
3.8 KiB
# PostIt file sharing server
|
|
|
|
PostIt is designed to work as a temporary public storage for text (and other)
|
|
files uploaded to it by software that need a publicly reachable page without
|
|
hosting its own server or even having a public IP.
|
|
|
|
The primary use case is to share diagnostic and contextual information
|
|
produced by Fediverse bots (think an interactive game where the game board
|
|
is rendered to an image or a text file on demand). There are sure to be many
|
|
other uses I didn't think of.
|
|
|
|
The server internally uses hash-based de-duplication with reference counting.
|
|
If the same file is uploaded more than once, only one copy is stored in memory
|
|
(and on disk).
|
|
|
|
The uploaded files have a lifetime of 10 minutes, which can be shortened or
|
|
extended up to 1 hour (or more, as configured). If file-backed persistence
|
|
is enabled (off by default), all uploaded (non-expired) files will survive
|
|
server restart.
|
|
|
|
## Config file
|
|
|
|
The server application reads a config file, called `postit.json` by default.
|
|
The file path can be set by a CLI argument (see `--help`).
|
|
|
|
Call the binary with `--default-config` to dump the default JSON. See `src/config.rs`
|
|
for documentation of the format.
|
|
|
|
The JSON file uses the JSON5 format - comments are allowed.
|
|
|
|
## Uploading a file
|
|
|
|
To upload a file, send a POST request to the running PostIt server.
|
|
|
|
```none
|
|
$ curl -X POST --data-binary @RICKROLL.txt 0.0.0.0:7745 -i
|
|
HTTP/1.1 200 OK
|
|
X-Secret: 5273d775746e393b
|
|
X-Expire: 599
|
|
|
|
421d082ef85827ea
|
|
```
|
|
|
|
Take note of the `X-Secret` header, you will need it to update or delete the file.
|
|
|
|
If you only want to share the file, this is all you need. Grab the file ID from the response body
|
|
and share it. The URL is `/<FILE_ID>`, e.g.
|
|
|
|
```none
|
|
$ curl -X GET 0.0.0.0:7745/421d082ef85827ea -i
|
|
HTTP/1.1 200 OK
|
|
Content-Type: text/plain; charset=utf8
|
|
Cache-Control: public, max-age=459
|
|
X-Expire: 459
|
|
Content-Length: 688
|
|
|
|
File content here...
|
|
```
|
|
|
|
### Content type
|
|
|
|
The server attempts to auto-detect the file's `Content-Type`. The fallback is `text/plain`.
|
|
If you wish to set a custom type, use the `Content-Type` header when uploading the file, e.g.
|
|
|
|
```
|
|
$ curl -X POST --data-binary @RICKROLL.txt 0.0.0.0:7745 -i -H 'Content-Type: application/json'
|
|
HTTP/1.1 200 OK
|
|
X-Secret: 5273d775746e393b
|
|
X-Expire: 599
|
|
|
|
421d082ef85827ea
|
|
```
|
|
|
|
### Expiration time
|
|
|
|
To customize the expiration time, use the header `X-Expire: <secs>`, or a URL parameter `?expire=<secs>` e.g.
|
|
|
|
```
|
|
$ curl -X POST --data-binary @RICKROLL.txt 0.0.0.0:7745 -i -H 'X-Expire: 60'
|
|
HTTP/1.1 200 OK
|
|
X-Secret: 5273d775746e393b
|
|
X-Expire: 59
|
|
|
|
421d082ef85827ea
|
|
```
|
|
|
|
## Updating a file
|
|
|
|
A file you uploaded can be deleted or modified using the **secret token** obtained in respose to its upload.
|
|
Send the token as the `X-Secret` header, or GET argument `?secret=....`
|
|
|
|
File is updated by sending a `PUT` request to the file's URL.
|
|
|
|
The `PUT` request can change file expiration (`X-Expire: <secs>` or a URL parameter `?expire=<secs>`),
|
|
update its `Content-Type` (by sending the header), or replace its content.
|
|
|
|
Note that sending `PUT` with empty body will *not* clear the file, in that case the file content is
|
|
not changed at all. This can be used to extend a file's expiration without changing it in any other way
|
|
(by sending the `X-Expire` header).
|
|
|
|
Example, changing `Content-Type`:
|
|
|
|
```none
|
|
$ curl -X PUT 0.0.0.0:7745/08b515d619419115 -i -H'Content-Type:image/ascii' -H'X-Secret:32064a5fdb0ca799'
|
|
HTTP/1.1 200 OK
|
|
|
|
Updated OK.
|
|
```
|
|
|
|
Example, changing the expiration time:
|
|
|
|
```none
|
|
$ curl -X PUT 0.0.0.0:7745/08b515d619419115 -i -H'X-Expire:600' -H'X-Secret:32064a5fdb0ca799'
|
|
HTTP/1.1 200 OK
|
|
X-Expire: 599
|
|
|
|
Updated OK.
|
|
```
|
|
|
|
## Deleting a file
|
|
|
|
The `DELETE` verb, unsurprisingly, deletes a file. As with `PUT`, the secret token is required.
|
|
|
|
```
|
|
$ curl -XDELETE 0.0.0.0:7745/08b515d619419115 -i -H'X-Secret:32064a5fdb0ca799'
|
|
HTTP/1.1 200 OK
|
|
|
|
Deleted.
|
|
```
|
|
|
|
.
|
|
|