Coverage for /home/runner/work/viur-core/viur-core/viur/src/viur/core/config.py: 89%

394 statements  

« prev     ^ index     » next       coverage.py v7.17.3, created at 2026-11-13 06:58 +0000

1import datetime 

2import hashlib 

3import logging 

4import os 

5import re 

6import reprlib 

7import typing as t 

8import warnings 

9from pathlib import Path 

10 

11import google.auth 

12from google.appengine.api.memcache import Client 

13 

14from viur.core.version import __version__ 

15from viur.core.current import user as current_user 

16 

17if t.TYPE_CHECKING: # pragma: no cover 

18 from viur.core.bones.text import HtmlBoneConfiguration 

19 from viur.core.email import EmailTransport 

20 from viur.core.skeleton import SkeletonInstance 

21 from viur.core.module import Module 

22 from viur.core.tasks import CustomEnvironmentHandler 

23 from viur.core import i18n 

24 

25# Construct an alias with a generic type to be able to write Multiple[str] 

26# TODO: Backward compatible implementation, refactor when viur-core 

27# becomes >= Python 3.12 with a type statement (PEP 695) 

28_T = t.TypeVar("_T") 

29Multiple: t.TypeAlias = list[_T] | tuple[_T] | set[_T] | frozenset[_T] # TODO: Refactor for Python 3.12 

30 

31 

32 

33 

34class ConfigType: 

35 """An abstract class for configurations. 

36 

37 It ensures nesting and backward compatibility for the viur-core config 

38 """ 

39 _mapping = {} 

40 """Mapping from old dict-key (must not be the entire key in case of nesting) to new attribute name""" 

41 

42 _strict_mode = None 

43 """Internal strict mode for this instance. 

44 

45 Use the property getter and setter to access it!""" 

46 

47 _parent = None 

48 """Parent config instance""" 

49 

50 def __init__(self, *, 

51 strict_mode: bool = None, 

52 parent: t.Union["ConfigType", None] = None): 

53 super().__init__() 

54 self._strict_mode = strict_mode 

55 self._parent = parent 

56 

57 @property 

58 def _path(self): 

59 """Get the path in dot-Notation to the current config instance.""" 

60 if self._parent is None: 

61 return "" 

62 return f"{self._parent._path}{self.__class__.__name__.lower()}." 

63 

64 @property 

65 def strict_mode(self): 

66 """Determine if the config runs in strict mode. 

67 

68 In strict mode, the dict-item-access backward compatibility is disabled, 

69 only attribute access is allowed. 

70 Alias mapping is also disabled. Only the real attribute names are allowed. 

71 

72 If self._strict_mode is None, it would inherit the value 

73 of the parent. 

74 If it's explicitly set to True or False, that value will be used. 

75 """ 

76 if self._strict_mode is not None or self._parent is None: 

77 # This config has an explicit value set or there's no parent 

78 return self._strict_mode 

79 else: 

80 # no value set: inherit from the parent 

81 return self._parent.strict_mode 

82 

83 @strict_mode.setter 

84 def strict_mode(self, value: bool | None) -> None: 

85 """Setter for the strict mode of the current instance. 

86 

87 Does not affect other instances! 

88 """ 

89 if not isinstance(value, (bool, type(None))): 

90 raise TypeError(f"Invalid {value=} for strict mode!") 

91 self._strict_mode = value 

92 

93 def _resolve_mapping(self, key: str) -> str: 

94 """Resolve the mapping old dict -> new attribute. 

95 

96 This method must not be called in strict mode! 

97 It can be overwritten to apply additional mapping. 

98 """ 

99 if key in self._mapping: 

100 old, key = key, self._mapping[key] 

101 warnings.warn( 

102 f"Conf member {self._path}{old} is now {self._path}{key}!", 

103 DeprecationWarning, 

104 stacklevel=3, 

105 ) 

106 return key 

107 

108 def items(self, 

109 full_path: bool = False, 

110 recursive: bool = True, 

111 ) -> t.Iterator[tuple[str, t.Any]]: 

112 """Get all setting of this config as key-value mapping. 

113 

114 :param full_path: Show prefix oder only the key. 

115 :param recursive: Call .items() on ConfigType members (children)? 

116 :return: 

117 """ 

118 for key in dir(self): 

119 if key.startswith("_"): 

120 # skip internals, like _parent and _strict_mode 

121 continue 

122 value = getattr(self, key) 

123 if recursive and isinstance(value, ConfigType): 

124 yield from value.items(full_path, recursive) 

125 elif key not in dir(ConfigType): 

126 if full_path: 126 ↛ 127line 126 didn't jump to line 127 because the condition on line 126 was never true

127 yield f"{self._path}{key}", value 

128 else: 

129 yield key, value 

130 

131 def get(self, key: str, default: t.Any = None) -> t.Any: 

132 """Return an item from the config, if it doesn't exist `default` is returned. 

133 

134 :param key: The key for the attribute lookup. 

135 :param default: The fallback value. 

136 :return: The attribute value or the fallback value. 

137 """ 

138 if self.strict_mode: 

139 raise SyntaxError( 

140 "In strict mode, the config must not be accessed " 

141 "with .get(). Only attribute access is allowed." 

142 ) 

143 try: 

144 return getattr(self, key) 

145 except (KeyError, AttributeError): 

146 return default 

147 

148 def __getitem__(self, key: str) -> t.Any: 

149 """Support the old dict-like syntax (getter). 

150 

151 Not allowed in strict mode. 

152 """ 

153 new_path = f"{self._path}{self._resolve_mapping(key)}" 

154 warnings.warn(f"conf uses now attributes! " 

155 f"Use conf.{new_path} to access your option", 

156 DeprecationWarning, 

157 stacklevel=2) 

158 

159 if self.strict_mode: 

160 raise SyntaxError( 

161 f"In strict mode, the config must not be accessed " 

162 f"with dict notation. " 

163 f"Only attribute access (conf.{new_path}) is allowed." 

164 ) 

165 

166 return getattr(self, key) 

167 

168 def __getattr__(self, key: str) -> t.Any: 

169 """Resolve dot-notation and name mapping in not strict mode. 

170 

171 This method is mostly executed by __getitem__, by the 

172 old dict-like access or by attr(conf, "key"). 

173 In strict mode it does nothing except raising an AttributeError. 

174 """ 

175 if self.strict_mode: 

176 raise AttributeError( 

177 f"AttributeError: '{self.__class__.__name__}' object has no" 

178 f" attribute '{key}' (strict mode is enabled)" 

179 ) 

180 

181 key = self._resolve_mapping(key) 

182 

183 # Got an old dict-key and resolve the segment to the first dot (.) as attribute. 

184 if "." in key: 

185 first, remaining = key.split(".", 1) 

186 return getattr(getattr(self, first), remaining) 

187 

188 return super().__getattribute__(key) 

189 

190 def __setitem__(self, key: str, value: t.Any) -> None: 

191 """Support the old dict-like syntax (setter). 

192 

193 Not allowed in strict mode. 

194 """ 

195 new_path = f"{self._path}{self._resolve_mapping(key)}" 

196 if self.strict_mode: 

197 raise SyntaxError( 

198 f"In strict mode, the config must not be accessed " 

199 f"with dict notation. " 

200 f"Only attribute access (conf.{new_path}) is allowed." 

201 ) 

202 

203 # TODO: re-enable?! 

204 # Avoid to set conf values to something which is already the default 

205 # if key in self and self[key] == value: 

206 # msg = f"Setting conf[\"{key}\"] to {value!r} has no effect, as this value has already been set" 

207 # warnings.warn(msg, stacklevel=3) 

208 # logging.warning(msg, stacklevel=3) 

209 # return 

210 

211 key = self._resolve_mapping(key) 

212 

213 # Got an old dict-key and resolve the segment to the first dot (.) as attribute. 

214 if "." in key: 

215 first, remaining = key.split(".", 1) 

216 if not hasattr(self, first): 

217 # TODO: Compatibility, remove it in a future major release! 

218 # This segment doesn't exist. Create it 

219 logging.warning(f"Creating new type for {first}") 

220 setattr(self, first, type(first.capitalize(), (ConfigType,), {})()) 

221 getattr(self, first)[remaining] = value 

222 return 

223 

224 return setattr(self, key, value) 

225 

226 def __setattr__(self, key: str, value: t.Any) -> None: 

227 """Set attributes after applying the old -> new mapping 

228 

229 In strict mode it does nothing except a super call 

230 for the default object behavior. 

231 """ 

232 if self.strict_mode: 

233 return super().__setattr__(key, value) 

234 

235 if not self.strict_mode: 235 ↛ 239line 235 didn't jump to line 239 because the condition on line 235 was always true

236 key = self._resolve_mapping(key) 

237 

238 # Got an old dict-key and resolve the segment to the first dot (.) as attribute. 

239 if "." in key: 239 ↛ 241line 239 didn't jump to line 241 because the condition on line 239 was never true

240 # TODO: Shall we allow this in strict mode as well? 

241 first, remaining = key.split(".", 1) 

242 return setattr(getattr(self, first), remaining, value) 

243 

244 return super().__setattr__(key, value) 

245 

246 @reprlib.recursive_repr() 

247 def __repr__(self) -> str: 

248 """Representation of this config""" 

249 return f"{self.__class__.__qualname__}({dict(self.items(False, False))})" 

250 

251 

252# Some values used more than once below 

253_project_id = google.auth.default()[1] 

254_app_version = os.getenv("GAE_VERSION") 

255 

256# Determine our basePath (as os.getCWD is broken on appengine) 

257_project_base_path = Path().absolute() 

258_core_base_path = Path(__file__).parent.parent.parent # fixme: this points to site-packages!!! 

259 

260 

261class Admin(ConfigType): 

262 """Administration tool configuration""" 

263 

264 name: str = "ViUR" 

265 """Administration tool configuration""" 

266 

267 logo: str = "" 

268 """URL for the Logo in the Topbar of the VI""" 

269 

270 login_background: str = "" 

271 """URL for the big Image in the background of the VI Login screen""" 

272 

273 login_logo: str = "" 

274 """URL for the Logo over the VI Login screen""" 

275 

276 color_primary: str = "#d00f1c" 

277 """primary color for viur-admin""" 

278 

279 color_secondary: str = "#333333" 

280 """secondary color for viur-admin""" 

281 

282 module_groups: dict[str, dict[t.Literal["name", "icon", "sortindex"], str | int]] = {} 

283 """Module Groups for the admin tool 

284 

285 Group modules in the sidebar in categories (groups). 

286 

287 Example: 

288 conf.admin.module_groups = { 

289 "content": { 

290 "name": "Content", 

291 "icon": "file-text-fill", 

292 "sortindex": 10, 

293 }, 

294 "shop": { 

295 "name": "Shop", 

296 "icon": "cart-fill", 

297 "sortindex": 20, 

298 }, 

299 } 

300 

301 To add a module to one of these groups (e.g. content), add `moduleGroup` to 

302 the admin_info of the module: 

303 "moduleGroup": "content", 

304 """ 

305 

306 _mapping: dict[str, str] = { 

307 "login.background": "login_background", 

308 "login.logo": "login_logo", 

309 "color.primary": "color_primary", 

310 "color.secondary": "color_secondary", 

311 } 

312 

313 

314class Database(ConfigType): 

315 query_external_limit: int = 100 

316 """Sets the maximum query limit allowed by external filters.""" 

317 

318 query_default_limit: int = 30 

319 """Sets the default query limit for all queries.""" 

320 

321 memcache_client: Client | None = None 

322 """If set, ViUR cache data for the db.get in the Memcache for faster access.""" 

323 

324 create_access_log: bool = True 

325 """If False no access log will be created. But then the caching is disabled too.""" 

326 

327 transaction_attempts: int = 3 

328 """How often :func:`db.run_in_transaction <viur.core.db.transport.run_in_transaction>` runs 

329 a transaction before giving up on conflicts; must be at least 1. Retries back off exponentially 

330 (1s, 2s, 4s, ...).""" 

331 

332 name: str | None = os.getenv("VIUR_DB_NAME") or None 

333 """Named datastore to target instead of ``(default)``. 

334 

335 Env-sourced: the client is built at ``db.transport`` import time, before any 

336 runtime config could set it.""" 

337 

338 namespace: str | None = os.getenv("VIUR_DB_NAMESPACE") or None 

339 """Datastore namespace to scope to. Env-sourced like `name`.""" 

340 

341 

342class Security(ConfigType): 

343 """Security related settings""" 

344 

345 force_ssl: bool = True 

346 """If true, all requests must be encrypted (ignored on development server)""" 

347 

348 no_ssl_check_urls: Multiple[str] = ["/_tasks*", "/ah/*"] 

349 """List of URLs for which force_ssl is ignored. 

350 Add an asterisk to mark that entry as a prefix (exact match otherwise)""" 

351 

352 content_security_policy: t.Optional[dict[str, dict[str, list[str]]]] = { 

353 "enforce": { 

354 "style-src": ["self", "https://accounts.google.com/gsi/style"], 

355 "default-src": ["self"], 

356 "img-src": ["self", "storage.googleapis.com"], # Serving-URLs of file-Bones will point here 

357 "script-src": ["self", "https://accounts.google.com/gsi/client"], 

358 # Required for login with Google 

359 "frame-src": ["self", "www.google.com", "drive.google.com", "accounts.google.com"], 

360 "form-action": ["self"], 

361 "connect-src": ["self", "accounts.google.com"], 

362 "upgrade-insecure-requests": [], 

363 "object-src": ["none"], 

364 } 

365 } 

366 """If set, viur will emit a CSP http-header with each request. Use security.addCspRule to set this property""" 

367 

368 reporting_endpoints: dict[str, str] = {} 

369 """Named endpoints reports are being sent to, emitted as ``Reporting-Endpoints`` http-header. 

370 

371 Maps an endpoint name to the URL receiving the reports. Other headers reference these names, 

372 for example the CSP-directive ``report-to``, which supersedes the deprecated ``report-uri``. 

373 The name ``default`` is used by the browser for reports whose header cannot name an endpoint 

374 on its own (i.e. deprecation reports). 

375 

376 Use :func:`~viur.core.securityheaders.set_reporting_endpoint` to set this property. 

377 

378 See https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Reporting-Endpoints 

379 """ 

380 

381 referrer_policy: str = "strict-origin" 

382 """Per default, we'll emit Referrer-Policy: strict-origin so no referrers leak to external services 

383 

384 See https://www.w3.org/TR/referrer-policy/ 

385 """ 

386 

387 permissions_policy: dict[str, list[str]] = { 

388 "autoplay": ["self"], 

389 "camera": [], 

390 "display-capture": [], 

391 "document-domain": [], 

392 "encrypted-media": [], 

393 "fullscreen": [], 

394 "geolocation": [], 

395 "microphone": [], 

396 "publickey-credentials-get": [], 

397 "usb": [], 

398 } 

399 """Include a default permissions-policy. 

400 To use the camera or microphone, you'll have to call 

401 :meth: securityheaders.setPermissionPolicyDirective to include at least "self" 

402 """ 

403 

404 enable_coep: bool = False 

405 """Shall we emit Cross-Origin-Embedder-Policy: require-corp?""" 

406 

407 enable_coop: t.Literal[ 

408 "unsafe-none", "same-origin-allow-popups", 

409 "same-origin", "same-origin-plus-COEP"] = "same-origin" 

410 """Emit a Cross-Origin-Opener-Policy Header? 

411 

412 See https://html.spec.whatwg.org/multipage/browsers.html#cross-origin-opener-policy-value 

413 """ 

414 

415 enable_corp: t.Literal["same-origin", "same-site", "cross-origin"] = "same-origin" 

416 """Emit a Cross-Origin-Resource-Policy Header? 

417 

418 See https://fetch.spec.whatwg.org/#cross-origin-resource-policy-header 

419 """ 

420 

421 strict_transport_security: t.Optional[str] = "max-age=22118400" 

422 """If set, ViUR will emit a HSTS HTTP-header with each request. 

423 Use security.enableStrictTransportSecurity to set this property""" 

424 

425 x_frame_options: t.Optional[ 

426 tuple[t.Literal["deny", "sameorigin", "allow-from"], t.Optional[str]] 

427 ] = ("sameorigin", None) 

428 """If set, ViUR will emit an X-Frame-Options header 

429 

430 In case of allow-from, the second parameters must be the host-url. 

431 Otherwise, it can be None. 

432 """ 

433 

434 x_xss_protection: t.Optional[bool] = True 

435 """ViUR will emit an X-XSS-Protection header if set (the default)""" 

436 

437 x_content_type_options: bool = True 

438 """ViUR will emit X-Content-Type-Options: nosniff Header unless set to False""" 

439 

440 x_permitted_cross_domain_policies: t.Optional[t.Literal["none", "master-only", "by-content-type", "all"]] = "none" 

441 """Unless set to logical none; ViUR will emit a X-Permitted-Cross-Domain-Policies with each request""" 

442 

443 captcha_default_public_key: t.Optional[str] = None 

444 """The default sitekey and secret to use for the :class:`CaptchaBone`. 

445 If set, must be a dictionary of "sitekey" and "secret". 

446 """ 

447 

448 captcha_enforce_always: bool = False 

449 """By default a captcha of the :class:`CaptchaBone` must not be solved on a local development server 

450 or by a root user. But for development it can be helpful to test the implementation 

451 on a local development server. Setting this flag to True, disables this behavior and 

452 enforces always a valid captcha. 

453 """ 

454 

455 password_recovery_key_length: int = 42 

456 """Length of the Password recovery key""" 

457 

458 closed_system: bool = False 

459 """If `True` it activates a mode in which only authenticated users can access all routes.""" 

460 

461 admin_allowed_paths: t.Iterable[str] = [ 

462 "vi", 

463 "vi/config", 

464 "vi/skey", 

465 "vi/user/auth_*", 

466 "vi/user/f2_*", 

467 "vi/user/login", 

468 "vi/user/select_authentication_provider", 

469 # DEPRECATED: 

470 "vi/settings", # FIXME: Deprecated; vi-admin 4.x backward compatiblity 

471 "vi/user/getAuthMethods", # FIXME: Deprecated; vi-admin 4.x backward compatiblity 

472 ] 

473 """Specifies admin tool paths which are being accessible without authenticated user.""" 

474 

475 closed_system_allowed_paths: t.Iterable[str] = admin_allowed_paths + [ 

476 "", # index site 

477 "json/skey", 

478 "json/user/auth_*", 

479 "json/user/f2_*", 

480 "json/user/getAuthMethods", # FIXME: deprecated, use `login` for this 

481 "json/user/login", 

482 "user/auth_*", 

483 "user/f2_*", 

484 "user/getAuthMethods", # FIXME: deprecated, use `login` for this 

485 "user/select_authentication_provider", 

486 "user/login", 

487 ] 

488 """Paths that are accessible without authentication in a closed system, see `closed_system` for details.""" 

489 

490 # CORS Settings 

491 

492 cors_origins: t.Iterable[str | re.Pattern] | t.Literal["*"] = [] 

493 r"""Allowed origins 

494 Access-Control-Allow-Origin 

495 

496 Pattern should be case-insensitive, for example: 

497 >>> re.compile(r"^http://localhost:(\d{4,5})/?$", flags=re.IGNORECASE) 

498 """ # noqa 

499 

500 cors_origins_use_wildcard: bool = False 

501 """Use * for Access-Control-Allow-Origin -- if possible""" 

502 

503 cors_methods: t.Iterable[str] = ["get", "head", "post", "options"] # , "put", "patch", "delete"] 

504 """Access-Control-Request-Method""" 

505 

506 cors_allow_headers: t.Iterable[str | re.Pattern] | t.Literal["*"] = [] 

507 """Access-Control-Request-Headers 

508 

509 Can also be set for specific @exposed methods with the @cors decorator. 

510 

511 Pattern should be case-insensitive, for example: 

512 >>> re.compile(r"^X-ViUR-.*$", flags=re.IGNORECASE) 

513 """ 

514 

515 cors_allow_credentials: bool = False 

516 """ 

517 Set Access-Control-Allow-Credentials to true 

518 to support fetch requests with credentials: include 

519 """ 

520 

521 cors_max_age: datetime.timedelta | None = None 

522 """Allow caching""" 

523 

524 _mapping = { 

525 "contentSecurityPolicy": "content_security_policy", 

526 "referrerPolicy": "referrer_policy", 

527 "permissionsPolicy": "permissions_policy", 

528 "enableCOEP": "enable_coep", 

529 "enableCOOP": "enable_coop", 

530 "enableCORP": "enable_corp", 

531 "strictTransportSecurity": "strict_transport_security", 

532 "xFrameOptions": "x_frame_options", 

533 "xXssProtection": "x_xss_protection", 

534 "xContentTypeOptions": "x_content_type_options", 

535 "xPermittedCrossDomainPolicies": "x_permitted_cross_domain_policies", 

536 } 

537 

538 

539class Debug(ConfigType): 

540 """Several debug flags""" 

541 

542 trace: bool = False 

543 """If enabled, trace any routing, HTTPExceptions and decorations for debugging and insight""" 

544 

545 trace_exceptions: bool = False 

546 """If enabled, user-generated exceptions from the viur.core.errors module won't be caught and handled""" 

547 

548 trace_external_call_routing: bool = False 

549 """If enabled, ViUR will log which (exposed) function are called from outside with what arguments""" 

550 

551 trace_internal_call_routing: bool = False 

552 """If enabled, ViUR will log which (internal-exposed) function are called from templates with what arguments""" 

553 

554 trace_queries: bool = False 

555 """If enabled, ViUR will log each query that run""" 

556 

557 skeleton_from_client: bool = False 

558 """If enabled, log errors raises from skeleton.fromClient()""" 

559 

560 dev_server_cloud_logging: bool = False 

561 """If disabled the local logging will not send with requestLogger to the cloud""" 

562 

563 disable_cache: bool = False 

564 """If set to true, the decorator @enableCache from viur.core.cache has no effect""" 

565 

566 _mapping = { 

567 "skeleton.fromClient": "skeleton_from_client", 

568 "traceExceptions": "trace_exceptions", 

569 "traceExternalCallRouting": "trace_external_call_routing", 

570 "traceInternalCallRouting": "trace_internal_call_routing", 

571 "skeleton_fromClient": "skeleton_from_client", 

572 "disableCache": "disable_cache", 

573 } 

574 

575 

576class Email(ConfigType): 

577 """Email related settings.""" 

578 

579 log_retention: datetime.timedelta = datetime.timedelta(days=30) 

580 """For how long we'll keep successfully send emails in the viur-emails table""" 

581 

582 transport_class: "EmailTransport" = None 

583 """EmailTransport instance that actually delivers the email using the service provider 

584 of choice. See :module:`core.email` for more details 

585 """ 

586 

587 send_from_local_development_server: bool = False 

588 """If set, we'll enable sending emails from the local development server. 

589 Otherwise, they'll just be logged. 

590 """ 

591 

592 recipient_override: str | list[str] | t.Callable[[], str | list[str]] | t.Literal[False] = None 

593 """If set, all outgoing emails will be sent to this address 

594 (overriding the 'dests'-parameter in :meth:`core.email.send_email`) 

595 """ 

596 

597 sender_default: str = f"viur@{_project_id}.appspotmail.com" 

598 """This sender is used by default for emails. 

599 It can be overridden for a specific email by passing the `sender` argument 

600 to :meth:`core.email.send_email` or for all emails with :attr:`sender_override`. 

601 """ 

602 

603 sender_override: str | None = None 

604 """If set, this sender will be used, regardless of what the templates advertise as sender""" 

605 

606 admin_recipients: str | list[str] | t.Callable[[], str | list[str]] = None 

607 """Sets recipients for mails send with :meth:`core.email.send_email_to_admins`. 

608 If not set, all root users will be used.""" 

609 

610 _mapping = { 

611 "logRetention": "log_retention", 

612 "transportClass": "transport_class", 

613 "sendFromLocalDevelopmentServer": "send_from_local_development_server", 

614 "recipientOverride": "recipient_override", 

615 "senderOverride": "sender_override", 

616 "sendInBlue.apiKey": "sendinblue_api_key", 

617 "sendInBlue.thresholds": "sendinblue_thresholds", 

618 } 

619 

620 

621class History(ConfigType): 

622 databases: Multiple[str] = ["viur"] 

623 """All history related settings.""" 

624 excluded_actions: Multiple[str] = [] 

625 """List of all action that are should not be logged.""" 

626 excluded_kinds: Multiple[str] = [] 

627 """List of all kinds that should be logged.""" 

628 

629 

630class I18N(ConfigType): 

631 """All i18n, multilang related settings.""" 

632 

633 available_languages: Multiple[str] = ["en"] 

634 """List of language-codes, which are valid for this application""" 

635 

636 default_language: str = "en" 

637 """Unless overridden by the Project: Use english as default language""" 

638 

639 domain_language_mapping: dict[str, str] = {} 

640 """Maps Domains to alternative default languages""" 

641 

642 language_alias_map: dict[str, str] = {} 

643 """Allows mapping of certain languages to one translation (i.e. us->en)""" 

644 

645 fallback_languages: Multiple[str] = [] 

646 """Languages tried in order when the requested language has no translation""" 

647 

648 sources: Multiple["i18n.TranslationSource"] = None 

649 """Translation sources, loaded in order; None uses i18n.DEFAULT_TRANSLATION_SOURCES""" 

650 

651 language_method: t.Literal["session", "url", "domain", "header"] = "session" 

652 """Defines how translations are applied: 

653 - session: Per Session 

654 - url: inject language prefix in url 

655 - domain: one domain per language 

656 - header: Per Http-Header 

657 """ 

658 

659 language_module_map: dict[str, dict[str, str]] = {} 

660 """Maps modules to their translation (if set)""" 

661 

662 auto_translate_bones: bool = True 

663 """Defines whether bone descr and categories should be automatically translated via i18n.translate-objects.""" 

664 

665 @property 

666 def available_dialects(self) -> list[str]: 

667 """Main languages and language aliases""" 

668 # Use a dict to keep the order and remove duplicates 

669 res = dict.fromkeys(self.available_languages) 

670 res |= self.language_alias_map 

671 return list(res.keys()) 

672 

673 add_missing_translations: (bool | str | t.Iterable[str] | "i18n.AddMissing" 

674 | t.Callable[["i18n.translate"], t.Union[bool, "i18n.AddMissing"]]) = False 

675 """Add missing translation into datastore, optionally with given fnmatch-patterns. 

676 

677 If a key is not found in the translation table when a translation is 

678 rendered, a database entry is created with the key and hint and 

679 default value (if set) so that the translations 

680 can be entered in the administration. 

681 

682 Instead of setting add_missing_translations to a boolean, it can also be set to 

683 a pattern or iterable of fnmatch-patterns; Only translation keys matching these 

684 patterns will be automatically added. 

685 If a callable is provided, it will be called with the translation object to make a complex decision. 

686 """ 

687 

688 def _dump_can_view(self, _key): 

689 return bool(current_user.get()) 

690 

691 dump_can_view: t.Callable[[t.Self, str], bool] = _dump_can_view 

692 """Customizable callback for translation.dump() to verify if a specific translation key can be queried. 

693 

694 This logic is omitted for translations flagged public.""" 

695 

696 

697class User(ConfigType): 

698 """User, session, login related settings""" 

699 

700 access_rights: Multiple[str] = [ 

701 "root", 

702 "admin", 

703 "scriptor", 

704 ] 

705 """Additional access flags available for users on this project. 

706 

707 There are three default flags: 

708 - `root` is allowed to view/add/edit/delete any module, regardless of role or other settings 

709 - `admin` is allowed to use the ViUR administration tool 

710 - `scriptor` is allowed to use the ViUR scripting features directly within the admin 

711 This does not affect scriptor actions which are configured for modules, as they allow for 

712 fine grained usage rule definitions. 

713 """ 

714 

715 roles: dict[str, str] = { 

716 "custom": "Custom", 

717 "user": "User", 

718 "viewer": "Viewer", 

719 "editor": "Editor", 

720 "admin": "Administrator", 

721 } 

722 """User roles available on this project. 

723 

724 The roles can be individually defined per module, see `Module.roles`. 

725 

726 The default roles can be described as follows: 

727 

728 - `custom` for users with a custom-settings via the `User.access`-bone; includes root users. 

729 - `user` for users without any additonal rights. They can log-in and view themselves, or particular modules which 

730 just check for authenticated users. 

731 - `viewer` for users who should only view content. 

732 - `editor` for users who are allowed to edit particular content. They mostly can `view` and `edit`, but not `add` 

733 or `delete`. 

734 - `admin` for users with administration privileges. They can edit any data, but still aren't `root`. 

735 

736 The preset roles are for guidiance, and already fit to most projects. 

737 """ 

738 

739 session_life_time: datetime.timedelta = datetime.timedelta(hours=1) 

740 """Default is 60 minutes lifetime for ViUR sessions""" 

741 

742 session_persistent_fields_on_login: Multiple[str] = ["language"] 

743 """If set, these Fields will survive the session.reset() called on user/login""" 

744 

745 session_persistent_fields_on_logout: Multiple[str] = ["language"] 

746 """If set, these Fields will survive the session.reset() called on user/logout""" 

747 

748 max_password_length: int = 512 

749 """Prevent Denial of Service attacks using large inputs for pbkdf2""" 

750 

751 otp_issuer: t.Optional[str] = None 

752 """The name of the issuer for the opt token""" 

753 

754 google_client_id: t.Optional[str] = None 

755 """OAuth Client ID for Google Login""" 

756 

757 google_gsuite_domains: list[str] = [] 

758 """A list of domains. When a user signs in for the first time with a 

759 Google account using Google OAuth sign-in, and the user's email address 

760 belongs to one of the listed domains, a user account (UserSkel) is created. 

761 If the user's email address belongs to any other domain, 

762 no account is created.""" 

763 

764 app_login_access: t.Optional[t.Iterable[str | t.Iterable[str]]] = None 

765 """Access rights required to use the App Login Flow (``get_cookie_for_app``). 

766 

767 ``None`` allows every authenticated user; the created session carries exactly the rights 

768 the user already has. Otherwise the format of :func:`viur.core.decorators.access` applies, 

769 e.g. ``("admin",)`` to restrict it to administrators. Users with ``root`` always pass. 

770 """ 

771 

772 redirect_whitelist: list[str] | t.Callable[[], list[str]] = ( 

773 lambda _: [ 

774 "http://localhost:*", 

775 f"https://{_project_id}.appspot.com", 

776 f"https://*-dot-{_project_id}.appspot.com", 

777 ] 

778 ) 

779 """Allowed redirect_to patterns for get_cookie_for_app. 

780 

781 Each pattern is a URL whose scheme, host, port and path are matched separately against 

782 the target via :func:`fnmatch.fnmatchcase`, so a wildcard never reaches beyond its 

783 component (e.g. ``https://*.example.com`` does not match ``https://evil.test/?.example.com``). 

784 A pattern without a port only matches URLs without an explicit port, a pattern without 

785 a path matches any path. URLs with user info (``user@host``) are always rejected. 

786 

787 The default is a callable that permits ``http://localhost`` on any port and the 

788 App Engine hosts of the current GCP project (including versions and services, 

789 ``*-dot-<project>.appspot.com``). 

790 A zero-argument callable is supported and evaluated on every request. 

791 Use ``["*"]`` to disable the restriction entirely. 

792 

793 Examples:: 

794 

795 conf.user.redirect_whitelist = [ 

796 "http://localhost:*", 

797 "https://*-dot-myapp.appspot.com", 

798 "https://tools.example.com/callback/*", 

799 ] 

800 

801 # dynamic / lazily evaluated 

802 conf.user.redirect_whitelist = lambda: load_whitelist_from_db() 

803 """ 

804 

805 def __setattr__(self, name: str, value: t.Any) -> None: 

806 if name == "session_life_time": 806 ↛ 807line 806 didn't jump to line 807 because the condition on line 806 was never true

807 if not isinstance(value, datetime.timedelta): 

808 from viur.core import utils 

809 warnings.warn( 

810 "Please use timedelta to set session_life_time.", 

811 DeprecationWarning, stacklevel=2, 

812 ) 

813 value = utils.parse.timedelta(value) 

814 super().__setattr__(name, value) 

815 

816 

817class Instance(ConfigType): 

818 """All app instance related settings information""" 

819 app_version: str = _app_version 

820 """Name of this version as deployed to the appengine""" 

821 

822 core_base_path: Path = _core_base_path 

823 """The base path of the core, can be used to find file in the core folder""" 

824 

825 is_dev_server: bool = os.getenv("GAE_ENV") == "localdev" 

826 """Determine whether instance is running on a local development server""" 

827 

828 project_base_path: Path = _project_base_path 

829 """The base path of the project, can be used to find file in the project folder""" 

830 

831 project_id: str = _project_id 

832 """The instance's project ID""" 

833 

834 version_hash: str = hashlib.sha256(f"{_app_version}{project_id}".encode("UTF-8")).hexdigest()[:10] 

835 """Version hash that does not reveal the actual version name, can be used for cache-busting static resources""" 

836 

837 

838class Conf(ConfigType): 

839 """Conf class wraps the conf dict and allows to handle 

840 deprecated keys or other special operations. 

841 """ 

842 

843 bone_boolean_str2true: Multiple[str | int] = ("true", "yes", "1") 

844 """Allowed values that define a str to evaluate to true""" 

845 

846 bone_string_escape_html: bool = True 

847 """Default escape_html setting for StringBone. Set to False to disable HTML escaping globally.""" 

848 

849 bone_strict_mode: bool = os.getenv("VIUR_CORE_BONE_STRICT_MODE", "").lower() != "false" 

850 """If enabled (the default), setting an *unknown* attribute on a bone after its construction 

851 raises an AttributeError instead of silently creating it -- this catches typos like ``readonly`` 

852 instead of ``readOnly``. Disable via ``conf.bone_strict_mode = False`` or the environment 

853 variable ``VIUR_CORE_BONE_STRICT_MODE=false``.""" 

854 

855 bone_html_default_allow: "HtmlBoneConfiguration" = { 

856 "validTags": [ 

857 "a", 

858 "abbr", 

859 "b", 

860 "blockquote", 

861 "br", 

862 "div", 

863 "em", 

864 "h1", 

865 "h2", 

866 "h3", 

867 "h4", 

868 "h5", 

869 "h6", 

870 "hr", 

871 "i", 

872 "img", 

873 "li", 

874 "ol", 

875 "p", 

876 "span", 

877 "strong", 

878 "sub", 

879 "sup", 

880 "table", 

881 "tbody", 

882 "td", 

883 "tfoot", 

884 "th", 

885 "thead", 

886 "tr", 

887 "u", 

888 "ul", 

889 ], 

890 "validAttrs": { 

891 "a": [ 

892 "href", 

893 "target", 

894 "title", 

895 ], 

896 "abbr": [ 

897 "title", 

898 ], 

899 "blockquote": [ 

900 "cite", 

901 ], 

902 "img": [ 

903 "src", 

904 "alt", 

905 "title", 

906 ], 

907 "p": [ 

908 "data-indent", 

909 ], 

910 "span": [ 

911 "title", 

912 ], 

913 "td": [ 

914 "colspan", 

915 "rowspan", 

916 ], 

917 

918 }, 

919 "validStyles": [ 

920 "color", 

921 ], 

922 "validClasses": [ 

923 "vitxt-*", 

924 "viur-txt-*" 

925 ], 

926 "singleTags": [ 

927 "br", 

928 "hr", 

929 "img", 

930 ] 

931 } 

932 """ 

933 A dictionary containing default configurations for handling HTML content in TextBone instances. 

934 """ 

935 

936 cache_environment_key: t.Optional[t.Callable[[], str]] = None 

937 """If set, this function will be called for each cache-attempt 

938 and the result will be included in the computed cache-key""" 

939 

940 # FIXME VIUR4: REMOVE ALL COMPATIBILITY MODES! 

941 compatibility: Multiple[str] = [ 

942 # "json.bone.structure.camelcasenames", # use camelCase attribute names (see #637 for details) 

943 # "json.bone.structure.keytuples", # use classic structure notation: `"structure = [["key", {...}] ...]` (#649) 

944 # "json.bone.structure.inlists", # dump skeleton structure with every JSON list response (#774 for details) 

945 # "tasks.periodic.useminutes", # Interpret int/float values for @PeriodicTask as minutes 

946 # # instead of seconds (#1133 for details) 

947 # "bone.select.structure.values.keytuple", # render old-style tuple-list in SelectBone's 

948 # values structure (#1203) 

949 ] 

950 """Backward compatibility flags; Remove to enforce new style.""" 

951 

952 error_handler: t.Callable[[Exception], str] | None = None 

953 """If set, ViUR calls this function instead of rendering the viur.errorTemplate if an exception occurs""" 

954 

955 error_logo: str = None 

956 """Path to a logo (static file). Will be used for the default error template""" 

957 

958 static_embed_svg_path: str = "/static/svgs/" 

959 """Path to the static SVGs folder. Will be used by the jinja-renderer-method: embedSvg""" 

960 

961 file_hmac_key: str = None 

962 """Hmac-Key used to sign download urls - set automatically""" 

963 

964 # TODO: separate this type hints and use it in the File module as well 

965 file_derivations: dict[str, t.Callable[["SkeletonInstance", dict, dict], list[tuple[str, float, str, t.Any]]]] = {} 

966 """Call-Map for file pre-processors""" 

967 

968 file_thumbnailer_url: t.Optional[str] = None 

969 # TODO: """docstring""" 

970 

971 main_app: "Module" = None 

972 """Reference to our pre-build Application-Instance""" 

973 

974 main_resolver: dict[str, dict] = None 

975 """Dictionary for Resolving functions for URLs""" 

976 

977 max_post_params_count: int = 250 

978 """Upper limit of the amount of parameters we accept per request. Prevents Hash-Collision-Attacks""" 

979 

980 param_filter_function: t.Callable[[str, str], bool] = lambda _, key, value: key.startswith("_") 

981 """ 

982 Function which decides if a request parameter should be used or filtered out. 

983 Returning True means to filter out. 

984 """ 

985 

986 moduleconf_admin_info: dict[str, t.Any] = { 

987 "icon": "gear-fill", 

988 "display": "hidden", 

989 } 

990 """Describing the internal ModuleConfig-module""" 

991 

992 script_admin_info: dict[str, t.Any] = { 

993 "icon": "file-code-fill", 

994 "display": "hidden", 

995 } 

996 """Describing the Script module""" 

997 

998 render_html_download_url_expiration: t.Optional[float | int] = None 

999 """The default duration, for which downloadURLs generated by the html renderer will stay valid""" 

1000 

1001 render_json_download_url_expiration: t.Optional[float | int] = None 

1002 """The default duration, for which downloadURLs generated by the json renderer will stay valid""" 

1003 

1004 request_preprocessor: t.Optional[t.Callable[[str], str]] = None 

1005 """Allows the application to register a function that's called before the request gets routed""" 

1006 

1007 search_valid_chars: str = "abcdefghijklmnopqrstuvwxyzäöüß0123456789" 

1008 """Characters valid for the internal search functionality (all other chars are ignored)""" 

1009 

1010 skeleton_search_path: Multiple[str] = [ 

1011 "/skeletons/", # skeletons of the project 

1012 "/viur/core/", # system-defined skeletons of viur-core 

1013 ] 

1014 """Priority, in which skeletons are loaded""" 

1015 

1016 _tasks_custom_environment_handler: t.Optional["CustomEnvironmentHandler"] = None 

1017 

1018 @property 

1019 def tasks_custom_environment_handler(self) -> t.Optional["CustomEnvironmentHandler"]: 

1020 """ 

1021 Preserve additional environment in deferred tasks. 

1022 

1023 If set, it must be an instance of CustomEnvironmentHandler 

1024 for serializing/restoring environment data. 

1025 """ 

1026 return self._tasks_custom_environment_handler 

1027 

1028 @tasks_custom_environment_handler.setter 

1029 def tasks_custom_environment_handler(self, value: "CustomEnvironmentHandler") -> None: 

1030 from .tasks import CustomEnvironmentHandler 

1031 if isinstance(value, CustomEnvironmentHandler) or value is None: 

1032 self._tasks_custom_environment_handler = value 

1033 elif isinstance(value, tuple): 

1034 if len(value) != 2: 

1035 raise ValueError(f"Expected a (serialize_env_func, restore_env_func) pair") 

1036 warnings.warn( 

1037 f"tuple is deprecated, please provide a CustomEnvironmentHandler object!", 

1038 DeprecationWarning, stacklevel=2, 

1039 ) 

1040 # Construct an CustomEnvironmentHandler class on the fly to be backward compatible 

1041 cls = type("ProjectCustomEnvironmentHandler", (CustomEnvironmentHandler,), 

1042 # serialize and restore will be bound methods. 

1043 # Therefore, consume the self argument with lambda. 

1044 {"serialize": lambda self: value[0](), 

1045 "restore": lambda self, obj: value[1](obj)}) 

1046 self._tasks_custom_environment_handler = cls() 

1047 else: 

1048 raise ValueError(f"Invalid type {type(value)}. Expected a CustomEnvironmentHandler object.") 

1049 

1050 tasks_default_queues: dict[str, str] = { 

1051 "__default__": "default", 

1052 } 

1053 """ 

1054 @CallDeferred tasks run in the Cloud Tasks Queue "default" by default. 

1055 One way to run them in a different task queue is to use the `_queue` parameter 

1056 when calling the task. 

1057 However, as this is not possible for existing or low-hanging calls, 

1058 default values can be defined here for each task. 

1059 To do this, the task path must be mapped to the queue name: 

1060 ``` 

1061 conf.tasks_default_queues["update_relations.viur.core.skeleton"] = "update_relations" 

1062 ``` 

1063 The queue (in the example: `"update_relations"`) must exist. 

1064 The default queue can be changed by overwriting `"__default__"`. 

1065 """ 

1066 

1067 valid_application_ids: list[str] = ["*"] 

1068 """Which application-ids we're supposed to run on""" 

1069 

1070 version: tuple[int, int, int] = tuple(int(part) if part.isdigit() else part for part in __version__.split(".", 3)) 

1071 """Semantic version number of viur-core as a tuple of 3 (major, minor, patch-level)""" 

1072 

1073 viur2import_blobsource: t.Optional[dict[t.Literal["infoURL", "gsdir"], str]] = None 

1074 """Configuration to import file blobs from ViUR2""" 

1075 

1076 def __init__(self, strict_mode: bool = False): 

1077 super().__init__() 

1078 self._strict_mode = strict_mode 

1079 self.admin = Admin(parent=self) 

1080 self.db = Database(parent=self) 

1081 self.security = Security(parent=self) 

1082 self.debug = Debug(parent=self) 

1083 self.email = Email(parent=self) 

1084 self.i18n = I18N(parent=self) 

1085 self.user = User(parent=self) 

1086 self.instance = Instance(parent=self) 

1087 self.history = History(parent=self) 

1088 

1089 _mapping = { 

1090 # debug 

1091 "viur.dev_server_cloud_logging": "debug.dev_server_cloud_logging", 

1092 "viur.disable_cache": "debug.disable_cache", 

1093 # i18n 

1094 "viur.availableLanguages": "i18n.available_languages", 

1095 "viur.defaultLanguage": "i18n.default_language", 

1096 "viur.domainLanguageMapping": "i18n.domain_language_mapping", 

1097 "viur.languageAliasMap": "i18n.language_alias_map", 

1098 "viur.languageMethod": "i18n.language_method", 

1099 "viur.languageModuleMap": "i18n.language_module_map", 

1100 # user 

1101 "viur.accessRights": "user.access_rights", 

1102 "viur.maxPasswordLength": "user.max_password_length", 

1103 "viur.otp.issuer": "user.otp_issuer", 

1104 "viur.session.lifeTime": "user.session_life_time", 

1105 "viur.session.persistentFieldsOnLogin": "user.session_persistent_fields_on_login", 

1106 "viur.session.persistentFieldsOnLogout": "user.session_persistent_fields_on_logout", 

1107 "viur.user.roles": "user.roles", 

1108 "viur.user.google.clientID": "user.google_client_id", 

1109 "viur.user.google.gsuiteDomains": "user.google_gsuite_domains", 

1110 # instance 

1111 "viur.instance.app_version": "instance.app_version", 

1112 "viur.instance.core_base_path": "instance.core_base_path", 

1113 "viur.instance.is_dev_server": "instance.is_dev_server", 

1114 "viur.instance.project_base_path": "instance.project_base_path", 

1115 "viur.instance.project_id": "instance.project_id", 

1116 "viur.instance.version_hash": "instance.version_hash", 

1117 # security 

1118 "viur.forceSSL": "security.force_ssl", 

1119 "viur.noSSLCheckUrls": "security.no_ssl_check_urls", 

1120 # old viur-prefix 

1121 "viur.cacheEnvironmentKey": "cache_environment_key", 

1122 "viur.contentSecurityPolicy": "content_security_policy", 

1123 "viur.bone.boolean.str2true": "bone_boolean_str2true", 

1124 "viur.errorHandler": "error_handler", 

1125 "viur.static.embedSvg.path": "static_embed_svg_path", 

1126 "viur.file.hmacKey": "file_hmac_key", 

1127 "viur.file_hmacKey": "file_hmac_key", 

1128 "viur.file.derivers": "file_derivations", 

1129 "viur.file.thumbnailerURL": "file_thumbnailer_url", 

1130 "viur.mainApp": "main_app", 

1131 "viur.mainResolver": "main_resolver", 

1132 "viur.maxPostParamsCount": "max_post_params_count", 

1133 "viur.moduleconf.admin_info": "moduleconf_admin_info", 

1134 "viur.script.admin_info": "script_admin_info", 

1135 "viur.render.html.downloadUrlExpiration": "render_html_download_url_expiration", 

1136 "viur.downloadUrlFor.expiration": "render_html_download_url_expiration", 

1137 "viur.render.json.downloadUrlExpiration": "render_json_download_url_expiration", 

1138 "viur.requestPreprocessor": "request_preprocessor", 

1139 "viur.searchValidChars": "search_valid_chars", 

1140 "viur.skeleton.searchPath": "skeleton_search_path", 

1141 "viur.tasks.customEnvironmentHandler": "tasks_custom_environment_handler", 

1142 "viur.validApplicationIDs": "valid_application_ids", 

1143 "viur.viur2import.blobsource": "viur2import_blobsource", 

1144 } 

1145 

1146 def _resolve_mapping(self, key: str) -> str: 

1147 """Additional mapping for new sub confs.""" 

1148 if key.startswith("viur.") and key not in self._mapping: 

1149 key = key.removeprefix("viur.") 

1150 return super()._resolve_mapping(key) 

1151 

1152 

1153conf = Conf( 

1154 strict_mode=os.getenv("VIUR_CORE_CONFIG_STRICT_MODE", "").lower() != "false", 

1155)