180 lines
6.0 KiB
Python
180 lines
6.0 KiB
Python
"""
|
||
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)
|