DECNET Domain Models

Important

DEVELOPMENT DISCLAIMER: DECNET is currently in active development. The models defined in decnet/models.py are subject to significant changes as the framework evolves.

Overview

The decnet/models.py file serves as the centralized repository for all Domain Models used throughout the project. These are implemented using Pydantic v2 and ensure that the core business logic remains decoupled from the specific implementation details of the database (SQLAlchemy/SQLite) or the web layer (FastAPI).

Model Hierarchy

DECNET categorizes its models into two primary functional groups: INI Specifications and Runtime Configurations.

1. INI Specifications (Input Validation)

These models are designed to represent the structure of a decnet.ini file. They are primarily consumed by the ini_loader.py during the parsing of user-provided configuration files.

IniConfig: The root model for a full deployment specification. It includes global settings like subnet, gateway, and interface, and contains a list of DeckySpec objects.
DeckySpec: A high-level description of a machine. It contains optional fields that the user may provide in an INI file (e.g., ip, archetype, services).
CustomServiceSpec: Defines external "Bring-Your-Own" services using Docker images and custom execution commands.

2. Runtime Configurations (Operational State)

These models represent the active, fully resolved state of the deployment. Unlike the specifications, these models require all fields to be populated and valid.

DecnetConfig: The operational root of a deployment. It includes the resolved network settings and the list of active DeckyConfig objects. It is used by the Engine for orchestration and is persisted in decnet-state.json.
DeckyConfig: A fully materialized decoy configuration. It includes generated hostnames, resolved distro images, and specific IP addresses.

The Fleet Transformer (`fleet.py`)

The connection between the Specifications and the Runtime Configurations is handled by decnet/fleet.py.

The function build_deckies_from_ini takes an IniConfig as input and performs the following "up-conversion" logic:

IP Allocation: Auto-allocates free IPs from the subnet for any deckies missing an explicit IP in the INI.
Service Resolution: Validates that all requested services exist in the registry and assigns defaults from archetypes if needed.
Environment Inheritance: Inherits settings like rotation intervals (mutate_interval) from the global INI context down to individual deckies.

Structural Validation: `IniContent`

To ensure that saved deployments in the database or provided by the API remain structurally sound, DECNET uses a specialized IniContent type.

validate_ini_string: A pre-validator that uses Python's native configparser. It ensures that the content is a valid INI string, does not exceed 512KB, and contains at least one section.
Standardized Errors: It raises specifically formatted ValueError exceptions that are captured by both the CLI and the Web UI to provide clear feedback to the user.

Key Consumer Modules

Module	Usage
`decnet/ini_loader.py`	Uses `IniConfig` and `DeckySpec` to parse raw `.ini` files into structured objects.
`decnet/fleet.py`	Transforms `IniConfig` specs into `DeckyConfig` operational models.
`decnet/config.py`	Uses `DecnetConfig` and `DeckyConfig` to manage the lifecycle of `decnet-state.json`.
`decnet/web/db/models.py`	Utilizes `IniContent` to enforce structural validity on INI strings stored in the database.

3.7 KiB Raw Blame History