view release on metacpan or  search on metacpan

lib/AmberDB/Base/Schema.pm  view on Meta::CPAN

        }
    }
}

# ============================================================================
# TABLE SCHEMA NORMALIZATION & VALIDATION PIPELINE
# Normalizes, converts, and validates table schema definitions through an ordered
# rule pipeline. Ensures consistent in-memory structures across disk loading,
# table_attr, and table_infset.
# Usage:
#   $adb->normalize_blocks($table, $schema_hashref);
# ============================================================================
sub normalize_blocks {
    my ( $self, $table, $schema ) = @_;

    return {} unless ref($schema) eq 'HASH';

    # ------------------------------------------------------------------------
    # Pipeline Step 0: Table Identity & Metadata
    # Ensure table name and database group are present in schema.
    # ------------------------------------------------------------------------
    if ( defined $table && length $table ) {
        $schema->{table} = $table unless defined $schema->{table} && length $schema->{table};
        my ($dbase) = ( $table =~ /^([a-z0-9]+)_/i );
        $dbase //= "";
        $schema->{dbase} = $dbase unless defined $schema->{dbase} && length $schema->{dbase};
    }

    # Normalize UTF-8 characters on schema identity and block definitions
    $schema->{name} = $self->utf_decode( $schema->{name} ) if defined $schema->{name};
    if ( ref( $schema->{blocks} ) eq 'ARRAY' ) {
        for my $b ( @{ $schema->{blocks} } ) {
            next unless ref($b) eq 'HASH';
            for my $k (qw(name option valid)) {
                $b->{$k} = $self->utf_decode( $b->{$k} ) if defined $b->{$k};
            }
        }
    }
    if ( ref( $schema->{facet_block} ) eq 'ARRAY' ) {
        for my $fb ( @{ $schema->{facet_block} } ) {
            next unless ref($fb) eq 'HASH';
            for my $k (qw(label name title)) {
                $fb->{$k} = $self->utf_decode( $fb->{$k} ) if defined $fb->{$k};
            }
        }
    }

    # ------------------------------------------------------------------------
    # Pipeline Step 0b: Dbase Schema Group Inheritance
    # Inherit whitelisted operational flags from .dbase if not overridden.
    # ------------------------------------------------------------------------
    $self->_apply_dbase_inheritance( $table, $schema );

    # ------------------------------------------------------------------------
    # Pipeline Step 1: Global Configuration Inheritance
    # ------------------------------------------------------------------------
    if ( defined $schema->{use_ramdisk} ) {
        $schema->{use_ramdisk} = $self->_normalize_ramdisk_tier( $schema->{use_ramdisk} );
    }
    elsif ( !defined $schema->{use_cache} ) {
        my $global_ram = $self->config('use_ramdisk');
        $global_ram = $self->_normalize_ramdisk_tier($global_ram);
        $global_ram = 0 if $global_ram == 3;
        $schema->{use_ramdisk} = $global_ram;
    }

    # ------------------------------------------------------------------------
    # Pipeline Step 1b: Volatile RAM-Disk Tier 3 Stripping
    # If use_ramdisk == 3, table is pure volatile key-value store on RAM-disk.
    # Strip all indexing, columnar, facet, and relational definitions.
    # ------------------------------------------------------------------------
    if ( ( $schema->{use_ramdisk} // 0 ) == 3 ) {
        delete @{$schema}{
            qw(
              blocks match_block search_block view_block facet_block filter_block
              suggest_block suggest_join
              slug_block sort_block sort_fields use_facet facet_rules use_junk junk_rules
              record_index repeat_start repeat_ids field_rules keep_deleted
            )
        };
        $schema->{use_simple}  = 1;
        $schema->{no_backup}   = 1;
        $schema->{no_transact} = 1;
        $schema->{ramdisk_ttl} = 300 unless defined $schema->{ramdisk_ttl};
    }

    # ------------------------------------------------------------------------
    # Pipeline Step 2: Simple Mode Stripping
    # In simple key-value mode, selectively strip columnar, indexing, relational,
    # and caching definitions to enforce lightweight operation.
    # ------------------------------------------------------------------------
    if ( $schema->{use_simple} && ( $schema->{use_ramdisk} // 0 ) != 3 ) {
        delete @{$schema}{
            qw(
              blocks match_block search_block view_block facet_block filter_block
              suggest_block suggest_join
              slug_block sort_block sort_fields use_facet facet_rules use_junk junk_rules
              record_index repeat_start repeat_ids field_rules
              use_ramdisk ramdisk_ttl use_cache cache_ttl
            )
        };
        return $schema;
    }

    # ------------------------------------------------------------------------
    # Pipeline Step 3: RAM-Disk Environment & Mount Verification
    # If RAM-disk is not physically mounted or ready, strip use_ramdisk.
    # The existence of $schema->{use_ramdisk} is a guaranteed contract of readiness.
    # ------------------------------------------------------------------------
    unless ( $self->ramdisk_is_mounted() ) {
        delete $schema->{use_ramdisk};
        delete $schema->{use_cache};
    }

    # ------------------------------------------------------------------------
    # Pipeline Step 4: Blocks & Relational Foreign Keys (RDBM) Normalization
    # Converts string RDBM definitions like:
    # "catalog_category,2", "catalog_category;2", "catalog_category|2", "catalog_category:2"
    # into canonical hashref: { table => "catalog_category", display => 2 }
    # ------------------------------------------------------------------------
    if ( exists $schema->{blocks} ) {
        if ( ref( $schema->{blocks} ) eq 'ARRAY' ) {
            foreach my $block ( @{ $schema->{blocks} } ) {
                $self->normalize_rdbm($block) if ref($block) eq 'HASH';