pastable2/README.md

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:

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:

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:

curl --request POST 'http://localhost:3000/' \
  --header 'Content-Type: text/plain' \
  --data-binary 'Hello, world!'

Create a paste with optional parameters:

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:

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.

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.

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

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.

curl --user 'alice:example-password' 'http://localhost:3000/list'

Home page

GET / returns the home page.