# 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 text file on demand). There are sure to be many 
other uses I didn't think of.

The uploaded files have a lifetime of 10 minutes, which can be shortened or 
extended up to 1 hour (or more, as configured).

## 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
Content-Length: 16

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
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'
```

### Expiration time

To customize the expiration time, use the header `X-Expire: <seconds>`, or a GET argument `?expire=<seconds>` e.g. 

```
$ curl -X POST --data-binary @RICKROLL.txt 0.0.0.0:7745 -i -H 'X-Expire: 60'
```

## 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 GET arg `expire`), 
update its `Content-Type`, 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 file's expiration without changing it in any other way
(by sending the `X-Expire` header). 

## Deleting a file

The `DELETE` verb, unsurprisingly, deletes a file. As with `PUT`, the secret token is required.

.