Initial commit

.gitignore

@@ -0,0 +1,155 @@
+
+# Created by https://www.toptal.com/developers/gitignore/api/python
+# Edit at https://www.toptal.com/developers/gitignore?templates=python
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+	
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+pytestdebug.log
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+doc/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+pythonenv*
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# profiling data
+.prof
+
+# Db and static files
+*.sqlite3
+/media
+/static
+/postgres
+/EXAMPLE_*
+
+# Docker
+docker-compose.override.yml
+docker-compose.override
+
+# End of https://www.toptal.com/developers/gitignore/api/python

README.md

@@ -0,0 +1,71 @@
+# yksa-django-kit
+
+Common Django modules for use across various YKSA services.
+
+## Install
+
+```
+yksa-django-kit @ git+https://git.intra.yksa.space/web/yksa-django-kit.git@v0.1.0
+```
+
+## Wire up
+
+```python
+# settings/base.py
+from yksa_kit.settings import read_secret, env_bool
+
+YKSA_SERVICE = "tdas"                                       # required
+YKSA_USER_AGENT = "yksa-tdas/0.1 (+https://tdas.tmtc.yksa.space)"
+
+INSTALLED_APPS = [..., "yksa_kit", ...]
+MIDDLEWARE = [..., "yksa_kit.middleware.UserTimezoneMiddleware", ...]
+TEMPLATES[0]["OPTIONS"]["context_processors"] += [
+    "yksa_kit.context_processors.ui_preferences",
+]
+```
+
+```python
+# urls.py
+urlpatterns = [
+    path("", include("yksa_kit.urls")),
+    ...
+]
+```
+
+`YKSA_SERVICE` is used as the Redis cache key, don't leave it unset. 
+
+The templates the timezone and policy views render (`timezone_preferences.html`,
+`privacy_policy.html`, `cookie_policy.html`) come from
+[yksa-web-kit](../yksa-web-kit).
+
+## What is in it
+
+| Module | |
+|---|---|
+| `models.ApiToken` | static bearer token, `read` or `ingest` |
+| `auth` | header / query / session carriers, `request_has_valid_token`, `request_can_ingest` |
+| `admin` | `ApiToken` admin |
+| `choices.RunStatus` | running / success / failed / skipped |
+| `http.get` | retries 429 and 5xx, honours `Retry-After`, sends the service User-Agent |
+| `host_rate_limit` | Redis fixed-window buckets, per-minute and per-hour |
+| `middleware.UserTimezoneMiddleware` | activates the session timezone |
+| `context_processors.ui_preferences` | timezone name, quick-pick zones, cookie consent |
+| `views` + `urls` | health, timezone preferences, privacy, cookies |
+| `settings` | `read_secret`, `env_bool`, `env_list` |
+
+## Migrating a service
+
+`ApiToken` moves from `<project>.core` (table `<label>_apitoken`) to `yksa_kit`
+(table `yksa_kit_apitoken`). None of the tmtc services is deployed, so the cheap
+path is taken: reset the migrations and re-issue the tokens (where needed) manually.
+
+## Tests
+
+```sh
+pip install -e ".[test]"
+python -m pytest
+```
+
+They run against `tests/settings.py`, a Django project with nothing in it but
+this package -- which is the point: if a test needs a service, the code belongs in
+the service.

pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "yksa-django-kit"
+version = "0.1.0"
+description = "Cross-cutting Django plumbing shared by the YKSA TMTC services"
+requires-python = ">=3.13"
+license = { text = "Proprietary" }
+dependencies = [
+    "Django>=5.2",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+    "pytest-django>=4.8",
+]
+
+[tool.setuptools.packages.find]
+include = ["yksa_kit*"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+python_files = ["test_*.py"]

tests/settings.py

@@ -0,0 +1,43 @@
+"""Minimal Django project, just enough to exercise the kit in isolation."""
+
+SECRET_KEY = "test-only"
+DEBUG = True
+PRODUCTION = False
+USE_TZ = True
+
+YKSA_SERVICE = "kit"
+
+INSTALLED_APPS = [
+    "django.contrib.contenttypes",
+    "django.contrib.auth",
+    "django.contrib.sessions",
+    "django.contrib.messages",
+    "yksa_kit",
+]
+
+MIDDLEWARE = [
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "yksa_kit.middleware.UserTimezoneMiddleware",
+    "django.contrib.messages.middleware.MessageMiddleware",
+]
+
+DATABASES = {
+    "default": {"ENGINE": "django.db.backends.sqlite3", "NAME": ":memory:"},
+}
+
+ROOT_URLCONF = "tests.urls"
+
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "APP_DIRS": True,
+        "OPTIONS": {"context_processors": [
+            "django.contrib.messages.context_processors.messages",
+            "yksa_kit.context_processors.ui_preferences",
+        ]},
+    },
+]
+
+CACHES = {
+    "default": {"BACKEND": "django.core.cache.backends.locmem.LocMemCache"},
+}

tests/test_auth.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import pytest
+from django.test import RequestFactory
+
+from yksa_kit.auth import (
+    extract_token,
+    request_can_ingest,
+    request_has_valid_token,
+    resolve_token,
+    store_session_token,
+)
+from yksa_kit.models import ApiToken, TokenKind
+
+
+@pytest.fixture
+def rf() -> RequestFactory:
+    return RequestFactory()
+
+
+@pytest.mark.django_db
+def test_returns_none_when_no_credentials(rf):
+    assert extract_token(rf.get("/api/v1/things/")) is None
+    assert request_has_valid_token(rf.get("/api/v1/things/")) is False
+
+
+@pytest.mark.django_db
+def test_authorization_bearer_header(rf):
+    token = ApiToken.objects.create(name="ci-job")
+    resolved = extract_token(rf.get("/", HTTP_AUTHORIZATION=f"Bearer {token.token}"))
+    assert resolved is not None and resolved.pk == token.pk
+
+
+@pytest.mark.django_db
+def test_authorization_raw_header_accepted(rf):
+    """Plain header value without the 'Bearer ' prefix is tolerated."""
+    token = ApiToken.objects.create(name="legacy-client")
+    assert extract_token(rf.get("/", HTTP_AUTHORIZATION=token.token)) is not None
+
+
+@pytest.mark.django_db
+def test_query_string_token(rf):
+    token = ApiToken.objects.create(name="browser")
+    assert extract_token(rf.get("/", {"api_token": token.token})) is not None
+
+
+@pytest.mark.django_db
+def test_revoked_token_is_anonymous(rf):
+    token = ApiToken.objects.create(name="revoked", is_active=False)
+    assert extract_token(rf.get("/", HTTP_AUTHORIZATION=f"Bearer {token.token}")) is None
+
+
+@pytest.mark.django_db
+def test_unknown_token_is_anonymous(rf):
+    assert extract_token(rf.get("/", HTTP_AUTHORIZATION="Bearer nope")) is None
+
+
+@pytest.mark.django_db
+def test_extract_token_updates_last_used(rf):
+    token = ApiToken.objects.create(name="track-me")
+    assert token.last_used_at is None
+    extract_token(rf.get("/", HTTP_AUTHORIZATION=f"Bearer {token.token}"))
+    token.refresh_from_db()
+    assert token.last_used_at is not None
+
+
+@pytest.mark.django_db
+def test_only_ingest_tokens_may_push(rf):
+    read = ApiToken.objects.create(name="reader")
+    ingest = ApiToken.objects.create(name="station", kind=TokenKind.INGEST)
+    assert request_can_ingest(rf.get("/", {"api_token": read.token})) is False
+    assert request_can_ingest(rf.get("/", {"api_token": ingest.token})) is True
+
+
+@pytest.mark.django_db
+def test_session_token_is_ignored_by_the_api_path(rf):
+    """The session carrier is for browser pages only; an API controller asking
+    request_has_valid_token() must not be authenticated by a stale session."""
+    token = ApiToken.objects.create(name="browser")
+    request = rf.get("/")
+    request.session = {}
+    store_session_token(request, token)
+
+    assert request_has_valid_token(request) is False
+    assert resolve_token(request) is not None

tests/test_health_and_settings.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import json
+
+import pytest
+from django.test import Client, override_settings
+
+from yksa_kit.conf import cache_key, user_agent
+from yksa_kit.settings import env_bool, env_list, read_secret
+
+
+@pytest.mark.django_db
+def test_health_reports_the_database():
+    response = Client().get("/health/")
+    assert response.status_code == 200
+    assert json.loads(response.content)["database"] == "connected"
+
+
+def test_cache_keys_are_namespaced_per_service():
+    """Two services share one Redis; an unnamespaced key merges their budgets."""
+    assert cache_key("host_rl", "example.com") == "kit:host_rl:example.com"
+
+
+def test_user_agent_falls_back_to_the_service_slug():
+    assert user_agent().startswith("yksa-kit/")
+
+
+@override_settings(YKSA_USER_AGENT="yksa-tdas/0.1 (+https://tdas.tmtc.yksa.space)")
+def test_user_agent_is_overridable():
+    assert "tdas" in user_agent()
+
+
+def test_env_bool_accepts_the_spellings_compose_files_actually_use(monkeypatch):
+    for raw in ("1", "true", "TRUE", "True", "yes", "on"):
+        monkeypatch.setenv("YKSA_TEST_FLAG", raw)
+        assert env_bool("YKSA_TEST_FLAG") is True
+    monkeypatch.setenv("YKSA_TEST_FLAG", "0")
+    assert env_bool("YKSA_TEST_FLAG") is False
+    monkeypatch.delenv("YKSA_TEST_FLAG")
+    assert env_bool("YKSA_TEST_FLAG", default=True) is True
+
+
+def test_env_list_splits_and_strips(monkeypatch):
+    monkeypatch.setenv("YKSA_TEST_HOSTS", "a.example, b.example ,")
+    assert env_list("YKSA_TEST_HOSTS") == ["a.example", "b.example"]
+
+
+def test_read_secret_falls_back_to_the_environment(monkeypatch):
+    monkeypatch.setenv("YKSA_TEST_SECRET", "from-env")
+    assert read_secret("yksa_test_secret") == "from-env"
+    assert read_secret("yksa_absent_secret") is None

tests/test_host_rate_limit.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from django.core.cache import cache
+from django.test import override_settings
+
+from yksa_kit import host_rate_limit
+
+
+def test_host_from_url():
+    assert host_rate_limit.host_from_url("https://Db.SatNOGS.org/api/") == "db.satnogs.org"
+    assert host_rate_limit.host_from_url("not a url") == ""
+
+
+def test_development_never_blocks():
+    cache.clear()
+    host_rate_limit.acquire("example.com", per_minute=1)
+    host_rate_limit.acquire("example.com", per_minute=1)
+    assert cache.get("kit:host_rl:example.com") is None
+
+
+@override_settings(PRODUCTION=True)
+def test_production_counts_against_the_minute_window():
+    cache.clear()
+    host_rate_limit.acquire("example.com", per_minute=5)
+    assert cache.get("kit:host_rl:example.com") == 1
+
+
+@override_settings(PRODUCTION=True)
+def test_a_zero_budget_means_unlimited():
+    """per_minute=0 is how a source says 'no published limit', not 'no requests'."""
+    cache.clear()
+    host_rate_limit.acquire("example.com", per_minute=0)
+    assert cache.get("kit:host_rl:example.com") is None
+
+
+@override_settings(PRODUCTION=True)
+def test_the_wait_gives_up_rather_than_stalling_the_worker():
+    cache.clear()
+    cache.set("kit:host_rl:example.com", 99, timeout=60)
+    host_rate_limit.acquire("example.com", per_minute=1, wait_seconds=0.0)

tests/test_states.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import pytest
+
+from yksa_kit.choices import RunStatus
+from yksa_kit.states import health_state
+
+
+@pytest.mark.parametrize("status,expected", [
+    ("success", "ok"), ("ok", "ok"), ("partial", "warning"), ("failed", "failed"),
+    ("error", "failed"), ("running", "running"), ("pending", "running"),
+    ("queued", "running"), ("skipped", "skipped"),
+    ("", "unknown"), (None, "unknown"), ("something-new", "unknown"),
+])
+def test_domain_status_maps_to_one_vocabulary(status, expected):
+    assert health_state(status) == expected
+
+
+@pytest.mark.parametrize("value", RunStatus.values)
+def test_every_run_status_has_a_state(value):
+    """A new RunStatus member without a mapping would render as `unknown` on every
+    status page, which reads as a bug in the poller rather than a missing table row."""
+    assert health_state(value) != "unknown"

tests/urls.py

@@ -0,0 +1,3 @@
+from django.urls import include, path
+
+urlpatterns = [path("", include("yksa_kit.urls"))]

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,
+        )