hyf

Context-aware query service for Radroots
git clone https://radroots.dev/git/hyf.git
Log | Files | Refs | README | LICENSE

envelope.mojo (7660B)


      1 from std.collections import Dict, Optional
      2 
      3 from json import Value, loads
      4 from json.deserialize import Deserializable, get_string
      5 
      6 from hyf_core.metadata import hyf_protocol_version
      7 from hyf_core.operation_context import (
      8     OperationContext,
      9     context_selects_versioned_any,
     10     is_corrected_operation,
     11     operation_context_selects_v2,
     12     operation_context_selects_v3,
     13     parse_operation_context,
     14 )
     15 from hyf_core.request_context import (
     16     RequestContext,
     17     default_request_context,
     18     parse_request_context,
     19 )
     20 from hyf_stdio.errors import WireError
     21 
     22 
     23 def _require_object(value: Value, context: String) raises:
     24     if not value.is_object():
     25         raise Error(context + " must be a JSON object")
     26 
     27 
     28 def _require_non_empty(value: String, field_name: String) raises:
     29     if value == "":
     30         raise Error(
     31             "request envelope field '" + field_name + "' must not be empty"
     32         )
     33 
     34 
     35 def _require_request_keys(value: Value) raises:
     36     for key in value.object_keys():
     37         if (
     38             key != "version"
     39             and key != "request_id"
     40             and key != "trace_id"
     41             and key != "capability"
     42             and key != "context"
     43             and key != "input"
     44         ):
     45             raise Error(
     46                 "request envelope contains unexpected field '" + key + "'"
     47             )
     48 
     49 
     50 def _has_key(value: Value, key: String) -> Bool:
     51     for candidate in value.object_keys():
     52         if candidate == key:
     53             return True
     54     return False
     55 
     56 
     57 def _first_duplicate_root_key(value: Value) raises -> Optional[String]:
     58     # ADR-0026 D46 CR04: decoded-key identity across every raw object entry, so
     59     # escaped equivalents (`\u0063ontext`) and repeated values are both found
     60     # rather than only the first `value[key]` lookup.
     61     var seen = Dict[String, Bool]()
     62     for item in value.object_items():
     63         var key = String(item[0])
     64         if key in seen:
     65             return Optional[String](key)
     66         seen[key] = True
     67     return None
     68 
     69 
     70 def envelope_targets_corrected_v2(json: Value) raises -> Bool:
     71     """True when an envelope contains a corrected-op capability value or a
     72     duplicate-aware v2 context selector.
     73 
     74     Scans every raw root entry, so a duplicated `capability` or `context` key
     75     cannot hide a corrected-operation value or a v2 selector behind an earlier
     76     legacy entry.
     77     """
     78     for item in json.object_items():
     79         if item[0] == "capability" and item[1].is_string():
     80             if is_corrected_operation(String(item[1].string_value())):
     81                 return True
     82         elif item[0] == "context":
     83             if context_selects_versioned_any(item[1]):
     84                 return True
     85     return False
     86 
     87 
     88 def _require_protocol_version(json: Value) raises -> Int:
     89     if not _has_key(json, "version"):
     90         raise Error("request envelope field 'version' is required")
     91 
     92     var version = json["version"]
     93     if not version.is_int():
     94         raise Error("request envelope field 'version' must be an integer")
     95 
     96     var version_value = Int(version.int_value())
     97     if version_value != hyf_protocol_version():
     98         raise Error(
     99             "request envelope version "
    100             + String(version_value)
    101             + " is unsupported; expected "
    102             + String(hyf_protocol_version())
    103         )
    104     return version_value
    105 
    106 
    107 def _parse_optional_trace_id(json: Value) raises -> Optional[String]:
    108     if not _has_key(json, "trace_id"):
    109         return None
    110 
    111     var trace_id = get_string(json, "trace_id")
    112     _require_non_empty(trace_id, "trace_id")
    113     return String(trace_id)
    114 
    115 
    116 def _require_input_value(json: Value) raises -> Value:
    117     if not _has_key(json, "input"):
    118         raise Error("request envelope field 'input' is required")
    119 
    120     var input = json["input"]
    121     if not input.is_object():
    122         raise Error("request envelope field 'input' must be a JSON object")
    123     return input.clone()
    124 
    125 
    126 @fieldwise_init
    127 struct WireRequest(Copyable, Deserializable, Movable):
    128     var version: Int
    129     var request_id: String
    130     var trace_id: Optional[String]
    131     var capability: String
    132     var context: RequestContext
    133     var input: Value
    134     # ADR-0025 D45 CB01: present only for a recognized hyf_ops_v2 request to one
    135     # of the three corrected operations. Legacy requests leave this None and
    136     # keep the unchanged legacy context.
    137     var operation_context: Optional[OperationContext]
    138 
    139     @staticmethod
    140     def from_json(json: Value) raises -> Self:
    141         _require_object(json, "request envelope")
    142         # ADR-0026 D46 CR04: reject ambiguous duplicate top-level keys before
    143         # first-wins lookup/selector dispatch for any envelope that targets a
    144         # corrected-operation capability or a v2 context selector. Unrelated
    145         # legacy capabilities keep their existing admission behavior.
    146         if envelope_targets_corrected_v2(json):
    147             var duplicate = _first_duplicate_root_key(json)
    148             if duplicate:
    149                 raise Error(
    150                     "request envelope contains duplicate top-level field '"
    151                     + duplicate.value()
    152                     + "'"
    153                 )
    154         _require_request_keys(json)
    155         var version = _require_protocol_version(json)
    156 
    157         var request_id = get_string(json, "request_id")
    158         _require_non_empty(request_id, "request_id")
    159 
    160         var trace_id = _parse_optional_trace_id(json)
    161 
    162         var capability = get_string(json, "capability")
    163         _require_non_empty(capability, "capability")
    164 
    165         var context_json = Value(None)
    166         if _has_key(json, "context"):
    167             context_json = json["context"].clone()
    168 
    169         var context = default_request_context()
    170         var operation_context: Optional[OperationContext] = None
    171         if is_corrected_operation(capability) and (
    172             operation_context_selects_v2(context_json)
    173             or operation_context_selects_v3(context_json)
    174         ):
    175             operation_context = parse_operation_context(
    176                 context_json.clone(), capability
    177             )
    178         else:
    179             context = parse_request_context(context_json)
    180         var input = _require_input_value(json)
    181 
    182         return Self(
    183             version=version,
    184             request_id=request_id,
    185             trace_id=trace_id^,
    186             capability=capability,
    187             context=context^,
    188             input=input^,
    189             operation_context=operation_context^,
    190         )
    191 
    192 
    193 @fieldwise_init
    194 struct WireSuccessResponse(Copyable, Movable):
    195     var version: Int
    196     var request_id: String
    197     var trace_id: Optional[String]
    198     var output: Value
    199     var meta: Optional[Value]
    200 
    201     def to_json_value(self) raises -> Value:
    202         var value = loads("{}")
    203         value.set("version", Value(self.version))
    204         value.set("request_id", Value(String(self.request_id)))
    205         if self.trace_id:
    206             value.set("trace_id", Value(String(self.trace_id.value())))
    207         value.set("ok", Value(True))
    208         value.set("output", self.output.clone())
    209         if self.meta:
    210             value.set("meta", self.meta.value().clone())
    211         return value^
    212 
    213 
    214 @fieldwise_init
    215 struct WireErrorResponse(Copyable, Movable):
    216     var version: Int
    217     var request_id: String
    218     var trace_id: Optional[String]
    219     var error: WireError
    220 
    221     def to_json_value(self) raises -> Value:
    222         var value = loads("{}")
    223         value.set("version", Value(self.version))
    224         value.set("request_id", Value(String(self.request_id)))
    225         if self.trace_id:
    226             value.set("trace_id", Value(String(self.trace_id.value())))
    227         value.set("ok", Value(False))
    228         value.set("error", self.error.to_json_value())
    229         return value^