*/ private $forced = array(); /** * Unknowns gathered in one evaluation. * * @var array */ private $unknowns = array(); /** * Badges gathered in one evaluation. * * @var array */ private $badges = array(); /** * Whether an UNKNOWN came from an audience cond node. * * @var bool */ private $audience_unknown = false; /** * Value each evaluated condition returned, by path (for the Decided by line). * * @var array */ private $values = array(); /** * 1.1.0: resolution stack of group ids currently being resolved by * ancestors of the current node. Ancestor stack, not a visited set. * * @var array */ private $ref_stack = array(); /** * 1.1.0: resolved-node counter, incremented on every node() entry that is * not short-circuited by the forced-value check. Per occurrence. * * @var int */ private $resolved_nodes = 0; /** * 1.1.0: resolved depth (depth of the current node in the expanded tree). * * @var int */ private $resolved_depth = 0; /** * 1.1.0: set when the resolved limits have been exceeded; the walk checks * this after every child return and aborts the whole evaluation. * * @var bool */ private $over_limit = false; /** * Constructor. * * @param Registry|null $registry Registry. */ public function __construct( $registry = null ) { $this->registry = $registry ? $registry : Registry::instance(); } /** * Evaluate a rule into a decision record. * * @param Rule $rule Rule. * @param array $opts Options: simulated_visitor (bool). * @return Decision */ public function evaluate( Rule $rule, array $opts = array() ) { $this->simulated = ! empty( $opts['simulated_visitor'] ); $this->forced = isset( $opts['forced'] ) && is_array( $opts['forced'] ) ? $opts['forced'] : array(); $d = new Decision(); if ( Rule::STATE_NONE === $rule->state ) { $d->visible = true; $d->tree_result = null; return $d; } $this->unknowns = array(); $this->badges = array(); $this->audience_unknown = false; $this->values = array(); $this->ref_stack = array(); $this->resolved_nodes = 0; $this->resolved_depth = 0; $this->over_limit = false; if ( Rule::STATE_INVALID === $rule->state ) { $d->tree_result = Decision::U; $d->unknowns[] = array( 'path' => 'rule', 'reason' => 'invalid_rule', 'text' => $rule->invalid_reason, ); $audience = true; // An invalid rule cannot prove it is location-only. Fallback_Policy::apply( $rule, $d, $audience ); return $d; } if ( $rule->over_limit() ) { $d->tree_result = Decision::U; $d->unknowns[] = array( 'path' => 'tree', 'reason' => 'too_large', 'text' => '', ); Fallback_Policy::apply( $rule, $d, true ); return $d; } if ( ! empty( $rule->ext['gateforge']['unauthorized'] ) ) { // A block rule added or changed by a user below the block-rule capability (10.3 setting): kept, fails closed. $d->tree_result = Decision::U; $d->unknowns[] = array( 'path' => 'rule', 'reason' => 'unauthorized', 'text' => '', ); Fallback_Policy::apply( $rule, $d, true ); return $d; } if ( ! $this->registry->ensure_loaded() ) { $d->tree_result = Decision::U; $d->unknowns[] = array( 'path' => 'tree', 'reason' => 'condition_unavailable', 'text' => 'registry_not_ready', ); Fallback_Policy::apply( $rule, $d, true ); return $d; } list( $value, $by ) = $this->node( $rule->tree, 'tree' ); if ( $this->over_limit ) { // 1.1.0 §2.3.1: resolved-side over-limit aborts the whole evaluation // with a single too_large at path 'tree', exactly like the shipped // stored-tree over-limit path above. No partial result. $d->tree_result = Decision::U; $d->unknowns = array( array( 'path' => 'tree', 'reason' => 'too_large', 'text' => '', ), ); $d->badges = array(); $d->decided_by = null; $d->decided_value = null; Fallback_Policy::apply( $rule, $d, true ); return $d; } $d->tree_result = $value; $d->decided_by = $by; $d->decided_value = null === $by ? null : $this->value_at( $by ); $d->unknowns = $this->unknowns; $d->badges = $this->badges; if ( Decision::T === $value ) { $d->visible = true; } elseif ( Decision::F === $value ) { $d->visible = false; } else { $simulated_parts = array_filter( $this->unknowns, static function ( $u ) { return 'simulated_visitor' === $u['reason']; } ); if ( $this->simulated && count( $simulated_parts ) === count( $this->unknowns ) ) { // Explain mode: the real visitor's answer is not unknown; show both outcomes. $forced_true = $this->probe( $rule, $simulated_parts, Decision::T ); $forced_false = $this->probe( $rule, $simulated_parts, Decision::F ); $d->both_outcomes = array( 'if_true' => $forced_true, 'if_false' => $forced_false, ); $d->visible = $forced_true || $forced_false; $d->fallback_applied = null; return $d; } Fallback_Policy::apply( $rule, $d, $this->audience_unknown ); } return $d; } /** * Re-evaluate with simulated parts forced to a value. * * @param Rule $rule Rule. * @param array $parts Unknown parts. * @param string $value Forced value. * @return bool Visible. */ private function probe( Rule $rule, array $parts, $value ) { $forced = array(); foreach ( $parts as $p ) { $forced[ $p['path'] ] = $value; } $e = new self( $this->registry ); $r = $e->evaluate( $rule, array( 'forced' => $forced ) ); return $r->visible; } /** * Evaluate one node. * * @param mixed $node Node. * @param string $path Path. * @return array{0:string,1:string|null} */ private function node( $node, $path ) { if ( isset( $this->forced[ $path ] ) ) { $this->values[ $path ] = $this->forced[ $path ]; return array( $this->forced[ $path ], $path ); } // 1.1.0 §2.3.1: resolved-side accounting runs for every non-forced entry. // The forced check above returns early, so a forced ref node is never // expanded and never trips the counter — correct: a probe asks what // would happen if the ref were true/false, it does not evaluate it. ++$this->resolved_nodes; if ( $this->resolved_nodes > Rule::MAX_NODES ) { $this->over_limit = true; return array( Decision::U, null ); } $previous_depth = $this->resolved_depth; $this->resolved_depth = $previous_depth + 1; if ( $this->resolved_depth > Rule::MAX_DEPTH ) { $this->over_limit = true; $this->resolved_depth = $previous_depth; return array( Decision::U, null ); } if ( ! is_array( $node ) ) { $this->resolved_depth = $previous_depth; return $this->unknown( $path, 'unsupported_node', '', false ); } if ( array_key_exists( 'unknown', $node ) ) { $reason = isset( $node['reason'] ) && is_string( $node['reason'] ) ? $node['reason'] : 'unsupported_syntax'; $this->resolved_depth = $previous_depth; return $this->unknown( $path, $reason, is_string( $node['unknown'] ) ? $node['unknown'] : '', false ); } if ( isset( $node['cond'] ) ) { $result = $this->cond( $node, $path ); $this->resolved_depth = $previous_depth; return $result; } $op = isset( $node['op'] ) ? $node['op'] : null; if ( 'ref' === $op ) { $result = $this->resolve_ref( $node, $path, $previous_depth ); $this->resolved_depth = $previous_depth; return $result; } if ( 'not' === $op ) { if ( ! isset( $node['item'] ) ) { $this->resolved_depth = $previous_depth; return $this->unknown( $path, 'unsupported_node', '', false ); } list( $v, $by ) = $this->node( $node['item'], $path . '.item' ); if ( $this->over_limit ) { $this->resolved_depth = $previous_depth; return array( Decision::U, null ); } $this->resolved_depth = $previous_depth; if ( Decision::T === $v ) { return array( Decision::F, $by ); } if ( Decision::F === $v ) { return array( Decision::T, $by ); } return array( Decision::U, null ); } if ( 'all' === $op || 'any' === $op ) { if ( ! isset( $node['items'] ) || ! is_array( $node['items'] ) ) { $this->resolved_depth = $previous_depth; return $this->unknown( $path, 'unsupported_node', '', false ); } $stop = 'all' === $op ? Decision::F : Decision::T; $unknown = false; $last = null; foreach ( array_values( $node['items'] ) as $i => $child ) { list( $v, $by ) = $this->node( $child, $path . '.items[' . $i . ']' ); if ( $this->over_limit ) { $this->resolved_depth = $previous_depth; return array( Decision::U, null ); } if ( $stop === $v ) { $this->resolved_depth = $previous_depth; return array( $stop, $by ); } if ( Decision::U === $v ) { $unknown = true; } else { $last = $by; } } $this->resolved_depth = $previous_depth; if ( $unknown ) { return array( Decision::U, null ); } return array( 'all' === $op ? Decision::T : Decision::F, $last ? $last : $path ); } $this->resolved_depth = $previous_depth; return $this->unknown( $path, 'unsupported_node', '', false ); } /** * 1.1.0 §2.3: resolve a ref node against the group store. * * @param array $node Ref node. * @param string $path Ref node's path. * @param int $previous_depth The depth of the ref node itself. * @return array{0:string,1:string|null} */ private function resolve_ref( array $node, $path, $previous_depth ) { $id = isset( $node['id'] ) && is_string( $node['id'] ) && '' !== $node['id'] ? $node['id'] : ''; if ( '' === $id ) { // Same ruling as a missing group: audience-flagged UNKNOWN, fail closed. return $this->unknown( $path, 'group_missing', '', true ); } if ( in_array( $id, $this->ref_stack, true ) ) { return $this->unknown( $path, 'group_cycle', $id, true ); } $tree = Groups::get( $id ); if ( null === $tree ) { return $this->unknown( $path, 'group_missing', $id, true ); } $this->ref_stack[] = $id; // The group's root node stands at the ref node's depth, so reset the // depth to $previous_depth before recursing (node() will increment it // back to the ref node's depth + 1, which is the group root's depth). $this->resolved_depth = $previous_depth; list( $value, $by ) = $this->node( $tree, $path ); array_pop( $this->ref_stack ); if ( $this->over_limit ) { return array( Decision::U, null ); } // The group root's subtree is logically the ref node's subtree: its // decided-by path (if it came from inside the group) already begins // with $path, so no rewriting is needed. return array( $value, $by ); } /** * Evaluate a cond node. * * @param array $node Node. * @param string $path Path. * @return array{0:string,1:string|null} */ private function cond( array $node, $path ) { $name = is_string( $node['cond'] ) ? strtolower( $node['cond'] ) : ''; $def = $this->registry->get( $name ); $stamped = isset( $node['risk'] ) && in_array( $node['risk'], array( 'audience', 'location' ), true ) ? $node['risk'] : 'audience'; $risk = ( 'audience' === $stamped || ( $def && 'audience' === $def['risk'] ) ) ? 'audience' : 'location'; $aud = 'audience' === $risk; $text = $name; if ( ! empty( $node['denied'] ) ) { return $this->unknown( $path, 'unauthorized', $text, $aud ); } if ( null === $def ) { return $this->unknown( $path, 'condition_unavailable', $text, $aud ); } $args = isset( $node['args'] ) ? $node['args'] : array(); $ok = $this->registry->validate_args( $name, $args ); if ( true !== $ok ) { return $this->unknown( $path, $ok, $text, $aud ); } if ( $this->simulated && ! $def['simulatable'] ) { return $this->unknown( $path, 'simulated_visitor', $text, false ); } if ( null !== $def['available'] ) { $available = false; try { $available = (bool) call_user_func( $def['available'] ); } catch ( \Throwable $e ) { $available = false; } if ( ! $available ) { if ( 'location' === $risk ) { // Exception (b): an inactive dependency makes a location condition natively false. $this->badges[] = array( 'path' => $path, 'badge' => 'dependency_inactive', 'cond' => $name, ); $this->values[ $path ] = Decision::F; return array( Decision::F, $path ); } return $this->unknown( $path, 'dependency_inactive', $text, $aud ); } } try { $result = call_user_func_array( $def['callback'], $args ); } catch ( \Throwable $e ) { Failure_Counter::record( $name ); return $this->unknown( $path, 'condition_error', $text, $aud ); } if ( true === $result ) { $this->values[ $path ] = Decision::T; return array( Decision::T, $path ); } if ( false === $result ) { $this->values[ $path ] = Decision::F; return array( Decision::F, $path ); } if ( null === $result ) { return $this->unknown( $path, 'condition_unavailable', $text, $aud ); } Failure_Counter::record( $name ); return $this->unknown( $path, 'condition_error', $text, $aud ); } /** * Record an UNKNOWN. * * @param string $path Path. * @param string $reason Reason code. * @param string $text Original text or condition name. * @param bool $audience Came from an audience cond node. * @return array{0:string,1:null} */ private function unknown( $path, $reason, $text, $audience ) { $this->unknowns[] = array( 'path' => $path, 'reason' => $reason, 'text' => $text, ); if ( $audience ) { $this->audience_unknown = true; } return array( Decision::U, null ); } /** * Value the condition at a path returned during this evaluation, if any. * * @param string $path Decision path. * @return string|null Decision::T, Decision::F or null. */ private function value_at( $path ) { return isset( $this->values[ $path ] ) ? $this->values[ $path ] : null; } }