flowtask 5.12.6__tar.gz → 5.12.8__tar.gz

{flowtask-5.12.6 → flowtask-5.12.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowtask
-Version: 5.12.6
+Version: 5.12.8
 Summary: Framework for Task orchestration
 Author-email: Jesus Lara <jesuslarag@gmail.com>
 License: Apache-2.0

{flowtask-5.12.6 → flowtask-5.12.8}/flowtask/conf.py

@@ -231,7 +231,7 @@ DEFAULT_EXECUTOR = config.get("DEFAULT_EXECUTOR", fallback="local")
 DOCKER_IMAGE = config.get("DOCKER_IMAGE", fallback="flowtask:latest")
 K8S_NAMESPACE = config.get("K8S_NAMESPACE", fallback="default")
 ALLOW_RESCHEDULE = config.getboolean("ALLOW_RESCHEDULE", fallback=False)
-SCHEDULER_STARTUP_JOB = config.getboolean("SCHEDULER_STARTUP_JOBS", fallback=False)
+SCHEDULER_STARTUP_JOB = config.getboolean("SCHEDULER_STARTUP_JOB", fallback=False)
 
 """
 Email Configuration
@@ -546,6 +546,22 @@ ZOOM_WEBHOOK_REPLAY_WINDOW_SECONDS = config.getint(
 )
 ZOOM_ALLOWED_CIDRS = config.get('ZOOM_ALLOWED_CIDRS', fallback='')
 
+## Maintenance / Status service (SOC2 CC8):
+# Master switch for the MaintenanceService (status + changelog + windows).
+MAINTENANCE_ENABLED = config.getboolean("MAINTENANCE_ENABLED", fallback=True)
+# Whether to email a summary of upcoming maintenance windows on startup.
+MAINTENANCE_NOTIFY_ON_STARTUP = config.getboolean(
+    "MAINTENANCE_NOTIFY_ON_STARTUP", fallback=True
+)
+# Recipient for maintenance-window notifications (falls back to DEFAULT_RECIPIENT).
+MAINTENANCE_NOTIFY_EMAIL = config.get("MAINTENANCE_NOTIFY_EMAIL", fallback=None)
+# Changelog source: a GitHub "owner/name" slug and/or a local CHANGELOG.md.
+MAINTENANCE_GITHUB_REPO = config.get("MAINTENANCE_GITHUB_REPO", fallback=None)
+MAINTENANCE_GITHUB_TOKEN = config.get("MAINTENANCE_GITHUB_TOKEN", fallback=None)
+MAINTENANCE_CHANGELOG_TITLE = config.get(
+    "MAINTENANCE_CHANGELOG_TITLE", fallback="What's New"
+)
+
 try:
     from navconfig.conf import *  # pylint: disable=W0401,W0614 # noqa
 except ImportError as e:

{flowtask-5.12.6 → flowtask-5.12.8}/flowtask/executors/docker.py

@@ -177,7 +177,7 @@ class DockerJobExecutor(AbstractJobExecutor):
             ExecutorConnectionError: If Docker daemon is unreachable.
             ExecutorError: If image pull or container creation fails.
         """
-        execution_id = task_id or str(uuid.uuid4())
+        execution_id = str(task_id) if task_id else str(uuid.uuid4())
         channel = f"FLOWTASK:EXEC:{execution_id}"
         container_name = self._container_name(program, task, execution_id)
 
@@ -244,7 +244,7 @@ class DockerJobExecutor(AbstractJobExecutor):
         Raises:
             ExecutorConnectionError: If Docker daemon is unreachable.
         """
-        execution_id = task_id or str(uuid.uuid4())
+        execution_id = str(task_id) if task_id else str(uuid.uuid4())
         container_name = self._container_name(program, task, execution_id)
         timeout = self._config.timeout
 

{flowtask-5.12.6 → flowtask-5.12.8}/flowtask/executors/k8s.py

@@ -214,7 +214,7 @@ class K8sJobExecutor(AbstractJobExecutor):
             ExecutorConnectionError: If the K8s cluster is unreachable.
             ExecutorError: If the Job cannot be created.
         """
-        execution_id = task_id or str(uuid.uuid4())
+        execution_id = str(task_id) if task_id else str(uuid.uuid4())
         channel = f"FLOWTASK:EXEC:{execution_id}"
         job_name = self._job_name(program, task, execution_id)
 
@@ -273,7 +273,7 @@ class K8sJobExecutor(AbstractJobExecutor):
         Raises:
             ExecutorConnectionError: If the K8s cluster is unreachable.
         """
-        execution_id = task_id or str(uuid.uuid4())
+        execution_id = str(task_id) if task_id else str(uuid.uuid4())
         job_name = self._job_name(program, task, execution_id)
         timeout = self._config.timeout
 

{flowtask-5.12.6 → flowtask-5.12.8}/flowtask/executors/local.py

@@ -132,7 +132,7 @@ class LocalJobExecutor(AbstractJobExecutor):
             program=program,
             **kwargs,
         )
-        execution_id = task_id  # always set by dispatch() / run() callers
+        execution_id = str(task_id) if task_id else str(uuid.uuid4())
 
         try:
             await task_obj.start()

{flowtask-5.12.6 → flowtask-5.12.8}/flowtask/executors/models.py

@@ -2,9 +2,10 @@
 #
 """Pydantic data models for the flowtask executor framework."""
 from __future__ import annotations
+import uuid
 from enum import Enum
 from typing import Any, Literal, Optional
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 
 
 class ExecutorType(str, Enum):
@@ -78,6 +79,19 @@ class ExecutionHandle(BaseModel):
     task_name: str
     channel: str
 
+    @field_validator("execution_id", mode="before")
+    @classmethod
+    def _coerce_execution_id(cls, value: Any) -> Any:
+        """Coerce UUID (or other non-str ids) into a string.
+
+        Callers frequently pass a ``uuid.UUID`` object as the execution id;
+        Pydantic's strict ``str`` validation would reject it. Normalise here so
+        the handle always carries a plain string.
+        """
+        if isinstance(value, uuid.UUID):
+            return str(value)
+        return value
+
 
 class TaskResult(BaseModel):
     """Result returned by run() when task execution completes.
@@ -95,3 +109,11 @@ class TaskResult(BaseModel):
     stats: Optional[Any] = None
     error: Optional[str] = None
     execution_id: Optional[str] = None
+
+    @field_validator("execution_id", mode="before")
+    @classmethod
+    def _coerce_execution_id(cls, value: Any) -> Any:
+        """Coerce UUID execution ids into a string (see ExecutionHandle)."""
+        if isinstance(value, uuid.UUID):
+            return str(value)
+        return value

{flowtask-5.12.6 → flowtask-5.12.8}/flowtask/executors/publish.py

@@ -118,7 +118,7 @@ class PublishJobExecutor(AbstractJobExecutor):
         Raises:
             ExecutorConnectionError: If Redis is unavailable.
         """
-        execution_id = task_id or str(uuid.uuid4())
+        execution_id = str(task_id) if task_id else str(uuid.uuid4())
         channel = f"FLOWTASK:EXEC:{execution_id}"
 
         await self._publisher.publish("dispatched", program, task, execution_id)
@@ -181,7 +181,7 @@ class PublishJobExecutor(AbstractJobExecutor):
         Raises:
             ExecutorConnectionError: If the initial Redis connection fails.
         """
-        execution_id = task_id or str(uuid.uuid4())
+        execution_id = str(task_id) if task_id else str(uuid.uuid4())
         result_channel = f"{RESULT_CHANNEL_PREFIX}:{execution_id}"
         timeout = self._config.timeout
 

{flowtask-5.12.6 → flowtask-5.12.8}/flowtask/executors/qworker.py

@@ -204,7 +204,7 @@ class QworkerJobExecutor(AbstractJobExecutor):
         Returns:
             An ExecutionHandle with the queue message result.
         """
-        execution_id = task_id or str(uuid.uuid4())
+        execution_id = str(task_id) if task_id else str(uuid.uuid4())
         priority: Optional[str] = kwargs.pop(
             "priority", self._config.priority
         )
@@ -266,7 +266,7 @@ class QworkerJobExecutor(AbstractJobExecutor):
         Returns:
             TaskResult with the worker's return value.
         """
-        execution_id = task_id or str(uuid.uuid4())
+        execution_id = str(task_id) if task_id else str(uuid.uuid4())
         priority: Optional[str] = kwargs.pop(
             "priority", self._config.priority
         )

{flowtask-5.12.6 → flowtask-5.12.8}/flowtask/interfaces/workday/handlers/custom_report.py

@@ -129,6 +129,22 @@ class CustomReportType(WorkdayTypeBase):
                 result[f"ID_{key}"] = values[0] if len(values) == 1 else values
             return result or None
 
+        # JSON RaaS shape: a list of dicts whose values are plain scalars, e.g.
+        # ``[{"Time_Entry_Codes": "A; B"}, {"Time_Entry_Codes": "C"}]``. Merge by
+        # key, joining repeated values with ``"; "`` so the multi-instance group
+        # collapses into a single flat string column.
+        if all(all(not isinstance(v, (dict, list)) for v in i.values()) for i in items):
+            result = {}
+            for item in items:
+                for key, value in item.items():
+                    if value is None:
+                        continue
+                    if key in result:
+                        result[key] = f"{result[key]}; {value}"
+                    else:
+                        result[key] = value
+            return result or None
+
         return None
 
     def _expand_list_dict_columns(self, df: pd.DataFrame, drop_original: bool) -> pd.DataFrame:
@@ -207,6 +223,37 @@ class CustomReportType(WorkdayTypeBase):
             self._logger.error(f"Error parsing XML response: {e}")
             raise
 
+    def _parse_json_to_entries(self, body: Any) -> List[Dict[str, Any]]:
+        """Extract ``Report_Entry`` rows from a RaaS JSON response.
+
+        Workday's ``?format=json`` RaaS output is already a list of flat dicts
+        (no namespace prefixes, no ``type``/``_value`` wrappers), so it feeds
+        straight into ``pd.json_normalize``. Multi-instance group columns arrive
+        as a list of dicts with scalar values, collapsed later by
+        :meth:`_list_of_dicts_to_dict` when ``flatten_list_dicts`` is set.
+
+        Args:
+            body: Parsed JSON payload (dict) or a raw JSON string/bytes.
+
+        Returns:
+            List of report-entry dicts (empty when none present).
+        """
+        import json as _json
+
+        if isinstance(body, (bytes, bytearray)):
+            body = body.decode("utf-8", errors="replace")
+        if isinstance(body, str):
+            body = _json.loads(body)
+
+        if isinstance(body, list):
+            return body
+        if isinstance(body, dict):
+            entries = body.get("Report_Entry", [])
+            if entries and not isinstance(entries, list):
+                entries = [entries]
+            return entries or []
+        return []
+
     def _build_raas_url(
         self,
         report_name: str,
@@ -317,12 +364,21 @@ class CustomReportType(WorkdayTypeBase):
             'flatten_list_dicts', 'drop_flattened_columns',
             'supervisory_organizations', 'supervisory_organizations_wid',
             'supervisory_organization_wid', 'include_subordinate_organizations',
-            'query_string_template'
+            'query_string_template', 'output_format'
         }
 
         offer_and_hire = self._coerce_bool(query_params.pop('offer_and_hire', False))
         flatten_list_dicts = self._coerce_bool(query_params.pop('flatten_list_dicts', False))
         drop_flattened_columns = self._coerce_bool(query_params.pop('drop_flattened_columns', False))
+        # Output format: 'xml' (default, legacy) or 'json'. JSON yields a cleaner
+        # shape for reports with nested multi-instance groups (no xmltodict
+        # cardinality split), at the cost of needing a flowtask that supports it.
+        output_format = str(query_params.pop('output_format', 'xml')).strip().lower()
+        if output_format not in ('xml', 'json'):
+            self._logger.warning(
+                "Unknown output_format '%s'; falling back to 'xml'", output_format
+            )
+            output_format = 'xml'
         report_path = query_params.pop('report_path', None)
         query_string_template = query_params.pop('query_string_template', None)
 
@@ -356,6 +412,10 @@ class CustomReportType(WorkdayTypeBase):
             if k not in internal_params
         }
 
+        # RaaS switches output via the ``format`` query param (default is XML).
+        if output_format == 'json' and 'format' not in filtered_params:
+            filtered_params['format'] = 'json'
+
         if offer_and_hire:
             self._logger.debug(
                 "offer_and_hire flag enabled: mapping start/end to Ready for Hire fields and adjusting path"
@@ -412,6 +472,8 @@ class CustomReportType(WorkdayTypeBase):
             # Build base URL without query params, then append template
             base_url = self._build_raas_url(report_name, report_owner, None, report_path)
             url = f"{base_url}?{query_string}"
+            if output_format == 'json' and 'format=' not in query_string:
+                url = f"{url}&format=json"
         else:
             # Use standard URL building with filtered_params
             url = self._build_raas_url(report_name, report_owner, filtered_params, report_path)
@@ -419,6 +481,8 @@ class CustomReportType(WorkdayTypeBase):
         self._logger.info(f"Executing custom report: {report_name}")
         self._logger.debug(f"RaaS URL: {url}")
 
+        accept_mime = "application/json" if output_format == "json" else "application/xml"
+
         # Initialize HTTP client if needed
         if self._http_client is None:
             # Get credentials from component
@@ -446,7 +510,7 @@ class CustomReportType(WorkdayTypeBase):
                     "password": password
                 },
                 auth_type="basic",
-                accept="application/xml",
+                accept=accept_mime,
                 timeout=120
             )
             # Set logger for HTTP client
@@ -457,7 +521,7 @@ class CustomReportType(WorkdayTypeBase):
             result, error = await self._http_client.async_request(
                 url=url,
                 method="GET",
-                accept="application/xml"
+                accept=accept_mime
             )
 
             if error:
@@ -472,15 +536,16 @@ class CustomReportType(WorkdayTypeBase):
             self._logger.error(f"Error executing custom report via REST: {exc}")
             raise
 
-        # Parse the XML response
-        # Convert to bytes for xmltodict
-        xml_bytes = result if isinstance(result, (bytes, bytearray)) else str(result).encode()
-
-        # Parse XML to list of dicts
-        raw_response = self._parse_xml_to_entries(xml_bytes)
+        # Parse the response into a list of report-entry dicts.
+        if output_format == "json":
+            raw_response = self._parse_json_to_entries(result)
+        else:
+            # Convert to bytes for xmltodict
+            xml_bytes = result if isinstance(result, (bytes, bytearray)) else str(result).encode()
+            raw_response = self._parse_xml_to_entries(xml_bytes)
 
         if not raw_response:
-            self._logger.warning("No report entries found in XML response")
+            self._logger.warning("No report entries found in %s response", output_format.upper())
             return pd.DataFrame()
 
         # Convert parsed XML (now as list of dicts) to DataFrame

flowtask-5.12.8/flowtask/interfaces/workday/rest.py

@@ -0,0 +1,217 @@
+"""Workday REST API client (``/ccx/api``).
+
+Minimal async client for Workday's REST surface, sharing :class:`WorkdayConfig`
+(credentials, tenant, prod/sandbox ``env`` selector) with the SOAP
+``WorkdayService``. Unlike the WSDL services — which have **no** operation to
+read raw time clock events — the REST API exposes them, echoing back the
+client-assigned ``Time_Clock_Event_ID`` as ``reference_ID`` and the effective
+``timeEntryCode`` applied to *In* events. That makes post-punch verification
+possible.
+
+Verified endpoints (Workday implementation tenant, 2026-07-03):
+
+- ``GET /ccx/api/v1/{tenant}/workers?search={text}`` — worker lookup; each row
+  carries ``id`` (the Workday WID) and ``descriptor``.
+- ``GET /ccx/api/timeTracking/v5/{tenant}/timeClockEvents?worker={WID}`` — raw
+  clock events. The ``worker`` parameter **requires a WID**; Employee_ID values
+  are rejected with ``400 "not found"``.
+
+Example::
+
+    from flowtask.interfaces.workday.config import WorkdayConfig
+    from flowtask.interfaces.workday.rest import WorkdayRestClient
+
+    client = WorkdayRestClient(config=WorkdayConfig(env="sandbox"))
+    workers = await client.find_worker("123456")
+    events = await client.get_time_clock_events(workers[0]["id"])
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import time as _time
+from typing import Any, Optional
+
+import httpx
+
+from flowtask.interfaces.workday.config import WorkdayConfig
+
+
+class WorkdayRestClient:
+    """Async client for Workday's ``/ccx/api`` REST endpoints.
+
+    Uses the same OAuth *refresh-token* grant as ``SOAPClient`` (no Redis
+    dependency — the bearer token is cached in-memory until shortly before
+    expiry). Host and credentials come from :class:`WorkdayConfig`, so the
+    ``WORKDAY_ENV`` prod/sandbox selector applies here too.
+
+    Args:
+        config: Explicit credentials / tenant. ``None`` → ``WorkdayConfig()``
+            (conf fallbacks + ``WORKDAY_ENV``).
+        timeout: HTTP timeout in seconds (default 30).
+        time_tracking_version: REST version segment for the timeTracking
+            service (default ``"v5"`` — the version available on this tenant;
+            ``v6`` returned 400 when probed).
+    """
+
+    def __init__(
+        self,
+        *,
+        config: WorkdayConfig | None = None,
+        timeout: int = 30,
+        time_tracking_version: str = "v5",
+    ) -> None:
+        self.config = config or WorkdayConfig()
+        self.timeout = timeout
+        self.time_tracking_version = time_tracking_version
+        self._token: Optional[str] = None
+        self._token_expires_at: float = 0.0
+        self._logger = logging.getLogger("flowtask.workday.rest")
+
+    # ------------------------------------------------------------------
+    # Auth
+    # ------------------------------------------------------------------
+
+    @property
+    def base_url(self) -> str:
+        """REST base: ``{workday_url}/ccx/api`` (env-aware host)."""
+        return f"{self.config.workday_url.rstrip('/')}/ccx/api"
+
+    def set_token(self, token: str, expires_in: int = 300) -> None:
+        """Reuse an externally obtained bearer token (e.g. from the SOAP flow).
+
+        Args:
+            token: A valid Workday OAuth access token.
+            expires_in: Seconds the token remains valid (default 300).
+        """
+        self._token = token
+        self._token_expires_at = _time.monotonic() + max(expires_in - 10, 0)
+
+    async def get_token(self) -> str:
+        """Return a cached bearer token, refreshing via OAuth when expired.
+
+        Performs the same ``refresh_token`` grant as ``SOAPClient`` (Basic auth
+        with client_id/client_secret against ``token_url``).
+
+        Returns:
+            A valid access token.
+        """
+        if self._token and _time.monotonic() < self._token_expires_at:
+            return self._token
+
+        cid = self.config.resolved_client_id
+        secret = self.config.resolved_client_secret
+        basic = base64.b64encode(f"{cid}:{secret}".encode()).decode()
+        async with httpx.AsyncClient(timeout=self.timeout) as http:
+            resp = await http.post(
+                self.config.resolved_token_url,
+                data={
+                    "grant_type": "refresh_token",
+                    "refresh_token": self.config.resolved_refresh_token,
+                },
+                headers={
+                    "Authorization": f"Basic {basic}",
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+            )
+            resp.raise_for_status()
+            payload = resp.json()
+
+        self.set_token(payload["access_token"], int(payload.get("expires_in", 300)))
+        self._logger.debug("Workday REST token refreshed (env=%s)", self.config.resolved_env)
+        return self._token  # type: ignore[return-value]
+
+    # ------------------------------------------------------------------
+    # Core GET
+    # ------------------------------------------------------------------
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> dict:
+        """Perform an authenticated GET against ``{base_url}{path}``.
+
+        Args:
+            path: Path below ``/ccx/api`` (must start with ``/``).
+            params: Optional query parameters.
+
+        Returns:
+            The parsed JSON body.
+
+        Raises:
+            httpx.HTTPStatusError: on non-2xx responses.
+        """
+        token = await self.get_token()
+        url = f"{self.base_url}{path}"
+        async with httpx.AsyncClient(timeout=self.timeout) as http:
+            resp = await http.get(
+                url,
+                params=params or {},
+                headers={"Authorization": f"Bearer {token}"},
+            )
+            resp.raise_for_status()
+            return resp.json()
+
+    # ------------------------------------------------------------------
+    # Endpoints
+    # ------------------------------------------------------------------
+
+    async def find_worker(self, search: str, *, limit: int = 20) -> list[dict]:
+        """Search workers; each result carries ``id`` (WID) and ``descriptor``.
+
+        Args:
+            search: Free-text search (name; associate/employee id support is
+                tenant-dependent — verify before relying on it).
+            limit: Max results (default 20).
+
+        Returns:
+            List of worker dicts (empty when no match).
+        """
+        payload = await self.get(
+            f"/v1/{self.config.tenant}/workers",
+            {"search": search, "limit": limit},
+        )
+        return payload.get("data", [])
+
+    async def get_time_clock_events(
+        self, worker_wid: str, *, limit: int = 100
+    ) -> list[dict]:
+        """Return the raw time clock events of a worker.
+
+        Each event carries ``reference_ID`` (the client-assigned
+        ``Time_Clock_Event_ID`` when the event was created via
+        ``Put_Time_Clock_Events``), ``dateTime`` (UTC ISO), ``eventType``,
+        ``comment``, ``timeZone``, and — on *In* events of time-tracking
+        eligible workers — the effective ``timeEntryCode``.
+
+        Args:
+            worker_wid: The worker's Workday WID (NOT an Employee_ID — the
+                REST API rejects those).
+            limit: Max events returned (default 100).
+
+        Returns:
+            List of event dicts (empty when the worker has none).
+        """
+        payload = await self.get(
+            f"/timeTracking/{self.time_tracking_version}/{self.config.tenant}/timeClockEvents",
+            {"worker": worker_wid, "limit": limit},
+        )
+        return payload.get("data", [])
+
+    async def find_time_clock_event(
+        self, worker_wid: str, reference_id: str
+    ) -> dict | None:
+        """Locate one clock event by its client-assigned ``reference_ID``.
+
+        Convenience for punch verification: after ``Put_Time_Clock_Events``
+        succeeds, the event is visible here within ~1 s (verified live).
+
+        Args:
+            worker_wid: The worker's Workday WID.
+            reference_id: The ``Time_Clock_Event_ID`` sent on the Put.
+
+        Returns:
+            The matching event dict, or ``None`` when not (yet) present.
+        """
+        for event in await self.get_time_clock_events(worker_wid):
+            if event.get("reference_ID") == reference_id:
+                return event
+        return None

{flowtask-5.12.6 → flowtask-5.12.8}/flowtask/scheduler/scheduler.py

@@ -439,7 +439,9 @@ class NavScheduler:
         return self._loop
 
     def set_test_job(self):
-        self.logger.debug("Scheduler: Adding a Test job")
+        self.logger.debug(
+            "Scheduler: Adding a Test job"
+        )
         run_date = datetime.now(self._timezone) + timedelta(minutes=1)
         # define Task:
         program = "navigator"
@@ -478,6 +480,7 @@ class NavScheduler:
                 f"[{ENVIRONMENT} - Scheduler] Error getting Jobs: {error!s}"
             )
         # Add a Job for testing purposes.
+        print('HERE > ', SCHEDULER_STARTUP_JOB)
         if SCHEDULER_STARTUP_JOB is True:
             self.set_test_job()
         for job in jobs:

{flowtask-5.12.6 → flowtask-5.12.8}/flowtask/services/files/service.py

@@ -664,7 +664,7 @@ class FileService(BaseView):
                     program_slug = filedef.program_slug
                     try:
                         # loop = asyncio.new_event_loop()
-                        task_uuid = uuid.uuid4()
+                        task_uuid = str(uuid.uuid4())
                         if not filedef.params:
                             params = {}
                         else:

flowtask-5.12.8/flowtask/services/maintenance/README.md

@@ -0,0 +1,80 @@
+# Flowtask Maintenance / Status Service
+
+SOC2 **CC8 (change management)** support for Flowtask running in aiohttp
+**server mode**. It exposes three surfaces:
+
+| Surface | What it does |
+|---------|--------------|
+| **Status page** | Reports server liveness, the startup-job outcome and the availability of the `/api/v2/task` and `/api/v2/scheduler` APIs. Failures are persisted (Redis, in-memory fallback) for auditing. |
+| **Changelog page** | End-user "What's New" page built from `CHANGELOG.md` or GitHub Releases and served as HTML. |
+| **Maintenance windows** | Register a window (day + hour range) over HTTP; upcoming windows are shown on the status page and emailed on startup via `async-notify`. |
+
+## Wiring it up
+
+Inside a Navigator `AppHandler.configure()` (already done in `app.py`):
+
+```python
+from flowtask.services.maintenance import MaintenanceService
+
+maintenance = MaintenanceService()
+maintenance.setup(self.app)
+```
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/status` | HTML status page |
+| GET | `/changelog` | HTML "What's New" page |
+| GET | `/api/v2/maintenance/status` | JSON status (HTTP 503 when unhealthy) |
+| GET | `/api/v2/maintenance/failures?limit=` | Recent recorded failures |
+| GET | `/api/v2/maintenance/changelog` | Changelog as JSON |
+| GET | `/api/v2/maintenance/windows?upcoming=true` | List maintenance windows |
+| POST | `/api/v2/maintenance/windows` | Register a window |
+| DELETE | `/api/v2/maintenance/windows/{identifier}` | Remove a window |
+
+### Registering a maintenance window
+
+```bash
+curl -X POST http://localhost:8080/api/v2/maintenance/windows \
+  -H 'Content-Type: application/json' \
+  -d '{
+        "title": "Planned DB upgrade",
+        "day": "2030-05-01",
+        "start_time": "02:00",
+        "end_time": "04:00",
+        "description": "Rolling restart",
+        "notify": true
+      }'
+```
+
+## Reporting a startup job outcome
+
+Any component can flag whether its on-startup work succeeded; the result shows
+up in the `startup_job` status probe:
+
+```python
+service = app["flowtask_maintenance"]
+await service.mark_startup("my_loader", ok=True, detail="warmed cache")
+```
+
+The scheduler installed at `app["_scheduler_"]` is always considered as a
+startup signal automatically, so a stalled scheduler surfaces even when no
+other startup jobs are recorded.
+
+## Configuration (`flowtask/conf.py` / environment)
+
+| Setting | Default | Purpose |
+|---------|---------|---------|
+| `MAINTENANCE_ENABLED` | `True` | Master switch |
+| `MAINTENANCE_NOTIFY_ON_STARTUP` | `True` | Email upcoming windows on startup |
+| `MAINTENANCE_NOTIFY_EMAIL` | `DEFAULT_RECIPIENT` | Notification recipient |
+| `MAINTENANCE_GITHUB_REPO` | `None` | `owner/name` for GitHub-sourced changelog |
+| `MAINTENANCE_GITHUB_TOKEN` | `None` | Optional token for the GitHub source |
+| `MAINTENANCE_CHANGELOG_TITLE` | `What's New` | Changelog page heading |
+| `REDIS_URL` | — | Store backend (falls back to in-memory) |
+| `EMAIL_HOST` / `EMAIL_PORT` / `EMAIL_USERNAME` / `EMAIL_PASSWORD` | — | SMTP account for notifications |
+
+Redis is optional: if it is unreachable the store degrades to an in-process
+fallback and flags itself (`degraded_store` in the failures endpoint) instead of
+taking the server down.