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^