camply-web 2.8.0__py3-none-any.whl

camply/__about__.py

@@ -0,0 +1,18 @@
+"""Shared installed distribution metadata for Camply."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+__application__ = "camply"
+"""Python application name."""
+
+__package_name__ = "camply-web"
+"""Python distribution name."""
+
+try:
+    __version__ = version(__package_name__)
+except PackageNotFoundError:  # pragma: no cover
+    try:
+        __version__ = version(__application__)
+    except PackageNotFoundError:
+        __version__ = "0.0.0"
+"""Installed distribution version shared by all runtimes."""

camply/__init__.py

@@ -0,0 +1 @@
+"""Campsite providers, persistence, and optional application runtimes."""

camply/cli/__init__.py

@@ -0,0 +1 @@
+"""Camply command-line interface using only base distribution dependencies."""

camply/cli/__main__.py

@@ -0,0 +1,6 @@
+"""Run the Camply CLI with ``python -m camply.cli``."""
+
+from camply.cli.main import cli
+
+if __name__ == "__main__":
+    cli()

camply/cli/healthcheck.py

@@ -0,0 +1,184 @@
+"""Read-only health probes for the application's foreground serving roles."""
+
+import json
+import os
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+import click
+
+from camply.cli.runtime import require_modules
+
+
+def beat_health_path() -> Path:
+    """Locate the scheduler heartbeat shared by serving and probing in one container."""
+    return (
+        Path(
+            os.environ.get("CAMPLY_BEAT_HEALTH_FILE")
+            or str(Path(tempfile.gettempdir()) / "camply-beat-health.json")
+        )
+        .expanduser()
+        .resolve()
+    )
+
+
+def _check_http(url: str, *, timeout: float) -> None:
+    """Check HTTP status without reading an unbounded body or following redirects."""
+    import httpx
+
+    try:
+        with httpx.stream(
+            "GET", url, timeout=timeout, trust_env=False, follow_redirects=False
+        ) as response:
+            if not response.is_success:
+                raise click.ClickException(
+                    f"HTTP healthcheck failed with status {response.status_code}."
+                )
+    except (httpx.HTTPError, ValueError) as exc:
+        raise click.ClickException(
+            "HTTP healthcheck could not reach the service."
+        ) from exc
+    click.echo("healthy")
+
+
+@click.group(invoke_without_command=True)
+@click.option(
+    "--url", help="Standalone health URL (default: http://127.0.0.1:8000/api/health)."
+)
+@click.option(
+    "--timeout",
+    type=click.FloatRange(min=0, min_open=True),
+    help="Network timeout in seconds (default: 5).",
+)
+@click.pass_context
+def healthcheck(ctx: click.Context, url: str | None, timeout: float | None) -> None:
+    """Check standalone health, or select an individual serving role."""
+    if ctx.invoked_subcommand is not None:
+        if url is not None or timeout is not None:
+            raise click.UsageError("Place healthcheck options after the role name.")
+        return
+    _check_http(url or "http://127.0.0.1:8000/api/health", timeout=timeout or 5)
+
+
+@healthcheck.command(name="backend")
+@click.option("--url", default="http://127.0.0.1:8000/api/health", show_default=True)
+@click.option(
+    "--timeout",
+    default=5.0,
+    type=click.FloatRange(min=0, min_open=True),
+    show_default=True,
+)
+def backend(url: str, timeout: float) -> None:
+    """Check the API's existing HTTP health endpoint."""
+    _check_http(url, timeout=timeout)
+
+
+@healthcheck.command(name="frontend")
+@click.option("--url", default="http://127.0.0.1:8080/healthz", show_default=True)
+@click.option(
+    "--timeout",
+    default=5.0,
+    type=click.FloatRange(min=0, min_open=True),
+    show_default=True,
+)
+def frontend(url: str, timeout: float) -> None:
+    """Check Nginx's health endpoint independently of its API upstream."""
+    _check_http(url, timeout=timeout)
+
+
+@healthcheck.command(name="worker")
+@click.option(
+    "--destination", help="Celery node name (default: celery@<local hostname>)."
+)
+@click.option(
+    "--timeout",
+    default=5.0,
+    type=click.FloatRange(min=0, min_open=True),
+    show_default=True,
+)
+def worker(destination: str | None, timeout: float) -> None:
+    """Require a reply from this worker through its configured broker."""
+    require_modules("distributed", ("celery", "redis", "prometheus_client"))
+    target = destination or f"celery@{socket.gethostname()}"
+    if "," in target:
+        raise click.BadParameter(
+            "Specify exactly one Celery node.", param_hint="--destination"
+        )
+    try:
+        result = subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "celery",
+                "-A",
+                "camply.worker.celery_app",
+                "inspect",
+                "--destination",
+                target,
+                "--timeout",
+                str(timeout / 2),
+                "ping",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=timeout,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise click.ClickException(
+            "Worker healthcheck did not receive a response in time."
+        ) from exc
+    if result.returncode != 0:
+        raise click.ClickException(
+            "Worker healthcheck failed; check the target worker and broker."
+        )
+    click.echo("healthy")
+
+
+@healthcheck.command(name="beat")
+@click.option(
+    "--heartbeat-file",
+    type=click.Path(path_type=Path),
+    help="Override CAMPLY_BEAT_HEALTH_FILE.",
+)
+@click.option(
+    "--max-age",
+    default=60.0,
+    type=click.FloatRange(min=0, min_open=True),
+    show_default=True,
+)
+def beat(heartbeat_file: Path | None, max_age: float) -> None:
+    """Require a fresh scheduler-loop heartbeat from a live local process."""
+    if os.name == "nt":
+        raise click.ClickException("Beat healthchecks require a Unix PID namespace.")
+    path = heartbeat_file or beat_health_path()
+    try:
+        state = json.loads(path.read_text())
+        if not isinstance(state, dict):
+            raise ValueError("Invalid heartbeat")
+        pid, stamp = state.get("pid"), state.get("timestamp")
+        if (
+            type(pid) is not int
+            or pid <= 0
+            or not isinstance(stamp, (int, float))
+            or isinstance(stamp, bool)
+        ):
+            raise ValueError("Invalid heartbeat")
+        timestamp = float(stamp)
+    except (OSError, ValueError, OverflowError) as exc:
+        raise click.ClickException("Beat heartbeat is missing or invalid.") from exc
+    if not 0 <= time.time() - timestamp <= max_age:
+        raise click.ClickException(
+            "Beat heartbeat is stale or has an invalid timestamp."
+        )
+    try:
+        os.kill(pid, 0)
+    except (OSError, OverflowError) as exc:
+        raise click.ClickException(
+            "Beat scheduler process is not running or accessible."
+        ) from exc
+    click.echo("healthy")

camply/cli/main.py

@@ -0,0 +1,235 @@
+"""
+Camply CLI entrypoint.
+
+The ``camply`` console script resolves to :func:`cli`. Subcommands are
+registered on this group as the CLI grows.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from importlib.resources import files
+from pathlib import Path
+
+import click
+
+from camply.__about__ import __application__, __version__
+from camply.cli.healthcheck import beat_health_path, healthcheck
+from camply.cli.runtime import require_modules
+
+
+@click.group(
+    name=__application__,
+    invoke_without_command=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.version_option(
+    version=__version__,
+    prog_name=__application__,
+    message="%(prog)s, version %(version)s",
+)
+@click.pass_context
+def cli(ctx: click.Context) -> None:
+    """
+    camply, the campsite finder ⛺️.
+
+    Find campsites at sold-out campgrounds.
+    """
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+def _executable(name: str, *, hint: str) -> str:
+    """Find a runtime executable before performing startup side effects."""
+    executable = shutil.which(name)
+    if executable is None:
+        raise click.ClickException(f"{name} is required. {hint}")
+    return executable
+
+
+def _require_server(*modules: str) -> None:
+    """Check shared server dependencies plus any role-specific Python modules."""
+    require_modules(
+        "server",
+        (
+            "fastapi",
+            "uvicorn",
+            "orjson",
+            "jwt",
+            "cryptography",
+            "prometheus_client",
+            *modules,
+        ),
+    )
+
+
+@cli.group(invoke_without_command=True)
+@click.option("--host", help="Standalone bind address (default: 127.0.0.1).")
+@click.option(
+    "--port", type=click.IntRange(1, 65535), help="Standalone port (default: 8000)."
+)
+@click.pass_context
+def serve(ctx: click.Context, host: str | None, port: int | None) -> None:
+    """Serve the standalone app, or select an individual application role."""
+    if ctx.invoked_subcommand is not None:
+        if host is not None or port is not None:
+            raise click.UsageError(
+                "--host and --port apply to standalone serving; omit the subcommand."
+            )
+        return
+    _require_server()
+    args = [sys.executable, "-m", "camply.server.standalone"]
+    if host is not None:
+        args.extend(["--host", host])
+    if port is not None:
+        args.extend(["--port", str(port)])
+    os.environ["CAMPLY_RUNTIME_MODE"] = "standalone"
+    os.execv(sys.executable, args)
+
+
+@serve.command(name="frontend")
+def serve_frontend() -> None:
+    """Serve bundled assets and proxy /api to CAMPLY_BACKEND_URL using Nginx."""
+    executable = _executable("nginx", hint="Install Nginx or use the camply-web image.")
+    directory = Path(__file__).resolve().parents[1] / "server" / "static"
+    if not (directory / "index.html").is_file():
+        raise click.ClickException(
+            "Frontend assets are missing. Install a prepared camply wheel."
+        )
+    templates = files("camply.cli").joinpath("nginx")
+    with tempfile.TemporaryDirectory(prefix="camply-nginx-") as temporary:
+        runtime = Path(temporary).resolve()
+        server = runtime / "server.conf"
+        config = runtime / "nginx.conf"
+        server.write_text(
+            templates.joinpath("server.conf")
+            .read_text()
+            .replace(
+                "${CAMPLY_FRONTEND_DIR}", json.dumps(str(directory), ensure_ascii=False)
+            )
+            .replace(
+                "${CAMPLY_BACKEND_URL}",
+                json.dumps(
+                    os.environ.get("CAMPLY_BACKEND_URL") or "http://backend:8000",
+                    ensure_ascii=False,
+                ),
+            )
+        )
+        config.write_text(
+            templates.joinpath("nginx.conf")
+            .read_text()
+            .replace(
+                "${CAMPLY_NGINX_SERVER_CONFIG}",
+                json.dumps(str(server), ensure_ascii=False),
+            )
+        )
+        os.execv(
+            executable,
+            [executable, "-p", f"{runtime}/", "-c", str(config), "-g", "daemon off;"],
+        )
+
+
+@serve.command(name="backend", context_settings={"ignore_unknown_options": True})
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
+def serve_backend(args: tuple[str, ...]) -> None:
+    """Migrate the database and serve the API; forward arguments to Gunicorn."""
+    _require_server("gunicorn", "uvicorn_worker")
+    if os.environ.get("SKIP_MIGRATIONS", "0") != "1":
+        from camply.db.migration import upgrade
+
+        upgrade()
+    os.execv(
+        sys.executable,
+        [
+            sys.executable,
+            "-m",
+            "gunicorn",
+            "--config",
+            "python:camply.server.gunicorn",
+            *args,
+            "camply.server.app:app",
+        ],
+    )
+
+
+@serve.command(name="worker", context_settings={"ignore_unknown_options": True})
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
+def serve_worker(args: tuple[str, ...]) -> None:
+    """Consume background tasks; forward arguments to the Celery worker."""
+    _worker_process("worker", ("-Q", "celery", "--concurrency=4", *args))
+
+
+@serve.command(name="beat", context_settings={"ignore_unknown_options": True})
+@click.option(
+    "--sync-providers",
+    is_flag=True,
+    help="Enqueue an initial provider catalog sync before starting the scheduler.",
+)
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
+def serve_beat(sync_providers: bool, args: tuple[str, ...]) -> None:
+    """Schedule background tasks; optionally enqueue a provider sync before exec."""
+    _worker_process(
+        "beat",
+        (
+            "--scheduler",
+            "camply.worker.scheduler:HealthScheduler",
+            "--max-interval=30",
+            *args,
+        ),
+        sync_providers=sync_providers,
+    )
+
+
+def _worker_process(
+    command: str, args: tuple[str, ...], *, sync_providers: bool = False
+) -> None:
+    """Check dependencies, optionally dispatch a sync, then exec the distributed role."""
+    require_modules("distributed", ("celery", "redis", "prometheus_client"))
+    if command == "beat":
+        path = beat_health_path()
+        try:
+            path.unlink(missing_ok=True)
+        except OSError as exc:
+            raise click.ClickException(
+                "Cannot prepare the beat heartbeat file."
+            ) from exc
+        os.environ["CAMPLY_BEAT_HEALTH_FILE"] = str(path)
+    if sync_providers:
+        try:
+            subprocess.run(
+                [
+                    sys.executable,
+                    "-m",
+                    "celery",
+                    "-A",
+                    "camply.worker.celery_app",
+                    "call",
+                    "camply.catalog.sync_all_providers",
+                    "--expires=600",
+                ],
+                check=True,
+            )
+        except subprocess.CalledProcessError as exc:
+            raise click.ClickException(
+                f"Could not enqueue provider sync (exit status {exc.returncode})."
+            ) from exc
+    os.execv(
+        sys.executable,
+        [
+            sys.executable,
+            "-m",
+            "celery",
+            "-A",
+            "camply.worker.celery_app",
+            command,
+            "-l",
+            "info",
+            *args,
+        ],
+    )
+
+
+serve.add_command(healthcheck)

camply/cli/nginx/nginx.conf

@@ -0,0 +1,25 @@
+worker_processes auto;
+error_log stderr notice;
+pid nginx.pid;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
+                    '$status $body_bytes_sent "$http_referer" '
+                    '"$http_user_agent" "$http_x_forwarded_for"';
+
+    access_log /dev/stdout main;
+
+    sendfile on;
+    tcp_nopush on;
+    keepalive_timeout 65;
+    gzip on;
+
+    include ${CAMPLY_NGINX_SERVER_CONFIG};
+}

camply/cli/nginx/server.conf

@@ -0,0 +1,64 @@
+server {
+    listen 8080;
+    server_name _;
+
+    root ${CAMPLY_FRONTEND_DIR};
+    index index.html;
+
+    # Resolve temp paths under the writable Nginx runtime prefix.
+    client_body_temp_path client_body_temp;
+    proxy_temp_path proxy_temp;
+    fastcgi_temp_path fastcgi_temp;
+    uwsgi_temp_path uwsgi_temp;
+    scgi_temp_path scgi_temp;
+
+    # Gzip compression for text, script, and style assets
+    gzip on;
+    gzip_vary on;
+    gzip_proxied any;
+    gzip_comp_level 6;
+    gzip_types text/plain text/css text/xml application/json application/javascript application/rss+xml application/atom+xml image/svg+xml;
+
+    location = /healthz {
+        access_log off;
+        add_header Content-Type text/plain;
+        return 200 'OK';
+    }
+
+    # Content-hashed static assets (safe to cache forever)
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, max-age=31536000, immutable";
+        access_log off;
+    }
+
+    # Ensure index.html is always revalidated for new deployments
+    location = /index.html {
+        add_header Cache-Control "no-cache";
+    }
+
+    location /api/ {
+        proxy_pass ${CAMPLY_BACKEND_URL};
+        proxy_ssl_server_name on;
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # Documentation has directory indexes and must never fall back to the app.
+    location = /docs {
+        return 301 /docs/;
+    }
+
+    location /docs/ {
+        try_files $uri $uri/ $uri.html =404;
+        add_header Cache-Control "no-cache";
+    }
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}

camply/cli/runtime.py

@@ -0,0 +1,14 @@
+"""Validate optional runtime dependencies without importing application bootstraps."""
+
+import importlib.util
+
+import click
+
+
+def require_modules(extra: str, modules: tuple[str, ...]) -> None:
+    """Reject incomplete extras in this interpreter before runtime side effects."""
+    missing = [name for name in modules if importlib.util.find_spec(name) is None]
+    if missing:
+        raise click.ClickException(
+            f"Missing runtime dependencies: {', '.join(missing)}. Install camply[{extra}]."
+        )

camply/db/README.md

@@ -0,0 +1,50 @@
+# camply.db
+
+Database models and migrations for the camply platform.
+
+## Checklist Data Layer Models
+
+These models support the smart de-duplicated poller.
+
+### User
+
+Represents a platform user with early access flags and notification tokens.
+
+- `id`: UUID (Primary Key)
+- `auth0_id`: String (Unique, Nullable)
+- `email`: String (Unique, Index)
+- `is_invited`: Boolean (defaults to False; stored in the existing `is_early_access_user` column)
+- `pushover_token`: String (Nullable)
+
+### UniqueTarget
+
+The de-duplicated "what" to scan. Represents a unique combination of provider, campground, and date range.
+
+- `id`: UUID (Primary Key)
+- `provider_id`: Integer (Foreign Key)
+- `campground_id`: String (Foreign Key)
+- `start_date`: Date
+- `end_date`: Date
+- `hash`: String (Unique Index) - SHA256 of composite fields, automatically calculated.
+
+### UserScan
+
+Links a user to a target with specific filtering preferences.
+
+- `id`: UUID (Primary Key)
+- `user_id`: UUID (Foreign Key)
+- `target_id`: UUID (Foreign Key)
+- `is_active`: Boolean (Defaults to True)
+- `min_stay_length`: Integer
+- `preferred_types`: ARRAY of Strings
+- `require_electric`: Boolean
+
+### ScanResult
+
+Cached findings from a scan execution.
+
+- `id`: UUID (Primary Key)
+- `target_id`: UUID (Foreign Key)
+- `campsite_id`: String
+- `available_dates`: JSONB (Array of ISO date strings)
+- `found_at`: Timestamp (Index)

camply/db/__init__.py

@@ -0,0 +1,15 @@
+"""
+Database Package for camply.
+"""
+
+from camply.db.eligibility import (
+    eligible_scan_condition,
+    is_scan_eligible,
+    is_user_scan_eligible,
+)
+
+__all__ = [
+    "eligible_scan_condition",
+    "is_scan_eligible",
+    "is_user_scan_eligible",
+]

camply/db/alembic.ini

@@ -0,0 +1,47 @@
+[alembic]
+script_location = camply.db:migrations
+timezone = utc
+version_path_separator = os
+
+[post_write_hooks]
+hooks = ruff_format, ruff_check
+ruff_format.type = exec
+ruff_format.executable = %(here)s/../../../.venv/bin/ruff
+ruff_format.options = format REVISION_SCRIPT_FILENAME
+ruff_check.type = exec
+ruff_check.executable = %(here)s/../../../.venv/bin/ruff
+ruff_check.options = check --fix REVISION_SCRIPT_FILENAME
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers = console
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers = console
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S