django-stack 0.0.1__tar.gz → 0.1.0__tar.gz

django_stack-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.5
+Name: django-stack
+Version: 0.1.0
+Summary: The backend glue of DjangoStack: settings from environment variables, API defaults, health checks and system checks.
+Project-URL: Homepage, https://github.com/dwarsbit/django-stack
+Project-URL: Source, https://github.com/dwarsbit/django-stack/tree/main/python/django-stack
+Project-URL: Issues, https://github.com/dwarsbit/django-stack/issues
+Author-email: Leon van der Grient <leon@dwarsbit.nl>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cms,django,django-content-studio,django-headless,headless,jamstack
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Requires-Dist: django-content-studio[huey,images]<2,>=1.8
+Requires-Dist: django-headless[schema]<2,>=1.1.1
+Requires-Dist: django<7,>=5.2
+Requires-Dist: djangorestframework<4,>=3.17
+Provides-Extra: s3
+Requires-Dist: django-storages[s3]>=1.14; extra == 's3'
+Provides-Extra: server
+Requires-Dist: gunicorn>=26; extra == 'server'
+Requires-Dist: psycopg[binary]>=3.2; extra == 'server'
+Requires-Dist: redis>=5; extra == 'server'
+Requires-Dist: uvicorn-worker>=0.3; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.34; extra == 'server'
+Requires-Dist: whitenoise>=6.9; extra == 'server'
+Description-Content-Type: text/markdown
+
+# django-stack
+
+The backend glue of [DjangoStack](https://github.com/dwarsbit/django-stack).
+Projects created with `npx @django-stack/cli init` depend on it.
+
+- `django_stack.settings.configure()` sets Django's settings from environment
+  variables: database, cache, task queue, mail, storage, security, and safe
+  defaults for Django Headless and Django Content Studio.
+- `PublishableModel`: draft and published content, with preview access.
+- API defaults: a closed API with a full-access and a read-only key, and
+  rate-limited public forms.
+- Preview tokens and signed revalidation requests to the frontend.
+- `/healthz` and `/readyz`, system checks, and the management commands
+  `create_admin`, `seed_content`, `export_content`, `import_content` and
+  `wait_for_db`.
+
+```python
+# config/settings.py
+from pathlib import Path
+
+from django_stack.settings import configure
+
+configure(globals(), base_dir=Path(__file__).resolve().parent.parent)
+```
+
+## License
+
+MIT; see [LICENSE](LICENSE).

django_stack-0.1.0/README.md

@@ -0,0 +1,28 @@
+# django-stack
+
+The backend glue of [DjangoStack](https://github.com/dwarsbit/django-stack).
+Projects created with `npx @django-stack/cli init` depend on it.
+
+- `django_stack.settings.configure()` sets Django's settings from environment
+  variables: database, cache, task queue, mail, storage, security, and safe
+  defaults for Django Headless and Django Content Studio.
+- `PublishableModel`: draft and published content, with preview access.
+- API defaults: a closed API with a full-access and a read-only key, and
+  rate-limited public forms.
+- Preview tokens and signed revalidation requests to the frontend.
+- `/healthz` and `/readyz`, system checks, and the management commands
+  `create_admin`, `seed_content`, `export_content`, `import_content` and
+  `wait_for_db`.
+
+```python
+# config/settings.py
+from pathlib import Path
+
+from django_stack.settings import configure
+
+configure(globals(), base_dir=Path(__file__).resolve().parent.parent)
+```
+
+## License
+
+MIT; see [LICENSE](LICENSE).

{django_stack-0.0.1 → django_stack-0.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "django-stack"
-version = "0.0.1"
+version = "0.1.0"
 description = "The backend glue of DjangoStack: settings from environment variables, API defaults, health checks and system checks."
 readme = "README.md"
 license = "MIT"
@@ -20,7 +20,23 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
 ]
-dependencies = ["Django>=5.2,<7"]
+dependencies = [
+    "Django>=5.2,<7",
+    "djangorestframework>=3.17,<4",
+    "django-headless[schema]>=1.1.1,<2",
+    "django-content-studio[images,huey]>=1.8,<2",
+]
+
+[project.optional-dependencies]
+server = [
+    "gunicorn>=26",
+    "uvicorn[standard]>=0.34",
+    "uvicorn-worker>=0.3",
+    "whitenoise>=6.9",
+    "psycopg[binary]>=3.2",
+    "redis>=5",
+]
+s3 = ["django-storages[s3]>=1.14"]
 
 [project.urls]
 Homepage = "https://github.com/dwarsbit/django-stack"
@@ -28,7 +44,13 @@ Source = "https://github.com/dwarsbit/django-stack/tree/main/python/django-stack
 Issues = "https://github.com/dwarsbit/django-stack/issues"
 
 [dependency-groups]
-dev = ["pytest>=8", "pytest-django>=4.11", "ruff>=0.15"]
+dev = [
+    "pytest>=8",
+    "pytest-django>=4.11",
+    "ruff>=0.15",
+    "django-storages[s3]>=1.14",
+    "whitenoise>=6.9",
+]
 
 [build-system]
 requires = ["hatchling>=1.27"]

{django_stack-0.0.1 → django_stack-0.1.0}/src/django_stack/__init__.py

@@ -1,3 +1,3 @@
 """The backend glue of DjangoStack."""
 
-__version__ = "0.0.1"
+__version__ = "0.1.0"

django_stack-0.1.0/src/django_stack/apps.py

@@ -0,0 +1,19 @@
+from django.apps import AppConfig
+
+
+class DjangoStackConfig(AppConfig):
+    name = "django_stack"
+    label = "django_stack"
+    verbose_name = "DjangoStack"
+
+    def ready(self):
+        from . import checks  # noqa: F401 - registers the system checks
+
+        try:
+            from content_studio.signals import content_changed
+        except ImportError:  # pragma: no cover - Content Studio is not installed
+            return
+
+        from .contrib.revalidate.receivers import on_content_changed
+
+        content_changed.connect(on_content_changed, dispatch_uid="django_stack_revalidate")

django_stack-0.1.0/src/django_stack/backup.py

@@ -0,0 +1,199 @@
+"""
+Database backups: ``pg_dump`` to a directory and, optionally, to a private
+S3 bucket, with retention.
+
+The ``backup`` service of a project runs ``run_backups``, which calls
+:func:`create_backup` once a day. ``backup_database`` makes one now and
+``restore_database`` restores one.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+
+from . import conf
+
+NAME_PATTERN = re.compile(r"^(?P<prefix>.+)-(?P<stamp>\d{8}T\d{6}Z)\.dump$")
+
+
+@dataclass
+class Backup:
+    name: str
+    path: Path
+    uploaded: bool = False
+
+
+def _database() -> dict:
+    database = settings.DATABASES["default"]
+    if "postgresql" not in database["ENGINE"]:
+        raise ImproperlyConfigured("Backups need a Postgres database; DATABASE_URL is not postgres://.")
+    return database
+
+
+def pg_environment(database: dict | None = None) -> dict[str, str]:
+    """The environment for pg_dump and pg_restore: connection values as PG* variables."""
+    database = database or _database()
+    env = dict(os.environ)
+    values = {
+        "PGHOST": database.get("HOST") or "localhost",
+        "PGPORT": str(database.get("PORT") or 5432),
+        "PGUSER": database.get("USER") or "",
+        "PGPASSWORD": database.get("PASSWORD") or "",
+        "PGDATABASE": database.get("NAME") or "",
+    }
+    sslmode = (database.get("OPTIONS") or {}).get("sslmode")
+    if sslmode:
+        values["PGSSLMODE"] = sslmode
+    env.update({key: value for key, value in values.items() if value})
+    return env
+
+
+def backup_dir() -> Path:
+    path = Path(conf.get("BACKUP_DIR") or Path(settings.BASE_DIR) / "backups")
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def backup_name(now: datetime | None = None) -> str:
+    now = now or datetime.now(UTC)
+    prefix = re.sub(r"[^a-zA-Z0-9_-]+", "-", getattr(settings, "PROJECT_NAME", "") or "backup")
+    return f"{prefix}-{now.strftime('%Y%m%dT%H%M%SZ')}.dump"
+
+
+def s3_client():
+    """A boto3 client for the backup bucket, with the S3_* credentials."""
+    import boto3
+
+    options = conf.get("BACKUP_S3") or {}
+    return boto3.client(
+        "s3",
+        endpoint_url=options.get("endpoint_url"),
+        region_name=options.get("region_name"),
+        aws_access_key_id=options.get("access_key"),
+        aws_secret_access_key=options.get("secret_key"),
+    )
+
+
+def _s3_target() -> tuple[str, str] | None:
+    bucket = conf.get("BACKUP_S3_BUCKET")
+    if not bucket:
+        return None
+    prefix = (conf.get("BACKUP_S3_PREFIX") or "").strip("/")
+    return bucket, f"{prefix}/" if prefix else ""
+
+
+def create_backup(*, keep: int | None = None) -> Backup:
+    """Dump the database, upload it when a backup bucket is set, and apply the retention."""
+    pg_dump = shutil.which("pg_dump")
+    if pg_dump is None:
+        raise ImproperlyConfigured("pg_dump is not installed; install the Postgres client.")
+    directory = backup_dir()
+    name = backup_name()
+    path = directory / name
+    partial = path.with_suffix(".partial")
+    subprocess.run(  # noqa: S603 (fixed arguments, no shell)
+        [pg_dump, "--format=custom", "--no-owner", "--no-acl", "--file", str(partial)],
+        env=pg_environment(),
+        check=True,
+        capture_output=True,
+    )
+    partial.rename(path)
+    path.chmod(0o600)
+    backup = Backup(name=name, path=path)
+
+    target = _s3_target()
+    if target:
+        bucket, prefix = target
+        s3_client().upload_file(str(path), bucket, f"{prefix}{name}")
+        backup.uploaded = True
+
+    prune(keep if keep is not None else conf.get("BACKUP_KEEP"))
+    return backup
+
+
+def _sorted_names(names) -> list[str]:
+    return sorted(
+        (name for name in names if NAME_PATTERN.match(name)),
+        key=lambda name: NAME_PATTERN.match(name)["stamp"],
+    )
+
+
+def local_backups() -> list[str]:
+    return _sorted_names(path.name for path in backup_dir().iterdir())
+
+
+def remote_backups() -> list[str]:
+    target = _s3_target()
+    if not target:
+        return []
+    bucket, prefix = target
+    names = []
+    for page in s3_client().get_paginator("list_objects_v2").paginate(Bucket=bucket, Prefix=prefix):
+        names += [item["Key"][len(prefix) :] for item in page.get("Contents", [])]
+    return _sorted_names(names)
+
+
+def prune(keep: int) -> list[str]:
+    """Delete all but the ``keep`` newest backups, locally and in the bucket."""
+    removed = []
+    if keep is None or keep <= 0:
+        return removed
+    for name in local_backups()[:-keep]:
+        (backup_dir() / name).unlink(missing_ok=True)
+        removed.append(name)
+    target = _s3_target()
+    if target:
+        bucket, prefix = target
+        client = s3_client()
+        for name in remote_backups()[:-keep]:
+            client.delete_object(Bucket=bucket, Key=f"{prefix}{name}")
+            removed.append(f"s3://{bucket}/{prefix}{name}")
+    return removed
+
+
+def fetch_backup(name: str) -> Path:
+    """The path of a local backup, downloading it from the bucket when it is only there."""
+    path = Path(name)
+    if path.is_file():
+        return path
+    local = backup_dir() / path.name
+    if local.is_file():
+        return local
+    target = _s3_target()
+    if target and NAME_PATTERN.match(path.name):
+        bucket, prefix = target
+        s3_client().download_file(bucket, f"{prefix}{path.name}", str(local))
+        return local
+    raise FileNotFoundError(f"No backup named {name} in {backup_dir()} or the backup bucket.")
+
+
+def restore_backup(path: Path) -> None:
+    """Restore a dump over the current database: objects in the dump are dropped and recreated."""
+    pg_restore = shutil.which("pg_restore")
+    if pg_restore is None:
+        raise ImproperlyConfigured("pg_restore is not installed; install the Postgres client.")
+    subprocess.run(  # noqa: S603 (fixed arguments, no shell)
+        [
+            pg_restore,
+            "--clean",
+            "--if-exists",
+            "--no-owner",
+            "--no-acl",
+            "--single-transaction",
+            "--dbname",
+            _database()["NAME"],
+            str(path),
+        ],
+        env=pg_environment(),
+        check=True,
+        capture_output=True,
+    )

django_stack-0.1.0/src/django_stack/checks.py

@@ -0,0 +1,135 @@
+"""
+DjangoStack's system checks.
+
+- ``django_stack.E001``: the read-only API key is the full-access key.
+- ``django_stack.E002``: no read-only API key, so the frontend cannot read content.
+- ``django_stack.E003``: ``DEBUG`` is on while ``SITE_URL`` is https.
+- ``django_stack.E004``: a model in ``PUBLIC_CREATE`` is not installed.
+- ``django_stack.W001``: ``REVALIDATE_URL`` without ``REVALIDATE_SECRET``, so the
+  frontend is never told about changes.
+- ``django_stack.W002``: no ``PREVIEW_SECRET``, so editors cannot preview drafts.
+- ``django_stack.W003`` (deploy): ``SECRET_KEY`` shorter than 50 characters.
+- ``django_stack.W004`` (deploy): the cache is per process, so throttles,
+  sessions and presence are not shared between workers.
+- ``django_stack.W005`` (deploy): ``SITE_URL`` is https but ``NUM_PROXIES`` is 0,
+  so Django does not see that requests came in over HTTPS.
+"""
+
+from django.apps import apps
+from django.conf import settings
+from django.core.checks import Error, Tags, Warning, register
+
+from . import conf
+
+
+def _headless():
+    return getattr(settings, "HEADLESS", None) or {}
+
+
+@register(Tags.security)
+def check_api_keys(app_configs, **kwargs):
+    errors = []
+    write_key = _headless().get("AUTH_SECRET_KEY")
+    read_key = _headless().get("AUTH_READ_ONLY_SECRET_KEY")
+    if write_key and read_key and write_key == read_key:
+        errors.append(
+            Error(
+                "API_READ_KEY is the same as API_SECRET_KEY.",
+                hint="Generate a separate read-only key: the frontend must not hold a key that can write.",
+                id="django_stack.E001",
+            )
+        )
+    if not read_key:
+        errors.append(
+            Error(
+                "API_READ_KEY is not set.",
+                hint="Set API_READ_KEY: the frontend reads content with it.",
+                id="django_stack.E002",
+            )
+        )
+    return errors
+
+
+@register(Tags.security)
+def check_debug(app_configs, **kwargs):
+    site_url = getattr(settings, "SITE_URL", "") or ""
+    if settings.DEBUG and site_url.startswith("https://"):
+        return [
+            Error(
+                "DEBUG is on while SITE_URL is https.",
+                hint="Set DJANGO_DEBUG=0 in production: debug pages show settings and source code.",
+                id="django_stack.E003",
+            )
+        ]
+    return []
+
+
+@register()
+def check_public_create(app_configs, **kwargs):
+    errors = []
+    for label in conf.get("PUBLIC_CREATE"):
+        try:
+            apps.get_model(label)
+        except (LookupError, ValueError):
+            errors.append(
+                Error(
+                    f"PUBLIC_CREATE names {label!r}, which is not an installed model.",
+                    hint="Use the model's label, such as 'content.formsubmission'.",
+                    id="django_stack.E004",
+                )
+            )
+    return errors
+
+
+@register()
+def check_secrets(app_configs, **kwargs):
+    warnings = []
+    if conf.get("REVALIDATE_URL") and not conf.get("REVALIDATE_SECRET"):
+        warnings.append(
+            Warning(
+                "REVALIDATE_URL is set without REVALIDATE_SECRET.",
+                hint="Set REVALIDATE_SECRET to the same value as in the frontend.",
+                id="django_stack.W001",
+            )
+        )
+    if not conf.get("PREVIEW_SECRET"):
+        warnings.append(
+            Warning(
+                "PREVIEW_SECRET is not set, so editors cannot preview drafts.",
+                hint="Set PREVIEW_SECRET to the same value as in the frontend.",
+                id="django_stack.W002",
+            )
+        )
+    return warnings
+
+
+@register(Tags.security, deploy=True)
+def check_deploy(app_configs, **kwargs):
+    warnings = []
+    if len(settings.SECRET_KEY or "") < 50:
+        warnings.append(
+            Warning(
+                "DJANGO_SECRET_KEY is shorter than 50 characters.",
+                hint="Generate a new one, for example with `npx @django-stack/cli secret`.",
+                id="django_stack.W003",
+            )
+        )
+    backend = settings.CACHES.get("default", {}).get("BACKEND", "")
+    if backend.endswith(("LocMemCache", "DummyCache")):
+        warnings.append(
+            Warning(
+                "The default cache is not shared between processes.",
+                hint="Set CACHE_URL to the Valkey or Redis service.",
+                id="django_stack.W004",
+            )
+        )
+    site_url = getattr(settings, "SITE_URL", "") or ""
+    if site_url.startswith("https://") and not getattr(settings, "SECURE_PROXY_SSL_HEADER", None):
+        warnings.append(
+            Warning(
+                "SITE_URL is https, but Django does not trust the proxy's X-Forwarded-Proto header.",
+                hint="Set NUM_PROXIES=1 behind Caddy, so secure cookies and CSRF checks see HTTPS.",
+                id="django_stack.W005",
+            )
+        )
+    return warnings

django_stack-0.1.0/src/django_stack/conf.py

@@ -0,0 +1,31 @@
+"""Access to the DJANGO_STACK settings with their defaults."""
+
+from django.conf import settings
+
+DEFAULTS = {
+    "PREVIEW_SECRET": None,
+    "PREVIEW_MAX_AGE": 3600,
+    "PREVIEW_HEADER": "X-Preview-Token",
+    "REVALIDATE_URL": None,
+    "REVALIDATE_SECRET": None,
+    "REVALIDATE_TIMEOUT": 5,
+    "PUBLIC_CREATE": [],
+    "CONTENT_APPS": ["content"],
+    "SEED_CONTENT": None,
+    "ADMIN_USERNAME": "admin",
+    "ADMIN_EMAIL": None,
+    "ADMIN_PASSWORD": None,
+    "BACKUP_DIR": None,
+    "BACKUP_KEEP": 14,
+    "BACKUP_TIME": "03:00",
+    "BACKUP_S3_BUCKET": None,
+    "BACKUP_S3_PREFIX": "backups/",
+    "BACKUP_S3": {},
+}
+
+
+def get(name: str):
+    configured = getattr(settings, "DJANGO_STACK", None) or {}
+    if name in configured:
+        return configured[name]
+    return DEFAULTS[name]

django_stack-0.1.0/src/django_stack/contrib/health/urls.py

@@ -0,0 +1,8 @@
+from django.urls import path
+
+from . import views
+
+urlpatterns = [
+    path("healthz", views.healthz, name="django-stack-healthz"),
+    path("readyz", views.readyz, name="django-stack-readyz"),
+]

django_stack-0.1.0/src/django_stack/contrib/health/views.py

@@ -0,0 +1,36 @@
+from django.core.cache import cache
+from django.db import connection
+from django.http import JsonResponse
+from django.views.decorators.cache import never_cache
+from django.views.decorators.http import require_GET
+
+
+@never_cache
+@require_GET
+def healthz(request):
+    """The process is up."""
+    return JsonResponse({"status": "ok"})
+
+
+@never_cache
+@require_GET
+def readyz(request):
+    """The database and the cache are reachable."""
+    checks = {}
+    try:
+        connection.ensure_connection()
+        with connection.cursor() as cursor:
+            cursor.execute("SELECT 1")
+        checks["database"] = "ok"
+    except Exception:  # noqa: BLE001
+        checks["database"] = "error"
+    try:
+        cache.set("django_stack:readyz", "1", 5)
+        checks["cache"] = "ok" if cache.get("django_stack:readyz") == "1" else "error"
+    except Exception:  # noqa: BLE001
+        checks["cache"] = "error"
+
+    ready = all(value == "ok" for value in checks.values())
+    return JsonResponse(
+        {"status": "ok" if ready else "error", "checks": checks}, status=200 if ready else 503
+    )

django_stack-0.1.0/src/django_stack/contrib/revalidate/receivers.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from ... import conf
+from .tasks import enqueue_revalidate
+
+
+def on_content_changed(sender, changes, **kwargs):
+    """Content Studio's content_changed signal: forward the changes to the frontend."""
+    if not conf.get("REVALIDATE_URL") or not conf.get("REVALIDATE_SECRET"):
+        return
+    payload = [
+        {
+            "action": change.action,
+            "model": change.model._meta.label_lower if change.model is not None else None,
+            "id": str(change.object_id) if change.object_id is not None else None,
+        }
+        for change in changes
+    ]
+    if payload:
+        enqueue_revalidate(payload)

django_stack-0.1.0/src/django_stack/contrib/revalidate/tasks.py

@@ -0,0 +1,71 @@
+"""Tell the frontend which content changed, so it can purge its cache."""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.error
+import urllib.request
+
+from ... import conf
+from ...signing import sign_webhook
+
+logger = logging.getLogger("django_stack.revalidate")
+
+try:  # Django 6.0+
+    from django.tasks import task
+except ImportError:  # pragma: no cover - Django 5.2 with or without django-tasks
+    try:
+        from django_tasks import task
+    except ImportError:
+        task = None
+
+
+def send_revalidate(changes: list[dict]) -> bool:
+    """POST the changes to REVALIDATE_URL, signed with REVALIDATE_SECRET."""
+    url = conf.get("REVALIDATE_URL")
+    secret = conf.get("REVALIDATE_SECRET")
+    if not url or not secret:
+        return False
+
+    body = json.dumps({"version": 1, "event": "content.changed", "changes": changes}).encode()
+    request = urllib.request.Request(  # noqa: S310 - the URL is the project's own setting
+        url,
+        data=body,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "User-Agent": "django-stack",
+            "X-Django-Stack-Signature": sign_webhook(secret, body),
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=conf.get("REVALIDATE_TIMEOUT")) as response:  # noqa: S310
+            ok = 200 <= response.status < 300
+    except (urllib.error.URLError, TimeoutError, OSError) as error:
+        logger.warning("Revalidation request to %s failed: %s", url, error)
+        return False
+    if not ok:
+        logger.warning("Revalidation request to %s answered %s", url, response.status)
+    return ok
+
+
+if task is not None:
+
+    @task()
+    def revalidate(changes: list[dict]) -> bool:
+        """The task the worker runs: one revalidation request."""
+        return send_revalidate(changes)
+
+else:  # pragma: no cover
+    revalidate = None
+
+
+def enqueue_revalidate(changes: list[dict]) -> None:
+    if revalidate is not None:
+        try:
+            revalidate.enqueue(changes)
+            return
+        except Exception as error:  # noqa: BLE001 - fall back to sending in the request
+            logger.warning("Could not enqueue the revalidation task: %s", error)
+    send_revalidate(changes)