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