settings.py 91 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044
  1. import asyncio
  2. import io
  3. import json
  4. import logging
  5. import os
  6. import zipfile
  7. from datetime import datetime
  8. from pathlib import Path
  9. from fastapi import APIRouter, Depends, File, HTTPException, UploadFile
  10. from fastapi.responses import FileResponse, JSONResponse
  11. from pydantic import BaseModel, Field
  12. from sqlalchemy import func, select
  13. from sqlalchemy.ext.asyncio import AsyncSession
  14. from backend.app.core.auth import (
  15. RequestPrinterScope,
  16. RequireAdminIfAuthEnabled,
  17. RequirePermissionIfAuthEnabled,
  18. ScopedCaller,
  19. caller_is_api_key,
  20. is_auth_enabled,
  21. require_auth_if_enabled,
  22. require_energy_cost_update,
  23. )
  24. from backend.app.core.config import APP_VERSION, settings as app_settings
  25. from backend.app.core.database import get_db
  26. from backend.app.core.permissions import Permission
  27. from backend.app.core.printer_scope import PrinterScope
  28. from backend.app.models.settings import Settings
  29. from backend.app.models.user import User
  30. from backend.app.schemas.settings import ADMIN_ONLY_SETTING_KEYS, AppSettings, AppSettingsUpdate
  31. from backend.app.services import camera_light
  32. from backend.app.services.secret_fields import SETTINGS_SECRETS, SecretConfigError, mask_fields, merge_partial
  33. logger = logging.getLogger(__name__)
  34. router = APIRouter(prefix="/settings", tags=["settings"])
  35. DEFAULT_SETTINGS = AppSettings()
  36. # Sensitive credential fields blanked for API-key callers. Everyone else sees
  37. # them as the placeholder (write-only secrets, see services/secret_fields).
  38. _SENSITIVE_FIELDS_FOR_API_KEY = (*SETTINGS_SECRETS, "octoeverywhere_api_key")
  39. async def get_setting(db: AsyncSession, key: str) -> str | None:
  40. """Get a single setting value by key."""
  41. result = await db.execute(select(Settings).where(Settings.key == key))
  42. setting = result.scalar_one_or_none()
  43. return setting.value if setting else None
  44. # Accepted spellings for a boolean settings value. Settings live in a VARCHAR
  45. # column and every reader compares them as strings, so these are normalised to
  46. # "true"/"false" on the way in. The sets are deliberately generous: these
  47. # endpoints are part of the documented REST surface, reached by scripts and by
  48. # Home Assistant rest_command, where "True", "1" and "on" are all natural.
  49. _TRUTHY_SETTING_VALUES = frozenset({"true", "1", "yes", "on"})
  50. _FALSY_SETTING_VALUES = frozenset({"false", "0", "no", "off"})
  51. def setting_is_true(value: object) -> bool:
  52. """Return True if a *stored* settings value means "on".
  53. Deliberately narrower than the spellings ``normalize_bool_setting`` accepts:
  54. it matches only what every other reader in the codebase treats as on
  55. (``value.lower() == "true"``). Submitted values are canonicalised on write,
  56. so a stored value is always "true"/"false"/""; accepting "1" or "on" here
  57. would make this function disagree with the rest of the app about any legacy
  58. row containing them.
  59. A bool is tolerated for the case of a row written before values were
  60. normalised, where SQLite coerced a raw bool into the VARCHAR column.
  61. """
  62. if isinstance(value, bool):
  63. return value
  64. if value is None:
  65. return False
  66. return str(value).strip().lower() == "true"
  67. def normalize_bool_setting(key: str, value: object) -> str:
  68. """Coerce a boolean-ish settings value to the canonical "true"/"false".
  69. Raises HTTPException(400) for values with no sensible interpretation, so an
  70. API client gets a message naming the field instead of a 500.
  71. A JSON boolean is the natural thing for an API client to send, and before
  72. this normalisation it caused two distinct failures on
  73. ``PUT /settings/spoolman``: ``bool.lower()`` raised AttributeError, and the
  74. raw bool was written into a VARCHAR column, which SQLite silently coerces
  75. to 1/0 while asyncpg rejects outright. Both surfaced as an opaque 500.
  76. """
  77. if isinstance(value, bool): # must precede the int branch — bool is an int
  78. return "true" if value else "false"
  79. if isinstance(value, int):
  80. if value in (0, 1):
  81. return "true" if value else "false"
  82. raise HTTPException(400, f"{key} must be a boolean; got the number {value}")
  83. if isinstance(value, str):
  84. candidate = value.strip().lower()
  85. if not candidate:
  86. # Empty is stored verbatim rather than normalised to "false".
  87. # get_spoolman_settings reads these with ``or "<default>"``, so an
  88. # empty stored value means "use the default" — and two of them
  89. # (spoolman_report_partial_usage, auto_add_unknown_rfid) default to
  90. # ON. Rewriting "" to "false" would silently switch them off for any
  91. # client that submits a blank value.
  92. return ""
  93. if candidate in _TRUTHY_SETTING_VALUES:
  94. return "true"
  95. if candidate in _FALSY_SETTING_VALUES:
  96. return "false"
  97. raise HTTPException(400, f"{key} must be a boolean; got {value!r}")
  98. raise HTTPException(400, f"{key} must be a boolean; got {type(value).__name__}")
  99. def normalize_str_setting(key: str, value: object) -> str:
  100. """Return a string settings value, rejecting types that would store garbage.
  101. ``str()`` on a dict or list would persist its repr, so those are refused
  102. rather than silently written. Numbers are accepted and stringified: a port
  103. or a bare host submitted unquoted is a plausible client mistake, not a
  104. reason to fail the request.
  105. """
  106. if isinstance(value, str):
  107. return value
  108. if value is None:
  109. return ""
  110. if isinstance(value, bool | int | float):
  111. return str(value)
  112. raise HTTPException(400, f"{key} must be a string; got {type(value).__name__}")
  113. async def get_external_base_url(db: AsyncSession) -> str:
  114. """Base URL for links Bambuddy hands to the outside world (no trailing slash).
  115. ``external_url`` is optional and has no default, so anything that must be
  116. absolute — a login link in an e-mail, the one-tap outcome verdict links
  117. (#1898), whose Telegram/ntfy buttons are dropped for a relative URL — falls
  118. back to APP_URL and finally to the dev origin.
  119. """
  120. import os
  121. external_url = await get_setting(db, "external_url")
  122. if external_url:
  123. return external_url.rstrip("/")
  124. return os.environ.get("APP_URL", "http://localhost:5173").rstrip("/")
  125. async def get_external_login_url(db: AsyncSession) -> str:
  126. """Get the external URL for the login page.
  127. Uses external_url from settings if available, otherwise falls back to APP_URL env var.
  128. Args:
  129. db: Database session
  130. Returns:
  131. Full URL to the login page
  132. """
  133. return await get_external_base_url(db) + "/login"
  134. async def set_setting(db: AsyncSession, key: str, value: str) -> None:
  135. """Set a single setting value."""
  136. from backend.app.core.db_dialect import upsert_setting
  137. await upsert_setting(db, Settings, key, value)
  138. # Settings stored as booleans / numbers. Storage is a VARCHAR column, so
  139. # _build_settings_response() parses these back, and update_settings() refuses
  140. # an explicit null for them: a null is stored as the literal "None", which
  141. # reads back as False for a boolean and is not a number at all.
  142. _BOOL_SETTING_KEYS = frozenset(
  143. {
  144. "auto_archive",
  145. "save_thumbnails",
  146. "capture_finish_photo",
  147. "finish_photo_restore_plate",
  148. "spoolman_enabled",
  149. "spoolman_disable_weight_sync",
  150. "spoolman_report_partial_usage",
  151. "auto_add_unknown_rfid",
  152. "disable_filament_warnings",
  153. "prefer_lowest_filament",
  154. "check_updates",
  155. "check_printer_firmware",
  156. "include_beta_updates",
  157. "announcements_enabled",
  158. "announcements_all_users",
  159. "ftp_retry_enabled",
  160. "mqtt_enabled",
  161. "mqtt_use_tls",
  162. "ha_enabled",
  163. "per_printer_mapping_expanded",
  164. "prometheus_enabled",
  165. "user_notifications_enabled",
  166. "queue_drying_enabled",
  167. "queue_drying_block",
  168. "ambient_drying_enabled",
  169. "print_drying_enabled",
  170. "require_plate_clear",
  171. "queue_shortest_first",
  172. # default_bed_levelling / default_flow_cali / default_nozzle_offset_cali
  173. # are tri-state strings (off/on/auto) — parsed via the raw-string else
  174. # branch; the TriState validator coerces legacy "true"/"false" rows.
  175. "default_vibration_cali",
  176. "default_layer_inspect",
  177. "default_timelapse",
  178. "default_confirm_outcome",
  179. "confirm_outcome_external_prints",
  180. "confirm_default_good_on_plate_clear",
  181. "billing_enabled",
  182. "printer_kill_switch_enabled",
  183. "ldap_enabled",
  184. "ldap_auto_provision",
  185. "local_login_enabled",
  186. "preheat_enabled",
  187. "queue_keep_bed_warm",
  188. "obico_enabled",
  189. "octoeverywhere_enabled",
  190. }
  191. )
  192. _FLOAT_SETTING_KEYS = frozenset(
  193. {
  194. "default_filament_cost",
  195. "energy_cost_per_kwh",
  196. "camera_light_delay",
  197. "ams_temp_good",
  198. "ams_temp_fair",
  199. "library_disk_warning_gb",
  200. "low_stock_threshold",
  201. }
  202. )
  203. # String settings limited to a fixed set of values, which a stored "None"
  204. # would break when the settings response is built.
  205. _ENUM_SETTING_KEYS = frozenset(
  206. {"energy_price_source", "obico_sensitivity", "obico_action", "octoeverywhere_confidence", "octoeverywhere_action"}
  207. )
  208. _INT_SETTING_KEYS = frozenset(
  209. {
  210. "ams_humidity_good",
  211. "ams_humidity_fair",
  212. "ams_history_retention_days",
  213. "printer_sensor_history_retention_days",
  214. "ftp_retry_count",
  215. "ftp_retry_delay",
  216. "ftp_timeout",
  217. "mqtt_port",
  218. "stagger_group_size",
  219. "stagger_interval_minutes",
  220. "forecast_global_lead_time_days",
  221. "location_sensor_poll_interval",
  222. "finance_budget_reset_day",
  223. "session_max_hours",
  224. "pipeline_max_copies",
  225. "preheat_max_wait_seconds",
  226. "preheat_soak_seconds",
  227. "queue_keep_warm_bed_temp",
  228. "queue_keep_warm_max_minutes",
  229. "queue_max_concurrent_uploads",
  230. "ambient_drying_sustained_minutes",
  231. "pause_warning_minutes",
  232. "obico_poll_interval",
  233. "octoeverywhere_poll_interval",
  234. }
  235. )
  236. async def _build_settings_response(db: AsyncSession, is_api_key: bool = False, mask: bool = True) -> AppSettings:
  237. """Build the full settings response.
  238. Secrets are blank for API-key callers and the placeholder for everyone else;
  239. ``mask=False`` is for server-side use only (comparing with an update).
  240. """
  241. settings_dict = DEFAULT_SETTINGS.model_dump()
  242. result = await db.execute(select(Settings))
  243. for setting in result.scalars().all():
  244. if setting.key not in settings_dict:
  245. continue
  246. if setting.key in _BOOL_SETTING_KEYS:
  247. settings_dict[setting.key] = setting.value.lower() == "true"
  248. elif setting.key in _FLOAT_SETTING_KEYS or setting.key in _INT_SETTING_KEYS:
  249. # A value that does not parse (the literal "None" from an old
  250. # null save, or a hand-edited row) keeps the default instead of
  251. # taking the whole settings response down with it.
  252. parse = int if setting.key in _INT_SETTING_KEYS else float
  253. try:
  254. settings_dict[setting.key] = parse(setting.value)
  255. except (TypeError, ValueError):
  256. logger.warning("Setting %s has an unparseable value; using the default", setting.key)
  257. elif setting.key in [
  258. # Nullable floats. Settings storage stringifies None to the literal
  259. # "None", which must read back as null here -- not as the default
  260. # the _FLOAT_SETTING_KEYS branch above falls back to (#2905).
  261. "ams_temp_alarm",
  262. ]:
  263. try:
  264. settings_dict[setting.key] = float(setting.value)
  265. except (TypeError, ValueError):
  266. settings_dict[setting.key] = None
  267. elif setting.key == "default_printer_id":
  268. settings_dict[setting.key] = int(setting.value) if setting.value and setting.value != "None" else None
  269. elif setting.key == "open_in_slicer":
  270. # None means "inherit from preferred_slicer" (#1329). The PUT path
  271. # serializes None as the literal string "None"; strip it back so
  272. # the frontend sees a true null and falls back as intended.
  273. settings_dict[setting.key] = setting.value if setting.value and setting.value != "None" else None
  274. else:
  275. settings_dict[setting.key] = setting.value
  276. ha_settings = await get_homeassistant_settings(db)
  277. settings_dict.update(ha_settings)
  278. # ldap_bind_password is never returned to any caller (mask=False is
  279. # server-side only)
  280. if mask or is_api_key:
  281. settings_dict["ldap_bind_password"] = ""
  282. # The saved key is write-only, including for authenticated administrators.
  283. settings_dict["octoeverywhere_api_key_configured"] = bool(settings_dict["octoeverywhere_api_key"].strip())
  284. settings_dict["octoeverywhere_api_key"] = ""
  285. if is_api_key:
  286. for field in _SENSITIVE_FIELDS_FOR_API_KEY:
  287. if field in settings_dict:
  288. settings_dict[field] = ""
  289. elif mask:
  290. settings_dict = mask_fields(settings_dict, SETTINGS_SECRETS)
  291. return AppSettings(**settings_dict)
  292. @router.get("", response_model=AppSettings)
  293. @router.get("/", response_model=AppSettings)
  294. async def get_settings(
  295. db: AsyncSession = Depends(get_db, scope="function"),
  296. _: User | None = RequirePermissionIfAuthEnabled(Permission.SETTINGS_READ),
  297. _is_api_key: bool = Depends(caller_is_api_key),
  298. ):
  299. """Get all application settings."""
  300. return await _build_settings_response(db, is_api_key=_is_api_key)
  301. def _as_stored_setting(value: object) -> str:
  302. """The text the settings writer below stores for ``value``."""
  303. if isinstance(value, bool):
  304. return "true" if value else "false"
  305. if value is None:
  306. return "None"
  307. return str(value)
  308. def _same_setting_value(new: object, old: object) -> bool:
  309. """Whether saving ``new`` stores exactly what ``old`` is stored as."""
  310. return _as_stored_setting(new) == _as_stored_setting(old)
  311. @router.put("/", response_model=AppSettings)
  312. async def update_settings(
  313. settings_update: AppSettingsUpdate,
  314. db: AsyncSession = Depends(get_db, scope="function"),
  315. current_user: User | None = RequirePermissionIfAuthEnabled(Permission.SETTINGS_UPDATE),
  316. ):
  317. """Update application settings."""
  318. update_data = settings_update.model_dump(exclude_unset=True)
  319. # Write-only secrets: the placeholder keeps the stored value, and a kept
  320. # secret does not follow a changed destination.
  321. stored = (await _build_settings_response(db, mask=False)).model_dump()
  322. secrets = dict(SETTINGS_SECRETS)
  323. if stored.get("ha_token_from_env"):
  324. # The deployment's own token, not a stored secret to enter again: the
  325. # URL may change (the placeholder sent back still writes nothing).
  326. secrets["ha_token"] = ()
  327. try:
  328. update_data = merge_partial(stored, update_data, secrets)
  329. except SecretConfigError as exc:
  330. raise HTTPException(status_code=400, detail=str(exc)) from None
  331. # Omitted/null preserves the saved key; an explicit empty string removes it.
  332. if update_data.get("octoeverywhere_api_key") is None:
  333. update_data.pop("octoeverywhere_api_key", None)
  334. # These typed settings are not clearable: null would be stored as "None".
  335. # Check before normalizing provider flags so enabling one cannot hide a
  336. # null submitted for the other.
  337. null_keys = sorted(
  338. key
  339. for key, value in update_data.items()
  340. if value is None and key in (_BOOL_SETTING_KEYS | _FLOAT_SETTING_KEYS | _INT_SETTING_KEYS | _ENUM_SETTING_KEYS)
  341. )
  342. if null_keys:
  343. raise HTTPException(status_code=422, detail=f"These settings cannot be null: {', '.join(null_keys)}")
  344. # Only one failure detection provider may control a print at a time.
  345. if update_data.get("obico_enabled") and update_data.get("octoeverywhere_enabled"):
  346. raise HTTPException(status_code=400, detail="Enable only one AI failure detection provider at a time.")
  347. if update_data.get("octoeverywhere_enabled"):
  348. update_data["obico_enabled"] = False
  349. elif update_data.get("obico_enabled"):
  350. update_data["octoeverywhere_enabled"] = False
  351. # Settings that decide who can sign in are admin-only, like the user routes.
  352. # Only a real change counts: the settings page sends every field on each
  353. # save, so an unchanged value from a non-admin must pass.
  354. if current_user is not None and not current_user.is_admin:
  355. changed = sorted(
  356. key
  357. for key in update_data
  358. if key in ADMIN_ONLY_SETTING_KEYS and not _same_setting_value(update_data[key], stored.get(key))
  359. )
  360. if changed:
  361. raise HTTPException(
  362. status_code=403,
  363. detail=f"Only an administrator can change these settings: {', '.join(changed)}",
  364. )
  365. # Like an API key's or a provider's printers: a page still open from before
  366. # a printer delete would save the deleted id, which SQLite gives to the next
  367. # printer created (the validator has already checked it is a list of ints).
  368. # Only ids not stored yet are checked: the page sends the whole list, and an
  369. # id already there must not block every save.
  370. for key in ("obico_enabled_printers", "octoeverywhere_enabled_printers"):
  371. if not update_data.get(key):
  372. continue
  373. from backend.app.core.printer_scope import ensure_printers_exist
  374. try:
  375. stored_printers = json.loads(await get_setting(db, key) or "[]")
  376. except ValueError:
  377. stored_printers = []
  378. stored_printers = set(stored_printers) if isinstance(stored_printers, list) else set()
  379. added = [i for i in json.loads(update_data[key]) if i not in stored_printers]
  380. await ensure_printers_exist(db, added)
  381. # Safety refusals on disabling local login (#1589). Two failure modes
  382. # would otherwise lock everyone out of the install:
  383. # 1. No enabled OIDC provider exists — nobody could authenticate.
  384. # 2. The caller has no UserOIDCLink — they would lock themselves out
  385. # even if other admins are linked.
  386. # Either case returns HTTP 400 instead of silently saving. The
  387. # ``BAMBUDDY_LOCAL_LOGIN=true`` env-var bypass on /auth/login is a
  388. # separate recovery path; the refusals here protect the *default*
  389. # configuration where the env var is absent.
  390. if update_data.get("local_login_enabled") is False:
  391. from backend.app.models.oidc_provider import OIDCProvider, UserOIDCLink
  392. enabled_count = await db.scalar(select(func.count(OIDCProvider.id)).where(OIDCProvider.is_enabled.is_(True)))
  393. if not enabled_count:
  394. raise HTTPException(
  395. status_code=400,
  396. detail="Cannot disable local login: no OIDC provider is enabled.",
  397. )
  398. if current_user is not None:
  399. caller_links = await db.scalar(
  400. select(func.count(UserOIDCLink.id)).where(UserOIDCLink.user_id == current_user.id)
  401. )
  402. if not caller_links:
  403. raise HTTPException(
  404. status_code=400,
  405. detail="Cannot disable local login: your account has no OIDC link, so you would lock yourself out.",
  406. )
  407. # Check if any MQTT settings are being updated
  408. mqtt_keys = {
  409. "mqtt_enabled",
  410. "mqtt_broker",
  411. "mqtt_port",
  412. "mqtt_username",
  413. "mqtt_password",
  414. "mqtt_topic_prefix",
  415. "mqtt_use_tls",
  416. }
  417. mqtt_updated = bool(mqtt_keys & set(update_data.keys()))
  418. # The page saves every field it shows on each change, so compare against
  419. # what is stored: only a real change of price source is worth a read.
  420. price_source_changed = False
  421. for key in ("energy_price_source", "energy_price_ha_entity"):
  422. if key in update_data and str(update_data[key]) != (await get_setting(db, key) or ""):
  423. price_source_changed = True
  424. for key, value in update_data.items():
  425. # Convert value to string for storage
  426. await set_setting(db, key, _as_stored_setting(value))
  427. await db.commit()
  428. # Expire all objects to ensure fresh reads after commit
  429. db.expire_all()
  430. if update_data.get("obico_enabled") is False:
  431. from backend.app.services.obico_detection import obico_detection_service
  432. await obico_detection_service.refresh_settings()
  433. if any(key.startswith("octoeverywhere_") for key in update_data):
  434. from backend.app.services.octoeverywhere_detection import octoeverywhere_detection_service
  435. await octoeverywhere_detection_service.refresh_settings()
  436. if {"camera_light_mode", "camera_light_delay"} & set(update_data.keys()):
  437. camera_light.invalidate_settings()
  438. if "require_plate_clear" in update_data:
  439. from backend.app.services.wled import wled_manager
  440. wled_manager.require_plate_clear = update_data["require_plate_clear"]
  441. if price_source_changed:
  442. # Read a newly chosen price sensor now, so the saved settings show its
  443. # price instead of the old one until the next hourly read (#1251).
  444. from backend.app.services.energy_price import current_price
  445. try:
  446. await current_price(db, remember=True)
  447. await db.commit()
  448. except Exception as e:
  449. logger.warning("Could not read the electricity price after saving its source: %s", e)
  450. # Reconfigure MQTT relay if any MQTT settings changed
  451. if mqtt_updated:
  452. try:
  453. from backend.app.services.mqtt_relay import mqtt_relay
  454. mqtt_settings = {
  455. "mqtt_enabled": (await get_setting(db, "mqtt_enabled") or "false") == "true",
  456. "mqtt_broker": await get_setting(db, "mqtt_broker") or "",
  457. "mqtt_port": int(await get_setting(db, "mqtt_port") or "1883"),
  458. "mqtt_username": await get_setting(db, "mqtt_username") or "",
  459. "mqtt_password": await get_setting(db, "mqtt_password") or "",
  460. "mqtt_topic_prefix": await get_setting(db, "mqtt_topic_prefix") or "bambuddy",
  461. "mqtt_use_tls": (await get_setting(db, "mqtt_use_tls") or "false") == "true",
  462. }
  463. await mqtt_relay.configure(mqtt_settings)
  464. except Exception:
  465. pass # Don't fail the settings update if MQTT reconfiguration fails
  466. # Return updated settings, secrets as the placeholder
  467. return await _build_settings_response(db, is_api_key=False)
  468. @router.patch("/", response_model=AppSettings)
  469. @router.patch("", response_model=AppSettings)
  470. async def patch_settings(
  471. settings_update: AppSettingsUpdate,
  472. db: AsyncSession = Depends(get_db, scope="function"),
  473. _: User | None = RequirePermissionIfAuthEnabled(Permission.SETTINGS_UPDATE),
  474. ):
  475. """Partially update application settings (same as PUT, for REST compatibility)."""
  476. return await update_settings(settings_update, db, _)
  477. class ElectricityPriceUpdate(BaseModel):
  478. """Payload for ``POST /settings/electricity-price`` (#1356).
  479. Mirrors the field name documented in ``wiki/features/energy.md`` so the
  480. Home Assistant ``rest_command`` example needs only a URL change, not a
  481. payload change. Plain non-negative float; tariffs can go as low as 0.0 in
  482. some markets (e.g. free hours).
  483. """
  484. energy_cost_per_kwh: float = Field(ge=0)
  485. @router.post("/electricity-price", response_model=AppSettings)
  486. async def update_electricity_price(
  487. payload: ElectricityPriceUpdate,
  488. db: AsyncSession = Depends(get_db, scope="function"),
  489. _: ScopedCaller = Depends(require_energy_cost_update()),
  490. _is_api_key: bool = Depends(caller_is_api_key),
  491. ):
  492. """Update the per-kWh electricity cost used by the energy-tracking pipeline.
  493. This is the only settings field writable via API key, gated by the
  494. ``can_update_energy_cost`` toggle on the key. JWT users still need the
  495. standard ``SETTINGS_UPDATE`` permission. See #1356 for the rationale —
  496. the general ``PATCH /settings`` route remains denied for API keys because
  497. it can rewrite SMTP/LDAP/MQTT credentials, which is a much wider surface
  498. than the documented dynamic-tariff use case requires.
  499. """
  500. await set_setting(db, "energy_cost_per_kwh", str(payload.energy_cost_per_kwh))
  501. await db.commit()
  502. db.expire_all()
  503. return await _build_settings_response(db, is_api_key=_is_api_key)
  504. @router.post("/reset", response_model=AppSettings)
  505. async def reset_settings(
  506. db: AsyncSession = Depends(get_db, scope="function"),
  507. _admin: User | None = RequireAdminIfAuthEnabled(),
  508. _: User | None = RequirePermissionIfAuthEnabled(Permission.SETTINGS_UPDATE),
  509. ):
  510. """Reset all settings to defaults."""
  511. # Delete all settings
  512. result = await db.execute(select(Settings))
  513. for setting in result.scalars().all():
  514. await db.delete(setting)
  515. await db.commit()
  516. camera_light.invalidate_settings()
  517. from backend.app.services.wled import wled_manager
  518. wled_manager.require_plate_clear = False
  519. return DEFAULT_SETTINGS
  520. @router.get("/default-sidebar-order")
  521. async def get_default_sidebar_order(
  522. db: AsyncSession = Depends(get_db, scope="function"),
  523. ):
  524. """Get the admin-set default sidebar order.
  525. Intentionally unauthenticated: non-admin users need to read this value to apply
  526. the default sidebar order, but may lack SETTINGS_READ permission.
  527. The value is non-sensitive (sidebar item IDs only).
  528. """
  529. value = await get_setting(db, "default_sidebar_order")
  530. return {"default_sidebar_order": value or ""}
  531. # Fields exposed via /ui-preferences without SETTINGS_READ. Each entry MUST be
  532. # non-sensitive (no credentials, no PII, no secret tokens) — granting SETTINGS_READ
  533. # also grants visibility of SMTP/LDAP/MQTT passwords and similar, so the goal of
  534. # this endpoint is exactly to NOT require that permission for UI rendering hints.
  535. # When adding a field here, confirm it doesn't carry anything sensitive.
  536. _UI_PREFERENCE_FIELDS: tuple[str, ...] = (
  537. "require_plate_clear",
  538. "check_printer_firmware",
  539. "camera_view_mode",
  540. "time_format",
  541. "date_format",
  542. "drying_presets",
  543. "ams_humidity_thresholds",
  544. "ams_humidity_good",
  545. "ams_humidity_fair",
  546. "ams_temp_good",
  547. "ams_temp_fair",
  548. # ams_temp_alarm is deliberately NOT here. This endpoint is unauthenticated
  549. # and exists so the UI can colour readings without SETTINGS_READ; the good /
  550. # fair bands are what the printer card colours by. The alarm threshold
  551. # changes no rendering anywhere -- only SettingsPage reads it, and that is
  552. # behind the settings permissions already (#2905).
  553. "bed_cooled_threshold",
  554. # Temperature / fan-speed presets for the printer-card popovers. Numbers
  555. # only; no PII / credentials.
  556. "nozzle_temp_presets",
  557. "bed_temp_presets",
  558. "chamber_temp_presets",
  559. "fan_speed_presets",
  560. )
  561. @router.get("/ui-preferences")
  562. async def get_ui_preferences(db: AsyncSession = Depends(get_db, scope="function")):
  563. """Get the curated subset of settings that any page needs to render correctly.
  564. Intentionally not gated on SETTINGS_READ — every authenticated user (and
  565. every page that loads for them) needs these fields, but granting SETTINGS_READ
  566. would also grant visibility of secrets (SMTP/LDAP/MQTT credentials, etc.).
  567. Same pattern as /default-sidebar-order (#1293).
  568. Reuses _build_settings_response so the typed values match what /settings
  569. returns for fields with the same name — bool/int/float/str types stay in
  570. sync without a separate type-coercion path.
  571. """
  572. full = await _build_settings_response(db, is_api_key=False)
  573. dumped = full.model_dump()
  574. return {key: dumped[key] for key in _UI_PREFERENCE_FIELDS if key in dumped}
  575. # Install configuration the app shell reads before it can render correctly.
  576. #
  577. # Deliberately a second list rather than more entries in _UI_PREFERENCE_FIELDS.
  578. # That one is served to anyone at all, on the recorded grounds that its contents
  579. # are "public defaults that ship with the app" (test_route_auth_coverage.py), and
  580. # its field set is pinned by a test written to make anyone adding to it stop and
  581. # think. These fields are not defaults -- they are facts about how this
  582. # particular deployment is configured -- so they get their own endpoint at their
  583. # own trust level instead of stretching that charter to fit them.
  584. _UI_FLAG_FIELDS: tuple[str, ...] = (
  585. # The sidebar hides Finance unless billing is on. Layout read this from
  586. # GET /settings, which requires SETTINGS_READ, so for a non-admin the query
  587. # 403'd, the value arrived undefined, `undefined !== true` held, and the
  588. # entry was hidden from exactly the users cost_centers:read_own exists to
  589. # serve. The page itself was reachable by URL the whole time (#3023).
  590. "billing_enabled",
  591. # Same 403, opposite outcome. That gate tests `=== false`, which undefined
  592. # never satisfies, so an administrator who turned user notifications off
  593. # still left the entry showing -- to precisely the non-admins it governs.
  594. "user_notifications_enabled",
  595. # Not gates, but read by the shell and equally undefined for a non-admin:
  596. # the sponsor prompt fell back to EUR whatever the install uses, and the
  597. # update check ran even where it had been switched off.
  598. "currency",
  599. "check_updates",
  600. # Read by the print dialog, queue, file manager, inventory and SpoolBuddy
  601. # pages, which users without SETTINGS_READ open too: the 403 dropped them
  602. # all to their defaults (with billing on, the print dialog hid the cost
  603. # centre picker and the print was then refused for lacking one).
  604. "queue_shortest_first",
  605. "use_slicer_api",
  606. "open_in_slicer",
  607. "preferred_slicer",
  608. "disable_filament_warnings",
  609. "prefer_lowest_filament",
  610. "per_printer_mapping_expanded",
  611. "default_filament_cost",
  612. "default_bed_levelling",
  613. "default_flow_cali",
  614. "default_vibration_cali",
  615. "default_layer_inspect",
  616. "default_timelapse",
  617. "default_nozzle_offset_cali",
  618. "default_confirm_outcome",
  619. "stagger_group_size",
  620. "stagger_interval_minutes",
  621. "library_disk_warning_gb",
  622. "low_stock_threshold",
  623. "location_sensor_poll_interval",
  624. "location_sensor_alert_defaults",
  625. "pipeline_max_copies",
  626. "language",
  627. "dark_style",
  628. "dark_background",
  629. "dark_accent",
  630. "light_style",
  631. "light_background",
  632. "light_accent",
  633. # Which inventory a new spool goes to (unknown-tag prompt), and the
  634. # forecast's default lead time.
  635. "spoolman_enabled",
  636. "forecast_global_lead_time_days",
  637. # Preselected in the print dialog; withheld below from a caller who may
  638. # not use that printer.
  639. "default_printer_id",
  640. )
  641. @router.get("/ui-flags")
  642. async def get_ui_flags(
  643. db: AsyncSession = Depends(get_db, scope="function"),
  644. _: User | None = Depends(require_auth_if_enabled),
  645. printer_scope: PrinterScope = RequestPrinterScope,
  646. ):
  647. """Install configuration the app shell needs, for any signed-in user.
  648. Gated on being authenticated rather than on ``SETTINGS_READ``. The sidebar
  649. has to know whether billing is enabled before it can decide whether to offer
  650. Finance, and ``SETTINGS_READ`` cannot be the price of knowing that -- it also
  651. grants sight of the SMTP, LDAP and MQTT credentials.
  652. ``require_auth_if_enabled`` returns ``None`` when auth is switched off
  653. entirely, which is the case /ui-preferences was left ungated for. That is the
  654. distinction the two endpoints draw: "works when there is no auth" is not the
  655. same statement as "readable by anyone", and conflating them is what put a
  656. settings read in front of a permission that was never meant to require one.
  657. """
  658. full = await _build_settings_response(db, is_api_key=False)
  659. dumped = full.model_dump()
  660. flags = {key: dumped[key] for key in _UI_FLAG_FIELDS if key in dumped}
  661. if flags.get("default_printer_id") is not None and not printer_scope.allows(flags["default_printer_id"]):
  662. flags["default_printer_id"] = None
  663. # Whether G-code snippets are set up, not the snippets themselves.
  664. flags["has_gcode_snippets"] = bool(dumped.get("gcode_snippets"))
  665. return flags
  666. @router.get("/check-ffmpeg")
  667. async def check_ffmpeg(
  668. _: User | None = RequirePermissionIfAuthEnabled(Permission.SETTINGS_READ),
  669. ):
  670. """Check if ffmpeg is installed and available.
  671. Gated on ``SETTINGS_READ`` (audit finding I4 — the binary path was
  672. leaking the host filesystem layout to unauthenticated callers).
  673. ``require_permission_if_auth_enabled`` returns ``None`` only when
  674. auth is disabled (in which case there's no privacy boundary to
  675. enforce); otherwise it raises 401/403 before we get here.
  676. """
  677. from backend.app.services.camera import get_ffmpeg_path
  678. ffmpeg_path = get_ffmpeg_path()
  679. return {
  680. "installed": ffmpeg_path is not None,
  681. "path": ffmpeg_path,
  682. }
  683. @router.get("/spoolman")
  684. async def get_spoolman_settings(
  685. db: AsyncSession = Depends(get_db, scope="function"),
  686. _: User | None = RequirePermissionIfAuthEnabled(Permission.SETTINGS_READ),
  687. ):
  688. """Get Spoolman integration settings."""
  689. spoolman_enabled = await get_setting(db, "spoolman_enabled") or "false"
  690. spoolman_url = await get_setting(db, "spoolman_url") or ""
  691. spoolman_sync_mode = await get_setting(db, "spoolman_sync_mode") or "auto"
  692. spoolman_disable_weight_sync = await get_setting(db, "spoolman_disable_weight_sync") or "false"
  693. spoolman_report_partial_usage = await get_setting(db, "spoolman_report_partial_usage") or "true"
  694. auto_add_unknown_rfid = await get_setting(db, "auto_add_unknown_rfid") or "true"
  695. return {
  696. "spoolman_enabled": spoolman_enabled,
  697. "spoolman_url": spoolman_url,
  698. "spoolman_sync_mode": spoolman_sync_mode,
  699. "spoolman_disable_weight_sync": spoolman_disable_weight_sync,
  700. "spoolman_report_partial_usage": spoolman_report_partial_usage,
  701. "auto_add_unknown_rfid": auto_add_unknown_rfid,
  702. }
  703. @router.put("/spoolman")
  704. async def update_spoolman_settings(
  705. settings: dict,
  706. db: AsyncSession = Depends(get_db, scope="function"),
  707. _: User | None = RequirePermissionIfAuthEnabled(Permission.SETTINGS_UPDATE),
  708. ):
  709. """Update Spoolman integration settings.
  710. The body is a free-form dict rather than a schema, so each value is
  711. normalised before it is persisted — see ``normalize_bool_setting`` for why
  712. a JSON boolean used to produce a 500 here.
  713. """
  714. if "spoolman_enabled" in settings:
  715. was_enabled = setting_is_true(await get_setting(db, "spoolman_enabled"))
  716. new_val = normalize_bool_setting("spoolman_enabled", settings["spoolman_enabled"])
  717. now_enabled = new_val == "true"
  718. await set_setting(db, "spoolman_enabled", new_val)
  719. # Nothing is deleted on a mode change (#2812). Each mode keeps its slot
  720. # assignments in its own table, so both can hold rows at once and the
  721. # toggle is reversible: switching to Spoolman to see what it does, then
  722. # switching back, returns you to the assignments you had.
  723. #
  724. # This used to empty the other mode's table on every toggle. The reason
  725. # was real -- checks that read both tables would let a row in the mode
  726. # you are not using answer for the mode you are -- but the cost was that
  727. # inspecting a mode destroyed your configuration, with no confirmation
  728. # and no way back, and the deletion was unfiltered across every printer.
  729. # The readers that could be confused now ask which mode is active
  730. # (``spoolman_owns_assignments``), which is where that decision belongs:
  731. # the mode is a property of the install, not of the rows.
  732. if was_enabled != now_enabled:
  733. logger.info(
  734. "Inventory mode switched to %s; slot assignments in both tables kept",
  735. "Spoolman" if now_enabled else "built-in",
  736. )
  737. if "spoolman_url" in settings:
  738. await set_setting(db, "spoolman_url", normalize_str_setting("spoolman_url", settings["spoolman_url"]))
  739. if "spoolman_sync_mode" in settings:
  740. await set_setting(
  741. db, "spoolman_sync_mode", normalize_str_setting("spoolman_sync_mode", settings["spoolman_sync_mode"])
  742. )
  743. for bool_key in ("spoolman_disable_weight_sync", "spoolman_report_partial_usage", "auto_add_unknown_rfid"):
  744. if bool_key in settings:
  745. await set_setting(db, bool_key, normalize_bool_setting(bool_key, settings[bool_key]))
  746. spoolman_changed = "spoolman_enabled" in settings or "spoolman_url" in settings
  747. await db.commit()
  748. db.expire_all()
  749. if spoolman_changed:
  750. from backend.app.services.location_service import maybe_sync_spoolman_locations
  751. if await maybe_sync_spoolman_locations(db):
  752. await db.commit()
  753. # Return updated settings
  754. return await get_spoolman_settings(db)
  755. async def get_homeassistant_settings(db: AsyncSession) -> dict:
  756. """
  757. Get Home Assistant integration settings.
  758. Environment variables (HA_URL, HA_TOKEN) take precedence over database settings.
  759. """
  760. import os
  761. # Check environment variables first
  762. ha_url_env = os.environ.get("HA_URL")
  763. ha_token_env = os.environ.get("HA_TOKEN")
  764. # Fall back to database values
  765. ha_url = ha_url_env or await get_setting(db, "ha_url") or ""
  766. ha_token = ha_token_env or await get_setting(db, "ha_token") or ""
  767. ha_enabled_db = await get_setting(db, "ha_enabled") or "false"
  768. # Track which settings come from environment
  769. ha_url_from_env = bool(ha_url_env)
  770. ha_token_from_env = bool(ha_token_env)
  771. ha_env_managed = ha_url_from_env and ha_token_from_env
  772. # Auto-enable when both env vars are set, otherwise use database value
  773. if ha_url_env and ha_token_env:
  774. ha_enabled = True
  775. else:
  776. ha_enabled = ha_enabled_db.lower() == "true"
  777. return {
  778. "ha_enabled": ha_enabled,
  779. "ha_url": ha_url,
  780. "ha_token": ha_token,
  781. "ha_url_from_env": ha_url_from_env,
  782. "ha_token_from_env": ha_token_from_env,
  783. "ha_env_managed": ha_env_managed,
  784. }
  785. # The file steps of a backup and a restore run in a worker thread. On the
  786. # event loop they froze the whole server for as long as they took -- no page,
  787. # no websocket, no printer message -- and with a large archive folder that was
  788. # over half a minute, long enough for the loop watchdog to dump every thread.
  789. def _copy_backup_dirs(dirs_to_backup: list[tuple[str, Path]], temp_path: Path) -> None:
  790. """Copy each data directory that has anything in it into the backup folder."""
  791. import shutil
  792. for name, src_dir in dirs_to_backup:
  793. if src_dir.exists() and any(src_dir.iterdir()):
  794. try:
  795. shutil.copytree(
  796. src_dir, temp_path / name
  797. ) # SEC-PATH-OK: name iterates the dirs_to_backup tuple of constant strings ("archive", "virtual_printer", ...)
  798. except shutil.Error as e:
  799. logger.warning("Some files in %s could not be copied: %s", name, e)
  800. except PermissionError as e:
  801. logger.warning("Permission denied copying %s: %s", name, e)
  802. def _write_backup_zip(temp_path: Path, zip_file: Path) -> None:
  803. """Zip every file under temp_path into zip_file, paths relative to temp_path."""
  804. with zipfile.ZipFile(zip_file, "w", zipfile.ZIP_DEFLATED) as zf:
  805. for file_path in temp_path.rglob("*"):
  806. if file_path.is_file():
  807. arcname = file_path.relative_to(temp_path)
  808. zf.write(file_path, arcname)
  809. def _extract_backup_zip(content: bytes, temp_path: Path) -> None:
  810. """Extract a backup ZIP into temp_path, refusing any entry that escapes it.
  811. Raises HTTPException(400) for an unsafe path or a file that is not a ZIP.
  812. """
  813. from fastapi import HTTPException
  814. try:
  815. with zipfile.ZipFile(io.BytesIO(content), "r") as zf:
  816. for name in zf.namelist():
  817. # Reject path-traversal payloads: any entry whose resolved
  818. # path escapes temp_path would allow writing arbitrary files
  819. # on the host (ZipSlip / CVE-2006-5456).
  820. dest = (
  821. temp_path / name
  822. ).resolve() # SEC-PATH-OK: is_relative_to containment check below before extractall
  823. # is_relative_to (Python 3.9+) covers both relative
  824. # path-traversal (../etc/passwd) and absolute-path overrides
  825. # (/etc/passwd) — str.startswith was vulnerable to
  826. # prefix-collision attacks (e.g. /tmp/abc_evil/file passing
  827. # a /tmp/abc prefix check).
  828. if not dest.is_relative_to(temp_path.resolve()):
  829. raise HTTPException(400, f"Invalid backup: unsafe path in ZIP: {name!r}")
  830. zf.extractall(temp_path)
  831. except zipfile.BadZipFile:
  832. raise HTTPException(400, "Invalid backup file: not a valid ZIP")
  833. def _restore_data_dirs(dirs_to_restore: list[tuple[str, Path]], temp_path: Path) -> list[str]:
  834. """Replace each data directory's contents with the backup's.
  835. Clears the contents, not the directory itself, which may be a Docker
  836. mount. Returns the names of the directories that could not be restored.
  837. """
  838. import shutil
  839. skipped_dirs = []
  840. for name, dest_dir in dirs_to_restore:
  841. src_dir = (
  842. temp_path / name
  843. ) # SEC-PATH-OK: name iterates the dirs_to_restore tuple of constant strings ("archive", "virtual_printer", ...)
  844. if src_dir.exists():
  845. logger.info("Restoring %s directory...", name)
  846. try:
  847. if dest_dir.exists():
  848. for item in dest_dir.iterdir():
  849. try:
  850. if item.is_dir():
  851. shutil.rmtree(item)
  852. else:
  853. item.unlink()
  854. except OSError as e:
  855. logger.warning("Could not delete %s: %s", item, e)
  856. else:
  857. dest_dir.mkdir(parents=True, exist_ok=True)
  858. # Copy contents from backup
  859. for item in src_dir.iterdir():
  860. dest_item = dest_dir / item.name
  861. if item.is_dir():
  862. shutil.copytree(item, dest_item)
  863. else:
  864. shutil.copy2(item, dest_item)
  865. except OSError as e:
  866. logger.warning("Could not restore %s directory: %s", name, e)
  867. skipped_dirs.append(name)
  868. return skipped_dirs
  869. def _restore_sqlite_db(backup_db: Path, db_path: Path) -> None:
  870. """Copy the backup into the live SQLite database with the online backup API."""
  871. import sqlite3
  872. src_conn = sqlite3.connect(str(backup_db))
  873. try:
  874. dst_conn = sqlite3.connect(str(db_path))
  875. try:
  876. src_conn.backup(dst_conn)
  877. finally:
  878. dst_conn.close()
  879. finally:
  880. src_conn.close()
  881. async def create_backup_zip(output_path: Path | None = None) -> tuple[Path, str]:
  882. """Create a complete backup ZIP (database + all data directories).
  883. If output_path is given, the ZIP is written there.
  884. Otherwise a temporary file is created (caller must clean up).
  885. Returns (zip_path, filename).
  886. """
  887. import shutil
  888. import tempfile
  889. from backend.app.core.db_dialect import is_sqlite
  890. base_dir = app_settings.base_dir
  891. filename = f"bambuddy-backup-{datetime.now().strftime('%Y%m%d-%H%M%S')}.zip"
  892. with tempfile.TemporaryDirectory() as temp_dir:
  893. temp_path = Path(temp_dir)
  894. if is_sqlite():
  895. from sqlalchemy import text
  896. from backend.app.core.database import engine
  897. db_path = Path(app_settings.database_url.replace("sqlite+aiosqlite:///", ""))
  898. # Checkpoint WAL to ensure all data is in main db file
  899. async with engine.begin() as conn:
  900. await conn.execute(text("PRAGMA wal_checkpoint(TRUNCATE)"))
  901. # Copy database file. Off the event loop, like every file step
  902. # below: a large file blocked the whole server while it copied.
  903. await asyncio.to_thread(shutil.copy2, db_path, temp_path / "bambuddy.db")
  904. else:
  905. # PostgreSQL: export to a portable SQLite file via SQLAlchemy.
  906. # This makes backups restorable on both SQLite and Postgres installs.
  907. import json
  908. import sqlite3
  909. from sqlalchemy import create_engine as create_sync_engine
  910. from backend.app.core.database import Base, engine
  911. backup_db_path = temp_path / "bambuddy.db"
  912. metadata = Base.metadata
  913. # Build the portable SQLite schema with SQLAlchemy's own DDL rather
  914. # than a hand-rolled CREATE TABLE. metadata.create_all() emits the
  915. # exact schema a native SQLite install gets — NOT NULL, DEFAULT
  916. # (server_default=func.now() → CURRENT_TIMESTAMP), foreign keys,
  917. # unique constraints and indexes. The previous name+type-only
  918. # rebuild dropped all of these, so a Postgres→SQLite restore left
  919. # server_default columns (e.g. spoolbuddy_devices.created_at) with
  920. # no DEFAULT — SQLAlchemy omits such columns on INSERT and the DB
  921. # then wrote NULL, which 500'd on the next read (#2526). Using the
  922. # real DDL also keeps the #1333 BLOB guard: LargeBinary still
  923. # renders as BLOB, so OIDC icon bytes survive the round trip.
  924. schema_engine = create_sync_engine(f"sqlite:///{backup_db_path}")
  925. try:
  926. metadata.create_all(schema_engine)
  927. finally:
  928. schema_engine.dispose()
  929. dst = sqlite3.connect(str(backup_db_path))
  930. # Export data from Postgres to SQLite
  931. async with engine.connect() as conn:
  932. for table in metadata.sorted_tables:
  933. result = await conn.execute(table.select())
  934. rows = result.fetchall()
  935. if not rows:
  936. continue
  937. columns = list(result.keys())
  938. placeholders = ", ".join(["?"] * len(columns))
  939. col_list = ", ".join(columns)
  940. insert_sql = f"INSERT INTO {table.name} ({col_list}) VALUES ({placeholders})" # noqa: S608 # nosec B608 — table/column names from ORM metadata, not user input
  941. def _serialize_row(row):
  942. return tuple(json.dumps(v) if isinstance(v, (list, dict)) else v for v in row)
  943. dst.executemany(insert_sql, [_serialize_row(row) for row in rows])
  944. dst.commit()
  945. dst.close()
  946. logger.info("PostgreSQL backup exported to portable SQLite format")
  947. # Copy data directories (if they exist)
  948. dirs_to_backup = [
  949. ("archive", base_dir / "archive"),
  950. ("virtual_printer", base_dir / "virtual_printer"),
  951. ("plate_calibration", app_settings.plate_calibration_dir),
  952. ("icons", base_dir / "icons"),
  953. ("projects", base_dir / "projects"),
  954. ("overlay-branding", base_dir / "overlay-branding"),
  955. ]
  956. await asyncio.to_thread(_copy_backup_dirs, dirs_to_backup, temp_path)
  957. # Say which version made this, so a restore that cannot import it can
  958. # name the versions rather than a list of columns. Backups from before
  959. # this existed simply have no manifest, and restore treats the version
  960. # as unknown.
  961. import json as _json
  962. manifest = {
  963. "format": 1,
  964. "app_version": APP_VERSION,
  965. "created_at": datetime.now().isoformat(timespec="seconds"),
  966. "database": "sqlite" if is_sqlite() else "postgresql",
  967. }
  968. (temp_path / "manifest.json").write_text(_json.dumps(manifest, indent=2) + "\n")
  969. # Include the MFA encryption key as a ZIP top-level entry alongside
  970. # bambuddy.db. Without it, encrypted client_secret / TOTP secret rows
  971. # would be unrecoverable after restore on a host without MFA_ENCRYPTION_KEY set.
  972. from backend.app.core.paths import resolve_data_dir
  973. mfa_key_src = resolve_data_dir() / ".mfa_encryption_key"
  974. if mfa_key_src.exists() and mfa_key_src.is_file():
  975. try:
  976. shutil.copy2(mfa_key_src, temp_path / ".mfa_encryption_key")
  977. except OSError as exc:
  978. logger.error(
  979. "Could not include MFA encryption key in backup (%s). "
  980. "The backup ZIP will not contain the key — restore on a "
  981. "keyless host will fail for encrypted secrets.",
  982. exc,
  983. )
  984. raise
  985. # Create ZIP
  986. if output_path is not None:
  987. zip_file = (
  988. output_path / filename
  989. ) # SEC-PATH-OK: filename = f"bambuddy-backup-{datetime.now()...}.zip" generated in create_backup_zip itself
  990. else:
  991. fd, tmp = tempfile.mkstemp(suffix=".zip")
  992. os.close(fd)
  993. zip_file = Path(tmp)
  994. await asyncio.to_thread(_write_backup_zip, temp_path, zip_file)
  995. return zip_file, filename
  996. @router.get("/backup")
  997. async def create_backup(
  998. db: AsyncSession = Depends(get_db, scope="function"),
  999. _admin: User | None = RequireAdminIfAuthEnabled(),
  1000. _: User | None = RequirePermissionIfAuthEnabled(Permission.SETTINGS_BACKUP),
  1001. ):
  1002. """Create a complete backup (database + all files) as a ZIP download."""
  1003. from starlette.background import BackgroundTask
  1004. try:
  1005. zip_file, filename = await create_backup_zip()
  1006. return FileResponse(
  1007. path=zip_file,
  1008. filename=filename,
  1009. media_type="application/zip",
  1010. background=BackgroundTask(lambda: zip_file.unlink(missing_ok=True)),
  1011. )
  1012. except Exception as e:
  1013. logger.error("Backup failed: %s", e, exc_info=True)
  1014. return JSONResponse(
  1015. status_code=500,
  1016. content={"success": False, "message": "Backup failed. Check server logs for details."},
  1017. )
  1018. class BackupSchemaIncompatible(Exception):
  1019. """The backup has no value for a column this version requires.
  1020. A backup carries the schema of the install that made it. Restoring it into
  1021. a different version means the destination can have NOT NULL columns the
  1022. backup never heard of -- either because that version is older and still has
  1023. a column since removed (``user_wallets.currency``, dropped in #3123), or
  1024. because it is newer and has added one. Most such columns have a default and
  1025. can simply be filled. The ones that cannot are what this reports, and it has
  1026. to be reported BEFORE the restore drops anything: the Postgres import wipes
  1027. every table in the first transaction, so a failure halfway leaves the
  1028. install with an empty schema and the previous data gone.
  1029. """
  1030. def _missing_required_columns(pg_table, src_columns: set[str]):
  1031. """Split the destination's NOT NULL columns that the backup lacks.
  1032. Returns ``(injectable, db_filled, unfillable)``:
  1033. * ``injectable`` -- ``{name: value}`` from the model's Python-side default.
  1034. These are invisible to the import's raw SQL: SQLAlchemy applies a
  1035. ``default=`` on ORM and Core inserts, never on ``text()``, and
  1036. ``create_all`` emits no DDL default for one. So a column like
  1037. ``currency VARCHAR(3) NOT NULL`` with ``default="EUR"`` arrives with
  1038. nothing to put in it unless we put it there.
  1039. * ``db_filled`` -- has a server default or is the autoincrement key; the
  1040. database fills it when the column is left out of the INSERT.
  1041. * ``unfillable`` -- nothing can supply a value. The backup is incompatible.
  1042. """
  1043. injectable: dict = {}
  1044. db_filled: list[str] = []
  1045. unfillable: list[str] = []
  1046. for col in pg_table.columns:
  1047. if col.nullable or col.name in src_columns:
  1048. continue
  1049. if col.default is not None:
  1050. arg = col.default.arg
  1051. injectable[col.name] = arg(None) if callable(arg) else arg
  1052. elif col.server_default is not None or col.primary_key:
  1053. db_filled.append(col.name)
  1054. else:
  1055. unfillable.append(col.name)
  1056. return injectable, db_filled, unfillable
  1057. def check_backup_schema_compatible(sqlite_path: Path, backup_version: str | None = None) -> None:
  1058. """Raise if this version cannot import that backup. Touches nothing.
  1059. Only the cross-engine path needs this. A SQLite install restores by copying
  1060. the backup's pages, schema included, and `init_db()` migrates it forward
  1061. afterwards; the Postgres import instead recreates the schema from THIS
  1062. process's ORM and then inserts the backup's columns into it.
  1063. """
  1064. import sqlite3
  1065. from backend.app.core.database import Base
  1066. src = sqlite3.connect(f"file:{sqlite_path}?mode=ro", uri=True)
  1067. try:
  1068. src_tables = {
  1069. row[0]
  1070. for row in src.execute(
  1071. "SELECT name FROM sqlite_master WHERE type='table' "
  1072. "AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'archive_fts%'"
  1073. )
  1074. }
  1075. problems: list[str] = []
  1076. # metadata.tables, not sorted_tables: the latter warns about the
  1077. # library_files/library_folders/print_archives cycle, and nothing here
  1078. # depends on the order.
  1079. for name, pg_table in Base.metadata.tables.items():
  1080. if name not in src_tables:
  1081. continue
  1082. # An empty table inserts nothing, so a column it cannot supply
  1083. # cannot fail. Refusing a restore over one would be a false alarm.
  1084. if src.execute(f'SELECT 1 FROM "{name}" LIMIT 1').fetchone() is None: # noqa: S608 # nosec B608 — name comes from ORM metadata
  1085. continue
  1086. src_columns = {row[1] for row in src.execute(f'PRAGMA table_info("{name}")')}
  1087. _, _, unfillable = _missing_required_columns(pg_table, src_columns)
  1088. problems.extend(f"{name}.{col}" for col in unfillable)
  1089. finally:
  1090. src.close()
  1091. if not problems:
  1092. return
  1093. made_by = f"The backup was made by Bambuddy {backup_version}, " if backup_version else "The backup "
  1094. raise BackupSchemaIncompatible(
  1095. "This backup cannot be restored by this version of Bambuddy. It carries no value for "
  1096. f"{len(problems)} column(s) this version requires and cannot default: {', '.join(sorted(problems))}. "
  1097. f"{made_by}and this install runs {APP_VERSION}. Restore it on the version that made it, or "
  1098. "upgrade this install to that version. Nothing has been changed."
  1099. )
  1100. def _read_backup_manifest(temp_path: Path) -> dict:
  1101. """The backup's manifest.json, or {} for a backup made before it existed."""
  1102. import json
  1103. path = temp_path / "manifest.json"
  1104. if not path.is_file():
  1105. return {}
  1106. try:
  1107. data = json.loads(path.read_text())
  1108. except (OSError, ValueError) as exc:
  1109. logger.warning("Ignoring unreadable backup manifest: %s", exc)
  1110. return {}
  1111. return data if isinstance(data, dict) else {}
  1112. def _restored_value_fixes(table_name: str) -> dict[str, tuple[tuple[str, ...], str]]:
  1113. """Columns of ``table_name`` whose backed-up value must be one of a set, with its fallback.
  1114. Older versions stored any project priority or status; one longer than the
  1115. column fails the whole import on PostgreSQL. The fallbacks are the ones
  1116. project import and the start-up repair use.
  1117. """
  1118. if table_name != "projects":
  1119. return {}
  1120. from backend.app.models.project import PROJECT_PRIORITIES, PROJECT_STATUSES
  1121. return {"priority": (PROJECT_PRIORITIES, "normal"), "status": (PROJECT_STATUSES, "active")}
  1122. async def _import_sqlite_to_postgres(sqlite_path: Path):
  1123. """Import data from a SQLite database file into the current PostgreSQL database.
  1124. Used for cross-database restore (SQLite backup → PostgreSQL).
  1125. Reads all tables from the SQLite file and bulk-inserts into Postgres.
  1126. """
  1127. import sqlite3
  1128. from sqlalchemy import text
  1129. from backend.app.core.database import AUTOINCREMENT_TABLES, Base, _create_engine, highest_referenced_id
  1130. # Before anything is dropped. The route checks this too, earlier and with
  1131. # the backup's version in the message; this call is what makes the guarantee
  1132. # a property of the import itself rather than of one caller.
  1133. check_backup_schema_compatible(sqlite_path)
  1134. # Create a temporary engine for the import (current engine was disposed)
  1135. pg_engine = _create_engine()
  1136. try:
  1137. # Open SQLite file directly (sync — it's a local file read)
  1138. src = sqlite3.connect(str(sqlite_path))
  1139. src.row_factory = sqlite3.Row
  1140. # Get list of tables from SQLite (skip internal/FTS tables)
  1141. cursor = src.execute(
  1142. "SELECT name FROM sqlite_master WHERE type='table' "
  1143. "AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'archive_fts%'"
  1144. )
  1145. src_tables = {row["name"] for row in cursor.fetchall()}
  1146. # Where SQLite's own counters stand: ids freed there are not given out
  1147. # again on PostgreSQL either (a backup from before they were kept has none).
  1148. src_counters: dict[str, int] = {}
  1149. if src.execute("SELECT 1 FROM sqlite_master WHERE name = 'sqlite_sequence'").fetchone():
  1150. src_counters = {row["name"]: row["seq"] for row in src.execute("SELECT name, seq FROM sqlite_sequence")}
  1151. # Get Postgres tables from our ORM models
  1152. metadata = Base.metadata
  1153. pg_tables = set(metadata.tables.keys())
  1154. # Only import tables that exist in both source and destination
  1155. tables_to_import = src_tables & pg_tables
  1156. sorted_tables = [t.name for t in metadata.sorted_tables if t.name in tables_to_import]
  1157. # Phase 1: Drop all tables and recreate WITHOUT foreign keys.
  1158. # This avoids all FK ordering/orphan issues during import; the
  1159. # constraints go back on at the end, once every row has landed.
  1160. async with pg_engine.begin() as conn:
  1161. # Cap how long DROP TABLE will wait for AccessExclusiveLock so
  1162. # any residual concurrent writer (per-printer MQTT clients
  1163. # writing reactively, an AMS history recorder firing on its
  1164. # hourly cadence) surfaces a fast `lock_timeout` error instead
  1165. # of blocking the restore for 30 s or producing a deadlock.
  1166. # SET LOCAL scopes to this transaction only; outside this
  1167. # restore path the global default (no timeout) applies.
  1168. await conn.execute(text("SET LOCAL lock_timeout = '10s'"))
  1169. # Drop every existing table in the public schema with CASCADE
  1170. # rather than `metadata.drop_all`. Two reasons:
  1171. # 1. The user's live DB may carry orphan tables from removed
  1172. # features (e.g. the legacy `spoolman_slot_assignments`,
  1173. # `spoolman_k_profile`) that hold FK constraints back to
  1174. # ORM tables. `drop_all` doesn't know they exist and emits
  1175. # `DROP TABLE printers` without CASCADE — Postgres refuses
  1176. # and the whole restore aborts (#XXXX).
  1177. # 2. Even within the metadata, `drop_all` is FK-ordered and
  1178. # breaks if a future schema rename leaves old constraints
  1179. # around. CASCADE is the right tool for a destructive
  1180. # restore: the user is intentionally wiping state.
  1181. await conn.execute(
  1182. text(
  1183. "DO $$ DECLARE r RECORD; BEGIN "
  1184. "FOR r IN (SELECT tablename FROM pg_tables WHERE schemaname = 'public') LOOP "
  1185. "EXECUTE 'DROP TABLE IF EXISTS public.' || quote_ident(r.tablename) || ' CASCADE'; "
  1186. "END LOOP; END $$;"
  1187. )
  1188. )
  1189. await conn.run_sync(metadata.create_all)
  1190. # Now strip the foreign keys, at the database level.
  1191. #
  1192. # This used to be done by discarding each ForeignKeyConstraint
  1193. # from `table.constraints` before `create_all`. That only
  1194. # suppresses the inline REFERENCES clause inside CREATE TABLE:
  1195. # `Table.foreign_key_constraints` is derived from the *columns'*
  1196. # ForeignKey objects, which the discard never touched. When
  1197. # `create_all` meets a dependency cycle it can't sort -- and
  1198. # library_files / library_folders / print_archives are exactly
  1199. # such a cycle -- it falls back to emitting those tables' keys
  1200. # as separate ALTER TABLE ... ADD FOREIGN KEY statements read
  1201. # straight from that property. Twelve constraints survived,
  1202. # including library_files.folder_id, and because the same cycle
  1203. # also drops the ordering edge from `sorted_tables` the child
  1204. # table was imported before its parent and the restore died on
  1205. # a ForeignKeyViolationError.
  1206. #
  1207. # Dropping them from pg_constraint instead is indifferent to how
  1208. # create_all chose to emit them, so a future model cycle cannot
  1209. # reintroduce this. It also keeps the app's global Base.metadata
  1210. # untouched: the old code only put the constraints back *after*
  1211. # the transaction, so a failure in here left the running process
  1212. # with an FK-less metadata until restart.
  1213. await conn.execute(
  1214. text(
  1215. "DO $$ DECLARE r RECORD; BEGIN "
  1216. "FOR r IN (SELECT conrelid::regclass AS tbl, conname FROM pg_constraint "
  1217. "WHERE contype = 'f' AND connamespace = 'public'::regnamespace) LOOP "
  1218. "EXECUTE 'ALTER TABLE ' || r.tbl || ' DROP CONSTRAINT ' || quote_ident(r.conname); "
  1219. "END LOOP; END $$;"
  1220. )
  1221. )
  1222. # Phase 2: Import data (no FKs to worry about)
  1223. async with pg_engine.begin() as conn:
  1224. # Import each table in dependency order (parents before children)
  1225. for table_name in sorted_tables:
  1226. rows = src.execute(f"SELECT * FROM {table_name}").fetchall() # noqa: S608 # nosec B608
  1227. if not rows:
  1228. continue
  1229. # Filter to columns that exist in the Postgres table
  1230. src_columns = rows[0].keys()
  1231. pg_table = metadata.tables.get(table_name)
  1232. pg_columns = {c.name for c in pg_table.columns} if pg_table is not None else set()
  1233. columns = [c for c in src_columns if c in pg_columns]
  1234. if not columns:
  1235. continue
  1236. # Columns this schema requires that the backup does not have at
  1237. # all. The block below handles a column PRESENT in the backup
  1238. # with a NULL in it; one the backup never had is not in
  1239. # `columns` and so never reached it -- which is how a backup
  1240. # from an install without `user_wallets.currency` died on
  1241. # NotNullViolationError against a version that still had it.
  1242. injected, _db_filled, _unfillable = _missing_required_columns(pg_table, set(src_columns))
  1243. if injected:
  1244. logger.info(
  1245. "Filling %s column(s) absent from the backup in %s: %s",
  1246. len(injected),
  1247. table_name,
  1248. ", ".join(sorted(injected)),
  1249. )
  1250. insert_columns = columns + list(injected)
  1251. col_list = ", ".join(insert_columns)
  1252. param_list = ", ".join(f":{c}" for c in insert_columns)
  1253. # ON CONFLICT DO NOTHING handles duplicate rows from SQLite (which doesn't enforce unique constraints)
  1254. insert_sql = text(f"INSERT INTO {table_name} ({col_list}) VALUES ({param_list}) ON CONFLICT DO NOTHING") # noqa: S608 # nosec B608
  1255. # Identify columns that need type conversion (SQLite stores booleans
  1256. # as int and datetimes as str — asyncpg requires native Python types)
  1257. from datetime import datetime as dt, timezone
  1258. bool_columns = set()
  1259. datetime_columns = set()
  1260. not_null_defaults = {} # col_name -> default value for NOT NULL columns
  1261. if pg_table is not None:
  1262. for col in pg_table.columns:
  1263. if col.name not in columns:
  1264. continue
  1265. col_type = str(col.type)
  1266. if col_type == "BOOLEAN":
  1267. bool_columns.add(col.name)
  1268. elif col_type in ("DATETIME", "TIMESTAMP WITHOUT TIME ZONE", "TIMESTAMP WITH TIME ZONE"):
  1269. datetime_columns.add(col.name)
  1270. # Track NOT NULL columns with defaults — older backups may have NULL
  1271. # for columns added after the backup was created
  1272. if not col.nullable:
  1273. if col.default is not None:
  1274. default = col.default.arg
  1275. if callable(default):
  1276. default = default(None)
  1277. not_null_defaults[col.name] = default
  1278. elif col.server_default is not None:
  1279. # server_default=func.now() → use current timestamp
  1280. if col.name in datetime_columns:
  1281. not_null_defaults[col.name] = "__now__"
  1282. else:
  1283. # Try to extract literal server default
  1284. sd = str(col.server_default.arg) if hasattr(col.server_default, "arg") else None
  1285. if sd is not None:
  1286. not_null_defaults[col.name] = sd
  1287. # Naive UTC, as every stored timestamp is: the host's local
  1288. # time put backfilled rows hours off (DB-C4).
  1289. now = dt.now(timezone.utc).replace(tzinfo=None)
  1290. value_fixes = _restored_value_fixes(table_name)
  1291. def _convert_row(
  1292. row,
  1293. cols=columns,
  1294. bools=bool_columns,
  1295. dts=datetime_columns,
  1296. nn_defaults=not_null_defaults,
  1297. _now=now,
  1298. inject=injected,
  1299. fixes=value_fixes,
  1300. ):
  1301. result = dict(inject)
  1302. for c in cols:
  1303. val = row[c]
  1304. if val is None and c in nn_defaults:
  1305. val = _now if nn_defaults[c] == "__now__" else nn_defaults[c]
  1306. if val is not None:
  1307. if c in bools:
  1308. val = bool(val)
  1309. elif c in dts and isinstance(val, str):
  1310. try:
  1311. val = dt.fromisoformat(val)
  1312. except ValueError:
  1313. pass
  1314. result[c] = val
  1315. for c, (allowed, fallback) in fixes.items():
  1316. if c in result and result[c] not in allowed:
  1317. result[c] = fallback
  1318. return result
  1319. batch = [_convert_row(row) for row in rows]
  1320. await conn.execute(insert_sql, batch)
  1321. logger.info("Imported %d rows into %s", len(batch), table_name)
  1322. # Reset sequences to max(id) + 1 for each table with an id column;
  1323. # for AUTOINCREMENT_TABLES past SQLite's counter and every id still
  1324. # referred to, so a deleted row's id is not given to a new one.
  1325. for table_name in sorted_tables:
  1326. try:
  1327. async with conn.begin_nested():
  1328. result = await conn.execute(text(f"SELECT MAX(id) FROM {table_name}")) # noqa: S608 # nosec B608
  1329. max_id = result.scalar()
  1330. if table_name in AUTOINCREMENT_TABLES:
  1331. max_id = max(
  1332. max_id or 0,
  1333. src_counters.get(table_name) or 0,
  1334. await highest_referenced_id(conn, table_name),
  1335. )
  1336. if max_id:
  1337. seq_name = f"{table_name}_id_seq"
  1338. await conn.execute(text(f"SELECT setval('{seq_name}', {max_id})")) # noqa: S608
  1339. except Exception:
  1340. pass # Table may not have an id column or sequence
  1341. src.close()
  1342. logger.info("Cross-database import complete: %d tables imported", len(tables_to_import))
  1343. # Recreate FK constraints from ORM metadata, which Phase 1 left intact.
  1344. # Use individual transactions so orphaned SQLite data doesn't block valid FKs.
  1345. from sqlalchemy.schema import AddConstraint
  1346. failed_fks = []
  1347. for table in metadata.sorted_tables:
  1348. for fk in table.foreign_key_constraints:
  1349. try:
  1350. async with pg_engine.begin() as fk_conn:
  1351. await fk_conn.execute(AddConstraint(fk))
  1352. except Exception as e:
  1353. # Name the constraint by what it links, not by `fk.name`:
  1354. # these are unnamed in the ORM, so that field is None and
  1355. # the warning used to read "print_archives.None" for every
  1356. # one of the five keys on that table -- unusable for
  1357. # working out which rows to go and look at.
  1358. cols = ", ".join(c.name for c in fk.columns)
  1359. target = fk.elements[0].target_fullname if fk.elements else "unknown"
  1360. failed_fks.append(f"{table.name}({cols}) -> {target}")
  1361. # Postgres puts the offending key in a DETAIL line; it
  1362. # names the exact orphan value, which is the one thing
  1363. # that turns this into an actionable report.
  1364. detail = next(
  1365. (ln.strip() for ln in str(e).splitlines() if ln.startswith("DETAIL:")),
  1366. str(e).splitlines()[0] if str(e) else e.__class__.__name__,
  1367. )
  1368. logger.info("FK %s(%s) -> %s not restored: %s", table.name, cols, target, detail)
  1369. if failed_fks:
  1370. logger.warning(
  1371. "Could not restore %d FK constraints (orphaned data in the backup): %s. "
  1372. "The data is restored and usable; those columns are simply no longer "
  1373. "enforced. See the INFO lines above for the offending key in each case.",
  1374. len(failed_fks),
  1375. ", ".join(failed_fks),
  1376. )
  1377. finally:
  1378. await pg_engine.dispose()
  1379. @router.post("/restore")
  1380. async def restore_backup(
  1381. file: UploadFile = File(...),
  1382. db: AsyncSession = Depends(get_db, scope="function"),
  1383. _admin: User | None = RequireAdminIfAuthEnabled(),
  1384. _: User | None = RequirePermissionIfAuthEnabled(Permission.SETTINGS_RESTORE),
  1385. ):
  1386. """Restore from a complete backup ZIP.
  1387. Replaces the database and all data directories from the backup ZIP.
  1388. Requires a restart after restore.
  1389. """
  1390. import tempfile
  1391. from fastapi import HTTPException
  1392. from backend.app.core.database import close_all_connections, init_db, reinitialize_database
  1393. from backend.app.core.db_dialect import is_sqlite
  1394. from backend.app.services.virtual_printer import virtual_printer_manager
  1395. base_dir = app_settings.base_dir
  1396. with tempfile.TemporaryDirectory() as temp_dir:
  1397. temp_path = Path(temp_dir)
  1398. # 1. Read and extract ZIP
  1399. content = await file.read()
  1400. # Check if it's a valid ZIP
  1401. if not file.filename or not file.filename.endswith(".zip"):
  1402. raise HTTPException(400, "Invalid backup file: must be a .zip file")
  1403. await asyncio.to_thread(_extract_backup_zip, content, temp_path)
  1404. # 2. Validate backup
  1405. backup_db = temp_path / "bambuddy.db"
  1406. if not backup_db.exists():
  1407. raise HTTPException(400, "Invalid backup: missing bambuddy.db")
  1408. # 2b. Can this version import this backup at all?
  1409. #
  1410. # Deliberately here: everything below has a side effect. The virtual
  1411. # printer stops, background services stop, the MFA key file is
  1412. # overwritten with the backup's -- and then the Postgres import drops
  1413. # every table in its first transaction. A backup rejected at the INSERT
  1414. # took the install's data with it and left the encrypted secrets under a
  1415. # key that no longer matches. Nothing above this line has touched
  1416. # anything.
  1417. import sqlite3
  1418. manifest = _read_backup_manifest(temp_path)
  1419. backup_version = manifest.get("app_version")
  1420. if backup_version:
  1421. logger.info("Backup was created by Bambuddy %s; this install runs %s", backup_version, APP_VERSION)
  1422. if not is_sqlite():
  1423. try:
  1424. check_backup_schema_compatible(backup_db, backup_version)
  1425. except BackupSchemaIncompatible as exc:
  1426. logger.error("Refusing backup: %s", exc)
  1427. raise HTTPException(400, str(exc)) from exc
  1428. except sqlite3.DatabaseError as exc:
  1429. raise HTTPException(400, f"Invalid backup: bambuddy.db is not readable ({exc})") from exc
  1430. try:
  1431. # 3. Stop the virtual printers if running (releases file locks).
  1432. # stop_all, not the legacy configure(): that ignores its arguments
  1433. # and re-syncs from the database not yet replaced, so their FTP,
  1434. # MQTT and SSDP services ran on through the restore (vp-2). Like
  1435. # the services below, they come back with the restart a
  1436. # successful restore asks for.
  1437. try:
  1438. if virtual_printer_manager.is_enabled:
  1439. logger.info("Stopping virtual printers for restore...")
  1440. await virtual_printer_manager.stop_all()
  1441. await asyncio.sleep(1)
  1442. except Exception as e:
  1443. logger.warning("Failed to stop virtual printer: %s", e)
  1444. # 3b. Pause timer-based background services BEFORE the DB swap.
  1445. # close_all_connections() below only disposes the engine's pool,
  1446. # not the asyncio tasks that opened sessions from it. The print
  1447. # scheduler (30 s cadence), smart-plug snapshot loop (30 s), and
  1448. # notification digest loop all
  1449. # wake up and call async_session(), which lazily re-creates a
  1450. # pool connection holding RowExclusiveLock on print_queue /
  1451. # smart_plug_energy_snapshots / etc. The DROP TABLE CASCADE
  1452. # pass in the PostgreSQL restore path needs AccessExclusiveLock
  1453. # on every public table, producing an AB/BA deadlock and a
  1454. # full restore rollback. Successful restore already requires a
  1455. # container restart, so we don't restart the services here.
  1456. try:
  1457. from backend.app.services.notification_service import notification_service
  1458. from backend.app.services.print_scheduler import scheduler as print_scheduler
  1459. from backend.app.services.smart_plug_manager import smart_plug_manager
  1460. logger.info("Pausing background services for restore...")
  1461. print_scheduler.stop()
  1462. smart_plug_manager.stop_scheduler()
  1463. notification_service.stop_digest_scheduler()
  1464. # In-flight loop iterations need a moment to commit + release
  1465. # their DB sessions before we dispose() the engine pool.
  1466. await asyncio.sleep(1.0)
  1467. except Exception as e:
  1468. logger.warning("Could not cleanly pause background services: %s", e)
  1469. # 4. Close current database connections
  1470. logger.info("Closing database connections...")
  1471. await close_all_connections()
  1472. # B1: Restore the MFA encryption key file BEFORE the database swap.
  1473. # If the key write fails (OSError, RO disk, full disk, EACCES) we
  1474. # can still abort while the live DB is intact. Doing this AFTER the
  1475. # DB swap would leave the database with rows encrypted under the
  1476. # backup's key but the running install holding only the old key —
  1477. # every encrypted secret becomes unrecoverable.
  1478. from backend.app.core.paths import resolve_data_dir
  1479. mfa_key_src = temp_path / ".mfa_encryption_key"
  1480. if mfa_key_src.exists() and mfa_key_src.is_file():
  1481. dst_key = resolve_data_dir() / ".mfa_encryption_key"
  1482. tmp_key = dst_key.parent / ".mfa_encryption_key.restore-tmp"
  1483. try:
  1484. dst_key.parent.mkdir(parents=True, exist_ok=True)
  1485. # S1: atomic write with restrictive mode from creation.
  1486. # O_TRUNC because a stale tmp may exist from a prior
  1487. # failed restore attempt — we want to overwrite it.
  1488. fd = os.open(str(tmp_key), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
  1489. try:
  1490. os.write(fd, mfa_key_src.read_bytes())
  1491. finally:
  1492. os.close(fd)
  1493. # POSIX rename(2) — atomic when source/dest are on the
  1494. # same filesystem (we're staying inside dst_key.parent).
  1495. os.replace(str(tmp_key), str(dst_key))
  1496. # S9: warn if the FS doesn't enforce 0o600
  1497. actual_mode = dst_key.stat().st_mode & 0o777
  1498. if actual_mode != 0o600:
  1499. logger.warning(
  1500. "Restored MFA key file %s: filesystem did not enforce 0o600 "
  1501. "(actual: 0o%o). Key may be world-readable on Windows / SMB / FUSE.",
  1502. dst_key,
  1503. actual_mode,
  1504. )
  1505. logger.info("Restored .mfa_encryption_key from backup")
  1506. except OSError as e:
  1507. logger.error(
  1508. "Could not write restored MFA key file to %s: %s — "
  1509. "aborting BEFORE database swap (DB unchanged).",
  1510. dst_key,
  1511. e,
  1512. exc_info=True,
  1513. )
  1514. raise HTTPException(
  1515. status_code=500,
  1516. detail=("Restore aborted: MFA key write failed. Database is unchanged. Check server logs."),
  1517. ) from e
  1518. # 5. Replace database
  1519. logger.info("Restoring database from backup...")
  1520. if is_sqlite():
  1521. db_path = Path(app_settings.database_url.replace("sqlite+aiosqlite:///", ""))
  1522. # Use SQLite's online backup API instead of shutil.copy2.
  1523. # The pragma at database.py:19 runs the live DB in WAL mode,
  1524. # which means a naive file copy is unsafe: anything written
  1525. # to the live DB before this call that hasn't been
  1526. # checkpointed yet (seed_default_groups + init_db on first
  1527. # start, plus whatever background heartbeats wrote during
  1528. # the request window) sits in bambuddy.db-wal with valid
  1529. # checksums. The route handler's own `db: Depends(get_db, scope="function")`
  1530. # session also keeps a connection checked out across
  1531. # engine.dispose(), holding fds to the WAL inode. With
  1532. # `shutil.copy2` SQLite finds the stale WAL on the next
  1533. # open and silently re-applies those page-level writes on
  1534. # top of the restored DB, partially clobbering it with
  1535. # fresh-install state — the user sees a "successful"
  1536. # restore where most rows and settings have reverted to
  1537. # defaults (#1211 / #668). The page-by-page backup API
  1538. # opens both DBs as real SQLite connections, takes the
  1539. # right locks, and routes new pages through the live DB's
  1540. # own WAL — so concurrent open sessions see their own
  1541. # snapshot until they close (transaction isolation) but
  1542. # can't corrupt the restored state.
  1543. await asyncio.to_thread(_restore_sqlite_db, backup_db, db_path)
  1544. else:
  1545. # Import SQLite backup into PostgreSQL
  1546. logger.info("Importing SQLite backup into PostgreSQL...")
  1547. await _import_sqlite_to_postgres(backup_db)
  1548. # 6. Replace data directories
  1549. # For Docker compatibility: clear contents then copy (don't delete mount points)
  1550. dirs_to_restore = [
  1551. ("archive", base_dir / "archive"),
  1552. ("virtual_printer", base_dir / "virtual_printer"),
  1553. ("plate_calibration", app_settings.plate_calibration_dir),
  1554. ("icons", base_dir / "icons"),
  1555. ("projects", base_dir / "projects"),
  1556. ("overlay-branding", base_dir / "overlay-branding"),
  1557. ]
  1558. skipped_dirs = await asyncio.to_thread(_restore_data_dirs, dirs_to_restore, temp_path)
  1559. # 7. Reset the encryption singleton so the migration that runs
  1560. # inside init_db() picks up the restored key file (if a new one
  1561. # was written above). Without this reset, _get_fernet would
  1562. # return the cached Fernet instance built from the previous key.
  1563. import backend.app.core.encryption as _enc_mod
  1564. _enc_mod._fernet_instance = None
  1565. _enc_mod._key_source = None
  1566. _enc_mod._warn_shown = False
  1567. # 8. Reinitialize the database engine and apply schema migrations so that
  1568. # tables added after the backup was created (e.g. ams_labels) exist
  1569. # immediately, without requiring a manual restart.
  1570. await reinitialize_database()
  1571. await init_db()
  1572. # 8b. A backup from a Windows install stores its paths with
  1573. # backslashes, which Linux and macOS read as part of a file name
  1574. # (#3501). After init_db, so the tables are current, and after the
  1575. # files are copied, so a path that exists as written is kept.
  1576. from backend.app.core import database as _db_mod
  1577. from backend.app.services.backup_paths import convert_windows_paths
  1578. try:
  1579. async with _db_mod.engine.begin() as conn:
  1580. await convert_windows_paths(conn, base_dir)
  1581. except Exception as e:
  1582. logger.warning("Could not convert Windows file paths from the backup: %s", e, exc_info=True)
  1583. # 9. Sign everyone out. The restored users and auth tokens come from
  1584. # another point in time, possibly written by older code, so no
  1585. # session issued before the restore should stay valid.
  1586. async with _db_mod.engine.begin() as conn:
  1587. await _db_mod.invalidate_all_sessions(conn)
  1588. # Open dashboards of signed-in users too: they are never signed in
  1589. # again. API-key and anonymous ones are not closed outright (nothing
  1590. # ended theirs), but the restored data decides what they may still see: the anonymous ones
  1591. # go if the backup turns authentication on, and the refresh closes
  1592. # those of a key the backup does not have (or has under another key).
  1593. from backend.app.core.auth import invalidate_auth_enabled_cache
  1594. from backend.app.core.websocket import ws_manager
  1595. # Read from the restored data: this request has just cached the
  1596. # setting it had before.
  1597. invalidate_auth_enabled_cache()
  1598. # Cloud presets were cached per user of the replaced user table.
  1599. from backend.app.api.routes.cloud import forget_all_cloud_presets
  1600. forget_all_cloud_presets()
  1601. async with _db_mod.async_session() as auth_db:
  1602. auth_on = await is_auth_enabled(auth_db)
  1603. if auth_on:
  1604. await ws_manager.close_signed_in()
  1605. await ws_manager.close_anonymous()
  1606. await ws_manager.refresh_printer_scopes()
  1607. logger.info("Restore complete - restart required")
  1608. message = "Backup restored successfully. Please restart Bambuddy for changes to take effect."
  1609. if skipped_dirs:
  1610. message += f" Note: Some directories could not be restored ({', '.join(skipped_dirs)})."
  1611. return {
  1612. "success": True,
  1613. "message": message,
  1614. }
  1615. except HTTPException:
  1616. # Preserve specific HTTP error responses raised inside the restore
  1617. # body (e.g. the key-write OSError → 500). The blanket
  1618. # except Exception below would otherwise swallow them and replace
  1619. # the operator-facing detail with a generic message.
  1620. raise
  1621. except Exception as e:
  1622. logger.error("Restore failed: %s", e, exc_info=True)
  1623. return JSONResponse(
  1624. status_code=500,
  1625. content={"success": False, "message": "Restore failed. Check server logs for details."},
  1626. )
  1627. @router.get("/network-interfaces")
  1628. async def get_network_interfaces(
  1629. _: User | None = RequirePermissionIfAuthEnabled(Permission.SETTINGS_READ),
  1630. ):
  1631. """Get available network interfaces with all IPs (primary + aliases)."""
  1632. from backend.app.services.network_utils import get_all_interface_ips
  1633. interfaces = get_all_interface_ips()
  1634. return {"interfaces": interfaces}
  1635. @router.get("/virtual-printer/models")
  1636. async def get_virtual_printer_models(
  1637. _: User | None = RequirePermissionIfAuthEnabled(Permission.SETTINGS_READ),
  1638. ):
  1639. """Get available virtual printer models."""
  1640. from backend.app.services.virtual_printer import (
  1641. DEFAULT_VIRTUAL_PRINTER_MODEL,
  1642. VIRTUAL_PRINTER_MODELS,
  1643. )
  1644. return {
  1645. "models": VIRTUAL_PRINTER_MODELS,
  1646. "default": DEFAULT_VIRTUAL_PRINTER_MODEL,
  1647. }
  1648. def _legacy_vp_status(status: dict, printer_scope: PrinterScope) -> dict:
  1649. """The first virtual printer's status, without what names its target for a limited caller."""
  1650. if printer_scope.is_unrestricted:
  1651. return status
  1652. return {key: value for key, value in status.items() if key not in ("name", "serial", "target_printer_ip", "proxy")}
  1653. @router.get("/virtual-printer")
  1654. async def get_virtual_printer_settings(
  1655. db: AsyncSession = Depends(get_db, scope="function"),
  1656. _: User | None = RequirePermissionIfAuthEnabled(Permission.SETTINGS_READ),
  1657. printer_scope: PrinterScope = RequestPrinterScope,
  1658. ):
  1659. """Get the settings this route still sets, and the virtual printers' status.
  1660. Every other virtual printer setting lives on its own row
  1661. (``GET /virtual-printers``).
  1662. """
  1663. from backend.app.services.virtual_printer import virtual_printer_manager
  1664. tailscale_disabled_raw = await get_setting(db, "virtual_printer_tailscale_disabled")
  1665. archive_name_source = await get_setting(db, "virtual_printer_archive_name_source")
  1666. return {
  1667. "tailscale_disabled": tailscale_disabled_raw == "true" if tailscale_disabled_raw else True,
  1668. "archive_name_source": archive_name_source if archive_name_source in ("metadata", "filename") else "metadata",
  1669. "status": _legacy_vp_status(virtual_printer_manager.get_status(), printer_scope),
  1670. }
  1671. @router.put("/virtual-printer")
  1672. async def update_virtual_printer_settings(
  1673. enabled: bool = None,
  1674. access_code: str = None,
  1675. mode: str = None,
  1676. model: str = None,
  1677. target_printer_id: int = None,
  1678. remote_interface_ip: str = None,
  1679. tailscale_disabled: bool = None,
  1680. archive_name_source: str = None,
  1681. db: AsyncSession = Depends(get_db, scope="function"),
  1682. _: User | None = RequirePermissionIfAuthEnabled(Permission.SETTINGS_UPDATE),
  1683. printer_scope: PrinterScope = RequestPrinterScope,
  1684. ):
  1685. """Legacy single-printer settings: the archive name source and the first
  1686. virtual printer's Tailscale switch.
  1687. Every other virtual printer setting lives on its own row, set with
  1688. ``PUT /virtual-printers/{id}``; the rest of this route's parameters are
  1689. refused (vp-3).
  1690. """
  1691. from sqlalchemy import select
  1692. from backend.app.models.virtual_printer import VirtualPrinter as FirstVP
  1693. current_target_id_str = await get_setting(db, "virtual_printer_target_printer_id")
  1694. current_target_id = int(current_target_id_str) if current_target_id_str else None
  1695. # One bridging to a printer the caller can't use is not theirs to change,
  1696. # and they can't aim it at such a printer.
  1697. # The first virtual printer is the one these settings reach.
  1698. first_vp = (await db.execute(select(FirstVP).order_by(FirstVP.position, FirstVP.id).limit(1))).scalar_one_or_none()
  1699. if not printer_scope.allows(current_target_id) or (
  1700. first_vp is not None and not printer_scope.allows(first_vp.target_printer_id)
  1701. ):
  1702. return JSONResponse(status_code=404, content={"detail": "Virtual printer not found"})
  1703. if target_printer_id is not None and not printer_scope.allows(target_printer_id):
  1704. return JSONResponse(status_code=400, content={"detail": f"Printer with ID {target_printer_id} not found"})
  1705. # Each virtual printer keeps these itself now; this route wrote them to
  1706. # settings keys nothing reads and answered 200 as if applied (vp-3). The
  1707. # stored legacy values are not checked either: an old install's stale
  1708. # mode or deleted target printer refused the settings this still serves.
  1709. unread = [
  1710. name
  1711. for name, value in (
  1712. ("enabled", enabled),
  1713. ("access_code", access_code),
  1714. ("mode", mode),
  1715. ("model", model),
  1716. ("target_printer_id", target_printer_id),
  1717. ("remote_interface_ip", remote_interface_ip),
  1718. )
  1719. if value is not None
  1720. ]
  1721. if unread:
  1722. return JSONResponse(
  1723. status_code=400,
  1724. content={
  1725. "detail": f"{', '.join(unread)} cannot be set here any more: set them for each virtual printer "
  1726. "with PUT /api/v1/virtual-printers/{id}"
  1727. },
  1728. )
  1729. if archive_name_source is not None and archive_name_source not in ("metadata", "filename"):
  1730. return JSONResponse(
  1731. status_code=400,
  1732. content={"detail": "archive_name_source must be 'metadata' or 'filename'"},
  1733. )
  1734. if tailscale_disabled is not None:
  1735. await set_setting(db, "virtual_printer_tailscale_disabled", "true" if tailscale_disabled else "false")
  1736. # The first virtual printer's card shows its Tailscale address by it.
  1737. if first_vp is not None:
  1738. first_vp.tailscale_disabled = tailscale_disabled
  1739. if archive_name_source is not None:
  1740. await set_setting(db, "virtual_printer_archive_name_source", archive_name_source)
  1741. await db.commit()
  1742. db.expire_all()
  1743. return await get_virtual_printer_settings(db, printer_scope=printer_scope)
  1744. # =============================================================================
  1745. # MQTT Relay Settings
  1746. # =============================================================================
  1747. @router.get("/mqtt/status")
  1748. async def get_mqtt_status(
  1749. _: User | None = RequirePermissionIfAuthEnabled(Permission.SETTINGS_READ),
  1750. ):
  1751. """Get MQTT relay connection status."""
  1752. from backend.app.services.mqtt_relay import mqtt_relay
  1753. return mqtt_relay.get_status()