askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
object_feature_flags.py · 3.7 KB · 89 lines
| 1 | """The two gates every optional pass reads: an operator opt-in in the |
| 2 | environment, and a brownout kill switch in the ``feature_flags`` collection. |
| 3 | |
| 4 | Extracted, not invented. The kill switch below existed as six word-for-word |
| 5 | copies (object_rollups, object_notify, object_email, object_connectors, |
| 6 | object_materialize, and app-timers' timer_actions), each docstring saying it |
| 7 | "mirrors" another one exactly. Doctrine #4 says to extract a primitive after |
| 8 | the pattern repeats; six is well past that, and mail sync was about to make |
| 9 | it seven. The five root modules keep their own public names |
| 10 | (``email_pass_enabled`` and friends) because callers and tests import those; |
| 11 | only the body moved here. app-timers' copy lives in a package object and is |
| 12 | left for that package's next version, since changing an installed object is |
| 13 | a package upgrade rather than a refactor. |
| 14 | |
| 15 | The two gates answer different questions and must not be merged: |
| 16 | |
| 17 | - ``env_opt_in`` is **adoption**: OFF unless the operator wrote the variable |
| 18 | into the environment file. A capability that talks to the outside world |
| 19 | (an SMTP relay, an IMAP server, a WebDAV mount) is something an operator |
| 20 | chooses, never something a fresh box does on its own. |
| 21 | - ``kill_switch_on`` is **brownout**: ON unless a ``feature_flags`` row says |
| 22 | off. It exists so an operator can stop a misbehaving pass from the admin |
| 23 | UI without a redeploy. A missing row, a missing or unreadable collection |
| 24 | and a blank value all read as "on"; only an explicit off/false/0/no turns |
| 25 | it off -- a kill switch that failed closed on a missing table would turn |
| 26 | every fresh box's passes off for a reason nobody chose. |
| 27 | |
| 28 | ``refusal`` combines them into the one sentence a caller reports, naming |
| 29 | exactly what to set (AGENTS.md: a capability that is absent refuses, and |
| 30 | the refusal names what to configure). |
| 31 | """ |
| 32 | |
| 33 | from __future__ import annotations |
| 34 | |
| 35 | import os |
| 36 | from pathlib import Path |
| 37 | from typing import Any, Mapping |
| 38 | |
| 39 | import object_collections |
| 40 | import object_records |
| 41 | |
| 42 | FEATURE_FLAGS_COLLECTION = "feature_flags" |
| 43 | TRUE_VALUES = frozenset({"1", "true", "yes", "on"}) |
| 44 | OFF_VALUES = frozenset({"off", "false", "0", "no"}) |
| 45 | |
| 46 | |
| 47 | def env_opt_in(name: str, env: Mapping[str, str] | None = None) -> bool: |
| 48 | """True only when the environment variable says 1/true/yes/on.""" |
| 49 | source = os.environ if env is None else env |
| 50 | return str(source.get(name, "") or "").strip().lower() in TRUE_VALUES |
| 51 | |
| 52 | |
| 53 | def kill_switch_on(flag: str, *, base_dir: Path | str | Any) -> bool: |
| 54 | """True unless a ``feature_flags`` row named ``flag`` says off/false/0/no. |
| 55 | |
| 56 | The first row carrying the flag decides, as every copy this replaced |
| 57 | did. |
| 58 | """ |
| 59 | try: |
| 60 | rows = object_records.read_collection_records(FEATURE_FLAGS_COLLECTION, base_dir=base_dir) |
| 61 | except ( |
| 62 | object_collections.CollectionNotFoundError, |
| 63 | object_collections.InvalidCollectionNameError, |
| 64 | OSError, |
| 65 | ValueError, |
| 66 | ): |
| 67 | return True |
| 68 | for row in rows: |
| 69 | if row.get("flag") == flag: |
| 70 | value = (row.get("value") or "").strip().lower() |
| 71 | return True if not value else value not in OFF_VALUES |
| 72 | return True |
| 73 | |
| 74 | |
| 75 | def refusal( |
| 76 | *, |
| 77 | env_name: str | None = None, |
| 78 | flag: str | None = None, |
| 79 | base_dir: Path | str | Any, |
| 80 | env: Mapping[str, str] | None = None, |
| 81 | ) -> str | None: |
| 82 | """None when the feature may run; otherwise the sentence saying why not, |
| 83 | naming the variable or the flag row that would change the answer.""" |
| 84 | if env_name and not env_opt_in(env_name, env): |
| 85 | return f"off: set {env_name}=true in the server's environment to turn it on" |
| 86 | if flag and not kill_switch_on(flag, base_dir=base_dir): |
| 87 | return (f"off: the feature_flags row {flag!r} is set to off " |
| 88 | f"(an operator's kill switch); remove it or set it to on") |
| 89 | return None |