Initial commit

yksa_kit/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

yksa_kit/admin.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from django.contrib import admin
+
+from .models import ApiToken
+
+
+@admin.register(ApiToken)
+class ApiTokenAdmin(admin.ModelAdmin):
+    list_display = ("name", "kind", "is_active", "created_at", "last_used_at")
+    list_filter = ("kind", "is_active")
+    search_fields = ("name", "notes")
+    readonly_fields = ("token", "created_at", "last_used_at")
+    fieldsets = (
+        (None, {"fields": ("name", "kind", "is_active", "notes")}),
+        ("Credential", {"fields": ("token",)}),
+        ("Audit", {"fields": ("created_at", "last_used_at")}),
+    )
+
+    def get_readonly_fields(self, request, obj=None):
+        # Hide the generated token on create, reveal it on edit: it is the only
+        # place an operator can ever read it back.
+        if obj is None:
+            return ("created_at", "last_used_at")
+        return self.readonly_fields

yksa_kit/apps.py

@@ -0,0 +1,11 @@
+from django.apps import AppConfig
+
+
+class YksaKitConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "yksa_kit"
+    label = "yksa_kit"
+    verbose_name = "YKSA kit"
+
+    def ready(self):
+        from . import checks  # noqa: F401  (registers the system check)

yksa_kit/auth.py

@@ -0,0 +1,98 @@
+"""Bearer-token auth for machine clients.
+
+Three carriers are recognised:
+
+1. ``Authorization: Bearer <token>`` header.
+2. ``?api_token=<token>`` query string.
+3. A token the visitor entered in a browser form, stashed in the session. This
+   lets token-gated HTML pages remember the credential without a login system.
+
+API controllers use :func:`request_has_valid_token` (carriers 1 and 2 only);
+browser pages use :func:`resolve_token`, which also accepts the session.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from django.http import HttpRequest
+
+from .models import ApiToken, TokenKind
+
+logger = logging.getLogger(__name__)
+
+_HEADER = "Authorization"
+_QUERY_PARAM = "api_token"
+_BEARER_PREFIX = "bearer "
+
+SESSION_TOKEN_KEY = "api_token"
+
+
+def validate_raw_token(raw: str | None) -> ApiToken | None:
+    raw = (raw or "").strip()
+    if not raw:
+        return None
+    token = ApiToken.objects.filter(token=raw, is_active=True).first()
+    if token is None:
+        logger.info("api: unknown or revoked token presented")
+        return None
+    try:
+        token.mark_used()
+    except Exception:  # noqa: BLE001
+        logger.warning("api: could not update last_used_at for token %s", token.name)
+    return token
+
+
+def extract_token(request: HttpRequest) -> ApiToken | None:
+    return validate_raw_token(_read_token_value(request))
+
+
+def request_has_valid_token(request: HttpRequest) -> bool:
+    return extract_token(request) is not None
+
+
+def request_can_ingest(request: HttpRequest) -> bool:
+    """True only for a valid INGEST token (push endpoints)."""
+    token = extract_token(request)
+    return token is not None and token.kind == TokenKind.INGEST
+
+
+def store_session_token(request: HttpRequest, token: ApiToken) -> None:
+    request.session[SESSION_TOKEN_KEY] = token.token
+
+
+def clear_session_token(request: HttpRequest) -> None:
+    request.session.pop(SESSION_TOKEN_KEY, None)
+
+
+def token_from_session(request: HttpRequest) -> ApiToken | None:
+    if not hasattr(request, "session"):
+        return None
+    return validate_raw_token(request.session.get(SESSION_TOKEN_KEY))
+
+
+def resolve_token(request: HttpRequest, *, allow_session: bool = True) -> ApiToken | None:
+    token = extract_token(request)
+    if token is not None:
+        return token
+    if allow_session:
+        return token_from_session(request)
+    return None
+
+
+def request_is_authenticated(request: HttpRequest, *, allow_session: bool = True) -> bool:
+    return resolve_token(request, allow_session=allow_session) is not None
+
+
+def _read_token_value(request: HttpRequest) -> str | None:
+    header = request.headers.get(_HEADER, "").strip()
+    if header:
+        if header.lower().startswith(_BEARER_PREFIX):
+            value = header[len(_BEARER_PREFIX):].strip()
+            if value:
+                return value
+        # Accept the raw value too if it's the only thing in the header.
+        elif " " not in header:
+            return header
+    qs_value = request.GET.get(_QUERY_PARAM, "").strip()
+    return qs_value or None

yksa_kit/checks.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from django.conf import settings
+from django.core.checks import Warning, register
+
+
+@register()
+def yksa_settings_declared(app_configs, **kwargs):
+    if getattr(settings, "YKSA_SERVICE", None):
+        return []
+    return [
+        Warning(
+            "YKSA_SERVICE is not set; cache keys fall back to the 'yksa' namespace.",
+            hint="Set YKSA_SERVICE to this service's slug in settings/base.py.",
+            id="yksa_kit.W001",
+        )
+    ]

yksa_kit/choices.py

@@ -0,0 +1,9 @@
+from django.db import models
+from django.utils.translation import gettext_lazy as _
+
+
+class RunStatus(models.TextChoices):
+    RUNNING = "running", _("Running")
+    SUCCESS = "success", _("Success")
+    FAILED = "failed", _("Failed")
+    SKIPPED = "skipped", _("Skipped")

yksa_kit/conf.py

@@ -0,0 +1,29 @@
+"""The two settings every service must declare, and their fallbacks."""
+
+from __future__ import annotations
+
+from django.conf import settings
+
+DEFAULT_SERVICE = "yksa"
+
+
+def service() -> str:
+    """Short service slug: ``tdas``, ``odms``, ``ops``.
+
+    Namespaces every cache key this package writes. The services share one Redis,
+    so a wrong or missing value silently merges two rate-limit budgets.
+    """
+    return getattr(settings, "YKSA_SERVICE", DEFAULT_SERVICE)
+
+
+def user_agent() -> str:
+    """Identifies us to the upstreams we poll; several ban unattributed clients."""
+    return getattr(
+        settings,
+        "YKSA_USER_AGENT",
+        f"yksa-{service()}/0.1 (+https://{service()}.tmtc.yksa.space)",
+    )
+
+
+def cache_key(*parts: str) -> str:
+    return ":".join((service(), *parts))

yksa_kit/context_processors.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from django.conf import settings
+from django.utils import timezone
+
+#: Quick-pick zones for the navbar switcher; override with YKSA_COMMON_TIMEZONES.
+DEFAULT_COMMON_TIMEZONES = ["UTC", "Europe/Moscow", "Asia/Yakutsk", "Asia/Tokyo"]
+
+
+def ui_preferences(request):
+    return {
+        "current_timezone_name": timezone.get_current_timezone_name(),
+        "common_timezones": getattr(
+            settings, "YKSA_COMMON_TIMEZONES", DEFAULT_COMMON_TIMEZONES
+        ),
+        "cookie_consent": request.COOKIES.get("yksa_cookie_consent", ""),
+    }

yksa_kit/host_rate_limit.py

@@ -0,0 +1,81 @@
+"""Redis-backed per-host token bucket for outbound HTTP calls.
+
+Shared across all Celery workers so that every task hitting, e.g.,
+``db.satnogs.org`` consumes from the same budget regardless of which worker
+picked it up. Two concurrent windows: per-minute (always) and optional per-hour,
+because Space-Track publishes 20/min *and* 200/hr ceilings.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from urllib.parse import urlparse
+
+from django.conf import settings
+from django.core.cache import cache
+
+from .conf import cache_key
+
+logger = logging.getLogger(__name__)
+
+
+def _bucket_key_minute(host: str) -> str:
+    return cache_key("host_rl", host)
+
+
+def _bucket_key_hour(host: str) -> str:
+    return cache_key("host_rl", "hour", host)
+
+
+def acquire(
+    host: str,
+    per_minute: int,
+    *,
+    per_hour: int = 0,
+    wait_seconds: float = 30.0,
+) -> None:
+    """Block (up to wait_seconds) until tokens are available for *host*."""
+    if not host or per_minute <= 0:
+        return
+
+    # Development has no shared Redis and no traffic worth pacing; blocking here
+    # would only make the dev server feel broken.
+    if not getattr(settings, "PRODUCTION", False):
+        logger.debug(
+            "host rate limit acquire: %s (per_minute=%d, per_hour=%d)",
+            host, per_minute, per_hour,
+        )
+        return
+
+    deadline = time.monotonic() + wait_seconds
+    if per_hour > 0:
+        _wait_for_window(_bucket_key_hour(host), per_hour, timeout=3600, deadline=deadline)
+    _wait_for_window(_bucket_key_minute(host), per_minute, timeout=60, deadline=deadline)
+
+
+def _wait_for_window(key: str, limit: int, *, timeout: int, deadline: float) -> None:
+    while True:
+        count = cache.get(key, 0)
+        if count < limit:
+            try:
+                count = cache.incr(key)
+            except ValueError:
+                cache.set(key, 1, timeout=timeout)
+                count = 1
+            if count <= limit:
+                return
+        sleep_for = min(1.0, max(0.05, deadline - time.monotonic()))
+        if time.monotonic() >= deadline:
+            # Proceeding over budget beats stalling a worker indefinitely; the
+            # upstream's own 429 handling in http.get() is the backstop.
+            logger.warning(
+                "host rate limit wait exceeded for %s (limit=%d, window=%ds)",
+                key, limit, timeout,
+            )
+            return
+        time.sleep(sleep_for)
+
+
+def host_from_url(url: str) -> str:
+    return (urlparse(url).hostname or "").lower()

yksa_kit/http.py

@@ -0,0 +1,82 @@
+"""Outbound HTTP helper with host-bucket rate limiting and simple retries."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+import httpx
+
+from . import host_rate_limit
+from .conf import user_agent
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TIMEOUT = httpx.Timeout(30.0, connect=10.0)
+
+
+def get(
+    url: str,
+    *,
+    host: str | None = None,
+    per_minute: int = 0,
+    per_hour: int = 0,
+    params: dict[str, Any] | None = None,
+    headers: dict[str, str] | None = None,
+    timeout: httpx.Timeout = DEFAULT_TIMEOUT,
+    max_retries: int = 3,
+) -> httpx.Response:
+    """GET *url*, respecting the per-host budget and retrying on 429/5xx.
+
+    ``host`` defaults to the URL's hostname; pass an explicit value to share a
+    bucket across subdomains (e.g. all Celestrak endpoints).
+    """
+    bucket_host = (host or host_rate_limit.host_from_url(url)).lower()
+    merged_headers = {"User-Agent": user_agent()}
+    if headers:
+        merged_headers.update(headers)
+
+    backoff = 1.0
+    last_exc: Exception | None = None
+    for attempt in range(1, max_retries + 1):
+        host_rate_limit.acquire(bucket_host, per_minute, per_hour=per_hour)
+        try:
+            with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+                resp = client.get(url, params=params, headers=merged_headers)
+        except httpx.HTTPError as exc:
+            last_exc = exc
+            logger.warning("http GET %s failed (attempt %d): %s", url, attempt, exc)
+            if attempt == max_retries:
+                raise
+            time.sleep(backoff)
+            backoff *= 2
+            continue
+
+        if resp.status_code == 429 or resp.status_code >= 500:
+            retry_after = _parse_retry_after(resp.headers.get("Retry-After"))
+            sleep_for = retry_after if retry_after is not None else backoff
+            logger.info(
+                "http GET %s -> %d, retry in %.1fs (attempt %d)",
+                url, resp.status_code, sleep_for, attempt,
+            )
+            if attempt == max_retries:
+                resp.raise_for_status()
+            time.sleep(sleep_for)
+            backoff *= 2
+            continue
+
+        resp.raise_for_status()
+        return resp
+
+    assert last_exc is not None  # pragma: no cover
+    raise last_exc
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        return None

yksa_kit/middleware.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from django.utils import timezone
+
+
+class UserTimezoneMiddleware:
+    """Activate the visitor's selected timezone (defaults to UTC).
+
+    Everything is stored in UTC; this is the only place display time is chosen,
+    so a page that renders a naive local time is a bug in the template, not here.
+    """
+
+    SESSION_KEY = "user_timezone"
+    DEFAULT_TIMEZONE = "UTC"
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        tz_name = request.session.get(self.SESSION_KEY, self.DEFAULT_TIMEZONE)
+        try:
+            timezone.activate(ZoneInfo(tz_name))
+            request.current_timezone_name = tz_name
+        except (ZoneInfoNotFoundError, ValueError):
+            timezone.activate(ZoneInfo(self.DEFAULT_TIMEZONE))
+            request.current_timezone_name = self.DEFAULT_TIMEZONE
+
+        response = self.get_response(request)
+        timezone.deactivate()
+        return response

yksa_kit/migrations/0001_initial.py

@@ -0,0 +1,30 @@
+import yksa_kit.models
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name='ApiToken',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('name', models.CharField(help_text="Human-readable label, e.g. 'TMTC pipeline' or 'ground station 1'.", max_length=64, unique=True)),
+                ('token', models.CharField(db_index=True, default=yksa_kit.models._generate_token, editable=False, help_text='Bearer credential. Treat as a secret.', max_length=128, unique=True)),
+                ('kind', models.CharField(choices=[('read', 'Read (non-public visibility)'), ('ingest', 'Ingest (push)')], default='read', help_text='Read tokens extend visibility; ingest tokens may also push data.', max_length=16)),
+                ('is_active', models.BooleanField(db_index=True, default=True)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('last_used_at', models.DateTimeField(blank=True, null=True)),
+                ('notes', models.TextField(blank=True)),
+            ],
+            options={
+                'verbose_name': 'API token',
+                'verbose_name_plural': 'API tokens',
+                'ordering': ['-created_at'],
+            },
+        ),
+    ]

yksa_kit/models.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import secrets
+
+from django.db import models
+from django.utils import timezone
+from django.utils.translation import gettext_lazy as _
+
+
+def _generate_token() -> str:
+    return secrets.token_urlsafe(32)
+
+
+class TokenKind(models.TextChoices):
+    READ = "read", _("Read (non-public visibility)")
+    INGEST = "ingest", _("Ingest (push)")
+
+
+class ApiToken(models.Model):
+    """Static API token for machine clients. Not tied to a user, no scopes.
+
+    Read tokens extend visibility to non-public records; ingest tokens may also
+    push data (ground-station frames in tdas, station logs in ops). A service
+    that has nothing to ingest simply never issues the second kind.
+    """
+
+    name = models.CharField(
+        max_length=64,
+        unique=True,
+        help_text=_("Human-readable label, e.g. 'TMTC pipeline' or 'ground station 1'."),
+    )
+    token = models.CharField(
+        max_length=128,
+        unique=True,
+        default=_generate_token,
+        editable=False,
+        db_index=True,
+        help_text=_("Bearer credential. Treat as a secret."),
+    )
+    kind = models.CharField(
+        max_length=16,
+        choices=TokenKind.choices,
+        default=TokenKind.READ,
+        help_text=_("Read tokens extend visibility; ingest tokens may also push data."),
+    )
+    is_active = models.BooleanField(default=True, db_index=True)
+
+    created_at = models.DateTimeField(auto_now_add=True)
+    last_used_at = models.DateTimeField(null=True, blank=True)
+    notes = models.TextField(blank=True)
+
+    class Meta:
+        ordering = ["-created_at"]
+        verbose_name = _("API token")
+        verbose_name_plural = _("API tokens")
+
+    def __str__(self) -> str:
+        return self.name
+
+    def mark_used(self) -> None:
+        # Written on every authenticated request, so it must not touch the rest
+        # of the row: a full save() here would clobber a concurrent admin edit.
+        self.last_used_at = timezone.now()
+        type(self).objects.filter(pk=self.pk).update(last_used_at=self.last_used_at)

yksa_kit/settings.py

@@ -0,0 +1,34 @@
+"""Settings helpers. Imported from a service's ``settings/base.py``."""
+
+from __future__ import annotations
+
+import os
+
+_TRUE = {"1", "true", "yes", "on"}
+
+
+def read_secret(secret_name: str, default: str | None = None) -> str | None:
+    """Resolution order: docker secret, then fall back to environment, then to default.
+    """
+    secret_path = f"/run/secrets/{secret_name}"
+    if os.path.exists(secret_path):
+        with open(secret_path, "r", encoding="utf-8") as file:
+            return file.read().strip()
+    return os.getenv(secret_name.upper(), default)
+
+
+def env_bool(name: str, default: bool = False) -> bool:
+    """Accepts 1/true/yes/on in any case.
+
+    Exists because ``os.getenv("X") == "True"`` silently ignored ``TRUE`` and
+    ``1`` in two of the services' compose files.
+    """
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in _TRUE
+
+
+def env_list(name: str, default: list[str] | None = None) -> list[str]:
+    raw = os.getenv(name, "")
+    return [item.strip() for item in raw.split(",") if item.strip()] or list(default or [])

yksa_kit/states.py

@@ -0,0 +1,30 @@
+"""Domain status -> UI state name.
+
+Lives here rather than in yksa-web-kit because it is a property of the data, not
+of the presentation: a model exposes ``ui_state`` and the template renders it.
+The visual vocabulary — which icon and word each state gets — is the web kit's
+half, in ``yksa_web.states``.
+"""
+
+from __future__ import annotations
+
+#: Every service's RunStatus-like TextChoices overlaps by value, so one table
+#: covers them all.
+_HEALTH = {
+    "ok": "ok",
+    "success": "ok",
+    "partial": "warning",
+    "warning": "warning",
+    "failed": "failed",
+    "error": "failed",
+    "running": "running",
+    "pending": "running",
+    "queued": "running",
+    "skipped": "skipped",
+}
+
+
+def health_state(value: str | None) -> str:
+    """A value absent from the table renders as ``unknown`` rather than blank —
+    a status the reader can see beats one that silently disappears."""
+    return _HEALTH.get((value or "").lower(), "unknown")

yksa_kit/urls.py

@@ -0,0 +1,18 @@
+"""The routes every service shares. Include unprefixed from the project urlconf:
+
+    path("", include("yksa_kit.urls")),
+
+URL names are unprefixed too (``health-check``, ``timezone-preferences``,
+``privacy-policy``, ``cookie-policy``) because the shared chrome reverses them.
+"""
+
+from django.urls import path
+
+from . import views
+
+urlpatterns = [
+    path("health/", views.health_check, name="health-check"),
+    path("preferences/timezone/", views.timezone_preferences, name="timezone-preferences"),
+    path("privacy/", views.privacy_policy, name="privacy-policy"),
+    path("cookies/", views.cookie_policy, name="cookie-policy"),
+]

yksa_kit/views.py

@@ -0,0 +1,97 @@
+"""Project-level views every service exposes: health, timezone, legal pages."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from zoneinfo import available_timezones
+
+from django.contrib import messages
+from django.db import connection
+from django.http import JsonResponse
+from django.shortcuts import redirect, render
+from django.urls import reverse
+from django.utils import timezone
+from django.utils.http import url_has_allowed_host_and_scheme
+from django.utils.translation import gettext as _
+
+from .context_processors import DEFAULT_COMMON_TIMEZONES
+
+
+@lru_cache(maxsize=1)
+def _timezone_name_options():
+    try:
+        names = sorted(available_timezones())
+    except Exception:
+        names = list(DEFAULT_COMMON_TIMEZONES)
+
+    preferred = ["UTC", "Europe/Moscow", "Asia/Yakutsk"]
+    ordered = [n for n in preferred if n in names]
+    ordered += [n for n in names if n not in ordered]
+    return ordered
+
+
+def _safe_next_url(request, candidate):
+    if candidate and url_has_allowed_host_and_scheme(
+        candidate,
+        allowed_hosts={request.get_host()},
+        require_https=request.is_secure(),
+    ):
+        return candidate
+    return reverse("timezone-preferences")
+
+
+def privacy_policy(request):
+    return render(request, "privacy_policy.html")
+
+
+def cookie_policy(request):
+    return render(request, "cookie_policy.html")
+
+
+def timezone_preferences(request):
+    timezone_names = _timezone_name_options()
+    timezone_set = set(timezone_names)
+
+    selected_timezone = request.session.get("user_timezone", "UTC")
+    if selected_timezone not in timezone_set:
+        selected_timezone = "UTC"
+
+    if request.method == "POST":
+        selected_timezone = (request.POST.get("timezone") or "UTC").strip()
+        if selected_timezone not in timezone_set:
+            messages.error(request, _("Selected time zone is not supported."))
+        else:
+            request.session["user_timezone"] = selected_timezone
+            request.session.modified = True
+            messages.success(request, _("Time zone preference saved."))
+            return redirect(_safe_next_url(request, request.POST.get("next")))
+
+    return render(request, "timezone_preferences.html", {
+        "timezone_names": timezone_names,
+        "selected_timezone": selected_timezone,
+        "next_url": _safe_next_url(
+            request, request.GET.get("next") or request.META.get("HTTP_REFERER"),
+        ),
+    })
+
+
+def health_check(request):
+    """Swarm healthcheck target: it must answer without a database, not raise."""
+    try:
+        with connection.cursor() as cursor:
+            cursor.execute("SELECT 1")
+        return JsonResponse({
+            "status": "healthy",
+            "timestamp": timezone.now().isoformat(),
+            "database": "connected",
+        })
+    except Exception as exc:
+        return JsonResponse(
+            {
+                "status": "unhealthy",
+                "timestamp": timezone.now().isoformat(),
+                "database": "disconnected",
+                "error": str(exc),
+            },
+            status=503,
+        )