tescmd 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

tescmd/telemetry/protos/vehicle_error.proto

@@ -0,0 +1,23 @@
+syntax = "proto3";
+
+package telemetry.vehicle_error;
+
+import "google/protobuf/timestamp.proto";
+
+option go_package = "github.com/teslamotors/fleet-telemetry/protos";
+
+
+// VehicleErrors is a collection of errors for a single vehicle.
+message VehicleErrors {
+  repeated VehicleError errors = 1;
+  google.protobuf.Timestamp created_at = 2;
+  string vin = 3;
+}
+
+// VehicleError is a single error
+message VehicleError {
+  google.protobuf.Timestamp created_at = 1;
+  string name = 2;
+  map<string, string> tags = 3;
+  string body = 4;
+}

tescmd/telemetry/protos/vehicle_error_pb2.py

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: vehicle_error.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'vehicle_error.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from google.protobuf import timestamp_pb2 as google_dot_protobuf_dot_timestamp__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x13vehicle_error.proto\x12\x17telemetry.vehicle_error\x1a\x1fgoogle/protobuf/timestamp.proto\"\x83\x01\n\rVehicleErrors\x12\x35\n\x06\x65rrors\x18\x01 \x03(\x0b\x32%.telemetry.vehicle_error.VehicleError\x12.\n\ncreated_at\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12\x0b\n\x03vin\x18\x03 \x01(\t\"\xc6\x01\n\x0cVehicleError\x12.\n\ncreated_at\x18\x01 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12\x0c\n\x04name\x18\x02 \x01(\t\x12=\n\x04tags\x18\x03 \x03(\x0b\x32/.telemetry.vehicle_error.VehicleError.TagsEntry\x12\x0c\n\x04\x62ody\x18\x04 \x01(\t\x1a+\n\tTagsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\x42/Z-github.com/teslamotors/fleet-telemetry/protosb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'vehicle_error_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'Z-github.com/teslamotors/fleet-telemetry/protos'
+  _globals['_VEHICLEERROR_TAGSENTRY']._loaded_options = None
+  _globals['_VEHICLEERROR_TAGSENTRY']._serialized_options = b'8\001'
+  _globals['_VEHICLEERRORS']._serialized_start=82
+  _globals['_VEHICLEERRORS']._serialized_end=213
+  _globals['_VEHICLEERROR']._serialized_start=216
+  _globals['_VEHICLEERROR']._serialized_end=414
+  _globals['_VEHICLEERROR_TAGSENTRY']._serialized_start=371
+  _globals['_VEHICLEERROR_TAGSENTRY']._serialized_end=414
+# @@protoc_insertion_point(module_scope)

tescmd/telemetry/protos/vehicle_error_pb2.pyi

@@ -0,0 +1,39 @@
+import datetime
+
+from google.protobuf import timestamp_pb2 as _timestamp_pb2
+from google.protobuf.internal import containers as _containers
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from collections.abc import Iterable as _Iterable, Mapping as _Mapping
+from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class VehicleErrors(_message.Message):
+    __slots__ = ("errors", "created_at", "vin")
+    ERRORS_FIELD_NUMBER: _ClassVar[int]
+    CREATED_AT_FIELD_NUMBER: _ClassVar[int]
+    VIN_FIELD_NUMBER: _ClassVar[int]
+    errors: _containers.RepeatedCompositeFieldContainer[VehicleError]
+    created_at: _timestamp_pb2.Timestamp
+    vin: str
+    def __init__(self, errors: _Optional[_Iterable[_Union[VehicleError, _Mapping]]] = ..., created_at: _Optional[_Union[datetime.datetime, _timestamp_pb2.Timestamp, _Mapping]] = ..., vin: _Optional[str] = ...) -> None: ...
+
+class VehicleError(_message.Message):
+    __slots__ = ("created_at", "name", "tags", "body")
+    class TagsEntry(_message.Message):
+        __slots__ = ("key", "value")
+        KEY_FIELD_NUMBER: _ClassVar[int]
+        VALUE_FIELD_NUMBER: _ClassVar[int]
+        key: str
+        value: str
+        def __init__(self, key: _Optional[str] = ..., value: _Optional[str] = ...) -> None: ...
+    CREATED_AT_FIELD_NUMBER: _ClassVar[int]
+    NAME_FIELD_NUMBER: _ClassVar[int]
+    TAGS_FIELD_NUMBER: _ClassVar[int]
+    BODY_FIELD_NUMBER: _ClassVar[int]
+    created_at: _timestamp_pb2.Timestamp
+    name: str
+    tags: _containers.ScalarMap[str, str]
+    body: str
+    def __init__(self, created_at: _Optional[_Union[datetime.datetime, _timestamp_pb2.Timestamp, _Mapping]] = ..., name: _Optional[str] = ..., tags: _Optional[_Mapping[str, str]] = ..., body: _Optional[str] = ...) -> None: ...

tescmd/telemetry/protos/vehicle_metric.proto

@@ -0,0 +1,22 @@
+syntax = "proto3";
+
+package telemetry.vehicle_metrics;
+
+import "google/protobuf/timestamp.proto";
+
+option go_package = "github.com/teslamotors/fleet-telemetry/protos";
+
+
+// VehicleMetrics is a collection of metrics for a single vehicle.
+message VehicleMetrics {
+  repeated Metric metrics = 1;
+  google.protobuf.Timestamp created_at = 2;
+  string vin = 3;
+}
+
+// Metric is a single metric value with a name, tags, and a value.
+message Metric {
+  string name = 1;
+  map<string, string> tags = 2;
+  double value = 3;
+}

tescmd/telemetry/protos/vehicle_metric_pb2.py

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: vehicle_metric.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'vehicle_metric.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from google.protobuf import timestamp_pb2 as google_dot_protobuf_dot_timestamp__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x14vehicle_metric.proto\x12\x19telemetry.vehicle_metrics\x1a\x1fgoogle/protobuf/timestamp.proto\"\x81\x01\n\x0eVehicleMetrics\x12\x32\n\x07metrics\x18\x01 \x03(\x0b\x32!.telemetry.vehicle_metrics.Metric\x12.\n\ncreated_at\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12\x0b\n\x03vin\x18\x03 \x01(\t\"\x8d\x01\n\x06Metric\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x39\n\x04tags\x18\x02 \x03(\x0b\x32+.telemetry.vehicle_metrics.Metric.TagsEntry\x12\r\n\x05value\x18\x03 \x01(\x01\x1a+\n\tTagsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\x42/Z-github.com/teslamotors/fleet-telemetry/protosb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'vehicle_metric_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'Z-github.com/teslamotors/fleet-telemetry/protos'
+  _globals['_METRIC_TAGSENTRY']._loaded_options = None
+  _globals['_METRIC_TAGSENTRY']._serialized_options = b'8\001'
+  _globals['_VEHICLEMETRICS']._serialized_start=85
+  _globals['_VEHICLEMETRICS']._serialized_end=214
+  _globals['_METRIC']._serialized_start=217
+  _globals['_METRIC']._serialized_end=358
+  _globals['_METRIC_TAGSENTRY']._serialized_start=315
+  _globals['_METRIC_TAGSENTRY']._serialized_end=358
+# @@protoc_insertion_point(module_scope)

tescmd/telemetry/protos/vehicle_metric_pb2.pyi

@@ -0,0 +1,37 @@
+import datetime
+
+from google.protobuf import timestamp_pb2 as _timestamp_pb2
+from google.protobuf.internal import containers as _containers
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from collections.abc import Iterable as _Iterable, Mapping as _Mapping
+from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class VehicleMetrics(_message.Message):
+    __slots__ = ("metrics", "created_at", "vin")
+    METRICS_FIELD_NUMBER: _ClassVar[int]
+    CREATED_AT_FIELD_NUMBER: _ClassVar[int]
+    VIN_FIELD_NUMBER: _ClassVar[int]
+    metrics: _containers.RepeatedCompositeFieldContainer[Metric]
+    created_at: _timestamp_pb2.Timestamp
+    vin: str
+    def __init__(self, metrics: _Optional[_Iterable[_Union[Metric, _Mapping]]] = ..., created_at: _Optional[_Union[datetime.datetime, _timestamp_pb2.Timestamp, _Mapping]] = ..., vin: _Optional[str] = ...) -> None: ...
+
+class Metric(_message.Message):
+    __slots__ = ("name", "tags", "value")
+    class TagsEntry(_message.Message):
+        __slots__ = ("key", "value")
+        KEY_FIELD_NUMBER: _ClassVar[int]
+        VALUE_FIELD_NUMBER: _ClassVar[int]
+        key: str
+        value: str
+        def __init__(self, key: _Optional[str] = ..., value: _Optional[str] = ...) -> None: ...
+    NAME_FIELD_NUMBER: _ClassVar[int]
+    TAGS_FIELD_NUMBER: _ClassVar[int]
+    VALUE_FIELD_NUMBER: _ClassVar[int]
+    name: str
+    tags: _containers.ScalarMap[str, str]
+    value: float
+    def __init__(self, name: _Optional[str] = ..., tags: _Optional[_Mapping[str, str]] = ..., value: _Optional[float] = ...) -> None: ...

tescmd/telemetry/server.py

@@ -0,0 +1,293 @@
+"""Async WebSocket server for receiving Fleet Telemetry pushes.
+
+Listens on all interfaces so Tailscale Funnel (which terminates TLS) can
+proxy to the local plain-WebSocket port.
+
+A lightweight TCP mux sits in front of the WebSocket server to handle
+plain HTTP requests (HEAD, GET) that the ``websockets`` library rejects.
+This is required because Tesla's Developer Portal sends HEAD requests to
+validate Allowed Origin URLs, and browsers send GET requests for health
+checks.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    import websockets.asyncio.server as ws_server
+
+    from tescmd.telemetry.decoder import TelemetryDecoder, TelemetryFrame
+
+logger = logging.getLogger(__name__)
+
+_HTTP_200 = (
+    b"HTTP/1.1 200 OK\r\n"
+    b"Content-Type: text/plain\r\n"
+    b"Content-Length: 24\r\n"
+    b"\r\n"
+    b"tescmd telemetry server\n"
+)
+
+_HTTP_200_HEAD = b"HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nContent-Length: 0\r\n\r\n"
+
+_WELL_KNOWN_PATH = "/.well-known/appspecific/com.tesla.3p.public-key.pem"
+
+
+class TelemetryServer:
+    """Async WebSocket server that receives telemetry from vehicles.
+
+    Internally runs two servers:
+
+    * A **TCP mux** on ``0.0.0.0:{port}`` (the public-facing port that
+      the tunnel proxy connects to).  It inspects the first HTTP request
+      line and either responds directly (HEAD / plain GET) or forwards
+      the connection to the internal WebSocket server.
+    * A **websockets** server on ``127.0.0.1:{port+1}`` that handles
+      actual WebSocket upgrade connections from vehicles.
+    """
+
+    def __init__(
+        self,
+        port: int,
+        decoder: TelemetryDecoder,
+        on_frame: Callable[[TelemetryFrame], Awaitable[None]],
+        *,
+        public_key_pem: str | None = None,
+    ) -> None:
+        self._port = port
+        self._ws_port = port + 1
+        self._decoder = decoder
+        self._on_frame = on_frame
+        self._public_key_pem = public_key_pem
+        self._ws_server: ws_server.Server | None = None
+        self._mux_server: asyncio.Server | None = None
+        self._active_ws: set[Any] = set()
+        self._connection_count = 0
+        self._frame_count = 0
+
+    async def start(self) -> None:
+        """Start the mux + WebSocket servers."""
+        try:
+            import websockets.asyncio.server as ws_server_mod
+        except ImportError as exc:
+            from tescmd.api.errors import ConfigError
+
+            raise ConfigError(
+                "websockets is required for telemetry streaming. "
+                "Install with: pip install tescmd[telemetry]"
+            ) from exc
+
+        # Internal WS server — only reachable from localhost
+        self._ws_server = await ws_server_mod.serve(
+            self._ws_handler,
+            host="127.0.0.1",
+            port=self._ws_port,
+        )
+
+        # Public-facing TCP mux — bind to all interfaces (IPv4 + IPv6).
+        self._mux_server = await asyncio.start_server(
+            self._mux_handler,
+            host=None,
+            port=self._port,
+        )
+
+        logger.info(
+            "Telemetry server listening on 0.0.0.0:%d (ws internal :%d)",
+            self._port,
+            self._ws_port,
+        )
+
+    async def stop(self) -> None:
+        """Gracefully shut down both servers and active connections."""
+        # Close active WebSocket connections first
+        for ws in list(self._active_ws):
+            with contextlib.suppress(Exception):
+                await ws.close()
+        self._active_ws.clear()
+
+        if self._mux_server is not None:
+            self._mux_server.close()
+            await self._mux_server.wait_closed()
+            self._mux_server = None
+
+        if self._ws_server is not None:
+            self._ws_server.close()
+            await self._ws_server.wait_closed()
+            self._ws_server = None
+
+        logger.info("Telemetry server stopped")
+
+    # ------------------------------------------------------------------
+    # TCP mux — inspects first request line, routes accordingly
+    # ------------------------------------------------------------------
+
+    async def _mux_handler(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+    ) -> None:
+        """Route an incoming TCP connection.
+
+        * **HEAD** — immediate HTTP 200 (Tesla origin validation).
+        * **GET without Upgrade** — immediate HTTP 200 (health check).
+        * **GET with Upgrade: websocket** — forward to internal WS server.
+        """
+        try:
+            first_line = await asyncio.wait_for(reader.readline(), timeout=10)
+        except (TimeoutError, ConnectionError):
+            writer.close()
+            return
+
+        if not first_line:
+            writer.close()
+            return
+
+        parts = first_line.decode("latin-1").strip().split(" ", 2)
+        method = parts[0].upper() if parts else ""
+        path = parts[1] if len(parts) > 1 else "/"
+
+        if method == "HEAD":
+            if path == _WELL_KNOWN_PATH and self._public_key_pem is not None:
+                pem_bytes = self._public_key_pem.encode()
+                writer.write(
+                    f"HTTP/1.1 200 OK\r\n"
+                    f"Content-Type: application/x-pem-file\r\n"
+                    f"Content-Length: {len(pem_bytes)}\r\n"
+                    f"\r\n".encode()
+                )
+            else:
+                writer.write(_HTTP_200_HEAD)
+            await writer.drain()
+            writer.close()
+            return
+
+        if method != "GET":
+            writer.write(_HTTP_200)
+            await writer.drain()
+            writer.close()
+            return
+
+        # Read remaining headers to check for WebSocket upgrade
+        raw_headers: list[bytes] = []
+        is_upgrade = False
+        try:
+            while True:
+                line = await asyncio.wait_for(reader.readline(), timeout=5)
+                raw_headers.append(line)
+                if line in (b"\r\n", b"\n", b""):
+                    break
+                if line.lower().startswith(b"upgrade:") and b"websocket" in line.lower():
+                    is_upgrade = True
+        except (TimeoutError, ConnectionError):
+            writer.close()
+            return
+
+        if not is_upgrade:
+            if path == _WELL_KNOWN_PATH and self._public_key_pem is not None:
+                pem_bytes = self._public_key_pem.encode()
+                writer.write(
+                    f"HTTP/1.1 200 OK\r\n"
+                    f"Content-Type: application/x-pem-file\r\n"
+                    f"Content-Length: {len(pem_bytes)}\r\n"
+                    f"\r\n".encode()
+                    + pem_bytes
+                )
+            else:
+                writer.write(_HTTP_200)
+            await writer.drain()
+            writer.close()
+            return
+
+        # WebSocket upgrade — forward entire connection to internal WS server
+        try:
+            ws_reader, ws_writer = await asyncio.open_connection("127.0.0.1", self._ws_port)
+        except ConnectionError:
+            writer.close()
+            return
+
+        # Replay the already-read request line + headers
+        ws_writer.write(first_line)
+        for hdr in raw_headers:
+            ws_writer.write(hdr)
+        await ws_writer.drain()
+
+        # Bidirectional pipe until either side closes
+        await asyncio.gather(
+            self._pipe(reader, ws_writer),
+            self._pipe(ws_reader, writer),
+        )
+
+    @staticmethod
+    async def _pipe(
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+    ) -> None:
+        """Copy bytes from *reader* to *writer* until EOF."""
+        try:
+            while True:
+                data = await reader.read(65536)
+                if not data:
+                    break
+                writer.write(data)
+                await writer.drain()
+        except (ConnectionError, asyncio.CancelledError):
+            pass
+        finally:
+            with contextlib.suppress(Exception):
+                writer.close()
+
+    # ------------------------------------------------------------------
+    # WebSocket handler
+    # ------------------------------------------------------------------
+
+    async def _ws_handler(self, websocket: Any) -> None:
+        """Handle a single vehicle WebSocket connection.
+
+        Receives binary frames, decodes via :class:`TelemetryDecoder`,
+        and dispatches to the ``on_frame`` callback.  Malformed frames
+        are logged and skipped — never crash the server.
+        """
+        self._connection_count += 1
+        self._active_ws.add(websocket)
+        remote = getattr(websocket, "remote_address", ("unknown", 0))
+        logger.info("Vehicle connected: %s (total: %d)", remote, self._connection_count)
+
+        try:
+            async for message in websocket:
+                if isinstance(message, str):
+                    # Tesla sends binary protobuf, but handle text gracefully
+                    logger.debug("Received text frame (unexpected): %s", message[:200])
+                    continue
+
+                try:
+                    frame = self._decoder.decode(message)
+                    self._frame_count += 1
+                    await self._on_frame(frame)
+                except Exception:
+                    logger.warning(
+                        "Failed to decode telemetry frame (%d bytes)",
+                        len(message),
+                        exc_info=True,
+                    )
+        except Exception:
+            logger.debug("Connection closed: %s", remote, exc_info=True)
+        finally:
+            self._active_ws.discard(websocket)
+            self._connection_count -= 1
+            logger.info("Vehicle disconnected: %s (remaining: %d)", remote, self._connection_count)
+
+    @property
+    def connection_count(self) -> int:
+        """Number of currently active WebSocket connections."""
+        return self._connection_count
+
+    @property
+    def frame_count(self) -> int:
+        """Total number of telemetry frames decoded since server start."""
+        return self._frame_count