Files
cbb-refresh-verify-795/src/cbb_refresh_verify/management.py
T

402 lines
20 KiB
Python

"""Checkpointed CBB mutations with native evidence and no automatic replay."""
from dataclasses import asdict, dataclass, field, replace
from datetime import datetime, timezone
import json
from pathlib import Path, PureWindowsPath
import re
from uuid import uuid4
from .library_lock import LibraryLock, LibraryBusy
from .scoped_manifest import (ManifestScope, build_manifest, build_exclusive_library_manifest,
copy_verified, hash_file, scan_tree)
@dataclass(frozen=True)
class Capability:
supported: bool
reason: str
@dataclass(frozen=True)
class ManagementRequest:
operation: str
library: Path
name: str
partition: str = 'Logical-Physical'
source: Path | None = None
auto_verify: bool = True
evidence_dir: Path = Path('management-evidence')
top_level_block: str = ''
timeout_seconds: float = 180
mapped_drive: str = ''
mapped_remote_root: str = ''
transaction_token: str = ''
check_previous_release: bool = False
@dataclass(frozen=True)
class CatalogEntry:
name: str
partition: str
engineering_identity: dict = field(default_factory=dict)
@dataclass(frozen=True)
class Catalog:
library: Path
flow: int
entries: tuple[CatalogEntry, ...]
safe_to_continue: bool = True
@dataclass(frozen=True)
class NativeOutcome:
success: bool
safe_to_continue: bool
detail: str
identity_matches: bool | None = None
evidence_path: Path | None = None
identity_proof: dict | None = None
@dataclass(frozen=True)
class ManagementResult:
operation: str
library: Path
name: str
partition: str
source: Path | None
auto_verify: bool
stage: str
status: str
safe_to_continue: bool
detail: str = ''
evidence_path: Path | None = None
release_proof: dict | None = None
def validate_name(value):
if (not value or value != value.strip() or value.endswith('.') or value in ('.', '..')
or any(ord(c) < 32 or c in '<>:"/\\|?*' for c in value)
or value.split('.')[0].upper() in {'CON', 'PRN', 'AUX', 'NUL',
*(f'COM{i}' for i in range(1, 10)), *(f'LPT{i}' for i in range(1, 10))}):
raise ValueError('CBB 名称/分区不是有效单一名称,禁止路径、控制字符或保留名称。')
def source_project(source, top_level_block=''):
"""Require complete PRJ/PCB and self-contained engineering references."""
from .backup_recovery import _project_text
source = Path(source).resolve(strict=True)
if source.suffix.casefold() != '.prj' or not source.is_file():
raise ValueError('请选择完整工程的 PRJ 文件。')
scan_tree(source.parent) # Reject reparse points, including file links.
text = _project_text(source)
roots = re.findall(r'^KEY RootBlock "([^"]+)"', text, re.M)
if len(roots) != 1 or top_level_block and roots[0] != top_level_block:
raise ValueError('工程顶层块不唯一或与输入不一致。')
validate_name(roots[0])
def reference(path, key):
values = re.findall(r'^KEY ' + re.escape(key) + r' "([^"]+)"', _project_text(path), re.M)
if len(values) != 1 or PureWindowsPath(values[0]).is_absolute() or PureWindowsPath(values[0]).drive:
raise ValueError(f'{key} 必须为唯一工程内相对引用。')
resolved = (path.parent/values[0]).resolve()
if not resolved.is_relative_to(source.parent):
raise ValueError(f'{key} 越出来源工程。')
return resolved
pcb = reference(source, 'PCBDesignPath')
if not pcb.is_file() or reference(pcb, 'ProjectFile') != source:
raise ValueError('PCB 未引用所选来源工程。')
from .maintenance_entry import maintenance_project_files
for path in maintenance_project_files(source, pcb):
if not path.is_file():
raise ValueError('工程缺少 PCB 工程配置。')
# Healthy Expedition PCB projects can use Layout/LayoutDB.lyt without
# declaring an independent iCDBDir. The schematic DB stays mandatory;
# an explicitly declared PCB DB must still pass every reference check.
if path != source and not re.search(r'^KEY iCDBDir\b', _project_text(path), re.M):
continue
db = reference(path, 'iCDBDir')
if not (db/'icdb.dat').is_file():
raise ValueError('工程缺少原理图/PCB 数据库。')
if not (pcb.parent/'Layout/LayoutDB.lyt').is_file():
raise ValueError('工程缺少布局数据库。')
return source, pcb, roots[0]
def engineering_identity(source):
"""Compare actual registered engineering bytes, not a name-only acknowledgment.
Conservative until native normalization has an independently proven semantic
comparison: changed database bytes cannot be claimed to match the source.
"""
source, pcb, top = source_project(source)
from .backup_recovery import _project_text
db = re.findall(r'^KEY iCDBDir "([^"]+)"', _project_text(source), re.M)[0]
return {'top_level_block': top, 'schematic_sha256': hash_file(source.parent/db/'icdb.dat'),
'layout_sha256': hash_file(pcb.parent/'Layout/LayoutDB.lyt')}
def _write_json(path, value):
path = Path(path)
pending = path.with_suffix('.pending')
with pending.open('w', encoding='utf-8') as stream:
json.dump(value, stream, ensure_ascii=False, default=str, indent=2)
stream.flush()
import os
os.fsync(stream.fileno())
pending.replace(path)
def unfinished_operations(root):
results = []
for path in sorted(Path(root).glob('*/checkpoint.json')):
try:
record = json.loads(path.read_text(encoding='utf-8'))
if (record.get('stage') != 'complete' or record.get('safe_to_continue') is False
or record.get('status') == 'RECOVERY_REQUIRED'):
results.append({**record, 'evidence_path': str(path)})
except (OSError, ValueError):
results.append({'status': 'CHECKPOINT_UNREADABLE', 'evidence_path': str(path)})
return results
def _may_have_mutated(record):
prewrite = {'preflight', 'release_check', 'catalog_before', 'baseline', 'stage_source', 'prepare_identity'}
history = record.get('history')
return (record.get('stage') not in prewrite | {'complete'} or record.get('status') == 'RECOVERY_REQUIRED'
or not isinstance(history, list) or not history
or any(not isinstance(item, dict) or item.get('stage') not in prewrite for item in history))
def run_management(request, *, adapter=None, verifier=None, idle_check=None, progress=None):
from .verify_runner import VerifyRequest, run_verify
from .backup_recovery import _idle_check
import win32con, win32event
import pythoncom
if adapter is None:
from .native_management import NativeManagementAdapter
adapter = NativeManagementAdapter()
verifier = verifier or run_verify
idle_check = idle_check or _idle_check
root = report = None
stage = 'preflight'
history = []
mutated = uploaded = removed = False
owner_safe = True
mutex = None
acquired = False
release_proof = None
def invoke(callback, *args):
nonlocal owner_safe
owner_safe = False
try:
result = callback(*args)
except Exception as error:
owner_safe = getattr(error, 'safe_to_continue', False) is True
raise
owner_safe = result.safe_to_continue
return result
def checkpoint(next_stage, **details):
nonlocal stage
stage = next_stage
history.append({'stage': stage, 'time': datetime.now(timezone.utc).isoformat(), **details})
if report:
_write_json(report, {**asdict(request), 'stage': stage, 'status': 'RUNNING',
'safe_to_continue': False, 'history': history, 'backup_policy': 'manual'})
if progress:
progress({'stage': stage, 'block': request.name, 'operation': request.operation, **details})
def finish(status, detail='', safe=True):
result = ManagementResult(request.operation, request.library, request.name, request.partition,
request.source, request.auto_verify, 'complete', status, safe, detail, report, release_proof)
if report:
try:
_write_json(report, {**asdict(result), 'history': history, 'backup_policy': 'manual'})
except OSError as error:
result = replace(result, detail=f'{detail}\n操作记录写入失败:{error}'.strip())
return result
from .com_runtime import initialize_com, uninitialize_com
initialized = initialize_com()
try:
if request.operation not in ('add', 'update', 'remove'):
raise ValueError('不支持的管理操作。')
validate_name(request.name); validate_name(request.partition)
from .network_path import absolute_preserving_drive
library = absolute_preserving_drive(request.library)
canonical_library = library.resolve(strict=True)
library_root = canonical_library.parent
if library.suffix.casefold() != '.lmc' or not library.is_file():
raise ValueError('中心库必须为现有 LMC 文件。')
evidence = Path(request.evidence_dir).resolve()
if evidence.is_relative_to(library_root) or library_root.is_relative_to(evidence):
raise ValueError('操作记录与暂存目录必须位于目标中心库之外,且不能包含目标库。')
capability = adapter.capabilities().get(request.operation, Capability(False, '未验证的原生接口'))
if not capability.supported:
return finish('UNSUPPORTED', capability.reason)
unfinished_target = None
for unfinished in unfinished_operations(evidence):
if (unfinished.get('library') and Path(unfinished['library']).resolve() == canonical_library
and _may_have_mutated(unfinished) and (not unfinished.get('name')
or str(unfinished['name']).casefold() == request.name.casefold())):
unfinished_target = unfinished
break
source = pcb = None
if request.operation in ('add', 'update'):
if request.source is None:
raise ValueError('新增/更新需要完整来源工程。')
source, pcb, top = source_project(request.source, request.top_level_block)
if (source.parent.is_relative_to(library_root) or library_root.is_relative_to(source.parent)
or evidence.is_relative_to(source.parent)
or source.parent.is_relative_to(evidence)):
raise ValueError('来源工程、目标库与操作证据必须使用独立目录。')
root = evidence/('management-' + uuid4().hex)
root.mkdir(parents=True, exist_ok=False)
report = root/'checkpoint.json'
checkpoint('release_check')
mutex = win32event.CreateMutex(None, False, r'Local\CbbRefreshVerify795')
acquired = win32event.WaitForSingleObject(mutex, 0) in (win32con.WAIT_OBJECT_0, win32con.WAIT_ABANDONED)
if not acquired:
return finish('BLOCKED', '已有 CBB 校验/管理/恢复任务运行;本次未启动。')
from .library_lock import has_blocker, has_retained_library, release_retained_library
if (has_blocker(library) or has_retained_library(library) or request.check_previous_release
or unfinished_target and unfinished_target.get('safe_to_continue') is not True):
release_proof = release_retained_library(library, root/'previous-release')
if unfinished_target:
return finish('BLOCKED', f'存在未完成/需恢复任务,禁止自动重放:{unfinished_target["evidence_path"]}')
if hasattr(adapter, 'bind_library_mapping'):
adapter.bind_library_mapping(request.mapped_drive, request.mapped_remote_root)
with LibraryLock(library, block_name=request.name, safe_to_release=lambda: owner_safe or (
callable(getattr(adapter, 'release_confirmed', None)) and adapter.release_confirmed(library))):
work = library.parent/'ReusableBlocksLP'/request.name/'Work'
target_project, target_pcb = work/(request.name+'.prj'), work/'PCB/pcb.pcb'
if request.operation != 'add':
# Read actual engineering references when available; fallback
# paths still permit removal of catalog entries missing Work.
from .verify_runner import preflight
try:
target_project, target_pcb = preflight(VerifyRequest(library, request.name, root))
except ValueError:
pass
idle_check(library, target_project, target_pcb)
if source:
idle_check(library, source, pcb)
checkpoint('catalog_before')
owner_safe = False
before = invoke(adapter.catalog, library, root/'before')
owner_safe = before.safe_to_continue
if not owner_safe or Path(before.library).resolve() != canonical_library or before.flow != 1:
return finish('BLOCKED', '原生目录身份/流程或所有者释放未确认。仅支持已验证 DxDesigner 流程。', owner_safe)
same_name = [entry for entry in before.entries if entry.name.casefold() == request.name.casefold()]
matches = [entry for entry in same_name if entry.partition == request.partition and entry.name == request.name]
if request.operation == 'add' and same_name:
return finish('UPLOAD_FAILED', '同名 CBB 已存在;新增禁止覆盖,请使用明确的同名更新。')
if request.operation != 'add' and len(matches) != 1:
return finish('BLOCKED', '目标名称和分区必须与原生目录唯一匹配。')
if hasattr(adapter, 'preflight'):
adapter.preflight(request, before)
# Native/project owners must be idle before snapshot or mutation.
idle_check(library, target_project, target_pcb)
scope = ManifestScope.library(request.name, library.name)
checkpoint('baseline')
original = build_exclusive_library_manifest(library_root, scope=scope, progress=progress)
_write_json(root/'library-baseline-manifest.json', original)
staged = request
identity = None
if source:
checkpoint('stage_source')
source_manifest = copy_verified(source.parent, root/'source', progress=progress)
_write_json(root/'source-manifest.json', source_manifest)
staged = replace(request, source=root/'source'/source.name, top_level_block=top)
identity = engineering_identity(staged.source)
if build_manifest(source.parent) != source_manifest:
raise OSError('来源工程在暂存期间变化。')
if source and hasattr(adapter, 'prepare_add_transaction'):
checkpoint('prepare_identity')
owner_safe = False
staged, proof = adapter.prepare_add_transaction(staged, root, original_source=source)
owner_safe = proof.safe_to_continue
if not owner_safe or proof.identity is None:
return finish('UPLOAD_FAILED', proof.detail, owner_safe)
identity = proof.identity
if build_exclusive_library_manifest(library_root, scope=scope, progress=progress) != original:
raise OSError('内容基线记录后中心库发生变化,停止写入。')
if request.operation in ('remove', 'update'):
checkpoint('native_remove')
mutated = True; owner_safe = False
native = invoke(adapter.remove, request, root/'remove')
owner_safe = native.safe_to_continue
if not owner_safe or not native.success:
return finish('RECOVERY_REQUIRED', native.detail, owner_safe)
idle_check(library, target_project, target_pcb)
after = invoke(adapter.catalog, library, root/'after-remove')
owner_safe = after.safe_to_continue
if (not owner_safe or Path(after.library).resolve() != canonical_library or after.flow != 1
or any(e.name == request.name and e.partition == request.partition for e in after.entries)):
return finish('RECOVERY_REQUIRED', '原生移除后目录未确认目标缺失。', owner_safe)
removed = True
checkpoint('removed')
if request.operation == 'remove':
return finish('REMOVED', '已由原生操作移除,重新读取目录确认不存在;应用未创建备份。')
checkpoint('native_add')
mutated = True; owner_safe = False
native = invoke(adapter.add, staged, root/'add')
owner_safe = native.safe_to_continue
if not owner_safe or not native.success:
return finish('RECOVERY_REQUIRED' if removed or not owner_safe else 'UPLOAD_FAILED',
native.detail, owner_safe)
idle_check(library, target_project, target_pcb)
after = invoke(adapter.catalog, library, root/'after-add')
owner_safe = after.safe_to_continue
matches = [entry for entry in after.entries if entry.name == request.name
and entry.partition == request.partition]
proof_matches = (native.identity_matches is True and native.identity_proof == identity
if hasattr(adapter, 'prepare_add_transaction') else
len(matches) == 1 and matches[0].engineering_identity == identity)
if (not owner_safe or Path(after.library).resolve() != canonical_library or after.flow != 1
or len(matches) != 1 or not proof_matches):
return finish('RECOVERY_REQUIRED', '原生新增后名称、分区或来源工程内容未确认一致。', owner_safe)
uploaded = True
checkpoint('uploaded')
if not request.auto_verify:
return finish('UPLOADED', '上传已确认;本批次未启用自动校验。')
# Adapter catalog cannot return until its exact native owner exits.
checkpoint('verify')
owner_safe = False
verified = verifier(VerifyRequest(library, request.name, root/'verify',
mapped_drive=request.mapped_drive, mapped_remote_root=request.mapped_remote_root), progress=progress)
owner_safe = verified.safe_to_continue
checkpoint('verified', verification=asdict(verified))
good = verified.status == 'PASS' and verified.library_flag == 'GREEN' and owner_safe
return finish('UPLOADED_VERIFIED' if good else 'UPLOADED_VERIFY_FAILED',
verified.stderr or verified.library_flag_detail, owner_safe)
except Exception as error:
if uploaded:
return finish('UPLOADED_VERIFY_FAILED', str(error), owner_safe)
status = 'RECOVERY_REQUIRED' if mutated else ('UPLOAD_FAILED' if request.operation in ('add', 'update') else 'BLOCKED')
# Bad input is never described as a native upload attempt.
if root is None and isinstance(error, ValueError):
status = 'BLOCKED'
if stage == 'release_check' and not mutated:
status = 'BLOCKED'
return finish(status, str(error), owner_safe)
finally:
if mutex is not None:
if acquired:
win32event.ReleaseMutex(mutex)
mutex.Close()
uninitialize_com(initialized)
def run_management_batch(requests, *, stop=None, progress=None, **kwargs):
results = []
for request in requests:
if stop is not None and stop.is_set():
break
result = run_management(request, progress=progress, **kwargs)
results.append(result)
if progress:
progress({'stage': result.status, 'block': result.name, 'detail': result.detail,
'evidence_path': str(result.evidence_path or '')})
if not result.safe_to_continue:
break
return results