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.exampleindex 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 enablesdiff --git a/config/env.transcription.example b/config/env.transcription.exampleindex 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.exampleindex 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 enablesdiff --git a/config/env.whisperx.example b/config/env.whisperx.exampleindex 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 generationdiff --git a/docs/admin-guide/retention.md b/docs/admin-guide/retention.mdindex 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-Deletiondiff --git a/docs/user-guide/api-reference.md b/docs/user-guide/api-reference.mdindex 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```httpdiff --git a/src/api/api_v1.py b/src/api/api_v1.pyindex 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 parameterspage = 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_atif 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 filterif 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_zinclude = 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.pyindex 55813672..287d09d1 100644--- a/src/app.py+++ b/src/app.py@@ -495,6 +495,10 @@ else:from src.database import dbdb.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 modulesfrom src.models import (User, Speaker, Recording, TranscriptChunk, Share, InternalShare,diff --git a/src/config/startup.py b/src/config/startup.pyindex 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 failurediff --git a/src/init_db.py b/src/init_db.pyindex 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__.pyindex 6270c543..f50713d4 100644--- a/src/models/__init__.py+++ b/src/models/__init__.py@@ -18,7 +18,7 @@ from .user import User, Speakerfrom .voice import VoiceEmbeddingSpace, SpeakerVoiceSamplefrom .api_token import APITokenfrom .speaker_snippet import SpeakerSnippet-from .recording import Recording, TranscriptChunk+from .recording import Recording, RecordingTombstone, TranscriptChunkfrom .sharing import Share, InternalShare, SharedRecordingStatefrom .organization import Group, GroupMembership, Tag, RecordingTag, Folderfrom .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.pyindex 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 serializationcompleted_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_idreturn 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.pynew file mode 100644index 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 responsediff --git a/src/services/recording_deletion.py b/src/services/recording_deletion.pyindex dfc1afcb..1e03cae6 100644--- a/src/services/recording_deletion.py+++ b/src/services/recording_deletion.py@@ -12,7 +12,7 @@ from flask import current_appfrom 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 therecording (retention wants that, so its next run retries). A user'sdelete 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 ProcessingJobfrom 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.pyindex 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_completelydeleted_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'] += 1current_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.pynew file mode 100644index 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.headersdiff --git a/tests/test_api_v1_scope_coverage.py b/tests/test_api_v1_scope_coverage.pyindex 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 appEXPECTED = {- "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.pynew file mode 100644index 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.pyindex 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")