rxerces 0.6.0 → 0.7.0

data/ext/rxerces/rxerces.cpp

@@ -1,8 +1,10 @@
 #include "rxerces.h"
+#include <ruby/encoding.h>
 #include <xercesc/util/PlatformUtils.hpp>
 #include <xercesc/parsers/XercesDOMParser.hpp>
 #include <xercesc/dom/DOM.hpp>
 #include <xercesc/util/XMLString.hpp>
+#include <xercesc/util/XMLUni.hpp>
 #include <xercesc/framework/MemBufInputSource.hpp>
 #include <xercesc/framework/MemBufFormatTarget.hpp>
 #include <xercesc/util/XercesDefs.hpp>
@@ -10,8 +12,12 @@
 #include <xercesc/dom/DOMXPathExpression.hpp>
 #include <xercesc/sax/ErrorHandler.hpp>
 #include <xercesc/sax/SAXParseException.hpp>
+#include <xercesc/sax/SAXException.hpp>
 #include <sstream>
 #include <vector>
+#include <mutex>
+#include <list>
+#include <unordered_map>
 
 #ifdef HAVE_XALAN
 #include <xalanc/XPath/XPathEvaluator.hpp>
@@ -50,6 +56,17 @@ static bool xerces_initialized = false;
 #ifdef HAVE_XALAN
 static bool xalan_initialized = false;
 #endif
+static std::mutex init_mutex;
+
+// XPath validation cache with LRU eviction
+// Uses a list for LRU ordering (front = most recently used)
+// and a map for O(1) lookup of list iterators
+static std::list<std::string>* xpath_cache_lru_list = nullptr;
+static std::unordered_map<std::string, std::list<std::string>::iterator>* xpath_cache_map = nullptr;
+static std::mutex xpath_cache_mutex;
+static bool cache_xpath_validation = true;  // Default: enabled
+static size_t xpath_cache_max_size = 10000; // Max cached expressions
+static size_t xpath_max_length = 10000;     // Max XPath expression length
 
 // Forward declarations
 static std::string css_to_xpath(const char* css);
@@ -63,6 +80,12 @@ static void ensure_xerces_initialized() {
         return;
     }
 
+    std::lock_guard<std::mutex> lock(init_mutex);
+
+    if (xerces_initialized) {
+        return;
+    }
+
     try {
         XMLPlatformUtils::Initialize();
 #ifdef HAVE_XALAN
@@ -80,6 +103,16 @@ static void ensure_xerces_initialized() {
 
 // Cleanup function called at exit
 static void cleanup_xerces() {
+    // Clean up XPath validation cache (LRU)
+    if (xpath_cache_lru_list) {
+        delete xpath_cache_lru_list;
+        xpath_cache_lru_list = nullptr;
+    }
+    if (xpath_cache_map) {
+        delete xpath_cache_map;
+        xpath_cache_map = nullptr;
+    }
+
 #ifdef HAVE_XALAN
     if (xalan_initialized) {
         XPathEvaluator::terminate();
@@ -92,6 +125,167 @@ static void cleanup_xerces() {
     }
 }
 
+// Validate XPath expression to prevent XPath injection attacks
+static void validate_xpath_expression(const char* xpath_str) {
+    if (!xpath_str || strlen(xpath_str) == 0) {
+        rb_raise(rb_eArgError, "XPath expression cannot be empty");
+    }
+
+    std::string xpath(xpath_str);
+
+    // Check cache first if caching is enabled (LRU cache)
+    if (cache_xpath_validation) {
+        std::lock_guard<std::mutex> lock(xpath_cache_mutex);
+        if (!xpath_cache_lru_list) {
+            xpath_cache_lru_list = new std::list<std::string>();
+        }
+        if (!xpath_cache_map) {
+            xpath_cache_map = new std::unordered_map<std::string, std::list<std::string>::iterator>();
+        }
+        auto it = xpath_cache_map->find(xpath);
+        if (it != xpath_cache_map->end()) {
+            // Cache hit: move to front (most recently used)
+            xpath_cache_lru_list->splice(xpath_cache_lru_list->begin(), *xpath_cache_lru_list, it->second);
+            return; // Already validated
+        }
+    }
+    size_t len = xpath.length();
+
+    // Check for excessively long XPath expressions (potential DoS)
+    if (xpath_max_length > 0 && len > xpath_max_length) {
+        rb_raise(rb_eArgError, "XPath expression is too long (max %zu characters)", xpath_max_length);
+    }
+
+    // Check for dangerous patterns that could indicate XPath injection
+    // These patterns are commonly used in XPath injection attacks
+
+    // 1. Check for unbalanced quotes which could break out of string literals
+    int single_quotes = 0;
+    int double_quotes = 0;
+    bool in_single_quote = false;
+    bool in_double_quote = false;
+
+    for (size_t i = 0; i < len; i++) {
+        char c = xpath[i];
+
+        // Track quote state
+        if (c == '\'' && !in_double_quote) {
+            in_single_quote = !in_single_quote;
+            single_quotes++;
+        } else if (c == '"' && !in_single_quote) {
+            in_double_quote = !in_double_quote;
+            double_quotes++;
+        }
+    }
+
+    // Unbalanced quotes are suspicious
+    if (single_quotes % 2 != 0 || double_quotes % 2 != 0) {
+        rb_raise(rb_eArgError, "XPath expression contains unbalanced quotes");
+    }
+
+    // 2. Check for suspicious comment patterns that could be used to bypass validation
+    if (xpath.find("(:") != std::string::npos || xpath.find(":)") != std::string::npos) {
+        rb_raise(rb_eArgError, "XPath expression contains suspicious comment patterns");
+    }
+
+    // 3. Check for null bytes which could truncate validation
+    if (xpath.find('\0') != std::string::npos) {
+        rb_raise(rb_eArgError, "XPath expression contains null bytes");
+    }
+
+    // 4. Check for excessive nesting which could cause stack overflow
+    int bracket_depth = 0;
+    int paren_depth = 0;
+    const int MAX_DEPTH = 100;
+
+    for (size_t i = 0; i < len; i++) {
+        char c = xpath[i];
+
+        if (c == '[') bracket_depth++;
+        else if (c == ']') bracket_depth--;
+        else if (c == '(') paren_depth++;
+        else if (c == ')') paren_depth--;
+
+        if (bracket_depth > MAX_DEPTH || paren_depth > MAX_DEPTH) {
+            rb_raise(rb_eArgError, "XPath expression has excessive nesting depth");
+        }
+
+        if (bracket_depth < 0 || paren_depth < 0) {
+            rb_raise(rb_eArgError, "XPath expression has unbalanced brackets or parentheses");
+        }
+    }
+
+    if (bracket_depth != 0 || paren_depth != 0) {
+        rb_raise(rb_eArgError, "XPath expression has unbalanced brackets or parentheses");
+    }
+
+    // 5. Check for suspicious function calls that could access system functions
+    // or perform dangerous operations
+    std::vector<std::string> dangerous_patterns = {
+        "document(",       // Can access external documents
+        "doc(",            // Can access external documents
+        "collection(",     // Can access external collections
+        "unparsed-text(", // Can read arbitrary files
+        "system-property(", // Can leak system information
+        "environment-variable(", // Can leak environment variables
+    };
+
+    for (const auto& pattern : dangerous_patterns) {
+        if (xpath.find(pattern) != std::string::npos) {
+            rb_raise(rb_eArgError, "XPath expression contains potentially dangerous function: %s", pattern.c_str());
+        }
+    }
+
+    // 6. Check for encoded characters that could bypass validation
+    // Use specific patterns to avoid false positives (e.g., "Q&A" in text)
+    if (xpath.find("&#") != std::string::npos ||    // Numeric character reference (&#60;)
+        xpath.find("&#x") != std::string::npos ||   // Hex character reference (&#x3C;)
+        xpath.find("&amp;#") != std::string::npos) { // Encoded entity reference
+        rb_raise(rb_eArgError, "XPath expression contains encoded characters");
+    }
+
+    // 7. Detect potential boolean-based blind XPath injection patterns
+    // These patterns use 'or' with always-true conditions
+    std::vector<std::string> injection_patterns = {
+        "or 1=1",
+        "or '1'='1'",
+        "or \"1\"=\"1\"",
+        "or true()",
+        "and 1=0",
+        "and false()",
+        "or 'a'='a'",
+        "or \"a\"=\"a\"",
+    };
+
+    // Convert to lowercase for case-insensitive comparison
+    std::string xpath_lower = xpath;
+    std::transform(xpath_lower.begin(), xpath_lower.end(), xpath_lower.begin(), ::tolower);
+
+    for (const auto& pattern : injection_patterns) {
+        if (xpath_lower.find(pattern) != std::string::npos) {
+            rb_raise(rb_eArgError, "XPath expression contains suspicious injection pattern");
+        }
+    }
+
+    // Add to cache if caching is enabled (LRU eviction)
+    if (cache_xpath_validation) {
+        std::lock_guard<std::mutex> lock(xpath_cache_mutex);
+        if (xpath_cache_lru_list && xpath_cache_map) {
+            // If cache is full, evict least recently used (back of list)
+            if (xpath_cache_max_size > 0 && xpath_cache_map->size() >= xpath_cache_max_size) {
+                std::string& lru = xpath_cache_lru_list->back();
+                xpath_cache_map->erase(lru);
+                xpath_cache_lru_list->pop_back();
+            }
+            // Add new entry to front (most recently used)
+            if (xpath_cache_max_size > 0) {
+                xpath_cache_lru_list->push_front(xpath);
+                (*xpath_cache_map)[xpath] = xpath_cache_lru_list->begin();
+            }
+        }
+    }
+}
+
 // Helper class to manage XMLCh strings
 class XStr {
 public:
@@ -353,35 +547,110 @@ static VALUE wrap_node(DOMNode* node, VALUE doc_ref) {
         return Qnil;
     }
 
-    NodeWrapper* wrapper = ALLOC(NodeWrapper);
-    wrapper->node = node;
-    wrapper->doc_ref = doc_ref;
-
-    VALUE rb_node;
-
+    VALUE rb_class;
     switch (node->getNodeType()) {
         case DOMNode::ELEMENT_NODE:
-            rb_node = TypedData_Wrap_Struct(rb_cElement, &node_type, wrapper);
+            rb_class = rb_cElement;
             break;
         case DOMNode::TEXT_NODE:
-            rb_node = TypedData_Wrap_Struct(rb_cText, &node_type, wrapper);
+            rb_class = rb_cText;
             break;
         default:
-            rb_node = TypedData_Wrap_Struct(rb_cNode, &node_type, wrapper);
+            rb_class = rb_cNode;
             break;
     }
 
+    VALUE rb_node = TypedData_Wrap_Struct(rb_class, &node_type, NULL);
+    NodeWrapper* wrapper = ALLOC(NodeWrapper);
+    wrapper->node = node;
+    wrapper->doc_ref = doc_ref;
+    DATA_PTR(rb_node) = wrapper;
+
     return rb_node;
 }
 
-// RXerces::XML::Document.parse(string)
-static VALUE document_parse(VALUE klass, VALUE str) {
+// RXerces::XML::Document.parse(string, options = {})
+// Validate options hash for document_parse - only allow known keys
+static void validate_parse_options(VALUE options) {
+    if (NIL_P(options)) {
+        return;
+    }
+
+    Check_Type(options, T_HASH);
+
+    // Define allowed option keys
+    std::vector<const char*> allowed_keys = {
+        "allow_external_entities"
+    };
+
+    // Get all keys from the provided options hash
+    VALUE keys = rb_funcall(options, rb_intern("keys"), 0);
+    long keys_len = RARRAY_LEN(keys);
+
+    // Check each key against the allowed list
+    for (long i = 0; i < keys_len; i++) {
+        VALUE key = rb_ary_entry(keys, i);
+
+        // Convert symbol or string key to string for comparison
+        VALUE key_str;
+        if (TYPE(key) == T_SYMBOL) {
+            key_str = rb_sym_to_s(key);
+        } else if (TYPE(key) == T_STRING) {
+            key_str = key;
+        } else {
+            rb_raise(rb_eArgError, "Option keys must be symbols or strings");
+        }
+
+        const char* key_cstr = StringValueCStr(key_str);
+        bool found = false;
+
+        for (const auto& allowed : allowed_keys) {
+            if (strcmp(key_cstr, allowed) == 0) {
+                found = true;
+                break;
+            }
+        }
+
+        if (!found) {
+            rb_raise(rb_eArgError, "Unknown option: %s. Allowed options are: allow_external_entities", key_cstr);
+        }
+    }
+}
+
+static VALUE document_parse(int argc, VALUE* argv, VALUE klass) {
+    VALUE str, options;
+    rb_scan_args(argc, argv, "11", &str, &options);
+
     ensure_xerces_initialized();
 
     Check_Type(str, T_STRING);
     const char* xml_str = StringValueCStr(str);
 
+    // Validate options hash before processing
+    validate_parse_options(options);
+
     XercesDOMParser* parser = new XercesDOMParser();
+
+    // Check if external entities should be allowed (default: false for security)
+    bool allow_external = false;
+    if (!NIL_P(options)) {
+        VALUE allow_key = rb_intern("allow_external_entities");
+        VALUE allow_val = rb_hash_aref(options, ID2SYM(allow_key));
+        if (RTEST(allow_val)) {
+            allow_external = true;
+        }
+    }
+
+    if (allow_external) {
+        // Allow external entities (less secure)
+        parser->setLoadExternalDTD(true);
+        parser->setDisableDefaultEntityResolution(false);
+    } else {
+        // Security: Disable external entity processing to prevent XXE attacks
+        parser->setLoadExternalDTD(false);
+        parser->setDisableDefaultEntityResolution(true);
+    }
+
     parser->setValidationScheme(XercesDOMParser::Val_Never);
     parser->setDoNamespaces(true);
     parser->setDoSchema(false);
@@ -485,8 +754,16 @@ static VALUE document_to_s(VALUE self) {
         serializer->release();
 
         return result;
+    } catch (const DOMException& e) {
+        CharStr message(e.getMessage());
+        rb_raise(rb_eRuntimeError, "Failed to serialize document: %s", message.localForm());
+    } catch (const XMLException& e) {
+        CharStr message(e.getMessage());
+        rb_raise(rb_eRuntimeError, "Failed to serialize document (XMLException): %s", message.localForm());
+    } catch (const std::exception& e) {
+        rb_raise(rb_eRuntimeError, "Failed to serialize document (std::exception): %s", e.what());
     } catch (...) {
-        rb_raise(rb_eRuntimeError, "Failed to serialize document");
+        rb_raise(rb_eRuntimeError, "Failed to serialize document (unknown exception type)");
     }
 
     return Qnil;
@@ -608,9 +885,103 @@ static VALUE document_create_element(VALUE self, VALUE name) {
     return Qnil;
 }
 
+// document.children - returns all children (elements, text, comments, etc.)
+static VALUE document_children(VALUE self) {
+    DocumentWrapper* wrapper;
+    TypedData_Get_Struct(self, DocumentWrapper, &document_type, wrapper);
+
+    VALUE children = rb_ary_new();
+
+    if (!wrapper->doc) {
+        return children;
+    }
+
+    DOMNodeList* child_nodes = wrapper->doc->getChildNodes();
+    XMLSize_t count = child_nodes->getLength();
+
+    for (XMLSize_t i = 0; i < count; i++) {
+        DOMNode* child = child_nodes->item(i);
+        rb_ary_push(children, wrap_node(child, self));
+    }
+
+    return children;
+}
+
+// document.element_children - returns only element children (no text nodes, comments, etc.)
+static VALUE document_element_children(VALUE self) {
+    DocumentWrapper* wrapper;
+    TypedData_Get_Struct(self, DocumentWrapper, &document_type, wrapper);
+
+    VALUE children = rb_ary_new();
+
+    if (!wrapper->doc) {
+        return children;
+    }
+
+    DOMNodeList* child_nodes = wrapper->doc->getChildNodes();
+    XMLSize_t count = child_nodes->getLength();
+
+    for (XMLSize_t i = 0; i < count; i++) {
+        DOMNode* child = child_nodes->item(i);
+        if (child->getNodeType() == DOMNode::ELEMENT_NODE) {
+            rb_ary_push(children, wrap_node(child, self));
+        }
+    }
+
+    return children;
+}
+
+// document.first_element_child - returns first element child
+static VALUE document_first_element_child(VALUE self) {
+    DocumentWrapper* wrapper;
+    TypedData_Get_Struct(self, DocumentWrapper, &document_type, wrapper);
+
+    if (!wrapper->doc) {
+        return Qnil;
+    }
+
+    DOMNodeList* child_nodes = wrapper->doc->getChildNodes();
+    XMLSize_t count = child_nodes->getLength();
+
+    for (XMLSize_t i = 0; i < count; i++) {
+        DOMNode* child = child_nodes->item(i);
+        if (child->getNodeType() == DOMNode::ELEMENT_NODE) {
+            return wrap_node(child, self);
+        }
+    }
+
+    return Qnil;
+}
+
+// document.last_element_child - returns last element child
+static VALUE document_last_element_child(VALUE self) {
+    DocumentWrapper* wrapper;
+    TypedData_Get_Struct(self, DocumentWrapper, &document_type, wrapper);
+
+    if (!wrapper->doc) {
+        return Qnil;
+    }
+
+    DOMNodeList* child_nodes = wrapper->doc->getChildNodes();
+    XMLSize_t count = child_nodes->getLength();
+
+    // Search backwards for last element
+    for (XMLSize_t i = count; i > 0; i--) {
+        DOMNode* child = child_nodes->item(i - 1);
+        if (child->getNodeType() == DOMNode::ELEMENT_NODE) {
+            return wrap_node(child, self);
+        }
+    }
+
+    return Qnil;
+}
+
 #ifdef HAVE_XALAN
 // Helper function to execute XPath using Xalan for full XPath 1.0 support
 static VALUE execute_xpath_with_xalan(DOMNode* context_node, const char* xpath_str, VALUE doc_ref) {
+    // Validate XPath expression before execution
+    validate_xpath_expression(xpath_str);
+
     ensure_xerces_initialized();
 
     try {
@@ -718,6 +1089,9 @@ static VALUE document_xpath(VALUE self, VALUE path) {
     Check_Type(path, T_STRING);
     const char* xpath_str = StringValueCStr(path);
 
+    // Validate XPath expression before execution
+    validate_xpath_expression(xpath_str);
+
 #ifdef HAVE_XALAN
     // Use Xalan for full XPath 1.0 support
     DOMElement* root = doc_wrapper->doc->getDocumentElement();
@@ -782,6 +1156,19 @@ static VALUE document_xpath(VALUE self, VALUE path) {
 #endif
 }
 
+// document.at_xpath(path) - returns first matching node or nil
+static VALUE document_at_xpath(VALUE self, VALUE path) {
+    VALUE nodeset = document_xpath(self, path);
+    NodeSetWrapper* wrapper;
+    TypedData_Get_Struct(nodeset, NodeSetWrapper, &nodeset_type, wrapper);
+
+    if (RARRAY_LEN(wrapper->nodes_array) == 0) {
+        return Qnil;
+    }
+
+    return rb_ary_entry(wrapper->nodes_array, 0);
+}
+
 // document.css(selector) - Convert CSS to XPath and execute
 static VALUE document_css(VALUE self, VALUE selector) {
     Check_Type(selector, T_STRING);
@@ -1104,6 +1491,65 @@ static VALUE node_element_children(VALUE self) {
     return children;
 }
 
+// node.first_element_child - returns first element child
+static VALUE node_first_element_child(VALUE self) {
+    NodeWrapper* wrapper;
+    TypedData_Get_Struct(self, NodeWrapper, &node_type, wrapper);
+
+    if (!wrapper->node) {
+        return Qnil;
+    }
+
+    VALUE doc_ref = wrapper->doc_ref;
+    DOMNodeList* child_nodes = wrapper->node->getChildNodes();
+    XMLSize_t count = child_nodes->getLength();
+
+    for (XMLSize_t i = 0; i < count; i++) {
+        DOMNode* child = child_nodes->item(i);
+        if (child->getNodeType() == DOMNode::ELEMENT_NODE) {
+            return wrap_node(child, doc_ref);
+        }
+    }
+
+    return Qnil;
+}
+
+// node.last_element_child - returns last element child
+static VALUE node_last_element_child(VALUE self) {
+    NodeWrapper* wrapper;
+    TypedData_Get_Struct(self, NodeWrapper, &node_type, wrapper);
+
+    if (!wrapper->node) {
+        return Qnil;
+    }
+
+    VALUE doc_ref = wrapper->doc_ref;
+    DOMNodeList* child_nodes = wrapper->node->getChildNodes();
+    XMLSize_t count = child_nodes->getLength();
+
+    // Search backwards for last element
+    for (XMLSize_t i = count; i > 0; i--) {
+        DOMNode* child = child_nodes->item(i - 1);
+        if (child->getNodeType() == DOMNode::ELEMENT_NODE) {
+            return wrap_node(child, doc_ref);
+        }
+    }
+
+    return Qnil;
+}
+
+// node.document - returns the document that owns this node
+static VALUE node_document(VALUE self) {
+    NodeWrapper* wrapper;
+    TypedData_Get_Struct(self, NodeWrapper, &node_type, wrapper);
+
+    if (!wrapper->node) {
+        return Qnil;
+    }
+
+    return wrapper->doc_ref;
+}
+
 // node.parent
 static VALUE node_parent(VALUE self) {
     NodeWrapper* wrapper;
@@ -1231,6 +1677,37 @@ static VALUE node_attributes(VALUE self) {
     return hash;
 }
 
+// node.attribute_nodes - returns array of attribute nodes (only for element nodes)
+static VALUE node_attribute_nodes(VALUE self) {
+    NodeWrapper* wrapper;
+    TypedData_Get_Struct(self, NodeWrapper, &node_type, wrapper);
+
+    VALUE nodes_array = rb_ary_new();
+
+    if (!wrapper->node || wrapper->node->getNodeType() != DOMNode::ELEMENT_NODE) {
+        return nodes_array;
+    }
+
+    DOMElement* element = dynamic_cast<DOMElement*>(wrapper->node);
+    DOMNamedNodeMap* attributes = element->getAttributes();
+
+    if (!attributes) {
+        return nodes_array;
+    }
+
+    VALUE doc_ref = wrapper->doc_ref;
+    XMLSize_t length = attributes->getLength();
+
+    for (XMLSize_t i = 0; i < length; i++) {
+        DOMNode* attr = attributes->item(i);
+        if (attr) {
+            rb_ary_push(nodes_array, wrap_node(attr, doc_ref));
+        }
+    }
+
+    return nodes_array;
+}
+
 // node.next_sibling
 static VALUE node_next_sibling(VALUE self) {
     NodeWrapper* wrapper;
@@ -1330,7 +1807,7 @@ static VALUE node_add_child(VALUE self, VALUE child) {
     }
 
     DOMNode* child_node = NULL;
-    bool needs_import = false;
+    VALUE doc_ref = wrapper->doc_ref;  // Keep track of the Ruby document reference
 
     // Check if child is a string or a node
     if (TYPE(child) == T_STRING) {
@@ -1344,13 +1821,27 @@ static VALUE node_add_child(VALUE self, VALUE child) {
         NodeWrapper* child_wrapper;
         if (rb_obj_is_kind_of(child, rb_cNode)) {
             TypedData_Get_Struct(child, NodeWrapper, &node_type, child_wrapper);
-            child_node = child_wrapper->node;
+            DOMNode* original_child = child_wrapper->node;
 
             // Check if child belongs to a different document
-            DOMDocument* child_doc = child_node->getOwnerDocument();
+            DOMDocument* child_doc = original_child->getOwnerDocument();
             if (child_doc && child_doc != doc) {
-                rb_raise(rb_eRuntimeError,
-                    "Node belongs to a different document. Use importNode to adopt nodes from other documents.");
+                // Automatically import the node from the other document
+                // The second parameter 'true' means deep copy (include all descendants)
+                try {
+                    child_node = doc->importNode(original_child, true);
+
+                    // Update the child wrapper to point to the imported node
+                    // and the new document reference
+                    child_wrapper->node = child_node;
+                    child_wrapper->doc_ref = doc_ref;
+                } catch (const DOMException& e) {
+                    CharStr message(e.getMessage());
+                    rb_raise(rb_eRuntimeError, "Failed to import node from different document: %s",
+                             message.localForm());
+                }
+            } else {
+                child_node = original_child;
             }
         } else {
             rb_raise(rb_eTypeError, "Argument must be a String or Node");
@@ -1589,6 +2080,9 @@ static VALUE node_xpath(VALUE self, VALUE path) {
     const char* xpath_str = StringValueCStr(path);
     VALUE doc_ref = node_wrapper->doc_ref;
 
+    // Validate XPath expression before execution
+    validate_xpath_expression(xpath_str);
+
 #ifdef HAVE_XALAN
     // Use Xalan for full XPath 1.0 support
     return execute_xpath_with_xalan(node_wrapper->node, xpath_str, doc_ref);
@@ -1958,6 +2452,31 @@ static VALUE nodeset_text(VALUE self) {
 }
 
 // nodeset.inspect / nodeset.to_s - human-readable representation
+// Helper function to safely truncate UTF-8 strings using Ruby's built-in UTF-8 handling
+// Ruby's rb_str_substr operates on CHARACTER positions, not byte positions
+static std::string safe_truncate_utf8(const std::string& str, long max_chars) {
+    if (str.empty()) {
+        return str;
+    }
+
+    // Create a Ruby string with UTF-8 encoding
+    VALUE rb_str = rb_enc_str_new(str.c_str(), str.length(), rb_utf8_encoding());
+
+    // Get the character length (not byte length)
+    long char_len = RSTRING_LEN(rb_str);
+
+    if (char_len <= max_chars) {
+        return str;
+    }
+
+    // Use Ruby's rb_str_substr which correctly handles multi-byte characters
+    // Parameters: string, start position (in characters), length (in characters)
+    VALUE truncated = rb_str_substr(rb_str, 0, max_chars);
+
+    // Convert back to C++ string
+    return std::string(RSTRING_PTR(truncated), RSTRING_LEN(truncated));
+}
+
 static VALUE nodeset_inspect(VALUE self) {
     NodeSetWrapper* wrapper;
     TypedData_Get_Struct(self, NodeSetWrapper, &nodeset_type, wrapper);
@@ -2028,7 +2547,7 @@ static VALUE nodeset_inspect(VALUE self) {
                     textStr = textStr.substr(start, end - start + 1);
 
                     if (textStr.length() > 30) {
-                        textStr = textStr.substr(0, 27) + "...";
+                        textStr = safe_truncate_utf8(textStr, 27) + "...";
                     }
 
                     result += ">";
@@ -2056,7 +2575,7 @@ static VALUE nodeset_inspect(VALUE self) {
                     textStr = textStr.substr(start, end - start + 1);
 
                     if (textStr.length() > 30) {
-                        textStr = textStr.substr(0, 27) + "...";
+                        textStr = safe_truncate_utf8(textStr, 27) + "...";
                     }
 
                     result += "text(\"";
@@ -2078,7 +2597,10 @@ static VALUE nodeset_inspect(VALUE self) {
     }
 
     result += "]>";
-    return rb_str_new_cstr(result.c_str());
+    VALUE rb_result = rb_str_new_cstr(result.c_str());
+    // Ensure the string is marked as UTF-8 encoded
+    rb_enc_associate(rb_result, rb_utf8_encoding());
+    return rb_result;
 }
 
 // Schema.from_document(schema_doc) or Schema.from_string(xsd_string)
@@ -2119,6 +2641,18 @@ static VALUE schema_from_document(int argc, VALUE* argv, VALUE klass) {
 
         try {
             schemaParser->parse(schemaInput);
+        } catch (const XMLException& e) {
+            delete schemaParser;
+            delete wrapper->schemaContent;
+            xfree(wrapper);
+            CharStr message(e.getMessage());
+            rb_raise(rb_eRuntimeError, "Schema parsing failed: %s", message.localForm());
+        } catch (const SAXException& e) {
+            delete schemaParser;
+            delete wrapper->schemaContent;
+            xfree(wrapper);
+            CharStr message(e.getMessage());
+            rb_raise(rb_eRuntimeError, "Schema parsing failed: %s", message.localForm());
         } catch (...) {
             delete schemaParser;
             delete wrapper->schemaContent;
@@ -2200,6 +2734,12 @@ static VALUE document_validate(VALUE self, VALUE rb_schema) {
             validator->loadGrammar(schemaSource, Grammar::SchemaGrammarType, true);
             validator->setExternalNoNamespaceSchemaLocation("schema.xsd");
             validator->useCachedGrammarInParse(true);
+        } catch (const XMLException& e) {
+            CharStr message(e.getMessage());
+            errorHandler.errors.push_back(std::string("Warning: Schema grammar could not be loaded: ") + message.localForm());
+        } catch (const SAXException& e) {
+            CharStr message(e.getMessage());
+            errorHandler.errors.push_back(std::string("Warning: Schema grammar could not be loaded: ") + message.localForm());
         } catch (...) {
             // If grammar loading fails, just note it
             errorHandler.errors.push_back("Warning: Schema grammar could not be loaded");
@@ -2251,25 +2791,129 @@ static VALUE document_validate(VALUE self, VALUE rb_schema) {
     }
 
     return Qnil;
-}extern "C" void Init_rxerces(void) {
+}
+
+// RXerces.cache_xpath_validation? - check if XPath validation caching is enabled
+static VALUE rxerces_cache_xpath_validation_p(VALUE self) {
+    return cache_xpath_validation ? Qtrue : Qfalse;
+}
+
+// RXerces.cache_xpath_validation = bool - enable/disable XPath validation caching
+static VALUE rxerces_set_cache_xpath_validation(VALUE self, VALUE val) {
+    cache_xpath_validation = RTEST(val);
+    return val;
+}
+
+// RXerces.clear_xpath_validation_cache - clear the XPath validation cache
+static VALUE rxerces_clear_xpath_validation_cache(VALUE self) {
+    std::lock_guard<std::mutex> lock(xpath_cache_mutex);
+    if (xpath_cache_lru_list) {
+        xpath_cache_lru_list->clear();
+    }
+    if (xpath_cache_map) {
+        xpath_cache_map->clear();
+    }
+    return Qnil;
+}
+
+// RXerces.xpath_validation_cache_size - return number of cached expressions
+static VALUE rxerces_xpath_validation_cache_size(VALUE self) {
+    std::lock_guard<std::mutex> lock(xpath_cache_mutex);
+    if (!xpath_cache_map) {
+        return LONG2NUM(0);
+    }
+    return LONG2NUM((long)xpath_cache_map->size());
+}
+
+// RXerces.xpath_validation_cache_max_size - get max cache size
+static VALUE rxerces_xpath_validation_cache_max_size(VALUE self) {
+    return LONG2NUM((long)xpath_cache_max_size);
+}
+
+// RXerces.xpath_validation_cache_max_size = n - set max cache size
+static VALUE rxerces_set_xpath_validation_cache_max_size(VALUE self, VALUE val) {
+    // Validate input: must be a non-negative integer
+    if (!RB_INTEGER_TYPE_P(val)) {
+        rb_raise(rb_eTypeError, "xpath_validation_cache_max_size must be an Integer");
+    }
+
+    long size = NUM2LONG(val);
+    if (size < 0) {
+        rb_raise(rb_eArgError, "xpath_validation_cache_max_size must be non-negative");
+    }
+
+    xpath_cache_max_size = (size_t)size;
+    return val;
+}
+
+// RXerces.xalan_enabled? - check if Xalan is available
+static VALUE rxerces_xalan_enabled_p(VALUE self) {
+#ifdef HAVE_XALAN
+    return Qtrue;
+#else
+    return Qfalse;
+#endif
+}
+
+// RXerces.xpath_max_length - get max XPath expression length
+static VALUE rxerces_xpath_max_length(VALUE self) {
+    return LONG2NUM((long)xpath_max_length);
+}
+
+// RXerces.xpath_max_length = n - set max XPath expression length (0 = no limit)
+static VALUE rxerces_set_xpath_max_length(VALUE self, VALUE val) {
+    // Validate input: must be a non-negative integer
+    if (!RB_INTEGER_TYPE_P(val)) {
+        rb_raise(rb_eTypeError, "xpath_max_length must be an Integer");
+    }
+
+    long size = NUM2LONG(val);
+    if (size < 0) {
+        rb_raise(rb_eArgError, "xpath_max_length must be non-negative");
+    }
+
+    xpath_max_length = (size_t)size;
+    return val;
+}
+
+extern "C" void Init_rxerces(void) {
     rb_mRXerces = rb_define_module("RXerces");
+
+    // Module-level configuration methods for XPath validation caching
+    rb_define_singleton_method(rb_mRXerces, "cache_xpath_validation?", RUBY_METHOD_FUNC(rxerces_cache_xpath_validation_p), 0);
+    rb_define_singleton_method(rb_mRXerces, "cache_xpath_validation=", RUBY_METHOD_FUNC(rxerces_set_cache_xpath_validation), 1);
+    rb_define_singleton_method(rb_mRXerces, "clear_xpath_validation_cache", RUBY_METHOD_FUNC(rxerces_clear_xpath_validation_cache), 0);
+    rb_define_singleton_method(rb_mRXerces, "xpath_validation_cache_size", RUBY_METHOD_FUNC(rxerces_xpath_validation_cache_size), 0);
+    rb_define_singleton_method(rb_mRXerces, "xpath_validation_cache_max_size", RUBY_METHOD_FUNC(rxerces_xpath_validation_cache_max_size), 0);
+    rb_define_singleton_method(rb_mRXerces, "xpath_validation_cache_max_size=", RUBY_METHOD_FUNC(rxerces_set_xpath_validation_cache_max_size), 1);
+    rb_define_singleton_method(rb_mRXerces, "xpath_max_length", RUBY_METHOD_FUNC(rxerces_xpath_max_length), 0);
+    rb_define_singleton_method(rb_mRXerces, "xpath_max_length=", RUBY_METHOD_FUNC(rxerces_set_xpath_max_length), 1);
+    rb_define_singleton_method(rb_mRXerces, "xalan_enabled?", RUBY_METHOD_FUNC(rxerces_xalan_enabled_p), 0);
+
     rb_mXML = rb_define_module_under(rb_mRXerces, "XML");
 
     rb_cDocument = rb_define_class_under(rb_mXML, "Document", rb_cObject);
     rb_undef_alloc_func(rb_cDocument);
-    rb_define_singleton_method(rb_cDocument, "parse", RUBY_METHOD_FUNC(document_parse), 1);
+    rb_define_singleton_method(rb_cDocument, "parse", RUBY_METHOD_FUNC(document_parse), -1);
     rb_define_method(rb_cDocument, "root", RUBY_METHOD_FUNC(document_root), 0);
     rb_define_method(rb_cDocument, "errors", RUBY_METHOD_FUNC(document_errors), 0);
     rb_define_method(rb_cDocument, "to_s", RUBY_METHOD_FUNC(document_to_s), 0);
     rb_define_alias(rb_cDocument, "to_xml", "to_s");
     rb_define_method(rb_cDocument, "inspect", RUBY_METHOD_FUNC(document_inspect), 0);
     rb_define_method(rb_cDocument, "xpath", RUBY_METHOD_FUNC(document_xpath), 1);
+    rb_define_method(rb_cDocument, "at_xpath", RUBY_METHOD_FUNC(document_at_xpath), 1);
+    rb_define_alias(rb_cDocument, "at", "at_xpath");
     rb_define_method(rb_cDocument, "css", RUBY_METHOD_FUNC(document_css), 1);
     rb_define_method(rb_cDocument, "at_css", RUBY_METHOD_FUNC(document_at_css), 1);
     rb_define_method(rb_cDocument, "encoding", RUBY_METHOD_FUNC(document_encoding), 0);
     rb_define_method(rb_cDocument, "text", RUBY_METHOD_FUNC(document_text), 0);
     rb_define_alias(rb_cDocument, "content", "text");
     rb_define_method(rb_cDocument, "create_element", RUBY_METHOD_FUNC(document_create_element), 1);
+    rb_define_method(rb_cDocument, "children", RUBY_METHOD_FUNC(document_children), 0);
+    rb_define_method(rb_cDocument, "element_children", RUBY_METHOD_FUNC(document_element_children), 0);
+    rb_define_alias(rb_cDocument, "elements", "element_children");
+    rb_define_method(rb_cDocument, "first_element_child", RUBY_METHOD_FUNC(document_first_element_child), 0);
+    rb_define_method(rb_cDocument, "last_element_child", RUBY_METHOD_FUNC(document_last_element_child), 0);
 
     rb_cNode = rb_define_class_under(rb_mXML, "Node", rb_cObject);
     rb_undef_alloc_func(rb_cNode);
@@ -2288,9 +2932,13 @@ static VALUE document_validate(VALUE self, VALUE rb_schema) {
     rb_define_method(rb_cNode, "children", RUBY_METHOD_FUNC(node_children), 0);
     rb_define_method(rb_cNode, "element_children", RUBY_METHOD_FUNC(node_element_children), 0);
     rb_define_alias(rb_cNode, "elements", "element_children");
+    rb_define_method(rb_cNode, "first_element_child", RUBY_METHOD_FUNC(node_first_element_child), 0);
+    rb_define_method(rb_cNode, "last_element_child", RUBY_METHOD_FUNC(node_last_element_child), 0);
+    rb_define_method(rb_cNode, "document", RUBY_METHOD_FUNC(node_document), 0);
     rb_define_method(rb_cNode, "parent", RUBY_METHOD_FUNC(node_parent), 0);
     rb_define_method(rb_cNode, "ancestors", RUBY_METHOD_FUNC(node_ancestors), -1);
     rb_define_method(rb_cNode, "attributes", RUBY_METHOD_FUNC(node_attributes), 0);
+    rb_define_method(rb_cNode, "attribute_nodes", RUBY_METHOD_FUNC(node_attribute_nodes), 0);
     rb_define_method(rb_cNode, "next_sibling", RUBY_METHOD_FUNC(node_next_sibling), 0);
     rb_define_method(rb_cNode, "next_element", RUBY_METHOD_FUNC(node_next_element), 0);
     rb_define_method(rb_cNode, "previous_sibling", RUBY_METHOD_FUNC(node_previous_sibling), 0);