Machine & Binary Services
Relevant source files
The following files were used as context for generating this wiki page:
Machine and Binary Services form the foundational layer of the abx-dl infrastructure, responsible for managing the host environment's configuration and resolving external dependencies required by plugins. The system distinguishes between user-provided configurations and runtime-derived data, ensuring that binary paths and environment-specific settings are cached and validated across different execution phases.
This subsystem manages the lifecycle of binary requirements, moving from a declarative state in plugin configurations to a resolved state where absolute paths and versions are verified. It interacts closely with the ABX Event Bus to handle requests for dependencies and updates to the machine state.
Sources: README.md:89-114, abx_dl/events.py:270-305
Machine State & Configuration Management
The MachineService (referenced as the logic handler for MachineEvent) manages two distinct layers of configuration: User Config and Derived Config. This separation ensures that manual user settings remain persistent and clean, while runtime-discovered information—such as validated binary paths—is stored as a cache to speed up subsequent runs.
Configuration Layers
| Layer | Description | Storage |
|---|---|---|
| User Config | Stores explicitly provided user values and persistent settings. | ~/.config/abx/config.env |
| Derived Config | Stores runtime-cached entries like resolved binary paths and install timestamps. | ~/.config/abx/derived.env |
Sources: README.md:92-105, abx_dl/events.py:308-320
Configuration Updates via MachineEvent
The system uses MachineEvent to update these configurations. This event can target either the "user" or "derived" config type and can perform single-key updates or bulk merges.
The diagram shows the logic flow when a MachineEvent is processed to update the local environment state.
Sources: abx_dl/events.py:308-320, abx_dl/cli.py:1085-1115
Binary Resolution & Dependency Lifecycle
Binary Services manage the transition from a BinaryRequestEvent (a declaration that a tool like wget is needed) to a BinaryEvent (a confirmation that the tool is found and validated).
Binary Request Workflow
When a plugin is executed, the orchestrator reads its required_binaries and emits request events. Provider plugins (e.g., apt, pip, npm, brew) listen for these requests and attempt to satisfy them.
- Requirement Declaration: Defined in
config.jsonunderrequired_binaries. - Request Emission: A
BinaryRequestEventis broadcast on the bus. - Resolution/Installation: Providers check the environment or install the binary.
- Verification: A
BinaryEventis emitted containing the absolute path and version.
Sources: abx_dl/events.py:270-305, TODOs.md:14-25, abx_dl/models.py:73-82
Binary Data Models
The system uses specific structures to represent these states:
This diagram illustrates the relationship between static configuration requirements and the dynamic events used during resolution.
Sources: abx_dl/models.py:73-82, abx_dl/events.py:270-305
Event Reference
Machine and Binary operations are driven by the following specific events on the ABX bus:
| Event Class | Purpose | Timeout |
|---|---|---|
BinaryRequestEvent | Requests a specific binary be found or installed. | 300.0s |
BinaryEvent | Confirms a binary is resolved with its metadata. | 10.0s |
MachineEvent | Triggers an update to the machine's configuration state. | 10.0s |
InstallEvent | Orchestrator preflight phase for binary resolution. | 300.0s |
Sources: abx_dl/events.py:46-55, abx_dl/events.py:270-320
Execution Phases & Hook Interaction
Binary resolution occurs primarily during the Install Phase. During this phase, on_BinaryRequest__* hooks are executed to satisfy dependencies before the CrawlEvent begins the actual snapshot process. Successful resolutions are cached in derived.env under ABX_INSTALL_CACHE for 24 hours.
The sequence shows the interaction between the orchestrator and providers to resolve a binary dependency.
Sources: abx_dl/events.py:16-35, README.md:149-160, TODOs.md:38-50
Conclusion
Machine & Binary Services provide the necessary environmental stability for abx-dl to run diverse sets of plugin tools. By isolating configuration layers and utilizing a robust event-driven resolution system, the project ensures that dependencies are managed efficiently with minimal redundancy through intelligent caching in the derived configuration layer.