// Base64 encodes binary data as ASCII text:
// - 3 bytes (24 bits) -> 4 Base64 characters (6 bits each)
// - Input not divisible by 3 requires padding
//
// Example:
// "M" (1 byte = 8 bits) -> "TQ==" (4 characters, with padding)
// "Ma" (2 bytes = 16 bits) -> "TWE=" (4 characters, with padding)
// "Man" (3 bytes = 24 bits) -> "TWFu" (4 characters, no padding needed)
 
// The encoding process:
// 1. Group input bytes into 3-byte chunks
// 2. Convert each chunk to 4 Base64 characters
// 3. Pad final chunk with '=' if incomplete
 
// Decoding reverses this:
// 1. Each 4 Base64 characters -> 3 bytes
// 2. Final chunk may have padding '=' characters
// 3. Remove padding to get original bytes

use base64::{Engine as _, engine::general_purpose};
 
fn trailing_bits_problem() {
    // Standard Base64 requires input to be multiple of 4 characters
    // and for trailing bits to properly align
    
    // Valid Base64: "TWFu" (4 characters, no padding needed)
    let valid = general_purpose::STANDARD.decode("TWFu").unwrap();
    // OK: decodes to "Man"
    
    // Invalid: missing padding
    // "TWE" should be "TWE=" (3 chars instead of 4)
    let result = general_purpose::STANDARD.decode("TWE");
    // Error: InvalidPadding or InvalidLength
    
    // Invalid: extra trailing bits
    // Some encoders produce output where final bits don't align
    // This can happen with:
    // - Corrupted data
    // - Non-compliant encoders
    // - Data truncation
    // - Legacy systems
}

// Base64 encoding groups bits into 6-bit units:
// - Each Base64 character represents 6 bits
// - 4 characters = 24 bits = 3 bytes
 
// When encoding data that isn't a multiple of 3 bytes:
// 
// Input: "M" (8 bits)
// Encoded: "TQ==" 
// - "T" = 19 (6 bits)
// - "Q" = 16 (6 bits, only 2 bits are data)
// - "=" = padding
// - "=" = padding
// Total: 8 bits of data + 4 padding bits
 
// Trailing bits problem occurs when:
// 1. Final characters have extra bits beyond data
// 2. Padding is incorrect or missing
// 3. Input length isn't divisible by 4
 
// Example: "TQ" (without padding)
// - "T" = 19 -> bits: 010011
// - "Q" = 16 -> bits: 010000
// Combined: 01001101 0000 (12 bits)
// Should represent: 1 byte (8 bits) + 4 trailing bits
// The 4 trailing bits don't form a complete byte

use base64::{Engine as _, engine::general_purpose, Config};
 
fn strict_decoding() {
    // Default: reject trailing bits
    // This is the safest and most correct behavior
    
    // Missing padding
    let result = general_purpose::STANDARD.decode("TWE");
    match result {
        Ok(_) => println!("Decoded successfully"),
        Err(e) => println!("Error: {:?}", e),
        // Error: InvalidPadding
    }
    
    // Incorrect length
    let result = general_purpose::STANDARD.decode("TWFub");  // 5 characters
    match result {
        Ok(_) => println!("Decoded successfully"),
        Err(e) => println!("Error: {:?}", e),
        // Error: InvalidLength
    }
    
    // Benefits of strict decoding:
    // - Detects corrupted data
    // - Ensures data integrity
    // - Follows RFC 4648 strictly
    // - Fails fast on malformed input
}

use base64::{Engine as _, engine::general_purpose, DecodePaddingMode};
 
fn lenient_decoding() {
    // Create a decoder that allows trailing bits
    let engine = general_purpose::GeneralPurpose::new(
        &general_purpose::STANDARDalphabet,
        general_purpose::GeneralPurposeConfig::new()
            .with_decode_allow_trailing_bits(true)
    );
    
    // Now decode input with trailing bits
    // "TWE" without proper padding
    let result = engine.decode("TWE");
    match result {
        Ok(data) => {
            println!("Decoded: {:?}", String::from_utf8_lossy(&data));
            // Successfully decodes to "Ma"
            // Trailing bits are silently ignored
        }
        Err(e) => println!("Error: {:?}", e),
    }
    
    // This is useful for:
    // - Legacy systems with non-compliant encoders
    // - Data that was truncated during transmission
    // - Buggy Base64 implementations
    // - Interoperability with lenient systems
}

use base64::{Engine as _, alphabet, engine::{general_purpose, GeneralPurpose, GeneralPurposeConfig}};
 
fn configuration_options() {
    // The full configuration includes several options:
    let config = GeneralPurposeConfig::new()
        .with_decode_allow_trailing_bits(true)
        .with_decode_padding_mode(DecodePaddingMode::Indifferent);
    
    let engine = GeneralPurpose::new(&alphabet::STANDARD, config);
    
    // Other related options:
    // - decode_padding_mode: How to handle padding during decode
    // - encode_padding: Whether to add padding during encode
    // - with_encode_padding: Configure encoding padding
    
    // DecodePaddingMode options:
    // - Canonical: Require canonical padding (default)
    // - Indifferent: Accept missing or extra padding
    // - NoPadding: Require no padding
    
    // These options are often used together for maximum leniency
}
 
#[derive(Debug, Clone, Copy)]
enum DecodePaddingMode {
    Canonical,   // Strict: require proper padding
    Indifferent, // Lenient: accept any padding
    NoPadding,   // Strict: require no padding
}

use base64::{Engine as _, engine::general_purpose, GeneralPurpose, GeneralPurposeConfig};
 
fn legacy_data_example() {
    // Scenario: receiving Base64 from legacy system
    // The legacy encoder has bugs:
    // - Sometimes omits padding
    // - Sometimes has extra trailing bits
    // - Not fully RFC compliant
    
    // Default decoder would fail
    let legacy_input = "SGVsbG8gV29ybGQ";  // Missing padding
    
    // Strict decoder fails
    let strict_result = general_purpose::STANDARD.decode(legacy_input);
    assert!(strict_result.is_err());
    
    // Lenient decoder succeeds
    let lenient_engine = GeneralPurpose::new(
        &general_purpose::STANDARDalphabet,
        GeneralPurposeConfig::new()
            .with_decode_allow_trailing_bits(true)
    );
    
    let lenient_result = lenient_engine.decode(legacy_input);
    assert!(lenient_result.is_ok());
    // Decodes to "Hello World" (ignoring missing padding)
    
    // Trade-off:
    // - Lenient: Accepts more input, but may hide data corruption
    // - Strict: Rejects malformed input, but may fail on valid data from buggy systems
}

use base64::{Engine as _, engine::general_purpose, GeneralPurpose, GeneralPurposeConfig};
 
fn corruption_detection() {
    // decode_allow_trailing_bits doesn't fix all problems
    // It only handles trailing bit issues
    
    // Still catches:
    // - Invalid Base64 characters
    // - Wrong character set
    // - Complete garbage input
    
    let lenient_engine = GeneralPurpose::new(
        &general_purpose::STANDARDalphabet,
        GeneralPurposeConfig::new()
            .with_decode_allow_trailing_bits(true)
    );
    
    // Still fails on invalid characters
    let result = lenient_engine.decode("SGVsbG8@V29ybGQ");
    assert!(result.is_err());  // '@' is not valid Base64
    
    // Still fails on completely wrong length (if unreasonably so)
    let result = lenient_engine.decode("");
    // Empty string decodes to empty bytes (OK)
    
    // Works on trailing bits:
    let result = lenient_engine.decode("SGVsbG8");
    // Successfully decodes, ignoring trailing bits
    
    // The feature is specifically for:
    // - Trailing bits that don't form complete bytes
    // - Missing or incorrect padding
    // Not for: completely corrupted data
}

use base64::{Engine as _, engine::general_purpose, GeneralPurpose, GeneralPurposeConfig, DecodePaddingMode};
 
fn padding_vs_trailing_bits() {
    // decode_allow_trailing_bits handles:
    // - Extra bits in final byte
    // - Bit alignment issues
    
    // DecodePaddingMode handles:
    // - Presence/absence of '=' padding characters
    
    // They address different aspects of leniency
    
    // Strict padding (default):
    let strict = GeneralPurpose::new(
        &general_purpose::STANDARDalphabet,
        GeneralPurposeConfig::new()
            .with_decode_padding_mode(DecodePaddingMode::Canonical)
    );
    // Requires correct padding: "TQ==", "TWE=", "TWFu"
    
    // Lenient padding (common for trailing bits):
    let lenient_padding = GeneralPurpose::new(
        &general_purpose::STANDARDalphabet,
        GeneralPurposeConfig::new()
            .with_decode_padding_mode(DecodePaddingMode::Indifferent)
    );
    // Accepts: "TQ==", "TQ", "TQ=", "TWE=", "TWE", "TWFu"
    
    // Maximum leniency (combine both):
    let very_lenient = GeneralPurpose::new(
        &general_purpose::STANDARDalphabet,
        GeneralPurposeConfig::new()
            .with_decode_allow_trailing_bits(true)
            .with_decode_padding_mode(DecodePaddingMode::Indifferent)
    );
    // Accepts most malformed Base64
}

use base64::{Engine as _, engine::general_purpose};
 
fn encoding_produces_valid_output() {
    // When encoding with base64 crate:
    // - Output is always valid, properly padded
    // - No trailing bits issue
    
    let input = "Hello";
    let encoded = general_purpose::STANDARD.encode(input.as_bytes());
    println!("Encoded: {}", encoded);
    // "SGVsbG8="
    // Always valid, properly padded
    
    // The trailing bits issue comes from:
    // - Other encoders (possibly buggy)
    // - Data transmission truncation
    // - Manual manipulation
    // - Legacy systems
    
    // When you control both encoding and decoding:
    // - Use strict decoding
    // - No need for decode_allow_trailing_bits
    
    // When receiving data from external sources:
    // - Consider lenient decoding if you encounter errors
    // - Log warnings about malformed input
}

use base64::{Engine as _, engine::general_purpose, GeneralPurpose, GeneralPurposeConfig};
 
fn security_considerations() {
    // Security implications of lenient decoding:
    
    // 1. May accept corrupted data
    // - Corrupted bits in trailing positions are silently dropped
    // - Could mask data tampering
    
    // 2. Canonical form ambiguity
    // - "TQ==" and "TQ" might both decode to same value
    // - Could cause issues with cryptographic signatures
    
    // 3. Different interpretation
    // - Lenient decoder might produce different output than strict
    // - Interoperability issues
    
    // Best practices:
    
    // a) Use strict decoding for security-sensitive data
    let strict_engine = general_purpose::STANDARD;
    
    // b) Use lenient decoding only when necessary for compatibility
    let lenient_engine = GeneralPurpose::new(
        &general_purpose::STANDARDalphabet,
        GeneralPurposeConfig::new()
            .with_decode_allow_trailing_bits(true)
    );
    
    // c) Log warnings when lenient decoding succeeds on malformed input
    // d) Consider validating input format before decoding if source is untrusted
    
    // For cryptographic purposes, always use strict decoding
    // For user-facing data, lenient can improve UX
}

use base64::{Engine as _, engine::general_purpose, GeneralPurpose, GeneralPurposeConfig, DecodePaddingMode};
 
fn when_to_use() {
    // Use strict decoding (default) when:
    // - Data integrity is critical
    // - You control both encoder and decoder
    // - Security is important
    // - Validating untrusted input
    // - Cryptographic operations
    
    // Use decode_allow_trailing_bits when:
    // - Interoperating with legacy systems
    // - Accepting data from external sources
    // - Handling potentially truncated data
    // - User experience matters more than strictness
    // - Data is known to have minor encoding issues
    
    // Examples of strict use cases:
    // - Decoding authentication tokens
    // - Processing signed data
    // - Configuration files
    
    // Examples of lenient use cases:
    // - User-submitted data
    // - Legacy data migration
    // - API compatibility layer
    
    // Combine with Indifferent padding for maximum compatibility:
    let compat_engine = GeneralPurpose::new(
        &general_purpose::STANDARDalphabet,
        GeneralPurposeConfig::new()
            .with_decode_allow_trailing_bits(true)
            .with_decode_padding_mode(DecodePaddingMode::Indifferent)
    );
    
    // This engine accepts most "good enough" Base64
}

use base64::{Engine as _, engine::general_purpose, GeneralPurpose, GeneralPurposeConfig};
 
fn performance() {
    // decode_allow_trailing_bits has minimal performance impact:
    // - Same core decoding algorithm
    // - Only affects final validation step
    // - No extra allocations
    
    // Both strict and lenient decoders:
    // - Parse Base64 characters
    // - Convert 6-bit units to bytes
    // - Handle padding
    
    // The difference:
    // - Strict: validates trailing bits, returns error
    // - Lenient: validates trailing bits, ignores them
    
    // Performance is essentially the same
    // The trade-off is correctness vs compatibility
    
    let strict_engine = general_purpose::STANDARD;
    
    let lenient_engine = GeneralPurpose::new(
        &general_purpose::STANDARDalphabet,
        GeneralPurposeConfig::new()
            .with_decode_allow_trailing_bits(true)
    );
    
    // Both have similar performance
    // Choice should be based on requirements, not performance
}

use base64::{Engine as _, engine::general_purpose, GeneralPurpose, GeneralPurposeConfig, DecodePaddingMode};
 
// Scenario: API receiving data from multiple legacy sources
fn api_endpoint(base64_data: &str) -> Result<Vec<u8>, String> {
    // Try strict first (most common case)
    match general_purpose::STANDARD.decode(base64_data) {
        Ok(data) => return Ok(data),
        Err(_) => {
            // Strict failed, try lenient
            let lenient_engine = GeneralPurpose::new(
                &general_purpose::STANDARDalphabet,
                GeneralPurposeConfig::new()
                    .with_decode_allow_trailing_bits(true)
                    .with_decode_padding_mode(DecodePaddingMode::Indifferent)
            );
            
            match lenient_engine.decode(base64_data) {
                Ok(data) => {
                    // Log warning about lenient decode
                    println!("Warning: Used lenient decode for input");
                    Ok(data)
                }
                Err(e) => Err(format!("Failed to decode: {}", e)),
            }
        }
    }
}
 
fn process_request() {
    // From well-behaved client
    let valid_data = "SGVsbG8gV29ybGQ=";
    let result = api_endpoint(valid_data);
    assert!(result.is_ok());
    
    // From legacy client with missing padding
    let legacy_data = "SGVsbG8gV29ybGQ";  // Missing '='
    let result = api_endpoint(legacy_data);
    assert!(result.is_ok());  // Lenient decode succeeds
    
    // Completely invalid data
    let invalid_data = "SGVsbG8@V29ybGQ";
    let result = api_endpoint(invalid_data);
    assert!(result.is_err());
}

// Base64 encoding: 6 bits per character, 4 chars = 24 bits = 3 bytes
// Trailing bits: leftover bits that don't form complete bytes
//
// Example: "TQ" (2 characters = 12 bits)
// - Decoded: 1 byte (8 bits) + 4 trailing bits
// - Strict: Error (trailing bits don't form complete byte)
// - Lenient: OK (ignore trailing bits, return 1 byte)

// Strict decoding (default):
let engine = general_purpose::STANDARD;
// Rejects trailing bits, requires proper padding
 
// Lenient decoding:
let engine = GeneralPurpose::new(
    &general_purpose::STANDARDalphabet,
    GeneralPurposeConfig::new()
        .with_decode_allow_trailing_bits(true)
        .with_decode_padding_mode(DecodePaddingMode::Indifferent)
);
// Accepts trailing bits, ignores padding issues

// Use strict (default) when:
// - Data integrity is critical
// - Processing security-sensitive data
// - You control encoding
// - Validating untrusted input
 
// Use lenient when:
// - Interoperating with legacy systems
// - Accepting external data with known issues
// - Compatibility is more important than strictness
// - Graceful degradation is desired