struct

Mica::XML::ParserOptions

Inherits Struct < Value < Object

Options for one parse: namespace processing, the safety limits and the work budget.

Every parse is secure by default. External DTD subsets and external entities are never fetched (the library has no network or file access), the limits below stop entity-expansion and nesting attacks early, and the work budget stops any input that would make parsing do more than a constant amount of work per byte.

options = Mica::XML::ParserOptions.new(max_element_depth: 64)
document = Mica::XML.parse(xml, options)

Constants

DEFAULT_WORK_BUDGET = Core::WorkBudget.new(operations_per_unit: 64, base_operations: 1000000, timeout: 60.seconds)

The default work budget for parsing: 64 operations per byte read (or expanded from an entity or a DTD default), plus 1,000,000, and at most 60 seconds of wall-clock time. Legitimate documents use well under a quarter of this allowance (see the README).

Constructors

default

Returns the default options.

new(namespace_aware : Bool = true, max_entity_expansions : Int32 = 10000, max_entity_expansion_bytes : Int64 = (16_i64 * 1024) * 1024, max_entity_depth : Int32 = 16, max_default_attributes : Int32 = 1000000, max_default_attribute_bytes : Int64 = (16_i64 * 1024) * 1024, max_element_depth : Int32 = 1024, max_name_bytes : Int32 = 50000, max_attributes : Int32 = 10000, max_token_bytes : Int32 = (10 * 1024) * 1024, max_input_bytes : Int64 | Nil = nil, work_budget : Core::WorkBudget = DEFAULT_WORK_BUDGET, check_normalization : Bool = false, allow_document_type : Bool = true)

Instance methods

allow_document_type?

Accepts a document type declaration. When false, the reader raises Mica::XML::DocumentTypeNotAllowedError as soon as it recognizes <!DOCTYPE, before it reads the internal subset or expands any parameter entity. Request bodies and other untrusted input that never needs a DTD should turn it off.

check_normalization?

Verifies XML 1.1 full normalization (section 2.13): every text, attribute value, comment, PI, CDATA section and name is in Unicode NFC, and none of them starts with a composing character. Raises Mica::XML::NormalizationError. Applies to XML 1.1 documents.

max_attributes

Maximum number of attributes on one element.

max_default_attribute_bytes

Maximum total bytes of attribute values added from DTD defaults in one document.

max_default_attributes

Maximum number of attributes added from DTD defaults in one document.

max_element_depth

Maximum element nesting depth.

max_entity_depth

Maximum nesting of entity references inside entity replacement text.

max_entity_expansion_bytes

Maximum total bytes produced by entity expansion in one document.

max_entity_expansions

Maximum number of entity references expanded in one document.

max_input_bytes

Maximum size in bytes of the whole input (decoded), or nil for no cap.

max_name_bytes

Maximum length in bytes of a single name (element, attribute, entity, PI target, name token).

max_token_bytes

Maximum size in bytes of one token: a text node, attribute value, comment, PI, CDATA section or the internal DTD subset.

namespace_aware?

Processes Namespaces in XML (prefix binding, QName syntax).

work_budget

The work budget and deadline every parse runs under. The deadline is checked at work-budget checkpoints, after every IO read that returns, and at the start and end of the parse; it bounds the parser's own work. A read from a blocking IO that never returns cannot be interrupted, so for a guaranteed wall-clock bound over an untrusted stream give the IO its own read timeout (for example Socket#read_timeout).