bit

bit is a lightweight, API‑only URL shortener designed for developers who need a fast, self‑hosted solution with minimal operational overhead. The core idea is to expose a RESTful interface that accepts a long URL and returns a short, deterministic slug while collecting only essential telemetry (country, browser, OS, referer) without relying on cookies or persistent identifiers. Its performance profile—~7.9 k requests per second with 15 ms latency on modest hardware—makes it suitable for high‑traffic sites, internal tooling, or as a building block in larger microservice architectures.

Architecture & Technical Stack

• Language & Framework: Implemented in Go, leveraging the standard library’s net/http for concurrency and performance. The codebase is intentionally small (≈ 3 k LOC) to keep the binary lightweight.
• Data Store: Uses SQLite as an embedded database, eliminating external dependencies while still supporting ACID transactions. The schema stores slug, original URL, creation timestamp, and optional metadata (user ID, API key).
• Authentication: API‑key based; keys are generated and managed via a CLI tool (bit-cli). Keys map to user accounts in the SQLite table, enabling per‑user rate limiting and analytics isolation.
• Telemetry: Captures minimal request headers (X-Forwarded-For, User-Agent) and derives geolocation from IP. No session cookies or client‑side storage are used, ensuring privacy compliance.
• Containerization: Built as a stateless Docker image (sjdonado/bit) with a single ENTRYPOINT that starts the HTTP server. The image size is under 100 MB, and it runs on both x86_64 and ARM64 architectures.

Core Capabilities

• CRUD API: Endpoints for creating (POST /shorten), retrieving (GET /{slug}), listing (GET /keys/{key}/urls), and deleting URLs (DELETE /{slug}).
• Key Management: POST /keys to generate a new API key, GET /keys to list keys, and DELETE /keys/{key} to revoke.
• Analytics Endpoint: GET /stats/{slug} returns hit count, timestamps, and aggregated telemetry.
• Webhooks: Optional webhook support for redirect events, allowing downstream services to react to click data.
• CLI: A small Go binary (bit-cli) that wraps the API for local key and URL management, simplifying integration in CI/CD pipelines.

Deployment & Infrastructure

bit is designed for self‑hosting with minimal resource requirements: 70 MiB RAM, 100 MB disk, and a single CPU core suffices for thousands of requests per second. It can be deployed via:

• Docker Compose: A single service definition with a persistent SQLite volume.
• Dokku: Uses the standard dokku dockerfile:create flow, making it trivial to scale horizontally by adding more dynos.
• Kubernetes: Stateless pods can be replicated; a shared PersistentVolumeClaim is needed for the SQLite file or an external database if desired.

Because the binary is stateless aside from the database, horizontal scaling is straightforward—simply add more instances behind a load balancer. For very high availability, consider sharding the SQLite file or migrating to PostgreSQL with a small wrapper layer.

Integration & Extensibility

• Plugin‑like Architecture: The Go code exposes a middleware interface; developers can inject custom HTTP middleware for logging, rate‑limiting, or additional telemetry without modifying the core.
• Webhooks & Callbacks: External services can subscribe to redirect events, enabling analytics dashboards or automated marketing workflows.
• Custom Slugs: The API accepts an optional slug field; if omitted, the service generates a random 6‑character base‑62 string.
• Rate Limiting: Built‑in per‑API‑key limits can be tuned via environment variables, or developers can replace the default limiter with a distributed one (e.g., Redis).

Developer Experience

The project follows clean Go conventions and ships with comprehensive documentation: an API.md spec, a SETUP.md guide for Docker and Dokku, and a contribution handbook. The CLI abstracts common tasks, reducing boilerplate when scripting or automating deployments. Community support is modest but active; issues are triaged quickly, and the codebase remains open for pull requests. The licensing is permissive (MIT), allowing commercial use without royalties.

Use Cases

• Internal Tooling: A dev‑ops team can expose a shortener for internal URLs, embedding click analytics into CI pipelines.
• Marketing Campaigns: Rapidly generate short links for email or social media, with per‑campaign API keys to isolate metrics.
• Microservice Orchestration: Embed bit in a service mesh to provide short URLs for internal services, leveraging the minimal telemetry footprint.
• Educational Projects: Demonstrate API design, rate limiting, and Go concurrency in a classroom setting.

Advantages Over Alternatives

• Performance: Benchmarked at 7.9 k req/sec on modest hardware, outperforming many Node.js or Python‑based shorteners.
• Resource Footprint: 30 MiB RAM and a single binary keep the operational cost low.
• Simplicity: No external dependencies (Redis, Memcached) or complex configuration—just a single SQLite file.
• Privacy‑Friendly: No cookies, no persistent tracking; only basic request data is stored.
• Extensibility