SRE.common

  1import hashlib
  2import json
  3from dataclasses import dataclass, asdict, field
  4from typing import List
  5
  6import msgpack
  7from enum import Enum
  8
  9
 10class TranslatedText(dict):
 11    """A dict subclass holding translations keyed by language code (e.g. 'en', 'fr').
 12
 13    Use ``resolve(lang)`` to get the text for a specific language, falling back to the
 14    first available translation.  ``from_value`` ensures backward-compat with plain strings.
 15    """
 16
 17    def resolve(self, lang: str, fallback: str = '') -> str:
 18        return self.get(lang) or next(iter(self.values()), fallback)
 19
 20    def resolve_priority(self, langs: list, fallback: str = '') -> str:
 21        """Return the first translation found in the priority list, or first available."""
 22        for lang in langs:
 23            if self.get(lang):
 24                return self[lang]
 25        return next(iter(self.values()), fallback)
 26
 27    def __add__(self, other) -> 'TranslatedText':
 28        if isinstance(other, str):
 29            return TranslatedText({lang: self[lang] + other for lang in self})
 30        if not isinstance(other, TranslatedText):
 31            return NotImplemented
 32        if not self:
 33            return TranslatedText(other)
 34        if not other:
 35            return TranslatedText(self)
 36        # Merge mismatched language sets gracefully (partial translations): take
 37        # the union of languages, falling back to each side's default-language
 38        # (first-key) value for a language that side lacks.
 39        self_default = next(iter(self.values()))
 40        other_default = next(iter(other.values()))
 41        langs = list(dict.fromkeys((*self, *other)))
 42        return TranslatedText({
 43            lang: self.get(lang, self_default) + other.get(lang, other_default)
 44            for lang in langs
 45        })
 46
 47    def __radd__(self, other) -> 'TranslatedText':
 48        if isinstance(other, str):
 49            return TranslatedText({lang: other + self[lang] for lang in self})
 50        return NotImplemented
 51
 52    def format(self, **kwargs) -> 'TranslatedText':
 53        """Apply str.format(**kwargs) to every language value."""
 54        return TranslatedText({lang: text.format(**kwargs) for lang, text in self.items()})
 55
 56    @classmethod
 57    def from_value(cls, v, default_lang: str = 'en') -> 'TranslatedText':
 58        if isinstance(v, cls):
 59            return v
 60        if isinstance(v, dict):
 61            return cls(v)
 62        return cls({default_lang: str(v)}) if v else cls()
 63
 64
 65def _tt_hash_str(v) -> str:
 66    """Stable string representation of a TranslatedText (or plain str) for hashing."""
 67    return json.dumps(dict(sorted(TranslatedText.from_value(v).items())), ensure_ascii=False)
 68
 69
 70class QuestionType(Enum):
 71    DUMMY = 0
 72    TEXT = 1
 73    FORM = 2
 74
 75
 76class Question:
 77    """Abstract base for all question types (TEXT, FORM, DUMMY)."""
 78
 79    def __init__(self, title, description, question_hash, order, question_type):
 80        self.title = title
 81        self.description = description
 82        self.question_hash = question_hash
 83        self.order = order
 84        self.question_type = question_type
 85
 86
 87
 88@dataclass
 89class QuestionText(Question):
 90    """A free-text answer question.  Hash is derived from *title* if not provided."""
 91
 92    title: TranslatedText | str
 93    description: TranslatedText | str
 94    question_hash: str
 95    order: int
 96    question_type: int = QuestionType.TEXT.value
 97
 98    def __init__(self, title, description='', question_hash=None, order=None, **kwargs):
 99        super().__init__(title, description, question_hash, order, question_type=QuestionType.TEXT)
100        if question_hash is None:
101            self.question_hash = hashlib.sha256(_tt_hash_str(title).encode('UTF-8')).hexdigest()
102        else:
103            self.question_hash = question_hash
104        self.question_type = QuestionType.TEXT.value
105
106    def to_json(self) -> str:
107        return json.dumps(asdict(self))
108
109    @classmethod
110    def from_json(cls, json_data: str) -> "QuestionText":
111        d = json.loads(json_data)
112        if isinstance(d.get('title'), dict):
113            d['title'] = TranslatedText(d['title'])
114        if isinstance(d.get('description'), dict):
115            d['description'] = TranslatedText(d['description'])
116        return cls(**d)
117
118
119@dataclass
120class QuestionDummy(Question):
121    """A display-only block (no answer input).  Hash derived from title + description."""
122
123    title: TranslatedText | str
124    description: TranslatedText | str
125    question_hash: str
126    order: int
127    question_type: int = QuestionType.DUMMY.value
128
129    def __init__(self, title, description, question_hash=None, order=None, **kwargs):
130        super().__init__(title, description, question_hash, order, question_type=QuestionType.DUMMY)
131        if question_hash is None:
132            self.question_hash = hashlib.sha256(
133                (_tt_hash_str(title) + '--' + _tt_hash_str(description)).encode('UTF-8')
134            ).hexdigest()
135        else:
136            self.question_hash = question_hash
137        self.question_type = QuestionType.DUMMY.value
138
139    def to_json(self) -> str:
140        return json.dumps(asdict(self))
141
142    @classmethod
143    def from_json(cls, json_data: str) -> "QuestionDummy":
144        d = json.loads(json_data)
145        if isinstance(d.get('title'), dict):
146            d['title'] = TranslatedText(d['title'])
147        if isinstance(d.get('description'), dict):
148            d['description'] = TranslatedText(d['description'])
149        return cls(**d)
150
151
152@dataclass
153class QuestionForm(Question):
154    """A structured-form question with ``@@{field:regex}@@`` inline markers.
155
156    ``fields`` is a list of dicts, each either ``{"name": str, "regex": str}``
157    for a text input or ``{"name": str, "choices": [...]}`` for a dropdown.
158    """
159
160    title: TranslatedText | str
161    description: TranslatedText | str
162    question_hash: str
163    order: int
164    fields: list  # [{"name": str, "regex": str}, ...]
165    question_type: int = QuestionType.FORM.value
166
167    def __init__(self, title, description, question_hash=None, order=None, fields=None, **kwargs):
168        super().__init__(title, description, question_hash, order, question_type=QuestionType.FORM)
169        if question_hash is None:
170            self.question_hash = hashlib.sha256(
171                (_tt_hash_str(title) + '--' + _tt_hash_str(description)).encode('UTF-8')
172            ).hexdigest()
173        else:
174            self.question_hash = question_hash
175        self.fields = fields or []
176        self.question_type = QuestionType.FORM.value
177
178    def to_json(self) -> str:
179        return json.dumps(asdict(self))
180
181    @classmethod
182    def from_json(cls, json_data: str) -> "QuestionForm":
183        d = json.loads(json_data)
184        if isinstance(d.get('title'), dict):
185            d['title'] = TranslatedText(d['title'])
186        if isinstance(d.get('description'), dict):
187            d['description'] = TranslatedText(d['description'])
188        return cls(**d)
189
190
191@dataclass
192class GradeElement:
193    """One entry in a grade rubric.
194
195    Either numeric (``grade`` / ``max_grade``) or letter-graded (``grade_letter`` ∈ OK/MEH/FAIL).
196    Call ``to_grade_letter()`` to convert a numeric element to its letter equivalent.
197
198    ``scope`` is a bitmask: bit 0 (SELF_EVAL_SCOPE=1) makes the element visible in
199    user-triggered self-eval (``sre eval --auto-eval``); bit 1 (EXO_EVAL_SCOPE=2)
200    makes it visible in non-user-triggered eval, ``sre outline`` and ``sre sheet``.
201    Default 3 (BOTH_EVAL_SCOPE) means visible in both.
202    """
203
204    title: str
205    max_grade: float | None = None
206    grade: float | None = None
207    grade_letter: str | None = None
208    description: TranslatedText | str = ""
209    scope: int = 3
210    grade_part: str | None = None
211
212    def to_dict(self) -> dict:
213        return asdict(self)
214
215    @classmethod
216    def from_dict(cls, d: dict) -> "GradeElement":
217        d = dict(d)
218        if isinstance(d.get('description'), dict):
219            d['description'] = TranslatedText(d['description'])
220        return cls(**d)
221
222    def pack(self) -> bytes:
223        return msgpack.packb(self.to_dict(), use_bin_type=True)
224
225    @classmethod
226    def unpack(cls, data: bytes) -> "GradeElement":
227        return cls.from_dict(msgpack.unpackb(data, raw=False))
228
229    def to_json(self) -> str:
230        return json.dumps(asdict(self))
231
232    @classmethod
233    def from_json(cls, s: str) -> "GradeElement":
234        d = json.loads(s)
235        if isinstance(d.get('description'), dict):
236            d['description'] = TranslatedText(d['description'])
237        return cls(**d)
238
239    def to_grade_letter(self) -> "GradeElement":
240        if self.grade == self.max_grade:
241            letter = "OK"
242        elif self.grade is not None and self.grade != 0:
243            letter = "MEH"
244        else:
245            letter = "FAIL"
246        return GradeElement(title=self.title, max_grade=None, grade=None, grade_letter=letter,
247                            description=self.description, scope=self.scope,
248                            grade_part=self.grade_part)
249
250
251@dataclass
252class GradePart:
253    """A named group of GradeElements with a shared title and description.
254
255    Lab code registers parts via ``Grade.add_grade_part()`` and associates
256    each :class:`GradeElement` with one via the ``grade_part=`` kwarg on
257    ``add_grade_element``.  The element stores the part's *title* (not the
258    object) so it serializes cleanly to JSON / msgpack.
259    """
260
261    title: str
262    description: TranslatedText | str = ""
263
264    def to_dict(self) -> dict:
265        return asdict(self)
266
267    @classmethod
268    def from_dict(cls, d: dict) -> "GradePart":
269        d = dict(d)
270        if isinstance(d.get('description'), dict):
271            d['description'] = TranslatedText(d['description'])
272        return cls(**d)
273
274    def pack(self) -> bytes:
275        return msgpack.packb(self.to_dict(), use_bin_type=True)
276
277    @classmethod
278    def unpack(cls, data: bytes) -> "GradePart":
279        return cls.from_dict(msgpack.unpackb(data, raw=False))
280
281    def to_json(self) -> str:
282        return json.dumps(asdict(self))
283
284    @classmethod
285    def from_json(cls, s: str) -> "GradePart":
286        d = json.loads(s)
287        if isinstance(d.get('description'), dict):
288            d['description'] = TranslatedText(d['description'])
289        return cls(**d)
290
291
292@dataclass
293class InfoInterface:
294    """Network interface descriptor stored inside ``InfoMachine``."""
295
296    network: str
297    interface_name: str
298
299    def to_json(self) -> str:
300        return json.dumps(asdict(self))
301
302    @classmethod
303    def from_json(cls, json_data: str) -> "InfoInterface":
304        return cls(**json.loads(json_data))
305
306
307@dataclass
308class InfoMachine:
309    """Runtime snapshot of a single container, written to ``info.json`` by the CLI and read by the GUI."""
310
311    name: str
312    status: str
313    allow_connection: bool
314    hidden: bool
315    interfaces: List[InfoInterface]
316    ports: List[str]
317    bridged: bool
318    x11_host: bool = False
319    color: str = ""
320    shape: str = ""
321
322    def to_json(self):
323        return json.dumps(asdict(self))
324
325    @classmethod
326    def from_json(cls, json_data: str) -> "InfoMachine":
327        return cls(**json.loads(json_data))
328
329
330@dataclass
331class InfoLab:
332    """Full lab metadata written to ``info.json`` at ``sre start`` and polled by the GUI every second.
333
334    ``informations`` (not ``description``) holds the Markdown lab description.
335    ``questions`` is a list of ``QuestionText | QuestionDummy | QuestionForm`` instances.
336    """
337
338    lab_name: str
339    lab_hash: str
340    title: TranslatedText
341    informations: TranslatedText
342    export_kathara_project: bool
343    allow_self_grade: bool
344    machines: List[InfoMachine]
345    questions: List[Question]
346    delay_between_self_grade: int
347    eval_interval_without_exam_mode: int
348    eval_before_exit: bool
349    user_allowed_states: dict
350    debug_project: bool = False
351    admin_only_states: list = field(default_factory=list)
352    default_language: str = ''
353    network_colors: dict = field(default_factory=dict)
354    network_shapes: dict = field(default_factory=dict)
355    show_nat_network: bool = False
356    nat_network_name: str = ''
357    nat_network_color: str = ''
358    host_network_exploded: bool = False
359    host_network_edge_relative_length: float = 1.0
360    schema_splines: str = 'curved'
361    schema_overlap: str = 'prism'
362
363    def to_json(self) -> str:
364        return json.dumps(asdict(self), indent=4)
365
366    @classmethod
367    def from_json(cls, s: str) -> "InfoLab":
368        d = json.loads(s)
369
370        def _wrap_q(item: dict) -> dict:
371            item = dict(item)
372            item['title'] = TranslatedText.from_value(item.get('title', ''))
373            item['description'] = TranslatedText.from_value(item.get('description', ''))
374            return item
375
376        return cls(
377            lab_name=d["lab_name"],
378            lab_hash=d["lab_hash"],
379            title=TranslatedText.from_value(d["title"]),
380            informations=TranslatedText.from_value(d.get("informations", "")),
381            export_kathara_project=d.get("export_kathara_project", True),
382            allow_self_grade=d.get("allow_self_grade", False),
383            debug_project=d.get("debug_project", False),
384            delay_between_self_grade=d.get("delay_between_self_grade", 0),
385            eval_interval_without_exam_mode=d.get("eval_interval_without_exam_mode", 0),
386            eval_before_exit=d.get("eval_before_exit", False),
387            user_allowed_states=d.get("user_allowed_states", {}),
388            admin_only_states=list(d.get("admin_only_states", []) or []),
389            default_language=d.get("default_language", ''),
390            network_colors=d.get("network_colors", {}),
391            network_shapes=d.get("network_shapes", {}),
392            show_nat_network=d.get("show_nat_network", False),
393            nat_network_name=d.get("nat_network_name", ''),
394            nat_network_color=d.get("nat_network_color", ''),
395            host_network_exploded=d.get("host_network_exploded", False),
396            host_network_edge_relative_length=float(d.get("host_network_edge_relative_length", 1.0)),
397            schema_splines=d.get("schema_splines", "curved"),
398            schema_overlap=d.get("schema_overlap", "prism"),
399            machines=[InfoMachine(**item) for item in d["machines"]],
400            questions=[
401                QuestionDummy(**_wrap_q(item)) if item.get("question_type") == QuestionType.DUMMY.value
402                else QuestionForm(**_wrap_q(item)) if item.get("question_type") == QuestionType.FORM.value
403                else QuestionText(**_wrap_q(item))
404                for item in d["questions"]
405            ],
406        )