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