Feature/asyncapi websocket spec

[BrandonTrigueros]

AsyncAPI WebSocket Specification + Consumer Implementation (TripConsumer + RouteConsumer)

Summary

This PR delivers the complete WebSocket real-time system for SIMOVI Infobus, from specification to production-ready implementation. It includes the AsyncAPI 3.0 specification with production features, full TripConsumer and RouteConsumer implementations with comprehensive tests, and automated demo systems with interactive Leaflet maps.

Phases Completed

Phase 1: AsyncAPI 3.0 Specification (Production Features)

Enhanced specification with:

• /ws prefix for all WebSocket URLs
• Error handling system (codes 4000, 4004, 4500) with connection closure
• Application-level heartbeat/keep-alive mechanism (optional)
• RouteVehicles scalability strategy (<50 vehicles per route)
• 100% AsyncAPI 3.0 compliance (0 validation errors)

Phase 2a: GTFS Serializers (TURNO 1)

Complete serialization layer with:

• serialize_trip_update() - TripUpdate → JSON payload
• serialize_vehicle_position() - VehiclePosition → JSON payload
• serialize_stop_time_update() - StopTimeUpdate → JSON payload
• serialize_route_vehicles() - Array of vehicles by route
• 18 comprehensive tests (100% passing)

Phase 2b: TripConsumer Backend Implementation (TURNO 2)

Complete Django Channels WebSocket consumer with:

• AsyncWebsocketConsumer with connect/disconnect/broadcast handlers
• Query parameters: include_stops, include_shape
• Payload type field for JavaScript event routing
• 6 comprehensive tests (100% passing, integration with channel layer)
• Demo system with Django views and interactive HTML

Phase 3: RouteConsumer Implementation (TURNO 3)

Complete route-level WebSocket consumer with:

• RouteConsumer (311 lines) - Track all vehicles on a route
• Dual URL patterns:
  • ws://host/ws/route/{route_id}/ - All directions
  • ws://host/ws/route/{route_id}/direction/{direction_id}/ - Filtered by direction (0 or 1)
• Direction filtering - Clients subscribe to specific traffic directions
• Snapshot strategy - Initial vehicle array on connection
• 9 comprehensive tests (100% passing)
• Interactive Leaflet map demo - Real-time vehicle tracking with markers
• ASGI routing fix - Combine feed + websocket URL patterns

Fase 4: Production Fixes (TURNO 4 + 5)

Sanitización de NaN/Infinity en JSON antes de enviar por WebSocket
Corrección de errores críticos en frontend por datos inválidos
Validación en Docker y verificación de funcionamiento en producción

Key Changes

1. AsyncAPI Specification Updates

URL Structure:

channels:
  /ws/trip/{trip_id}:
    address: /ws/trip/{trip_id}
  /ws/route/{route_id}:
    address: /ws/route/{route_id}
  /ws/route/{route_id}/direction/{direction_id}:
    address: /ws/route/{route_id}/direction/{direction_id}

AsyncAPI Spec: URLs, errores, heartbeat, y estructura de canales.
TripConsumer: Manejo de parámetros, errores, y snapshots iniciales.
RouteConsumer: Filtrado por dirección, snapshots, y manejo robusto de datos GTFS-RT.
Serializers: Funciones para serializar TripUpdate, VehiclePosition, StopTimeUpdate y arrays de vehículos.
Demo Systems: Mapas interactivos, comandos automáticos, y scripts de verificación.
Infraestructura: Fix en ASGI routing para múltiples apps.

Error Handling:

Code	Type	Behavior
4000	Bad Request	Invalid params → close
4001	Not Found (Trip)	Trip missing → close
4004	Not Found (Route)	Route missing → close
4500	Server Error	Internal failure → close

Heartbeat (Optional):

{"type": "heartbeat", "action": "ping", "timestamp": "..."}

2. TripConsumer Implementation (websocket/consumers/trip.py)

class TripConsumer(AsyncWebsocketConsumer):
    async def connect(self):
        # Validate trip exists, parse params, send initial snapshot
        
    async def trip_update(self, event):
        # Receive broadcast from Celery, serialize, send to client

Features:

• Query params: ?include_stops=true&include_shape=false
• Error codes: 4001 (not found), 4002 (invalid params), 5001 (server error)
• Initial snapshot on connection
• Broadcast integration via channel layer

3. RouteConsumer Implementation (websocket/consumers/route.py)

class RouteConsumer(AsyncWebsocketConsumer):
    async def connect(self):
        # Validate route exists, parse direction, send vehicle snapshot
        
    async def route_update(self, event):
        # Receive broadcast, filter by direction, send to clients

Features:

• Direction filtering: Optional direction_id parameter (0 or 1)
• Dual subscriptions: Clients can subscribe to all vehicles or filtered by direction
• Snapshot array: Initial state with all active vehicles on route
• Manual serialization: Avoids async/sync issues with Django ORM
• Channel groups:
  • route_{route_id} - All vehicles on route
  • route_{route_id}_dir_{direction_id} - Vehicles filtered by direction

Data Structure:

{
  "type": "route.snapshot",
  "route_id": "DEMO_ROUTE_001",
  "direction_id": null,
  "vehicles": [
    {
      "vehicle_id": "BUS-001",
      "latitude": 9.9342,
      "longitude": -84.0873,
      "bearing": 45.0,
      "speed": 35.5,
      "direction_id": 0,
      "timestamp": "2026-01-24T..."
    }
  ],
  "timestamp": "2026-01-24T..."
}

4. GTFS Serializers (websocket/serializers/gtfs.py)

def serialize_trip_update(trip_update, include_stops=True) -> Dict:
    # Returns TripUpdatePayload following AsyncAPI schema
    
def serialize_vehicle_position(vehicle_pos) -> Dict:
    # Returns VehiclePositionPayload following AsyncAPI schema

5. Demo Systems

Trip Demo (/websocket/demo/trip/)

• Django view with auto-connect
• Live message log with snapshots and updates
• Auto-detects WebSocket URL (WSL2 compatible)
• Management commands: demo_trip_data, test_broadcast --type trip

Route Demo (/websocket/demo/route/)

• Interactive Leaflet map with real-time vehicle markers
• Direction toggle: Filter by direction (All, 0, 1)
• Color-coded markers: Blue (direction 0), Green (direction 1)
• Vehicle popups: Click marker for details
• Live vehicle list: Side panel with real-time updates
• Management commands: demo_route_data, test_broadcast --type route

Automated Scripts

• run_trip_demo.sh - One-command trip demo setup
• run_route_demo.sh - One-command route demo setup (with background broadcasts)
• clean_docker.sh - Complete Docker teardown

AsyncAPI Validation

✓ File is valid! 0 errors, 0 warnings
✓ 815 lines (from 665)
✓ 9 schemas (added ErrorPayload, HeartbeatPayload)
✓ 6 messages (added Error, Heartbeat)
✓ 3 channels (trip, route, route+direction)

Impact

For Developers:

• One-command demos: ./scripts/run_trip_demo.sh and ./scripts/run_route_demo.sh
• Clear error codes and handling patterns
• Comprehensive tests demonstrate usage
• Consistent naming conventions (trip vs route)

For Frontend:

• Auto-detecting WebSocket URLs (no hardcoded IPs)
• Type-based message routing (trip.snapshot, trip.update, route.snapshot, route.update)
• Live examples:
  • Trip: http://localhost:8000/websocket/demo/trip/
  • Route: http://localhost:8000/websocket/demo/route/
• Interactive map with Leaflet.js for visualization

For Production:

• Scalable channel layer integration
• Proper error handling with connection closure
• Direction filtering reduces unnecessary data transmission
• Background broadcast simulation ready for Celery integration

Next Steps

Future Enhancements:

• Optional heartbeat implementation
• Rate limiting and authentication
• Performance optimization for 100+ vehicles
• Multi-route subscriptions

References

• AsyncAPI 3.0 Spec
• Django Channels Docs
• GTFS-Realtime Reference
• Leaflet.js Documentation

Checklist

Phase 1: Specification

• ✅ AsyncAPI validates with CLI
• ✅ All channel references correct
• ✅ Error codes documented
• ✅ Heartbeat mechanism explained

Phase 2a: Serializers (TURNO 1)

• ✅ 4 GTFS serializer functions
• ✅ Following AsyncAPI schema exactly
• ✅ 18 comprehensive tests passing
• ✅ Type hints and docstrings

Phase 2b: TripConsumer (TURNO 2)

• ✅ TripConsumer with async handlers
• ✅ Query parameter parsing
• ✅ Error handling with closure codes
• ✅ Channel layer broadcast integration
• ✅ 6 comprehensive tests passing
• ✅ Demo system with Django views

Phase 3: RouteConsumer (TURNO 3)

• ✅ RouteConsumer with async handlers
• ✅ Dual URL patterns (with/without direction)
• ✅ Direction filtering logic
• ✅ Snapshot strategy with vehicle array
• ✅ Manual payload building (avoid async/sync issues)
• ✅ 9 comprehensive tests passing
• ✅ Interactive Leaflet map demo
• ✅ ASGI routing fix (combine multiple apps)
• ✅ Naming consistency refactor

Phase 4: Verification

• ✅ Fresh Docker build tested
• ✅ WebSocket connects successfully (both consumers)
• ✅ Real-time updates working
• ✅ Auto-connect and auto-detection
• ✅ All tests passing (33/33)
• ✅ Leaflet map visualization functional
• ✅ Direction filtering operational

---