Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/object_feature_flags.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

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
2environment, and a brownout kill switch in the ``feature_flags`` collection.
3
4Extracted, not invented. The kill switch below existed as six word-for-word
5copies (object_rollups, object_notify, object_email, object_connectors,
6object_materialize, and app-timers' timer_actions), each docstring saying it
7"mirrors" another one exactly. Doctrine #4 says to extract a primitive after
8the pattern repeats; six is well past that, and mail sync was about to make
9it seven. The five root modules keep their own public names
10(``email_pass_enabled`` and friends) because callers and tests import those;
11only the body moved here. app-timers' copy lives in a package object and is
12left for that package's next version, since changing an installed object is
13a package upgrade rather than a refactor.
14
15The 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
29exactly what to set (AGENTS.md: a capability that is absent refuses, and
30the refusal names what to configure).
31"""
32
33from __future__ import annotations
34
35import os
36from pathlib import Path
37from typing import Any, Mapping
38
39import object_collections
40import object_records
41
42FEATURE_FLAGS_COLLECTION = "feature_flags"
43TRUE_VALUES = frozenset({"1", "true", "yes", "on"})
44OFF_VALUES = frozenset({"off", "false", "0", "no"})
45
46
47def 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
53def 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
75def 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