trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/sync/migrations/0002_remove_syncbatch_syncbatch_project_client_batch_uniq_and_more.py

@@ -0,0 +1,41 @@
+# Generated by Django 5.2.14 on 2026-05-30 22:19
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("projects", "0054_sprintscopechange_goal_impact_and_more"),
+        ("sync", "0001_initial"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.RemoveConstraint(
+            model_name="syncbatch",
+            name="syncbatch_project_client_batch_uniq",
+        ),
+        migrations.AddField(
+            model_name="syncbatch",
+            name="actor_user",
+            field=models.ForeignKey(
+                blank=True,
+                null=True,
+                on_delete=django.db.models.deletion.CASCADE,
+                related_name="sync_batches",
+                to=settings.AUTH_USER_MODEL,
+            ),
+        ),
+        # safe-constraint: widens the (project, client_batch_id) uniqueness removed
+        # above to (project, actor_user, client_batch_id). A superset of an already
+        # unique key is unique, so no existing row can violate the wider constraint.
+        migrations.AddConstraint(
+            model_name="syncbatch",
+            constraint=models.UniqueConstraint(
+                fields=("project", "actor_user", "client_batch_id"),
+                name="syncbatch_project_actor_client_batch_uniq",
+            ),
+        ),
+    ]

trueppm_api/apps/sync/migrations/0003_boardevent.py

@@ -0,0 +1,46 @@
+# Generated by Django 5.2.15 on 2026-07-05 23:56
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("projects", "0109_projectexportjob"),
+        (
+            "sync",
+            "0001_squashed_0002_remove_syncbatch_syncbatch_project_client_batch_uniq_and_more",
+        ),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="BoardEvent",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+                    ),
+                ),
+                ("event_type", models.CharField(max_length=64)),
+                ("payload", models.JSONField(blank=True, default=dict)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                (
+                    "project",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="board_events",
+                        to="projects.project",
+                    ),
+                ),
+            ],
+            options={
+                "ordering": ["id"],
+                "indexes": [
+                    models.Index(fields=["project", "id"], name="boardevent_project_seq_idx"),
+                    models.Index(fields=["created_at"], name="boardevent_created_idx"),
+                ],
+            },
+        ),
+    ]

trueppm_api/apps/sync/migrations/0003_squashed_0005_release_0_4.py

@@ -0,0 +1,77 @@
+# Generated by Django 5.2.17 on 2026-10-05 20:38
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+import trueppm_api.apps.sync.backfill
+
+
+class Migration(migrations.Migration):
+    replaces = [
+        ("sync", "0003_boardevent"),
+        ("sync", "0004_seed_sync_seq"),
+        ("sync", "0005_program_sync_sequence"),
+    ]
+
+    dependencies = [
+        ("access", "0018_programmembership_sync_seq_and_more"),
+        ("integrations", "0011_tasklink_sync_seq_tasklink_tasklink_syncseq_idx"),
+        ("projects", "0109_projectexportjob"),
+        ("projects", "0128_acceptancecriterion_sync_seq_apitoken_sync_seq_and_more"),
+        (
+            "sync",
+            "0001_squashed_0002_remove_syncbatch_syncbatch_project_client_batch_uniq_and_more",
+        ),
+        ("timetracking", "0004_timeentry_sync_seq_and_more"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="BoardEvent",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+                    ),
+                ),
+                ("event_type", models.CharField(max_length=64)),
+                ("payload", models.JSONField(blank=True, default=dict)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                (
+                    "project",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="board_events",
+                        to="projects.project",
+                    ),
+                ),
+            ],
+            options={
+                "ordering": ["id"],
+                "indexes": [
+                    models.Index(fields=["project", "id"], name="boardevent_project_seq_idx"),
+                    models.Index(fields=["created_at"], name="boardevent_created_idx"),
+                ],
+            },
+        ),
+        migrations.RunPython(
+            code=trueppm_api.apps.sync.backfill.seed_sync_seq,
+            reverse_code=trueppm_api.apps.sync.backfill.unseed_sync_seq,
+        ),
+        migrations.CreateModel(
+            name="ProgramSyncSequence",
+            fields=[
+                ("id", models.BigAutoField(primary_key=True, serialize=False)),
+                ("value", models.BigIntegerField(default=0, editable=False)),
+            ],
+            options={
+                "verbose_name": "program sync sequence",
+                "verbose_name_plural": "program sync sequence",
+            },
+        ),
+        migrations.RunPython(
+            code=trueppm_api.apps.sync.backfill.seed_program_sync_seq,
+            reverse_code=trueppm_api.apps.sync.backfill.unseed_program_sync_seq,
+        ),
+    ]

trueppm_api/apps/sync/migrations/0004_seed_sync_seq.py

@@ -0,0 +1,24 @@
+"""Seed the per-project sync delta cursor for existing data (ADR-0686, #2491).
+
+Runs after every app that adds the ``sync_seq`` column, because the renumber
+touches all of them in one pass. The logic lives in ``apps/sync/backfill.py`` so
+tests can import it without referencing this file's name (CLAUDE.md rule 3).
+"""
+
+from django.db import migrations
+
+from trueppm_api.apps.sync.backfill import seed_sync_seq, unseed_sync_seq
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("sync", "0003_boardevent"),
+        ("projects", "0128_acceptancecriterion_sync_seq_apitoken_sync_seq_and_more"),
+        ("access", "0018_programmembership_sync_seq_and_more"),
+        ("integrations", "0011_tasklink_sync_seq_tasklink_tasklink_syncseq_idx"),
+        ("timetracking", "0004_timeentry_sync_seq_and_more"),
+    ]
+
+    operations = [
+        migrations.RunPython(seed_sync_seq, unseed_sync_seq, elidable=True),
+    ]

trueppm_api/apps/sync/migrations/0005_program_sync_sequence.py

@@ -0,0 +1,35 @@
+"""Installation-wide allocator for the program sync cursor (ADR-0747, #2498).
+
+Creates the singleton counter, then seeds it and both program tables' ``sync_seq``
+in one ordered pass. The backfill logic lives in ``apps/sync/backfill.py`` so tests
+can import it without referencing this file's name (CLAUDE.md migration rule 3).
+"""
+
+from django.db import migrations, models
+
+from trueppm_api.apps.sync.backfill import seed_program_sync_seq, unseed_program_sync_seq
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("sync", "0004_seed_sync_seq"),
+        # The backfill reads both tables' server_version and writes their sync_seq,
+        # so both columns must already exist.
+        ("projects", "0128_acceptancecriterion_sync_seq_apitoken_sync_seq_and_more"),
+        ("access", "0018_programmembership_sync_seq_and_more"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="ProgramSyncSequence",
+            fields=[
+                ("id", models.BigAutoField(primary_key=True, serialize=False)),
+                ("value", models.BigIntegerField(default=0, editable=False)),
+            ],
+            options={
+                "verbose_name": "program sync sequence",
+                "verbose_name_plural": "program sync sequence",
+            },
+        ),
+        migrations.RunPython(seed_program_sync_seq, unseed_program_sync_seq, elidable=True),
+    ]

trueppm_api/apps/sync/migrations/0006_boardevent_per_project_seq.py

@@ -0,0 +1,77 @@
+# Generated by Django 5.2.17 on 2026-10-14 15:35
+
+"""Per-project, commit-ordered WebSocket replay sequence (ADR-1285, #4386).
+
+Adds ``BoardEvent.seq`` and the per-project ``BoardEventSequence`` allocator. It
+seeds each project's counter at that project's highest existing global id plus
+``BOARD_EVENT_SEQ_UPGRADE_OFFSET`` (2**32), so every new per-project ``seq`` sits far
+above any global id, including ids old pods issue during the rolling update. Every
+pre-upgrade cursor therefore gets one ``resync_required``. See
+``seed_board_event_sequences``.
+
+Existing rows are not renumbered: they keep ``seq = NULL`` and stay live-only. The
+same holds for rows a pod still running the previous release INSERTs during a
+rolling update (it does not know the column). The window is disclosed in the
+upgrade notes.
+"""
+
+from typing import Any
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+def _seed(apps: Any, schema_editor: Any) -> None:
+    from trueppm_api.apps.sync.sequence import seed_board_event_sequences
+
+    seed_board_event_sequences(
+        apps.get_model("sync", "BoardEvent"),
+        apps.get_model("sync", "BoardEventSequence"),
+        apps.get_model("projects", "Project"),
+        schema_editor.connection,
+    )
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("projects", "0106_squashed_0158_release_0_4"),
+        ("sync", "0003_squashed_0005_release_0_4"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="BoardEventSequence",
+            fields=[
+                (
+                    "project",
+                    models.OneToOneField(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        primary_key=True,
+                        related_name="board_event_sequence",
+                        serialize=False,
+                        to="projects.project",
+                    ),
+                ),
+                ("value", models.BigIntegerField(default=0, editable=False)),
+            ],
+        ),
+        migrations.AddField(
+            model_name="boardevent",
+            name="seq",
+            field=models.BigIntegerField(blank=True, editable=False, null=True),
+        ),
+        # Reverse is a no-op: unapplying CreateModel drops the counter table.
+        migrations.RunPython(_seed, migrations.RunPython.noop),
+        migrations.RemoveIndex(
+            model_name="boardevent",
+            name="boardevent_project_seq_idx",
+        ),
+        # safe-constraint: seq was added by this migration and nothing writes it, so
+        # every existing row is NULL, and NULLs never collide in a unique index.
+        migrations.AddConstraint(
+            model_name="boardevent",
+            constraint=models.UniqueConstraint(
+                fields=("project", "seq"), name="boardevent_project_seq_uniq"
+            ),
+        ),
+    ]

trueppm_api/apps/sync/models.py

@@ -0,0 +1,272 @@
+"""Models for the sync app.
+
+The only model here is :class:`SyncBatch`, the idempotency + atomicity
+envelope for a mobile offline **upload** batch (ADR-0082, issue #667). It is
+server infrastructure — the mobile client never pulls it as a domain row — so
+it is a plain ``models.Model`` (not ``VersionedModel``), mirroring the
+transactional-outbox style of ``projects.SprintCloseRequest``.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import timedelta
+
+from django.conf import settings
+from django.db import models
+from django.utils import timezone
+
+
+class SyncBatchStatus(models.TextChoices):
+    """Lifecycle of an upload batch envelope (ADR-0082 §D)."""
+
+    PENDING = "pending", "Pending"
+    COMPLETED = "completed", "Completed"
+
+
+class SyncBatch(models.Model):
+    """Records a mobile upload batch so a retry is a no-op, not a double-apply.
+
+    A mobile client generates a stable ``client_batch_id`` (UUID) per delta and
+    re-uploads the *same* id until it sees an ACK. The first request that wins
+    the unique-constraint race applies the delta and snapshots its HTTP response
+    here, inside the same transaction as the row writes (all-or-nothing). A
+    later request carrying the same id — the lost-ACK retry — returns the stored
+    response without re-applying anything.
+
+    Concurrency is serialized by the ``client_batch_id`` unique constraint:
+    Postgres blocks a concurrent duplicate INSERT until the first transaction
+    commits or aborts, after which the duplicate either reads the committed row
+    (replay) or proceeds (the first attempt rolled back). See
+    ``sync.views.ProjectSyncView.post`` for the full algorithm.
+
+    Rows are dedup-relevant only within the freshness window
+    (``TRUEPPM_SYNC_BATCH_RETENTION_HOURS``, default 24h); the
+    ``sync.purge_sync_batches`` Beat task reaps older rows so the table stays
+    bounded (ADR-0081 purge convention).
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    # Client-generated dedup key. Uniqueness (and every lookup) is scoped to
+    # (project, actor_user): a retry always targets the same project endpoint as
+    # the same authenticated user, so that composite unique index is a sufficient
+    # concurrency backstop, while scoping prevents one project — or one user —
+    # replaying another's stored response (the dedup lookup must never cross the
+    # project or actor boundary — see views.post, #887/#894).
+    client_batch_id = models.UUIDField()
+    project = models.ForeignKey(
+        "projects.Project",
+        on_delete=models.CASCADE,
+        related_name="sync_batches",
+    )
+    # Actor scoping (#894): the stored response body carries task ids,
+    # server_versions, and the sync watermark for the rows *this user* pushed.
+    # Keying dedup on (project, client_batch_id) alone let any project member
+    # replay another member's batch by reusing its client_batch_id and read back
+    # that user's response — an information leak across actors. Scoping
+    # uniqueness and the replay lookup to the actor closes it: a reused id from a
+    # different user is a distinct batch, never a replay of someone else's.
+    # Nullable so the migration is backfill-safe for rows written before this
+    # field existed (those legacy rows simply never match a new actor-scoped
+    # lookup and age out of the freshness window).
+    actor_user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="sync_batches",
+        null=True,
+        blank=True,
+    )
+    status = models.CharField(
+        max_length=12,
+        choices=SyncBatchStatus.choices,
+        default=SyncBatchStatus.PENDING,
+        db_index=True,
+    )
+    # Verbatim success response so a retry replays byte-identically.
+    response_body = models.JSONField(default=dict, blank=True)
+    response_status = models.PositiveSmallIntegerField(default=200)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    objects: models.Manager[SyncBatch] = models.Manager()
+
+    class Meta:
+        ordering = ["created_at"]
+        constraints = [
+            # Actor-scoped uniqueness (#894): two different users may legitimately
+            # reuse the same client_batch_id; only a same-(project, actor) duplicate
+            # is a replay. Scoping the constraint to the actor prevents one user's
+            # batch from blocking — or being replayed by — another's.
+            models.UniqueConstraint(
+                fields=["project", "actor_user", "client_batch_id"],
+                name="syncbatch_project_actor_client_batch_uniq",
+            ),
+        ]
+        indexes = [
+            # Reaper scans by age; the index keeps the nightly purge cheap.
+            models.Index(fields=["created_at"], name="syncbatch_created_idx"),
+        ]
+
+    def __str__(self) -> str:
+        return f"SyncBatch({self.client_batch_id}, {self.status})"
+
+    def is_fresh(self, *, ttl_hours: int = 24) -> bool:
+        """Return True if this batch is still within the dedup window.
+
+        A duplicate of a *fresh* completed batch replays the stored response; a
+        duplicate of an *expired* batch re-runs the apply (the stale row is
+        deleted first). ``ttl_hours`` is supplied by the caller from
+        ``settings.TRUEPPM_SYNC_BATCH_RETENTION_HOURS``.
+        """
+        return self.created_at > timezone.now() - timedelta(hours=ttl_hours)
+
+
+class BoardEvent(models.Model):
+    """Bounded per-project replay buffer for WebSocket events (ADR-0236, #321).
+
+    Real-time broadcasts are best-effort: a client that disconnects loses every
+    event sent during the gap. Each replayable broadcast persists one ``BoardEvent``
+    row here so a reconnecting client can request ``?since=<seq>`` and replay only
+    the events it missed — instead of a broad refetch storm — and recover the
+    incremental ``task_dates_updated`` CPM splices a refetch-on-focus would drop.
+
+    Like :class:`SyncBatch`, this is server infrastructure, never pulled as a synced
+    domain row, so it is a plain ``models.Model`` (no ``server_version``).
+
+    **``seq`` is a per-project, dense, commit-ordered sequence (ADR-1285, #4386).**
+    It is drawn from the project's :class:`BoardEventSequence` row in the *same*
+    transaction as this row's INSERT, so the counter's row lock is held until the
+    event commits: within one project, commit order equals allocation order and the
+    committed values are 1, 2, 3, … with no holes. That is what lets a client treat
+    ``seq > last + 1`` as "a frame is missing or still in flight" and ``seq <= last``
+    as a genuine duplicate, and lets the consumer prove a replay complete by
+    counting rows. The previous design used the global ``BigAutoField`` PK, which
+    could not support either: other projects' traffic interleaved it (so the next
+    frame on a project was almost never ``last + 1``), two workers' sends could
+    arrive in the reverse of allocation order and the later-allocated one would
+    make the client drop the other as a duplicate, and the delta between frames
+    leaked instance-wide event volume to every project member.
+
+    ``seq`` is NULL on two kinds of row: those written before the #4386 migration,
+    which deliberately did not renumber them (``seed_board_event_sequences``), and
+    those a pod still running the old code INSERTs during a rolling update. Both are
+    live-only. The replay query filters ``seq`` non-null and the allocator never
+    counted them, so they neither create a false gap nor get replayed. Rows are reaped past
+    ``TRUEPPM_BOARD_EVENT_RETENTION_HOURS`` (default 24h) by the
+    ``sync.purge_board_events`` Beat task (the ADR-0081 purge convention).
+    """
+
+    # id: implicit BigAutoField PK (DEFAULT_AUTO_FIELD) — row identity only; the
+    # wire sequence is ``seq`` (ADR-1285).
+    project = models.ForeignKey(
+        "projects.Project",
+        on_delete=models.CASCADE,
+        related_name="board_events",
+    )
+    seq = models.BigIntegerField(null=True, blank=True, editable=False)
+    event_type = models.CharField(max_length=64)
+    payload = models.JSONField(default=dict, blank=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    objects: models.Manager[BoardEvent] = models.Manager()
+
+    class Meta:
+        ordering = ["id"]
+        constraints = [
+            # One event per (project, seq). Its index also serves the replay query
+            # ``WHERE project_id=? AND seq > ? AND seq <= ? ORDER BY seq``. NULLs
+            # (rolling-update rows, see the class docstring) are distinct in a
+            # Postgres unique index, so they never collide.
+            models.UniqueConstraint(fields=["project", "seq"], name="boardevent_project_seq_uniq"),
+        ]
+        indexes = [
+            # The reaper scans by age; keeps the nightly purge cheap.
+            models.Index(fields=["created_at"], name="boardevent_created_idx"),
+        ]
+
+    def __str__(self) -> str:
+        return f"BoardEvent(seq={self.seq}, {self.event_type}, project={self.project_id})"
+
+
+class BoardEventSequence(models.Model):
+    """Per-project allocator for :attr:`BoardEvent.seq` (ADR-1285, #4386).
+
+    One row per project that has ever persisted a replayable event, created lazily
+    on the first one. ``value`` is the last allocated ``seq`` and therefore also the
+    replay head the consumer reports as ``latest_seq``.
+
+    **Why a row lock and not a PostgreSQL SEQUENCE** — the same reason as
+    :class:`ProgramSyncSequence` and the ``sync_seq`` allocator (ADR-0686):
+    ``nextval()`` is non-transactional, so it would hand out values with no
+    relationship to commit order and leave holes on rollback. Allocating by
+    ``UPDATE … RETURNING`` in the event's own transaction holds this row's lock
+    until that transaction commits, which is what makes the committed values dense
+    and commit-ordered.
+
+    **Why its own row and not a column on ``Project``.** ``Project.last_sync_version``
+    is held locked for the *whole* apply of a sync upload, and ``Project`` rows are
+    also taken ``FOR UPDATE`` by several domain transactions. Broadcasts run in
+    ``on_commit`` callbacks; putting their allocator on the project row would make
+    every broadcast on a project wait behind any of those, and couple a transport
+    counter to domain locking. A dedicated row is locked only for the few
+    milliseconds of one event INSERT, and nothing else ever locks it, so it cannot
+    take part in a lock cycle with the project row.
+    """
+
+    project = models.OneToOneField(
+        "projects.Project",
+        on_delete=models.CASCADE,
+        primary_key=True,
+        related_name="board_event_sequence",
+    )
+    value = models.BigIntegerField(default=0, editable=False)
+
+    objects: models.Manager[BoardEventSequence] = models.Manager()
+
+    def __str__(self) -> str:
+        return f"BoardEventSequence(project={self.project_id}, value={self.value})"
+
+
+class ProgramSyncSequence(models.Model):
+    """Installation-wide monotonic allocator for the program sync cursor (ADR-0747).
+
+    Exactly one row, pk=1. Every synced write to ``Program`` or
+    ``ProgramMembership`` draws the next value from it and stamps the row's
+    ``sync_seq``, so those values are totally ordered installation-wide, ``MAX`` is
+    a meaningful checkpoint, and ``sync_seq__gt=since`` is a correct delta filter.
+
+    **Why a table row and not a PostgreSQL SEQUENCE.** ``nextval()`` would avoid
+    this row's write lock, and would be wrong. Sequences are non-transactional, so
+    they grant no relationship between allocation order and commit order: one
+    transaction could allocate 100, a later one allocate 101 and commit first, and a
+    pull between the two commits would report 101 and permanently skip 100 — the
+    exact defect this replaces, reintroduced as a race. Allocating by ``UPDATE``
+    holds this row's write lock until commit, so commit order equals allocation
+    order. The lock is the correctness mechanism, not overhead.
+
+    **Why installation-wide and not per-program.** ``Program`` rows have no single
+    owning entity to sequence from the way a ``Task`` has its project (ADR-0686).
+    The accessible set is per-user — the union of the caller's programs — so a
+    scalar cursor over per-program sequences would reintroduce the same
+    hot-row-outruns-cold-row failure one level up. Ordering every program-scoped
+    write against one counter is what makes a scalar cursor sound.
+
+    The cost is that program writes serialize installation-wide. That is acceptable
+    because program writes are rare and administrative — create, rename, add or
+    remove a member — never a hot path or a bulk import. See ADR-0747 for the
+    escape hatch if that ever changes.
+    """
+
+    #: The single row's primary key. Named so call sites read as intent.
+    SINGLETON_PK = 1
+
+    id = models.BigAutoField(primary_key=True)
+    value = models.BigIntegerField(default=0, editable=False)
+
+    objects: models.Manager[ProgramSyncSequence] = models.Manager()
+
+    class Meta:
+        verbose_name = "program sync sequence"
+        verbose_name_plural = "program sync sequence"
+
+    def __str__(self) -> str:
+        return f"ProgramSyncSequence(value={self.value})"