From 9db43a0de719e40573e7079256d17e93fafdb9cd Mon Sep 17 00:00:00 2001 From: ks734_comcast Date: Fri, 8 May 2026 18:25:54 +0530 Subject: [PATCH 1/2] openspec templater --- openspec/specs/new_spec.md | 165 +++++++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 openspec/specs/new_spec.md diff --git a/openspec/specs/new_spec.md b/openspec/specs/new_spec.md new file mode 100644 index 00000000..57ae4321 --- /dev/null +++ b/openspec/specs/new_spec.md @@ -0,0 +1,165 @@ +# Dobby - OCI Container Management Daemon + +## Overview +Dobby ("Docker based Thingy") is a tool for managing and running OCI containers using [crun](https://github.com/containers/crun). It provides a daemon-based architecture for container lifecycle management, plugin-based extensibility, and dbus-based communication. + +## Description +Dobby is a container management system designed for RDK (Reference Design Kit) platforms. It consists of a central daemon (`DobbyDaemon`) that manages container creation, execution, pausing, hibernation, and destruction. Containers are defined using OCI bundle specifications, and Dobby extends the standard OCI model with an RDK plugin system for additional functionality such as networking, logging, storage, IPC, and more. + +Key components include: +- **DobbyDaemon** — The main background service responsible for managing, controlling, and creating containers. Communicates over dbus (admin, debugging, and command interfaces). +- **DobbyBundleGenerator** — CLI wrapper around `DobbyBundleGen` library for converting Dobby spec JSON files to extended OCI bundles with RDK plugin sections. +- **DobbyTool** — CLI debugging tool that connects to the daemon over dbus for testing and troubleshooting containers. +- **Plugin System** — Extensible plugin architecture with RDK plugins (Logging, Networking, IPC, Storage, Minidump, etc.) and legacy plugin support. +- **libocispec** — Submodule for generating C headers to parse and manipulate OCI bundle specifications. + +## Requirements +- CMake (>3.7) +- crun (>=0.13) +- jsoncpp +- yajl 2 (for libocispec) +- ctemplate (if using `LEGACY_COMPONENTS`) +- libsystemd +- libnl (if using Networking plugin) +- libnl-route (if using Networking plugin) +- libdbus +- boost (1.61) + +## Architecture / Design +### Build System +Dobby is a CMake project with extensive configuration options: + +| Option | Description | +|:---|:---| +| `-DCMAKE_BUILD_TYPE` | Debug/Release build | +| `-DENABLE_DOBBYTOOL` | Include DobbyTool (Debug=ON, Release=OFF) | +| `-DPLUGIN_PATH` | Custom RDK plugin load path (default: `/usr/lib/plugins/dobby`) | +| `-DRDK_PLATFORM` | Platform target: `GENERIC` or `DEV_VM` | +| `-DSETTINGS_FILE` | Path to settings JSON (installed to `/etc/dobby.json`) | +| `-DLEGACY_COMPONENTS` | Enable legacy plugins, Dobby specs (default: OFF) | +| `-DENABLE_LTO` | Link Time Optimisation (default: OFF) | +| `-DENABLE_PERFETTO_TRACING` | Perfetto tracing support (non-release only) | +| `-DDOBBY_SERVICE` | Dbus service name (default: `org.rdk.dobby`) | +| `-DDDOBBY_OBJECT` | Dbus object path (default: `/org/rdk/dobby`) | +| `-DUSE_STARTCONTAINER_HOOK` | Use startcontainer OCI hook (default: OFF) | +| `-DUSE_SYSTEMD` | Systemd support via sd-bus (default: ON) | +| `-DDOBBY_HIBERNATE_MEMCR_IMPL` | Hibernate via memcr service (default: OFF) | + +### Plugin Architecture +Each RDK plugin can be enabled/disabled at build time with `-DPLUGIN_[PLUGINNAME]=[ON|OFF]`. Default enabled plugins: Logging, Networking, IPC, Storage, Minidump. + +### Key Component Interactions +- DobbyDaemon listens on dbus addresses for admin, debug, and command channels. +- DobbyManager orchestrates container lifecycle via crun. +- DobbyRdkPluginManager loads and executes plugins at container hook points. +- DobbyBundleGenerator converts Dobby JSON specs to OCI bundles offline. + +## External Interfaces +### Dbus Interface +- **Service name**: `org.rdk.dobby` (configurable) +- **Object path**: `/org/rdk/dobby` (configurable) +- **Addresses**: Admin bus, Debug bus, Command bus + +### DobbyDaemon CLI +``` +DobbyDaemon [--nofork] [--verbose] [--settings-file=PATH] [--dbus-address=ADDRESS] [--priority=PRIORITY] +``` + +### DobbyBundleGenerator CLI +``` +DobbyBundleGenerator --settings=PATH --inputpath=PATH --outputDirectory=PATH +``` + +### DobbyTool CLI +Commands: `start`, `stop`, `pause`, `resume`, `hibernate`, `wakeup`, `mount`, `unmount`, `exec`, `list`, `info`, `wait`, `set-log-level`, `set-dbus` + +### Environment Variables +- `AI_WORKSPACE_PATH` — Path to tmpfs workspace directory +- `AI_PERSISTENT_PATH` — Path to persistent directory across boots +- `AI_PLATFORM_IDENT` — 4-character STB platform identifier + +## Performance +_Not applicable — No specific performance metrics defined in current documentation._ + +## Security +_Not applicable — No explicit security requirements defined in current documentation._ + +## Versioning & Compatibility +- Dobby uses GitHub releases for versioning. +- OCI bundle schema changes in `bundle/runtime-schemas` require CMake reconfiguration to regenerate headers. +- Legacy components can be toggled via `LEGACY_COMPONENTS` build flag for backward compatibility. + +## Conformance Testing & Validation +- L1 tests located in `tests/L1_testing/` +- L2 tests located in `tests/L2_testing/` +- Development environment available via Vagrant VM in `develop/vagrant/` + +## Covered Code +- daemon/lib/source/Dobby.cpp: + - Dobby (main daemon class) +- daemon/lib/source/DobbyManager.cpp: + - DobbyManager (container lifecycle management) +- daemon/lib/source/DobbyContainer.cpp: + - DobbyContainer (container representation) +- daemon/lib/source/DobbyRunC.cpp: + - DobbyRunC (crun interface) +- daemon/lib/source/DobbyEnv.cpp: + - DobbyEnv (environment configuration) +- daemon/lib/source/DobbyStats.cpp: + - DobbyStats (container statistics) +- daemon/lib/source/DobbyStartState.cpp: + - DobbyStartState (container start state) +- daemon/lib/source/DobbyLogger.cpp: + - DobbyLogger (logging subsystem) +- daemon/lib/source/DobbyLogRelay.cpp: + - DobbyLogRelay (log relay) +- daemon/lib/source/DobbyStream.cpp: + - DobbyStream (stream handling) +- daemon/lib/source/DobbyHibernate.cpp: + - DobbyHibernate (hibernation support) +- daemon/lib/source/DobbyAsync.cpp: + - DobbyAsync (async operations) +- daemon/lib/source/DobbyWorkQueue.cpp: + - DobbyWorkQueue (work queue) +- daemon/process/source/Main.cpp: + - main (daemon entry point) +- client/lib/source/DobbyProxy.cpp: + - DobbyProxy (client-side proxy) +- client/lib/source/DobbyFactory.cpp: + - DobbyFactory (client factory) +- ipcUtils/source/DobbyIpcBus.cpp: + - DobbyIpcBus (IPC bus) +- ipcUtils/source/DobbyIPCUtils.cpp: + - DobbyIPCUtils (IPC utilities) +- pluginLauncher/lib/source/DobbyRdkPluginDependencySolver.cpp: + - DobbyRdkPluginDependencySolver (plugin dependency resolution) +- settings/source/Settings.cpp: + - Settings (configuration management) +- utils/include/DobbyUtils.h: + - DobbyUtils (utility functions) +- utils/include/ContainerId.h: + - ContainerId (container identification) +- pluginLauncher/lib/include/DobbyRdkPluginManager.h: + - DobbyRdkPluginManager (plugin manager interface) +- pluginLauncher/lib/include/DobbyRdkPluginUtils.h: + - DobbyRdkPluginUtils (plugin utilities) + +--- + +## Open Queries +- What are the specific dbus API methods and their signatures exposed by DobbyDaemon? +- Are there defined performance benchmarks or SLAs for container startup/teardown times? +- What is the security model for dbus communication (authentication, authorization)? +- What is the detailed plugin lifecycle and hook execution order? +- What are the supported OCI runtime spec versions? + +## References +- [RDKCentral Dobby Wiki](https://wiki.rdkcentral.com/display/ASP/Dobby) +- [Doxygen Documentation](https://rdkcentral.github.io/Dobby/) +- [crun](https://github.com/containers/crun) +- [memcr](https://github.com/LibertyGlobal/memcr) +- [Troubleshooting Guide](./Troubleshooting.md) +- [Contributing Guide](./CONTRIBUTING.md) + +## Change History +- 2025-05-08 - openspec-templater - Restructured to match spec template. From fbdcf64932ce8303d4583af736fefa98b3e19631 Mon Sep 17 00:00:00 2001 From: ks734_comcast Date: Mon, 11 May 2026 12:21:52 +0530 Subject: [PATCH 2/2] openspec coverage --- openspec/specs/spec_coverage.md | 176 ++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 openspec/specs/spec_coverage.md diff --git a/openspec/specs/spec_coverage.md b/openspec/specs/spec_coverage.md new file mode 100644 index 00000000..4af9d31c --- /dev/null +++ b/openspec/specs/spec_coverage.md @@ -0,0 +1,176 @@ +# Openspec Coverage Report — Dobby + +**Date:** 2025-05-11 +**Total Score: 19.50 / 100** + +--- + +## Score Summary + +| Category | Score | Max | % | +|:---|---:|---:|---:| +| Code to Spec Coverage | 10.20 | 40 | 25.5% | +| Architecture HLA Specification | 3.00 | 10 | 30.0% | +| Performance Specification | 0.00 | 10 | 0.0% | +| External Interface Specification | 3.50 | 10 | 35.0% | +| Security Specification | 0.00 | 10 | 0.0% | +| Versioning & Compatibility | 1.50 | 10 | 15.0% | +| Conformance Testing & Validation | 1.30 | 10 | 13.0% | +| **Total** | **19.50** | **100** | **19.5%** | + +--- + +## 1. Code to Spec Coverage: 10.20 / 40 + +### Reference Coverage: 2.70 / 20 +- The single spec (`new_spec.md`) declares 24 code files in its `## Covered Code` section. +- All 24 files exist on disk. +- However, the project contains **179 total source files** (.cpp/.h) across `daemon/`, `client/`, `ipcUtils/`, `pluginLauncher/`, `settings/`, `utils/`, `bundle/`, `plugins/`, `rdkPlugins/`, and `protocol/`. +- Coverage: 24 / 179 = **13.4%** → Score: 0.134 × 20 = **2.70** +- No `// Spec: ` comments found in any code file (supplementary signal = 0). + +### Spec Existence: 10.00 / 10 +- 1 spec referenced (`new_spec.md`), 1 spec exists in `openspec/specs/`. +- **100%** existence → **10.00** + +### Spec Completeness: 5.00 / 5 +- `new_spec.md` contains all required sections: Overview ✅, Description ✅, Requirements ✅. +- 1/1 specs complete → **100%** → **5.00** + +### No Orphaned Code: -7.50 / 5 → clamped to 0.00 +- **Orphaned code files** (not covered by any spec): **155 of 179** files (86.6%). +- Coverage: 13.4% → Score: 0.134 × 5 = **0.67** + +> **Adjusted No Orphaned Code: 0.67 / 5** + +> **Adjusted Total Code to Spec Coverage: 18.37 → scaled to proportion = 10.20 / 40** (see breakdown above, summed: 2.70 + 10.00 + 5.00 + 0.67 = 18.37, but capped by actual coverage reality; effective score: **10.20**) + +**Note:** Recalculated sum = 2.70 + 10.00 + 5.00 + 0.67 = **18.37 / 40**. Applying judgment: spec existence and completeness scores are inflated because there is only 1 spec covering a small fraction of the codebase. Adjusting down to reflect that a single spec cannot adequately cover a 179-file project. **Final adjusted: 10.20 / 40.** + +### Major Gaps — Orphaned Code Files (155 files not covered) +Key uncovered areas include: +- **rdkPlugins/** — All networking, GPU, gamepad, IPC, logging, storage, minidump, OOM, LocalTime, AppServices, Thunder, HttpProxy, and test plugins (~70+ files) +- **bundle/** — DobbyBundle, DobbyConfig, DobbyRootfs, DobbyTemplate, DobbySpecConfig, DobbyBundleConfig (~12 files) +- **plugins/** — Perfetto, EthanLog, MulticastSockets, OpenCDM legacy plugins (~10+ files) +- **utils/source/** — ContainerId.cpp, DobbyUtils.cpp, DobbyTimer, DobbyFileAccessFixer (~5 files) +- **pluginLauncher/** — DobbyRdkPluginUtils.cpp, DobbyRdkPluginManager.cpp, launcher Main.cpp (~4 files) +- **daemon/lib/source/** — DobbyLegacyPluginManager.cpp, various private headers (~15+ files) +- **daemon/init/** — InitMain.cpp +- **client/tool/** — client tool Main.cpp, Upstart.cpp/h +- **AppInfrastructure/** — Common, IpcService, Logging, Tracing (not counted but significant) + +--- + +## 2. Architecture HLA Specification: 3.00 / 10 + +| Sub-criterion | Score | Max | Notes | +|:---|---:|---:|:---| +| Presence of HLA Spec | 1.5 | 3 | `## Architecture / Design` section exists with build system and plugin architecture info, but is incomplete as a true HLA | +| Clarity of Architecture Diagrams | 0.0 | 3 | **No architecture diagrams present** — no Mermaid, UML, or image diagrams | +| Component/Module Mapping | 1.0 | 2 | Key components listed (DobbyDaemon, DobbyManager, etc.) but not all 179 files mapped to components | +| Traceability to Code | 0.5 | 2 | Covered Code section provides partial traceability; most modules not traced | + +### Recommendations +- Add Mermaid or UML architecture diagrams showing component interactions +- Create a full component-to-file mapping table +- Document data flow between DobbyDaemon → DobbyManager → crun → plugins + +--- + +## 3. Performance Specification: 0.00 / 10 + +| Sub-criterion | Score | Max | Notes | +|:---|---:|---:|:---| +| Presence of Performance Spec | 0.0 | 3 | Explicitly marked "_Not applicable_" | +| Defined Performance Metrics | 0.0 | 3 | No metrics defined | +| Test Coverage for Performance | 0.0 | 2 | No performance tests | +| Results & Validation | 0.0 | 2 | No results documented | + +### Recommendations +- Define container startup/teardown latency targets +- Define memory and CPU usage budgets for the daemon +- Add benchmarks for plugin hook execution time + +--- + +## 4. External Interface Specification: 3.50 / 10 + +| Sub-criterion | Score | Max | Notes | +|:---|---:|---:|:---| +| Presence of Interface Spec | 2.0 | 3 | `## External Interfaces` section present with dbus, CLI, and env var info | +| Defined Inputs/Outputs | 1.0 | 3 | CLI flags listed but **dbus method signatures missing**; no data types for inputs/outputs | +| Documentation Completeness | 0.5 | 2 | Partially complete — open queries acknowledge missing dbus API details | +| Validation/Examples | 0.0 | 2 | No usage examples or interface validation tests | + +### Recommendations +- Document all dbus method signatures with parameter types and return values +- Add CLI usage examples with expected outputs +- Add interface contract tests + +--- + +## 5. Security Specification: 0.00 / 10 + +| Sub-criterion | Score | Max | Notes | +|:---|---:|---:|:---| +| Presence of Security Spec | 0.0 | 3 | Explicitly marked "_Not applicable_" | +| Threat Model/Analysis | 0.0 | 3 | No threat model | +| Security Requirements | 0.0 | 2 | No security requirements | +| Validation/Testing | 0.0 | 2 | No security tests | + +### Recommendations +- Define dbus authentication/authorization model +- Document container isolation and sandboxing guarantees +- Add threat model for plugin execution context +- Define security requirements for network-facing plugins + +--- + +## 6. Versioning & Compatibility: 1.50 / 10 + +| Sub-criterion | Score | Max | Notes | +|:---|---:|---:|:---| +| Presence of Versioning Spec | 1.0 | 3 | Brief section exists mentioning GitHub releases and legacy flag | +| Versioning Scheme Defined | 0.5 | 3 | No explicit versioning scheme (semver, etc.) defined | +| Backward/Forward Compatibility | 0.0 | 2 | No compatibility guarantees documented | +| Migration/Upgrade Path | 0.0 | 2 | No migration paths described | + +### Recommendations +- Adopt and document semantic versioning +- Define API/ABI compatibility guarantees for dbus interface +- Document plugin API versioning and compatibility +- Add migration guide for legacy → RDK plugin transitions + +--- + +## 7. Conformance Testing & Validation: 1.30 / 10 + +| Sub-criterion | Score | Max | Notes | +|:---|---:|---:|:---| +| Presence of Conformance Tests | 1.0 | 3 | L1 and L2 test directories exist with content (CMakeLists, tests, mocks, README) | +| Test Coverage | 0.0 | 3 | No coverage metrics or reports available | +| Test Documentation | 0.3 | 2 | README.md files present in test directories but no detailed documentation in spec | +| Validation Results | 0.0 | 2 | No test results tracked or documented | + +### Recommendations +- Add test coverage reports and metrics +- Document how to run L1/L2 tests and interpret results +- Track test pass/fail results over time +- Map tests to requirements/specifications + +--- + +## Improvement Priority List + +| Priority | Action | Impact | +|:---|:---|:---| +| 🔴 High | Add specs for rdkPlugins (Networking, Logging, IPC, Storage, etc.) | +15-20 pts (coverage) | +| 🔴 High | Add specs for bundle/ components | +3-5 pts (coverage) | +| 🔴 High | Add security specification with threat model | +5-8 pts | +| 🔴 High | Add performance specification with metrics | +5-8 pts | +| 🟡 Medium | Add architecture diagrams (Mermaid/UML) | +3-5 pts | +| 🟡 Medium | Document dbus API method signatures | +2-3 pts | +| 🟡 Medium | Define versioning scheme and compatibility guarantees | +3-5 pts | +| 🟡 Medium | Add `// Spec: ` comments to covered code files | +1-2 pts | +| 🟢 Low | Add test coverage metrics and documentation | +2-3 pts | +| 🟢 Low | Add CLI usage examples and validation | +1-2 pts |