1# -*- coding: utf-8 -*- 2# 3# Check (context-free) QAPI schema expression structure 4# 5# Copyright IBM, Corp. 2011 6# Copyright (c) 2013-2019 Red Hat Inc. 7# 8# Authors: 9# Anthony Liguori <aliguori@us.ibm.com> 10# Markus Armbruster <armbru@redhat.com> 11# Eric Blake <eblake@redhat.com> 12# Marc-André Lureau <marcandre.lureau@redhat.com> 13# 14# This work is licensed under the terms of the GNU GPL, version 2. 15# See the COPYING file in the top-level directory. 16 17from collections import OrderedDict 18import re 19 20from .common import c_name 21from .error import QAPISemError 22 23 24# Names consist of letters, digits, -, and _, starting with a letter. 25# An experimental name is prefixed with x-. A name of a downstream 26# extension is prefixed with __RFQDN_. The latter prefix goes first. 27valid_name = re.compile(r'(__[a-z0-9.-]+_)?' 28 r'(x-)?' 29 r'([a-z][a-z0-9_-]*)$', re.IGNORECASE) 30 31 32def check_name_is_str(name, info, source): 33 if not isinstance(name, str): 34 raise QAPISemError(info, "%s requires a string name" % source) 35 36 37def check_name_str(name, info, source, 38 permit_upper=False): 39 # Reserve the entire 'q_' namespace for c_name(), and for 'q_empty' 40 # and 'q_obj_*' implicit type names. 41 match = valid_name.match(name) 42 if not match or c_name(name, False).startswith('q_'): 43 raise QAPISemError(info, "%s has an invalid name" % source) 44 if not permit_upper and name.lower() != name: 45 raise QAPISemError( 46 info, "%s uses uppercase in name" % source) 47 return match.group(3) 48 49 50def check_name_upper(name, info, source): 51 stem = check_name_str(name, info, source, permit_upper=True) 52 # TODO reject '[a-z-]' in @stem 53 54 55def check_name_lower(name, info, source, 56 permit_upper=False): 57 stem = check_name_str(name, info, source, permit_upper) 58 # TODO reject '_' in stem 59 60 61def check_name_camel(name, info, source): 62 stem = check_name_str(name, info, source, permit_upper=True) 63 # TODO reject '[_-]' in stem, require CamelCase 64 65 66def check_defn_name_str(name, info, meta): 67 if meta == 'event': 68 check_name_upper(name, info, meta) 69 elif meta == 'command': 70 check_name_lower(name, info, meta, permit_upper=True) 71 else: 72 check_name_camel(name, info, meta) 73 if name.endswith('Kind') or name.endswith('List'): 74 raise QAPISemError( 75 info, "%s name should not end in '%s'" % (meta, name[-4:])) 76 77 78def check_keys(value, info, source, required, optional): 79 80 def pprint(elems): 81 return ', '.join("'" + e + "'" for e in sorted(elems)) 82 83 missing = set(required) - set(value) 84 if missing: 85 raise QAPISemError( 86 info, 87 "%s misses key%s %s" 88 % (source, 's' if len(missing) > 1 else '', 89 pprint(missing))) 90 allowed = set(required + optional) 91 unknown = set(value) - allowed 92 if unknown: 93 raise QAPISemError( 94 info, 95 "%s has unknown key%s %s\nValid keys are %s." 96 % (source, 's' if len(unknown) > 1 else '', 97 pprint(unknown), pprint(allowed))) 98 99 100def check_flags(expr, info): 101 for key in ['gen', 'success-response']: 102 if key in expr and expr[key] is not False: 103 raise QAPISemError( 104 info, "flag '%s' may only use false value" % key) 105 for key in ['boxed', 'allow-oob', 'allow-preconfig', 'coroutine']: 106 if key in expr and expr[key] is not True: 107 raise QAPISemError( 108 info, "flag '%s' may only use true value" % key) 109 if 'allow-oob' in expr and 'coroutine' in expr: 110 # This is not necessarily a fundamental incompatibility, but 111 # we don't have a use case and the desired semantics isn't 112 # obvious. The simplest solution is to forbid it until we get 113 # a use case for it. 114 raise QAPISemError(info, "flags 'allow-oob' and 'coroutine' " 115 "are incompatible") 116 117 118def check_if(expr, info, source): 119 120 def check_if_str(ifcond, info): 121 if not isinstance(ifcond, str): 122 raise QAPISemError( 123 info, 124 "'if' condition of %s must be a string or a list of strings" 125 % source) 126 if ifcond.strip() == '': 127 raise QAPISemError( 128 info, 129 "'if' condition '%s' of %s makes no sense" 130 % (ifcond, source)) 131 132 ifcond = expr.get('if') 133 if ifcond is None: 134 return 135 if isinstance(ifcond, list): 136 if ifcond == []: 137 raise QAPISemError( 138 info, "'if' condition [] of %s is useless" % source) 139 for elt in ifcond: 140 check_if_str(elt, info) 141 else: 142 check_if_str(ifcond, info) 143 expr['if'] = [ifcond] 144 145 146def normalize_members(members): 147 if isinstance(members, OrderedDict): 148 for key, arg in members.items(): 149 if isinstance(arg, dict): 150 continue 151 members[key] = {'type': arg} 152 153 154def check_type(value, info, source, 155 allow_array=False, allow_dict=False): 156 if value is None: 157 return 158 159 # Array type 160 if isinstance(value, list): 161 if not allow_array: 162 raise QAPISemError(info, "%s cannot be an array" % source) 163 if len(value) != 1 or not isinstance(value[0], str): 164 raise QAPISemError(info, 165 "%s: array type must contain single type name" % 166 source) 167 return 168 169 # Type name 170 if isinstance(value, str): 171 return 172 173 # Anonymous type 174 175 if not allow_dict: 176 raise QAPISemError(info, "%s should be a type name" % source) 177 178 if not isinstance(value, OrderedDict): 179 raise QAPISemError(info, 180 "%s should be an object or type name" % source) 181 182 permit_upper = allow_dict in info.pragma.name_case_whitelist 183 184 # value is a dictionary, check that each member is okay 185 for (key, arg) in value.items(): 186 key_source = "%s member '%s'" % (source, key) 187 if key.startswith('*'): 188 key = key[1:] 189 check_name_lower(key, info, key_source, permit_upper) 190 if c_name(key, False) == 'u' or c_name(key, False).startswith('has_'): 191 raise QAPISemError(info, "%s uses reserved name" % key_source) 192 check_keys(arg, info, key_source, ['type'], ['if', 'features']) 193 check_if(arg, info, key_source) 194 check_features(arg.get('features'), info) 195 check_type(arg['type'], info, key_source, allow_array=True) 196 197 198def check_features(features, info): 199 if features is None: 200 return 201 if not isinstance(features, list): 202 raise QAPISemError(info, "'features' must be an array") 203 features[:] = [f if isinstance(f, dict) else {'name': f} 204 for f in features] 205 for f in features: 206 source = "'features' member" 207 assert isinstance(f, dict) 208 check_keys(f, info, source, ['name'], ['if']) 209 check_name_is_str(f['name'], info, source) 210 source = "%s '%s'" % (source, f['name']) 211 check_name_lower(f['name'], info, source) 212 check_if(f, info, source) 213 214 215def check_enum(expr, info): 216 name = expr['enum'] 217 members = expr['data'] 218 prefix = expr.get('prefix') 219 220 if not isinstance(members, list): 221 raise QAPISemError(info, "'data' must be an array") 222 if prefix is not None and not isinstance(prefix, str): 223 raise QAPISemError(info, "'prefix' must be a string") 224 225 permit_upper = name in info.pragma.name_case_whitelist 226 227 members[:] = [m if isinstance(m, dict) else {'name': m} 228 for m in members] 229 for member in members: 230 source = "'data' member" 231 member_name = member['name'] 232 check_keys(member, info, source, ['name'], ['if']) 233 check_name_is_str(member_name, info, source) 234 source = "%s '%s'" % (source, member_name) 235 # Enum members may start with a digit 236 if member_name[0].isdigit(): 237 member_name = 'd' + member_name # Hack: hide the digit 238 check_name_lower(member_name, info, source, permit_upper) 239 check_if(member, info, source) 240 241 242def check_struct(expr, info): 243 name = expr['struct'] 244 members = expr['data'] 245 246 check_type(members, info, "'data'", allow_dict=name) 247 check_type(expr.get('base'), info, "'base'") 248 249 250def check_union(expr, info): 251 name = expr['union'] 252 base = expr.get('base') 253 discriminator = expr.get('discriminator') 254 members = expr['data'] 255 256 if discriminator is None: # simple union 257 if base is not None: 258 raise QAPISemError(info, "'base' requires 'discriminator'") 259 else: # flat union 260 check_type(base, info, "'base'", allow_dict=name) 261 if not base: 262 raise QAPISemError(info, "'discriminator' requires 'base'") 263 check_name_is_str(discriminator, info, "'discriminator'") 264 265 for (key, value) in members.items(): 266 source = "'data' member '%s'" % key 267 if discriminator is None: 268 check_name_lower(key, info, source) 269 # else: name is in discriminator enum, which gets checked 270 check_keys(value, info, source, ['type'], ['if']) 271 check_if(value, info, source) 272 check_type(value['type'], info, source, allow_array=not base) 273 274 275def check_alternate(expr, info): 276 members = expr['data'] 277 278 if not members: 279 raise QAPISemError(info, "'data' must not be empty") 280 for (key, value) in members.items(): 281 source = "'data' member '%s'" % key 282 check_name_lower(key, info, source) 283 check_keys(value, info, source, ['type'], ['if']) 284 check_if(value, info, source) 285 check_type(value['type'], info, source) 286 287 288def check_command(expr, info): 289 args = expr.get('data') 290 rets = expr.get('returns') 291 boxed = expr.get('boxed', False) 292 293 if boxed and args is None: 294 raise QAPISemError(info, "'boxed': true requires 'data'") 295 check_type(args, info, "'data'", allow_dict=not boxed) 296 check_type(rets, info, "'returns'", allow_array=True) 297 298 299def check_event(expr, info): 300 args = expr.get('data') 301 boxed = expr.get('boxed', False) 302 303 if boxed and args is None: 304 raise QAPISemError(info, "'boxed': true requires 'data'") 305 check_type(args, info, "'data'", allow_dict=not boxed) 306 307 308def check_exprs(exprs): 309 for expr_elem in exprs: 310 expr = expr_elem['expr'] 311 info = expr_elem['info'] 312 doc = expr_elem.get('doc') 313 314 if 'include' in expr: 315 continue 316 317 if 'enum' in expr: 318 meta = 'enum' 319 elif 'union' in expr: 320 meta = 'union' 321 elif 'alternate' in expr: 322 meta = 'alternate' 323 elif 'struct' in expr: 324 meta = 'struct' 325 elif 'command' in expr: 326 meta = 'command' 327 elif 'event' in expr: 328 meta = 'event' 329 else: 330 raise QAPISemError(info, "expression is missing metatype") 331 332 name = expr[meta] 333 check_name_is_str(name, info, "'%s'" % meta) 334 info.set_defn(meta, name) 335 check_defn_name_str(name, info, meta) 336 337 if doc: 338 if doc.symbol != name: 339 raise QAPISemError( 340 info, "documentation comment is for '%s'" % doc.symbol) 341 doc.check_expr(expr) 342 elif info.pragma.doc_required: 343 raise QAPISemError(info, 344 "documentation comment required") 345 346 if meta == 'enum': 347 check_keys(expr, info, meta, 348 ['enum', 'data'], ['if', 'features', 'prefix']) 349 check_enum(expr, info) 350 elif meta == 'union': 351 check_keys(expr, info, meta, 352 ['union', 'data'], 353 ['base', 'discriminator', 'if', 'features']) 354 normalize_members(expr.get('base')) 355 normalize_members(expr['data']) 356 check_union(expr, info) 357 elif meta == 'alternate': 358 check_keys(expr, info, meta, 359 ['alternate', 'data'], ['if', 'features']) 360 normalize_members(expr['data']) 361 check_alternate(expr, info) 362 elif meta == 'struct': 363 check_keys(expr, info, meta, 364 ['struct', 'data'], ['base', 'if', 'features']) 365 normalize_members(expr['data']) 366 check_struct(expr, info) 367 elif meta == 'command': 368 check_keys(expr, info, meta, 369 ['command'], 370 ['data', 'returns', 'boxed', 'if', 'features', 371 'gen', 'success-response', 'allow-oob', 372 'allow-preconfig', 'coroutine']) 373 normalize_members(expr.get('data')) 374 check_command(expr, info) 375 elif meta == 'event': 376 check_keys(expr, info, meta, 377 ['event'], ['data', 'boxed', 'if', 'features']) 378 normalize_members(expr.get('data')) 379 check_event(expr, info) 380 else: 381 assert False, 'unexpected meta type' 382 383 check_if(expr, info, meta) 384 check_features(expr.get('features'), info) 385 check_flags(expr, info) 386 387 return exprs 388