[% META title = 'Technical Changes Documentation' %] [% PageVersion = 'Documentation/technical_changes.tt,v 1.01 2025/01/21 system Exp system ' %] [% debug %] [% IF c.session.debug_mode == 1 %] [% PageVersion %] [% "Debugging HostName: " _ HostName %] [%# INCLUDE 'debug.tt' %] [% END %]

Technical Changes Documentation

Last Updated: January 2025 - Added Documentation System Overhaul

Recent Major Changes (January 2025)

Documentation System Overhaul

Date: January 21, 2025
Impact: Major system enhancement
Status: Completed

Problem:
The previous documentation system had significant limitations:

Solution Implemented:
Complete transformation from config-based to dynamic file scanning system:

  1. Dynamic File Discovery: Replaced JSON config with filesystem scanning
  2. Automatic Categorization: Intelligent categorization based on directory structure
  3. Proper Logging Integration: Fixed logging to use centralized logging utility
  4. Zero Maintenance: New files automatically discovered without config updates

Files Modified:

Benefits:

Dependency Management Issues

1. Net::CIDR Module Installation

The application requires the Net::CIDR Perl module for network address management in the Comserv::Util::NetworkMap module. Despite being correctly listed in the cpanfile, the module was not automatically installed during dependency resolution.

Issue:

Can't locate Net/CIDR.pm in @INC (you may need to install the Net::CIDR module) (@INC entries checked: /opt/comserv/Comserv/lib /etc/perl /usr/local/lib/x86_64-linux-gnu/perl/5.38.2 /usr/local/share/perl/5.38.2 /usr/lib/x86_64-linux-gnu/perl5/5.38 /usr/share/perl5 /usr/lib/x86_64-linux-gnu/perl-base /usr/lib/x86_64-linux-gnu/perl/5.38 /usr/share/perl/5.38 /usr/local/lib/site_perl) at /opt/comserv/Comserv/lib/Comserv/Util/NetworkMap.pm line 7.

Solution:
The module must be installed manually using:

sudo cpanm Net::CIDR

Explanation:

  1. The comserv_server.pl script runs without this module because it uses lazy loading - the NetworkMap module is only loaded when actually used
  2. Starman pre-loads all modules during initialization, causing it to fail immediately when the dependency is missing
  3. Perl applications don't automatically install missing dependencies at runtime for security and stability reasons

Future Fix Required:
The dependency management system needs to be reviewed to ensure all modules listed in cpanfile are properly installed during deployment. This could involve:

  1. Creating a deployment script that validates all dependencies are installed before starting the application
  2. Adding a pre-flight check to the Starman startup process
  3. Implementing a more robust dependency management system using Carton or a similar tool
  4. Adding clear documentation about required manual installation steps

Proxmox Model Fixes

1. Duplicate Method Declarations

The test_proxmox_node method was defined three times in the Proxmox.pm file. This is a problem in Perl because only the last definition is used, and the others are silently ignored, which can lead to unexpected behavior.

Original Code (problematic):

# First definition at lines 318-424
sub test_proxmox_node {
    # Implementation 1
}

# Second definition at lines 426-532
sub test_proxmox_node {
    # Implementation 2
}

# Third definition at lines 1142-1168
sub test_proxmox_node {
    # Implementation 3
}

Fixed Code:

# Kept only the first implementation
sub test_proxmox_node {
    # Implementation 1
}

# Replaced second definition with comment
# This duplicate test_proxmox_node method has been removed to fix declaration errors

# Replaced third definition with comment
# This duplicate test_proxmox_node method has been removed to fix declaration errors

2. Indentation Error

There was an extra closing brace in the _get_real_vms_new method that caused incorrect nesting of code blocks.

Original Code (problematic):

            # Store debug info
            $self->{debug_info}->{error} = "No VMs found on any node";
            $self->{debug_info}->{original_error} = "First API request failed: " . $res->status_line;

            return [];
        }
        }
    }
}

Fixed Code:

            # Store debug info
            $self->{debug_info}->{error} = "No VMs found on any node";
            $self->{debug_info}->{original_error} = "First API request failed: " . $res->status_line;

            return [];
        }
    }
}

3. Missing Attribute

The code referenced a token attribute that wasn't defined in the class, which could lead to undefined behavior.

Original Code (problematic):

# No definition for 'token' attribute

# But code references it
if (!$self->{api_token} && !$self->{token}) {
    # ...
}

Fixed Code:

# Added proper attribute definition
has 'token' => (
    is => 'rw',
    isa => 'Str',
    required => 0,
);

# Now the reference works correctly
if (!$self->{api_token} && !$self->{token}) {
    # ...
}
[% END %]