WIP

README.md

@@ -1,26 +1,153 @@
 # Pastable
 
-Pastable is a free and open-source Plabble initiative to Pastebin.
+Pastable is a free and open-source Plabble initiative for sharing text, code, short links, and one-time secrets.
+
+## Run locally
+
+With Rust and Cargo installed:
+
+```sh
+cargo run
+```
+
+The server listens on `0.0.0.0:3000` and is available locally at `http://localhost:3000`.
+
+On startup, the server creates the SQLite database and initializes its tables before accepting requests.
+The default database is `pastable.db` in the working directory. Set `DATABASE_URL` to use a different location:
+
+```sh
+DATABASE_URL=sqlite://data.db cargo run
+```
+
+Route handlers can access the shared database pool with the `State(pool): State<SqlitePool>` extractor.
 
 ## Features
-- Paste text and code
-    - Optional expiration
-    - Self destruct option (view N times)
-- URL shortener
-- One-time password share
 
-## Routes
+- Share text and code, with optional syntax highlighting.
+- Set an expiration time or a maximum number of views.
+- Share a secret that can only be viewed once.
+- Create short links.
+- Use HTTP Basic authentication to associate pastes with a user, update them, and list them.
 
-- GET `/` - Home page with explanation
-- GET `/:id` -  based on Accept header, syntax-highlighted HTML or plain text
-- POST `/` - create a new paste (default no expiration and infinite views), plain text raw body.
-OR: form parameters `content`, and optional `language`, `expires` (UNIX timestamp) and `max_views` (integer)
-Returns generated id as plain text.
-- POST `/:id` - same as POST `/`, but uses the ID if available. Else it returns a random id.
-- POST `/once` - same as POST `/`, but sets `max_views` to 1
-- POST `/once/:id` - same as POST `/:id`, but sets `max_views` to 1
-- GET `/to/:id` - navigate to shortcut link (redirects using HTTP if found)
-- POST `/to` - create a new link (plain text raw body)
-OR: form parameter `href`.
-Returns generated id as plain text.
-- POST `/to/:id` - same but uses the ID if available, else it returns a random id.
+## API
+
+All paths are relative to the server URL. `{id}` is a path parameter containing a paste or short-link ID.
+
+### Create a paste
+
+| Method | Path | Behavior |
+| --- | --- | --- |
+| `POST` | `/` | Create a paste with a generated ID. |
+| `POST` | `/{id}` | Use the requested ID if available; otherwise generate a random ID. |
+| `POST` | `/once` | Create a paste with `max_views` fixed to `1`. |
+| `POST` | `/once/{id}` | Request a custom ID and set `max_views` to `1`. Generate a random ID if the requested ID is taken. |
+
+**Request body:** raw text, or an `application/x-www-form-urlencoded` form. Use a form to supply optional parameters.
+
+| Form parameter | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `content` | String | Yes | — | Text or code to store. For raw text requests, the entire body supplies this value. |
+| `language` | String | No | Not set | Language for syntax highlighting. |
+| `expires` | Integer | No | No expiration | Expiration time in seconds |
+| `max_views` | Integer | No | Unlimited views | Maximum number of views before self-destruction. The `/once` routes force this to `1`. |
+
+**Authentication:** optional HTTP Basic authentication. If supplied, the paste is associated with that user. An account is created if the user does not exist.
+
+**Returns:** the assigned ID as plain text. This is an ID, not a full URL. Always use the returned ID, since a requested custom ID may already be taken.
+
+Create a paste from raw text:
+
+```sh
+curl --request POST 'http://localhost:3000/' \
+  --header 'Content-Type: text/plain' \
+  --data-binary 'Hello, world!'
+```
+
+Create a paste with optional parameters:
+
+```sh
+curl 'http://localhost:3000/' \
+  --data-urlencode 'content=println!("Hello, world!");' \
+  --data-urlencode 'language=rust' \
+  --data-urlencode 'max_views=5'
+```
+
+Request a custom ID for a one-time secret:
+
+```sh
+curl --request POST 'http://localhost:3000/once/my-secret' \
+  --header 'Content-Type: text/plain' \
+  --data-binary 'A secret to share once'
+```
+
+### Read a paste
+
+`GET /{id}` retrieves a paste by its ID.
+
+| Parameter | Location | Required | Description |
+| --- | --- | --- | --- |
+| `id` | Path | Yes | The paste ID returned when it was created. |
+| `Accept` | Header | No | Use `text/html` for syntax-highlighted HTML or `text/plain` for plain text. |
+
+**Returns:** the paste as HTML or plain text, based on the `Accept` header. The default representation is not defined yet.
+
+```sh
+curl 'http://localhost:3000/my-paste' \
+  --header 'Accept: text/plain'
+```
+
+### Create a short link
+
+| Method | Path | Behavior |
+| --- | --- | --- |
+| `POST` | `/to` | Create a short link with a generated ID. |
+| `POST` | `/to/{id}` | Use the requested ID if available; otherwise generate a random ID. |
+
+**Request body:** the destination URL as raw text, or an `application/x-www-form-urlencoded` form with the following parameter:
+
+| Form parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `href` | String | Yes | Destination URL. For raw text requests, the entire body supplies this value. |
+
+**Returns:** the assigned ID as plain text. Use it in `/to/{id}` to follow the link.
+
+```sh
+curl 'http://localhost:3000/to' \
+  --data-urlencode 'href=https://example.com'
+```
+
+### Follow a short link
+
+`GET /to/{id}` looks up a short link by its ID.
+
+**Returns:** an HTTP redirect to the destination URL when found. The redirect status code and behavior for missing links are not defined yet.
+
+### Update a paste
+
+`PUT /{id}` updates a paste by its ID.
+
+**Authentication:** HTTP Basic authentication of the creator is required.
+
+The same request body as [the POST request](#create-a-paste)
+
+### Delete a paste
+
+`DELETE` delete a paste by its ID.
+
+**Authentication:** HTTP Basic authentication of the creator is required.
+
+### List pastes
+
+`GET /list` returns a list of notes.
+
+**Authentication:** HTTP Basic authentication is required.
+
+**Returns:** a plain-text list of the notes that are present and their content.
+
+```sh
+curl --user 'alice:example-password' 'http://localhost:3000/list'
+```
+
+### Home page
+
+`GET /` returns the home page.