Z2M Wrapper Backend

Backend service exposing configuration, restart controls, and status streaming for the Z2M Wrapper UI.

1. Copy .env.example to .env and set APP_TABS_CONFIG, APP_AUTH_TOKEN, network bindings, and FLASK_ENV (development or production). Optionally override APP_AUTH_COOKIE_NAME, APP_SECRET_KEY, and APP_SSE_HEARTBEAT_SECONDS (defaults: 5 seconds in development, 30 seconds otherwise).
2. Install dependencies and run:

poetry install
poetry run dev

In production mode (FLASK_ENV=production) the service is served by Waitress; development mode keeps the Flask reloader/debugger enabled.

All endpoints are served under /api and return JSON unless noted otherwise.

• Description: Exchanges a shared secret token for a long-lived (≈10 year) signed authentication cookie (HttpOnly, SameSite=None, Partitioned; Secure is added automatically when FLASK_ENV=production).
• Request body:

  {"token": "<APP_AUTH_TOKEN>"}

• Response:

  {"authenticated": true, "disabled": false}

  Includes Set-Cookie headers for the auth cookie. Returns 403 Forbidden when the token does not match APP_AUTH_TOKEN. The JWT payload intentionally omits an expiry claim; the cookie remains valid until you revoke it (e.g. by rotating the shared secret).

• Description: Probe endpoint used by NGINX auth_request or health checks. Returns 200 OK when the authentication cookie is valid, 403 Forbidden otherwise. When APP_AUTH_DISABLED=1, always returns success with { "disabled": true }.

• Auth: Requires a valid authentication cookie.
• Description: Fetches the tab configuration that the frontend should render.
• Response:

  {
    "tabs": [
      {
        "text": "Primary Dashboard",
        "iconUrl": "https://example.com/icon.svg",
        "iframeUrl": "https://example.com/dashboard",
        "restartable": false
      }
    ]
  }

• Status codes: 200 OK on success.

• Auth: Requires a valid authentication cookie and a restartable tab.
• Description: Triggers an optimistic restart for the tab at index <idx> when it has Kubernetes metadata.
• Response:

  {
    "status": "restarting",
    "message": null
  }

• Status codes:
  • 200 OK when the restart request is accepted.
  • 400 Bad Request if the tab is not restartable.
  • 404 Not Found if the index is out of range.
  • 409 Conflict if a restart for the deployment is already in progress.
  • 500 Internal Server Error for unexpected Kubernetes or configuration issues.

• Auth: Requires a valid authentication cookie.
• Description: Server-Sent Events stream that emits status updates for tab <idx>, interleaved with lightweight event: heartbeat frames when no state changes occur.
• Usage: Subscribe via an EventSource in the browser or any SSE-capable client. Example event payload:

  retry: 3000
  event: status
  data: {"state": "running", "message": null}
  
  

• Initial behaviour: The latest known state (running, restarting, or error) is sent immediately upon connection.
• Heartbeat: The backend sends event: heartbeat frames every APP_SSE_HEARTBEAT_SECONDS (default 5/30 seconds) so intermediaries such as Waitress can notice disconnected clients.