DOCSEARCHbyAlgolia
Submit Docs

rustypaste

repository·master·Indexed 22 days ago

https://github.com/orhun/rustypaste

A minimal, high-performance, single-binary file upload and pastebin service written in Rust. It uses the filesystem instead of a database for easy self-hosting. Key features include support for password-protected files (Argon2id), expiring and one-shot links, URL shortening, and remote URL uploads. It provides a flexible configuration system via TOML and environment variables, supports Docker deployment, and includes customizable MIME type handling.

Tokens
10.3K
Snippets
47
Records
53
Agent score
78%

What's inside rustypaste

  1. Overview of rustypaste features

    master

    Rustypaste is a minimal, single-binary file upload and pastebin service written in Rust. Key features include:

    • Upload Capabilities: Supports file uploads, URL shortening, and uploading directly from a URL.
    • Naming Options: Supports random file names using pet names (e.g., capital-mosquito.txt), alphanumeric strings, or random suffixes.
    • Security: Supports password-protected files (using Argon2id hashing) and basic HTTP authentication.
    • Link Management: Supports expiring links (with optional auto-deletion) and one-shot links (viewable only once).
    • MIME Handling: Guesses MIME types with support for overriding, blacklisting, or forcing downloads via the ?download=true query parameter.
    • Deployment: No database required (uses the filesystem), supports hot reloading for configuration, and is available as Docker images.

  2. Access password-protected files

    master

    When a file is uploaded using the protected flag, it is secured with a password. To download the file, you must provide the password via either a Bearer token or Basic Auth.

    Important Notes:

    • Protected files cannot be combined with oneshot or url types.
    • The password is permanently tied to the file and cannot be changed.
    • If the password is lost, the file is inaccessible.
    • Password files are automatically deleted when the main file expires or is deleted.
    # Download with Bearer token
curl -H "Authorization: Bearer <password>" https://paste.site.com/secret.txt

# Download with Basic Auth
curl -u "user:<password>" https://paste.site.com/secret.txt

  3. Install rustypaste

    master

    You can install rustypaste using several methods depending on your environment:

    • Rust/Cargo: cargo install rustypaste
    • Arch Linux: pacman -S rustypaste
    • Alpine Linux: apk add rustypaste (requires community repository enabled on Alpine Edge)
    • FreeBSD: pkg install rustypaste
    • Binary Releases: Download pre-built binaries from the GitHub releases page.
    • Build from source: Clone the repository and use cargo build --release.
    cargo install rustypaste

  4. Upload files and data via curl

    master

    You can interact with the rustypaste server using curl to upload files, text from stdin, or remote URLs.

    Basic Uploads

    • Upload a file: Use -F "file=@path/to/file".
    • Paste from stdin: Use -F "file=@-".
    • Override filename: Use the -H "filename: <name>" header to specify a custom name for the uploaded content.

    Advanced Upload Types

    • One-shot files: Files that are deleted immediately after one download. Use -F "oneshot=@file".
    • One-shot URLs: Use -F "oneshot_url=<url>".
    • Remote URL: Fetch and upload a file from a remote URL using -F "remote=<url>".
    • URL shortening: Submit a URL to be shortened using -F "url=<url>".
    • Password-protected files: Upload a file that requires a password to access using -F "protected=@file". The server will return the URL and a generated password.
    # Upload a file
curl -F "file=@x.txt" "<server_address>"

# Paste from stdin
curl -F "file=@-" "<server_address>"

# Override filename
curl -F "file=@x.txt" -H "filename: custom.txt" "<server_address>"

# One-shot file
curl -F "oneshot=@x.txt" "<server_address>"

# Password-protected file
curl -F "protected=@secret.txt" "<server_address>"

  5. Build rustypaste from source with feature flags

    master

    When building from source, you can choose between different TLS implementations using Cargo feature flags:

    • rustls: The default implementation.
    • openssl: Uses the distribution's OpenSSL, which can reduce the binary size by approximately 20% in release mode.

    To build using the system's OpenSSL instead of the default rustls, use the following command:

    cargo build --release --no-default-features --features openssl

  6. Configure and run the rustypaste server

    master

    The server can be started by running the rustypaste command.

    Configuration

    • Config File Location: The server looks for a configuration file in the current directory. To use a specific file, set the CONFIG environment variable.
    • Authentication:
      • To enable basic HTTP auth, set the AUTH_TOKEN environment variable (e.g., via a .env file).
      • For multiple tokens, use the [server].auth_tokens array in config.toml or provide a newline-separated list via the AUTH_TOKENS_FILE environment variable.
      • If no tokens are configured, the server is public (except for the DELETE endpoint, which always requires a token).

    Running with Docker

    You can run the server using Docker by mounting your upload directory and config file:

    # Start server with custom config
$ CONFIG="$HOME/.rustypaste.toml" rustypaste

# Run via Docker
$ docker run --rm -d \
  -v "$(pwd)/upload/":/app/upload \
  -v "$(pwd)/config.toml":/app/config.toml \
  --env-file "$(pwd)/.env" \
  -e "RUST_LOG=debug" \
  -p 8000:8000 \
  --name rustypaste \
  orhunp/rustypaste

  7. Access password-protected files

    master

    If a file is of type ProtectedFile, it requires authentication via the Authorization header to access.

    Supported authentication methods:

    1. Basic Auth: Authorization: Basic <base64(user:pass)>. The server extracts the password from the credentials.
    2. Bearer Token: Authorization: Bearer <token>. The token is used as the password.

    If the password provided does not match the one stored with the file, the server returns a 404 Not Found error to prevent file enumeration.

    curl -H "Authorization: Bearer mysecretpassword" http://localhost:8080/protected_file.txt

  8. Automatic cleanup of expired pastes

    master

    The server includes a background cleanup routine that automatically deletes expired files and orphaned password files to manage storage.

    This feature is controlled by the paste.delete_expired_files section in your configuration. You can enable or disable the routine and set the frequency of the cleanup cycle using the interval key.

  9. Hot-reload configuration at runtime

    master

    The rustypaste server supports hot-reloading of its configuration. When the configuration file (specified via CONFIG_ENV or the default config.toml) is modified, the server detects the change and updates its internal state without requiring a restart.

    Note that the refresh rate for the configuration watcher is controlled by the settings.refresh_rate value within the configuration file itself. If not specified, it defaults to a 1-second delay.

  10. Configure MIME type handling

    master

    The server determines MIME types from file extensions. You can control this behavior via config.toml using the following keys:

    • [paste].mime_override: Use regex to override MIME types based on the filename.
    • [paste].mime_blacklist: Block uploads of specific MIME types.
    • [paste].text_mime_overrides: Force specific detected/guessed MIME types to be rendered as text/plain; charset=utf-8 to prevent script execution.

  11. Understand PasteType variants

    master

    The PasteType enum defines the different categories of data that can be stored in the system. Each type determines how the file is stored on disk and its specific behavior (e.g., expiration or protection).

    Available variants:

    • File: A standard file upload.
    • RemoteFile: A file downloaded from a remote URL.
    • Oneshot: A file that is intended to be accessed only once.
    • Url: A paste that contains only a URL string.
    • OneshotUrl: A URL paste that is intended to be accessed only once.
    • ProtectedFile: A password-protected file.
    pub enum PasteType {
    File,
    RemoteFile,
    Oneshot,
    Url,
    OneshotUrl,
    ProtectedFile,
}

  12. Handle Spaces in Filenames

    master

    The handle_spaces setting in the [server] section determines how spaces in filenames are treated. You can choose between two strategies:

    • encode: Spaces are URL-encoded (e.g., file with spaces.txt becomes file%20with%20spaces.txt).
    • replace: Spaces are replaced with underscores (e.g., file with spaces.txt becomes file_with_spaces.txt).
    [server]
handle_spaces = "encode"  # or "replace"