# Pastable

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

- 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.

## 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.