rs-short

rs‑short is a lightweight, self‑hosted URL shortener written in Rust that prioritizes performance, type safety, and minimal runtime overhead. The core of the application is a single binary that exposes both an HTTP API for programmatic interaction and a minimal web UI for manual management. The codebase follows idiomatic Rust practices, leveraging crates such as axum for routing, sqlx for async database access, and serde for serialization. The project is designed to be compiled once per target architecture, making it ideal for containerized deployments or direct binary execution on Linux servers.

Architecture

• Language & Runtime: Rust 1.75+, compiled to native binaries with no external runtime dependencies.
• Web Framework: axum (Tower‑based) provides a composable middleware stack, request extraction, and graceful shutdown.
• Database Layer: sqlx supports PostgreSQL, MySQL, and SQLite through compile‑time feature flags. Migrations are managed via sqlx-cli embedded in the repository, ensuring schema consistency across environments.
• Configuration: TOML‑based config (config.toml.sample) is parsed at startup, with support for environment variable overrides. The application validates configuration early to avoid runtime surprises.
• Asset Handling: Static files (templates, CSS, JS) are bundled using include_dir or served directly from a mounted volume in Docker builds.

Core Capabilities

• RESTful API: Endpoints for creating, retrieving, updating, and deleting short URLs. The API accepts JSON payloads and returns structured responses with appropriate HTTP status codes.
• Web UI: A lightweight interface for creating links, viewing statistics (click counts, timestamps), and managing blacklists/whitelists. The UI is built with vanilla JS; no heavy frontend frameworks are required.
• Analytics: Basic click tracking is stored in the database, allowing developers to expose custom dashboards or integrate with external analytics tools via webhooks.
• Security: Rate limiting, IP blacklisting, and optional authentication hooks (e.g., JWT or Basic Auth) can be added through middleware layers without modifying core logic.

Deployment & Infrastructure

• Containerization: A Dockerfile builds a multi‑stage image, copying only the compiled binary and static assets. The resulting image is under 30 MB, making it suitable for edge deployments or CI/CD pipelines.
• Scalability: Stateless request handling allows horizontal scaling behind a reverse proxy (NGINX, Traefik). Persistent storage is handled by the chosen database; replication and sharding are left to the underlying DBMS.
• Self‑Hosting Requirements: Minimal – a Linux server with Docker or direct binary execution, plus a supported database instance. No external services are required unless the developer opts for advanced features like OAuth.

Integration & Extensibility

• Plugin Hooks: The project exposes a trait‑based plugin system where developers can inject custom logic for URL generation, analytics collection, or authentication. Plugins are compiled into the binary but can be swapped by rebuilding.
• Webhooks: Optional outbound HTTP requests on link creation or click events enable integration with CI/CD pipelines, monitoring systems, or third‑party services.
• API Customization: OpenAPI annotations (via utoipa) are available, allowing automatic generation of API docs and client SDKs in various languages.

Developer Experience

• Documentation: The README, inline comments, and a detailed Wiki provide clear guidance on building, configuring, and extending the application. The code follows Rust’s idiomatic style, making it approachable for seasoned developers.
• Community & Support: The repository hosts an active issue tracker with a moderate number of contributors. Pull requests are reviewed promptly, and the license (MIT) encourages commercial use without restrictions.
• Testing: Extensive unit tests cover routing, database interactions, and configuration parsing. CI pipelines run on Gitea Actions, ensuring that every commit passes all checks before merging.

Use Cases

1. Internal Documentation – Expose short links to internal wikis or knowledge bases, with click analytics for usage reporting.
2. Marketing Campaigns – Deploy a lightweight service to generate campaign‑specific URLs, track engagement, and integrate with email marketing tools via webhooks.
3. API Gateways – Use rs‑short as a thin layer that redirects to microservices, allowing versioned endpoints while keeping URLs human‑friendly.
4. Educational Projects – Demonstrate Rust web development, async programming, and database migrations in a hands‑on setting.

Advantages

• Performance & Size: A single compiled binary with no JIT or VM overhead results in low latency and minimal memory footprint.
• Safety & Reliability: Rust’s ownership model eliminates common bugs (null derefs, data races), leading to more robust production deployments.
• Licensing Freedom: MIT license permits unrestricted use, modification, and redistribution—even in proprietary projects.
• Extensibility: The plugin architecture and webhook support enable developers to tailor the service without touching core code, fostering rapid iteration.

In summary, rs‑short offers a developer‑centric, high‑performance solution for URL shortening that can be deployed anywhere—from a small VPS to a Kubernetes cluster—while remaining fully customizable and open for integration with existing tooling.