The Access Control List

// Ensures that an ACL (Access Control List) record exists for a storage file.
// This method is idempotent: it will insert a new record if one doesn't exist, 
// or update the existing one if it does, preventing duplicate entries.
method ensureStorageFileACL(storageFileKey as int, userKey as int, businessUnitKey as int, organizationKey as int, u as bool, r as bool, d as bool) {
    
    // --- 1. VALIDATION PHASE ---
    // A storage file key is always mandatory.
    validation->failIf(storageFileKey == null, "Argument 'storageFileKey' is required");
    
    // Validates that at least ONE target entity (User, Business Unit, or Organization) is provided.
    validation->failIf(userKey == null and businessUnitKey == null and organizationKey == null, "One argument is reqruied between 'userKey', 'businessUnitKey', 'organizationKey'");
    
    // Validates that EXACTLY ONE target entity is provided (preventing mixed ACL records).
    // Note: The variable is named 'isOnlyOne', but the logic actually checks if MORE THAN ONE is provided.
    var isOnlyOne = (userKey != null and businessUnitKey != null) or (userKey != null and organizationKey != null) or (businessUnitKey != null and organizationKey != null);
    validation->failIf(isOnlyOne, "You can use only one argument between 'userKey', 'businessUnitKey', 'organizationKey'");
    
    // --- 2. IDEMPOTENT UPSERT PHASE ---
    // Prepare a new, empty ACL record in memory. 
    var acl = CREATE storage_file_acl;

    // Handle User ACL
    if (userKey != null) {
        // Query the database to see if an ACL record already exists for this exact file and user.
        var exists = FETCH storage_file_acl(key) FILTER AND (id_storage_file == ${storageFileKey}, id_user_acl == ${userKey}) LIMIT 1**;
        
        // If a record is found, discard the newly created empty record and fetch the existing one.
        if (exists != null) {
            acl = GET storage_file_acl (exists.key);
        }
        
        // Pass the record (either brand new or fetched from DB) to the helper method to apply values.
        this->storageFileACL(acl, storageFileKey, userKey, businessUnitKey, organizationKey, u, r, d);
        return null;
    }
    
    // Handle Business Unit ACL (Same idempotent logic as User)
    if (businessUnitKey != null) {
        var exists = FETCH storage_file_acl(key) FILTER AND (id_storage_file == ${storageFileKey}, id_business_unit_acl == ${businessUnitKey}) LIMIT 1**;
        if (exists != null) {
            acl = GET storage_file_acl (exists.key);
        }
        this->storageFileACL(acl, storageFileKey, userKey, businessUnitKey, organizationKey, u, r, d);
        return null;
    }
    
    // Handle Organization ACL (Same idempotent logic as User)
    if (organizationKey != null) {
        var exists = FETCH storage_file_acl(key) FILTER AND (id_storage_file == ${storageFileKey}, id_organization_acl == ${organizationKey}) LIMIT 1**;
        if (exists != null) {
            acl = GET storage_file_acl (exists.key);
        }
        this->storageFileACL(acl, storageFileKey, userKey, businessUnitKey, organizationKey, u, r, d);
        return null;
    }
}

// Helper method to map the provided parameters to the database entity fields.
method storageFileACL(acl as ENTITY storage_file_acl, storageFileKey as int, userKey as int, businessUnitKey as int, organizationKey as int, u as bool, r as bool, d as bool) {
    
    // Map the foreign keys
    acl.id_storage_file = storageFileKey;
    acl.id_user_acl = userKey;
    acl.id_business_unit_acl = businessUnitKey;
    acl.id_organization_acl = organizationKey;
    
    // Map the boolean permission flags (Read, Update, Delete)
    acl.entity_get = r;
    acl.entity_update = u;
    acl.entity_delete = d;

    // Save the record to the database.
    // Because of the logic in the parent method, this will act as an INSERT 
    // if 'acl' is a new entity, or an UPDATE if 'acl' was fetched from the database.
    PUT acl;
}