navidrome-litefs/conductor/tracks/fix_routing_20260207/spec.md

Specification: Direct Primary Routing for Navidrome-LiteFS

Overview

This track aims to fix routing issues caused by the LiteFS proxy. We will reconfigure the Nomad service registration to point directly to the Navidrome process (port 4533) on the primary node, bypassing the LiteFS write-forwarding proxy (port 8080). To ensure Traefik only routes traffic to the node capable of writes, we will implement a "Primary-only" health check.

Functional Requirements

• Direct Port Mapping: Update the Nomad service block to use the host port 4533 directly instead of the LiteFS proxy port.
• Primary-Aware Health Check: Replace the standard HTTP health check with a script check.
• Check Logic: The script will execute litefs is-primary.
  • If the node is the primary, the command exits with 0 (Passing).
  • If the node is a replica, the command exits with a non-zero code (Critical).
• Service Tags: Retain all existing Traefik tags so ingress routing continues to work.

Non-Functional Requirements

• Failover Reliability: In the event of a leader election, the old primary must become unhealthy and the new primary must become healthy in Consul, allowing Traefik to update its backends automatically.
• Minimal Latency: Bypassing the proxy eliminates the extra network hop for reads and potential compatibility issues with Navidrome's connection handling.

Acceptance Criteria

• Consul reports the service as passing only on the node currently holding the LiteFS primary lease.
• Consul reports the service as critical on all replica nodes.
• Traefik correctly routes traffic to the primary node.
• Navidrome is accessible and functions correctly without the LiteFS proxy intermediary.

Out of Scope

• Modifying Navidrome internal logic.
• Implementing an external health-check responder.