Readiness, Electrum status, audit browsing and logs (B-92, API-37, API-46, API-47, AUD-34, AUD-41, ARC-02, ARC-09, ARC-61, ELC-29, SEC-48)

- GET /health/ready (Electrum connected, header < 1800s, scheduler heartbeat < 30s) is the
  container healthcheck; the scheduler beats on every tick and draw-wait iteration
- GET /admin/electrum and an Electrum indicator in /admin (server, header age, last rotation)
- GET /admin/audit-log: before_id, event_type, round_id, user_id, from, to; the panel gets filters
- registration writes user_registered in its transaction
- the app's own logs also go to stdout; uvicorn trusts X-Forwarded-For from Caddy's fixed
  address only, so the access log shows the client's IP

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5.5 committed 2026-10-18 01:15:22 +02:00
1 parent 9520c80dcf
commit 575f1a5354
23 files changed
+478 -91

No files matched your search

+71 -3
View File
@@ -1,7 +1,8 @@
import json
import secrets
from datetime import datetime, timezone
from fastapi import APIRouter, Depends, Header, Query, status
from fastapi import APIRouter, Depends, Header, Query, Request, status
from pydantic import BaseModel, Field, field_validator
from sqlalchemy import select, update
from sqlalchemy.ext.asyncio import AsyncSession
@@ -369,13 +370,54 @@ class AdminAuditLogResponse(BaseModel):
created_at: str
def _parse_instant(name: str, value: str | None) -> datetime | None:
"""An ISO 8601 instant with an offset, as UTC; anything else is a 422 (API-37)."""
if value is None:
return None
try:
parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
except ValueError:
parsed = None
if parsed is None or parsed.tzinfo is None:
raise http_error(
status.HTTP_422_UNPROCESSABLE_CONTENT,
"invalid_request",
"invalid request",
errors=[{"loc": ["query", name], "msg": "an ISO 8601 instant with an offset is required", "type": "value_error"}],
)
return parsed.astimezone(timezone.utc)
@router.get(
"/audit-log", response_model=list[AdminAuditLogResponse], dependencies=[Depends(require_admin)]
)
async def list_audit_log(
session: AsyncSession = Depends(get_session), limit: int = Query(default=200, ge=1, le=500)
session: AsyncSession = Depends(get_session),
limit: int = Query(default=200, ge=1, le=500),
before_id: int | None = Query(default=None),
event_type: list[str] | None = Query(default=None),
round_id: int | None = Query(default=None),
user_id: int | None = Query(default=None),
from_: str | None = Query(default=None, alias="from"),
to: str | None = Query(default=None),
) -> list[AdminAuditLogResponse]:
entries = (await session.scalars(select(AuditLog).order_by(AuditLog.id.desc()).limit(limit))).all()
"""B-92 (API-37): newest first, a page at a time, every filter optional and combined with
"and". The next page asks for `before_id` equal to the last id received."""
query = select(AuditLog).order_by(AuditLog.id.desc()).limit(limit)
if before_id is not None:
query = query.where(AuditLog.id < before_id)
if event_type:
query = query.where(AuditLog.event_type.in_(event_type))
if round_id is not None:
query = query.where(AuditLog.round_id == round_id)
if user_id is not None:
query = query.where(AuditLog.user_id == user_id)
start, end = _parse_instant("from", from_), _parse_instant("to", to)
if start is not None:
query = query.where(AuditLog.created_at >= start)
if end is not None:
query = query.where(AuditLog.created_at < end)
entries = (await session.scalars(query)).all()
return [
AdminAuditLogResponse(
id=e.id,
@@ -517,3 +559,29 @@ async def update_bug_report_status(
username = user.username if user is not None else None
return _bug_report_response(report, username)
class AdminElectrumResponse(BaseModel):
connected: bool
endpoint: str | None
tip_height: int
last_header_age_seconds: int | None
fallback_count: int
quorum_enforced: bool
last_rotation: dict | None
@router.get("/electrum", response_model=AdminElectrumResponse, dependencies=[Depends(require_admin)])
async def electrum_status(request: Request) -> AdminElectrumResponse:
"""B-92 (API-47, ELC-29): the connection to the network, for the panel's indicator."""
listener = request.app.state.electrum_listener
connected = listener.client is not None
return AdminElectrumResponse(
connected=connected,
endpoint=str(listener.current_endpoint) if connected and listener.current_endpoint else None,
tip_height=listener.tip_height,
last_header_age_seconds=listener.last_header_age_seconds(),
fallback_count=listener.fallback_count,
quorum_enforced=listener.quorum_enforced,
last_rotation=listener.last_rotation,
)
+10
View File
@@ -6,6 +6,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
from app.api.client_ip import client_ip as _client_ip
from app.api.errors import http_error
from app.audit.log import write_audit_log
from app.auth.rate_limit import AuthRateLimiters
from app.auth.security import (
MIN_PASSWORD_LENGTH,
@@ -121,6 +122,15 @@ async def register(
)
session.add(user)
try:
# B-92 (AUD-41, REG-16): in the same transaction as the user, so after a restore the log
# says which derivation indexes were already assigned.
await session.flush()
await write_audit_log(
session,
"user_registered",
{"derivation_index": next_index, "address": address},
user_id=user.id,
)
await session.commit()
except IntegrityError as exc:
await session.rollback()
+33 -1
View File
@@ -1,6 +1,7 @@
import asyncio
import logging
import time
from datetime import datetime, timezone
from collections import Counter
from collections.abc import Callable
@@ -79,6 +80,14 @@ _RESTORE_GAP_WINDOW = 20
_MAX_HEADERS_PER_REQUEST = 2016
def _rotation_reason(exc: BaseException) -> str:
if isinstance(exc, ServerStalledError):
return "stalled_tip"
if isinstance(exc, HeaderValidationError):
return "invalid_header"
return "error"
class ServerStalledError(Exception):
"""The active server stopped following the chain while others report a higher tip
(B-86, ELC-21). Ends the session like a dropped connection, so run() rotates."""
@@ -119,6 +128,9 @@ class ElectrumListener:
self._allow_no_quorum = allow_no_quorum
self._endpoint_index = 0
self._restore_checked = False
# B-92 (API-47): why and when the listener last moved on to another server.
self.last_rotation: dict | None = None
self._end_reason: str | None = None
self._refresh_locks: dict[int, asyncio.Lock] = {}
self._scripthash_to_user: dict[str, int] = {}
# Retains address_for_new_user's fire-and-forget subscribe task so it
@@ -144,6 +156,18 @@ class ElectrumListener:
# Users with a refresh already running because of a new block (see _consume_headers).
self._block_refreshes: set[int] = set()
def last_header_age_seconds(self) -> int | None:
"""B-92 (ELC-29): seconds since a header was last accepted, None before the first."""
return None if self._last_header_at is None else int(_monotonic() - self._last_header_at)
@property
def fallback_count(self) -> int:
return max(len(self._endpoints) - 1, 0)
@property
def quorum_enforced(self) -> bool:
return not self._allow_no_quorum
@property
def current_endpoint(self) -> ElectrumEndpoint | None:
"""Which server the next (or current) session uses — for logging and for
@@ -190,11 +214,13 @@ class ElectrumListener:
logger.error("no Electrum endpoints configured; listener idle")
return
connected = False
self._end_reason = None
try:
connected = await self._run_once(endpoint)
except asyncio.CancelledError:
raise
except Exception:
except Exception as exc:
self._end_reason = _rotation_reason(exc)
logger.exception("Electrum session on %s failed", endpoint)
finally:
self.client = None
@@ -203,6 +229,11 @@ class ElectrumListener:
# server that just dropped us has no claim on being tried first again.
if len(self._endpoints) > 1:
self._endpoint_index = (self._endpoint_index + 1) % len(self._endpoints)
self.last_rotation = {
"reason": self._end_reason or ("connection_closed" if connected else "unreachable"),
"from": str(endpoint),
"at": datetime.now(timezone.utc).isoformat(),
}
if connected:
# We did reach a server, so the network is up — don't let an earlier
@@ -294,6 +325,7 @@ class ElectrumListener:
for task in done:
exc = task.exception()
if exc is not None:
self._end_reason = _rotation_reason(exc)
logger.warning("Electrum session on %s ending: %r", endpoint, exc)
finally:
self.client = None
+8
View File
@@ -1,4 +1,5 @@
import logging
import sys
from logging.handlers import RotatingFileHandler
from pathlib import Path
@@ -16,9 +17,16 @@ def setup_logging() -> None:
handler = RotatingFileHandler(LOG_FILE, maxBytes=10 * 1024 * 1024, backupCount=5)
handler.setFormatter(logging.Formatter(_FORMAT))
# B-92 (ARC-09): also on stdout, so `docker compose logs app` shows the app's own messages
# (scheduler, listener, reconcilers) next to uvicorn's and the startup output. Only on the
# root logger: uvicorn's loggers already print to the console by themselves.
console = logging.StreamHandler(sys.stdout)
console.setFormatter(logging.Formatter(_FORMAT))
root = logging.getLogger()
root.setLevel(logging.INFO)
root.addHandler(handler)
root.addHandler(console)
# "uvicorn.error"/"uvicorn.access" have propagate=False in uvicorn's default
# logging config, so they never reach the root handler above and need their
+30
View File
@@ -72,6 +72,7 @@ async def lifespan(app: FastAPI):
app.state.user_locks = UserLocks()
scheduler = RoundScheduler(AsyncSessionLocal, listener)
app.state.scheduler = scheduler # B-92: /health/ready reads its heartbeat
poller = ConfirmationPoller(AsyncSessionLocal, lambda: listener.client, network=listener)
bumper = RbfBumper(AsyncSessionLocal, lambda: listener.client, network=listener)
# Resolves in-flight transactions against the chain — the piece that lets the
@@ -158,6 +159,35 @@ async def health() -> dict[str, str]:
return {"status": "ok"}
# B-92 (API-46, ELC-29, ARC-61): the header age is generous on purpose — with 120 s blocks, 360 s
# of silence happens by chance about 5% of the time (e^-3), and a healthcheck must not flap on that.
READY_MAX_HEADER_AGE_SECONDS = 1800
READY_MAX_SCHEDULER_HEARTBEAT_SECONDS = 30
@app.get("/health/ready", include_in_schema=False)
async def health_ready() -> JSONResponse:
listener = getattr(app.state, "electrum_listener", None)
scheduler = getattr(app.state, "scheduler", None)
header_age = listener.last_header_age_seconds() if listener is not None else None
heartbeat_age = scheduler.heartbeat_age_seconds() if scheduler is not None else None
checks = {
"electrum_connected": listener is not None and listener.client is not None,
"last_header_age_seconds": header_age,
"scheduler_heartbeat_age_seconds": heartbeat_age,
}
ready = (
checks["electrum_connected"]
and header_age is not None
and header_age < READY_MAX_HEADER_AGE_SECONDS
and heartbeat_age is not None
and heartbeat_age < READY_MAX_SCHEDULER_HEARTBEAT_SECONDS
)
return JSONResponse(
status_code=200 if ready else 503, content={"status": "ready" if ready else "not_ready", "checks": checks}
)
_NO_STORE_HEADERS = {"Cache-Control": "no-store"}
+9
View File
@@ -1,4 +1,5 @@
import asyncio
import time
import logging
from datetime import datetime, timedelta, timezone
@@ -62,9 +63,16 @@ class RoundScheduler:
def __init__(self, session_factory: async_sessionmaker, listener: ElectrumListener):
self._session_factory = session_factory
self._listener = listener
# B-92 (ARC-61): monotonic time of the last tick or draw-wait iteration, read by
# /health/ready. The draw wait runs inside a tick and lasts several blocks, so it beats too.
self.last_heartbeat: float | None = None
def heartbeat_age_seconds(self) -> int | None:
return None if self.last_heartbeat is None else int(time.monotonic() - self.last_heartbeat)
async def run(self) -> None:
while True:
self.last_heartbeat = time.monotonic()
try:
await self._tick()
except asyncio.CancelledError:
@@ -409,6 +417,7 @@ class RoundScheduler:
reported_hashes: set[str | None] = set()
while True:
self.last_heartbeat = time.monotonic()
now = datetime.now(timezone.utc)
tip = self._listener.tip_height
if tip >= required_tip:
+13 -1
View File
@@ -37,6 +37,7 @@
<span id="chain-status-label">Connessione…</span>
</span>
<span class="chain-block mono" id="chain-block">Blocco —</span>
<span class="chain-block mono" id="electrum-status">Electrum —</span>
<button class="secondary" style="margin:8px 0 8px 14px" onclick="adminLogout()">Esci</button>
</nav>
@@ -153,7 +154,17 @@
<div class="view" id="view-audit">
<h2 class="section-title">Audit log</h2>
<p class="hint">Ultimi eventi registrati dal sistema (config, bet, payout, accessi a chiavi private, ecc.).</p>
<p class="hint">Eventi registrati dal sistema (config, bet, payout, accessi a chiavi private, ecc.), dal più recente. I filtri si combinano; "Carica altri" prosegue dall'ultimo evento mostrato.</p>
<div class="card">
<div class="row-between" style="flex-wrap:wrap;gap:8px">
<input id="audit-f-type" placeholder="Tipo (es. payout_failed)" style="width:200px" />
<input id="audit-f-round" placeholder="Round" inputmode="numeric" style="width:90px" />
<input id="audit-f-user" placeholder="Utente" inputmode="numeric" style="width:90px" />
<input id="audit-f-from" type="datetime-local" title="Da" />
<input id="audit-f-to" type="datetime-local" title="A" />
<button class="secondary" style="width:auto;margin-top:0" onclick="loadAuditLog()">Filtra</button>
</div>
</div>
<div class="card">
<div class="table-wrap">
@@ -164,6 +175,7 @@
<tbody id="audit-tbody"></tbody>
</table>
</div>
<button id="audit-more" class="secondary hidden" style="width:auto" onclick="loadAuditLog(true)">Carica altri</button>
</div>
</div>
+45 -5
View File
@@ -76,6 +76,26 @@ async function refreshChainStatus() {
} catch (e) {
// leave the last-known status on screen rather than blanking it out
}
refreshElectrumStatus();
}
// B-92 (API-47): which server the platform is talking to and how fresh its last block is.
async function refreshElectrumStatus() {
const el = document.getElementById('electrum-status');
if (!adminToken) return;
try {
const s = await callAdmin('GET', '/admin/electrum');
const age = s.last_header_age_seconds;
el.textContent = s.connected
? `Electrum ${s.endpoint}${age != null ? ' · ultimo blocco ' + age + 's fa' : ''}`
: 'Electrum non connesso';
el.title = s.last_rotation
? `Ultimo cambio server: ${s.last_rotation.from} (${s.last_rotation.reason}) alle ${fmtDate(s.last_rotation.at)}`
: '';
if (!s.quorum_enforced) el.title += ' · quorum non imposto (ALLOW_NO_QUORUM)';
} catch (e) {
// keep the last text
}
}
function startChainStatusPolling() {
@@ -90,7 +110,7 @@ function stopChainStatusPolling() {
}
const VIEWS = ['parametri', 'utenti', 'round', 'pending', 'audit', 'bugreports'];
const VIEW_LOADERS = { utenti: loadUsers, round: loadRounds, pending: loadPending, audit: loadAuditLog, bugreports: loadBugReports };
const VIEW_LOADERS = { utenti: loadUsers, round: loadRounds, pending: loadPending, audit: () => loadAuditLog(), bugreports: loadBugReports };
let currentAdminView = 'parametri';
function switchView(name) {
@@ -345,11 +365,29 @@ async function loadPending() {
}
}
async function loadAuditLog() {
let auditLastId = null;
const AUDIT_PAGE = 200;
async function loadAuditLog(more = false) {
try {
const entries = await callAdmin('GET', '/admin/audit-log');
// B-92 (API-37): filters combine; "more" continues from the last id shown.
const params = new URLSearchParams({ limit: String(AUDIT_PAGE) });
const type = document.getElementById('audit-f-type').value.trim();
if (type) params.append('event_type', type);
for (const [id, key] of [['audit-f-round', 'round_id'], ['audit-f-user', 'user_id']]) {
const v = document.getElementById(id).value.trim();
if (v) params.append(key, v);
}
for (const [id, key] of [['audit-f-from', 'from'], ['audit-f-to', 'to']]) {
const v = document.getElementById(id).value;
if (v) params.append(key, new Date(v).toISOString());
}
if (more === true && auditLastId !== null) params.append('before_id', String(auditLastId));
const entries = await callAdmin('GET', '/admin/audit-log?' + params);
auditLastId = entries.length ? entries[entries.length - 1].id : auditLastId;
document.getElementById('audit-more').classList.toggle('hidden', entries.length < AUDIT_PAGE);
const tbody = document.getElementById('audit-tbody');
tbody.innerHTML = entries.map((e) => `
const rows = entries.map((e) => `
<tr>
<td>${e.id}</td>
<td>${escapeHtml(e.event_type)}</td>
@@ -358,7 +396,9 @@ async function loadAuditLog() {
<td>${e.round_id ?? '—'}</td>
<td>${fmtDate(e.created_at)}</td>
</tr>
`).join('') || '<tr><td colspan="6" class="hint">Nessun evento registrato.</td></tr>';
`).join('');
if (more === true) tbody.insertAdjacentHTML('beforeend', rows);
else tbody.innerHTML = rows || '<tr><td colspan="6" class="hint">Nessun evento registrato.</td></tr>';
} catch (e) {
toast('Errore nel caricamento audit log: ' + e.message, 'error');
}