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
« 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
11import google.auth
12from google.appengine.api.memcache import Client
14from viur.core.version import __version__
15from viur.core.current import user as current_user
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
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
34class ConfigType:
35 """An abstract class for configurations.
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"""
42 _strict_mode = None
43 """Internal strict mode for this instance.
45 Use the property getter and setter to access it!"""
47 _parent = None
48 """Parent config instance"""
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
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()}."
64 @property
65 def strict_mode(self):
66 """Determine if the config runs in strict mode.
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.
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
83 @strict_mode.setter
84 def strict_mode(self, value: bool | None) -> None:
85 """Setter for the strict mode of the current instance.
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
93 def _resolve_mapping(self, key: str) -> str:
94 """Resolve the mapping old dict -> new attribute.
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
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.
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
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.
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
148 def __getitem__(self, key: str) -> t.Any:
149 """Support the old dict-like syntax (getter).
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)
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 )
166 return getattr(self, key)
168 def __getattr__(self, key: str) -> t.Any:
169 """Resolve dot-notation and name mapping in not strict mode.
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 )
181 key = self._resolve_mapping(key)
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)
188 return super().__getattribute__(key)
190 def __setitem__(self, key: str, value: t.Any) -> None:
191 """Support the old dict-like syntax (setter).
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 )
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
211 key = self._resolve_mapping(key)
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
224 return setattr(self, key, value)
226 def __setattr__(self, key: str, value: t.Any) -> None:
227 """Set attributes after applying the old -> new mapping
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)
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)
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)
244 return super().__setattr__(key, value)
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))})"
252# Some values used more than once below
253_project_id = google.auth.default()[1]
254_app_version = os.getenv("GAE_VERSION")
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!!!
261class Admin(ConfigType):
262 """Administration tool configuration"""
264 name: str = "ViUR"
265 """Administration tool configuration"""
267 logo: str = ""
268 """URL for the Logo in the Topbar of the VI"""
270 login_background: str = ""
271 """URL for the big Image in the background of the VI Login screen"""
273 login_logo: str = ""
274 """URL for the Logo over the VI Login screen"""
276 color_primary: str = "#d00f1c"
277 """primary color for viur-admin"""
279 color_secondary: str = "#333333"
280 """secondary color for viur-admin"""
282 module_groups: dict[str, dict[t.Literal["name", "icon", "sortindex"], str | int]] = {}
283 """Module Groups for the admin tool
285 Group modules in the sidebar in categories (groups).
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 }
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 """
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 }
314class Database(ConfigType):
315 query_external_limit: int = 100
316 """Sets the maximum query limit allowed by external filters."""
318 query_default_limit: int = 30
319 """Sets the default query limit for all queries."""
321 memcache_client: Client | None = None
322 """If set, ViUR cache data for the db.get in the Memcache for faster access."""
324 create_access_log: bool = True
325 """If False no access log will be created. But then the caching is disabled too."""
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, ...)."""
332 name: str | None = os.getenv("VIUR_DB_NAME") or None
333 """Named datastore to target instead of ``(default)``.
335 Env-sourced: the client is built at ``db.transport`` import time, before any
336 runtime config could set it."""
338 namespace: str | None = os.getenv("VIUR_DB_NAMESPACE") or None
339 """Datastore namespace to scope to. Env-sourced like `name`."""
342class Security(ConfigType):
343 """Security related settings"""
345 force_ssl: bool = True
346 """If true, all requests must be encrypted (ignored on development server)"""
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)"""
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"""
368 reporting_endpoints: dict[str, str] = {}
369 """Named endpoints reports are being sent to, emitted as ``Reporting-Endpoints`` http-header.
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).
376 Use :func:`~viur.core.securityheaders.set_reporting_endpoint` to set this property.
378 See https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Reporting-Endpoints
379 """
381 referrer_policy: str = "strict-origin"
382 """Per default, we'll emit Referrer-Policy: strict-origin so no referrers leak to external services
384 See https://www.w3.org/TR/referrer-policy/
385 """
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 """
404 enable_coep: bool = False
405 """Shall we emit Cross-Origin-Embedder-Policy: require-corp?"""
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?
412 See https://html.spec.whatwg.org/multipage/browsers.html#cross-origin-opener-policy-value
413 """
415 enable_corp: t.Literal["same-origin", "same-site", "cross-origin"] = "same-origin"
416 """Emit a Cross-Origin-Resource-Policy Header?
418 See https://fetch.spec.whatwg.org/#cross-origin-resource-policy-header
419 """
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"""
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
430 In case of allow-from, the second parameters must be the host-url.
431 Otherwise, it can be None.
432 """
434 x_xss_protection: t.Optional[bool] = True
435 """ViUR will emit an X-XSS-Protection header if set (the default)"""
437 x_content_type_options: bool = True
438 """ViUR will emit X-Content-Type-Options: nosniff Header unless set to False"""
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"""
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 """
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 """
455 password_recovery_key_length: int = 42
456 """Length of the Password recovery key"""
458 closed_system: bool = False
459 """If `True` it activates a mode in which only authenticated users can access all routes."""
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."""
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."""
490 # CORS Settings
492 cors_origins: t.Iterable[str | re.Pattern] | t.Literal["*"] = []
493 r"""Allowed origins
494 Access-Control-Allow-Origin
496 Pattern should be case-insensitive, for example:
497 >>> re.compile(r"^http://localhost:(\d{4,5})/?$", flags=re.IGNORECASE)
498 """ # noqa
500 cors_origins_use_wildcard: bool = False
501 """Use * for Access-Control-Allow-Origin -- if possible"""
503 cors_methods: t.Iterable[str] = ["get", "head", "post", "options"] # , "put", "patch", "delete"]
504 """Access-Control-Request-Method"""
506 cors_allow_headers: t.Iterable[str | re.Pattern] | t.Literal["*"] = []
507 """Access-Control-Request-Headers
509 Can also be set for specific @exposed methods with the @cors decorator.
511 Pattern should be case-insensitive, for example:
512 >>> re.compile(r"^X-ViUR-.*$", flags=re.IGNORECASE)
513 """
515 cors_allow_credentials: bool = False
516 """
517 Set Access-Control-Allow-Credentials to true
518 to support fetch requests with credentials: include
519 """
521 cors_max_age: datetime.timedelta | None = None
522 """Allow caching"""
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 }
539class Debug(ConfigType):
540 """Several debug flags"""
542 trace: bool = False
543 """If enabled, trace any routing, HTTPExceptions and decorations for debugging and insight"""
545 trace_exceptions: bool = False
546 """If enabled, user-generated exceptions from the viur.core.errors module won't be caught and handled"""
548 trace_external_call_routing: bool = False
549 """If enabled, ViUR will log which (exposed) function are called from outside with what arguments"""
551 trace_internal_call_routing: bool = False
552 """If enabled, ViUR will log which (internal-exposed) function are called from templates with what arguments"""
554 trace_queries: bool = False
555 """If enabled, ViUR will log each query that run"""
557 skeleton_from_client: bool = False
558 """If enabled, log errors raises from skeleton.fromClient()"""
560 dev_server_cloud_logging: bool = False
561 """If disabled the local logging will not send with requestLogger to the cloud"""
563 disable_cache: bool = False
564 """If set to true, the decorator @enableCache from viur.core.cache has no effect"""
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 }
576class Email(ConfigType):
577 """Email related settings."""
579 log_retention: datetime.timedelta = datetime.timedelta(days=30)
580 """For how long we'll keep successfully send emails in the viur-emails table"""
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 """
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 """
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 """
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 """
603 sender_override: str | None = None
604 """If set, this sender will be used, regardless of what the templates advertise as sender"""
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."""
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 }
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."""
630class I18N(ConfigType):
631 """All i18n, multilang related settings."""
633 available_languages: Multiple[str] = ["en"]
634 """List of language-codes, which are valid for this application"""
636 default_language: str = "en"
637 """Unless overridden by the Project: Use english as default language"""
639 domain_language_mapping: dict[str, str] = {}
640 """Maps Domains to alternative default languages"""
642 language_alias_map: dict[str, str] = {}
643 """Allows mapping of certain languages to one translation (i.e. us->en)"""
645 fallback_languages: Multiple[str] = []
646 """Languages tried in order when the requested language has no translation"""
648 sources: Multiple["i18n.TranslationSource"] = None
649 """Translation sources, loaded in order; None uses i18n.DEFAULT_TRANSLATION_SOURCES"""
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 """
659 language_module_map: dict[str, dict[str, str]] = {}
660 """Maps modules to their translation (if set)"""
662 auto_translate_bones: bool = True
663 """Defines whether bone descr and categories should be automatically translated via i18n.translate-objects."""
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())
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.
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.
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 """
688 def _dump_can_view(self, _key):
689 return bool(current_user.get())
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.
694 This logic is omitted for translations flagged public."""
697class User(ConfigType):
698 """User, session, login related settings"""
700 access_rights: Multiple[str] = [
701 "root",
702 "admin",
703 "scriptor",
704 ]
705 """Additional access flags available for users on this project.
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 """
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.
724 The roles can be individually defined per module, see `Module.roles`.
726 The default roles can be described as follows:
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`.
736 The preset roles are for guidiance, and already fit to most projects.
737 """
739 session_life_time: datetime.timedelta = datetime.timedelta(hours=1)
740 """Default is 60 minutes lifetime for ViUR sessions"""
742 session_persistent_fields_on_login: Multiple[str] = ["language"]
743 """If set, these Fields will survive the session.reset() called on user/login"""
745 session_persistent_fields_on_logout: Multiple[str] = ["language"]
746 """If set, these Fields will survive the session.reset() called on user/logout"""
748 max_password_length: int = 512
749 """Prevent Denial of Service attacks using large inputs for pbkdf2"""
751 otp_issuer: t.Optional[str] = None
752 """The name of the issuer for the opt token"""
754 google_client_id: t.Optional[str] = None
755 """OAuth Client ID for Google Login"""
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."""
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``).
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 """
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.
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.
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.
793 Examples::
795 conf.user.redirect_whitelist = [
796 "http://localhost:*",
797 "https://*-dot-myapp.appspot.com",
798 "https://tools.example.com/callback/*",
799 ]
801 # dynamic / lazily evaluated
802 conf.user.redirect_whitelist = lambda: load_whitelist_from_db()
803 """
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)
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"""
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"""
825 is_dev_server: bool = os.getenv("GAE_ENV") == "localdev"
826 """Determine whether instance is running on a local development server"""
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"""
831 project_id: str = _project_id
832 """The instance's project ID"""
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"""
838class Conf(ConfigType):
839 """Conf class wraps the conf dict and allows to handle
840 deprecated keys or other special operations.
841 """
843 bone_boolean_str2true: Multiple[str | int] = ("true", "yes", "1")
844 """Allowed values that define a str to evaluate to true"""
846 bone_string_escape_html: bool = True
847 """Default escape_html setting for StringBone. Set to False to disable HTML escaping globally."""
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``."""
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 ],
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 """
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"""
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."""
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"""
955 error_logo: str = None
956 """Path to a logo (static file). Will be used for the default error template"""
958 static_embed_svg_path: str = "/static/svgs/"
959 """Path to the static SVGs folder. Will be used by the jinja-renderer-method: embedSvg"""
961 file_hmac_key: str = None
962 """Hmac-Key used to sign download urls - set automatically"""
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"""
968 file_thumbnailer_url: t.Optional[str] = None
969 # TODO: """docstring"""
971 main_app: "Module" = None
972 """Reference to our pre-build Application-Instance"""
974 main_resolver: dict[str, dict] = None
975 """Dictionary for Resolving functions for URLs"""
977 max_post_params_count: int = 250
978 """Upper limit of the amount of parameters we accept per request. Prevents Hash-Collision-Attacks"""
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 """
986 moduleconf_admin_info: dict[str, t.Any] = {
987 "icon": "gear-fill",
988 "display": "hidden",
989 }
990 """Describing the internal ModuleConfig-module"""
992 script_admin_info: dict[str, t.Any] = {
993 "icon": "file-code-fill",
994 "display": "hidden",
995 }
996 """Describing the Script module"""
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"""
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"""
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"""
1007 search_valid_chars: str = "abcdefghijklmnopqrstuvwxyzäöüß0123456789"
1008 """Characters valid for the internal search functionality (all other chars are ignored)"""
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"""
1016 _tasks_custom_environment_handler: t.Optional["CustomEnvironmentHandler"] = None
1018 @property
1019 def tasks_custom_environment_handler(self) -> t.Optional["CustomEnvironmentHandler"]:
1020 """
1021 Preserve additional environment in deferred tasks.
1023 If set, it must be an instance of CustomEnvironmentHandler
1024 for serializing/restoring environment data.
1025 """
1026 return self._tasks_custom_environment_handler
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.")
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 """
1067 valid_application_ids: list[str] = ["*"]
1068 """Which application-ids we're supposed to run on"""
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)"""
1073 viur2import_blobsource: t.Optional[dict[t.Literal["infoURL", "gsdir"], str]] = None
1074 """Configuration to import file blobs from ViUR2"""
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)
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 }
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)
1153conf = Conf(
1154 strict_mode=os.getenv("VIUR_CORE_CONFIG_STRICT_MODE", "").lower() != "false",
1155)