clink

clink is a minimalistic, self‑hosted URL shortener written entirely in C and powered by the embedded web server library Mongoose. The project deliberately eschews heavyweight frameworks, offering a single‑binary deployment that can be compiled on any POSIX system. Its core functionality is to accept a long URL via an HTTP endpoint, generate a short identifier, store the mapping in memory or a lightweight file‑based database, and redirect clients to the original address. The API surface is intentionally small: a POST endpoint for creation, a GET endpoint for redirection, and optional query parameters to customize expiration or custom aliases.

Key Features

• Pure C implementation – no external dependencies beyond the standard library and Mongoose, enabling static linking and easy cross‑compilation.
• In‑memory + optional persistence – URL mappings are held in a hash table; the state can be dumped to a JSON file for recovery.
• HTTPS support – Mongoose handles TLS via OpenSSL; self‑signed certificates are auto‑generated if not provided.
• Rate limiting & basic auth – configurable via command line flags or a simple config file, useful for protecting the creation endpoint.
• Webhooks – optional POST callbacks on link creation or deletion, allowing integration with CI/CD pipelines or analytics services.

Technical Stack

The codebase is split into three logical modules:
main.c – entry point, argument parsing, and server initialization.
mongoose.c/h – thin wrapper around Mongoose to expose request handlers.
clinkctl/ – a small CLI tool for managing links (list, delete, stats) and for generating self‑signed certs.

Architecture

1. Request Handling – Mongoose listens on a configurable port; each incoming request is dispatched to handle_request().
2. URL Mapping – A thread‑safe hash table (url_map) stores short_id → long_url pairs. The key is a base‑62 encoded counter or a user‑supplied slug.
3. Persistence Layer – On startup, the binary reads clink.db (JSON) into memory; on shutdown or every N seconds, it writes back to disk.
4. CLI Control – clinkctl communicates with the running instance via Unix domain sockets, allowing administrative commands without exposing a separate HTTP API.

Deployment & Infrastructure

• Self‑hosting – A single static binary (clink) can be dropped onto any Linux/Unix host. No runtime dependencies other than libc and OpenSSL.
• Scalability – While the single‑process model limits concurrency to a few hundred concurrent connections, it is sufficient for low‑to‑medium traffic. For higher load, deploy behind a reverse proxy (NGINX/Traefik) with sticky sessions or run multiple instances behind a load balancer.
• Containerization – The included Dockerfile builds an Alpine image; the container can be orchestrated with Docker Compose, Kubernetes (Deployment + Service), or any other container platform.
• Infrastructure as Code – The Makefile can generate a systemd unit file (clink.service) and an NGINX configuration snippet, simplifying production deployments.

Integration & Extensibility

• API – The minimal REST API (POST /shorten, GET /{id}) can be consumed by any language.
• Webhooks – Developers can register a callback URL; clink POSTs JSON payloads containing the new short link data.
• Plugins – While no plugin system exists, the modular C code allows developers to fork and extend mongoose.c for custom authentication, analytics, or storage backends (e.g., SQLite).
• CLI – clinkctl exposes commands for bulk import/export, statistics, and manual cleanup, which can be scripted in CI pipelines.

Developer Experience

• Configuration – Options are passed via command line flags (--port, --cert, --key) or a simple TOML file (clink.conf).
• Documentation – The README provides an overview, build instructions, and API reference. Inline comments in the source are concise but sufficient for understanding the flow.
• Community & Support – The project has a modest issue tracker; contributors are welcomed. Licensing is MIT, allowing unrestricted use in commercial or proprietary projects.

Use Cases

• Internal tooling – Shorten URLs for internal dashboards, logs, or documentation links within a corporate network.
• API gateway – Expose a clean endpoint for external services while keeping the original URLs hidden.
• Rapid prototyping – Developers can spin up a shortener in seconds to test URL routing or analytics pipelines.
• Self‑hosted social platforms – Integrate with custom CMSs to generate shareable links without relying on third‑party services.

Advantages Over Alternatives