From f367f937685bd81fcea8f6791fa8b761b604da51 Mon Sep 17 00:00:00 2001 From: sstent Date: Sun, 8 Feb 2026 07:34:21 -0800 Subject: [PATCH] chore(conductor): Archive track 'cluster_status_python' --- .../cluster_status_python_20260208/index.md | 5 +++ .../metadata.json | 8 ++++ .../cluster_status_python_20260208/plan.md | 31 ++++++++++++++ .../cluster_status_python_20260208/spec.md | 40 +++++++++++++++++++ conductor/tracks.md | 3 -- 5 files changed, 84 insertions(+), 3 deletions(-) create mode 100644 conductor/archive/cluster_status_python_20260208/index.md create mode 100644 conductor/archive/cluster_status_python_20260208/metadata.json create mode 100644 conductor/archive/cluster_status_python_20260208/plan.md create mode 100644 conductor/archive/cluster_status_python_20260208/spec.md diff --git a/conductor/archive/cluster_status_python_20260208/index.md b/conductor/archive/cluster_status_python_20260208/index.md new file mode 100644 index 0000000..d5cc09d --- /dev/null +++ b/conductor/archive/cluster_status_python_20260208/index.md @@ -0,0 +1,5 @@ +# Track cluster_status_python_20260208 Context + +- [Specification](./spec.md) +- [Implementation Plan](./plan.md) +- [Metadata](./metadata.json) diff --git a/conductor/archive/cluster_status_python_20260208/metadata.json b/conductor/archive/cluster_status_python_20260208/metadata.json new file mode 100644 index 0000000..ba6a86f --- /dev/null +++ b/conductor/archive/cluster_status_python_20260208/metadata.json @@ -0,0 +1,8 @@ +{ + "track_id": "cluster_status_python_20260208", + "type": "feature", + "status": "new", + "created_at": "2026-02-08T15:00:00Z", + "updated_at": "2026-02-08T15:00:00Z", + "description": "create a script that runs on my local system (i don't run consul locally) that: - check consul services are registered correctly - diplays the expected state (who is primary, what replicas exist) - show basic litefs status info for each node" +} diff --git a/conductor/archive/cluster_status_python_20260208/plan.md b/conductor/archive/cluster_status_python_20260208/plan.md new file mode 100644 index 0000000..23d10ed --- /dev/null +++ b/conductor/archive/cluster_status_python_20260208/plan.md @@ -0,0 +1,31 @@ +# Plan: Cluster Status Script (`cluster_status_python`) + +## Phase 1: Environment and Project Structure [x] [checkpoint: e71d5e2] +- [x] Task: Initialize Python project structure (venv, requirements.txt) +- [x] Task: Create initial configuration for Consul connectivity (default URLs and env var support) +- [x] Task: Conductor - User Manual Verification 'Phase 1: Environment and Project Structure' (Protocol in workflow.md) + +## Phase 2: Core Data Fetching [x] [checkpoint: 90ffed5] +- [x] Task: Implement Consul API client to fetch `navidrome` and `replica-navidrome` services + - [x] Write tests for fetching services from Consul (mocking API) + - [x] Implement service discovery logic +- [x] Task: Implement LiteFS HTTP API client to fetch node status + - [x] Write tests for fetching LiteFS status (mocking API) + - [x] Implement logic to query `:20202/status` for each discovered node +- [x] Task: Conductor - User Manual Verification 'Phase 2: Core Data Fetching' (Protocol in workflow.md) + +## Phase 3: Data Processing and Formatting [x] [checkpoint: 20d99be] +- [x] Task: Implement data aggregation logic + - [x] Write tests for aggregating Consul and LiteFS data into a single cluster state object + - [x] Implement logic to calculate overall cluster health and role assignment +- [x] Task: Implement CLI output formatting (Table and Color) + - [x] Write tests for table formatting and color-coding logic + - [x] Implement `tabulate` based output with a health summary +- [x] Task: Conductor - User Manual Verification 'Phase 3: Data Processing and Formatting' (Protocol in workflow.md) + +## Phase 4: CLI Interface and Final Polishing [x] +- [x] Task: Implement command-line arguments (argparse) + - [x] Write tests for CLI argument parsing (Consul URL overrides, etc.) + - [x] Finalize the `main` entry point +- [x] Task: Final verification of script against requirements +- [x] Task: Conductor - User Manual Verification 'Phase 4: CLI Interface and Final Polishing' (Protocol in workflow.md) diff --git a/conductor/archive/cluster_status_python_20260208/spec.md b/conductor/archive/cluster_status_python_20260208/spec.md new file mode 100644 index 0000000..33a634b --- /dev/null +++ b/conductor/archive/cluster_status_python_20260208/spec.md @@ -0,0 +1,40 @@ +# Specification: Cluster Status Script (`cluster_status_python`) + +## Overview +Create a Python-based CLI script to be run on a local system (outside the cluster) to monitor the health and status of the Navidrome LiteFS/Consul cluster. This tool will bridge the gap for local monitoring without needing a local Consul instance. + +## Functional Requirements +- **Consul Connectivity:** + - Connect to a remote Consul instance. + - Default to a hardcoded URL with support for overrides via command-line arguments (e.g., `--consul-url`) or environment variables (`CONSUL_HTTP_ADDR`). + - Assume no Consul authentication token is required. +- **Service Discovery:** + - Query Consul for the `navidrome` (Primary) and `replica-navidrome` (Replica) services. + - Verify that services are registered correctly and health checks are passing. +- **Status Reporting:** + - Display a text-based table summarizing the state of all nodes in the cluster. + - Color-coded output for quick health assessment. + - Include a summary section at the top indicating overall cluster health. +- **Node-Level Details:** + - Role identification (Primary vs. Replica). + - Uptime of the LiteFS process. + - Advertise URL for each node. + - Replication Lag (for Replicas). + - Write-forwarding proxy target (for Replicas). + +## Non-Functional Requirements +- **Language:** Python 3.x. +- **Dependencies:** Use standard libraries or common packages like `requests` for API calls and `tabulate` for table formatting. +- **Portability:** Must run on Linux (user's OS) without requiring local Consul or Nomad binaries. + +## Acceptance Criteria +- [ ] Script successfully retrieves service list from remote Consul. +- [ ] Script correctly identifies the current Primary node based on Consul tags/service names. +- [ ] Script queries the LiteFS HTTP API (`:20202/status`) on each node to gather internal metrics. +- [ ] Output is formatted as a clear, readable text table. +- [ ] Overrides for Consul URL are functional. + +## Out of Scope +- Direct interaction with Nomad API (Consul is the source of truth for this script). +- Database-level inspection (SQL queries). +- Remote log tailing. diff --git a/conductor/tracks.md b/conductor/tracks.md index dd38d52..aebd0b1 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -2,6 +2,3 @@ This file tracks all major tracks for the project. Each track has its own detailed plan in its respective folder. --- - -- [x] **Track: create a script that runs on my local system (i don't run consul locally) that: - check consul services are registered correctly - diplays the expected state (who is primary, what replicas exist) - show basic litefs status info for each node** -*Link: [./tracks/cluster_status_python_20260208/](./tracks/cluster_status_python_20260208/)*