lligma-tutor / lligma /tutor /server.py
Mortxm's picture
LLigMA Tutor: codice + indice + pesi SFT pass 2 (9/20 launch set)
a538280 verified
Raw History Blame Contribute Delete
15 kB
"""Server HTTP del tutor: solo libreria standard.
Perche' non FastAPI: il servizio ha due endpoint, un file statico e uno stream
SSE. ``http.server`` li copre senza installare nulla, il che conta quando il
destinatario e' un laboratorio scolastico con un Python qualsiasi. Se in futuro
servono autenticazione, quota per studente e log strutturati, il posto giusto e'
un reverse proxy davanti, non dentro questo file.
Sicurezza di base, deliberata:
* bind su 127.0.0.1 per default;
* body massimo 64 KB e domanda massima 800 caratteri;
* nessun percorso fuori da ``web/`` (controllo con realpath);
* header CSP e ``nosniff`` su ogni risposta.
"""
from __future__ import annotations
import argparse
import json
import sys
import threading
from http import HTTPStatus
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
from urllib.parse import unquote, urlparse
from .config import TutorConfig
from .service import TutorService
MAX_BODY_BYTES = 64 * 1024
MAX_QUESTION_CHARS = 800
LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1"})
CONTENT_TYPES = {
".html": "text/html; charset=utf-8",
".css": "text/css; charset=utf-8",
".js": "application/javascript; charset=utf-8",
".svg": "image/svg+xml",
".png": "image/png",
".ico": "image/x-icon",
".json": "application/json; charset=utf-8",
".woff2": "font/woff2",
}
SECURITY_HEADERS = {
"X-Content-Type-Options": "nosniff",
"Referrer-Policy": "no-referrer",
"Content-Security-Policy": (
"default-src 'self'; style-src 'self' 'unsafe-inline'; "
"script-src 'self' 'unsafe-inline'; img-src 'self' data:; "
"connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; "
"form-action 'self'"
),
"X-Frame-Options": "DENY",
"Permissions-Policy": "camera=(), microphone=(), geolocation=()",
}
CONNECTION_LOSS_ERRORS = (BrokenPipeError, ConnectionResetError, ConnectionAbortedError)
def write_sse_event(wfile, event: dict) -> bool:
"""Scrive un evento SSE e sopprime solo la chiusura del client.
Restituisce ``False`` quando la connessione e' gia' morta, cosi' il
chiamante smette di generare e di scrivere altri eventi.
"""
chunk = f"data: {json.dumps(event, ensure_ascii=False)}\n\n".encode("utf-8")
try:
wfile.write(chunk)
wfile.flush()
except CONNECTION_LOSS_ERRORS:
return False
return True
class TutorRequestHandler(BaseHTTPRequestHandler):
service: TutorService
web_dir: Path
protocol_version = "HTTP/1.1"
server_version = "LLigMaTutor/1.0"
# -- infrastruttura ------------------------------------------------------
def log_message(self, fmt: str, *args) -> None: # noqa: D102 - firma stdlib
sys.stderr.write(f"[tutor] {self.address_string()} {fmt % args}\n")
def _send(self, status: int, body: bytes, content_type: str, extra: dict | None = None) -> None:
self.send_response(status)
self.send_header("Content-Type", content_type)
self.send_header("Content-Length", str(len(body)))
for key, value in SECURITY_HEADERS.items():
self.send_header(key, value)
for key, value in (extra or {}).items():
self.send_header(key, value)
self.end_headers()
if self.command != "HEAD":
self.wfile.write(body)
def _json(self, status: int, payload: dict, extra: dict | None = None) -> None:
body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
headers = {"Cache-Control": "no-store"}
headers.update(extra or {})
self._send(status, body, "application/json; charset=utf-8", headers)
def _error(self, status: int, message: str, close: bool = False) -> None:
if close:
# Se il corpo non e' stato letto, riusare questa connessione
# farebbe interpretare i byte residui come una nuova richiesta.
self.close_connection = True
self._json(
status,
{"error": message},
{"Connection": "close"} if close else None,
)
def _read_json(self) -> dict | None:
try:
length = int(self.headers.get("Content-Length") or 0)
except ValueError:
self._error(HTTPStatus.BAD_REQUEST, "Content-Length non valido", close=True)
return None
if length <= 0:
self._error(HTTPStatus.BAD_REQUEST, "corpo della richiesta mancante", close=True)
return None
if length > MAX_BODY_BYTES:
self._error(
HTTPStatus.REQUEST_ENTITY_TOO_LARGE,
"richiesta troppo grande",
close=True,
)
return None
try:
payload = json.loads(self.rfile.read(length).decode("utf-8"))
except (UnicodeDecodeError, json.JSONDecodeError):
self._error(HTTPStatus.BAD_REQUEST, "JSON non valido")
return None
if not isinstance(payload, dict):
self._error(HTTPStatus.BAD_REQUEST, "atteso un oggetto JSON")
return None
return payload
@staticmethod
def _clean_question(payload: dict) -> str | None:
question = payload.get("question") or payload.get("q")
if not isinstance(question, str):
return None
question = question.strip()
return question[:MAX_QUESTION_CHARS] or None
@staticmethod
def _clean_subject(payload: dict) -> str | None:
subject = payload.get("subject")
if not isinstance(subject, str):
return None
subject = subject.strip().lower()
return subject or None
def _host_allowed(self) -> bool:
"""Blocca il DNS rebinding sul bind loopback.
Il confronto Origin/Host da solo non basta: una pagina su evil.example
puo' far risolvere evil.example su 127.0.0.1, e allora Host e Origin
coincidono. Con un bind loopback accettiamo solo i nomi locali, salvo
una lista esplicita in configurazione per un reverse proxy.
"""
allowed = getattr(self.server, "allowed_hosts", frozenset())
if not allowed:
return True
host_header = (self.headers.get("Host") or "").strip()
if not host_header:
return False
try:
hostname = urlparse(f"//{host_header}").hostname
except ValueError:
return False
return bool(hostname) and hostname.lower() in allowed
def _origin_allowed(self) -> bool:
"""Rifiuta i POST inviati da pagine di altri siti.
Senza questo controllo una pagina qualsiasi aperta nel browser dello
studente puo' chiamare il tutor su localhost e consumare la chiave API.
I client non browser (curl, script, test) non mandano ``Origin`` e
restano ammessi; il confronto e' sull'host, non sullo schema, cosi'
funziona anche dietro un reverse proxy TLS.
"""
origin = self.headers.get("Origin")
if not origin:
return True
host = (self.headers.get("Host") or "").strip().lower()
try:
origin_host = urlparse(origin).netloc.strip().lower()
except ValueError:
return False
return bool(host) and bool(origin_host) and origin_host == host
@staticmethod
def _clean_history(payload: dict) -> list[dict]:
history = payload.get("history")
if not isinstance(history, list):
return []
cleaned = []
for turn in history[-6:]:
if isinstance(turn, dict) and isinstance(turn.get("content"), str):
cleaned.append(
{
"role": turn.get("role") if turn.get("role") in {"user", "assistant"} else "user",
"content": turn["content"][:800],
}
)
return cleaned
# -- GET -----------------------------------------------------------------
def do_GET(self) -> None: # noqa: N802 - nome imposto da stdlib
if not self._host_allowed():
self._error(HTTPStatus.FORBIDDEN, "host non consentito", close=True)
return
path = unquote(urlparse(self.path).path)
if path in {"/api/health", "/health"}:
payload = self.service.health()
# Diagnostica additiva: non entra negli eventi SSE e non cambia
# la risposta osservata da un client normale.
lock = getattr(self.server, "stream_aborts_lock", None)
if lock is None:
aborts = int(getattr(self.server, "stream_aborts", 0))
else:
with lock:
aborts = int(getattr(self.server, "stream_aborts", 0))
payload["stream_aborts"] = aborts
self._json(HTTPStatus.OK, payload)
return
if path in {"/", "/index.html"}:
path = "/index.html"
relative = path.lstrip("/")
candidate = (self.web_dir / relative).resolve()
try:
candidate.relative_to(self.web_dir.resolve())
except ValueError:
self._error(HTTPStatus.FORBIDDEN, "percorso non consentito")
return
if not candidate.is_file():
self._error(HTTPStatus.NOT_FOUND, "risorsa non trovata")
return
content_type = CONTENT_TYPES.get(candidate.suffix.lower(), "application/octet-stream")
self._send(HTTPStatus.OK, candidate.read_bytes(), content_type)
# -- POST ----------------------------------------------------------------
def do_POST(self) -> None: # noqa: N802 - nome imposto da stdlib
if not self._host_allowed():
self._error(HTTPStatus.FORBIDDEN, "host non consentito", close=True)
return
path = urlparse(self.path).path
if path not in {"/api/ask", "/api/stream"}:
self._error(HTTPStatus.NOT_FOUND, "endpoint non trovato", close=True)
return
if not self._origin_allowed():
self._error(HTTPStatus.FORBIDDEN, "origine non consentita", close=True)
return
payload = self._read_json()
if payload is None:
return
question = self._clean_question(payload)
if question is None:
self._error(HTTPStatus.BAD_REQUEST, "serve il campo 'question'")
return
subject = self._clean_subject(payload)
history = self._clean_history(payload)
if path == "/api/ask":
answer = self.service.ask(question, subject=subject, history=history)
self._json(HTTPStatus.OK, answer.to_dict())
return
self._stream(question, subject, history)
def _note_stream_abort(self) -> None:
server = getattr(self, "server", None)
if server is None:
return
with server.stream_aborts_lock:
server.stream_aborts = getattr(server, "stream_aborts", 0) + 1
def _stream(self, question: str, subject: str | None, history: list[dict]) -> None:
self.send_response(HTTPStatus.OK)
self.send_header("Content-Type", "text/event-stream; charset=utf-8")
self.send_header("Cache-Control", "no-store")
self.send_header("X-Accel-Buffering", "no")
self.send_header("Connection", "close")
for key, value in SECURITY_HEADERS.items():
self.send_header(key, value)
self.end_headers()
try:
for event in self.service.stream(question, subject=subject, history=history):
if not write_sse_event(self.wfile, event):
# Lo studente ha chiuso la scheda: non e' un errore del server.
self._note_stream_abort()
return
except CONNECTION_LOSS_ERRORS:
# Chiusura avvenuta tra due eventi, prima del prossimo write.
self._note_stream_abort()
return
except Exception as error: # pragma: no cover - rete reale
try:
message = {"type": "error", "message": f"errore interno: {error}"}
self.wfile.write(f"data: {json.dumps(message, ensure_ascii=False)}\n\n".encode())
self.wfile.flush()
except OSError:
pass
finally:
self.close_connection = True
def _allowed_hosts(config: TutorConfig) -> frozenset[str]:
configured = config.server.allowed_hosts or []
if isinstance(configured, str):
configured = [configured]
hosts = {str(host).strip().lower() for host in configured if str(host).strip()}
if hosts:
return frozenset(hosts)
if (config.server.host or "").strip().lower() in LOOPBACK_HOSTS:
return LOOPBACK_HOSTS
# Un bind esplicito su LAN/0.0.0.0 resta invariato finche' l'operatore non
# configura allowed_hosts: il tutor non deve rompersi in una rete didattica.
return frozenset()
def build_server(config: TutorConfig, service: TutorService | None = None) -> ThreadingHTTPServer:
"""Server pronto ma non in ascolto: i test lo avviano su una porta effimera."""
service = service or TutorService(config)
handler = type("BoundTutorHandler", (TutorRequestHandler,), {
"service": service,
"web_dir": config.server.web_dir,
})
server = ThreadingHTTPServer((config.server.host, config.server.port), handler)
server.daemon_threads = True
server.stream_aborts = 0
server.stream_aborts_lock = threading.Lock()
server.allowed_hosts = _allowed_hosts(config)
return server
def main(argv: list[str] | None = None) -> int:
from .console import setup_utf8
setup_utf8()
parser = argparse.ArgumentParser(description="Server di LLigMa Tutor")
parser.add_argument("--config", default="configs/tutor.yaml")
parser.add_argument("--host", default=None)
parser.add_argument("--port", type=int, default=None)
parser.add_argument("--backend", default=None, help="auto | extractive | openai | local")
args = parser.parse_args(argv)
config = TutorConfig.from_file(args.config)
if args.host:
config.server.host = args.host
if args.port:
config.server.port = args.port
if args.backend:
config.generation.backend = args.backend
service = TutorService(config)
server = build_server(config, service)
print(f"LLigMa Tutor in ascolto su http://{config.server.host}:{server.server_address[1]}/")
print(f" indice : {len(service.index)} passaggi da {service.index.metadata.get('documents')} schede")
print(f" backend: {service.backend.name}")
for note in service.startup_notes:
print(f" nota : {note}")
print(" Ctrl+C per fermare.")
try:
server.serve_forever()
except KeyboardInterrupt:
print("\nArresto.")
finally:
server.server_close()
return 0
if __name__ == "__main__":
raise SystemExit(main())