Merge pull request #1097 from LibreQoE/fix_207

rchac · web-flow · commit d50cb8544d5f · 2026-05-30T00:04:37.000-06:00
changes
diff --git a/docs-es/v2.0/configuration-advanced-es.md b/docs-es/v2.0/configuration-advanced-es.md
@@ -73,6 +73,17 @@ Si el modo integración está habilitado, los ciclos de refresco suelen ser due
 - Use edición manual/WebUI para ajustes operativos temporales.
 - Mantenga cambios permanentes en el sistema de integración, overrides de integración o flujo externo declarado.
 
+### Modo de compilación de topología para archivos DIY/manuales
+
+Para despliegues DIY/manuales que mantienen `network.json` y `ShapedDevices.csv`, use un modo que conserve jerarquía cuando los circuitos deban moldearse bajo los nombres `Parent Node` de `network.json`:
+
+```toml
+[topology]
+compile_mode = "full"
+```
+
+Use `compile_mode = "flat"` solo cuando la jerarquía no forme parte del plan de shaping. En modo flat, LibreQoS asigna los circuitos a colas generadas por CPU, como `Generated_PN_1`; el `Parent Node` original queda como referencia lógica, pero el padre efectivo de shaping en `shaping_inputs.json` será una cola generada con `resolution_source: "flat_bucket"`.
+
 ### Overrides en runtime (`lqos_overrides.json`)
 
 LibreQoS también permite ajustes de runtime mediante `lqos_overrides.json` en el `lqos_directory`.
diff --git a/docs-es/v2.0/operating-modes-es.md b/docs-es/v2.0/operating-modes-es.md
@@ -26,6 +26,8 @@ Comportamiento clave:
 - Su flujo externo es donde deben hacerse los cambios permanentes.
 - Las ediciones por WebUI son válidas para cambios operativos rápidos.
 - Mantenga los cambios de largo plazo en sus scripts o automatización.
+- Use `topology.compile_mode = "full"` cuando los valores `Parent Node` de `ShapedDevices.csv` deban moldear bajo la jerarquía nombrada en `network.json`.
+- Use `flat` solo cuando las colas generadas por CPU, como `Generated_PN_1`, sean la topología de colas deseada.
 
 ## Modo archivos manuales
 
@@ -35,6 +37,8 @@ Comportamiento clave:
 - Es más adecuado para redes pequeñas, pilotos cortos o soluciones temporales.
 - La WebUI le ayuda a validar lo que LibreQoS está usando.
 - Requiere disciplina manual porque no hay un sistema superior que mantenga esos archivos sincronizados.
+- Use `topology.compile_mode = "full"` cuando el shaping por padres superiores, AP o Sitio deba seguir `network.json`.
+- Si `shaping_inputs.json` muestra `resolution_source: "flat_bucket"`, LibreQoS está en modo flat y los circuitos mostrarán colas padre generadas en vez de los nombres de `network.json`.
 
 ## Lista de verificación de modo (antes de producción)
 
diff --git a/docs-es/v2.0/quickstart-es.md b/docs-es/v2.0/quickstart-es.md
@@ -107,7 +107,10 @@ Elija esta opción solo si otro proceso interno ya escribe archivos compatibles
 Haga esto ahora:
 1. Configure el comportamiento compartido de topología en `Integration - Common`.
 2. Publique `network.json` y `ShapedDevices.csv` desde su propio proceso.
-3. Recargue o espere al scheduler para que LibreQoS valide y use esos archivos.
+3. Use `topology.compile_mode = "full"` si los circuitos deben moldearse bajo la jerarquía nombrada por `Parent Node` en `network.json`.
+4. Recargue o espere al scheduler para que LibreQoS valide y use esos archivos.
+
+No use `topology.compile_mode = "flat"` si espera que los valores `Parent Node` de `ShapedDevices.csv` creen colas superiores de shaping. En modo flat, LibreQoS asigna intencionalmente los circuitos a colas generadas por CPU, como `Generated_PN_1`.
 
 Siguiente:
 - [Modos de operación y fuente de verdad](operating-modes-es.md)
@@ -120,8 +123,11 @@ Elija esta opción solo si quiere que LibreQoS mantenga directamente esos archiv
 Haga esto ahora:
 1. Construya `network.json`.
 2. Construya `ShapedDevices.csv`.
-3. Manténgalos con los editores de WebUI o con su flujo basado en archivos.
-4. Confirme que el scheduler acepta los datos y que aparece la topología esperada.
+3. Configure `topology.compile_mode = "full"` si la columna `Parent Node` debe moldear bajo los nodos nombrados en `network.json`.
+4. Manténgalos con los editores de WebUI o con su flujo basado en archivos.
+5. Confirme que el scheduler acepta los datos y que aparece la topología esperada.
+
+Use `flat` solo cuando quiera colas generadas por CPU en vez de colas padre basadas en jerarquía.
 
 Siguiente:
 - [Referencia avanzada de configuración](configuration-advanced-es.md)
diff --git a/docs-es/v2.0/troubleshooting-es.md b/docs-es/v2.0/troubleshooting-es.md
@@ -216,6 +216,25 @@ journalctl -u lqosd --since "10 minutes ago"
 
 Si sigue en blanco con tráfico normal, recolecte logs y abra issue.
 
+### Los circuitos muestran Generated_PN en vez de nombres de network.json
+
+Si un despliegue DIY/manual usa `network.json` y `ShapedDevices.csv`, pero la página de Circuitos muestra padres como `Generated_PN_1`, revise las entradas de shaping runtime:
+
+```bash
+jq '.circuits[] | {circuit_id, logical_parent_node_name, effective_parent_node_name, resolution_source}' /opt/libreqos/state/shaping/shaping_inputs.json
+```
+
+Si `resolution_source` es `flat_bucket`, LibreQoS está en modo de topología flat. Ese modo asigna intencionalmente los circuitos a colas generadas por CPU en vez de moldearlos bajo la jerarquía nombrada por `Parent Node`.
+
+Para moldear circuitos bajo los nombres de nodo de `network.json`, configure:
+
+```toml
+[topology]
+compile_mode = "full"
+```
+
+Después recargue o espere al scheduler para regenerar `network.effective.json` y `shaping_inputs.json`.
+
 ### Colisión de promoción de nodo virtual (`network.json`)
 
 Si `LibreQoS.py` falla con `Virtual node promotion collision: 'AP_A' already exists at this level.`, hay un nodo con `"virtual": true` cuyos hijos colisionan por nombre al promoverse.
diff --git a/docs/v2.0/configuration-advanced.md b/docs/v2.0/configuration-advanced.md
@@ -88,6 +88,17 @@ If built-in integration mode is enabled, the integration and topology compiler o
 - Use WebUI/manual edits for short operational adjustments only.
 - Put permanent changes in your integration system, integration overrides, or declared external source of truth workflow.
 
+#### Topology compile mode for DIY/manual files
+
+For DIY/manual deployments that maintain `network.json` and `ShapedDevices.csv`, use a hierarchy-preserving mode when circuits should shape under the `Parent Node` names from `network.json`:
+
+```toml
+[topology]
+compile_mode = "full"
+```
+
+Use `compile_mode = "flat"` only when hierarchy is not part of the shaping plan. In flat mode, LibreQoS assigns circuits to generated CPU bucket queues such as `Generated_PN_1`; the original `Parent Node` remains a logical reference, but the effective shaping parent in `shaping_inputs.json` will be a generated bucket with `resolution_source: "flat_bucket"`.
+
 #### Static queue visibility policy
 
 Current builds separate logical topology from queue-visible topology.
diff --git a/docs/v2.0/operating-modes.md b/docs/v2.0/operating-modes.md
@@ -43,6 +43,8 @@ Key behavior:
 - Your external workflow is where permanent changes belong.
 - WebUI edits are fine for quick operational changes.
 - Keep your long-term changes in your own scripts or automation.
+- Use `topology.compile_mode = "full"` when the `Parent Node` values in `ShapedDevices.csv` should shape under the named hierarchy in `network.json`.
+- Use `flat` only when generated CPU bucket queues such as `Generated_PN_1` are the intended queue layout.
 
 ## Manual Files Mode
 
@@ -52,6 +54,8 @@ Key behavior:
 - Best fit for small networks, short pilots, or temporary workarounds.
 - WebUI helps you validate what LibreQoS is using.
 - Manual discipline matters because there is no upstream system keeping those files in sync for you.
+- Use `topology.compile_mode = "full"` when top-level or AP/Site parent shaping should follow `network.json`.
+- If `shaping_inputs.json` shows `resolution_source: "flat_bucket"`, LibreQoS is in flat mode and circuits will show generated parent queues instead of the names from `network.json`.
 
 ## Mode Declaration Checklist (Before Go-Live)
 
diff --git a/docs/v2.0/quickstart.md b/docs/v2.0/quickstart.md
@@ -102,7 +102,10 @@ Choose this only if another internal process already writes LibreQoS-compatible
 Do this now:
 1. Configure shared topology behavior under `Integration - Common`.
 2. Publish `network.json` and `ShapedDevices.csv` from your own process.
-3. Reload or wait for the scheduler so LibreQoS can validate and use those files.
+3. Use `topology.compile_mode = "full"` if circuits should shape under the named `Parent Node` hierarchy from `network.json`.
+4. Reload or wait for the scheduler so LibreQoS can validate and use those files.
+
+Do not use `topology.compile_mode = "flat"` when you expect `Parent Node` values from `ShapedDevices.csv` to create top-level shaping queues. In flat mode, LibreQoS intentionally assigns circuits to generated CPU bucket queues such as `Generated_PN_1`.
 
 Next:
 - [Operating Modes and Source of Truth](operating-modes.md)
@@ -115,8 +118,11 @@ Choose this only if you intentionally want LibreQoS to own the files directly.
 Do this now:
 1. Build `network.json`.
 2. Build `ShapedDevices.csv`.
-3. Use the WebUI editors or file-based workflow to maintain them.
-4. Confirm the scheduler accepts the data and the expected topology appears.
+3. Set `topology.compile_mode = "full"` if the `Parent Node` column should shape under the named nodes in `network.json`.
+4. Use the WebUI editors or file-based workflow to maintain them.
+5. Confirm the scheduler accepts the data and the expected topology appears.
+
+Use `flat` only when you want generated CPU bucket queues instead of hierarchy-based parent queues.
 
 Next:
 - [Advanced Configuration Reference](configuration-advanced.md)
diff --git a/docs/v2.0/topology-data-flow.md b/docs/v2.0/topology-data-flow.md
@@ -110,6 +110,15 @@ Operator-managed files remain the ingress contract.
   - `network.effective.json`
   - `shaping_inputs.json`
 
+For DIY/manual deployments that expect the `Parent Node` column in `ShapedDevices.csv` to shape under named nodes from `network.json`, use a hierarchy-preserving topology mode such as:
+
+```toml
+[topology]
+compile_mode = "full"
+```
+
+Do not use `compile_mode = "flat"` for hierarchy-based parent shaping. Flat mode intentionally assigns circuits to generated CPU bucket queues such as `Generated_PN_1`; `shaping_inputs.json` will show `resolution_source: "flat_bucket"` for those circuits.
+
 ```{mermaid}
 flowchart LR
     A[Built-in Integration Mode] --> B[topology_import.json]
@@ -143,6 +152,8 @@ flowchart LR
 
 When a circuit references a parent or anchor that is not present in the queue-visible effective topology, LibreQoS still shapes the circuit under a generated parent node. Scheduler output summarizes those fallbacks by reason and includes a few example circuits instead of printing one warning per circuit. Review the examples in Topology Manager or the source integration when those circuits should attach to a specific real site, AP, or parent node.
 
+This is different from explicit flat mode. If `shaping_inputs.json` shows `resolution_source: "flat_bucket"`, the generated parent node is expected flat-mode behavior. Switch `topology.compile_mode` away from `flat` when circuits should follow `network.json` parent names.
+
 ## Consumer Map
 
 ```{mermaid}
diff --git a/docs/v2.0/troubleshooting.md b/docs/v2.0/troubleshooting.md
@@ -283,6 +283,25 @@ journalctl -u lqosd --since "10 minutes ago"
 
 If still blank under normal traffic, collect recent logs and open an issue.
 
+### Circuits show Generated_PN instead of network.json node names
+
+If a DIY/manual deployment uses `network.json` and `ShapedDevices.csv`, but the Circuit page shows parents such as `Generated_PN_1`, check the runtime shaping inputs:
+
+```bash
+jq '.circuits[] | {circuit_id, logical_parent_node_name, effective_parent_node_name, resolution_source}' /opt/libreqos/state/shaping/shaping_inputs.json
+```
+
+If `resolution_source` is `flat_bucket`, LibreQoS is in flat topology mode. That mode intentionally assigns circuits to generated CPU bucket queues instead of shaping them under the named `Parent Node` hierarchy.
+
+To shape circuits under the node names from `network.json`, set:
+
+```toml
+[topology]
+compile_mode = "full"
+```
+
+Then reload or wait for the scheduler to regenerate `network.effective.json` and `shaping_inputs.json`.
+
 ### Site Map appears blank or slow
 
 Site Map has one extra dependency beyond normal WebUI data feeds: current builds fetch bbox/bootstrap data and raster tiles from `https://insight.libreqos.com`.
diff --git a/src/rust/lqos_config/src/lib.rs b/src/rust/lqos_config/src/lib.rs
@@ -96,8 +96,8 @@ pub use topology_runtime_state::{
     TopologyEffectiveNodeState, TopologyEffectiveStateFile, TopologyRuntimeShapingPayloadIdentity,
     TopologyRuntimeStateError, TopologyRuntimeStatusFile, TopologyShapingCircuitInput,
     TopologyShapingDeviceInput, TopologyShapingInputsFile, TopologyShapingResolutionSource,
-    active_runtime_shaping_inputs_path, compute_effective_network_generation,
-    active_runtime_shaping_inputs_path_from_status, compute_topology_source_generation,
+    active_runtime_shaping_inputs_path, active_runtime_shaping_inputs_path_from_status,
+    compute_effective_network_generation, compute_topology_source_generation,
     load_active_runtime_shaping_inputs, load_active_runtime_shaping_inputs_from_status,
     topology_attachment_health_state_path, topology_compiled_shaping_path,
     topology_effective_network_path, topology_effective_state_path, topology_import_path,
diff --git a/src/rust/lqos_config/src/topology_canonical_state.rs b/src/rust/lqos_config/src/topology_canonical_state.rs
@@ -37,6 +37,8 @@ pub enum TopologyCanonicalIngressKind {
 pub enum TopologyCanonicalRateInputSource {
     /// The canonical node rate input came from the richest available attachment metadata.
     AttachmentMax,
+    /// The canonical node rate input came from an operator-saved rate override.
+    OperatorOverride,
     /// The canonical node rate input came from an imported legacy `network.json`.
     ImportedNetworkJson,
     /// The canonical node rate input came from the compatibility export tree.
diff --git a/src/rust/lqos_topology/src/lib.rs b/src/rust/lqos_topology/src/lib.rs
@@ -4571,6 +4571,50 @@ mod tests {
         );
     }
 
+    #[test]
+    fn native_operator_override_rates_still_cap_nodes() {
+        let mut root = sample_effective_bandwidth_tree();
+        let canonical = TopologyCanonicalStateFile {
+            ingress_kind: TopologyCanonicalIngressKind::NativeIntegration,
+            nodes: vec![
+                canonical_node_with_rate_source(
+                    "site-hoodoo",
+                    "Hoodoo Hill",
+                    774,
+                    774,
+                    TopologyCanonicalRateInputSource::AttachmentMax,
+                ),
+                canonical_node_with_rate_source(
+                    "ap-thunderhill",
+                    "HoodooHill-Thunderhill",
+                    300,
+                    300,
+                    TopologyCanonicalRateInputSource::OperatorOverride,
+                ),
+            ],
+            ..Default::default()
+        };
+
+        super::recompile_effective_network_bandwidths(
+            &mut root,
+            &canonical,
+            &TopologyEditorStateFile::default(),
+            &TopologyEffectiveStateFile::default(),
+        );
+
+        let ap = root["Hoodoo Hill"]["children"]["HoodooHill-Thunderhill"]
+            .as_object()
+            .expect("AP node should exist");
+        assert_eq!(
+            super::node_bandwidth_mbps(ap, "downloadBandwidthMbps"),
+            Some(300)
+        );
+        assert_eq!(
+            super::node_bandwidth_mbps(ap, "uploadBandwidthMbps"),
+            Some(300)
+        );
+    }
+
     fn write_runtime_json_fixture(path: PathBuf, value: &Value, label: &str) {
         let parent = path
             .parent()
diff --git a/src/scheduler.py b/src/scheduler.py
@@ -1070,7 +1070,7 @@ def normalize_bandwidth_value(value):
                     rate_input['legacy_imported_upload_mbps'] = normalized_upload
                     nodes_changed = True
                 if download is not None or upload is not None:
-                    rate_input['source'] = 'compatibility_export'
+                    rate_input['source'] = 'operator_override'
         elif adj_type == 'set_node_virtual':
             target_name = adj.get('node_name', '')
             virtual_val = adj.get('virtual', None)
diff --git a/src/test_scheduler.py b/src/test_scheduler.py
@@ -1525,6 +1525,10 @@ def test_apply_lqos_overrides_updates_canonical_only_for_integration_ingress(sel
         mock_write_network.assert_not_called()
         mock_write_sd.assert_not_called()
         mock_write_canonical.assert_called_once()
+        rate_input = canonical_state["nodes"][0]["rate_input"]
+        self.assertEqual(rate_input["source"], "operator_override")
+        self.assertEqual(rate_input["intrinsic_download_mbps"], 80)
+        self.assertEqual(rate_input["intrinsic_upload_mbps"], 40)
 
     def test_override_devices_to_rows_preserves_anchor_node_id(self):
         header = [
