cliver-playbook-app-basic 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- cliver_playbook/app/basic/__init__.py +12 -0
- cliver_playbook/app/basic/__main__.py +33 -0
- cliver_playbook/app/basic/alembic/__init__.py +57 -0
- cliver_playbook/app/basic/alembic/env.py +91 -0
- cliver_playbook/app/basic/alembic/script.py.mako +26 -0
- cliver_playbook/app/basic/alembic/versions/0001_basic_items.py +54 -0
- cliver_playbook/app/basic/alembic/versions/0002_app_settings.py +47 -0
- cliver_playbook/app/basic/api/__init__.py +0 -0
- cliver_playbook/app/basic/api/items.py +58 -0
- cliver_playbook/app/basic/api/meta.py +27 -0
- cliver_playbook/app/basic/api/routes.py +20 -0
- cliver_playbook/app/basic/app.py +48 -0
- cliver_playbook/app/basic/config_yaml.py +220 -0
- cliver_playbook/app/basic/db/__init__.py +0 -0
- cliver_playbook/app/basic/db/base.py +7 -0
- cliver_playbook/app/basic/db/session.py +31 -0
- cliver_playbook/app/basic/models/__init__.py +0 -0
- cliver_playbook/app/basic/models/entities.py +83 -0
- cliver_playbook/app/basic/runtime.py +160 -0
- cliver_playbook/app/basic/runtime_settings.py +557 -0
- cliver_playbook/app/basic/schemas/__init__.py +0 -0
- cliver_playbook/app/basic/schemas/item.py +31 -0
- cliver_playbook/app/basic/services/__init__.py +0 -0
- cliver_playbook/app/basic/services/items.py +50 -0
- cliver_playbook/app/basic/settings.py +162 -0
- cliver_playbook_app_basic-0.1.0.dist-info/METADATA +79 -0
- cliver_playbook_app_basic-0.1.0.dist-info/RECORD +29 -0
- cliver_playbook_app_basic-0.1.0.dist-info/WHEEL +4 -0
- cliver_playbook_app_basic-0.1.0.dist-info/licenses/LICENSE +201 -0
|
@@ -0,0 +1,557 @@
|
|
|
1
|
+
"""Module-owned runtime settings: registry, validation, persistence, overlay.
|
|
2
|
+
|
|
3
|
+
ADR-0021. Configuration has four layers, highest precedence first:
|
|
4
|
+
|
|
5
|
+
environment > .env > persisted runtime overrides > app.yaml > defaults
|
|
6
|
+
|
|
7
|
+
The first two and ``app.yaml`` are resolved by pydantic-settings when the
|
|
8
|
+
process starts; this module owns the middle layer. A package registers a
|
|
9
|
+
``SettingsSection`` at import time — its fields, labels, allowed values, and
|
|
10
|
+
the functions that read/apply the section on a Settings instance. The central
|
|
11
|
+
admin API (in the identity package) never interprets those fields itself; it
|
|
12
|
+
asks each section to describe itself, validates the request, and calls the
|
|
13
|
+
owner's ``apply``. That is how RAG settings stay owned by RAG while the
|
|
14
|
+
administrator sees one settings surface.
|
|
15
|
+
|
|
16
|
+
Boundaries (deliberate, see the ADR):
|
|
17
|
+
|
|
18
|
+
- Environment-managed fields are read-only. An explicit ``env_var`` is checked
|
|
19
|
+
against the process environment and the project ``.env``; a persisted
|
|
20
|
+
override for such a field is ignored on load and rejected on write, because
|
|
21
|
+
the environment would win at the next restart anyway.
|
|
22
|
+
- Secrets are write-only. The API accepts a new value, persists it with the
|
|
23
|
+
section, and never returns it — the description reports only configured /
|
|
24
|
+
not configured. An environment variable or ``.env`` entry with the declared
|
|
25
|
+
``env_var`` still wins and makes the field read-only, so a deployment can
|
|
26
|
+
keep credentials out of the database entirely.
|
|
27
|
+
- ``apply`` must validate fully before mutating the bound Settings instance.
|
|
28
|
+
The live instance is mutated in place so a change takes effect on the next
|
|
29
|
+
request without rebuilding the engine.
|
|
30
|
+
- A missing ``app_settings`` table is not fatal. Apps are constructed before
|
|
31
|
+
migrations in several test/bootstrap paths, and a deployment that has not
|
|
32
|
+
run the basic chain yet should still serve requests with static config.
|
|
33
|
+
"""
|
|
34
|
+
|
|
35
|
+
from __future__ import annotations
|
|
36
|
+
|
|
37
|
+
import logging
|
|
38
|
+
import os
|
|
39
|
+
import re
|
|
40
|
+
from collections.abc import Callable, Mapping, Sequence
|
|
41
|
+
from contextlib import asynccontextmanager
|
|
42
|
+
from dataclasses import dataclass
|
|
43
|
+
from typing import Any
|
|
44
|
+
|
|
45
|
+
from dotenv import dotenv_values
|
|
46
|
+
from sqlalchemy import delete, select
|
|
47
|
+
from sqlalchemy.exc import SQLAlchemyError
|
|
48
|
+
from sqlalchemy.ext.asyncio import AsyncSession
|
|
49
|
+
|
|
50
|
+
from cliver_playbook.app.basic import runtime
|
|
51
|
+
from cliver_playbook.app.basic.config_yaml import resolve_env_file
|
|
52
|
+
from cliver_playbook.app.basic.db.session import open_session
|
|
53
|
+
from cliver_playbook.app.basic.models.entities import AppSetting
|
|
54
|
+
|
|
55
|
+
logger = logging.getLogger("cliver_playbook.app.basic.runtime_settings")
|
|
56
|
+
|
|
57
|
+
_FIELD_TYPES = frozenset({"string", "integer", "number", "boolean", "enum", "json"})
|
|
58
|
+
_SECTION_KEY_PATTERN = r"^[a-z][a-z0-9_-]{0,63}$"
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
class SettingsError(RuntimeError):
|
|
62
|
+
"""Base class for runtime-settings failures (reported as a 400 by the API)."""
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
class UnknownSectionError(SettingsError):
|
|
66
|
+
"""No package registered the requested section key."""
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
class SettingsValidationError(SettingsError):
|
|
70
|
+
"""A requested value is unknown, read-only, or fails the section's rules."""
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
@dataclass(frozen=True)
|
|
74
|
+
class SettingsField:
|
|
75
|
+
"""One editable value in a module-owned settings section.
|
|
76
|
+
|
|
77
|
+
``env_var`` is the canonical environment variable that overrides the
|
|
78
|
+
field (``CLIVER_RAG__EMBEDDER``). For a secret it names the variable a
|
|
79
|
+
deployment can use to keep the credential out of the database: when set,
|
|
80
|
+
the environment wins and the field becomes read-only. Otherwise the
|
|
81
|
+
secret is write-only — accepted on update, persisted with the section,
|
|
82
|
+
never returned.
|
|
83
|
+
"""
|
|
84
|
+
|
|
85
|
+
name: str
|
|
86
|
+
label: str
|
|
87
|
+
type: str = "string"
|
|
88
|
+
description: str = ""
|
|
89
|
+
enum: tuple[str, ...] | None = None
|
|
90
|
+
minimum: float | None = None
|
|
91
|
+
maximum: float | None = None
|
|
92
|
+
env_var: str | None = None
|
|
93
|
+
secret: bool = False
|
|
94
|
+
# Optional presentation grouping. Fields sharing a key render together
|
|
95
|
+
# under one heading; ``group_title`` is the English label a UI falls back
|
|
96
|
+
# to when it has no translation. ``subgroup`` adds a nested heading inside
|
|
97
|
+
# that group (for a large configuration with distinct purposes). Purely
|
|
98
|
+
# presentational — persistence and validation remain per field.
|
|
99
|
+
group: str | None = None
|
|
100
|
+
group_title: str = ""
|
|
101
|
+
subgroup: str | None = None
|
|
102
|
+
subgroup_title: str = ""
|
|
103
|
+
|
|
104
|
+
def __post_init__(self) -> None:
|
|
105
|
+
if (
|
|
106
|
+
not self.name
|
|
107
|
+
or "." in self.name
|
|
108
|
+
and not all(part.isidentifier() for part in self.name.split("."))
|
|
109
|
+
):
|
|
110
|
+
raise ValueError(f"invalid settings field name: {self.name!r}")
|
|
111
|
+
if not self.name[0].islower():
|
|
112
|
+
raise ValueError(f"settings field name must start lowercase: {self.name!r}")
|
|
113
|
+
if self.type not in _FIELD_TYPES:
|
|
114
|
+
raise ValueError(f"{self.name}: unknown field type {self.type!r}")
|
|
115
|
+
if self.type == "enum" and not self.enum:
|
|
116
|
+
raise ValueError(f"{self.name}: an enum field needs at least one choice")
|
|
117
|
+
if self.enum is not None:
|
|
118
|
+
if self.type != "enum":
|
|
119
|
+
raise ValueError(f"{self.name}: only an enum field may declare choices")
|
|
120
|
+
if len(set(self.enum)) != len(self.enum):
|
|
121
|
+
raise ValueError(f"{self.name}: duplicate enum choices")
|
|
122
|
+
if self.minimum is not None and self.maximum is not None and self.minimum > self.maximum:
|
|
123
|
+
raise ValueError(f"{self.name}: minimum exceeds maximum")
|
|
124
|
+
if self.group is not None:
|
|
125
|
+
if not re.match(_SECTION_KEY_PATTERN, self.group):
|
|
126
|
+
raise ValueError(f"{self.name}: invalid group key {self.group!r}")
|
|
127
|
+
if not self.group_title:
|
|
128
|
+
raise ValueError(
|
|
129
|
+
f"{self.name}: a grouped field must declare group_title "
|
|
130
|
+
"(the untranslated UI fallback)"
|
|
131
|
+
)
|
|
132
|
+
elif self.group_title:
|
|
133
|
+
raise ValueError(f"{self.name}: group_title requires a group key")
|
|
134
|
+
if self.subgroup is not None:
|
|
135
|
+
if self.group is None:
|
|
136
|
+
raise ValueError(f"{self.name}: a subgroup requires a group key")
|
|
137
|
+
if not re.match(_SECTION_KEY_PATTERN, self.subgroup):
|
|
138
|
+
raise ValueError(f"{self.name}: invalid subgroup key {self.subgroup!r}")
|
|
139
|
+
if not self.subgroup_title:
|
|
140
|
+
raise ValueError(
|
|
141
|
+
f"{self.name}: a subgrouped field must declare subgroup_title "
|
|
142
|
+
"(the untranslated UI fallback)"
|
|
143
|
+
)
|
|
144
|
+
elif self.subgroup_title:
|
|
145
|
+
raise ValueError(f"{self.name}: subgroup_title requires a subgroup key")
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
@dataclass(frozen=True)
|
|
149
|
+
class SettingsSection:
|
|
150
|
+
"""A package-owned slice of the settings surface.
|
|
151
|
+
|
|
152
|
+
``read`` returns the section's current values keyed by field name (raw —
|
|
153
|
+
including secrets, for the configured/not-configured check). ``apply``
|
|
154
|
+
receives a partial mapping and must validate the resulting full state
|
|
155
|
+
before mutating the Settings instance.
|
|
156
|
+
"""
|
|
157
|
+
|
|
158
|
+
key: str
|
|
159
|
+
title: str
|
|
160
|
+
description: str
|
|
161
|
+
fields: Callable[[], Sequence[SettingsField]]
|
|
162
|
+
read: Callable[[Any], Mapping[str, Any]]
|
|
163
|
+
apply: Callable[[Any, Mapping[str, Any]], None]
|
|
164
|
+
|
|
165
|
+
def __post_init__(self) -> None:
|
|
166
|
+
if not re.match(_SECTION_KEY_PATTERN, self.key):
|
|
167
|
+
raise ValueError(f"invalid settings section key: {self.key!r}")
|
|
168
|
+
if not self.title:
|
|
169
|
+
raise ValueError(f"settings section {self.key!r} needs a title")
|
|
170
|
+
_validated_fields(self)
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
def _validated_fields(section: SettingsSection) -> tuple[SettingsField, ...]:
|
|
174
|
+
"""Materialise and structurally validate a section's field list."""
|
|
175
|
+
fields = tuple(section.fields())
|
|
176
|
+
if not fields:
|
|
177
|
+
raise ValueError(f"settings section {section.key!r} has no fields")
|
|
178
|
+
names = [field.name for field in fields]
|
|
179
|
+
if len(set(names)) != len(names):
|
|
180
|
+
raise ValueError(f"settings section {section.key!r} has duplicate field names")
|
|
181
|
+
return fields
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
_sections: dict[str, SettingsSection] = {}
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
def register_settings_section(section: SettingsSection) -> None:
|
|
188
|
+
"""Register a module-owned settings section (idempotent for re-imports)."""
|
|
189
|
+
existing = _sections.get(section.key)
|
|
190
|
+
if existing is not None:
|
|
191
|
+
if existing == section:
|
|
192
|
+
return
|
|
193
|
+
raise ValueError(
|
|
194
|
+
f"settings section {section.key!r} is already registered by another "
|
|
195
|
+
"package — section keys are process-wide"
|
|
196
|
+
)
|
|
197
|
+
_sections[section.key] = section
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def settings_sections() -> tuple[SettingsSection, ...]:
|
|
201
|
+
"""Every registered section, in registration order."""
|
|
202
|
+
return tuple(_sections.values())
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
def get_settings_section(key: str) -> SettingsSection | None:
|
|
206
|
+
return _sections.get(key)
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
def env_snapshot(settings: Any | None = None) -> dict[str, str]:
|
|
210
|
+
"""Process environment plus the project .env, for env-managed detection.
|
|
211
|
+
|
|
212
|
+
The process environment wins, matching the settings precedence. Empty
|
|
213
|
+
values still count as "set" — an explicitly empty environment variable is
|
|
214
|
+
an operator decision, not an absence.
|
|
215
|
+
|
|
216
|
+
The dotenv layer follows the bound Settings instance's ``_env_file``:
|
|
217
|
+
``None`` means the instance deliberately disabled that layer (tests do
|
|
218
|
+
this), so the project .env must not leak into the description either.
|
|
219
|
+
"""
|
|
220
|
+
snapshot: dict[str, str] = dict(os.environ)
|
|
221
|
+
resolved = settings if settings is not None else runtime.configured_settings()
|
|
222
|
+
env_file: Any
|
|
223
|
+
if resolved is not None and hasattr(resolved, "_env_file"):
|
|
224
|
+
env_file = resolved._env_file
|
|
225
|
+
else:
|
|
226
|
+
env_file = resolve_env_file()
|
|
227
|
+
if env_file is not None:
|
|
228
|
+
try:
|
|
229
|
+
for key, value in dotenv_values(env_file).items():
|
|
230
|
+
if value is not None:
|
|
231
|
+
snapshot.setdefault(key, value)
|
|
232
|
+
except OSError: # pragma: no cover - resolve_env_file already checked
|
|
233
|
+
logger.warning("could not read %s while describing runtime settings", env_file)
|
|
234
|
+
return snapshot
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
def is_env_managed(field: SettingsField, env: Mapping[str, str]) -> bool:
|
|
238
|
+
"""True when the environment (or .env) explicitly sets this field."""
|
|
239
|
+
if not field.env_var:
|
|
240
|
+
return False
|
|
241
|
+
return field.env_var in env or field.env_var.upper() in env
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
def _env_value(field: SettingsField, env: Mapping[str, str]) -> str | None:
|
|
245
|
+
if not field.env_var:
|
|
246
|
+
return None
|
|
247
|
+
return env.get(field.env_var) or env.get(field.env_var.upper())
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
def _describe_field(
|
|
251
|
+
field: SettingsField,
|
|
252
|
+
raw: Mapping[str, Any],
|
|
253
|
+
*,
|
|
254
|
+
env: Mapping[str, str],
|
|
255
|
+
persisted: Mapping[str, Any],
|
|
256
|
+
) -> dict[str, Any]:
|
|
257
|
+
value = raw.get(field.name)
|
|
258
|
+
managed = is_env_managed(field, env)
|
|
259
|
+
# A secret is writable unless the environment supplies it: the UI accepts
|
|
260
|
+
# a replacement and never receives the stored value back.
|
|
261
|
+
read_only = managed
|
|
262
|
+
if managed:
|
|
263
|
+
source = "environment"
|
|
264
|
+
elif field.name in persisted:
|
|
265
|
+
source = "runtime"
|
|
266
|
+
else:
|
|
267
|
+
source = "config"
|
|
268
|
+
return {
|
|
269
|
+
"name": field.name,
|
|
270
|
+
"label": field.label,
|
|
271
|
+
"type": field.type,
|
|
272
|
+
"description": field.description,
|
|
273
|
+
"enum": list(field.enum) if field.enum else None,
|
|
274
|
+
"minimum": field.minimum,
|
|
275
|
+
"maximum": field.maximum,
|
|
276
|
+
"env_var": field.env_var,
|
|
277
|
+
"secret": field.secret,
|
|
278
|
+
"group": field.group,
|
|
279
|
+
"group_title": field.group_title,
|
|
280
|
+
"subgroup": field.subgroup,
|
|
281
|
+
"subgroup_title": field.subgroup_title,
|
|
282
|
+
"read_only": read_only,
|
|
283
|
+
"source": source,
|
|
284
|
+
# A secret never leaves the process; its presence is the useful fact.
|
|
285
|
+
# An environment value counts even when the running instance predates
|
|
286
|
+
# it (the environment is authoritative at the next restart).
|
|
287
|
+
"value": None if field.secret else value,
|
|
288
|
+
"configured": (bool(_env_value(field, env) or value) if field.secret else None),
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
def describe_section(
|
|
293
|
+
section: SettingsSection,
|
|
294
|
+
*,
|
|
295
|
+
env: Mapping[str, str] | None = None,
|
|
296
|
+
persisted: Mapping[str, Any] | None = None,
|
|
297
|
+
) -> dict[str, Any]:
|
|
298
|
+
"""Public, secret-free representation of one section for the admin UI."""
|
|
299
|
+
settings = runtime.configured_settings()
|
|
300
|
+
if settings is None:
|
|
301
|
+
raise RuntimeError("describe_section() requires a configured runtime")
|
|
302
|
+
env = env_snapshot(settings) if env is None else env
|
|
303
|
+
persisted = persisted or {}
|
|
304
|
+
raw = section.read(settings)
|
|
305
|
+
return {
|
|
306
|
+
"key": section.key,
|
|
307
|
+
"title": section.title,
|
|
308
|
+
"description": section.description,
|
|
309
|
+
"fields": [
|
|
310
|
+
_describe_field(field, raw, env=env, persisted=persisted)
|
|
311
|
+
for field in _validated_fields(section)
|
|
312
|
+
],
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
|
|
316
|
+
def describe_sections(
|
|
317
|
+
*,
|
|
318
|
+
env: Mapping[str, str] | None = None,
|
|
319
|
+
overrides: Mapping[str, Mapping[str, Any]] | None = None,
|
|
320
|
+
) -> list[dict[str, Any]]:
|
|
321
|
+
settings = _require_settings()
|
|
322
|
+
env = env_snapshot(settings) if env is None else env
|
|
323
|
+
overrides = overrides or {}
|
|
324
|
+
return [
|
|
325
|
+
describe_section(section, env=env, persisted=overrides.get(section.key, {}))
|
|
326
|
+
for section in settings_sections()
|
|
327
|
+
]
|
|
328
|
+
|
|
329
|
+
|
|
330
|
+
def _validate_value(field: SettingsField, value: Any) -> None:
|
|
331
|
+
"""Type/range check before the owning section's model validation runs."""
|
|
332
|
+
if field.type == "boolean":
|
|
333
|
+
ok = isinstance(value, bool)
|
|
334
|
+
elif field.type == "integer":
|
|
335
|
+
ok = isinstance(value, int) and not isinstance(value, bool)
|
|
336
|
+
elif field.type == "number":
|
|
337
|
+
ok = isinstance(value, (int, float)) and not isinstance(value, bool)
|
|
338
|
+
elif field.type == "string":
|
|
339
|
+
ok = isinstance(value, str)
|
|
340
|
+
elif field.type == "enum":
|
|
341
|
+
ok = isinstance(value, str) and value in (field.enum or ())
|
|
342
|
+
else: # json
|
|
343
|
+
ok = isinstance(value, (dict, list, str, int, float, bool)) or value is None
|
|
344
|
+
if not ok:
|
|
345
|
+
expected = " or ".join(field.enum) if field.type == "enum" else field.type
|
|
346
|
+
raise SettingsValidationError(
|
|
347
|
+
f"{field.label} ({field.name}) must be {expected}, got {type(value).__name__}"
|
|
348
|
+
)
|
|
349
|
+
if field.type in {"integer", "number"}:
|
|
350
|
+
if field.minimum is not None and value < field.minimum:
|
|
351
|
+
raise SettingsValidationError(f"{field.label} must be at least {field.minimum:g}")
|
|
352
|
+
if field.maximum is not None and value > field.maximum:
|
|
353
|
+
raise SettingsValidationError(f"{field.label} must be at most {field.maximum:g}")
|
|
354
|
+
|
|
355
|
+
|
|
356
|
+
def _field_map(section: SettingsSection) -> dict[str, SettingsField]:
|
|
357
|
+
return {field.name: field for field in _validated_fields(section)}
|
|
358
|
+
|
|
359
|
+
|
|
360
|
+
def redact_values(section: SettingsSection, values: Mapping[str, Any]) -> dict[str, Any]:
|
|
361
|
+
"""A copy safe to persist in the audit trail: secret values are masked.
|
|
362
|
+
|
|
363
|
+
Section values are otherwise recorded verbatim so an operator can see
|
|
364
|
+
what changed. ``api_key``-style fields must not end up in the audit log,
|
|
365
|
+
whose readers and retention differ from the settings row's.
|
|
366
|
+
"""
|
|
367
|
+
fields = _field_map(section)
|
|
368
|
+
redacted: dict[str, Any] = {}
|
|
369
|
+
for name, value in values.items():
|
|
370
|
+
field = fields.get(name)
|
|
371
|
+
if field is not None and field.secret:
|
|
372
|
+
redacted[name] = "<redacted>" if value else ""
|
|
373
|
+
else:
|
|
374
|
+
redacted[name] = value
|
|
375
|
+
return redacted
|
|
376
|
+
|
|
377
|
+
|
|
378
|
+
def _clean_values(
|
|
379
|
+
section: SettingsSection,
|
|
380
|
+
values: Mapping[str, Any],
|
|
381
|
+
*,
|
|
382
|
+
env: Mapping[str, str],
|
|
383
|
+
for_write: bool,
|
|
384
|
+
) -> dict[str, Any]:
|
|
385
|
+
"""Filter a stored/proposed mapping to fields the runtime may apply.
|
|
386
|
+
|
|
387
|
+
Unknown keys are ignored on load (a section may have dropped a field) but
|
|
388
|
+
rejected on write. Env-managed fields — secrets included — are always
|
|
389
|
+
dropped: the environment is authoritative for them. A persisted secret
|
|
390
|
+
that the environment does not manage survives the load so the startup
|
|
391
|
+
overlay can apply it.
|
|
392
|
+
"""
|
|
393
|
+
fields = _field_map(section)
|
|
394
|
+
clean: dict[str, Any] = {}
|
|
395
|
+
for name, value in values.items():
|
|
396
|
+
field = fields.get(name)
|
|
397
|
+
if field is None:
|
|
398
|
+
if for_write:
|
|
399
|
+
raise SettingsValidationError(f"unknown setting: {name!r}")
|
|
400
|
+
continue
|
|
401
|
+
if is_env_managed(field, env):
|
|
402
|
+
if for_write:
|
|
403
|
+
raise SettingsValidationError(
|
|
404
|
+
f"{field.label} is managed by {field.env_var} and cannot be changed at runtime"
|
|
405
|
+
)
|
|
406
|
+
continue
|
|
407
|
+
if for_write:
|
|
408
|
+
_validate_value(field, value)
|
|
409
|
+
clean[name] = value
|
|
410
|
+
return clean
|
|
411
|
+
|
|
412
|
+
|
|
413
|
+
def _require_settings() -> Any:
|
|
414
|
+
settings = runtime.configured_settings()
|
|
415
|
+
if settings is None:
|
|
416
|
+
raise RuntimeError("runtime settings require a configured runtime")
|
|
417
|
+
return settings
|
|
418
|
+
|
|
419
|
+
|
|
420
|
+
async def load_overrides(db: AsyncSession | None = None) -> dict[str, dict[str, Any]]:
|
|
421
|
+
"""Read every persisted section row (empty when the table is absent)."""
|
|
422
|
+
owns_session = db is None
|
|
423
|
+
session = open_session() if db is None else db
|
|
424
|
+
try:
|
|
425
|
+
rows = (await session.execute(select(AppSetting))).scalars().all()
|
|
426
|
+
return {row.section: dict(row.values or {}) for row in rows}
|
|
427
|
+
finally:
|
|
428
|
+
if owns_session:
|
|
429
|
+
# Startup overlays must never fail on teardown: a session whose
|
|
430
|
+
# connection could not be acquired (or belongs to another event
|
|
431
|
+
# loop) may also fail to close, and that error must not replace
|
|
432
|
+
# the read error the caller is about to handle.
|
|
433
|
+
try:
|
|
434
|
+
await session.close()
|
|
435
|
+
except Exception: # pragma: no cover - defensive teardown
|
|
436
|
+
logger.warning("could not close the runtime-settings session", exc_info=True)
|
|
437
|
+
|
|
438
|
+
|
|
439
|
+
def is_missing_table(exc: SQLAlchemyError) -> bool:
|
|
440
|
+
original = getattr(exc, "orig", None)
|
|
441
|
+
pgcode = getattr(original, "pgcode", None)
|
|
442
|
+
text = str(original or exc).lower()
|
|
443
|
+
return (
|
|
444
|
+
pgcode == "42P01"
|
|
445
|
+
or "undefinedtable" in text
|
|
446
|
+
or "no such table" in text
|
|
447
|
+
or "does not exist" in text
|
|
448
|
+
)
|
|
449
|
+
|
|
450
|
+
|
|
451
|
+
async def update_section(
|
|
452
|
+
db: AsyncSession,
|
|
453
|
+
section: SettingsSection,
|
|
454
|
+
values: Mapping[str, Any],
|
|
455
|
+
*,
|
|
456
|
+
actor_id: int | None,
|
|
457
|
+
) -> dict[str, Any]:
|
|
458
|
+
"""Validate, apply live, and persist a partial section update.
|
|
459
|
+
|
|
460
|
+
The caller owns the transaction (the admin API writes its audit row and
|
|
461
|
+
commits both changes together). On a validation failure nothing is
|
|
462
|
+
persisted and — because sections validate before mutating — the live
|
|
463
|
+
settings are unchanged.
|
|
464
|
+
"""
|
|
465
|
+
if not isinstance(values, Mapping):
|
|
466
|
+
raise SettingsValidationError("values must be an object")
|
|
467
|
+
settings = _require_settings()
|
|
468
|
+
env = env_snapshot(settings)
|
|
469
|
+
clean = _clean_values(section, values, env=env, for_write=True)
|
|
470
|
+
|
|
471
|
+
row = await db.get(AppSetting, section.key)
|
|
472
|
+
stored = dict(row.values or {}) if row is not None else {}
|
|
473
|
+
merged = {**stored, **clean}
|
|
474
|
+
# A value stored before its field became environment-managed must not
|
|
475
|
+
# override the environment in-process.
|
|
476
|
+
merged = _clean_values(section, merged, env=env, for_write=False)
|
|
477
|
+
|
|
478
|
+
section.apply(settings, merged)
|
|
479
|
+
|
|
480
|
+
if row is None:
|
|
481
|
+
row = AppSetting(section=section.key, values=merged, updated_by=actor_id)
|
|
482
|
+
db.add(row)
|
|
483
|
+
else:
|
|
484
|
+
row.values = merged
|
|
485
|
+
row.updated_by = actor_id
|
|
486
|
+
await db.flush()
|
|
487
|
+
return merged
|
|
488
|
+
|
|
489
|
+
|
|
490
|
+
async def reset_section(
|
|
491
|
+
db: AsyncSession, section: SettingsSection, *, actor_id: int | None
|
|
492
|
+
) -> None:
|
|
493
|
+
"""Delete the section's persisted row and restore the startup baseline."""
|
|
494
|
+
settings = _require_settings()
|
|
495
|
+
baseline = runtime.baseline_settings()
|
|
496
|
+
if baseline is None: # pragma: no cover - configure always stores one
|
|
497
|
+
raise RuntimeError("runtime baseline is unavailable")
|
|
498
|
+
env = env_snapshot(settings)
|
|
499
|
+
baseline_values = dict(section.read(baseline))
|
|
500
|
+
restore = _clean_values(section, baseline_values, env=env, for_write=False)
|
|
501
|
+
section.apply(settings, restore)
|
|
502
|
+
await db.execute(delete(AppSetting).where(AppSetting.section == section.key))
|
|
503
|
+
await db.flush()
|
|
504
|
+
|
|
505
|
+
|
|
506
|
+
async def load_persisted_settings() -> None:
|
|
507
|
+
"""Apply every persisted override at startup (best effort).
|
|
508
|
+
|
|
509
|
+
Called by each package's lifespan. A missing table (migrations not yet
|
|
510
|
+
applied) is a warning, not a crash: the application still serves static
|
|
511
|
+
configuration. Any other read failure is handled the same way — the
|
|
512
|
+
overlay is an optimization, and no database condition at startup may
|
|
513
|
+
prevent the process from serving. A bad row is logged and skipped for the
|
|
514
|
+
same reason — one malformed section must not take the process down.
|
|
515
|
+
"""
|
|
516
|
+
if not runtime.is_configured():
|
|
517
|
+
return
|
|
518
|
+
settings = runtime.configured_settings()
|
|
519
|
+
try:
|
|
520
|
+
overrides = await load_overrides()
|
|
521
|
+
except Exception as exc:
|
|
522
|
+
if isinstance(exc, SQLAlchemyError) and is_missing_table(exc):
|
|
523
|
+
logger.warning(
|
|
524
|
+
"app_settings table is missing; runtime settings overrides are disabled "
|
|
525
|
+
"until the basic migration chain is applied"
|
|
526
|
+
)
|
|
527
|
+
else:
|
|
528
|
+
logger.exception("could not read app_settings; continuing with static configuration")
|
|
529
|
+
return
|
|
530
|
+
|
|
531
|
+
env = env_snapshot(settings)
|
|
532
|
+
for key, values in overrides.items():
|
|
533
|
+
section = get_settings_section(key)
|
|
534
|
+
if section is None:
|
|
535
|
+
logger.warning(
|
|
536
|
+
"app_settings row for unknown section %r ignored (owning package not installed?)",
|
|
537
|
+
key,
|
|
538
|
+
)
|
|
539
|
+
continue
|
|
540
|
+
try:
|
|
541
|
+
clean = _clean_values(section, values, env=env, for_write=False)
|
|
542
|
+
section.apply(settings, clean)
|
|
543
|
+
except Exception:
|
|
544
|
+
logger.exception(
|
|
545
|
+
"could not apply persisted settings for section %r; using static configuration",
|
|
546
|
+
key,
|
|
547
|
+
)
|
|
548
|
+
|
|
549
|
+
|
|
550
|
+
@asynccontextmanager
|
|
551
|
+
async def settings_lifespan(_app: Any):
|
|
552
|
+
"""Lifespan wrapper: overlay persisted settings, then release the engine."""
|
|
553
|
+
await load_persisted_settings()
|
|
554
|
+
try:
|
|
555
|
+
yield
|
|
556
|
+
finally:
|
|
557
|
+
await runtime.dispose()
|
|
File without changes
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
"""Pydantic schemas for the Item demo entity (request/response contracts)."""
|
|
2
|
+
|
|
3
|
+
from datetime import datetime
|
|
4
|
+
|
|
5
|
+
from pydantic import BaseModel, ConfigDict, Field
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class ItemBase(BaseModel):
|
|
9
|
+
name: str = Field(min_length=1, max_length=200)
|
|
10
|
+
description: str = Field(default="", max_length=10_000)
|
|
11
|
+
quantity: int = Field(default=0, ge=0)
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class ItemCreate(ItemBase):
|
|
15
|
+
"""Payload for POST /api/v1/items."""
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class ItemUpdate(BaseModel):
|
|
19
|
+
"""Payload for PATCH /api/v1/items/{id} — all fields optional."""
|
|
20
|
+
|
|
21
|
+
name: str | None = Field(default=None, min_length=1, max_length=200)
|
|
22
|
+
description: str | None = Field(default=None, max_length=10_000)
|
|
23
|
+
quantity: int | None = Field(default=None, ge=0)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class ItemRead(ItemBase):
|
|
27
|
+
model_config = ConfigDict(from_attributes=True)
|
|
28
|
+
|
|
29
|
+
id: int
|
|
30
|
+
created_at: datetime
|
|
31
|
+
updated_at: datetime
|
|
File without changes
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"""Item CRUD service.
|
|
2
|
+
|
|
3
|
+
Functions take an `AsyncSession` and stay transport-agnostic: routers own
|
|
4
|
+
HTTP concerns, services own persistence rules. This layer is the seam a
|
|
5
|
+
consuming project (or a real domain) extends.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from sqlalchemy import func, select
|
|
9
|
+
from sqlalchemy.ext.asyncio import AsyncSession
|
|
10
|
+
|
|
11
|
+
from cliver_playbook.app.basic.models.entities import Item
|
|
12
|
+
from cliver_playbook.app.basic.schemas.item import ItemCreate, ItemUpdate
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
async def list_items(
|
|
16
|
+
db: AsyncSession, *, limit: int = 50, offset: int = 0
|
|
17
|
+
) -> tuple[list[Item], int]:
|
|
18
|
+
"""Return (items, total_count) ordered by newest first."""
|
|
19
|
+
rows = await db.execute(
|
|
20
|
+
select(Item).order_by(Item.created_at.desc(), Item.id.desc()).limit(limit).offset(offset)
|
|
21
|
+
)
|
|
22
|
+
total = await db.scalar(select(func.count()).select_from(Item))
|
|
23
|
+
return list(rows.scalars().all()), int(total or 0)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
async def get_item(db: AsyncSession, item_id: int) -> Item | None:
|
|
27
|
+
return await db.get(Item, item_id)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
async def create_item(db: AsyncSession, payload: ItemCreate) -> Item:
|
|
31
|
+
item = Item(**payload.model_dump())
|
|
32
|
+
db.add(item)
|
|
33
|
+
await db.commit()
|
|
34
|
+
await db.refresh(item)
|
|
35
|
+
return item
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
async def update_item(db: AsyncSession, item: Item, payload: ItemUpdate) -> Item:
|
|
39
|
+
changes = payload.model_dump(exclude_unset=True)
|
|
40
|
+
for field, value in changes.items():
|
|
41
|
+
setattr(item, field, value)
|
|
42
|
+
if changes:
|
|
43
|
+
await db.commit()
|
|
44
|
+
await db.refresh(item)
|
|
45
|
+
return item
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
async def delete_item(db: AsyncSession, item: Item) -> None:
|
|
49
|
+
await db.delete(item)
|
|
50
|
+
await db.commit()
|