cosmo/backend/app/services/firmware_service.py

180 lines
6.0 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

"""
Firmware package service - OTA storage and version comparison
Files live in backend/upload/firmware/ (mounted at /upload/) and are treated as
immutable: nginx caches /upload/ for a year, so a release must never overwrite an
existing path. Re-releasing the same version means deleting the row first.
"""
import hashlib
import logging
import re
from pathlib import Path
from typing import List, Optional, Tuple
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from app.models.db import FirmwareVersion, TerminalDevice
logger = logging.getLogger(__name__)
# Same directory app/main.py mounts at /upload
UPLOAD_ROOT = Path(__file__).resolve().parents[2] / "upload"
FIRMWARE_SUBDIR = "firmware"
# Versions may only carry characters that are safe inside a URL path segment
_VERSION_RE = re.compile(r"^[0-9A-Za-z][0-9A-Za-z.\-_]{0,31}$")
# esp_image_header_t magic: catches a gzipped or text file uploaded by mistake
_IMAGE_MAGIC = 0xE9
class FirmwareError(Exception):
"""Raised for anything the admin did wrong; mapped to 4xx by the route."""
def parse_version(text: Optional[str]) -> Tuple[int, int, int]:
"""'1.2.0-rc1' -> (1, 2, 0). Unparsable input sorts lowest, so a device that
cannot tell us its version is always offered the latest package."""
nums = [int(p) for p in re.findall(r"\d+", text or "")][:3]
while len(nums) < 3:
nums.append(0)
return tuple(nums)
def needs_update(candidate: str, current: Optional[str]) -> bool:
"""The enabled release *is* the version terminals should run, so any difference
is an update - including a rollback, which is how an admin takes a bad image
back without reflashing by hand. Compare the parsed numbers, not the strings,
so a local build suffix ("1.2.1-dirty") is still the same release."""
if not current:
return True
return parse_version(candidate) != parse_version(current)
def package_file(board: str, version: str) -> Path:
return UPLOAD_ROOT / FIRMWARE_SUBDIR / f"{board}-{version}.bin"
def public_path(board: str, version: str) -> str:
"""Path relative to the upload root, i.e. what /upload/ serves."""
return f"{FIRMWARE_SUBDIR}/{board}-{version}.bin"
async def enabled_release(db: AsyncSession, board: str) -> Optional[FirmwareVersion]:
"""The image terminals of this board should be running: the highest of the
enabled packages. Disabling the newest one is therefore also the rollback
lever - devices move back down to what is still enabled."""
rows = (
await db.execute(
select(FirmwareVersion).where(
FirmwareVersion.board == board,
FirmwareVersion.enabled.is_(True),
)
)
).scalars().all()
if not rows:
return None
return max(rows, key=lambda row: parse_version(row.version))
async def record_report(
db: AsyncSession,
device: TerminalDevice,
board: Optional[str],
version: Optional[str],
) -> bool:
"""Remember what the terminal reports it runs. True when the row actually changed."""
changed = False
if board and device.board != board:
device.board = board
changed = True
if version and device.firmware_version != version:
device.firmware_version = version
changed = True
return changed
async def store_package(
db: AsyncSession,
*,
board: str,
version: str,
notes: Optional[str],
source,
) -> FirmwareVersion:
"""Persist an uploaded image and register it. `source` is an UploadFile."""
if not _VERSION_RE.match(version or ""):
raise FirmwareError("版本号只能包含字母数字和 . - _,长度 1-32")
exists = (
await db.execute(
select(FirmwareVersion).where(
FirmwareVersion.board == board, FirmwareVersion.version == version
)
)
).scalar_one_or_none()
if exists is not None:
raise FirmwareError(f"{board} {version} 已存在,请先删除旧记录(同名文件不允许覆盖)")
target = package_file(board, version)
if target.exists():
raise FirmwareError(f"文件已存在:{target.name},版本号必须换新")
target.parent.mkdir(parents=True, exist_ok=True)
digest = hashlib.sha256()
size = 0
first = True
tmp = target.with_suffix(".bin.part")
try:
with tmp.open("wb") as fh:
while True:
chunk = await source.read(1 << 20)
if not chunk:
break
if first:
if not chunk or chunk[0] != _IMAGE_MAGIC:
raise FirmwareError(
"文件不是 ESP32 app 镜像(首字节应为 0xE9),请上传编译产物的 .app.bin"
)
first = False
fh.write(chunk)
digest.update(chunk)
size += len(chunk)
if size == 0:
raise FirmwareError("上传的文件是空的")
tmp.rename(target)
except Exception:
tmp.unlink(missing_ok=True)
raise
row = FirmwareVersion(
version=version,
board=board,
file_path=public_path(board, version),
file_size=size,
sha256=digest.hexdigest(),
notes=notes,
enabled=True,
)
db.add(row)
await db.flush()
logger.info("firmware stored: %s %s (%d bytes)", board, version, size)
return row
async def list_packages(db: AsyncSession) -> List[FirmwareVersion]:
rows = (await db.execute(select(FirmwareVersion))).scalars().all()
return sorted(rows, key=lambda r: (r.board, parse_version(r.version)), reverse=True)
async def get_package(db: AsyncSession, pkg_id: int) -> Optional[FirmwareVersion]:
return await db.get(FirmwareVersion, pkg_id)
def delete_file(row: FirmwareVersion) -> None:
"""Remove the image from disk; the caller deletes the row."""
path = UPLOAD_ROOT / row.file_path
if path.exists():
path.unlink()
logger.info("firmware file deleted: %s", path)