# 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 `/`, 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: `, or a URL parameter `?expire=` 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: ` or a URL parameter `?expire=`), 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. ``` .