Metadata-Version: 2.4
Name: bh_urlshortener
Version: 0.0.7
Summary: A simple URL shortener service.
Author: Abin M
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.49.0
Requires-Dist: pydantic>=2.6
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: sqlalchemy>=2.0.51
Requires-Dist: psycopg[binary]>=3.1
Requires-Dist: prometheus-client>=0.20
Provides-Extra: test
Requires-Dist: pytest>=9.1.0; extra == "test"
Requires-Dist: pytest-cov>=7.1.0; extra == "test"
Requires-Dist: mypy>=2.1.0; extra == "test"
Requires-Dist: httpx>=0.27; extra == "test"
Dynamic: license-file

# urlshortener

Self-hosted URL shortener. Shorten URLs, redirect, track visits. 

## Quickstart

**Docker Compose (recommended)**

```bash
# create an .env file by following the configs docs  
# set POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB
docker compose up -d
```

**Local**

```bash
pip install -e .
export URLSHORTENER_DATABASE_URL="postgresql+psycopg://user:pass@localhost:5432/urlshortener"
urlshortener serve
```

App runs at `http://localhost:8000`.

---

## API

| Method | Path            | Description                  |
|--------|-----------------|------------------------------|
| POST   | `/shorten`      | Create short link            |
| GET    | `/{code}`       | Redirect to original (307)   |
| GET    | `/stats/{code}` | Visit count + original URL   |
| GET    | `/healthz`      | Liveness + DB check          |
| GET    | `/metrics`      | Prometheus metrics           |

```bash
curl -X POST http://localhost:8000/shorten \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/long/path"}'
# {"code": "aB3kR7z", "short_url": "http://localhost:8000/aB3kR7z"}

curl http://localhost:8000/stats/aB3kR7z
# {"code": "aB3kR7z", "url": "https://example.com/long/path", "visits": 4}
```

---



## Development

```bash
pip install -e ".[test]"

pytest        # test + coverage
mypy src      # type check
tox           # full matrix
```

Tests run against an in-memory fake store — no DB required.

---

## Observability

Docker Compose includes Prometheus, Alertmanager, and Grafana.

| Service      | URL                       |
|--------------|---------------------------|
| Grafana      | http://localhost:3000     |
| Prometheus   | http://localhost:9090     |
| Alertmanager | http://localhost:9093     |

See [`docs/05_observability.md`](docs/05_observability.md) for details.

---

## Docs

- [`docs/01_setup.md`](docs/01_setup.md)
- [`docs/02_api.md`](docs/02_api.md)
- [`docs/03_config.md`](docs/03_config.md)
- [`docs/04_development.md`](docs/04_development.md)
- [`docs/05_observability.md`](docs/05_observability.md)

---

## License

MIT
