---
title: Cpanel::Plugins::Components::Rules::Random Internal Sequence Diagram
displayMode: compact
generateBy: augment
---
sequenceDiagram
    participant Client
    participant Random
    participant Filter as Filter (Base)
    participant Base as Rules::Base
    participant NestedRule as Nested Rule
    participant Cache as Cache System
    participant Entropy as Entropy Sources
    participant Random as Random Generator
    participant FileSystem as File System

    Note over Client, FileSystem: Random Internal Flow

    %% Initial call
    Client->>+Random: new(config)
    Random->>Random: validate config structure
    Random-->>-Client: Random instance

    Client->>+Random: is_allowed()

    %% Filter base class processing
    Random->>+Filter: is_allowed()
    Filter->>Filter: validate config structure
    Filter->>Filter: extract nested rule from config

    %% Process nested rule first
    Filter->>+Base: process_rule('and', nested_rule)
    Base->>Base: get_module_name(rule_type)
    Base->>Base: load_module(module_name)
    Base->>+NestedRule: new(rule_config)
    NestedRule-->>-Base: rule instance
    Base->>+NestedRule: is_allowed()
    NestedRule-->>-Base: boolean result
    Base-->>-Filter: nested_rule_result

    alt nested rule failed
        Filter-->>Random: return false (short-circuit)
        Random-->>-Client: false
    else nested rule passed
        %% Apply filter logic
        Filter->>+Random: apply_filter(true, config)

        %% Validate configuration
        Random->>Random: validate sample_size (required)
        Random->>Random: validate fleet_size (optional, default 100000)
        Random->>Random: extract cache_file (optional)

        %% Check cache first
        alt cache_file specified
            Random->>+Cache: read_cache(cache_file)
            Cache->>+FileSystem: read file
            alt cache file exists and valid
                FileSystem-->>Cache: cached content
                Cache->>Cache: validate content (0 or 1)
                Cache-->>-Random: cached_decision
                Random-->>Filter: return cached_decision
                Filter-->>-Random: cached_decision
                Random-->>-Client: cached_decision
            else cache miss or invalid
                FileSystem-->>Cache: error or invalid content
                Cache-->>-Random: undef
                Note over Random: Continue to generate new decision
            end
        end

        %% Generate new random decision
        Random->>+Random: generate_random_decision(sample_size, fleet_size)

        %% Gather entropy sources
        Random->>+Entropy: collect server entropy
        Entropy->>Entropy: get hostname
        Entropy->>Entropy: get timestamp
        Entropy->>Entropy: get process_id
        Entropy->>Entropy: get perl rand()
        Entropy-->>-Random: entropy_string

        %% Generate secure random bytes
        Random->>+Random: get_secure_random_bytes(32)
        Random->>+FileSystem: try read /dev/urandom
        alt /dev/urandom available
            FileSystem-->>Random: secure random bytes
        else fallback to perl rand
            Random->>Random: generate bytes using rand(256)
            Random-->>Random: fallback random bytes
        end
        Random-->>-Random: random_bytes

        %% Combine entropy and hash
        Random->>Random: combine entropy + random_bytes
        Random->>Random: SHA256 hash of combined entropy
        Random->>Random: extract first 8 bytes as uint64

        %% Calculate probability and decision
        Random->>Random: calculate selection_probability = sample_size / fleet_size
        Random->>Random: calculate threshold = max_uint64 * selection_probability
        Random->>Random: decision = (random_value <= threshold) ? 1 : 0
        Random-->>-Random: is_selected

        %% Cache the result
        alt cache_file specified
            Random->>+Cache: write_cache(cache_file, is_selected)
            Cache->>Cache: normalize decision to 0 or 1
            Cache->>+FileSystem: atomic write to cache file
            FileSystem-->>-Cache: write success
            Cache-->>-Random: cache write complete
        end

        Random-->>-Filter: is_selected
        Filter-->>-Random: is_selected
        Random-->>-Client: is_selected
    end

    Note over Client, FileSystem: Key Algorithm Details
    Note over Random: Selection Probability = sample_size / fleet_size
    Note over Random: Threshold = (2^64 - 1) * selection_probability
    Note over Random: Selected if random_value <= threshold
    Note over Random: Cryptographic security via /dev/urandom + SHA256
    Note over Random: Server-specific entropy ensures uniqueness
    Note over Random: Caching ensures consistent decisions per server
