Feeder API v3 routes + v2 node-upsert field aliases

[pskillen]

Summary

Support older meshtastic-bot releases still posting legacy field names on node upsert, and introduce a strict feeder API v3 URL namespace for new bot installs.

Related: pskillen/meshflow-bot#110 (startup store_node 400s when meshtastic_* fields were missing server-side). Bot fix in pskillen/meshflow-bot#111; this ticket covers meshflow-api only.

Problem

NodeSerializer on POST /api/packets/{meshtastic_node_id}/nodes/ only maps nested position / device_metrics using meshtastic_location_source, meshtastic_channel_utilization, and meshtastic_air_util_tx. Older bots send location_source, channel_utilization, and air_util_tx, which become null and fail validation (This field may not be null).

Wild bots use STORAGE_API_VERSION=2 and the existing /api/packets/... paths — they cannot be forced to upgrade immediately.

Versioning model

Client STORAGE_API_VERSION	URL prefix	Node upsert wire
2 (deployed bots)	/api/packets/{nodenum}/... (unchanged)	Legacy unprefixed fields and meshtastic_*
3 (new installs, after bot PR)	/api/v3/packets/{nodenum}/...	meshtastic_* only (OpenAPI ObservedNodeUpdate)

API work

v2 backward compatibility (existing /api/packets/... routes)

• In Meshflow/packets/serializers.py NodeSerializer.to_internal_value, alias:
  • location_source → meshtastic_location_source
  • channel_utilization → meshtastic_channel_utilization
  • air_util_tx → meshtastic_air_util_tx
• Default nulls: location source → UNSET (convert_location_source); utilization → 0.0
• Optional: heading required=False, allow_null=True on feeder position nested serializer

v3 routes (strict contract)

• Add path("v3/packets/", include("packets.urls")) in Meshflow/urls.py
• Mirror ingest, nodes, bot-version under /api/v3/packets/{id}/...
• Strict serializer (no legacy aliases; clear 400 if legacy-only payload)

Tests & docs

• Unit tests in Meshflow/packets/tests/test_packet_serializers.py for v2 legacy wire and v3 strict wire + URL routing
• Update openapi.yaml (v3 paths; document legacy fields on v2 upsert)
• Update docs/features/meshcore/phase-2-outstanding.md (feeder upsert gap)

Git workflow

• Branch from origin/main: api-{N}/paddy/feeder-v3-node-upsert (use this issue number once filed)
• Conventional commits; pre-commit: black, isort, flake8 in Meshflow/
• PR closes this issue; deploy before meshflow-bot defaults STORAGE_API_VERSION=3 (bot work stays on bot-110 branch / PR feat(nodes): add traceroute-links endpoint for node-centric link data #111)

Deploy order

1. Merge & deploy meshflow-api (v2 aliases fix wild bots immediately on current URLs)
2. Merge meshflow-bot PR feat(nodes): add traceroute-links endpoint for node-centric link data #111 (includes v3 client paths + meshtastic_* serializer)