001/*
002 * Copyright 2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package com.revetsec.scim;
017
018import org.jspecify.annotations.NonNull;
019import org.jspecify.annotations.Nullable;
020
021import com.google.errorprone.annotations.CheckReturnValue;
022import javax.annotation.concurrent.Immutable;
023import java.util.List;
024
025import static java.util.Objects.requireNonNull;
026
027/**
028 * A bounded immutable SCIM filter syntax tree (RFC 7644 section 3.4.2.2).
029 * AND and OR are ordered, flattened n-ary nodes. NOT binds more tightly than
030 * AND, which binds more tightly than OR. ValuePath predicates describe one
031 * array element and cannot contain another ValuePath.
032 * <p>
033 * A successful syntax parse does not bind paths to schemas, validate attribute
034 * types, approve a filter policy, or authorize query execution. Applications
035 * must perform those checks before using a tree to select resources.
036 * <p>
037 * Parsed and schema-bound roots privately retain their bounded original expression for later
038 * receiving-provider checks. This text may contain personal data and grants no query permission.
039 * Equality is structural, with the path's ASCII case-insensitive equality and
040 * numeric-value literal equality. Explicit serialization contains the complete
041 * filter and may expose personal data; every diagnostic toString redacts it.
042 * <p>
043 * The six permitted node kinds are stable within a major version and may be matched exhaustively.
044 * Adding a node kind or an abstract visitor callback requires a major release.
045 *
046 * @since 1.0.0
047 */
048@Immutable
049public sealed interface ScimFilter permits ScimFilter.And, ScimFilter.Or, ScimFilter.Not,
050        ScimFilter.Comparison, ScimFilter.Present, ScimFilter.ValuePath {
051    /**
052     * Parses filter syntax under the shared immutable default limits.
053     *
054     * @param expression untrusted filter expression
055     * @return success or a fixed rejection with a UTF-16 expression offset
056     * @throws NullPointerException if expression is null
057     * @since 1.0.0
058     */
059    @CheckReturnValue
060    static @NonNull ScimFilterParseResult fromExpressionResult(@NonNull String expression) {
061        return fromExpressionResult(expression, ScimFilterLimits.defaultInstance());
062    }
063
064    /**
065     * Parses filter syntax directly into a result, without exception-driven
066     * handling of malformed input. Bounds apply before recursive stack growth,
067     * AST construction and literal/number allocation. Depth covers retained AST
068     * levels as well as transient grouping/NOT/ValuePath nesting; nodes count
069     * the retained flattened tree, rather than discarded parentheses.
070     *
071     * @param expression untrusted filter expression
072     * @param limits immutable limits
073     * @return syntax success or a fixed rejection with a UTF-16 expression offset
074     * @throws NullPointerException if either argument is null
075     * @since 1.0.0
076     */
077    @CheckReturnValue
078    static @NonNull ScimFilterParseResult fromExpressionResult(
079            @NonNull String expression, @NonNull ScimFilterLimits limits) {
080        return new ScimFilterParser(requireNonNull(expression), requireNonNull(limits)).parse();
081    }
082
083    /**
084     * Dispatches this node to a Java 17 visitor. The visitor controls traversal.
085     *
086     * @param visitor visitor
087     * @param <R> nonnull result type
088     * @return the visitor's result
089     * @throws NullPointerException if visitor or its result is null
090     * @since 1.0.0
091     */
092    @CheckReturnValue
093    <R extends @NonNull Object> @NonNull R accept(@NonNull ScimFilterVisitor<@NonNull R> visitor);
094
095    /**
096     * Emits a canonical filter with lowercase operators and minimal grouping.
097     * Strings use JSON escapes; numeric exponent notation remains compact and
098     * never expands an exponent into zeros. The output contains personal data and can exceed
099     * the original input-character limit after schema normalization. Rendering does not prove
100     * that this text fits a receiving parser's limits.
101     *
102     * @return canonical SCIM syntax, subject to receiving parser limits
103     * @since 1.0.0
104     */
105    @CheckReturnValue
106    @NonNull String toScimString();
107
108    /** An ordered flattened conjunction.
109     * @since 1.0.0
110     */
111    @Immutable
112    final class And implements ScimFilter {
113        private final @NonNull List<@NonNull ScimFilter> operands;
114        // Root-only lexical provenance; excluded from structural equality, hashing and rendering.
115        private final @Nullable String sourceExpression;
116        @Nullable String sourceExpression() { return sourceExpression; }
117        And(@NonNull List<@NonNull ScimFilter> operands) { this(operands, null); }
118        And(@NonNull List<@NonNull ScimFilter> operands, @Nullable String sourceExpression) {
119            this.operands = List.copyOf(operands);
120            this.sourceExpression = sourceExpression;
121        }
122
123        /** Returns ordered conjunction operands.
124         * @return immutable operands
125         * @since 1.0.0
126         */
127        @CheckReturnValue public @NonNull List<@NonNull ScimFilter> getOperands() { return this.operands; }
128        /** Dispatches this node.
129         * @param visitor visitor
130         * @param <R> result type
131         * @return result
132         * @since 1.0.0
133         */
134        @Override @CheckReturnValue
135        public <R extends @NonNull Object> @NonNull R accept(@NonNull ScimFilterVisitor<@NonNull R> visitor) {
136            return requireNonNull(requireNonNull(visitor).visitAnd(this));
137        }
138        /** Emits filter data.
139         * @return canonical syntax
140         * @since 1.0.0
141         */
142        @Override @CheckReturnValue public @NonNull String toScimString() { return ScimFilterRendering.render(this); }
143        /** Compares ordered structure.
144         * @param other candidate
145         * @return equality
146         * @since 1.0.0
147         */
148        @Override public boolean equals(@Nullable Object other) {
149            return this == other || (other instanceof And filter && this.operands.equals(filter.operands));
150        }
151        /** Returns the structural hash.
152         * @return hash
153         * @since 1.0.0
154         */
155        @Override public int hashCode() { return 31 * this.operands.hashCode(); }
156        /** Redacts filter data.
157         * @return redacted description
158         * @since 1.0.0
159         */
160        @Override public @NonNull String toString() { return "ScimFilter.And{operands=<redacted>}"; }
161    }
162
163    /** An ordered flattened disjunction.
164     * @since 1.0.0
165     */
166    @Immutable
167    final class Or implements ScimFilter {
168        private final @NonNull List<@NonNull ScimFilter> operands;
169        // Root-only lexical provenance; excluded from structural equality, hashing and rendering.
170        private final @Nullable String sourceExpression;
171        @Nullable String sourceExpression() { return sourceExpression; }
172        Or(@NonNull List<@NonNull ScimFilter> operands) { this(operands, null); }
173        Or(@NonNull List<@NonNull ScimFilter> operands, @Nullable String sourceExpression) {
174            this.operands = List.copyOf(operands);
175            this.sourceExpression = sourceExpression;
176        }
177
178        /** Returns ordered disjunction operands.
179         * @return immutable operands
180         * @since 1.0.0
181         */
182        @CheckReturnValue public @NonNull List<@NonNull ScimFilter> getOperands() { return this.operands; }
183        /** Dispatches this node.
184         * @param visitor visitor
185         * @param <R> result type
186         * @return result
187         * @since 1.0.0
188         */
189        @Override @CheckReturnValue
190        public <R extends @NonNull Object> @NonNull R accept(@NonNull ScimFilterVisitor<@NonNull R> visitor) {
191            return requireNonNull(requireNonNull(visitor).visitOr(this));
192        }
193        /** Emits filter data.
194         * @return canonical syntax
195         * @since 1.0.0
196         */
197        @Override @CheckReturnValue public @NonNull String toScimString() { return ScimFilterRendering.render(this); }
198        /** Compares ordered structure.
199         * @param other candidate
200         * @return equality
201         * @since 1.0.0
202         */
203        @Override public boolean equals(@Nullable Object other) {
204            return this == other || (other instanceof Or filter && this.operands.equals(filter.operands));
205        }
206        /** Returns the structural hash.
207         * @return hash
208         * @since 1.0.0
209         */
210        @Override public int hashCode() { return 37 * this.operands.hashCode(); }
211        /** Redacts filter data.
212         * @return redacted description
213         * @since 1.0.0
214         */
215        @Override public @NonNull String toString() { return "ScimFilter.Or{operands=<redacted>}"; }
216    }
217
218    /** Negation of a grouped predicate.
219     * @since 1.0.0
220     */
221    @Immutable
222    final class Not implements ScimFilter {
223        private final @NonNull ScimFilter operand;
224        // Root-only lexical provenance; excluded from structural equality, hashing and rendering.
225        private final @Nullable String sourceExpression;
226        @Nullable String sourceExpression() { return sourceExpression; }
227        Not(@NonNull ScimFilter operand) { this(operand, null); }
228        Not(@NonNull ScimFilter operand, @Nullable String sourceExpression) {
229            this.operand = requireNonNull(operand);
230            this.sourceExpression = sourceExpression;
231        }
232
233        /** Returns the operand.
234         * @return operand
235         * @since 1.0.0
236         */
237        @CheckReturnValue public @NonNull ScimFilter getOperand() { return this.operand; }
238
239        /** Dispatches this node.
240         * @param visitor visitor
241         * @param <R> result type
242         * @return result
243         * @since 1.0.0
244         */
245        @Override @CheckReturnValue
246        public <R extends @NonNull Object> @NonNull R accept(@NonNull ScimFilterVisitor<@NonNull R> visitor) {
247            return requireNonNull(requireNonNull(visitor).visitNot(this));
248        }
249        /** Emits filter data.
250         * @return canonical syntax
251         * @since 1.0.0
252         */
253        @Override @CheckReturnValue public @NonNull String toScimString() { return ScimFilterRendering.render(this); }
254        /** Compares structure.
255         * @param other candidate
256         * @return equality
257         * @since 1.0.0
258         */
259        @Override public boolean equals(@Nullable Object other) {
260            return this == other || (other instanceof Not filter
261                    && this.operand.equals(filter.operand));
262        }
263        /** Returns the structural hash.
264         * @return hash
265         * @since 1.0.0
266         */
267        @Override public int hashCode() { return this.operand.hashCode(); }
268        /** Redacts filter data.
269         * @return redacted description
270         * @since 1.0.0
271         */
272        @Override public @NonNull String toString() { return "ScimFilter.Not{filter=<redacted>}"; }
273    }
274
275    /** An attribute comparison with a JSON literal.
276     * @since 1.0.0
277     */
278    @Immutable
279    final class Comparison implements ScimFilter {
280        private final @NonNull ScimAttributePath attributePath;
281        private final @NonNull ScimComparisonOperator operator;
282        private final @NonNull ScimFilterValue value;
283        // Root-only lexical provenance; excluded from structural equality, hashing and rendering.
284        private final @Nullable String sourceExpression;
285        @Nullable String sourceExpression() { return sourceExpression; }
286        Comparison(@NonNull ScimAttributePath attributePath, @NonNull ScimComparisonOperator operator, @NonNull ScimFilterValue value) { this(attributePath, operator, value, null); }
287        Comparison(@NonNull ScimAttributePath attributePath, @NonNull ScimComparisonOperator operator, @NonNull ScimFilterValue value, @Nullable String sourceExpression) {
288            this.attributePath = requireNonNull(attributePath);
289            this.operator = requireNonNull(operator);
290            this.value = requireNonNull(value);
291            this.sourceExpression = sourceExpression;
292        }
293
294        /** Returns the attributePath.
295         * @return attributePath
296         * @since 1.0.0
297         */
298        @CheckReturnValue public @NonNull ScimAttributePath getAttributePath() { return this.attributePath; }
299        /** Returns the operator.
300         * @return operator
301         * @since 1.0.0
302         */
303        @CheckReturnValue public @NonNull ScimComparisonOperator getOperator() { return this.operator; }
304        /** Returns the value.
305         * @return value
306         * @since 1.0.0
307         */
308        @CheckReturnValue public @NonNull ScimFilterValue getValue() { return this.value; }
309
310        /** Dispatches this node.
311         * @param visitor visitor
312         * @param <R> result type
313         * @return result
314         * @since 1.0.0
315         */
316        @Override @CheckReturnValue
317        public <R extends @NonNull Object> @NonNull R accept(@NonNull ScimFilterVisitor<@NonNull R> visitor) {
318            return requireNonNull(requireNonNull(visitor).visitComparison(this));
319        }
320        /** Emits filter data.
321         * @return canonical syntax
322         * @since 1.0.0
323         */
324        @Override @CheckReturnValue public @NonNull String toScimString() { return ScimFilterRendering.render(this); }
325        /** Compares structure.
326         * @param other candidate
327         * @return equality
328         * @since 1.0.0
329         */
330        @Override public boolean equals(@Nullable Object other) {
331            return this == other || (other instanceof Comparison filter
332                    && this.attributePath.equals(filter.attributePath) && this.operator.equals(filter.operator) && this.value.equals(filter.value));
333        }
334        /** Returns the structural hash.
335         * @return hash
336         * @since 1.0.0
337         */
338        @Override public int hashCode() { return (31 * (31 * this.attributePath.hashCode() + this.operator.hashCode()) + this.value.hashCode()); }
339        /** Redacts filter data.
340         * @return redacted description
341         * @since 1.0.0
342         */
343        @Override public @NonNull String toString() { return "ScimFilter.Comparison{filter=<redacted>}"; }
344    }
345
346    /** An attribute presence test.
347     * @since 1.0.0
348     */
349    @Immutable
350    final class Present implements ScimFilter {
351        private final @NonNull ScimAttributePath attributePath;
352        // Root-only lexical provenance; excluded from structural equality, hashing and rendering.
353        private final @Nullable String sourceExpression;
354        @Nullable String sourceExpression() { return sourceExpression; }
355        Present(@NonNull ScimAttributePath attributePath) { this(attributePath, null); }
356        Present(@NonNull ScimAttributePath attributePath, @Nullable String sourceExpression) {
357            this.attributePath = requireNonNull(attributePath);
358            this.sourceExpression = sourceExpression;
359        }
360
361        /** Returns the attributePath.
362         * @return attributePath
363         * @since 1.0.0
364         */
365        @CheckReturnValue public @NonNull ScimAttributePath getAttributePath() { return this.attributePath; }
366
367        /** Dispatches this node.
368         * @param visitor visitor
369         * @param <R> result type
370         * @return result
371         * @since 1.0.0
372         */
373        @Override @CheckReturnValue
374        public <R extends @NonNull Object> @NonNull R accept(@NonNull ScimFilterVisitor<@NonNull R> visitor) {
375            return requireNonNull(requireNonNull(visitor).visitPresent(this));
376        }
377        /** Emits filter data.
378         * @return canonical syntax
379         * @since 1.0.0
380         */
381        @Override @CheckReturnValue public @NonNull String toScimString() { return ScimFilterRendering.render(this); }
382        /** Compares structure.
383         * @param other candidate
384         * @return equality
385         * @since 1.0.0
386         */
387        @Override public boolean equals(@Nullable Object other) {
388            return this == other || (other instanceof Present filter
389                    && this.attributePath.equals(filter.attributePath));
390        }
391        /** Returns the structural hash.
392         * @return hash
393         * @since 1.0.0
394         */
395        @Override public int hashCode() { return this.attributePath.hashCode(); }
396        /** Redacts filter data.
397         * @return redacted description
398         * @since 1.0.0
399         */
400        @Override public @NonNull String toString() { return "ScimFilter.Present{filter=<redacted>}"; }
401    }
402
403    /** A predicate whose relative paths refer to the same array element.
404     * @since 1.0.0
405     */
406    @Immutable
407    final class ValuePath implements ScimFilter {
408        private final @NonNull ScimAttributePath attributePath;
409        private final @NonNull ScimFilter filter;
410        // Root-only lexical provenance; excluded from structural equality, hashing and rendering.
411        private final @Nullable String sourceExpression;
412        @Nullable String sourceExpression() { return sourceExpression; }
413        ValuePath(@NonNull ScimAttributePath attributePath, @NonNull ScimFilter filter) { this(attributePath, filter, null); }
414        ValuePath(@NonNull ScimAttributePath attributePath, @NonNull ScimFilter filter, @Nullable String sourceExpression) {
415            this.attributePath = requireNonNull(attributePath);
416            this.filter = requireNonNull(filter);
417            this.sourceExpression = sourceExpression;
418        }
419
420        /** Returns the attributePath.
421         * @return attributePath
422         * @since 1.0.0
423         */
424        @CheckReturnValue public @NonNull ScimAttributePath getAttributePath() { return this.attributePath; }
425        /** Returns the filter.
426         * @return filter
427         * @since 1.0.0
428         */
429        @CheckReturnValue public @NonNull ScimFilter getFilter() { return this.filter; }
430
431        /** Dispatches this node.
432         * @param visitor visitor
433         * @param <R> result type
434         * @return result
435         * @since 1.0.0
436         */
437        @Override @CheckReturnValue
438        public <R extends @NonNull Object> @NonNull R accept(@NonNull ScimFilterVisitor<@NonNull R> visitor) {
439            return requireNonNull(requireNonNull(visitor).visitValuePath(this));
440        }
441        /** Emits filter data.
442         * @return canonical syntax
443         * @since 1.0.0
444         */
445        @Override @CheckReturnValue public @NonNull String toScimString() { return ScimFilterRendering.render(this); }
446        /** Compares structure.
447         * @param other candidate
448         * @return equality
449         * @since 1.0.0
450         */
451        @Override public boolean equals(@Nullable Object other) {
452            return this == other || (other instanceof ValuePath filter
453                    && this.attributePath.equals(filter.attributePath) && this.filter.equals(filter.filter));
454        }
455        /** Returns the structural hash.
456         * @return hash
457         * @since 1.0.0
458         */
459        @Override public int hashCode() { return (31 * this.attributePath.hashCode() + this.filter.hashCode()); }
460        /** Redacts filter data.
461         * @return redacted description
462         * @since 1.0.0
463         */
464        @Override public @NonNull String toString() { return "ScimFilter.ValuePath{filter=<redacted>}"; }
465    }
466}