bambuddy/backend/app/schemas/settings.py

import json
import re
from typing import Literal
from urllib.parse import urlparse

from pydantic import BaseModel, Field, ValidationInfo, field_validator

from backend.app.schemas.print_queue import TriState
from backend.app.utils.printer_models import MAX_CHAMBER_TEMP_C

# Outbound service URLs validated on save, so a bad value is rejected at
# configuration time with a clear message rather than failing opaquely at
# request time. Every one of these services is commonly self-hosted on the same
# host or LAN as Bambuddy, so the LAN-service policy applies: loopback and
# RFC-1918 stay permitted, while cloud-metadata endpoints, numeric-encoded IPs,
# IPv4-mapped IPv6 and non-HTTP schemes are rejected. See
# ``_url_safety.assert_safe_lan_service_url``.
#
# Module-level rather than a class attribute so the CI backstop in
# tests/unit/test_outbound_url_ssrf_guards.py can import the real list and
# cannot drift from it. Any new outbound-URL setting belongs here (or, if it
# must be reachable on the public internet, on the stricter OIDC guard).
LAN_SERVICE_URL_SETTINGS = ("ha_url", "obico_ml_url", "orcaslicer_api_url", "bambu_studio_api_url")

# ``docker_compose_dir`` is unusual among the string settings: it is not
# consumed by Bambuddy at all, it is interpolated into a shell command that
# the Settings page invites the user to copy and paste into a root-capable
# terminal (#2664). A value like ``/opt/bambuddy; rm -rf /`` would render as a
# perfectly plausible-looking update command, so anyone with settings:update
# could hand every admin a destructive one-liner to run. Restricting the field
# to characters that occur in real paths removes that entirely; the frontend
# double-quotes the value when it contains a space, which is safe precisely
# because quotes, ``$`` and backticks cannot survive this pattern.
_COMPOSE_DIR_ALLOWED = re.compile(r"^[\w \-./\\:~]+$", re.UNICODE)
_COMPOSE_DIR_MAX_LEN = 512


class AppSettings(BaseModel):
    """Application settings schema."""

    auto_archive: bool = Field(default=True, description="Automatically archive prints when completed")
    save_thumbnails: bool = Field(default=True, description="Extract and save preview images from 3MF files")
    capture_finish_photo: bool = Field(
        default=True,
        description=(
            "Capture photo from printer camera when print completes. Bambuddy records a "
            "brief timelapse during the print so the photo can be sourced from the moment "
            "before the bed drops; the timelapse file is kept if you enabled timelapse for "
            "this print, otherwise it is deleted automatically after the photo is captured."
        ),
    )
    finish_photo_restore_plate: bool = Field(
        default=True,
        description=(
            "Raise the build plate back into camera framing before taking the finish photo. "
            "Bambu's end G-code drops the plate ~100mm as the last thing it does, leaving the "
            "finished print far below the camera's natural framing. Bambuddy moves it back to "
            "just above the last printed layer, takes the photo, then lowers it again. Skipped "
            "when the print height is unknown or another job is queued for the printer."
        ),
    )
    default_filament_cost: float = Field(default=25.0, description="Default filament cost per kg")
    currency: str = Field(default="USD", description="Currency for cost tracking")
    energy_cost_per_kwh: float = Field(default=0.15, description="Electricity cost per kWh for energy tracking")
    energy_tracking_mode: str = Field(
        default="total",
        description="Energy display mode on stats: 'print' shows sum of per-print energy, 'total' shows lifetime plug consumption",
    )
    # A plain string on the way out, like energy_tracking_mode: a stray value
    # (a restored backup) reads as "fixed" everywhere instead of failing the
    # whole settings response. Writes are checked in AppSettingsUpdate.
    energy_price_source: str = Field(
        default="fixed",
        description=(
            "Where the electricity price comes from: 'fixed' uses energy_cost_per_kwh, "
            "'homeassistant' reads energy_price_ha_entity hourly and at print start and end (#1251)"
        ),
    )
    energy_price_ha_entity: str = Field(
        default="", description="Home Assistant sensor holding the electricity price per kWh"
    )

    # Spoolman integration
    spoolman_enabled: bool = Field(default=False, description="Enable Spoolman integration for filament tracking")
    spoolman_url: str = Field(default="", description="Spoolman server URL (e.g., http://localhost:7912)")
    spoolman_sync_mode: str = Field(
        default="auto", description="Sync mode: 'auto' syncs immediately, 'manual' requires button press"
    )
    spoolman_disable_weight_sync: bool = Field(
        default=False,
        description="Disable remaining_weight sync. When enabled, only location is updated for existing spools.",
    )
    spoolman_report_partial_usage: bool = Field(
        default=True,
        description="Report Partial Usage for Failed Prints. When a print fails or is cancelled, report the estimated filament used up to that point based on layer progress.",
    )
    auto_add_unknown_rfid: bool = Field(
        default=True,
        description="Automatically add spools with unknown RFID tags to inventory. Disable if you pre-create inventory entries manually to avoid duplicates.",
    )
    disable_filament_warnings: bool = Field(
        default=False,
        description="Disable insufficient filament warnings when printing or queueing prints",
    )
    prefer_lowest_filament: bool = Field(
        default=False,
        description="When multiple AMS spools match, prefer the one with lowest remaining filament",
    )

    # Updates
    check_updates: bool = Field(default=True, description="Automatically check for updates on startup")
    check_printer_firmware: bool = Field(default=True, description="Check for printer firmware updates from Bambu Lab")
    include_beta_updates: bool = Field(default=False, description="Include beta/prerelease versions in update checks")
    announcements_enabled: bool = Field(
        default=True, description="Fetch announcements from the Bambuddy maintainers (a signed file on GitHub)"
    )
    announcements_all_users: bool = Field(
        default=False, description="Show announcements to every signed-in user, not only administrators"
    )

    # Language
    language: str = Field(default="en", description="UI language (en, de, fr, ja, it, pt-BR)")
    notification_language: str = Field(default="en", description="Language for push notifications (en, de)")

    # Bed cooled notification threshold
    bed_cooled_threshold: float = Field(
        default=35.0, description="Bed temperature threshold for cooled notification (°C)"
    )

    # AMS threshold settings for humidity and temperature coloring
    ams_humidity_good: int = Field(default=40, description="Humidity threshold for good (green): <= this value")
    ams_humidity_fair: int = Field(
        default=60, description="Humidity threshold for fair (orange): <= this value, > is red"
    )
    ams_temp_good: float = Field(default=28.0, description="Temperature threshold for good (blue): <= this value")
    ams_temp_fair: float = Field(
        default=35.0, description="Temperature threshold for fair (orange): <= this value, > is red"
    )
    # Separate from ams_temp_fair on purpose (#2905). The fair threshold decides
    # when the AMS card turns amber; this decides when a notification is sent.
    # 35 C is a sensible place to change a colour and not a sensible place to
    # page someone -- a room above 35 C makes the alarm fire once an hour for as
    # long as the weather lasts, and the only way to silence it was to raise the
    # display band and lose the colour that says the unit is warm. None means
    # "not set", which resolves to ams_temp_fair so every existing install keeps
    # behaving exactly as it does now.
    ams_temp_alarm: float | None = Field(
        default=None,
        description="Temperature threshold (°C) for sending an alarm. Unset falls back to ams_temp_fair.",
    )
    ams_history_retention_days: int = Field(default=30, description="Number of days to keep AMS sensor history data")
    printer_sensor_history_retention_days: int = Field(
        default=30, description="Number of days to keep printer heater history data (nozzle / bed / chamber)"
    )

    # Queue auto-drying settings
    queue_drying_enabled: bool = Field(
        default=False, description="Automatically dry AMS filament between queued prints"
    )
    queue_drying_block: bool = Field(
        default=False,
        description="Block queue until drying completes (when disabled, prints take priority over drying)",
    )
    ambient_drying_enabled: bool = Field(
        default=False,
        description="Automatically dry AMS filament on idle printers when humidity exceeds threshold, regardless of queue",
    )
    ambient_drying_sustained_minutes: int = Field(
        default=0,
        ge=0,
        le=240,
        description=(
            "Minutes the humidity must stay above the threshold before an ambient "
            "auto-dry starts (0 = start immediately). Rides out the reading spike "
            "from opening the AMS lid instead of buying a dry cycle for it."
        ),
    )
    print_drying_enabled: bool = Field(
        default=False,
        description=(
            "Allow auto-drying to also fire on a printer that is currently printing, "
            "when its model+firmware supports concurrent drying (H2D 01.03.00.00+, "
            "H2C/H2S/P2S/H2D Pro 01.02.00.00+, X2D/A2L 01.01.00.00+, X1C 01.11.02.00+). "
            "Drying temperature is automatically capped 5 degC below the idle preset "
            "(floor 40 degC) to protect spools during print."
        ),
    )
    drying_presets: str = Field(
        default="",
        description="JSON blob of drying presets per filament type (empty = use built-in defaults)",
    )
    ams_humidity_thresholds: str = Field(
        default="",
        description=(
            "JSON blob of per-filament-type humidity trigger thresholds for auto-drying and alarms. "
            'Shape: {"default": int, "PLA": int, "ASA": int, ...}. '
            "Empty = fall back to ams_humidity_fair for all types."
        ),
    )

    # Auto-print G-code injection (#422)
    gcode_snippets: str = Field(
        default="",
        description="JSON: per-model G-code injection snippets {model: {start_gcode, end_gcode}}",
    )

    # Scheduled local backup (#884)
    local_backup_enabled: bool = Field(default=False, description="Enable scheduled local backups")
    local_backup_schedule: str = Field(default="daily", description="Backup frequency: hourly, daily, weekly")
    local_backup_time: str = Field(default="03:00", description="Time of day for daily/weekly backups (HH:MM, 24h)")
    local_backup_retention: int = Field(default=5, description="Number of backup files to keep (1-100)")
    local_backup_path: str = Field(default="", description="Backup output directory (empty = DATA_DIR/backups)")

    # Print modal settings
    per_printer_mapping_expanded: bool = Field(
        default=False, description="Expand custom filament mapping by default in print modal"
    )

    # Date/time display format
    date_format: str = Field(default="system", description="Date format: system, us, eu, iso")
    time_format: str = Field(default="system", description="Time format: system, 12h, 24h")

    # Default printer for operations
    default_printer_id: int | None = Field(default=None, description="Default printer ID for uploads, reprints, etc.")

    # Slicer Pipelines (#1425 PR C). Cap on the ``copies`` field in the
    # Run-with-pipeline modal — keeps a misclick from queueing 5000 prints.
    pipeline_max_copies: int = Field(
        default=50,
        ge=1,
        le=1000,
        description="Upper bound on the copies an operator can request when running a Slicer Pipeline. Larger fleets / production rigs can raise this; the hard ceiling at 1000 is a sanity guard against fat-fingered input.",
    )

    # Virtual Printer
    virtual_printer_enabled: bool = Field(default=False, description="Enable virtual printer for slicer uploads")
    virtual_printer_access_code: str = Field(default="", description="Access code for virtual printer authentication")
    virtual_printer_mode: str = Field(
        default="archive",
        description="Mode: 'archive' (archive now), 'review' (pending review), 'queue' (add to print queue), or 'proxy' (relay to real printer)",
    )
    virtual_printer_archive_name_source: str = Field(
        default="metadata",
        description="Source for the archive's display name on virtual-printer uploads: 'metadata' uses the 3MF's embedded print_name (default, matches Bambu's behavior), 'filename' uses the filename Bambu Studio sent over FTP (lets users rename via the slicer's 'send to printer' dialog).",
    )

    # Dark mode theme settings
    dark_style: str = Field(default="vibrant", description="Dark mode style: classic, glow, vibrant")
    dark_background: str = Field(
        default="cool", description="Dark mode background: neutral, warm, cool, oled, slate, forest"
    )
    dark_accent: str = Field(default="green", description="Dark mode accent: green, teal, blue, orange, purple, red")

    # Light mode theme settings
    light_style: str = Field(default="classic", description="Light mode style: classic, glow, vibrant")
    light_background: str = Field(default="neutral", description="Light mode background: neutral, warm, cool")
    light_accent: str = Field(default="green", description="Light mode accent: green, teal, blue, orange, purple, red")

    # FTP retry settings for unreliable WiFi connections
    ftp_retry_enabled: bool = Field(default=True, description="Enable automatic retry for FTP operations")
    ftp_retry_count: int = Field(default=3, description="Number of retry attempts for FTP operations (1-10)")
    ftp_retry_delay: int = Field(default=2, description="Seconds to wait between FTP retry attempts (1-30)")
    ftp_timeout: int = Field(default=30, description="FTP connection timeout in seconds (10-300)")

    # MQTT Relay settings for publishing events to external broker
    mqtt_enabled: bool = Field(default=False, description="Enable MQTT event publishing to external broker")
    mqtt_broker: str = Field(default="", description="MQTT broker hostname or IP address")
    mqtt_port: int = Field(default=1883, description="MQTT broker port (default 1883, TLS typically 8883)")
    mqtt_username: str = Field(default="", description="MQTT username for authentication (optional)")
    mqtt_password: str = Field(default="", description="MQTT password for authentication (optional)")
    mqtt_topic_prefix: str = Field(default="bambuddy", description="Topic prefix for all published messages")
    mqtt_use_tls: bool = Field(default=False, description="Use TLS/SSL encryption for MQTT connection")

    # External URL for notifications
    external_url: str = Field(
        default="", description="External URL where Bambuddy is accessible (for notification images)"
    )

    # Directory holding the user's docker-compose.yml, shown in the update
    # instructions so the printed command can be pasted from anywhere (#2664).
    # Empty means "omit the cd" — which is also the correct rendering when
    # nothing could be detected, rather than guessing a path that fails.
    docker_compose_dir: str = Field(
        default="", description="Host directory containing docker-compose.yml, used in the update instructions"
    )

    # Home Assistant integration for smart plug control
    ha_enabled: bool = Field(default=False, description="Enable Home Assistant integration for smart plug control")
    ha_url: str = Field(default="", description="Home Assistant URL (e.g., http://192.168.1.100:8123)")
    ha_token: str = Field(default="", description="Home Assistant Long-Lived Access Token")
    ha_url_from_env: bool = Field(default=False, description="Whether HA URL is set via HA_URL environment variable")
    ha_token_from_env: bool = Field(
        default=False, description="Whether HA token is set via HA_TOKEN environment variable"
    )
    ha_env_managed: bool = Field(
        default=False, description="Whether HA integration is fully managed by environment variables"
    )

    # File Manager / Library settings
    library_archive_mode: str = Field(
        default="ask",
        description="When printing from File Manager, create archive entry: 'always', 'never', or 'ask'",
    )
    library_disk_warning_gb: float = Field(
        default=5.0,
        description="Show warning when free disk space falls below this threshold (GB)",
    )

    # Chamber light while the camera is in use (#1655): "off", "all" printers,
    # or the "selected" printers (Printer.camera_light_auto). A stored value
    # outside these reads as off in the service, so it is a plain str here.
    camera_light_mode: str = Field(
        default="off",
        description="Turn the chamber light on while the camera is in use: 'off', 'all' or 'selected' printers",
    )
    camera_light_delay: float = Field(
        default=2.0,
        description="Seconds an automatic snapshot waits after the chamber light was turned on",
    )

    # Camera view settings
    camera_view_mode: str = Field(
        default="window",
        description="Camera view mode: 'window' opens in new browser window, 'embedded' shows overlay on main screen",
    )

    # Preferred slicer application (server-side / API sidecar slicer)
    preferred_slicer: str = Field(
        default="bambu_studio",
        description="Slicer used for the server-side API / sidecar: 'bambu_studio' or 'orcaslicer'",
    )
    # "Open in Slicer" desktop URI handler — independent of the API slicer so
    # a user can slice via the Bambu Studio sidecar but open files locally in
    # OrcaSlicer, or vice versa (#1329). None falls back to ``preferred_slicer``
    # so existing installs behave identically until someone changes it.
    open_in_slicer: str | None = Field(
        default=None,
        description=(
            "Desktop slicer for the 'Open in Slicer' button: 'bambu_studio' or "
            "'orcaslicer'. None inherits from preferred_slicer."
        ),
    )

    # Where slicing runs. Orthogonal to ``preferred_slicer``, which only says
    # *which slicer binary* the sidecar drives: a browser engine is a different
    # execution site, not a different binary choice. Kept as its own key so the
    # two never have to encode impossible combinations.
    #
    # Only "sidecar" is implemented today; the slice modal offers a per-job
    # choice when more than one engine is available, and hides the control
    # entirely while there is only one.
    slice_engine: str = Field(
        default="sidecar",
        description="Default execution site for slicing: 'sidecar' (server-side API) or 'browser'",
    )

    # Slicer dispatch mode: when True, "Slice" actions open the in-app
    # SliceModal and call the slicer-API sidecar. When False (default), they
    # hand off to the user's local desktop slicer via URI scheme — preserving
    # the original Bambuddy behavior for users who don't run a sidecar.
    use_slicer_api: bool = Field(
        default=False,
        description="Use the slicer-API sidecar for slicing instead of the desktop slicer URI scheme",
    )

    # Slicer-API sidecar base URLs. Per-installation, configured via the
    # Settings UI (the "Slicer" card). Empty string means "fall back to the
    # SLICER_API_URL / BAMBU_STUDIO_API_URL env vars" — which themselves
    # default to the docker-compose ports in core/config.py.
    orcaslicer_api_url: str = Field(
        default="",
        description="OrcaSlicer sidecar URL (e.g. http://localhost:3003). Empty falls back to the SLICER_API_URL env var.",
    )
    bambu_studio_api_url: str = Field(
        default="",
        description="BambuStudio sidecar URL (e.g. http://localhost:3001). Empty falls back to the BAMBU_STUDIO_API_URL env var.",
    )
    # How long to keep waiting on a slice that isn't finishing. Measured against
    # the sidecar's progress channel, not total elapsed time — a heavy model can
    # legitimately slice for half an hour, and a wall-clock ceiling cannot tell
    # that apart from a stalled one (#2730). Sidecars too old to report progress
    # fall back to using this as a total-elapsed ceiling, which is the pre-#2730
    # behaviour with a configurable number.
    slicer_stall_timeout_minutes: int = Field(
        default=15,
        ge=1,
        le=240,
        description=(
            "Give up on a slice after this many minutes with no progress from the sidecar. "
            "On sidecars that do not report progress, applies to total slicing time instead."
        ),
    )

    # Prometheus metrics endpoint
    prometheus_enabled: bool = Field(default=False, description="Enable Prometheus metrics endpoint at /metrics")
    prometheus_token: str = Field(
        default="", description="Bearer token for Prometheus metrics authentication (optional)"
    )

    # Inventory low stock threshold
    low_stock_threshold: float = Field(
        default=20.0,
        ge=0.1,
        le=99.9,
        description="Low stock threshold percentage (%) for inventory filtering and display",
    )

    # Session policy (#1706) — admin-set ceiling for user session lifetime.
    # Default 24h preserves the M-2 audit reduction from 7 days. Max 720h
    # (30 days) bounds blast radius if an admin chooses a long session.
    session_max_hours: int = Field(
        default=24,
        ge=1,
        le=720,
        description=(
            "Maximum session lifetime in hours for user logins (default 24, max 720). "
            "Applies to new logins only; already-issued tokens keep their original expiry. "
            "Longer sessions reduce automatic logout protection."
        ),
    )

    # User email notifications (requires Advanced Authentication)
    user_notifications_enabled: bool = Field(
        default=True,
        description="Enable user email notifications for print job events (requires Advanced Authentication)",
    )

    # Default print options. bed_levelling / flow_cali / nozzle_offset_cali are
    # tri-state (off/on/auto), defaulting to "auto" per BambuStudio.
    default_bed_levelling: TriState = Field(default="auto", description="Default bed levelling option for new prints")
    default_flow_cali: TriState = Field(default="auto", description="Default flow calibration option for new prints")
    default_vibration_cali: bool = Field(
        default=True, description="Default vibration calibration option for new prints"
    )
    default_layer_inspect: bool = Field(
        default=False, description="Default first layer inspection option for new prints"
    )
    default_timelapse: bool = Field(default=False, description="Default timelapse option for new prints")
    default_nozzle_offset_cali: TriState = Field(
        default="auto",
        description="Default nozzle offset calibration option for new prints (dual-nozzle printers only)",
    )
    default_confirm_outcome: bool = Field(
        default=False,
        description="Default for asking for a post-print outcome verdict on new prints (#1898)",
    )
    confirm_outcome_external_prints: bool = Field(
        default=False,
        description=(
            "Also ask for the outcome of prints Bambuddy archived but did not dispatch — started at "
            "the printer, in Bambu Studio or in the Handy app (#1898)"
        ),
    )
    confirm_default_good_on_plate_clear: bool = Field(
        default=False,
        description=(
            "When the build plate is released (manual acknowledgment or next dispatch) with the "
            "outcome prompt still unanswered, record the print as a good part (#1898)"
        ),
    )

    # Staggered batch start for multi-printer jobs
    stagger_group_size: int = Field(
        default=2, ge=1, le=50, description="Number of printers to start simultaneously in staggered mode"
    )
    stagger_interval_minutes: int = Field(
        default=5, ge=1, le=60, description="Minutes between staggered printer groups"
    )

    # Finance budget window settings
    billing_enabled: bool = Field(
        default=False,
        description="Enable cost-center billing enforcement for print and queue operations",
    )
    printer_kill_switch_enabled: bool = Field(
        default=False,
        description="Immediately stop printer jobs that start without Bambuddy authorization",
    )
    finance_budget_reset_day: int = Field(
        default=1,
        ge=1,
        le=31,
        description="Day of month when monthly finance budget window resets (1-31, clamped for short months)",
    )
    finance_budget_reset_timezone: str = Field(
        default="UTC",
        description="IANA timezone for finance monthly budget reset calculation (e.g., Europe/Berlin)",
    )

    # Plate-clear confirmation for queue scheduling
    require_plate_clear: bool = Field(
        default=False,
        description="Require per-printer plate-clear confirmation before starting queued prints on finished printers",
    )
    queue_shortest_first: bool = Field(
        default=False,
        description="Shortest Job First — scheduler prioritizes shorter print jobs over longer ones",
    )
    queue_max_concurrent_uploads: int = Field(
        default=4,
        ge=1,
        le=16,
        description=(
            "How many printers the queue may upload to at the same time. Printers are independent "
            "machines, so raising this starts a multi-printer batch proportionally sooner; each "
            "concurrent upload costs one connection and one thread on the Bambuddy host."
        ),
    )

    # Preheat / heat-soak before queued prints (#1468). The scheduler stage runs
    # BEFORE FTP upload. Three hardware tiers behave differently:
    #   - Chamber heater (H2C/H2D/H2DPro/H2S/X2D/X1E): M141 → wait for chamber
    #     sensor to reach target → soak
    #   - Chamber sensor only (X1C/P2S): M140 only → wait for radiant chamber
    #     warm-up to reach target OR max-wait timeout → soak
    #   - No chamber sensor (P1S/P1P/A1/A1 Mini): M140 only → fixed soak timer
    #     (no way to verify chamber temp; relies entirely on max_wait + soak)
    # Chamber target derives per-print from the loaded AMS filament types via
    # preheat_filament_targets (max across loaded slots). A target of 0 skips
    # the chamber phase but keeps the bed phase + soak. Per-queue-item
    # `preheat_chamber_target_override` (nullable) bypasses the derivation.
    preheat_enabled: bool = Field(
        default=False,
        description="Master toggle / default for new queue items. Per-item preheat_override can flip the decision per print.",
    )
    preheat_filament_targets: str = Field(
        default="",
        description=(
            "JSON map of normalized filament type → chamber target °C. Empty = bundled defaults "
            "(PLA/PETG/TPU/PVA: 0, PETG-CF: 40, ABS/ASA: 45, PA/PC/PC-FR: 50, PA-CF: 55, default: 0). "
            "Scheduler picks max across loaded AMS slots; 0 disables chamber phase for that print."
        ),
    )
    preheat_max_wait_seconds: int = Field(
        default=900,
        ge=60,
        le=3600,
        description="Maximum time to wait for the chamber to reach the target before falling through to the soak phase (radiant heating on X1C/P2S can take 15-30 min).",
    )
    preheat_soak_seconds: int = Field(
        default=300,
        ge=0,
        le=1800,
        description="Additional hold time at temperature after the chamber reaches the target (or after max_wait_seconds elapses). 0 = no soak.",
    )
    queue_keep_bed_warm: bool = Field(
        default=False,
        description=(
            "While a printer is in FINISH state awaiting plate-clear and the next queued item requires "
            "chamber heating, hold the bed hot so the chamber stays warm during the bed-clearing "
            "window. The bed is the chamber's heating element here: the hold target is "
            "queue_keep_warm_bed_temp, or the item's own bed_temperature when the slicer metadata "
            "reports a higher one. Only fires for filaments with a non-zero chamber target "
            "(ASA, ABS, PA, PC etc.); PLA/PETG prints are skipped automatically."
        ),
    )
    queue_keep_warm_bed_temp: int = Field(
        default=90,
        ge=40,
        le=110,
        description=(
            "Bed temperature (°C) used when the bed's job is to heat the chamber. 90 sustains "
            "chamber warmth on enclosed printers and satisfies bed-threshold-linked aftermarket "
            "chamber heaters (which typically activate at bed ≥ 80). Applies in two places: the "
            "keep-warm hold between chamber-heated prints, and preheat when a chamber-heated "
            "item's slicer metadata carries no bed temperature at all. A parsed bed temperature "
            "higher than this always wins, so the bed is never driven cooler than the print needs."
        ),
    )
    queue_keep_warm_max_minutes: int = Field(
        default=120,
        ge=5,
        le=480,
        description=(
            "How long keep-warm may hold the bed on a printer waiting for its plate to be cleared. "
            "When this elapses the bed is switched off, and the hold does not re-arm until the "
            "printer next becomes a keep-warm candidate — so a plate nobody clears cannot leave the "
            "bed hot indefinitely. Set it to how long you realistically take to reach the printer; "
            "the only cost of it being too short is that the next print re-soaks from cold."
        ),
    )

    # User-configurable presets for the printer-card temperature / fan-speed
    # popovers. Each is a JSON array of exactly 3 ints (the "Off" button is
    # rendered separately and is not configurable). Empty string = use built-in
    # defaults. Validators on AppSettingsUpdate enforce the shape on writes.
    nozzle_temp_presets: str = Field(
        default="",
        description="JSON array of 3 nozzle-temperature preset values in C (0-320). Empty = use defaults [120, 220, 260]",
    )
    bed_temp_presets: str = Field(
        default="",
        description="JSON array of 3 bed-temperature preset values in C (0-140). Empty = use defaults [55, 75, 90]",
    )
    chamber_temp_presets: str = Field(
        default="",
        description="JSON array of 3 chamber-temperature preset values in C (0-65). Empty = use defaults [35, 45, 60]",
    )
    fan_speed_presets: str = Field(
        default="",
        description="JSON array of 3 fan-speed preset values in % (0-100). Empty = use defaults [50, 75, 100]",
    )

    # Local login (#1589) — when False, /auth/login rejects username+password
    # credentials with HTTP 403 and the login page hides the credentials form,
    # leaving only the OIDC SSO provider buttons. LDAP is governed by its own
    # `ldap_enabled` toggle and is not affected. The env-var
    # ``BAMBUDDY_LOCAL_LOGIN=true`` bypasses this gate at the route level so a
    # server admin can recover an install whose SSO provider is unreachable
    # without editing the DB.
    local_login_enabled: bool = Field(
        default=True,
        description=(
            "Allow username + password login on /auth/login. Disable when only SSO should be usable. "
            "BAMBUDDY_LOCAL_LOGIN=true on the server overrides this to keep a recovery path open."
        ),
    )

    # LDAP authentication (#794)
    ldap_enabled: bool = Field(default=False, description="Enable LDAP authentication")
    ldap_server_url: str = Field(default="", description="LDAP server URL (e.g., ldap://ldap.example.com:389)")
    ldap_bind_dn: str = Field(default="", description="Bind DN for LDAP searches (e.g., cn=admin,dc=example,dc=com)")
    ldap_bind_password: str = Field(default="", description="Bind password for LDAP searches")
    ldap_search_base: str = Field(default="", description="Search base DN (e.g., ou=users,dc=example,dc=com)")
    ldap_user_filter: str = Field(
        default="(sAMAccountName={username})",
        description="LDAP user search filter. {username} is replaced with the login username",
    )
    ldap_security: str = Field(default="starttls", description="LDAP security: 'starttls' or 'ldaps'")
    ldap_group_mapping: str = Field(
        default="",
        description="JSON: LDAP group to BamBuddy group mapping {ldap_group_dn: bambuddy_group_name}",
    )
    ldap_auto_provision: bool = Field(
        default=False,
        description="Auto-create BamBuddy user on first successful LDAP login",
    )
    ldap_default_group: str = Field(
        default="",
        description="Fallback BamBuddy group name assigned when an LDAP user authenticates but has no mapped groups. Empty = no fallback.",
    )

    # Obico AI failure detection (#172)
    obico_enabled: bool = Field(default=False, description="Enable Obico AI print failure detection")
    obico_ml_url: str = Field(
        default="",
        description="Self-hosted Obico ML API base URL (e.g., http://192.168.1.10:3333)",
    )
    bambuddy_internal_url: str = Field(
        default="", description="Bambuddy Internal URL for Obico; empty uses External URL"
    )
    obico_ml_token: str = Field(
        default="",
        description=(
            "Bearer token for the Obico ML API, matching the server's ML_API_TOKEN "
            "environment variable. Empty when the server runs without one."
        ),
    )
    obico_sensitivity: str = Field(
        default="medium",
        description="Detection sensitivity: 'low', 'medium', or 'high' (adjusts LOW/HIGH thresholds)",
    )
    obico_action: str = Field(
        default="notify",
        description="Action on detected failure: 'notify', 'pause', or 'pause_and_off'",
    )
    obico_poll_interval: int = Field(
        default=10,
        ge=5,
        le=120,
        description="Seconds between detection checks while a print is running",
    )
    obico_enabled_printers: str = Field(
        default="",
        description="JSON array of printer IDs to monitor (empty = all connected printers)",
    )

    # Inventory forecasting
    forecast_global_lead_time_days: int = Field(
        default=0,
        ge=0,
        description="Global lead time floor (days) used in reorder point calculation for all SKUs",
    )

    location_sensor_poll_interval: int = Field(
        default=120,
        ge=60,
        le=3600,
        description="Seconds between Home Assistant polls/UI refreshes for storage-location sensors",
    )
    # Server-backed rather than per-browser: these seed the alert rule written
    # onto each sensor row when one is bound, so two admins binding sensors
    # from different browsers must not seed different rules — and a restore
    # has to bring them back. The "show on card" default stays local, because
    # show_on_card is decided per sensor and this is only its form
    # pre-selection. Same JSON-in-a-string shape as preheat_filament_targets.
    location_sensor_alert_defaults: str = Field(
        default="",
        description=(
            "JSON map of sensor category (temperature/humidity/battery) → "
            '{"alertAbove": str, "alertBelow": str, "notifyOnAlert": bool}, seeding new '
            "storage-location sensor bindings. Empty = built-in defaults."
        ),
    )

    # Default sidebar order (admin-set for all users)
    default_sidebar_order: str = Field(
        default="",
        description="JSON object with 'order' key containing array of sidebar item IDs (empty = no default)",
    )

    # The settings page sends every field back on each save, and the update
    # schema accepts only these values. A stored value outside them would make
    # every later save fail, so it is read back as what the service treats it as.
    @field_validator("camera_light_mode", mode="before")
    @classmethod
    def _known_camera_light_mode(cls, value):
        return value if value in ("off", "all", "selected") else "off"

    @field_validator("camera_light_delay", mode="before")
    @classmethod
    def _camera_light_delay_in_range(cls, value):
        try:
            seconds = float(value)
        except (TypeError, ValueError):
            return 2.0
        return min(max(0.0, seconds), 5.0)


class AppSettingsUpdate(BaseModel):
    """Schema for updating settings (all fields optional)."""

    auto_archive: bool | None = None
    save_thumbnails: bool | None = None
    capture_finish_photo: bool | None = None
    finish_photo_restore_plate: bool | None = None
    default_filament_cost: float | None = None
    currency: str | None = None
    energy_cost_per_kwh: float | None = None
    energy_tracking_mode: str | None = None
    energy_price_source: Literal["fixed", "homeassistant"] | None = None
    energy_price_ha_entity: str | None = Field(default=None, max_length=255)
    spoolman_enabled: bool | None = None
    spoolman_url: str | None = None
    spoolman_sync_mode: str | None = None
    spoolman_disable_weight_sync: bool | None = None
    spoolman_report_partial_usage: bool | None = None
    auto_add_unknown_rfid: bool | None = None
    disable_filament_warnings: bool | None = None
    prefer_lowest_filament: bool | None = None
    check_updates: bool | None = None
    check_printer_firmware: bool | None = None
    include_beta_updates: bool | None = None
    announcements_enabled: bool | None = None
    announcements_all_users: bool | None = None
    local_login_enabled: bool | None = None
    language: str | None = None
    notification_language: str | None = None
    bed_cooled_threshold: float | None = None
    ams_humidity_good: int | None = None
    ams_humidity_fair: int | None = None
    ams_temp_good: float | None = None
    ams_temp_fair: float | None = None
    ams_temp_alarm: float | None = None
    ams_history_retention_days: int | None = None
    printer_sensor_history_retention_days: int | None = None
    queue_drying_enabled: bool | None = None
    queue_drying_block: bool | None = None
    ambient_drying_enabled: bool | None = None
    ambient_drying_sustained_minutes: int | None = Field(default=None, ge=0, le=240)
    print_drying_enabled: bool | None = None
    drying_presets: str | None = None
    ams_humidity_thresholds: str | None = None
    per_printer_mapping_expanded: bool | None = None
    date_format: str | None = None
    time_format: str | None = None
    default_printer_id: int | None = None
    pipeline_max_copies: int | None = None
    virtual_printer_enabled: bool | None = None
    virtual_printer_access_code: str | None = None
    virtual_printer_mode: str | None = None
    virtual_printer_archive_name_source: str | None = None
    dark_style: str | None = None
    dark_background: str | None = None
    dark_accent: str | None = None
    light_style: str | None = None
    light_background: str | None = None
    light_accent: str | None = None
    ftp_retry_enabled: bool | None = None
    ftp_retry_count: int | None = None
    ftp_retry_delay: int | None = None
    ftp_timeout: int | None = None
    mqtt_enabled: bool | None = None
    mqtt_broker: str | None = None
    mqtt_port: int | None = None
    mqtt_username: str | None = None
    mqtt_password: str | None = None
    mqtt_topic_prefix: str | None = None
    mqtt_use_tls: bool | None = None
    external_url: str | None = None
    docker_compose_dir: str | None = None
    ha_enabled: bool | None = None
    ha_url: str | None = None
    ha_token: str | None = None
    library_archive_mode: str | None = None
    library_disk_warning_gb: float | None = None
    camera_view_mode: str | None = None
    camera_light_mode: Literal["off", "all", "selected"] | None = None
    # Capped by camera_light.MAX_DELAY_SECONDS: the finish photo's budget
    # has no more to spare.
    camera_light_delay: float | None = Field(default=None, ge=0, le=5)
    preferred_slicer: str | None = None
    open_in_slicer: str | None = None
    slice_engine: str | None = None
    use_slicer_api: bool | None = None
    orcaslicer_api_url: str | None = None
    bambu_studio_api_url: str | None = None
    slicer_stall_timeout_minutes: int | None = Field(default=None, ge=1, le=240)
    prometheus_enabled: bool | None = None
    prometheus_token: str | None = None
    low_stock_threshold: float | None = Field(default=None, ge=0.1, le=99.9)
    session_max_hours: int | None = Field(default=None, ge=1, le=720)
    user_notifications_enabled: bool | None = None
    default_bed_levelling: TriState | None = None
    default_flow_cali: TriState | None = None
    default_vibration_cali: bool | None = None
    default_layer_inspect: bool | None = None
    default_timelapse: bool | None = None
    default_nozzle_offset_cali: TriState | None = None
    default_confirm_outcome: bool | None = None
    confirm_outcome_external_prints: bool | None = None
    confirm_default_good_on_plate_clear: bool | None = None
    stagger_group_size: int | None = Field(default=None, ge=1, le=50)
    stagger_interval_minutes: int | None = Field(default=None, ge=1, le=60)
    billing_enabled: bool | None = None
    printer_kill_switch_enabled: bool | None = None
    finance_budget_reset_day: int | None = Field(default=None, ge=1, le=31)
    finance_budget_reset_timezone: str | None = None
    require_plate_clear: bool | None = None
    queue_shortest_first: bool | None = None
    queue_max_concurrent_uploads: int | None = Field(default=None, ge=1, le=16)
    preheat_enabled: bool | None = None
    preheat_filament_targets: str | None = None
    preheat_max_wait_seconds: int | None = Field(default=None, ge=60, le=3600)
    preheat_soak_seconds: int | None = Field(default=None, ge=0, le=1800)
    queue_keep_bed_warm: bool | None = None
    queue_keep_warm_bed_temp: int | None = Field(default=None, ge=40, le=110)
    queue_keep_warm_max_minutes: int | None = Field(default=None, ge=5, le=480)
    nozzle_temp_presets: str | None = None
    bed_temp_presets: str | None = None
    chamber_temp_presets: str | None = None
    fan_speed_presets: str | None = None
    gcode_snippets: str | None = None
    local_backup_enabled: bool | None = None
    local_backup_schedule: str | None = None
    local_backup_time: str | None = None
    local_backup_retention: int | None = None
    local_backup_path: str | None = None
    ldap_enabled: bool | None = None
    ldap_server_url: str | None = None
    ldap_bind_dn: str | None = None
    ldap_bind_password: str | None = None
    ldap_search_base: str | None = None
    ldap_user_filter: str | None = None
    ldap_security: str | None = None
    ldap_group_mapping: str | None = None
    ldap_auto_provision: bool | None = None
    ldap_default_group: str | None = None
    obico_enabled: bool | None = None
    obico_ml_url: str | None = None
    bambuddy_internal_url: str | None = None
    obico_ml_token: str | None = None
    obico_sensitivity: str | None = None
    obico_action: str | None = None
    obico_poll_interval: int | None = Field(default=None, ge=5, le=120)
    obico_enabled_printers: str | None = None
    default_sidebar_order: str | None = None
    forecast_global_lead_time_days: int | None = Field(default=None, ge=0)
    location_sensor_poll_interval: int | None = Field(default=None, ge=60, le=3600)
    # Three categories × three short fields is well under 300 characters of
    # JSON, so 2000 is pure headroom — the cap only stops a stray client from
    # parking megabytes in the settings table. Write path only: the AppSettings
    # read model must keep accepting whatever an older install already stored.
    location_sensor_alert_defaults: str | None = Field(default=None, max_length=2000)

    @field_validator(*LAN_SERVICE_URL_SETTINGS)
    @classmethod
    def validate_lan_service_url(cls, v: str | None, info: ValidationInfo) -> str | None:
        """Reject SSRF-unsafe outbound service URLs on save.

        Empty (and whitespace-only) is the documented "not configured / fall
        back to the env var" value for all four fields and must keep passing.

        Values that are not absolute URLs at all ("192.168.1.10:3333",
        "localhost:3333") are left alone rather than rejected. Two reasons:

        - They are inert. Every consumer of these four settings goes through
          httpx, which raises UnsupportedProtocol for a URL with no scheme, so
          no request is ever issued and there is nothing to guard against.
        - They were storable before this validator existed, and the settings
          UI is a plain text input with no scheme enforcement. Newly rejecting
          them would break saves that have nothing to do with the URL: the
          Obico panel, for one, sends obico_ml_url with every change and
          auto-saves, so one legacy value would block toggling detection on or
          off. A pre-existing misconfiguration should keep failing where it
          already failed (at request time), not spread to unrelated fields.

        ``urlparse`` is no help in telling the two apart — it reads
        "localhost:3333" as scheme "localhost" — so the test is the literal
        "://" that makes a string an absolute URL.
        """
        if v is None or not v.strip():
            return v
        candidate = v.strip()
        if "://" not in candidate:
            return v
        # Lazy-imported: schemas avoid top-level imports from api/routes,
        # matching the existing pattern in auth.py's _validate_icon_url.
        from backend.app.api.routes._url_safety import assert_safe_lan_service_url

        try:
            assert_safe_lan_service_url(candidate, label=info.field_name or "URL")
        except ValueError as exc:
            raise ValueError(str(exc)) from exc
        return v

    @field_validator("docker_compose_dir")
    @classmethod
    def validate_docker_compose_dir(cls, v: str | None) -> str | None:
        """Keep the copy-and-paste update command free of shell injection (#2664).

        Validated on the write path only. Doing it on ``AppSettings`` as well
        would mean a single bad row — however it got there — 500s the entire
        settings GET and takes the app down with it, which is a worse outcome
        than rendering a string that has to be pasted into a shell by hand to
        do anything at all.
        """
        if v is None or not v.strip():
            return v
        candidate = v.strip()
        if len(candidate) > _COMPOSE_DIR_MAX_LEN:
            raise ValueError(f"Compose directory must be at most {_COMPOSE_DIR_MAX_LEN} characters")
        if not _COMPOSE_DIR_ALLOWED.match(candidate):
            raise ValueError(
                "Compose directory may only contain path characters (letters, digits, space, and - _ . / \\ : ~)"
            )
        # A trailing backslash is the one survivor that would still break the
        # frontend's double-quoting: `cd "/opt/bam buddy\"` escapes the closing
        # quote and swallows the rest of the line. Harmless (the shell just
        # waits for a terminator rather than running anything) but the user
        # would be left staring at a continuation prompt, so refuse it here
        # instead of shipping a command that cannot work.
        if candidate.endswith("\\"):
            raise ValueError("Compose directory must not end with a backslash")
        return candidate

    @field_validator("gcode_snippets")
    @classmethod
    def validate_gcode_snippets(cls, v: str | None) -> str | None:
        if v is None or v == "":
            return v
        try:
            parsed = json.loads(v)
        except json.JSONDecodeError:
            raise ValueError("gcode_snippets must be valid JSON or empty")
        if not isinstance(parsed, dict):
            raise ValueError("gcode_snippets must be a JSON object keyed by printer model")
        return v

    @field_validator("ldap_group_mapping")
    @classmethod
    def validate_ldap_group_mapping(cls, v: str | None) -> str | None:
        if v is None or v == "":
            return v
        try:
            parsed = json.loads(v)
        except json.JSONDecodeError:
            raise ValueError("ldap_group_mapping must be valid JSON or empty")
        if not isinstance(parsed, dict):
            raise ValueError("ldap_group_mapping must be a JSON object mapping LDAP group DNs to BamBuddy group names")
        return v

    @field_validator("obico_enabled_printers")
    @classmethod
    def validate_obico_enabled_printers(cls, v: str | None) -> str | None:
        if v is None or v == "":
            return v
        try:
            parsed = json.loads(v)
        except json.JSONDecodeError:
            raise ValueError("obico_enabled_printers must be valid JSON or empty")
        if not isinstance(parsed, list) or not all(isinstance(item, int) for item in parsed):
            raise ValueError("obico_enabled_printers must be a JSON array of printer IDs (integers)")
        return v

    @field_validator("bambuddy_internal_url")
    @classmethod
    def validate_bambuddy_internal_url(cls, v: str | None) -> str:
        """Require an absolute http(s) URL, or empty to fall back to External URL.

        Obico's ML server fetches snapshots from this address, so a value
        without a scheme ("bambuddy:8000") would only fail later, mid-print,
        as a snapshot error. Rejecting it here surfaces the mistake on save.

        An explicit null clears the field. The settings updater stores None
        as the literal "None", which would read back as an address.
        """
        candidate = (v or "").strip()
        if not candidate:
            return ""
        error = "bambuddy_internal_url must be a full http:// or https:// address"
        if any(ch.isspace() for ch in candidate):
            raise ValueError(error)
        try:
            parsed = urlparse(candidate)
            hostname = parsed.hostname
            _ = parsed.port  # raises on a port outside 0-65535
        except ValueError:
            raise ValueError(error) from None
        if parsed.scheme not in ("http", "https") or not hostname:
            raise ValueError(error)
        return candidate

    @staticmethod
    def _validate_preset_triple(v: str | None, field_name: str, lo: int, hi: int) -> str | None:
        """Validate a JSON array of exactly 3 ints in [lo, hi]. Empty = defaults."""
        if v is None or v == "":
            return v
        try:
            parsed = json.loads(v)
        except json.JSONDecodeError:
            raise ValueError(f"{field_name} must be valid JSON or empty")
        if not isinstance(parsed, list) or len(parsed) != 3:
            raise ValueError(f"{field_name} must be a JSON array of exactly 3 integers")
        if not all(isinstance(item, int) and not isinstance(item, bool) for item in parsed):
            raise ValueError(f"{field_name} entries must all be integers")
        if not all(lo <= item <= hi for item in parsed):
            raise ValueError(f"{field_name} entries must each be in [{lo}, {hi}]")
        return v

    @field_validator("nozzle_temp_presets")
    @classmethod
    def validate_nozzle_temp_presets(cls, v: str | None) -> str | None:
        return cls._validate_preset_triple(v, "nozzle_temp_presets", 0, 320)

    @field_validator("bed_temp_presets")
    @classmethod
    def validate_bed_temp_presets(cls, v: str | None) -> str | None:
        return cls._validate_preset_triple(v, "bed_temp_presets", 0, 140)

    @field_validator("chamber_temp_presets")
    @classmethod
    def validate_chamber_temp_presets(cls, v: str | None) -> str | None:
        return cls._validate_preset_triple(v, "chamber_temp_presets", 0, MAX_CHAMBER_TEMP_C)

    @field_validator("fan_speed_presets")
    @classmethod
    def validate_fan_speed_presets(cls, v: str | None) -> str | None:
        return cls._validate_preset_triple(v, "fan_speed_presets", 0, 100)

    @field_validator("obico_sensitivity")
    @classmethod
    def validate_obico_sensitivity(cls, v: str | None) -> str | None:
        if v is None:
            return v
        if v not in ("low", "medium", "high"):
            raise ValueError("obico_sensitivity must be 'low', 'medium', or 'high'")
        return v

    @field_validator("obico_action")
    @classmethod
    def validate_obico_action(cls, v: str | None) -> str | None:
        if v is None:
            return v
        if v not in ("notify", "pause", "pause_and_off"):
            raise ValueError("obico_action must be 'notify', 'pause', or 'pause_and_off'")
        return v

    @field_validator("default_sidebar_order")
    @classmethod
    def validate_default_sidebar_order(cls, v: str | None) -> str | None:
        if v is None or v == "":
            return v
        try:
            parsed = json.loads(v)
        except json.JSONDecodeError:
            raise ValueError("default_sidebar_order must be valid JSON or empty")
        if isinstance(parsed, dict):
            order = parsed.get("order")
            hidden_system_item_ids = parsed.get("hiddenSystemItemIds", [])
            if not isinstance(hidden_system_item_ids, list) or not all(
                isinstance(item, str) for item in hidden_system_item_ids
            ):
                raise ValueError("sidebar hidden system item IDs must be an array of strings")
        elif isinstance(parsed, list):
            order = parsed
        else:
            raise ValueError("default_sidebar_order must be a JSON object with 'order' key or a JSON array")
        if not isinstance(order, list) or not all(isinstance(item, str) for item in order):
            raise ValueError("sidebar order must be an array of strings")
        return v