Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 14 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,15 @@ when the model doesn't.
dudamel splits an assistant into two planes. The **command plane** is the
chat loop: a message comes in, the model picks tools to call, dudamel runs
them and feeds results back until it has an answer. The **data plane** —
the dashboard, widgets, scheduled jobs, database migrations — does not
depend on the model at all. If your LLM endpoint is down, the dashboard
still renders, because widgets are plain `async def` functions that read
the database directly; nothing about them calls the model, and the framework
enforces it — `app.llm()` raises inside a widget. To show model output, have a
job or tool compute it, store it, and let the widget read the stored result.
the dashboard, widgets, database migrations — does not depend on the model at
all. If your LLM endpoint is down, the dashboard still renders, because widgets
are plain `async def` functions that read the database directly; nothing about
them calls the model, and the framework enforces it — `app.llm()` raises inside
a widget. Scheduled jobs sit beside the data plane rather than in it: they run
without the chat loop but may call the model. If that call fails the job
records a failed run and the scheduler carries on, and the dashboard keeps
rendering whatever was last stored. To show model output, have a job or tool
compute it, store it, and let the widget read the stored result.

Apps are code, not configuration:

Expand Down Expand Up @@ -755,7 +758,11 @@ zone it actually resolved, which is how you confirm the key landed.
Leave it unset and dudamel uses the host's zone. That is what the scheduler has
always done — despite what earlier versions of this file said — so an existing
install's jobs keep firing at the same moment. `dudamel doctor` prints the zone
it resolved and whether it came from your config or from the host.
it resolved and whether it came from your config or from the host. If `$TZ` is
set in the shell you ran doctor from, the host zone comes from it and doctor
warns: the shipped service units do not set `$TZ`, so the service reads
`/etc/localtime` and may use a different zone. Pin `timezone` to remove the
doubt.

**Daylight saving.** A cron job scheduled inside the hour that repeats on a
fall-back day fires twice. One scheduled inside the hour that is skipped on a
Expand Down
18 changes: 5 additions & 13 deletions src/dudamel/app.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@

from pydantic import AliasChoices, AliasPath, BaseModel, ValidationError

from dudamel.config import to_zone
from dudamel.contract.renderers import ACTION_LABEL_MAX, RENDERERS, clean_action_label
from dudamel.contract.schema import ToolSchema
from dudamel.contract.types import TOOL_NAME_RE, Job, Tool, Widget
Expand Down Expand Up @@ -411,20 +412,11 @@ def in_timezone(self, value: datetime) -> datetime:
in Auckland is dated the previous day everywhere its raw stored value is
printed, which puts one card a day behind the rest of the homescreen.

The conversion is `value.replace(tzinfo=UTC).astimezone(zone)`: the
value is LABELLED UTC first, then moved. Calling `.astimezone(zone)`
straight on a naive value is the tempting one-liner and it is wrong --
Python reads a naive value in the PROCESS's zone, so that bug is
invisible on a UTC machine (CI, most containers) and wrong on every host
configured to a real location.

An already-aware value is moved without relabelling, so its instant
survives.
The conversion itself, and why a naive value must be labelled UTC before
it is moved, lives in `dudamel.config.to_zone`, shared with the
dashboard's pages. An already-aware value keeps its instant.
"""
zone = self.timezone
if value.tzinfo is None:
value = value.replace(tzinfo=UTC)
return value.astimezone(zone)
return to_zone(value, self.timezone)

def today(self) -> date:
"""The current date in the framework's zone.
Expand Down
17 changes: 14 additions & 3 deletions src/dudamel/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -546,17 +546,28 @@ def _check_web_token(settings: Settings) -> tuple[Status, str]:
return True, f"{settings.web.token_env} is set"


def _check_timezone(settings: Settings) -> tuple[bool, str]:
def _check_timezone(settings: Settings) -> tuple[Status, str]:
"""Report the RESOLVED framework zone and where it came from.

Always OK -- an unusable zone is rejected by validation long before this
runs. It is printed because unset means the host's zone, so the answer
OK unless the zone is the host's AND `$TZ` is set: tzlocal honours `$TZ`
over /etc/localtime, but the shipped systemd and launchd units do not set
it, so the running service may resolve a different zone than the one printed
here. That is a warning rather than a failure -- the service still runs, on
a zone the operator may not expect -- and pinning `timezone` removes the
ambiguity. An unusable zone is rejected by validation long before this runs.
It is printed because unset means the host's zone, so the answer
depends on /etc/localtime, and because a misspelled top-level key is dropped
in silence: this line is where an operator sees that `timezome` did nothing.
"""
zone = resolve_timezone(settings)
if timezone_source(settings) == "config":
return True, f"{zone} (from `timezone` in dudamel.toml)"
if os.environ.get("TZ"):
return "warn", (
f"{zone} (from $TZ in this shell; the service units do not set $TZ, "
"so the service may use a different zone -- set a top-level "
f'`timezone = "{zone}"` in dudamel.toml to pin it)'
)
return True, f"{zone} (from the host; set a top-level `timezone` to pin it)"


Expand Down
20 changes: 20 additions & 0 deletions src/dudamel/config.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
from __future__ import annotations

import tomllib
from datetime import UTC, datetime
from pathlib import Path
from typing import Any, Literal
from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
Expand Down Expand Up @@ -272,5 +273,24 @@ def resolve_timezone(settings: Settings) -> ZoneInfo:
return get_localzone()


def to_zone(value: datetime, zone: ZoneInfo) -> datetime:
"""A stored timestamp, as an aware datetime in `zone`. The one place that
conversion is spelled.

Columns defaulted from `now()` are stored NAIVE UTC, so a naive value is
LABELLED UTC first (`replace(tzinfo=UTC)`), then moved. Calling
`.astimezone(zone)` straight on a naive value is the tempting one-liner and
it is wrong -- Python reads a naive value in the PROCESS's zone, so that bug
is invisible on a UTC machine (CI, most containers) and wrong on every host
configured to a real location.

An already-aware value is moved without relabelling, so its instant
survives.
"""
if value.tzinfo is None:
value = value.replace(tzinfo=UTC)
return value.astimezone(zone)


def timezone_source(settings: Settings) -> str:
return "config" if settings.timezone is not None else "host"
9 changes: 2 additions & 7 deletions src/dudamel/web/ui.py
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,6 @@

from __future__ import annotations

from datetime import UTC
from pathlib import Path
from typing import Any
from zoneinfo import ZoneInfo
Expand All @@ -52,7 +51,7 @@
from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates

from dudamel.config import Settings
from dudamel.config import Settings, to_zone
from dudamel.runtime import Runtime
from dudamel.web.api import resolve_cookie_secure
from dudamel.web.auth import SessionStore, session_cookie_name
Expand All @@ -78,11 +77,7 @@ def _in_zone(
"""
converted: list[dict[str, Any]] = []
for row in rows:
moved = {
field: row[field].replace(tzinfo=UTC).astimezone(tz)
for field in fields
if row.get(field) is not None
}
moved = {field: to_zone(row[field], tz) for field in fields if row.get(field) is not None}
converted.append({**row, **moved} if moved else row)
return converted

Expand Down
44 changes: 43 additions & 1 deletion tests/test_cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -1138,7 +1138,11 @@ def _pin_host_zone(monkeypatch: pytest.MonkeyPatch, zone: str) -> None:

Never read the real host zone to build an expectation: CI runs on UTC
runners, where an implementation that simply printed `UTC` would pass every
assertion below while telling a Sao Paulo operator the wrong thing."""
assertion below while telling a Sao Paulo operator the wrong thing.

Also clears `$TZ`: doctor warns when the host zone came from it, and a
developer's shell may well export one."""
monkeypatch.delenv("TZ", raising=False)
monkeypatch.setattr("dudamel.config.get_localzone", lambda: ZoneInfo(zone))


Expand Down Expand Up @@ -1187,6 +1191,44 @@ def test_doctor_reports_the_host_zone_when_unset(
)


def test_doctor_warns_when_the_host_zone_came_from_tz(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
"""tzlocal honours `$TZ`, but the shipped systemd and launchd units do not
set it, so the service resolves /etc/localtime and can land on a different
zone than the one doctor just printed. That is a warning, not a failure: the
exit code stays 0."""
_pin_host_zone(monkeypatch, "Pacific/Auckland")
monkeypatch.setenv("TZ", "Pacific/Auckland")
target = scaffold(tmp_path)
monkeypatch.chdir(target)
capsys.readouterr() # drain `new`'s output

assert cli.main(["doctor"]) == 0
out = capsys.readouterr().out
assert (
"\u26a0 timezone: Pacific/Auckland (from $TZ in this shell; the service "
"units do not set $TZ, so the service may use a different zone -- set a "
'top-level `timezone = "Pacific/Auckland"` in dudamel.toml to pin it)' in out
)


def test_doctor_stays_ok_for_a_pinned_zone_even_with_tz_set(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
"""A pinned zone is what the service uses whatever `$TZ` says, so there is
nothing to warn about."""
monkeypatch.setenv("TZ", "America/Sao_Paulo")
target = scaffold(tmp_path)
_set_top_level(target, 'timezone = "Pacific/Auckland"\n')
monkeypatch.chdir(target)
capsys.readouterr() # drain `new`'s output

assert cli.main(["doctor"]) == 0
out = capsys.readouterr().out
assert "\u2713 timezone: Pacific/Auckland (from `timezone` in dudamel.toml)" in out


def _enable_suite_apps(target: Path, *names: str) -> None:
"""Switch on suite apps the way an operator does. These are section
headers, so unlike a top-level key they can safely be appended."""
Expand Down
27 changes: 20 additions & 7 deletions tests/test_mcp_reconnect.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,13 @@
process is `SIGKILL`ed out from under a live session, and the tool call
that trips over the corpse is expected to rebuild the connection.

Killing is done by pid, found with `pgrep` against a per-test server name,
rather than through the fixture's own `die()` tool. `die()` is itself a
tool call, so calling it would trigger the very reconnect the test is
trying to observe; an external kill leaves the mount believing it is still
healthy, which is the real-world shape of a server that crashes.
Killing is done by pid, found with `pgrep` against a per-test server name
and scoped to direct children of this pytest process (`pgrep -P`, so
concurrent runs cannot kill each other's servers), rather than through the
fixture's own `die()` tool. `die()` is itself a tool call, so calling it
would trigger the very reconnect the test is trying to observe; an
external kill leaves the mount believing it is still healthy, which is the
real-world shape of a server that crashes.

They spawn a real subprocess per `MCPMount`, same as `test_mcp_mount.py`.

Expand Down Expand Up @@ -250,8 +252,19 @@ async def test_flaky_fixture_advertises_all_five_tools_by_default(


def _pids(pattern: str) -> list[int]:
"""Pids whose full command line contains `pattern`, via `pgrep -f`."""
proc = subprocess.run(["pgrep", "-f", pattern], capture_output=True, text=True)
"""Pids of this process's own children whose command line contains `pattern`.

`pgrep -P <our pid>` restricts the search to direct children. A bare
`pgrep -f` searches the whole machine, so two pytest runs going at once
(two worktrees, a watcher beside a manual run) find each other's fixture
servers with the same name pattern and `SIGKILL` them mid-test; three
concurrent runs produced 25 spurious failures.
"""
proc = subprocess.run(
["pgrep", "-P", str(os.getpid()), "-f", pattern],
capture_output=True,
text=True,
)
return [int(line) for line in proc.stdout.split() if line.strip()]


Expand Down
Loading