Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python

API v1: updated_at, deletion records and a changes feed; ETags on recording reads (mailr spec G2, G11)

Murtaza Nasird577f37d1ee1
diff --git a/config/env.asr.example b/config/env.asr.example
index 38c0e9af..fda16b5b 100644
--- a/config/env.asr.example
+++ b/config/env.asr.example
@@ -390,6 +390,10 @@ MAX_CONCURRENT_UPLOADS=3
# Default: false.
# MODELS_ARE_LOCAL=false
+# Days to keep records of deleted recordings for API clients that sync with
+# the changes feed (/api/v1/recordings/changes). Default: 90.
+# RECORDING_TOMBSTONE_DAYS=90
+
# --- Server-Side Recording Sessions (optional) ---
# Opt-in: in-app recordings stream audio chunks to the server as they record,
# instead of buffering the entire recording in browser RAM. This enables
diff --git a/config/env.transcription.example b/config/env.transcription.example
index 76b8436f..ba899b22 100644
--- a/config/env.transcription.example
+++ b/config/env.transcription.example
@@ -548,6 +548,10 @@ MAX_CONCURRENT_UPLOADS=3
# Default: false.
# MODELS_ARE_LOCAL=false
+# Days to keep records of deleted recordings for API clients that sync with
+# the changes feed (/api/v1/recordings/changes). Default: 90.
+# RECORDING_TOMBSTONE_DAYS=90
+
# =============================================================================
# SERVER-SIDE RECORDING SESSIONS (optional)
# =============================================================================
diff --git a/config/env.whisper.example b/config/env.whisper.example
index 0f93f8be..55db544e 100644
--- a/config/env.whisper.example
+++ b/config/env.whisper.example
@@ -386,6 +386,10 @@ MAX_CONCURRENT_UPLOADS=3
# Default: false.
# MODELS_ARE_LOCAL=false
+# Days to keep records of deleted recordings for API clients that sync with
+# the changes feed (/api/v1/recordings/changes). Default: 90.
+# RECORDING_TOMBSTONE_DAYS=90
+
# --- Server-Side Recording Sessions (optional) ---
# Opt-in: in-app recordings stream audio chunks to the server as they record,
# instead of buffering the entire recording in browser RAM. This enables
diff --git a/config/env.whisperx.example b/config/env.whisperx.example
index d4099f59..42d144ba 100644
--- a/config/env.whisperx.example
+++ b/config/env.whisperx.example
@@ -304,6 +304,10 @@ MAX_CONCURRENT_UPLOADS=3
# Default: false.
# MODELS_ARE_LOCAL=false
+# Days to keep records of deleted recordings for API clients that sync with
+# the changes feed (/api/v1/recordings/changes). Default: 90.
+# RECORDING_TOMBSTONE_DAYS=90
+
# --- Background Processing Queues ---
# Separate queues for transcription (slow) and summary (fast) jobs
# This prevents slow ASR jobs from blocking quick summary generation
diff --git a/docs/admin-guide/retention.md b/docs/admin-guide/retention.md
index eac199de..5ac2549c 100644
--- a/docs/admin-guide/retention.md
+++ b/docs/admin-guide/retention.md
@@ -131,6 +131,17 @@ The filter appears when audio-only retention is active or when the user is allow
- **Player**: "The audio file was removed. The transcript, summary and notes remain available."
- **Filter**: **Audio removed** quick filter in the sidebar filters
+## Deletion Records for API Clients
+
+When a recording is deleted, by a user or by auto-deletion, Speakr keeps a small record of the deletion: the recording id, the user, the time and the reason. No title or content is kept. API clients read these records from the [changes feed](../user-guide/api-reference.md#changes-feed) to remove their own copy of the recording.
+
+The records are removed after `RECORDING_TOMBSTONE_DAYS` days (default 90), checked every hour. A client whose last sync is older than that starts a full sync again.
+
+```bash
+# Days to keep deletion records for API clients (default 90)
+RECORDING_TOMBSTONE_DAYS=90
+```
+
## Admin Controls
### Running Auto-Deletion
diff --git a/docs/user-guide/api-reference.md b/docs/user-guide/api-reference.md
index 5ee927ba..a2c441e6 100644
--- a/docs/user-guide/api-reference.md
+++ b/docs/user-guide/api-reference.md
@@ -100,7 +100,7 @@ Lists the features this instance supports. Read features here, not from the vers
{
"speakr_version": "v0.10.11-alpha",
"api_version": "1.1",
- "features": {"token_scopes": true},
+ "features": {"token_scopes": true, "changes_feed": true, "etags": true},
"models_local": false
}
```
@@ -382,10 +382,12 @@ GET /api/v1/recordings
| `page` | integer | 1 | Page number |
| `per_page` | integer | 25 | Items per page (max: 100) |
| `status` | string | `all` | Filter: `all`, `pending`, `processing`, `completed`, `failed` |
-| `sort_by` | string | `created_at` | Sort field: `created_at`, `meeting_date`, `title`, `file_size` |
+| `sort_by` | string | `created_at` | Sort field: `created_at`, `meeting_date`, `title`, `file_size`, `status`, `updated_at` |
| `sort_order` | string | `desc` | Sort order: `asc`, `desc` |
| `date_from` | string | - | Filter from date (ISO format) |
-| `date_to` | string | - | Filter to date (ISO format) |
+| `date_to` | string | - | Filter to date (ISO format); a date alone includes that whole day |
+| `date_field` | string | `created_at` | What `date_from` and `date_to` filter: `created_at` or `meeting_date` |
+| `updated_since` | string | - | Only recordings changed after this time (ISO 8601). Deletions are not listed; use the [changes feed](#changes-feed) for those. |
| `tag_id` | integer | - | Filter by tag ID |
| `q` | string | - | Search query (title, participants) |
| `inbox` | boolean | - | Filter by inbox status |
@@ -424,7 +426,8 @@ GET /api/v1/recordings
"keep_audio_only": false,
"tags": [
{"id": 1, "name": "Work", "color": "#3B82F6"}
- ]
+ ],
+ "updated_at": "2024-01-15T10:05:00.000000Z"
}
],
"pagination": {
@@ -438,6 +441,76 @@ GET /api/v1/recordings
}
```
+`updated_at` is the time of the last change a client can see: title, participants, notes, summary, transcript, status, dates, folder, flags, tags, events or sharing. It is present on every recording in API v1 and starts at `created_at`.
+
+### Changes Feed
+
+```http
+GET /api/v1/recordings/changes
+```
+
+**Scope:** `read`
+
+Every create, edit and delete of your recordings since a cursor, each once and in its latest state. This is the way to keep a copy of your recordings in sync without listing the whole collection.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `cursor` | string | - | `next_cursor` from the previous answer. Without it, the answer lists every recording (a full pass) and no older deletions. |
+| `limit` | integer | 100 | 1 to 500 |
+| `scope` | string | `own` | `own` |
+
+**Response:**
+
+```json
+{
+ "changes": [
+ {"type": "upsert", "recording": {"id": 412, "title": "Weekly sync", "updated_at": "2026-10-02T14:03:22.123456Z"}},
+ {"type": "delete", "id": 398, "deleted_at": "2026-10-02T14:05:00.000000Z", "reason": "deleted"}
+ ],
+ "next_cursor": "eyJ1IjoiMjAyNi0xMC0wMlQxNDowNTowMC4wMDAwMDBaIiwiayI6MSwiaSI6Mzk4fQ",
+ "has_more": false
+}
+```
+
+- `recording` in an upsert has the same fields as one item of [List Recordings](#list-recordings).
+- `reason` on a delete is `deleted` (by a user, the API or a merge), `retention` (auto-deletion) or `access_revoked` (a recording shared with you is no longer shared).
+- Changes from the last two seconds wait for the next call, so a change saved late is never skipped.
+- The cursor is opaque. Store `next_cursor` after every answer, including an answer with no changes.
+- `400` with `"code": "invalid_parameter"`: the cursor cannot be read.
+- `410` with `"code": "cursor_expired"`: the cursor is older than the deletions Speakr still keeps (`RECORDING_TOMBSTONE_DAYS`, default 90). Start again without a cursor.
+
+A sync loop:
+
+```text
+cursor = stored cursor, or none
+repeat:
+ answer = GET /api/v1/recordings/changes?cursor=<cursor>
+ if status is 410: drop the local copy's sync state, cursor = none, continue
+ apply each change: upsert replaces the recording, delete removes it
+ cursor = answer.next_cursor; store it
+ if not answer.has_more: wait (or wait for a webhook), then repeat
+```
+
+### Conditional Requests
+
+These requests send a weak `ETag` header:
+
+| Request | Answer depends on |
+|---------|-------------------|
+| `GET /api/v1/recordings/{id}` | the recording, its tags and folder, and the parameters |
+| `GET /api/v1/recordings/{id}/transcript` | the transcript, the format and, for `format=text`, your transcript template |
+| `GET /api/v1/recordings/{id}/summary` | the summary |
+| `GET /api/v1/recordings/{id}/notes` | the notes you can see |
+| `GET /api/v1/recordings/{id}/events` | the extracted events |
+| `GET /api/v1/recordings/{id}/speakers` | the speakers and the voice suggestions |
+
+Send the value back in `If-None-Match`. When nothing in the answer changed, the answer is `304 Not Modified` with no body. Treat the value as opaque. The access check comes first, so a caller without access gets `403` or `404`, never `304`. The answers carry `Cache-Control: private, no-cache`.
+
+```bash
+curl -i -H "Authorization: Bearer $TOKEN" -H 'If-None-Match: W/"t412-1790950000000000-3f2a9c0d1b7e4a55"' \
+ https://speakr.example.com/api/v1/recordings/412/transcript
+```
+
### Get Recording Details
```http
diff --git a/src/api/api_v1.py b/src/api/api_v1.py
index 47f287ce..82b9ec78 100644
--- a/src/api/api_v1.py
+++ b/src/api/api_v1.py
@@ -153,7 +153,8 @@ OPENAPI_SPEC = {
"folder": {"type": "object", "nullable": True, "properties": {"id": {"type": "integer"}, "name": {"type": "string"}}},
"events": {"type": "array", "description": "Calendar events extracted from the recording (detail endpoint only)", "items": {"type": "object"}},
"tags": {"type": "array", "items": {"$ref": "#/components/schemas/Tag"}},
- "keep_audio_only": {"type": "boolean", "description": "True if the upload was processed in audio-only mode (video stream discarded). Set at upload time; immutable via PATCH."}
+ "keep_audio_only": {"type": "boolean", "description": "True if the upload was processed in audio-only mode (video stream discarded). Set at upload time; immutable via PATCH."},
+ "updated_at": {"type": "string", "format": "date-time", "description": "Last change a client can see; starts at created_at"}
}
},
"Tag": {
@@ -252,6 +253,33 @@ OPENAPI_SPEC = {
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Capabilities"}}}}}
}
},
+ "/recordings/changes": {
+ "get": {
+ "tags": ["Recordings"],
+ "summary": "Changes to your recordings since a cursor",
+ "description": "Each create, edit and delete once, in latest state. Store next_cursor after every answer. 410 cursor_expired: start again without a cursor.",
+ "parameters": [
+ {"name": "cursor", "in": "query", "schema": {"type": "string"}},
+ {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 100, "minimum": 1, "maximum": 500}},
+ {"name": "scope", "in": "query", "schema": {"type": "string", "enum": ["own"], "default": "own"}}
+ ],
+ "responses": {
+ "200": {"description": "A page of changes", "content": {"application/json": {"schema": {
+ "type": "object",
+ "properties": {
+ "changes": {"type": "array", "items": {"type": "object", "properties": {
+ "type": {"type": "string", "enum": ["upsert", "delete"]},
+ "recording": {"$ref": "#/components/schemas/Recording"},
+ "id": {"type": "integer"},
+ "deleted_at": {"type": "string", "format": "date-time"},
+ "reason": {"type": "string", "enum": ["deleted", "retention", "access_revoked"]}}}},
+ "next_cursor": {"type": "string"},
+ "has_more": {"type": "boolean"}}}}}},
+ "400": {"description": "invalid_parameter"},
+ "410": {"description": "cursor_expired"}
+ }
+ }
+ },
"/stats": {
"get": {
"tags": ["Stats"],
@@ -277,7 +305,9 @@ OPENAPI_SPEC = {
{"name": "page", "in": "query", "schema": {"type": "integer", "default": 1}},
{"name": "per_page", "in": "query", "schema": {"type": "integer", "default": 25, "maximum": 100}},
{"name": "status", "in": "query", "schema": {"type": "string", "enum": ["all", "pending", "processing", "completed", "failed"]}},
- {"name": "sort_by", "in": "query", "schema": {"type": "string", "enum": ["created_at", "meeting_date", "title", "file_size"]}},
+ {"name": "sort_by", "in": "query", "schema": {"type": "string", "enum": ["created_at", "meeting_date", "title", "file_size", "status", "updated_at"]}},
+ {"name": "updated_since", "in": "query", "schema": {"type": "string", "format": "date-time"}, "description": "Only recordings changed after this time"},
+ {"name": "date_field", "in": "query", "schema": {"type": "string", "enum": ["created_at", "meeting_date"], "default": "created_at"}, "description": "What date_from and date_to filter"},
{"name": "sort_order", "in": "query", "schema": {"type": "string", "enum": ["asc", "desc"]}},
{"name": "tag_id", "in": "query", "schema": {"type": "integer"}},
{"name": "archived", "in": "query", "schema": {"type": "boolean"}, "description": "true: only archived recordings; false: only unarchived. Omitted: both, as before."},
@@ -858,6 +888,8 @@ def get_current_token():
# ships; a missing key means false.
CAPABILITY_FEATURES = {
'token_scopes': True,
+ 'changes_feed': True,
+ 'etags': True,
}
@@ -942,6 +974,44 @@ def get_current_user():
# Recordings List with Enhanced Filtering
# =============================================================================
+def _updated_at_z(recording):
+ from src.services.recording_changes import effective_updated_at, iso_z
+ return iso_z(effective_updated_at(recording))
+
+
+def _recording_list_item(r):
+ """One recording as GET /recordings lists it; the changes feed uses the same shape."""
+ from src.services.recording_changes import effective_updated_at, iso_z
+ return {
+ 'id': r.id,
+ 'title': r.title,
+ 'status': r.status,
+ 'created_at': r.created_at.isoformat() if r.created_at else None,
+ 'completed_at': r.completed_at.isoformat() if r.completed_at else None,
+ 'meeting_date': r.meeting_date.isoformat() if r.meeting_date else None,
+ 'file_size': r.file_size,
+ 'original_filename': r.original_filename,
+ 'participants': r.participants,
+ 'is_inbox': r.is_inbox,
+ 'is_highlighted': r.is_highlighted,
+ 'is_archived': bool(r.is_archived),
+ 'audio_available': r.audio_deleted_at is None,
+ 'audio_duration': r.get_audio_duration(),
+ 'has_transcription': bool(r.transcription),
+ 'has_summary': bool(r.summary),
+ 'processing_time_seconds': r.processing_time_seconds,
+ 'transcription_duration_seconds': r.transcription_duration_seconds,
+ 'summarization_duration_seconds': r.summarization_duration_seconds,
+ 'folder_id': r.folder_id,
+ 'folder': {'id': r.folder.id, 'name': r.folder.name} if r.folder else None,
+ 'deletion_exempt': r.deletion_exempt,
+ 'error_message': r.error_message if r.status == 'FAILED' else None,
+ 'tags': [{'id': t.id, 'name': t.name, 'color': t.color} for t in r.tags],
+ 'keep_audio_only': r.keep_audio_only,
+ 'updated_at': iso_z(effective_updated_at(r)),
+ }
+
+
@api_v1_bp.route('/recordings', methods=['GET'])
@require_scope('read')
@login_required
@@ -962,6 +1032,9 @@ def list_recordings():
inbox: Filter by inbox status (true/false)
starred: Filter by starred status (true/false)
archived: Filter by archive status (true/false); omitted returns both
+ updated_since: Only recordings changed after this time (ISO 8601)
+ date_field: What date_from and date_to filter: created_at (default)
+ or meeting_date
"""
# Parse query parameters
page = request.args.get('page', 1, type=int)
@@ -977,6 +1050,11 @@ def list_recordings():
inbox_filter = request.args.get('inbox')
starred_filter = request.args.get('starred')
archived_filter = request.args.get('archived')
+ updated_since = request.args.get('updated_since')
+ date_field = request.args.get('date_field', 'created_at')
+ if date_field not in ('created_at', 'meeting_date'):
+ return jsonify({'error': "date_field must be created_at or meeting_date",
+ 'code': 'invalid_parameter'}), 400
# Base query - user's recordings.
# Eager-load folder and tag-association+Tag so the list builder
@@ -1010,10 +1088,11 @@ def list_recordings():
# Aware values are converted to the naive-UTC storage convention; a bare
# date_to includes that whole day (#412 B8).
from src.utils.dates import to_utc_naive
+ date_column = Recording.meeting_date if date_field == 'meeting_date' else Recording.created_at
if date_from:
try:
from_date = to_utc_naive(datetime.fromisoformat(date_from.replace('Z', '+00:00')))
- query = query.filter(Recording.created_at >= from_date)
+ query = query.filter(date_column >= from_date)
except ValueError:
pass
@@ -1021,12 +1100,21 @@ def list_recordings():
try:
to_date = to_utc_naive(datetime.fromisoformat(date_to.replace('Z', '+00:00')))
if len(date_to.strip()) == 10:
- query = query.filter(Recording.created_at < to_date + timedelta(days=1))
+ query = query.filter(date_column < to_date + timedelta(days=1))
else:
- query = query.filter(Recording.created_at <= to_date)
+ query = query.filter(date_column <= to_date)
except ValueError:
pass
+ changed_column = db.func.coalesce(Recording.updated_at, Recording.created_at)
+ if updated_since:
+ try:
+ since = to_utc_naive(datetime.fromisoformat(updated_since.replace('Z', '+00:00')))
+ except ValueError:
+ return jsonify({'error': 'updated_since must be an ISO 8601 date-time',
+ 'code': 'invalid_parameter'}), 400
+ query = query.filter(changed_column > since)
+
# Tag filter
if tag_id:
query = query.join(RecordingTag).filter(RecordingTag.tag_id == tag_id)
@@ -1075,7 +1163,8 @@ def list_recordings():
'meeting_date': Recording.meeting_date,
'title': Recording.title,
'file_size': Recording.file_size,
- 'status': Recording.status
+ 'status': Recording.status,
+ 'updated_at': changed_column,
}
sort_column = sort_columns.get(sort_by, Recording.created_at)
@@ -1088,35 +1177,7 @@ def list_recordings():
pagination = query.paginate(page=page, per_page=per_page, error_out=False)
# Build response
- recordings = []
- for r in pagination.items:
- recordings.append({
- 'id': r.id,
- 'title': r.title,
- 'status': r.status,
- 'created_at': r.created_at.isoformat() if r.created_at else None,
- 'completed_at': r.completed_at.isoformat() if r.completed_at else None,
- 'meeting_date': r.meeting_date.isoformat() if r.meeting_date else None,
- 'file_size': r.file_size,
- 'original_filename': r.original_filename,
- 'participants': r.participants,
- 'is_inbox': r.is_inbox,
- 'is_highlighted': r.is_highlighted,
- 'is_archived': bool(r.is_archived),
- 'audio_available': r.audio_deleted_at is None,
- 'audio_duration': r.get_audio_duration(),
- 'has_transcription': bool(r.transcription),
- 'has_summary': bool(r.summary),
- 'processing_time_seconds': r.processing_time_seconds,
- 'transcription_duration_seconds': r.transcription_duration_seconds,
- 'summarization_duration_seconds': r.summarization_duration_seconds,
- 'folder_id': r.folder_id,
- 'folder': {'id': r.folder.id, 'name': r.folder.name} if r.folder else None,
- 'deletion_exempt': r.deletion_exempt,
- 'error_message': r.error_message if r.status == 'FAILED' else None,
- 'tags': [{'id': t.id, 'name': t.name, 'color': t.color} for t in r.tags],
- 'keep_audio_only': r.keep_audio_only,
- })
+ recordings = [_recording_list_item(r) for r in pagination.items]
return jsonify({
'recordings': recordings,
@@ -1135,9 +1196,80 @@ def list_recordings():
# Recording Detail
# =============================================================================
+def _conditional(prefix):
+ """Weak ETag and If-None-Match for a GET on one recording (mailr spec G11).
+
+ The tag holds the recording id, its updated_at and a hash of the body, so
+ it also changes when something outside the recording changes the answer
+ (a tag or folder name, the viewer's transcript template, voice
+ suggestions). It runs after the view, so the view's access check comes
+ first and a caller without access gets 403 or 404, never 304.
+ """
+ def decorator(view):
+ @wraps(view)
+ def wrapper(recording_id, *args, **kwargs):
+ import hashlib
+ from flask import make_response
+ from src.services.recording_changes import etag_matches, updated_at_us
+ response = make_response(view(recording_id, *args, **kwargs))
+ if response.status_code != 200 or response.direct_passthrough:
+ return response
+ recording = db.session.get(Recording, recording_id)
+ digest = hashlib.sha1(response.get_data()).hexdigest()[:16]
+ etag = f'W/"{prefix}{recording_id}-{updated_at_us(recording) if recording else 0}-{digest}"'
+ if etag_matches(request, etag):
+ response = make_response('', 304)
+ response.headers['ETag'] = etag
+ response.headers['Cache-Control'] = 'private, no-cache'
+ return response
+ return wrapper
+ return decorator
+
+
+@api_v1_bp.route('/recordings/changes', methods=['GET'])
+@require_scope('read')
+@login_required
+def list_recording_changes():
+ """Changes to the user's recordings since a cursor (mailr spec G2).
+
+ Query params:
+ cursor: from a previous answer; absent starts a full pass (every live
+ recording, no tombstones)
+ limit: 1 to 500 (default 100)
+ scope: own (default; shared and all arrive with G4)
+ """
+ from src.services.recording_changes import (CursorError, cursor_expired, decode_cursor,
+ iso_z, read_changes)
+ cursor = request.args.get('cursor') or None
+ limit = request.args.get('limit', 100, type=int)
+ if limit is None or not 1 <= limit <= 500:
+ return jsonify({'error': 'limit must be between 1 and 500', 'code': 'invalid_parameter'}), 400
+ scope = request.args.get('scope', 'own')
+ if scope != 'own':
+ return jsonify({'error': "scope must be 'own'", 'code': 'invalid_parameter'}), 400
+ if cursor:
+ try:
+ changed_at, _, _, full_since = decode_cursor(cursor)
+ except CursorError:
+ return jsonify({'error': 'The cursor could not be read', 'code': 'invalid_parameter'}), 400
+ if cursor_expired(current_user.id, changed_at, full_since):
+ return jsonify({'error': 'The cursor is too old; start again without a cursor',
+ 'code': 'cursor_expired'}), 410
+ items, next_cursor, has_more = read_changes(current_user.id, cursor=cursor, limit=limit)
+ changes = []
+ for kind, obj in items:
+ if kind == 'upsert':
+ changes.append({'type': 'upsert', 'recording': _recording_list_item(obj)})
+ else:
+ changes.append({'type': 'delete', 'id': obj.recording_id,
+ 'deleted_at': iso_z(obj.deleted_at), 'reason': obj.reason})
+ return jsonify({'changes': changes, 'next_cursor': next_cursor, 'has_more': has_more})
+
+
@api_v1_bp.route('/recordings/<int:recording_id>', methods=['GET'])
@require_scope('read')
@login_required
+@_conditional('r')
def get_recording(recording_id):
"""
Get full recording details.
@@ -1154,6 +1286,7 @@ def get_recording(recording_id):
if not has_recording_access(recording, current_user):
return jsonify({'error': 'Permission denied'}), 403
+ from src.services.recording_changes import effective_updated_at, iso_z
include = request.args.get('include', 'transcription,summary,notes')
include_fields = [f.strip() for f in include.split(',')]
format_type = request.args.get('format', 'full')
@@ -1185,6 +1318,7 @@ def get_recording(recording_id):
'tags': [{'id': t.id, 'name': t.name, 'color': t.color} for t in recording.tags],
'duplicate_info': recording.get_duplicate_info(),
'keep_audio_only': recording.keep_audio_only,
+ 'updated_at': iso_z(effective_updated_at(recording)),
}
# Include large text fields based on params
@@ -1209,6 +1343,7 @@ def get_recording(recording_id):
@api_v1_bp.route('/recordings/<int:recording_id>/transcript', methods=['GET'])
@require_scope('read')
@login_required
+@_conditional('t')
def get_transcript(recording_id):
"""
Get transcript in various formats.
@@ -1299,6 +1434,7 @@ def get_transcript(recording_id):
@api_v1_bp.route('/recordings/<int:recording_id>/summary', methods=['GET'])
@require_scope('read')
@login_required
+@_conditional('s')
def get_summary(recording_id):
"""Get summary markdown."""
recording = db.session.get(Recording, recording_id)
@@ -1317,6 +1453,7 @@ def get_summary(recording_id):
@api_v1_bp.route('/recordings/<int:recording_id>/notes', methods=['GET'])
@require_scope('read')
@login_required
+@_conditional('n')
def get_notes(recording_id):
"""Get notes markdown."""
recording = db.session.get(Recording, recording_id)
@@ -1477,7 +1614,8 @@ def update_recording(recording_id):
'is_inbox': recording.is_inbox,
'is_highlighted': recording.is_highlighted,
'is_archived': get_user_archived(recording, current_user),
- 'folder_id': recording.folder_id
+ 'folder_id': recording.folder_id,
+ 'updated_at': _updated_at_z(recording),
}
})
@@ -2287,6 +2425,7 @@ def delete_speaker(speaker_id):
@api_v1_bp.route('/recordings/<int:recording_id>/speakers', methods=['GET'])
@require_scope('read')
@login_required
+@_conditional('k')
def get_recording_speakers(recording_id):
"""Get speakers in a recording with suggestions."""
from src.services.speaker_embedding_matcher import find_matching_speakers
@@ -2653,6 +2792,7 @@ Notes: {recording.notes or 'None'}
@api_v1_bp.route('/recordings/<int:recording_id>/events', methods=['GET'])
@require_scope('read')
@login_required
+@_conditional('e')
def get_recording_events(recording_id):
"""Get calendar events extracted from a recording."""
recording = db.session.get(Recording, recording_id)
diff --git a/src/app.py b/src/app.py
index 55813672..287d09d1 100644
--- a/src/app.py
+++ b/src/app.py
@@ -495,6 +495,10 @@ else:
from src.database import db
db.init_app(app)
+# updated_at and tombstones for API clients (mailr spec G2)
+from src.services.recording_changes import register_change_tracking
+register_change_tracking()
+
# Import all models from extracted modules
from src.models import (
User, Speaker, Recording, TranscriptChunk, Share, InternalShare,
diff --git a/src/config/startup.py b/src/config/startup.py
index 24694a8c..bb2ba8c7 100644
--- a/src/config/startup.py
+++ b/src/config/startup.py
@@ -262,6 +262,12 @@ def initialize_recording_session_cleanup(app):
removed = cleanup_stale_parts()
if removed:
app.logger.info(f"Upload-join cleanup removed {removed} stale part(s)")
+ # Changes-feed tombstones past RECORDING_TOMBSTONE_DAYS.
+ with app.app_context():
+ from src.services.recording_changes import prune_tombstones
+ pruned = prune_tombstones()
+ if pruned:
+ app.logger.info(f"Pruned {pruned} recording tombstone(s)")
except Exception as e:
app.logger.error(f"Recording-session cleanup error: {e}", exc_info=True)
# Don't tight-loop on failure
diff --git a/src/init_db.py b/src/init_db.py
index 5aca4e9b..3a2d13de 100644
--- a/src/init_db.py
+++ b/src/init_db.py
@@ -238,6 +238,26 @@ def _run_migrations(app, engine):
app.logger.info("Added audio_duration_seconds column to recording table")
if add_column_if_not_exists(engine, 'recording', 'completed_at', 'DATETIME'):
app.logger.info("Added completed_at column to recording table")
+ # Change tracking for API clients (mailr spec G2). Filled from
+ # completed_at or created_at once; the feed reads NULL as created_at,
+ # so a failed backfill is harmless and the next start retries it.
+ if add_column_if_not_exists(engine, 'recording', 'updated_at', 'DATETIME'):
+ app.logger.info("Added updated_at column to recording table")
+ create_index_if_not_exists(engine, 'ix_recording_updated_at', 'recording', 'updated_at')
+ create_index_if_not_exists(engine, 'ix_recording_user_updated', 'recording', 'user_id, updated_at')
+
+ def _backfill_recording_updated_at(engine):
+ from datetime import datetime as _dt
+ from src.services.recording_changes import FEED_SINCE_KEY, iso_z
+ with engine.begin() as conn:
+ conn.execute(text(
+ 'UPDATE recording SET updated_at = COALESCE(completed_at, created_at) '
+ 'WHERE updated_at IS NULL'))
+ SystemSetting.set_setting(FEED_SINCE_KEY, iso_z(_dt.utcnow()),
+ 'Start of change tracking (changes feed)')
+
+ run_once(engine, '0002_backfill_recording_updated_at', _backfill_recording_updated_at,
+ logger=app.logger)
if add_column_if_not_exists(engine, 'recording', 'processing_time_seconds', 'INTEGER'):
app.logger.info("Added processing_time_seconds column to recording table")
if add_column_if_not_exists(engine, 'recording', 'transcription_duration_seconds', 'INTEGER'):
diff --git a/src/models/__init__.py b/src/models/__init__.py
index 6270c543..f50713d4 100644
--- a/src/models/__init__.py
+++ b/src/models/__init__.py
@@ -18,7 +18,7 @@ from .user import User, Speaker
from .voice import VoiceEmbeddingSpace, SpeakerVoiceSample
from .api_token import APIToken
from .speaker_snippet import SpeakerSnippet
-from .recording import Recording, TranscriptChunk
+from .recording import Recording, RecordingTombstone, TranscriptChunk
from .sharing import Share, InternalShare, SharedRecordingState
from .organization import Group, GroupMembership, Tag, RecordingTag, Folder
from .events import Event
@@ -61,7 +61,7 @@ __all__ = [
'SpeakerSnippet',
# Recording models
'Recording',
- 'TranscriptChunk',
+ 'TranscriptChunk', 'RecordingTombstone',
# Sharing models
'Share',
'InternalShare',
diff --git a/src/models/recording.py b/src/models/recording.py
index c34c6632..4cf212f6 100644
--- a/src/models/recording.py
+++ b/src/models/recording.py
@@ -48,6 +48,9 @@ class Recording(db.Model):
mime_type = db.Column(db.String(100), nullable=True)
audio_duration_seconds = db.Column(db.Float, nullable=True) # Cached audio duration to avoid materializing remote storage during serialization
completed_at = db.Column(db.DateTime, nullable=True)
+ # Last change a client can see (mailr spec G2); set by the before_flush
+ # listener in src/services/recording_changes.py, never by hand.
+ updated_at = db.Column(db.DateTime, nullable=True, index=True)
processing_time_seconds = db.Column(db.Integer, nullable=True)
transcription_duration_seconds = db.Column(db.Integer, nullable=True) # Time taken for transcription
# Cached audio duration in seconds, populated at transcription
@@ -333,6 +336,11 @@ class Recording(db.Model):
return tags, folder, self.folder_id
return tags, None, None
+ def updated_at_z(self):
+ """updated_at (created_at before the first change) as ISO 8601 with Z."""
+ value = self.updated_at or self.created_at
+ return value.strftime('%Y-%m-%dT%H:%M:%S.%fZ') if value else None
+
def to_list_dict(self, viewer_user=None, duplicate_info_map=None, share_map=None):
"""
Lightweight dict for list views - excludes expensive HTML conversions.
@@ -368,6 +376,7 @@ class Recording(db.Model):
'status': self.status,
'created_at': self.created_at.isoformat() if self.created_at else None,
'completed_at': self.completed_at.isoformat() if self.completed_at else None,
+ 'updated_at': self.updated_at_z(),
'meeting_date': self.meeting_date.isoformat() if self.meeting_date else None,
'file_size': self.file_size,
'original_filename': self.original_filename,
@@ -451,6 +460,7 @@ class Recording(db.Model):
'status': self.status,
'created_at': self.created_at.isoformat() if self.created_at else None,
'completed_at': self.completed_at.isoformat() if self.completed_at else None,
+ 'updated_at': self.updated_at_z(),
'processing_time_seconds': self.processing_time_seconds,
'transcription_duration_seconds': self.transcription_duration_seconds,
'summarization_duration_seconds': self.summarization_duration_seconds,
@@ -525,3 +535,21 @@ class TranscriptChunk(db.Model):
'speaker_name': self.speaker_name,
'created_at': self.created_at.isoformat() if self.created_at else None
}
+
+
+class RecordingTombstone(db.Model):
+ """A recording a user can no longer see, for the changes feed (mailr spec G2).
+
+ No foreign key to the recording: the row outlives it. Written by the
+ before_flush listener in src/services/recording_changes.py; pruned after
+ RECORDING_TOMBSTONE_DAYS.
+ """
+ __tablename__ = 'recording_tombstone'
+
+ id = db.Column(db.Integer, primary_key=True)
+ recording_id = db.Column(db.Integer, nullable=False)
+ user_id = db.Column(db.Integer, db.ForeignKey('user.id', ondelete='CASCADE'), nullable=False)
+ deleted_at = db.Column(db.DateTime, nullable=False, index=True)
+ reason = db.Column(db.String(20), nullable=False, default='deleted') # deleted | retention | access_revoked
+
+ __table_args__ = (db.Index('ix_recording_tombstone_user_deleted', 'user_id', 'deleted_at'),)
diff --git a/src/services/recording_changes.py b/src/services/recording_changes.py
new file mode 100644
index 00000000..65b08ebb
--- /dev/null
+++ b/src/services/recording_changes.py
@@ -0,0 +1,313 @@
+"""Change tracking for recordings: updated_at, tombstones, the changes feed
+and ETags (mailr spec G2 and G11).
+
+updated_at is set in one before_flush listener, so no write path can forget
+it: a change to a field a client sees, or to a row that belongs to the
+recording (tags, events, shares, per-user state), moves it. Fields that only
+processing uses (embeddings, timings, resolved settings, export file name) do
+not.
+
+Deleting a recording writes a tombstone for the owner and for every user it
+was shared with; removing an internal share writes an access_revoked
+tombstone for that user. The changes feed reads updated_at and the
+tombstones in one order, (changed_at, kind, id), and pages with an opaque
+cursor.
+
+Bulk Query.update() bypasses ORM events; tests/test_recording_changes.py fails
+if one is added for the recording table.
+"""
+
+import base64
+import json
+import os
+from datetime import datetime, timedelta
+
+from sqlalchemy import event, or_, and_, func
+from sqlalchemy.orm import Session
+
+from src.database import db
+
+# Fields whose change a client should see.
+TRACKED_FIELDS = (
+ 'title', 'participants', 'notes', 'summary', 'transcription', 'status', 'meeting_date',
+ 'folder_id', 'is_inbox', 'is_highlighted', 'is_archived', 'audio_deleted_at', 'completed_at',
+ 'error_message', 'speaker_label_map', 'deletion_exempt', 'prompt_variables',
+)
+
+SETTLE_SECONDS = 2
+TOMBSTONE_DAYS = int(os.environ.get('RECORDING_TOMBSTONE_DAYS', '90') or 90)
+FEED_SINCE_KEY = 'changes_feed_since'
+PRUNED_BEFORE_KEY = 'recording_tombstones_pruned_before'
+
+_UPSERT, _DELETE = 0, 1
+_MAX_ID = 2 ** 62
+
+_registered = False
+
+
+def iso_z(value):
+ """ISO 8601 with microseconds and a Z suffix, for new fields."""
+ if value is None:
+ return None
+ return value.strftime('%Y-%m-%dT%H:%M:%S.%fZ')
+
+
+def effective_updated_at(recording):
+ return recording.updated_at or recording.created_at
+
+
+# ---------------------------------------------------------------- listener
+
+def _child_recording_ids(session):
+ """Recording ids touched through a row that belongs to a recording."""
+ from src.models import Event, InternalShare, RecordingTag, SharedRecordingState
+ child_types = (RecordingTag, Event, InternalShare, SharedRecordingState)
+ try:
+ from src.models import RecordingExternalRef # G8
+ child_types = child_types + (RecordingExternalRef,)
+ except ImportError:
+ pass
+ ids = set()
+ for obj in list(session.new) + list(session.dirty) + list(session.deleted):
+ if isinstance(obj, child_types):
+ rid = getattr(obj, 'recording_id', None)
+ if rid is not None:
+ ids.add(rid)
+ return ids
+
+
+def _changed_fields(session, recording):
+ from sqlalchemy import inspect as sa_inspect
+ state = sa_inspect(recording)
+ keys = state.attrs.keys()
+ return [name for name in TRACKED_FIELDS if name in keys and state.attrs[name].history.has_changes()]
+
+
+def _before_flush(session, flush_context, instances):
+ from src.models import InternalShare, Recording
+ now = datetime.utcnow()
+ changes = session.info.setdefault('recording_changes', {})
+
+ for obj in session.new:
+ if isinstance(obj, Recording):
+ if obj.created_at is None:
+ obj.created_at = now
+ if obj.updated_at is None:
+ obj.updated_at = obj.created_at
+
+ for obj in session.dirty:
+ if isinstance(obj, Recording) and session.is_modified(obj, include_collections=False):
+ fields = _changed_fields(session, obj)
+ if fields:
+ obj.updated_at = now
+ changes.setdefault(obj.id, set()).update(fields)
+
+ deleted_recordings = {obj.id for obj in session.deleted if isinstance(obj, Recording)}
+ with session.no_autoflush:
+ for rid in _child_recording_ids(session) - deleted_recordings:
+ rec = session.get(Recording, rid)
+ if rec is not None and rec not in session.new:
+ rec.updated_at = now
+ changes.setdefault(rid, set()).add('related')
+
+ for obj in session.deleted:
+ if isinstance(obj, Recording):
+ _tombstones_for_deleted_recording(session, obj, now)
+ elif isinstance(obj, InternalShare) and obj.recording_id not in deleted_recordings:
+ _add_tombstone(session, obj.recording_id, obj.shared_with_user_id, now, 'access_revoked')
+
+
+def _tombstones_for_deleted_recording(session, recording, now):
+ from src.models import InternalShare
+ reason = session.info.get('tombstone_reason', 'deleted')
+ users = set()
+ if recording.user_id is not None:
+ users.add(recording.user_id)
+ for (uid,) in session.query(InternalShare.shared_with_user_id).filter(
+ InternalShare.recording_id == recording.id).all():
+ users.add(uid)
+ for uid in users:
+ _add_tombstone(session, recording.id, uid, now, reason)
+
+
+def _add_tombstone(session, recording_id, user_id, now, reason):
+ from src.models import RecordingTombstone
+ session.add(RecordingTombstone(recording_id=recording_id, user_id=user_id, deleted_at=now, reason=reason))
+
+
+def register_change_tracking():
+ """Register the listener once, for every session."""
+ global _registered
+ if _registered:
+ return
+ event.listen(Session, 'before_flush', _before_flush)
+ _registered = True
+
+
+# ---------------------------------------------------------------- pruning
+
+def prune_tombstones(now=None):
+ """Remove tombstones older than RECORDING_TOMBSTONE_DAYS. Returns the count."""
+ from src.models import RecordingTombstone, SystemSetting
+ now = now or datetime.utcnow()
+ horizon = now - timedelta(days=TOMBSTONE_DAYS)
+ removed = RecordingTombstone.query.filter(RecordingTombstone.deleted_at < horizon).delete(
+ synchronize_session=False)
+ db.session.commit()
+ if removed:
+ SystemSetting.set_setting(PRUNED_BEFORE_KEY, iso_z(horizon),
+ 'Tombstones before this time are pruned (changes feed 410)')
+ return removed
+
+
+# ---------------------------------------------------------------- feed
+
+class CursorError(ValueError):
+ pass
+
+
+def encode_cursor(changed_at, kind, rid, full_since=None):
+ data = {'u': iso_z(changed_at), 'k': kind, 'i': rid}
+ if full_since is not None:
+ data['s'] = iso_z(full_since)
+ raw = json.dumps(data, separators=(',', ':')).encode()
+ return base64.urlsafe_b64encode(raw).decode().rstrip('=')
+
+
+def _parse_z(value):
+ return datetime.strptime(value, '%Y-%m-%dT%H:%M:%S.%fZ')
+
+
+def decode_cursor(cursor):
+ try:
+ raw = base64.urlsafe_b64decode(cursor + '=' * (-len(cursor) % 4))
+ data = json.loads(raw)
+ changed_at = _parse_z(data['u'])
+ kind, rid = int(data['k']), int(data['i'])
+ full_since = _parse_z(data['s']) if data.get('s') else None
+ except Exception as e:
+ raise CursorError('cursor could not be decoded') from e
+ if kind not in (_UPSERT, _DELETE):
+ raise CursorError('cursor could not be decoded')
+ return changed_at, kind, rid, full_since
+
+
+def _after(column, id_column, kind, cursor_key):
+ """SQL for (column, kind, id) > cursor_key, for one constant kind."""
+ at, ck, ci = cursor_key
+ same_time = column == at
+ if kind > ck:
+ tie = same_time
+ elif kind == ck:
+ tie = and_(same_time, id_column > ci)
+ else:
+ tie = False
+ return or_(column > at, tie) if tie is not False else column > at
+
+
+def cursor_expired(user_id, changed_at, full_since):
+ """True when deletions the cursor still needs may have been pruned."""
+ from src.models import SystemSetting
+ needed_from = full_since or changed_at
+ pruned = SystemSetting.get_setting(PRUNED_BEFORE_KEY)
+ if pruned:
+ try:
+ if needed_from < _parse_z(pruned):
+ return True
+ except ValueError:
+ pass
+ since = SystemSetting.get_setting(FEED_SINCE_KEY)
+ if since and full_since is None:
+ try:
+ # A first answer can put the cursor up to the settle window before
+ # the upgrade time; no deletion can be missing from that gap.
+ if changed_at < _parse_z(since) - timedelta(seconds=SETTLE_SECONDS + 1):
+ return True
+ except ValueError:
+ pass
+ return False
+
+
+def read_changes(user_id, cursor=None, limit=100, now=None):
+ """One page of the feed. Returns (items, next_cursor, has_more); each item
+ is ('upsert', Recording) or ('delete', RecordingTombstone).
+
+ Raises CursorError for an undecodable cursor. The caller checks
+ cursor_expired first.
+ """
+ from src.models import Recording, RecordingTombstone
+ now = now or datetime.utcnow()
+ settle = now - timedelta(seconds=SETTLE_SECONDS)
+
+ if cursor:
+ at, kind, rid, full_since = decode_cursor(cursor)
+ key = (at, kind, rid)
+ else:
+ key, full_since = None, now # a full pass: tombstones only from its start
+
+ changed = func.coalesce(Recording.updated_at, Recording.created_at)
+ rq = Recording.query.filter(Recording.user_id == user_id, changed <= settle)
+ if key:
+ rq = rq.filter(_after(changed, Recording.id, _UPSERT, key))
+ recs = rq.order_by(changed.asc(), Recording.id.asc()).limit(limit + 1).all()
+
+ tq = RecordingTombstone.query.filter(RecordingTombstone.user_id == user_id,
+ RecordingTombstone.deleted_at <= settle)
+ if full_since is not None:
+ tq = tq.filter(RecordingTombstone.deleted_at >= full_since)
+ if key:
+ tq = tq.filter(_after(RecordingTombstone.deleted_at, RecordingTombstone.id, _DELETE, key))
+ stones = tq.order_by(RecordingTombstone.deleted_at.asc(), RecordingTombstone.id.asc()).limit(limit + 1).all()
+
+ merged = [((effective_updated_at(r), _UPSERT, r.id), 'upsert', r) for r in recs]
+ merged += [((t.deleted_at, _DELETE, t.id), 'delete', t) for t in stones]
+ merged.sort(key=lambda item: item[0])
+ page, has_more = merged[:limit], len(merged) > limit
+
+ if has_more:
+ last = page[-1][0]
+ next_cursor = encode_cursor(*last, full_since=full_since)
+ else:
+ # Everything up to the settle point has been returned.
+ next_cursor = encode_cursor(settle, _DELETE, _MAX_ID)
+ return [(kind, obj) for _, kind, obj in page], next_cursor, has_more
+
+
+# ---------------------------------------------------------------- ETags
+
+def updated_at_us(recording):
+ value = effective_updated_at(recording)
+ if value is None:
+ return 0
+ return int((value - datetime(1970, 1, 1)).total_seconds() * 1_000_000)
+
+
+def etag_matches(request, etag):
+ header = request.headers.get('If-None-Match')
+ if not header:
+ return False
+ if header.strip() == '*':
+ return True
+ bare = etag[2:] if etag.startswith('W/') else etag
+ for candidate in header.split(','):
+ candidate = candidate.strip()
+ if candidate.startswith('W/'):
+ candidate = candidate[2:]
+ if candidate == bare:
+ return True
+ return False
+
+
+def conditional(request, etag, build):
+ """304 when If-None-Match matches etag, else build() with the ETag set.
+ Call only after the access check."""
+ from flask import make_response
+ if etag_matches(request, etag):
+ response = make_response('', 304)
+ else:
+ response = make_response(build())
+ if response.status_code != 200:
+ return response
+ response.headers['ETag'] = etag
+ response.headers['Cache-Control'] = 'private, no-cache'
+ return response
diff --git a/src/services/recording_deletion.py b/src/services/recording_deletion.py
index dfc1afcb..1e03cae6 100644
--- a/src/services/recording_deletion.py
+++ b/src/services/recording_deletion.py
@@ -12,7 +12,7 @@ from flask import current_app
from src.database import db
-def delete_recording_completely(recording, storage=None, strict_media=False):
+def delete_recording_completely(recording, storage=None, strict_media=False, reason='deleted'):
"""Delete the media, the rows that reference the recording, and the recording.
Emits the recording.deleted webhook and marks the export as deleted.
@@ -23,6 +23,8 @@ def delete_recording_completely(recording, storage=None, strict_media=False):
strict_media: when the media cannot be deleted, raise and keep the
recording (retention wants that, so its next run retries). A user's
delete leaves a stray file instead of an undeletable recording.
+ reason: the tombstone reason for the changes feed, 'deleted' or
+ 'retention'.
"""
from src.models.processing_job import ProcessingJob
from src.models.speaker_snippet import SpeakerSnippet
@@ -54,8 +56,12 @@ def delete_recording_completely(recording, storage=None, strict_media=False):
if snippets or jobs:
current_app.logger.info(f"Deleted {snippets} speaker snippets and {jobs} processing jobs for recording {recording_id}")
- db.session.delete(recording) # cascades to chunks, shares, tags
- db.session.commit()
+ db.session.info['tombstone_reason'] = reason
+ try:
+ db.session.delete(recording) # cascades to chunks, shares, tags
+ db.session.commit()
+ finally:
+ db.session.info.pop('tombstone_reason', None)
current_app.logger.info(f"Deleted recording {recording_id}")
try:
diff --git a/src/services/retention.py b/src/services/retention.py
index 8bd28c12..1e00de46 100644
--- a/src/services/retention.py
+++ b/src/services/retention.py
@@ -167,7 +167,8 @@ def process_auto_deletion():
from src.services.recording_deletion import delete_recording_completely
deleted_id = recording.id
- delete_recording_completely(recording, storage=get_storage_service(), strict_media=True)
+ delete_recording_completely(recording, storage=get_storage_service(), strict_media=True,
+ reason='retention')
stats['deleted_full'] += 1
current_app.logger.info(f"Auto-deleted full recording ID: {deleted_id}")
diff --git a/tests/test_api_v1_etags.py b/tests/test_api_v1_etags.py
new file mode 100644
index 00000000..9f59dae4
--- /dev/null
+++ b/tests/test_api_v1_etags.py
@@ -0,0 +1,102 @@
+"""Conditional GETs on one recording (mailr spec G11).
+
+The six read routes send a weak ETag and answer If-None-Match with 304 and no
+body. The tag changes when the recording changes and when anything else in
+the answer changes (here: the user's transcript template). A caller without
+access gets 403 or 404, never 304.
+
+SHARED-DB: users, tokens, templates and the recording are removed afterwards.
+"""
+
+import json
+import os
+import secrets
+import sys
+
+import pytest
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from src.app import app, db
+from src.models import APIToken, Recording, TranscriptTemplate, User
+from src.utils.token_auth import hash_token
+
+SEGMENTS = [{"speaker": "Jane", "sentence": "Launch moves to Q3.", "start_time": 0.0, "end_time": 2.0}]
+ROUTES = ["", "/transcript", "/transcript?format=text", "/summary", "/notes", "/events", "/speakers"]
+
+
+def world():
+ with app.app_context():
+ s = secrets.token_hex(4)
+ me = User(username=f"etag_{s}", email=f"etag_{s}@local.test", password="x")
+ other = User(username=f"etago_{s}", email=f"etago_{s}@local.test", password="x")
+ db.session.add_all([me, other])
+ db.session.commit()
+ rec = Recording(user_id=me.id, title="Sync", status="COMPLETED", original_filename="s.wav",
+ transcription=json.dumps(SEGMENTS), summary="## Summary", notes="n")
+ db.session.add(rec)
+ tokens = {}
+ for who in (me, other):
+ plain = f"tok-{secrets.token_urlsafe(16)}"
+ db.session.add(APIToken(user_id=who.id, token_hash=hash_token(plain), name="etag"))
+ tokens[who.id] = plain
+ db.session.commit()
+ ids = dict(me=me.id, other=other.id, rec=rec.id, tokens=tokens)
+ yield ids
+ with app.app_context():
+ db.session.rollback()
+ users = [ids["me"], ids["other"]]
+ TranscriptTemplate.query.filter(TranscriptTemplate.user_id.in_(users)).delete(synchronize_session=False)
+ Recording.query.filter_by(id=ids["rec"]).delete()
+ APIToken.query.filter(APIToken.user_id.in_(users)).delete(synchronize_session=False)
+ User.query.filter(User.id.in_(users)).delete(synchronize_session=False)
+ db.session.commit()
+
+
+def _h(world, who="me", etag=None):
+ headers = {"Authorization": f"Bearer {world['tokens'][world[who]]}"}
+ if etag:
+ headers["If-None-Match"] = etag
+ return headers
+
+
[email protected]("route", ROUTES)
+def test_unchanged_answers_304_and_a_change_answers_200(world, route):
+ url = f"/api/v1/recordings/{world['rec']}{route}"
+ with app.test_client() as c:
+ first = c.get(url, headers=_h(world))
+ etag = first.headers.get("ETag")
+ assert first.status_code == 200 and etag and etag.startswith('W/"')
+ assert first.headers["Cache-Control"] == "private, no-cache"
+ again = c.get(url, headers=_h(world, etag=etag))
+ assert again.status_code == 304 and again.get_data() == b"" and again.headers["ETag"] == etag
+ assert c.patch(f"/api/v1/recordings/{world['rec']}", json={"summary": "## New", "notes": "m",
+ "participants": "Jane"},
+ headers=_h(world)).status_code == 200
+ after = c.get(url, headers=_h(world, etag=etag))
+ if route in ("/events",):
+ assert after.status_code in (200, 304) # unaffected content may keep its body
+ else:
+ assert after.status_code == 200 and after.headers["ETag"] != etag
+
+
+def test_the_text_transcript_follows_the_users_template(world):
+ url = f"/api/v1/recordings/{world['rec']}/transcript?format=text"
+ with app.test_client() as c:
+ etag = c.get(url, headers=_h(world)).headers["ETag"]
+ with app.app_context():
+ db.session.add(TranscriptTemplate(user_id=world["me"], name="Mine", template="{{speaker}} said {{text}}",
+ is_default=True))
+ db.session.commit()
+ changed = c.get(url, headers=_h(world, etag=etag))
+ assert changed.status_code == 200 and changed.headers["ETag"] != etag
+
+
[email protected]("route", ROUTES)
+def test_no_access_never_gets_304(world, route):
+ url = f"/api/v1/recordings/{world['rec']}{route}"
+ with app.test_client() as c:
+ etag = c.get(url, headers=_h(world)).headers["ETag"]
+ resp = c.get(url, headers=_h(world, who="other", etag=etag))
+ assert resp.status_code in (403, 404) and "ETag" not in resp.headers
diff --git a/tests/test_api_v1_scope_coverage.py b/tests/test_api_v1_scope_coverage.py
index e073de20..9679665c 100644
--- a/tests/test_api_v1_scope_coverage.py
+++ b/tests/test_api_v1_scope_coverage.py
@@ -13,7 +13,7 @@ sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from src.app import app
EXPECTED = {
- "read": {"get_openapi_spec", "get_docs", "get_stats", "get_current_user", "list_recordings", "get_recording",
+ "read": {"get_openapi_spec", "get_docs", "get_stats", "get_current_user", "list_recordings", "list_recording_changes", "get_recording",
"get_transcript", "get_summary", "get_notes", "get_recording_status", "list_tags", "list_folders",
"get_folder", "get_transcription_info", "list_speakers", "get_recording_speakers",
"get_recording_events", "download_events_ics", "download_audio"},
diff --git a/tests/test_recording_changes.py b/tests/test_recording_changes.py
new file mode 100644
index 00000000..a158655d
--- /dev/null
+++ b/tests/test_recording_changes.py
@@ -0,0 +1,373 @@
+"""updated_at, tombstones and the changes feed (mailr spec G2).
+
+Every write path a client can see moves Recording.updated_at, through one
+before_flush listener; processing-only fields do not. Deleting a recording or
+an internal share writes tombstones. GET /api/v1/recordings/changes returns
+each create, edit and delete once, in latest state, with a cursor.
+
+SHARED-DB: users, tokens, tags, recordings and tombstones are removed afterwards.
+"""
+
+import json
+import os
+import re
+import secrets
+import sys
+from datetime import datetime, timedelta
+from unittest.mock import patch
+
+import pytest
+from flask import g, has_app_context
+from flask.testing import FlaskClient
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from src.app import app, db
+from src.models import (APIToken, Event, InternalShare, Recording, RecordingTag, RecordingTombstone,
+ SystemSetting, Tag, User)
+from src.services import recording_changes as rc
+from src.utils.token_auth import hash_token
+
+app.config["WTF_CSRF_ENABLED"] = False
+PAST = datetime(2020, 1, 1, 12, 0, 0)
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+SEGMENTS = [{"speaker": "SPEAKER_00", "sentence": "Launch moves to Q3.", "start_time": 0.0, "end_time": 2.0}]
+
+
+class _Client(FlaskClient):
+ def open(self, *args, **kwargs):
+ if has_app_context():
+ g.pop('_login_user', None)
+ return super().open(*args, **kwargs)
+
+
+def world():
+ with app.app_context():
+ s = secrets.token_hex(4)
+ me = User(username=f"chg_{s}", email=f"chg_{s}@local.test", password="x")
+ other = User(username=f"chgo_{s}", email=f"chgo_{s}@local.test", password="x")
+ db.session.add_all([me, other])
+ db.session.commit()
+ rec = Recording(user_id=me.id, title="Sync", status="COMPLETED", original_filename="s.wav",
+ transcription=json.dumps(SEGMENTS))
+ tag = Tag(name=f"t-{s}", user_id=me.id)
+ db.session.add_all([rec, tag])
+ db.session.commit()
+ plain = f"tok-{secrets.token_urlsafe(16)}"
+ db.session.add(APIToken(user_id=me.id, token_hash=hash_token(plain), name="chg"))
+ db.session.commit()
+ ids = dict(me=me.id, other=other.id, rec=rec.id, tag=tag.id, token=plain)
+ yield ids
+ with app.app_context():
+ db.session.rollback()
+ users = [ids["me"], ids["other"]]
+ rec_ids = [r.id for r in Recording.query.filter(Recording.user_id.in_(users))]
+ RecordingTag.query.filter(RecordingTag.recording_id.in_(rec_ids)).delete(synchronize_session=False)
+ Event.query.filter(Event.recording_id.in_(rec_ids)).delete(synchronize_session=False)
+ InternalShare.query.filter(InternalShare.recording_id.in_(rec_ids)).delete(synchronize_session=False)
+ Recording.query.filter(Recording.id.in_(rec_ids)).delete(synchronize_session=False)
+ RecordingTombstone.query.filter(RecordingTombstone.user_id.in_(users)).delete(synchronize_session=False)
+ Tag.query.filter(Tag.user_id.in_(users)).delete(synchronize_session=False)
+ APIToken.query.filter(APIToken.user_id.in_(users)).delete(synchronize_session=False)
+ User.query.filter(User.id.in_(users)).delete(synchronize_session=False)
+ db.session.commit()
+
+
+def _backdate(rid, when=PAST):
+ with app.app_context():
+ r = db.session.get(Recording, rid)
+ r.updated_at = when
+ db.session.commit()
+
+
+def _updated(rid):
+ with app.app_context():
+ return db.session.get(Recording, rid).updated_at
+
+
+def _session(uid):
+ c = _Client(app, app.response_class, use_cookies=True)
+ with c.session_transaction() as sess:
+ sess["_user_id"] = str(uid)
+ return c
+
+
+def _api(world):
+ return {"Authorization": f"Bearer {world['token']}"}
+
+
+# ------------------------------------------------------------ updated_at
+
+def _no_side_effects():
+ return (patch("src.api.recordings.reindex_recording_chunks_async"),
+ patch("src.file_exporter.export_recording"),
+ patch("src.services.speaker.update_voice_profiles", return_value=(0, 0)))
+
+
+WRITE_PATHS = {
+ "v1 PATCH": lambda w, c: c.patch(f"/api/v1/recordings/{w['rec']}", json={"title": "New"}, headers=_api(w)),
+ "v1 PUT notes": lambda w, c: c.put(f"/api/v1/recordings/{w['rec']}/notes", json={"notes": "n"}, headers=_api(w)),
+ "v1 PUT summary": lambda w, c: c.put(f"/api/v1/recordings/{w['rec']}/summary", json={"summary": "s"}, headers=_api(w)),
+ "v1 tag add": lambda w, c: c.post(f"/api/v1/recordings/{w['rec']}/tags", json={"tag_ids": [w["tag"]]}, headers=_api(w)),
+ "web /save": lambda w, c: c.post("/save", json={"id": w["rec"], "title": "Saved"}),
+ "web update_speakers": lambda w, c: c.post(f"/recording/{w['rec']}/update_speakers",
+ json={"speaker_map": {"SPEAKER_00": {"name": "Jane", "isMe": False}}}),
+ "web update_transcript": lambda w, c: c.post(f"/recording/{w['rec']}/update_transcript",
+ json={"transcript_data": [dict(SEGMENTS[0], sentence="Edited.")]}),
+ "web tag add": lambda w, c: c.post(f"/api/recordings/{w['rec']}/tags", json={"tag_id": w["tag"]}),
+ "web archive": lambda w, c: c.post(f"/recording/{w['rec']}/toggle_archive"),
+ "web inbox": lambda w, c: c.post(f"/recording/{w['rec']}/toggle_inbox"),
+}
+
+
[email protected]("path", sorted(WRITE_PATHS))
+def test_each_write_path_moves_updated_at(world, path):
+ _backdate(world["rec"])
+ a, b, d = _no_side_effects()
+ with a, b, d:
+ resp = WRITE_PATHS[path](world, _session(world["me"]))
+ assert resp.status_code in (200, 201), (path, resp.get_data(as_text=True)[:300])
+ assert _updated(world["rec"]) > PAST + timedelta(days=1000), path
+
+
+def test_tag_removal_moves_updated_at(world):
+ with app.app_context():
+ db.session.add(RecordingTag(recording_id=world["rec"], tag_id=world["tag"], order=0))
+ db.session.commit()
+ _backdate(world["rec"])
+ resp = _session(world["me"]).delete(f"/api/v1/recordings/{world['rec']}/tags/{world['tag']}", headers=_api(world))
+ assert resp.status_code == 200
+ assert _updated(world["rec"]) > PAST + timedelta(days=1000)
+
+
[email protected]("change", ["status", "event", "audio_deleted", "share"])
+def test_processing_and_related_rows_move_updated_at(world, change):
+ _backdate(world["rec"])
+ with app.app_context():
+ r = db.session.get(Recording, world["rec"])
+ if change == "status":
+ r.status = "SUMMARIZING"
+ elif change == "event":
+ db.session.add(Event(recording_id=r.id, title="Review", start_datetime=datetime(2026, 10, 9, 15)))
+ elif change == "audio_deleted":
+ r.audio_deleted_at = datetime.utcnow()
+ else:
+ db.session.add(InternalShare(recording_id=r.id, owner_id=world["me"], shared_with_user_id=world["other"]))
+ db.session.commit()
+ assert _updated(world["rec"]) > PAST + timedelta(days=1000)
+
+
+def test_processing_only_fields_do_not_move_updated_at(world):
+ _backdate(world["rec"])
+ with app.app_context():
+ r = db.session.get(Recording, world["rec"])
+ r.processing_time_seconds = 12
+ r.speaker_embeddings = {"SPEAKER_00": [0.1, 0.2]}
+ r.export_filename = "x.md"
+ db.session.commit()
+ assert _updated(world["rec"]) == PAST
+
+
+def test_a_new_recording_starts_with_updated_at_equal_to_created_at(world):
+ with app.app_context():
+ r = Recording(user_id=world["me"], title="New", status="PENDING", original_filename="n.wav")
+ db.session.add(r)
+ db.session.commit()
+ assert r.updated_at is not None and r.updated_at == r.created_at
+
+
+def test_no_bulk_update_bypasses_the_listener():
+ pattern = re.compile(r"(Recording\.query[^\n]*\.update\(|query\(Recording\)[^\n]*\.update\()")
+ hits = []
+ for folder, _, files in os.walk(os.path.join(ROOT, "src")):
+ for name in files:
+ if name.endswith(".py"):
+ path = os.path.join(folder, name)
+ for n, line in enumerate(open(path, encoding="utf-8"), 1):
+ if pattern.search(line):
+ hits.append(f"{os.path.relpath(path, ROOT)}:{n}")
+ assert not hits, f"bulk update on recording bypasses updated_at: {hits}"
+
+
+# ------------------------------------------------------------ feed
+
+def _feed(c, world, **params):
+ q = "&".join(f"{k}={v}" for k, v in params.items())
+ return c.get(f"/api/v1/recordings/changes?{q}", headers=_api(world))
+
+
+def no_settle():
+ with patch.object(rc, "SETTLE_SECONDS", 0):
+ yield
+
+
+def test_the_feed_returns_each_change_once(world, no_settle):
+ _backdate(world["rec"])
+ with app.app_context():
+ second = Recording(user_id=world["me"], title="Second", status="COMPLETED", original_filename="b.wav")
+ db.session.add(second)
+ db.session.commit()
+ second_id = second.id
+ c = app.test_client()
+ first = _feed(c, world).get_json()
+ assert [ch["recording"]["id"] for ch in first["changes"]] == [world["rec"], second_id]
+ assert first["has_more"] is False and first["changes"][0]["recording"]["updated_at"].endswith("Z")
+
+ idle = _feed(c, world, cursor=first["next_cursor"]).get_json()
+ assert idle["changes"] == [] and idle["next_cursor"]
+
+ c.patch(f"/api/v1/recordings/{world['rec']}", json={"title": "Edited"}, headers=_api(world))
+ edited = _feed(c, world, cursor=idle["next_cursor"]).get_json()
+ assert [(ch["type"], ch["recording"]["title"]) for ch in edited["changes"]] == [("upsert", "Edited")]
+
+ with patch("src.services.storage.get_storage_service"):
+ assert c.delete(f"/api/v1/recordings/{second_id}", headers=_api(world)).status_code == 200
+ gone = _feed(c, world, cursor=edited["next_cursor"]).get_json()
+ assert gone["changes"] == [{"type": "delete", "id": second_id, "deleted_at": gone["changes"][0]["deleted_at"],
+ "reason": "deleted"}]
+
+
+def test_retention_deletes_are_marked(world, no_settle):
+ c = app.test_client()
+ start = _feed(c, world).get_json()["next_cursor"]
+ from src.services.recording_deletion import delete_recording_completely
+ with app.app_context(), patch("src.services.storage.get_storage_service"):
+ delete_recording_completely(db.session.get(Recording, world["rec"]), storage=type("S", (), {"delete": lambda *a, **k: None})(),
+ reason="retention")
+ changes = _feed(c, world, cursor=start).get_json()["changes"]
+ assert [(ch["type"], ch["reason"]) for ch in changes] == [("delete", "retention")]
+
+
+def test_paging_visits_every_change_once(world, no_settle):
+ with app.app_context():
+ made = []
+ for i in range(3):
+ r = Recording(user_id=world["me"], title=f"R{i}", status="COMPLETED", original_filename="r.wav")
+ db.session.add(r)
+ db.session.commit()
+ made.append(r.id)
+ c = app.test_client()
+ cursor, seen = None, []
+ for step in range(10):
+ page = _feed(c, world, limit=1, **({"cursor": cursor} if cursor else {})).get_json()
+ if step == 0: # a delete during the full pass is reported
+ with app.app_context():
+ db.session.delete(db.session.get(Recording, made[1]))
+ db.session.commit()
+ seen += [(ch["type"], ch.get("id") or ch["recording"]["id"]) for ch in page["changes"]]
+ cursor = page["next_cursor"]
+ if not page["has_more"]:
+ break
+ # made[1] may be listed before its delete; each change still appears once
+ assert len(seen) == len(set(seen))
+ assert {("upsert", world["rec"]), ("upsert", made[0]), ("upsert", made[2]), ("delete", made[1])} <= set(seen)
+
+
+def test_a_change_inside_the_settle_window_waits(world):
+ c = app.test_client()
+ first = _feed(c, world)
+ assert first.status_code == 200, first.get_json()
+ cursor = first.get_json()["next_cursor"]
+ c.patch(f"/api/v1/recordings/{world['rec']}", json={"title": "Fresh"}, headers=_api(world))
+ waiting = _feed(c, world, cursor=cursor)
+ assert waiting.status_code == 200, waiting.get_json()
+ assert waiting.get_json()["changes"] == []
+ with patch.object(rc, "SETTLE_SECONDS", 0):
+ later = _feed(c, world, cursor=cursor).get_json()["changes"]
+ assert [ch["recording"]["title"] for ch in later] == ["Fresh"]
+
+
+def test_bad_and_expired_cursors(world, no_settle):
+ c = app.test_client()
+ assert _feed(c, world, cursor="garbage!").status_code == 400
+ old = rc.encode_cursor(datetime.utcnow() - timedelta(days=400), 1, 1)
+ with app.app_context():
+ before = SystemSetting.get_setting(rc.PRUNED_BEFORE_KEY)
+ SystemSetting.set_setting(rc.PRUNED_BEFORE_KEY, rc.iso_z(datetime.utcnow() - timedelta(days=90)))
+ try:
+ resp = _feed(c, world, cursor=old)
+ assert resp.status_code == 410 and resp.get_json()["code"] == "cursor_expired"
+ finally:
+ with app.app_context():
+ if before is None:
+ SystemSetting.query.filter_by(key=rc.PRUNED_BEFORE_KEY).delete()
+ db.session.commit()
+ else:
+ SystemSetting.set_setting(rc.PRUNED_BEFORE_KEY, before)
+
+
+def test_another_users_changes_never_appear(world, no_settle):
+ c = app.test_client()
+ cursor = _feed(c, world).get_json()["next_cursor"]
+ with app.app_context():
+ r = Recording(user_id=world["other"], title="Theirs", status="COMPLETED", original_filename="t.wav")
+ db.session.add(r)
+ db.session.commit()
+ theirs = r.id
+ db.session.delete(r)
+ db.session.commit()
+ ids = [ch.get("id") or ch["recording"]["id"] for ch in _feed(c, world, cursor=cursor).get_json()["changes"]]
+ assert theirs not in ids
+
+
+def test_a_shared_recording_writes_tombstones_for_owner_and_recipient(world):
+ with app.app_context():
+ db.session.add(InternalShare(recording_id=world["rec"], owner_id=world["me"], shared_with_user_id=world["other"]))
+ db.session.commit()
+ db.session.delete(db.session.get(Recording, world["rec"]))
+ db.session.commit()
+ stones = {(t.user_id, t.reason) for t in RecordingTombstone.query.filter(
+ RecordingTombstone.recording_id == world["rec"],
+ RecordingTombstone.user_id.in_([world["me"], world["other"]]))}
+ assert stones == {(world["me"], "deleted"), (world["other"], "deleted")}
+
+
+def test_removing_a_share_writes_access_revoked(world):
+ with app.app_context():
+ share = InternalShare(recording_id=world["rec"], owner_id=world["me"], shared_with_user_id=world["other"])
+ db.session.add(share)
+ db.session.commit()
+ db.session.delete(share)
+ db.session.commit()
+ stones = [(t.user_id, t.reason) for t in RecordingTombstone.query.filter(
+ RecordingTombstone.recording_id == world["rec"],
+ RecordingTombstone.user_id.in_([world["me"], world["other"]]))]
+ assert stones == [(world["other"], "access_revoked")]
+
+
+def test_pruning_removes_old_tombstones_and_records_the_horizon(world):
+ with app.app_context():
+ db.session.add(RecordingTombstone(recording_id=999999, user_id=world["me"],
+ deleted_at=datetime.utcnow() - timedelta(days=400), reason="deleted"))
+ db.session.commit()
+ assert rc.prune_tombstones() >= 1
+ assert RecordingTombstone.query.filter_by(recording_id=999999, user_id=world["me"]).count() == 0
+ assert SystemSetting.get_setting(rc.PRUNED_BEFORE_KEY)
+
+
+# ------------------------------------------------------------ list filters
+
+def test_list_filters_updated_since_and_date_field(world):
+ _backdate(world["rec"])
+ with app.app_context():
+ r = db.session.get(Recording, world["rec"])
+ r.meeting_date = datetime(2021, 6, 1, 10)
+ db.session.commit()
+ fresh = Recording(user_id=world["me"], title="Fresh", status="COMPLETED", original_filename="f.wav")
+ db.session.add(fresh)
+ db.session.commit()
+ fresh_id = fresh.id
+ c = app.test_client()
+ since = c.get("/api/v1/recordings?updated_since=2025-01-01T00:00:00Z", headers=_api(world)).get_json()
+ ids = [r["id"] for r in since["recordings"]]
+ assert fresh_id in ids and world["rec"] in ids # the meeting_date edit moved it
+ by_meeting = c.get("/api/v1/recordings?date_field=meeting_date&date_from=2021-06-01&date_to=2021-06-01",
+ headers=_api(world)).get_json()
+ assert [r["id"] for r in by_meeting["recordings"]] == [world["rec"]]
+ assert c.get("/api/v1/recordings?date_field=bogus", headers=_api(world)).status_code == 400
+ assert c.get("/api/v1/recordings?updated_since=nope", headers=_api(world)).status_code == 400
+ ordered = c.get("/api/v1/recordings?sort_by=updated_at&sort_order=desc", headers=_api(world)).get_json()
+ stamps = [r["updated_at"] for r in ordered["recordings"]]
+ assert stamps == sorted(stamps, reverse=True)
diff --git a/tests/test_upgrade_mailr_api.py b/tests/test_upgrade_mailr_api.py
index c43d6f11..0a83f717 100644
--- a/tests/test_upgrade_mailr_api.py
+++ b/tests/test_upgrade_mailr_api.py
@@ -59,3 +59,51 @@ def test_api_token_scopes_column(tmp_path, fixture):
con.close()
assert row[:4] == ("abc123", "n8n", "2027-01-01 00:00:00", 1)
assert row[4] is None, "existing tokens keep full access (scopes NULL)"
+
+
[email protected]("fixture", FIXTURES, ids=[f[:-4] for f in FIXTURES])
+def test_recording_updated_at_and_tombstones(tmp_path, fixture):
+ """G2: updated_at is filled from completed_at or created_at, once."""
+ db_path, con = _load(tmp_path, fixture)
+ cols = _columns(con, "recording")
+ con.execute('INSERT INTO "user" (id, username, email, password) VALUES (1, ?, ?, ?)',
+ ("u", "[email protected]", "hash"))
+ extra = {"keep_audio_only": 0} if "keep_audio_only" in cols else {}
+
+ def _insert(**values):
+ values.update(extra)
+ names = ", ".join(values)
+ marks = ", ".join("?" for _ in values)
+ con.execute(f"INSERT INTO recording ({names}) VALUES ({marks})", tuple(values.values()))
+
+ _insert(id=7, user_id=1, title="Old", status="COMPLETED", created_at="2024-03-01 10:00:00")
+ if "completed_at" in cols:
+ _insert(id=8, user_id=1, title="Done", status="COMPLETED", created_at="2024-03-02 10:00:00",
+ completed_at="2024-03-02 11:30:00")
+ con.commit()
+ con.close()
+
+ _upgrade(db_path)
+ con = sqlite3.connect(db_path)
+ con.execute("UPDATE recording SET updated_at = '2025-05-05 05:05:05' WHERE id = 7")
+ con.commit()
+ con.close()
+ _upgrade(db_path) # second start: the backfill does not run again
+
+ con = sqlite3.connect(db_path)
+ assert "updated_at" in _columns(con, "recording")
+ rows = dict(con.execute("SELECT id, updated_at FROM recording").fetchall())
+ titles = dict(con.execute("SELECT id, title FROM recording").fetchall())
+ indexes = {r[1] for r in con.execute("PRAGMA index_list('recording')")}
+ tables = {r[0] for r in con.execute("SELECT name FROM sqlite_master WHERE type='table'")}
+ ledger = con.execute("SELECT count(*) FROM schema_migrations "
+ "WHERE migration_id = '0002_backfill_recording_updated_at'").fetchone()[0]
+ since = con.execute("SELECT value FROM system_setting WHERE key = 'changes_feed_since'").fetchone()
+ con.close()
+ assert rows[7].startswith("2025-05-05 05:05:05"), "second start left the value alone"
+ if 8 in rows:
+ assert rows[8].startswith("2024-03-02 11:30:00"), "filled from completed_at"
+ assert titles[7] == "Old"
+ assert {"ix_recording_updated_at", "ix_recording_user_updated"} <= indexes
+ assert "recording_tombstone" in tables
+ assert ledger == 1 and since and since[0].endswith("Z")