Skip to content

refactor(cli): add supervisor control and process adapters#504

Open
xiami762 wants to merge 30 commits into
devfrom
refactor/supervisor-control-adapters
Open

refactor(cli): add supervisor control and process adapters#504
xiami762 wants to merge 30 commits into
devfrom
refactor/supervisor-control-adapters

Conversation

@xiami762

@xiami762 xiami762 commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Refactor local service lifecycle management around a supervisor daemon, typed control API, and backend/WebUI process adapters.
  • This addresses cases where backend or WebUI child services become unavailable while the parent supervisor is still running, and keeps CLI/updater lifecycle operations on one control path.

Key Changes

  • Added supervisor daemon lifecycle management for backend and WebUI child process groups.
  • Added backend health recovery for process exit, lost listener port, and repeated /api/health failures.
  • Added WebUI recovery for process exit and lost listener port.
  • Added flocks/cli/service_control.py typed control operations for status, stop, restart, WebUI stop/restart, and logs.
  • Added flocks/cli/service_config.py as the single owner for service config defaults, CLI/env merge, and control payload serialization.
  • Added flocks/cli/service_process.py backend/WebUI process adapters so supervisor policy is separated from process start/stop/probe implementation.
  • Updated updater handoff/recovery to use supervisor control operations instead of raw endpoint/payload calls.
  • Removed public raw read_control_json / post_control_json usage from CLI/updater callers.

Impact Scope

  • User-visible behavior: flocks start/status/stop/restart/logs now operate through the supervisor control plane. Backend and WebUI are restarted by the supervisor when they exit or lose their listener.
  • Compatibility / migration: existing backend/WebUI log paths are preserved. Legacy runtime records are only used for one-time cleanup during supervisor startup.
  • Configuration / environment: no new required environment variables. Existing host/port CLI options remain supported.
  • Dependencies: no new third-party dependencies.
  • Performance / resources: adds periodic supervisor health probes with short socket and health-check requests.
  • Security / permissions: control API remains local-only through Unix domain socket on Unix/macOS and loopback TCP on Windows.

Business Logic to Review

  • flocks/cli/service_supervisor.py: restart policy, pause behavior for upgrade handoff, health failure threshold, and process-group shutdown ordering.
  • flocks/cli/service_control.py: typed control API mapping and status parsing.
  • flocks/cli/service_config.py: config serialization/deserialization and CLI/env/default precedence.
  • flocks/cli/service_process.py: backend/WebUI probe semantics for process exit, listener loss, and backend /api/health failures.
  • flocks/updater/updater.py: WebUI stop/restart during upgrade handoff and rollback recovery.

Why This Approach

  • The supervisor daemon becomes the single owner of service lifecycle policy.
  • The CLI and updater no longer need to know raw control endpoints, payload shapes, or status keys.
  • Backend/WebUI process details live behind adapters, keeping restart/backoff policy separate from platform/process implementation.

Test Plan

  • uv run pytest tests/updater/test_updater.py tests/cli/test_service_manager.py tests/cli/test_service_commands.py
  • uv run ruff check flocks/cli/service_config.py flocks/cli/service_control.py flocks/cli/service_process.py flocks/cli/service_supervisor.py flocks/cli/service_manager.py flocks/cli/main.py flocks/updater/updater.py tests/cli/test_service_manager.py tests/cli/test_service_commands.py tests/updater/test_updater.py
  • git diff --check

Compatibility, Migration & Rollback

  • No migration is required for normal users.
  • Rollback is to revert this PR and return CLI service management to the previous lifecycle implementation.
  • Existing logs remain under the same backend/WebUI paths, with supervisor logs kept separately.

xiami762 added 30 commits July 1, 2026 17:09
…ters' into refactor/supervisor-control-adapters
…ntrol-adapters

# Conflicts:
#	flocks/storage/storage.py
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant