import math import hashlib import re import wave from datetime import datetime, timezone as datetime_timezone from django.core.cache import cache from django.db import IntegrityError, transaction from django.utils.dateparse import parse_datetime from datetime import timedelta from decimal import Decimal, InvalidOperation import json import logging import mimetypes import uuid from pathlib import Path from urllib.error import HTTPError, URLError from urllib.request import Request, urlopen from django.contrib.admin.views.decorators import staff_member_required from django.http import FileResponse, Http404, JsonResponse from django.core import signing from django.shortcuts import get_object_or_404, redirect, render from django.utils import timezone from django.utils.dateparse import parse_date from django.utils.translation import gettext as _ from django.views.decorators.cache import never_cache from django.views.decorators.csrf import csrf_exempt from django.views.decorators.http import require_http_methods from .h3_utils import cell_boundary, cell_center, cell_from_coordinates, h3_resolution from .browser_policy import advisory_browser_metadata, browser_config, browser_policy from .models import BrowserProcessingSettings, ClassificationRule, Event, ManualReportRevision, PendingEvent, Sensor, SensorSubmission from .field_notes import draft_token from .bursts import BURST_MIN_BANGS, DEFAULT_ESTIMATED_DURATION_MINUTES, burst_intensity, burst_rate CLASSIFIER_URL = "http://192.168.1.122:5000/classify" MAX_AUDIO_SIZE = 25 * 1024 * 1024 # 25 MiB: enough for this demo, and avoids accidental large uploads. FIREWORK_TERMS = ( "firework", "firecracker", "explosion", "explosive", "bang", "boom", "hiss", "crackle", "burst", "gunshot", "artillery", "cannon", "rocket", ) SPEECH_TERMS = ( "speech", "conversation", "narration", "monologue", "babbling", "whisper", "speaking", "speech synthesizer", ) AUDIO_EXTENSIONS = {".aac", ".aif", ".aiff", ".flac", ".m4a", ".mp3", ".ogg", ".opus", ".wav", ".weba"} logger = logging.getLogger(__name__) @require_http_methods(["GET"]) @never_cache def browser_processing_policy(request): return JsonResponse(browser_policy()) @never_cache def fireworks_view(request): return render(request, "fireworks_detect/home.html", {"browser_processing_config": browser_config()}) MAP_DATE_RANGES = { "7": 7, "14": 14, "30": 30, "all": None, "custom": None, } def _map_filters(request): """Return the selected map filters, using an inclusive date range.""" selected_range = request.GET.get("range", "14") if selected_range not in MAP_DATE_RANGES: selected_range = "14" if selected_range == "custom": date_from = parse_date(request.GET.get("from", "")) date_to = parse_date(request.GET.get("to", "")) elif MAP_DATE_RANGES[selected_range]: date_to = timezone.localdate() date_from = date_to - timedelta(days=MAP_DATE_RANGES[selected_range] - 1) else: date_from = date_to = None visual = request.GET.get("visual", "all") if visual not in {"all", "yes", "no"}: visual = "all" source = request.GET.get("source", "manual") if source not in {"manual", "sensor", "all"}: source = "manual" return { "date_from": date_from, "date_to": date_to, "range": selected_range, "visual": visual, "source": source, } def _events_for_map(filters): """Create H3 map data for reviewed events with a stored, trusted location.""" source = filters.get("source", "manual") events = Event.objects.all() if source != "all": events = events.filter(source_type=source) if filters["date_from"]: events = events.filter(created_at__date__gte=filters["date_from"]) if filters["date_to"]: events = events.filter(created_at__date__lte=filters["date_to"]) if filters["visual"] == "yes": events = events.filter(visually_confirmed=True) elif filters["visual"] == "no": events = events.filter(visually_confirmed=False) cells = {} mapped_events = [] for event in events.values( "h3_cell", "latitude", "longitude", "occurrences", "visually_confirmed", "direction_degrees", "direction_accuracy_degrees", "created_at", "captured_at", "submitted_at", "source_type", "observation_duration_minutes", "observation_duration_kind", "occurrence_time_approximate", ): # Coordinates are used only here to derive an H3 cell; they never leave the server. h3_cell = event["h3_cell"] or cell_from_coordinates(event["latitude"], event["longitude"]) center = cell_center(h3_cell) if h3_cell else None boundary = cell_boundary(h3_cell) if h3_cell else None if not center or not boundary: continue aggregate = cells.setdefault(h3_cell, { "cell": h3_cell, "boundary": boundary, "center": center, "reports": 0, "occurrences": 0, "manual_reports": 0, "sensor_reports": 0, }) aggregate["reports"] += 1 aggregate["occurrences"] += event["occurrences"] aggregate[f'{event["source_type"]}_reports'] += 1 rate = burst_rate(event["occurrences"], event["observation_duration_minutes"]) if event["observation_duration_kind"] else None mapped_events.append({ "cell": h3_cell, "center": center, "source_type": event["source_type"], "occurrences": event["occurrences"], "event_kind": "burst" if event["occurrences"] >= BURST_MIN_BANGS else "ordinary", "observation_duration_minutes": event["observation_duration_minutes"], "observation_duration_kind": event["observation_duration_kind"], "bangs_per_15_minutes": float(rate) if rate is not None else None, "burst_intensity": burst_intensity(event["occurrences"], event["observation_duration_minutes"]) if event["observation_duration_kind"] else None, "occurrence_time_approximate": event["occurrence_time_approximate"], "occurred_on": (event["captured_at"] or event["created_at"]).date().isoformat(), "submitted_on": event["submitted_at"].date().isoformat() if event["submitted_at"] else None, "visually_confirmed": event["visually_confirmed"], # A day is sufficient for this map and avoids sharing a precise report time. "reported_on": event["created_at"].date().isoformat(), "direction_degrees": float(event["direction_degrees"]) if event["direction_degrees"] is not None else None, "direction_accuracy_degrees": ( float(event["direction_accuracy_degrees"]) if event["direction_accuracy_degrees"] is not None else None ), }) return mapped_events, list(cells.values()) @never_cache def fireworks_map_view(request): filters = _map_filters(request) map_events, h3_cells = _events_for_map(filters) return render(request, "fireworks_detect/map.html", { "h3_resolution": h3_resolution(), "h3_cells": h3_cells, "map_events": map_events, "mapped_event_count": len(map_events), "map_source": filters["source"], "map_filters": { "date_from": filters["date_from"].isoformat() if filters["date_from"] else "", "date_to": filters["date_to"].isoformat() if filters["date_to"] else "", "range": filters["range"], "visual": filters["visual"], "source": filters["source"], }, }) @never_cache def dashboard_view(request): from .field_notes import draft_token from .forms import FieldNoteForm map_events, h3_cells = _events_for_map({ "date_from": None, "date_to": None, "range": "all", "visual": "all", }) return render(request, "fireworks_detect/dashboard.html", { "note_token": draft_token(request.user), "note_form": FieldNoteForm(), "note_mode": "draft", "note_panel_id": "live-field-notes", "h3_resolution": h3_resolution(), "h3_cells": h3_cells, "map_events": map_events, "browser_processing_config": browser_config(), }) def events_view(request): return render(request, "fireworks_detect/events.html", {"events": Event.objects.all()[:30]}) def _classification_context(payload): predictions = _decorate_predictions(payload.get("predictions")) peak_predictions = _decorate_predictions(payload.get("peak_predictions")) return { "result": payload, "predictions": predictions, "peak_predictions": peak_predictions, "firework_count": sum(item["kind"] == "firework" for item in predictions + peak_predictions), "speech_count": sum(item["kind"] == "speech" for item in predictions + peak_predictions), } def _label_kind(label): lowered = label.lower() if any(term in lowered for term in SPEECH_TERMS): return "speech" if any(term in lowered for term in FIREWORK_TERMS): return "firework" return "default" def _score_details(score): try: percentage = max(0, min(float(score) * 100, 100)) except (TypeError, ValueError): return "—", 0 return f"{percentage:.1f}%", round(percentage, 1) def _decorate_predictions(predictions): decorated = [] for prediction in predictions if isinstance(predictions, list) else []: if not isinstance(prediction, dict): continue label = str(prediction.get("class", "Unknown")) score, score_width = _score_details(prediction.get("score")) decorated.append({ **prediction, "label": label, "kind": _label_kind(label), "score_display": score, "score_width": score_width, }) return decorated def _encode_audio_multipart(uploaded_file): """Build the multipart request expected by the classifier without a third-party HTTP client.""" boundary = f"----DjangoAudioUpload{uuid.uuid4().hex}" filename = Path(uploaded_file.name).name.replace('"', "") content_type = getattr(uploaded_file, "content_type", None) or mimetypes.guess_type(filename)[0] or "application/octet-stream" header = ( f"--{boundary}\r\n" f'Content-Disposition: form-data; name="file"; filename="{filename}"\r\n' f"Content-Type: {content_type}\r\n\r\n" ).encode() body = header + uploaded_file.read() + f"\r\n--{boundary}--\r\n".encode() return body, f"multipart/form-data; boundary={boundary}" def _render_error(request, message, status=400): return render(request, "fireworks_detect/classification_result.html", {"error": message}, status=status) @require_http_methods(["GET", "POST"]) @never_cache def classify_upload(request): # Opening this endpoint in a browser should return the upload screen rather # than a 405 page. Only POST requests perform classification. if request.method == "GET": return redirect("fireworks_detect:fireworks") uploaded_file = request.FILES.get("audio") if not uploaded_file: return _render_error(request, _("Choose an audio file before starting the analysis.")) extension = Path(uploaded_file.name).suffix.lower() if not (uploaded_file.content_type or "").startswith("audio/") and extension not in AUDIO_EXTENSIONS: return _render_error(request, _("Please upload a supported audio file (such as WAV, MP3, M4A, or OGG).")) if uploaded_file.size > MAX_AUDIO_SIZE: return _render_error(request, _("This demo accepts audio files up to 25 MiB.")) metadata = advisory_browser_metadata(request.POST) if metadata: logger.info("Browser beta diagnostics (advisory only): %s", metadata) body, content_type = _encode_audio_multipart(uploaded_file) classifier_request = Request( CLASSIFIER_URL, data=body, headers={"Content-Type": content_type, "Accept": "application/json"}, method="POST", ) try: with urlopen(classifier_request, timeout=60) as response: payload = json.loads(response.read().decode("utf-8")) except HTTPError as error: return _render_error(request, _("The classifier returned an error (HTTP %(code)s).") % {"code": error.code}, status=502) except (URLError, TimeoutError): return _render_error(request, _("The classifier could not be reached. Please try again shortly."), status=502) except json.JSONDecodeError: return _render_error(request, _("The classifier returned an unreadable response."), status=502) if not isinstance(payload, dict): return _render_error(request, _("The classifier returned an unexpected response."), status=502) # Keep the raw payload in this request flow; this is the future hand-off point # for saving the upload and its classification to a database or queue. context = _classification_context(payload) override = ( BrowserProcessingSettings.enabled() and metadata.get("browser_override") is True and metadata.get("browser_gate_result") in {"speech_only", "no_match"} ) if override: # The browser gate is advisory. Always classify server-side first, then # force this explicit override into Pending Review regardless of scores. pending = PendingEvent.objects.create( audio_file=uploaded_file, original_filename=uploaded_file.name, classifier_response=payload, ) context["pending"] = pending logger.info("Browser override sent to Pending Review: %s", pending.pk) else: context["submission_token"] = signing.dumps(payload, salt="fireworks_detect.classification") return render(request, "fireworks_detect/classification_result.html", context) @require_http_methods(["POST"]) @never_cache def submit_pending_event(request): metadata = advisory_browser_metadata(request.POST) if metadata: logger.info("Browser beta submission diagnostics (advisory only): %s", metadata) uploaded_file = request.FILES.get("audio") token = request.POST.get("classification_token") if not uploaded_file: return render(request, "fireworks_detect/pending_submission.html", {"error": _("Keep the analysed audio file selected before submitting it for review.")}, status=400) if not token: return render(request, "fireworks_detect/pending_submission.html", {"error": _("Analyse the file before submitting it for review.")}, status=400) try: payload = signing.loads(token, salt="fireworks_detect.classification", max_age=60 * 60) except signing.BadSignature: return render(request, "fireworks_detect/pending_submission.html", {"error": _("This analysis has expired. Please analyse the audio again.")}, status=400) if not isinstance(payload, dict): return render(request, "fireworks_detect/pending_submission.html", {"error": _("The saved analysis is not valid.")}, status=400) pending = PendingEvent.objects.create( audio_file=uploaded_file, original_filename=uploaded_file.name, classifier_response=payload, ) return render(request, "fireworks_detect/pending_submission.html", {"pending": pending}) def _manual_coordinates(request): try: latitude = Decimal(request.POST.get("latitude", "")) longitude = Decimal(request.POST.get("longitude", "")) if not -90 <= latitude <= 90 or not -180 <= longitude <= 180: return None, None return latitude.quantize(Decimal("0.000001")), longitude.quantize(Decimal("0.000001")) except (InvalidOperation, TypeError, ValueError): return None, None def _manual_direction(request): try: heading = float(request.POST.get("direction_degrees", "")) except (TypeError, ValueError): return None, None if not math.isfinite(heading) or not 0 <= heading < 360: return None, None try: accuracy = float(request.POST.get("direction_accuracy_degrees", "")) except (TypeError, ValueError): accuracy = None if accuracy is not None and (not math.isfinite(accuracy) or accuracy < 0): accuracy = None return heading, accuracy @require_http_methods(["GET"]) @never_cache def manual_direction_panel(request): return render(request, "fireworks_detect/includes/manual_direction_panel.html", { "measuring": request.GET.get("mode") == "measure", }) @require_http_methods(["POST"]) @never_cache @transaction.atomic def submit_manual_pending_event(request): try: occurrences = int(request.POST.get("occurrences", "")) except (TypeError, ValueError): occurrences = 0 if not 1 <= occurrences <= 1000: return render( request, "fireworks_detect/manual_pending_submission.html", {"error": _("Choose between 1 and 1,000 occurrences.")}, status=400, ) details, error = _manual_observation_details(request, occurrences) if error: return render(request, "fireworks_detect/manual_pending_submission.html", {"error": error}, status=400) uploaded_file = request.FILES.get("audio") if uploaded_file: if uploaded_file.size > MAX_AUDIO_SIZE or uploaded_file.content_type not in ("audio/wav", "audio/wave", "audio/x-wav"): return render(request, "fireworks_detect/manual_pending_submission.html", {"error": _("Please attach a WAV clip no larger than 25 MiB.")}, status=400) header = uploaded_file.read(12) uploaded_file.seek(0) if len(header) != 12 or header[:4] != b"RIFF" or header[8:] != b"WAVE": return render(request, "fireworks_detect/manual_pending_submission.html", {"error": _("The attached audio is not a WAV file.")}, status=400) uploaded_file.name = f"sound-signal-manual-{timezone.now():%Y%m%d-%H%M%S}-{uuid.uuid4().hex[:8]}.wav" latitude, longitude = _manual_coordinates(request) h3_cell = cell_from_coordinates(latitude, longitude) direction_degrees, direction_accuracy_degrees = _manual_direction(request) # Reject stale/foreign contexts before FileField writes an audio file. note_token = request.POST.get("field_note_context") if request.user.is_authenticated and note_token: from .field_notes import context_for_token from django.core.exceptions import PermissionDenied note_context = context_for_token(request.user, note_token) if note_context.event_id or note_context.pending_event_id: raise PermissionDenied("This note context already belongs to a report. Reload before reporting again.") pending = PendingEvent.objects.create( audio_file=uploaded_file, original_filename="Manual fireworks report", classifier_response={}, source_type=PendingEvent.SourceType.MANUAL, occurrences=occurrences, **details, latitude=latitude, longitude=longitude, h3_cell=h3_cell or "", direction_degrees=direction_degrees, direction_accuracy_degrees=direction_accuracy_degrees, direction_source="device_compass" if direction_degrees is not None else "", ) from .field_notes import bind_report bind_report(request.user, request.POST.get("field_note_context"), pending) owned = request.session.get("manual_pending_ids", []) request.session["manual_pending_ids"] = (owned + [pending.pk])[-20:] direction_names = { "N": _("North"), "NE": _("Northeast"), "E": _("East"), "SE": _("Southeast"), "S": _("South"), "SW": _("Southwest"), "W": _("West"), "NW": _("Northwest"), } return render(request, "fireworks_detect/manual_pending_submission.html", { "pending": pending, "editable": True, "next_note_token": draft_token(request.user), "direction_label": direction_names.get(pending.direction_cardinal) if direction_degrees is not None else "", }) def _manual_observation_details(request, occurrences): raw_time = request.POST.get("occurred_at", "").strip() if raw_time: occurred_at = parse_datetime(raw_time) if occurred_at is None: return None, _("Enter a valid occurrence date and time.") if timezone.is_naive(occurred_at): occurred_at = timezone.make_aware(occurred_at, timezone.get_current_timezone()) if occurred_at > timezone.now() + timedelta(minutes=5): return None, _("Occurrence time cannot be in the future.") else: occurred_at = timezone.now() details = { "captured_at": occurred_at, "occurrence_time_approximate": request.POST.get("time_approximate") == "on", "observation_duration_minutes": None, "observation_duration_kind": "", } if occurrences >= BURST_MIN_BANGS and request.POST.get("duration_confirmed") == "on": raw_duration = request.POST.get("duration_minutes", "").strip() try: duration = int(raw_duration) if raw_duration else DEFAULT_ESTIMATED_DURATION_MINUTES except ValueError: return None, _("Enter a duration between 1 and 1,440 minutes.") if not 1 <= duration <= 1440: return None, _("Enter a duration between 1 and 1,440 minutes.") details["observation_duration_minutes"] = duration details["observation_duration_kind"] = PendingEvent.DurationKind.ESTIMATED return details, None @require_http_methods(["POST"]) @never_cache def update_manual_pending_event(request, event_id): if event_id not in request.session.get("manual_pending_ids", []): raise Http404 try: occurrences = int(request.POST.get("occurrences", "")) except (TypeError, ValueError): occurrences = 0 if not 1 <= occurrences <= 1000: return render(request, "fireworks_detect/manual_pending_submission.html", {"error": _("Choose between 1 and 1,000 occurrences.")}, status=400) _, error = _manual_observation_details(request, occurrences) if error: return render(request, "fireworks_detect/manual_pending_submission.html", {"error": error}, status=400) # The occurrence time and location belong to the original observation. duration = None kind = "" if occurrences >= BURST_MIN_BANGS and request.POST.get("duration_confirmed") == "on": raw = request.POST.get("duration_minutes", "").strip() duration = int(raw) if raw else DEFAULT_ESTIMATED_DURATION_MINUTES kind = PendingEvent.DurationKind.ESTIMATED with transaction.atomic(): pending = get_object_or_404(PendingEvent.objects.select_for_update(), pk=event_id, source_type=PendingEvent.SourceType.MANUAL) ManualReportRevision.objects.create( pending_event=pending, original_pending_id=pending.pk, previous_occurrences=pending.occurrences, new_occurrences=occurrences, previous_duration_minutes=pending.observation_duration_minutes, new_duration_minutes=duration, ) pending.occurrences = occurrences pending.observation_duration_minutes = duration pending.observation_duration_kind = kind pending.save(update_fields=["occurrences", "observation_duration_minutes", "observation_duration_kind"]) return render(request, "fireworks_detect/manual_pending_submission.html", {"pending": pending, "editable": True, "updated": True}) @never_cache def events_list(request): return render(request, "fireworks_detect/events_list.html", {"events": Event.objects.all()[:30]}) @never_cache def event_detail(request, event_id): event = get_object_or_404(Event, pk=event_id) context = _classification_context(event.classifier_response) context["event"] = event context["event_h3_cell"] = event.h3_cell or cell_from_coordinates(event.latitude, event.longitude) if request.user.is_authenticated: from .note_views import panel_context context.update(panel_context(request, {"event": event.pk})) template = "fireworks_detect/event_detail.html" if request.headers.get("HX-Request") == "true" else "fireworks_detect/event_page.html" return render(request, template, context) def _audio_response(record): if not record.audio_file: raise Http404(_("No audio is attached to this record.")) content_type = mimetypes.guess_type(record.audio_file.name)[0] or "application/octet-stream" return FileResponse(record.audio_file.open("rb"), content_type=content_type) @staff_member_required def pending_audio(request, event_id): return _audio_response(get_object_or_404(PendingEvent, pk=event_id)) @staff_member_required def event_audio(request, event_id): return _audio_response(get_object_or_404(Event, pk=event_id)) def _sensor_from_request(request): authorization = request.headers.get("Authorization", "") token = authorization.removeprefix("Bearer ").strip() if authorization.startswith("Bearer ") else request.headers.get("X-Sensor-Token", "").strip() if not token: return None sensor = Sensor.objects.filter(is_active=True, token_prefix=token[:15]).first() return sensor if sensor and sensor.token_matches(token) else None def _sensor_error(message, status=400): return JsonResponse({"detail": message}, status=status) @csrf_exempt @require_http_methods(["POST"]) def classify_audio(request): """Token-authenticated device API. Browser uploads use classify_upload instead.""" sensor = _sensor_from_request(request) if not sensor: return _sensor_error("A valid sensor API token is required.", 401) uploaded_file = request.FILES.get("file") or request.FILES.get("audio") if not uploaded_file: return _sensor_error("Attach audio as multipart field 'file'.") extension = Path(uploaded_file.name).suffix.lower() if not (uploaded_file.content_type or "").startswith("audio/") and extension not in AUDIO_EXTENSIONS: return _sensor_error("Unsupported audio file.") if uploaded_file.size > MAX_AUDIO_SIZE: return _sensor_error("Audio exceeds the 25 MiB limit.") body, content_type = _encode_audio_multipart(uploaded_file) classifier_request = Request(CLASSIFIER_URL, data=body, headers={"Content-Type": content_type, "Accept": "application/json"}, method="POST") try: with urlopen(classifier_request, timeout=60) as response: payload = json.loads(response.read().decode("utf-8")) except HTTPError as error: return _sensor_error(f"Classifier returned HTTP {error.code}.", 502) except (URLError, TimeoutError, json.JSONDecodeError): return _sensor_error("Classifier is unavailable or returned invalid JSON.", 502) if not isinstance(payload, dict): return _sensor_error("Classifier returned an unexpected response.", 502) uploaded_file.seek(0) pending = PendingEvent.objects.create(audio_file=uploaded_file, sensor=sensor, original_filename=uploaded_file.name, classifier_response=payload) sensor.record_heartbeat(submission=True) return JsonResponse({**payload, "pending_event_id": pending.pk, "sensor": sensor.name}, status=201) def _submission_error(code, detail, status=400): return JsonResponse({"code": code, "detail": detail}, status=status) @csrf_exempt @require_http_methods(["POST"]) def submit_sensor_pending(request): sensor = _sensor_from_request(request) if sensor is None: return _submission_error("unauthorized", "A valid sensor API token is required.", 401) if not sensor.owner_id: return _submission_error("unowned_sensor", "Sensor has no registered owner.", 403) if request.POST.get("sensor_id") != str(sensor.pk): return _submission_error("sensor_mismatch", "sensor_id must match the authenticated sensor.", 403) event_id = request.POST.get("event_id", "") if not re.fullmatch(r"[A-Za-z0-9_-]{1,100}", event_id): return _submission_error("invalid_event_id", "Provide a valid event_id.") uploaded = request.FILES.get("file") if uploaded is None: return _submission_error("missing_file", "Attach PCM WAV as multipart field 'file'.") if uploaded.size > MAX_AUDIO_SIZE: return _submission_error("file_too_large", "Audio exceeds 25 MiB.", 413) if not uploaded.name.lower().endswith(".wav"): return _submission_error("invalid_audio", "Only PCM WAV is accepted.") try: with wave.open(uploaded, "rb") as wav: if wav.getcomptype() != "NONE" or wav.getnchannels() != 1 or wav.getsampwidth() != 2 or wav.getframerate() != 16000: raise ValueError("WAV must be 16-bit mono PCM at 16 kHz.") frames = wav.getnframes() if len(wav.readframes(frames)) != frames * 2: raise ValueError("WAV sample data is truncated.") actual_duration = frames / wav.getframerate() if not 0.1 <= actual_duration <= 30: raise ValueError("WAV duration must be between 0.1 and 30 seconds.") declared_duration = float(request.POST.get("duration_seconds", "")) if not math.isfinite(declared_duration) or abs(declared_duration - actual_duration) > 0.1: raise ValueError("duration_seconds does not match the WAV.") except (wave.Error, EOFError, ValueError, TypeError) as error: return _submission_error("invalid_audio", str(error)) finally: uploaded.seek(0) raw_time = request.POST.get("captured_at", "") if not raw_time and request.POST.get("time_state") == "unknown": captured_at = None else: try: captured_at = datetime.fromtimestamp(float(raw_time), datetime_timezone.utc) if re.fullmatch(r"[0-9]{10}(?:\.[0-9]+)?", raw_time) else parse_datetime(raw_time) if captured_at is None or timezone.is_naive(captured_at): raise ValueError() if captured_at > timezone.now() + timedelta(minutes=5): raise ValueError() except (ValueError, OverflowError, OSError): return _submission_error("invalid_capture_time", "Provide a valid UTC captured_at or time_state=unknown.") firmware = request.POST.get("firmware_version", "") if not 1 <= len(firmware) <= 64 or not firmware.isprintable(): return _submission_error("invalid_firmware_version", "Provide a printable firmware_version of at most 64 characters.") metadata = {"time_state": "unknown"} if captured_at is None else {} for key in ("trigger_type", "signal_rms", "signal_peak", "latitude", "longitude", "capture_started_at", "triggered_at", "queued_at"): value = request.POST.get(key) if value is None or value == "": continue if key.endswith("_at"): parsed = parse_datetime(value) if parsed is None or timezone.is_naive(parsed): return _submission_error("invalid_metadata", f"Invalid {key}.") elif key == "trigger_type": if len(value) > 64 or not value.isprintable(): return _submission_error("invalid_metadata", "Invalid trigger_type.") else: try: number = float(value) if not math.isfinite(number) or (key.startswith("signal_") and number < 0) or (key == "latitude" and abs(number) > 90) or (key == "longitude" and abs(number) > 180): raise ValueError() except ValueError: return _submission_error("invalid_metadata", f"Invalid {key}.") metadata[key] = value digest = hashlib.sha256() for chunk in uploaded.chunks(): digest.update(chunk) audio_hash = digest.hexdigest() uploaded.seek(0) existing = SensorSubmission.objects.filter(sensor=sensor, event_id=event_id).first() if existing: if existing.audio_sha256 != audio_hash: return _submission_error("event_id_conflict", "event_id already belongs to different audio.", 409) return JsonResponse({"submission_id": str(existing.submission_id), "event_id": event_id, "status": "pending" if existing.pending_event_id else "reviewed", "duplicate": True}, status=200) rate_key = f"sensor-submissions:{sensor.pk}" if cache.get(rate_key, 0) >= 30: response = _submission_error("rate_limited", "Sensor submission rate exceeded.", 429) response["Retry-After"] = "60" return response cache.add(rate_key, 0, 60) try: cache.incr(rate_key) except ValueError: cache.set(rate_key, 1, 60) body, content_type = _encode_audio_multipart(uploaded) classifier_request = Request(CLASSIFIER_URL, data=body, headers={"Content-Type": content_type, "Accept": "application/json"}, method="POST") try: with urlopen(classifier_request, timeout=60) as response: payload = json.loads(response.read().decode("utf-8")) if not isinstance(payload, dict): raise ValueError("Classifier response must be an object.") except (HTTPError, URLError, TimeoutError, OSError, ValueError, json.JSONDecodeError): return _submission_error("classifier_unavailable", "Classification failed; retain the queued recording.", 502) uploaded.seek(0) pending = None try: with transaction.atomic(): pending = PendingEvent.objects.create(audio_file=uploaded, sensor=sensor, source_type=PendingEvent.SourceType.SENSOR, original_filename=Path(uploaded.name).name[:255], classifier_response=payload, captured_at=captured_at, firmware_version=firmware, device_metadata=metadata) receipt = SensorSubmission.objects.create(sensor=sensor, event_id=event_id, audio_sha256=audio_hash, pending_event=pending) except IntegrityError: if pending and pending.audio_file: pending.audio_file.storage.delete(pending.audio_file.name) existing = SensorSubmission.objects.get(sensor=sensor, event_id=event_id) if existing.audio_sha256 != audio_hash: return _submission_error("event_id_conflict", "event_id already belongs to different audio.", 409) return JsonResponse({"submission_id": str(existing.submission_id), "event_id": event_id, "status": "pending" if existing.pending_event_id else "reviewed", "duplicate": True}) sensor.record_heartbeat(submission=True) return JsonResponse({"submission_id": str(receipt.submission_id), "event_id": event_id, "pending_event_id": pending.pk, "status": "pending", "classification": payload}, status=201) @csrf_exempt @require_http_methods(["POST"]) def sensor_heartbeat(request): sensor = _sensor_from_request(request) if not sensor: return _sensor_error("A valid sensor API token is required.", 401) sensor.record_heartbeat() return JsonResponse({"ok": True, "sensor": sensor.name, "heartbeat_at": sensor.last_heartbeat.isoformat()}) @require_http_methods(["GET"]) def classification_whitelist(request): classifications = ClassificationRule.objects.filter( rule_type=ClassificationRule.RuleType.WHITELIST, enabled=True, ).order_by("value").values_list("value", flat=True) return JsonResponse({"classifications": list(classifications)}) @require_http_methods(["GET"]) def classification_blacklist(request): classifications = ClassificationRule.objects.filter( rule_type=ClassificationRule.RuleType.BLACKLIST, enabled=True, ).order_by("value").values_list("value", flat=True) return JsonResponse({"classifications": list(classifications)})