Elangovan Natarajan

This commit **refactors** the **FBOSS CLI testing infrastructure** by migrating **FSDB publisher and subscriber tests** from a Facebook-internal directory to the general OSS test suite. It introduces a new `MockFsdb` class and integrates FSDB mocking capabilities, including `setupMockedFsdbServer()` and `getMockFsdb()`, into `CmdHandlerTestBase` to facilitate testing. This change **enables comprehensive OSS testing** for FSDB-related CLI commands, improving the maintainability and accessibility of these tests for the open-source community. The `CmdShowFsdbTest.cpp` now houses these tests, ensuring broader coverage for the `fboss/cli/fboss2` module.

This commit **refactors** the `CmdStreamHandler` template class and its core implementation by moving it from an internal Facebook path to a **shared, open-source location**. This change **enables** the `stream fsdb stats` and `stream fsdb state` commands within the **FBOSS CLI's open-source build**, making these powerful **data streaming capabilities** accessible to all users. The `CmdStreamHandler` now provides a unified interface for processing and printing streaming command results, improving the **observability and debugging experience** for FSDB operational data. This involves creating new shared files like `CmdStreamHandler.h` and `CmdStreamHandler.cpp`, updating existing command headers to use the new shared path, and registering the commands in the common `CmdList.cpp`. Consequently, **FBOSS CLI** users can now leverage these commands to stream real-time FSDB operational statistics and state.

This commit **enables** the `show fsdb` commands (e.g., `stats`, `state`, `subscribers`, `publishers`) within the **open-source FBOSS CLI**. It involves a significant **refactoring** effort to migrate the command registration, global CLI options like `--fsdb-port`, and `FsdbService` client creation logic from internal-only paths to common and OSS-specific files such as `CmdList.cpp`, `CmdGlobalOptions.cpp`, and `CmdClientUtils.cpp`. This **feature enablement** allows users of the **open-source FBOSS build** to access critical **FSDB operational data**, significantly improving debugging and monitoring capabilities. `CmdShowVersionFsdb` is intentionally excluded from this move due to its internal dependencies.

This commit **enhances the memory benchmark infrastructure** within `fboss/thrift_cow/storage` by introducing **configurable iterations** and **statistical reporting**. It adds a new gflag, `bm_memory_iters`, allowing users to explicitly control the number of memory measurement iterations for benchmarks. Furthermore, the `bm_storage_metrics_helper` now computes and reports the standard deviation of memory usage, exposed as a new `stddev_memory_KB` user counter. This **new capability** provides more robust insights into memory stability alongside existing `avg_memory_KB` and `max_memory_KB` metrics, improving the precision and analytical depth of memory benchmarks.

This commit introduces a **new capability** to the **FSDB memory benchmarking framework**, allowing users to measure the memory footprint of a **specific FSDB subtree** rather than the entire state or stats tree. It adds a `--bm_fsdb_path` flag to the C++ `CowStorageBenchHelper` and a corresponding `--path` option to the Python CLI (`fsdb_memory_bench.py`). The core logic involves building full storage, extracting the target subtree, and then measuring its memory usage in isolation, supported by new data filtering functions in `AgentStatsBuilders` and `SwitchStateBuilders` to generate relevant test data. This enhancement provides more granular insights into memory consumption for **Thrift-based Copy-on-Write (COW) storage**, aiding in targeted optimization efforts.

This commit significantly **expands benchmark coverage** for **FSDB state and stats memory benchmarks** by introducing new configurations for various network device roles. It adds FDSW and SDSW roles to `CowStorageFsdbStateBench.cpp` and a comprehensive set of roles (EDSW, SDSW, FA, RSW, SSW, RTSW, FTSW, STSW, XSW, MA) to `CowStorageFsdbStatsBench.cpp`. These additions are applied to both **ThriftCow** and **HybridCow** modes, utilizing production-like scale configurations from `TestDataFactory`. This **testing improvement** enables more thorough **memory comparison** and analysis across diverse deployment scenarios for the `thrift_cow` storage system.

This commit introduces **data builder helper functions** within the `thrift_cow` storage test suite to programmatically populate various fields of the **FBOSS `SwitchState`** object. Implemented in `SwitchStateBuilders.cpp` and declared in `SwitchStateBuilders.h`, these builders generate realistic, production-like data for numerous components, including `ports`, `vlans`, `interfaces`, `ACLs`, and `QoS policies`. This **test infrastructure enhancement** is crucial for conducting accurate **memory benchmarks**, enabling developers to test `SwitchState` memory usage under diverse and worst-case configurations derived from real-world data. The work significantly improves the reliability and realism of memory profiling for the **FBOSS `thrift_cow` storage subsystem**.

This commit **enhances the `TestDataFactory`** within `fboss/thrift_cow/storage/tests` to generate more comprehensive and realistic test data for network switch configurations. It **expands the `RoleSelector` enum** to cover all switch roles and significantly updates `getRoleScale()` with production-like scale configurations for both existing and newly added roles. This **new capability** ensures that `buildSwitchState()` and `buildAgentStats()` populate all fields, including detailed scales for port queues and buffer pools, enabling **more robust testing**. Finally, the **`BUCK` build targets** are updated to include new builder source files and a `switch_config-cpp2-types` dependency.

This commit introduces **new helper functions** within `AgentStatsBuilders.h` and `AgentStatsBuilders.cpp` to **populate various AgentStats fields** with scaled, production-like data. This **new capability** is specifically designed to support **FSDB memory benchmarks**, enabling more accurate testing of memory usage for agent statistics. The builders generate data for a comprehensive set of statistics, including hardware resources, ASIC errors, and switch drops, using scale numbers derived from real-world network regions. This enhancement significantly improves the fidelity of **memory usage testing** for the **FSDB system**, ensuring it can handle realistic data shapes efficiently.

This commit **migrates** the **FBOSS CLI commands** from the deprecated `thrift-py-deprecated` library to the modern `thrift-python` library. This **refactoring** involves updating **Thrift import paths** (e.g., `.ttypes` to `.thrift_types`), adjusting **service client instantiation** by removing the `.Client` suffix, and adapting **enum and struct usage patterns** to align with the new library's API. Specifically, it affects modules like `dapper.py`, `flowcontrol.py`, `qcm.py`, and `route.py`, ensuring continued compatibility and leveraging the updated Thrift Python bindings.

This commit performs a significant **migration** of the `fbcode//neteng/fboss/py:thrift_clients` from the deprecated `thrift-py-deprecated` library to the modern **`thrift-python`** library. This **refactoring** involves updating BUCK dependencies, adjusting import paths, and adapting client instantiation from `FbossCtrl.Client` to `FbossCtrl`. To ensure compatibility and maintain existing behavior, explicit arguments are now required for Thrift methods like `getPortStatus([])`, and `.enforceTLS_ADVANCED()` is added to `ClientParams` to preserve TLS security. This update primarily impacts the **FBOSS Python CLI and utilities** (`port.py`, `route.py`, `utils.py`) that interact with these Thrift services, ensuring they function correctly with the new client library. The OSS base target `//fboss/py/fboss:thrift_clients` remains on `py-deprecated` for specific fallback use cases, limiting the scope of this migration.

This commit performs a significant **refactoring** of the **FBOSS CLI library** (`fboss_cli_lib`) by **migrating** its Python Thrift dependencies from the deprecated `thrift-py-deprecated` to the modern `thrift-python` library. This involved updating `BUCK` build rules, adjusting import paths from `*.ttypes` to `*.thrift_types`, and modernizing exception handling and enum access patterns across various CLI command files. Specifically, `TApplicationException` was replaced with `ApplicationError`, enum value lookups were updated, and struct immutability for `PortPrbsState` and `TransceiverInfo` was fixed to align with the new library's conventions. This **maintenance** effort ensures the **FBOSS CLI** remains compatible with current Python Thrift standards, improving its long-term maintainability.

This commit introduces **debug logging** within the `createAndDumpOverriddenAgentConfig` function in `fboss/agent/test/AgentEnsemble.cpp`. This **maintenance** change enhances **observability** during the **Agent ensemble's** configuration override process, which was previously lacking diagnostic information. The added logs will provide crucial insights to debug why **HW agents** might fail to read overridden configurations, directly addressing flakiness observed in **Conveyor runs**. This significantly streamlines the troubleshooting of configuration-related issues by making the override process transparent.

This commit **enhances the `fboss2 show fsdb subscribers` CLI command** by displaying human-readable paths for FSDB PATCH subscriptions. Previously, these subscriptions would show cryptic numeric path IDs (e.g., `1/2/108`), making the output difficult to interpret. The `getSubscriptionPathStr()` function in `fboss/cli/fboss2/utils/CmdUtils.cpp` is updated to convert these internal IDs to meaningful field names using `PathConverter<FsdbOperStateRoot>`. This **improves the user experience** and **readability** when inspecting **FSDB subscription details**, making debugging and monitoring more intuitive.

This commit performs a **documentation update** to the **FBOSS agent's introductory page** (`intro.mdx`). It **adds new links** to a FBOSS cheatsheet and a general documentation "How to" guide, enhancing resource discoverability. Additionally, this **maintenance** work updates the existing roadmap link to reflect the H1 2026 roadmap, ensuring users have access to the most current planning information for the `fboss/agent` module.

This commit performs a significant **documentation cleanup** by **removing 27 redundant RST files** from various `fboss/agent/wiki` directories. These legacy files, covering topics from `pktio_benchmarks_th3.rst` to `Learning_FBOSS.rst`, had already been migrated to the **MDX format** within the `static_docs` system, making them obsolete. This **maintenance** effort streamlines the **FBOSS documentation**, ensuring content consistency and reducing redundancy by consolidating information into the new static documentation framework.

This commit **migrates documentation** related to the **Warmboot agent** and its **routing interactions**. Specifically, the content is moved from the `fbsphinx` documentation system to **static documentation files**. This is a **documentation maintenance** effort, streamlining how these specific system behaviors are documented. The change ensures that critical information about the **Warmboot agent's** operational aspects and how it handles routing is now available through the new static documentation infrastructure, improving accessibility and consistency.

This commit **migrates the documentation for QOS maps** from its previous wiki location to the project's **static documentation system**. This is a **documentation maintenance** task, ensuring that information regarding **Quality of Service (QOS) maps** is now managed as part of the project's static documentation. The change improves the discoverability and consistency of the QOS maps documentation, making it more integrated with other project resources.

This commit **introduces a new, comprehensive homepage** for the **FBOSS Agent's static documentation**, effectively making it the primary landing page for the Docusaurus framework. This **new capability** centralizes critical information such as oncall details, project roadmap, and team resources, mirroring content previously available on an internal wiki. The **documentation framework** is updated by modifying `docusaurus.config.js` to direct the home navigation and logo to the new `intro.mdx` page, while also cleaning up the `HomepageFeatures.js` component. This change significantly **improves the discoverability and accessibility** of essential information for anyone interacting with the FBOSS Agent documentation.

This commit **refactors** the **Fsdb client library** by extracting template method implementations from `FsdbSubManager.h` into a new inline header file, `FsdbSubManager-inl.h`. Specifically, the constructor, `subscribe()`, `subscribeBound()`, and `parseChunkAndInvokeCallback()` methods of the `FsdbSubManager` are now defined separately. This **architectural change** aims to **reduce compilation times** for modules depending on `FsdbSubManager.h` by keeping the primary header smaller and containing only declarations. The `BUCK` file is updated to include the new inline header, ensuring that the public interface and functionality of the `FsdbSubManager` remain unchanged.