bh-urlshortener 0.0.4__tar.gz

bh_urlshortener-0.0.4/.dockerignore

@@ -0,0 +1,15 @@
+.git
+.gitignore
+.env
+.env.*
+__pycache__
+*.pyc
+*.egg-info
+.pytest_cache
+.mypy_cache
+.coverage
+.venv
+venv
+dist
+build
+tests

bh_urlshortener-0.0.4/.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly

bh_urlshortener-0.0.4/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*.*.*"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    container:
+      image: python:${{ matrix.python-version }}-slim
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: "3.11"
+            toxenv: py311
+          - python-version: "3.12"
+            toxenv: py312
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: actions/cache@v5
+        with:
+          path: ~/.cache/pip
+          key: pip-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}
+          restore-keys: pip-${{ matrix.python-version }}-
+      - run: pip install tox
+      - run: tox -e ${{ matrix.toxenv }}
+
+  mypy:
+    runs-on: ubuntu-latest
+    container:
+      image: python:3.12-slim
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: actions/cache@v5
+        with:
+          path: ~/.cache/pip
+          key: pip-mypy-${{ hashFiles('pyproject.toml') }}
+          restore-keys: pip-mypy-
+      - run: pip install tox
+      - run: tox -e mypy
+
+  docker:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [test, mypy]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: docker/setup-buildx-action@v4
+      - uses: docker/metadata-action@v6
+        id: meta
+        with:
+          images: ${{ secrets.DOCKERHUB_USERNAME }}/urlshortener
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+      - uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - uses: docker/build-push-action@v7
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: true
+          sbom: true

bh_urlshortener-0.0.4/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Release
+
+# Tag a release with vX.Y.Z (matching the version in pyproject.toml) to
+# build and publish to PyPI. Requires a PyPI Trusted Publisher configured
+# for this repo/workflow — no API token stored here.
+on:
+  push:
+    tags: ["v*.*.*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - python-version: "3.11"
+            toxenv: py311
+          - python-version: "3.12"
+            toxenv: py312
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install tox
+      - run: tox -e ${{ matrix.toxenv }}
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

bh_urlshortener-0.0.4/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+.env
+.env.*
+.DS_Store
+.tox/

bh_urlshortener-0.0.4/Dockerfile

@@ -0,0 +1,42 @@
+# syntax=docker/dockerfile:1
+
+# Build stage
+FROM python:3.12-slim AS build
+
+ENV PIP_NO_CACHE_DIR=1 PIP_DISABLE_PIP_VERSION_CHECK=1
+WORKDIR /build
+
+COPY pyproject.toml README.md ./
+COPY src ./src
+
+RUN python -m pip install --upgrade pip build \
+    && python -m build --wheel --outdir /dist
+
+# Runtime stage 
+FROM python:3.12-slim AS runtime
+
+LABEL org.opencontainers.image.title="urlshortener" \
+      org.opencontainers.image.description="A simple URL shortener service." \
+      org.opencontainers.image.version="0.1.0"
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    URLSHORTENER_HOST=0.0.0.0 \
+    URLSHORTENER_PORT=8000
+
+# Run as an unprivileged user (rootless).
+RUN groupadd --gid 1000 app \
+    && useradd --uid 1000 --gid 1000 --no-create-home --shell /usr/sbin/nologin app
+
+WORKDIR /app
+COPY --from=build /dist/*.whl /tmp/
+RUN python -m pip install /tmp/*.whl && rm -f /tmp/*.whl
+
+USER app
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+    CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/healthz').status==200 else 1)"
+
+ENTRYPOINT ["urlshortener", "serve"]

bh_urlshortener-0.0.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abin M
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bh_urlshortener-0.0.4/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: bh_urlshortener
+Version: 0.0.4
+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
+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
+
+A self-hosted URL shortener. Shorten a URL, get a redirect, track visit counts. That's it.
+
+
+
+## API
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/shorten` | Create a short link |
+| `GET` | `/{code}` | Redirect to original URL (307) |
+| `GET` | `/stats/{code}` | Visit count + original URL |
+| `GET` | `/healthz` | Liveness + DB connectivity check |
+
+```bash
+# shorten
+curl -X POST http://localhost:8000/shorten \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com/some/long/path"}'
+# {"code": "aB3kR7z", "short_url": "http://localhost:8000/aB3kR7z"}
+
+# stats
+curl http://localhost:8000/stats/aB3kR7z
+# {"code": "aB3kR7z", "url": "https://example.com/some/long/path", "visits": 4}
+```
+
+---
+
+## Running locally
+
+**Prerequisites:** Python 3.11, a running PostgreSQL instance.
+
+```bash
+pip install -e .
+
+# point at your DB (or rely on the default below)
+export URLSHORTENER_DATABASE_URL="postgresql+psycopg://user:pass@localhost:5432/urlshortener"
+
+urlshortener serve
+# listening on http://127.0.0.1:8000
+```
+
+---
+
+## Docker Compose
+
+Spins up Postgres + app together:
+
+```bash
+docker compose up -d 
+```
+
+
+---
+
+## Configuration
+
+All settings are environment variables with the `URLSHORTENER_` prefix.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `URLSHORTENER_DATABASE_URL` | `postgresql+psycopg://urlshortener:urlshortener@localhost:5432/urlshortener` | SQLAlchemy connection string |
+| `URLSHORTENER_BASE_URL` | `http://localhost:8000` | Public base URL used when building short links |
+| `URLSHORTENER_HOST` | `127.0.0.1` | Bind address |
+| `URLSHORTENER_PORT` | `8000` | Bind port |
+| `URLSHORTENER_CODE_LENGTH` | `7` | Length of generated short codes (4–32) |
+| `URLSHORTENER_LOG_LEVEL` | `INFO` | Root log level |
+
+---
+
+## Development
+
+```bash
+pip install -e ".[test]"
+
+pytest          # runs tests + coverage
+mypy src        # strict type checking
+```
+
+> Tests use an in-memory fake store 
+
+
+## License
+
+MIT

bh_urlshortener-0.0.4/README.md

@@ -0,0 +1,86 @@
+# urlshortener
+
+A self-hosted URL shortener. Shorten a URL, get a redirect, track visit counts. That's it.
+
+
+
+## API
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/shorten` | Create a short link |
+| `GET` | `/{code}` | Redirect to original URL (307) |
+| `GET` | `/stats/{code}` | Visit count + original URL |
+| `GET` | `/healthz` | Liveness + DB connectivity check |
+
+```bash
+# shorten
+curl -X POST http://localhost:8000/shorten \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com/some/long/path"}'
+# {"code": "aB3kR7z", "short_url": "http://localhost:8000/aB3kR7z"}
+
+# stats
+curl http://localhost:8000/stats/aB3kR7z
+# {"code": "aB3kR7z", "url": "https://example.com/some/long/path", "visits": 4}
+```
+
+---
+
+## Running locally
+
+**Prerequisites:** Python 3.11, a running PostgreSQL instance.
+
+```bash
+pip install -e .
+
+# point at your DB (or rely on the default below)
+export URLSHORTENER_DATABASE_URL="postgresql+psycopg://user:pass@localhost:5432/urlshortener"
+
+urlshortener serve
+# listening on http://127.0.0.1:8000
+```
+
+---
+
+## Docker Compose
+
+Spins up Postgres + app together:
+
+```bash
+docker compose up -d 
+```
+
+
+---
+
+## Configuration
+
+All settings are environment variables with the `URLSHORTENER_` prefix.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `URLSHORTENER_DATABASE_URL` | `postgresql+psycopg://urlshortener:urlshortener@localhost:5432/urlshortener` | SQLAlchemy connection string |
+| `URLSHORTENER_BASE_URL` | `http://localhost:8000` | Public base URL used when building short links |
+| `URLSHORTENER_HOST` | `127.0.0.1` | Bind address |
+| `URLSHORTENER_PORT` | `8000` | Bind port |
+| `URLSHORTENER_CODE_LENGTH` | `7` | Length of generated short codes (4–32) |
+| `URLSHORTENER_LOG_LEVEL` | `INFO` | Root log level |
+
+---
+
+## Development
+
+```bash
+pip install -e ".[test]"
+
+pytest          # runs tests + coverage
+mypy src        # strict type checking
+```
+
+> Tests use an in-memory fake store 
+
+
+## License
+
+MIT

bh_urlshortener-0.0.4/compose.yaml

@@ -0,0 +1,20 @@
+services:
+  db:
+    image: postgres:16-alpine
+    env_file: .env
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $POSTGRES_USER"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  app:
+    build: .
+    depends_on:
+      db:
+        condition: service_healthy
+    env_file: .env
+    ports:
+      - "8000:8000"

bh_urlshortener-0.0.4/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68", "setuptools-scm>=8", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bh_urlshortener"
+dynamic = ["version"]
+description = "A simple URL shortener service."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Abin M" }]
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.49.0",
+    "pydantic>=2.6",
+    "pydantic-settings>=2.2",
+    "sqlalchemy>=2.0.51",
+    "psycopg[binary]>=3.1",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=9.1.0",
+    "pytest-cov>=7.1.0",
+    "mypy>=2.1.0",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+urlshortener = "urlshortener.__main__:main"
+
+[tool.setuptools_scm]
+fallback_version = "0.0.0"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+[tool.pytest.ini_options]
+addopts = "--cov=urlshortener --cov-report=term-missing"
+testpaths = ["tests"]
+
+[tool.black]
+line-length = 88
+target-version = ["py311"]

bh_urlshortener-0.0.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bh_urlshortener-0.0.4/src/bh_urlshortener.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: bh_urlshortener
+Version: 0.0.4
+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
+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
+
+A self-hosted URL shortener. Shorten a URL, get a redirect, track visit counts. That's it.
+
+
+
+## API
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/shorten` | Create a short link |
+| `GET` | `/{code}` | Redirect to original URL (307) |
+| `GET` | `/stats/{code}` | Visit count + original URL |
+| `GET` | `/healthz` | Liveness + DB connectivity check |
+
+```bash
+# shorten
+curl -X POST http://localhost:8000/shorten \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com/some/long/path"}'
+# {"code": "aB3kR7z", "short_url": "http://localhost:8000/aB3kR7z"}
+
+# stats
+curl http://localhost:8000/stats/aB3kR7z
+# {"code": "aB3kR7z", "url": "https://example.com/some/long/path", "visits": 4}
+```
+
+---
+
+## Running locally
+
+**Prerequisites:** Python 3.11, a running PostgreSQL instance.
+
+```bash
+pip install -e .
+
+# point at your DB (or rely on the default below)
+export URLSHORTENER_DATABASE_URL="postgresql+psycopg://user:pass@localhost:5432/urlshortener"
+
+urlshortener serve
+# listening on http://127.0.0.1:8000
+```
+
+---
+
+## Docker Compose
+
+Spins up Postgres + app together:
+
+```bash
+docker compose up -d 
+```
+
+
+---
+
+## Configuration
+
+All settings are environment variables with the `URLSHORTENER_` prefix.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `URLSHORTENER_DATABASE_URL` | `postgresql+psycopg://urlshortener:urlshortener@localhost:5432/urlshortener` | SQLAlchemy connection string |
+| `URLSHORTENER_BASE_URL` | `http://localhost:8000` | Public base URL used when building short links |
+| `URLSHORTENER_HOST` | `127.0.0.1` | Bind address |
+| `URLSHORTENER_PORT` | `8000` | Bind port |
+| `URLSHORTENER_CODE_LENGTH` | `7` | Length of generated short codes (4–32) |
+| `URLSHORTENER_LOG_LEVEL` | `INFO` | Root log level |
+
+---
+
+## Development
+
+```bash
+pip install -e ".[test]"
+
+pytest          # runs tests + coverage
+mypy src        # strict type checking
+```
+
+> Tests use an in-memory fake store 
+
+
+## License
+
+MIT

bh_urlshortener-0.0.4/src/bh_urlshortener.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+.dockerignore
+.gitignore
+Dockerfile
+LICENSE
+README.md
+compose.yaml
+pyproject.toml
+tox.ini
+.github/dependabot.yml
+.github/workflows/ci.yml
+.github/workflows/release.yml
+src/bh_urlshortener.egg-info/PKG-INFO
+src/bh_urlshortener.egg-info/SOURCES.txt
+src/bh_urlshortener.egg-info/dependency_links.txt
+src/bh_urlshortener.egg-info/entry_points.txt
+src/bh_urlshortener.egg-info/requires.txt
+src/bh_urlshortener.egg-info/top_level.txt
+src/urlshortener/__init__.py
+src/urlshortener/__main__.py
+src/urlshortener/app.py
+src/urlshortener/config.py
+src/urlshortener/storage.py
+tests/__init__.py
+tests/test_app.py

bh_urlshortener-0.0.4/src/bh_urlshortener.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bh_urlshortener-0.0.4/src/bh_urlshortener.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+urlshortener = urlshortener.__main__:main

bh_urlshortener-0.0.4/src/bh_urlshortener.egg-info/requires.txt

@@ -0,0 +1,12 @@
+fastapi>=0.110
+uvicorn[standard]>=0.49.0
+pydantic>=2.6
+pydantic-settings>=2.2
+sqlalchemy>=2.0.51
+psycopg[binary]>=3.1
+
+[test]
+pytest>=9.1.0
+pytest-cov>=7.1.0
+mypy>=2.1.0
+httpx>=0.27

bh_urlshortener-0.0.4/src/bh_urlshortener.egg-info/top_level.txt

@@ -0,0 +1 @@
+urlshortener

bh_urlshortener-0.0.4/src/urlshortener/__main__.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import uvicorn
+
+from .app import create_app
+from .config import Settings
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="urlshortener",
+        description="URL shortener service.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    serve = sub.add_parser("serve", help="Start the HTTP server.")
+    serve.add_argument(
+        "--host",
+        default=os.environ.get("URLSHORTENER_HOST", "127.0.0.1"),
+        help="Bind address (env: URLSHORTENER_HOST).",
+    )
+    serve.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("URLSHORTENER_PORT", "8000")),
+        help="Bind port (env: URLSHORTENER_PORT).",
+    )
+    return parser
+
+
+def main() -> None:
+    args = _build_parser().parse_args()
+
+    if args.command == "serve":
+        settings = Settings(host=args.host, port=args.port)
+        logging.basicConfig(
+            level=settings.log_level.upper(),
+            format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        )
+        app = create_app(settings)
+        uvicorn.run(app, host=settings.host, port=settings.port)
+
+
+if __name__ == "__main__":
+    main()

bh_urlshortener-0.0.4/src/urlshortener/app.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import logging
+import secrets
+import string
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import RedirectResponse
+from pydantic import BaseModel, HttpUrl
+from sqlalchemy import Engine, create_engine
+
+from .config import Settings
+from .storage import CodeExistsError, LinkNotFoundError, LinkStore
+
+logger = logging.getLogger(__name__)
+
+_ALPHABET = string.ascii_letters + string.digits
+_MAX_ATTEMPTS = 5
+
+
+class ShortenRequest(BaseModel):
+    url: HttpUrl
+
+
+class LinkResponse(BaseModel):
+    code: str
+    short_url: str
+
+
+def _make_code(length: int) -> str:
+    return "".join(secrets.choice(_ALPHABET) for _ in range(length))
+
+
+def create_app(settings: Settings, store: LinkStore | None = None) -> FastAPI:
+    """``store`` exists for test injection; production builds it from settings."""
+    engine: Engine | None = None
+    if store is None:
+        engine = create_engine(settings.database_url)
+        store = LinkStore(engine)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        if engine is not None:
+            store.init_schema()
+        logger.info("Application started")
+        yield
+        if engine is not None:
+            engine.dispose()
+        logger.info("Application stopped")
+
+    app = FastAPI(title="URL Shortener", version="0.1.0", lifespan=lifespan)
+
+    @app.get("/healthz")
+    def healthz() -> dict[str, str]:
+        try:
+            store.ping()
+        except Exception as exc:  # noqa: BLE001 - report as unhealthy
+            raise HTTPException(
+                status_code=503, detail="database unavailable") from exc
+        return {"status": "ok"}
+
+    @app.post("/shorten", response_model=LinkResponse, status_code=201)
+    def shorten(payload: ShortenRequest) -> LinkResponse:
+        for _ in range(_MAX_ATTEMPTS):
+            code = _make_code(settings.code_length)
+            try:
+                store.create(code, str(payload.url))
+            except CodeExistsError:
+                continue
+            return LinkResponse(
+                code=code, short_url=f"{settings.base_url.rstrip('/')}/{code}"
+            )
+        raise HTTPException(
+            status_code=500, detail="could not generate a unique code")
+
+    @app.get("/stats/{code}")
+    def stats(code: str) -> dict[str, object]:
+        try:
+            url, visits = store.get_stats(code)
+        except LinkNotFoundError as exc:
+            raise HTTPException(
+                status_code=404, detail="code not found") from exc
+        return {"code": code, "url": url, "visits": visits}
+
+    @app.get("/{code}")
+    def redirect(code: str) -> RedirectResponse:
+        try:
+            url = store.resolve_and_count(code)
+        except LinkNotFoundError as exc:
+            raise HTTPException(
+                status_code=404, detail="code not found") from exc
+        return RedirectResponse(url=url, status_code=307)
+
+    return app

bh_urlshortener-0.0.4/src/urlshortener/config.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+
+    model_config = SettingsConfigDict(
+        env_prefix="URLSHORTENER_",
+        frozen=True,
+        extra="ignore",
+    )
+
+    database_url: str = Field(
+        default="postgresql+psycopg://urlshortener:urlshortener@localhost:5432/urlshortener",
+        description="PostgreSQL connection string (SQLAlchemy URL, psycopg3 driver).",
+    )
+    host: str = Field(default="127.0.0.1", description="Bind address.")
+    port: int = Field(default=8000, ge=1, le=65535, description="Bind port.")
+    base_url: str = Field(
+        default="http://localhost:8000",
+        description="Public base URL used when building short links.",
+    )
+    code_length: int = Field(
+        default=7, ge=4, le=32, description="Length of generated short codes."
+    )
+    log_level: str = Field(default="INFO", description="Root log level.")

bh_urlshortener-0.0.4/src/urlshortener/storage.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+
+from sqlalchemy import BigInteger, Engine, String, func, select, update
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, sessionmaker
+
+logger = logging.getLogger(__name__)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Link(Base):
+    __tablename__ = "links"
+
+    code: Mapped[str] = mapped_column(String, primary_key=True)
+    url: Mapped[str] = mapped_column(String, nullable=False)
+    visits: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    created_at: Mapped[datetime] = mapped_column(server_default=func.now())
+
+
+class CodeExistsError(Exception):
+    pass
+
+
+class LinkNotFoundError(Exception):
+    pass
+
+
+class LinkStore:
+    """Data access for short links over a SQLAlchemy engine."""
+
+    def __init__(self, engine: Engine) -> None:
+        self._engine = engine
+        self._session_factory = sessionmaker(bind=engine)
+
+    def init_schema(self) -> None:
+        Base.metadata.create_all(self._engine)
+        logger.info("Schema initialised")
+
+    def create(self, code: str, url: str) -> None:
+        """Raises CodeExistsError on duplicate code."""
+        with self._session_factory() as session:
+            session.add(Link(code=code, url=url))
+            try:
+                session.commit()
+            except IntegrityError as exc:
+                session.rollback()
+                raise CodeExistsError(code) from exc
+
+    def get_stats(self, code: str) -> tuple[str, int]:
+        """Raises LinkNotFoundError if code absent."""
+        with self._session_factory() as session:
+            link = session.get(Link, code)
+        if link is None:
+            raise LinkNotFoundError(code)
+        return link.url, link.visits
+
+    def resolve_and_count(self, code: str) -> str:
+        """Raises LinkNotFoundError if code absent."""
+        with self._session_factory() as session:
+            row = session.execute(
+                update(Link)
+                .where(Link.code == code)
+                .values(visits=Link.visits + 1)
+                .returning(Link.url)
+            ).first()
+            session.commit()
+        if row is None:
+            raise LinkNotFoundError(code)
+        return str(row[0])
+
+    def ping(self) -> None:
+        """Raises if DB unreachable."""
+        with self._session_factory() as session:
+            session.execute(select(1))

bh_urlshortener-0.0.4/tests/test_app.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import os
+import pytest
+from fastapi.testclient import TestClient
+
+from urlshortener.app import create_app
+from urlshortener.config import Settings
+from urlshortener.storage import CodeExistsError, LinkNotFoundError
+
+
+class FakeStore:
+    """In-memory stand-in for LinkStore."""
+
+    def __init__(self) -> None:
+        self._data: dict[str, list[object]] = {}  # code -> [url, visits]
+
+    def create(self, code: str, url: str) -> None:
+        if code in self._data:
+            raise CodeExistsError(code)
+        self._data[code] = [url, 0]
+
+    def get_stats(self, code: str) -> tuple[str, int]:
+        if code not in self._data:
+            raise LinkNotFoundError(code)
+        url, visits = self._data[code]
+        return str(url), int(visits)  # type: ignore[arg-type]
+
+    def resolve_and_count(self, code: str) -> str:
+        if code not in self._data:
+            raise LinkNotFoundError(code)
+        self._data[code][1] = int(self._data[code][1]) + \
+            1  # type: ignore[arg-type]
+        return str(self._data[code][0])
+
+    def ping(self) -> None:
+        return None
+
+
+@pytest.fixture()
+def client() -> TestClient:
+    settings = Settings(base_url="http://testserver", code_length=6)
+    app = create_app(settings, store=FakeStore())  # type: ignore[arg-type]
+    with TestClient(app) as test_client:
+        yield test_client
+
+
+def test_healthz_returns_ok(client: TestClient) -> None:
+    resp = client.get("/healthz")
+    assert resp.status_code == 200
+    assert resp.json() == {"status": "ok"}
+
+
+def test_shorten_returns_code_of_configured_length(client: TestClient) -> None:
+    resp = client.post("/shorten", json={"url": "https://example.com"})
+    assert resp.status_code == 201
+    body = resp.json()
+    assert len(body["code"]) == 6
+    assert body["short_url"].endswith(body["code"])
+
+
+def test_shorten_then_redirect_round_trips(client: TestClient) -> None:
+    code = client.post(
+        "/shorten", json={"url": "https://example.com"}).json()["code"]
+    redirect = client.get(f"/{code}", follow_redirects=False)
+    assert redirect.status_code == 307
+    assert redirect.headers["location"] == "https://example.com/"
+
+
+def test_stats_reflects_visit_count(client: TestClient) -> None:
+    code = client.post(
+        "/shorten", json={"url": "https://example.com"}).json()["code"]
+    client.get(f"/{code}", follow_redirects=False)
+    client.get(f"/{code}", follow_redirects=False)
+    assert client.get(f"/stats/{code}").json()["visits"] == 2
+
+
+def test_unknown_code_returns_404(client: TestClient) -> None:
+    assert client.get("/nope").status_code == 404
+    assert client.get("/stats/nope").status_code == 404
+
+
+def test_invalid_url_returns_422(client: TestClient) -> None:
+    assert client.post(
+        "/shorten", json={"url": "not-a-url"}).status_code == 422
+
+
+def test_settings_read_from_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    for key in list(os.environ):
+        if key.startswith("URLSHORTENER_"):
+            monkeypatch.delenv(key, raising=False)
+    monkeypatch.setenv("URLSHORTENER_PORT", "9999")
+    assert Settings().port == 9999
+
+
+# --- CLI tests ---
+
+def test_cli_serve_defaults(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("URLSHORTENER_HOST", raising=False)
+    monkeypatch.delenv("URLSHORTENER_PORT", raising=False)
+    from urlshortener.__main__ import _build_parser
+    args = _build_parser().parse_args(["serve"])
+    assert args.host == "127.0.0.1"
+    assert args.port == 8000
+
+
+def test_cli_serve_flags_override_defaults(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("URLSHORTENER_HOST", raising=False)
+    monkeypatch.delenv("URLSHORTENER_PORT", raising=False)
+    from urlshortener.__main__ import _build_parser
+    args = _build_parser().parse_args(
+        ["serve", "--host", "0.0.0.0", "--port", "9000"])
+    assert args.host == "0.0.0.0"
+    assert args.port == 9000
+
+
+def test_cli_serve_env_as_defaults(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("URLSHORTENER_HOST", "0.0.0.0")
+    monkeypatch.setenv("URLSHORTENER_PORT", "9000")
+    from urlshortener.__main__ import _build_parser
+    args = _build_parser().parse_args(["serve"])
+    assert args.host == "0.0.0.0"
+    assert args.port == 9000

bh_urlshortener-0.0.4/tox.ini

@@ -0,0 +1,11 @@
+[tox]
+envlist = py311, py312, mypy
+isolated_build = true
+
+[testenv]
+extras = test
+commands = pytest
+
+[testenv:mypy]
+extras = test
+commands = mypy src/urlshortener