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 */
016
017package com.revetsec.scim;
018
019import com.google.errorprone.annotations.CheckReturnValue;
020import com.revetsec.internal.Limit;
021import com.revetsec.internal.Limits;
022import org.jspecify.annotations.NonNull;
023import org.jspecify.annotations.Nullable;
024
025import javax.annotation.concurrent.Immutable;
026import javax.annotation.concurrent.NotThreadSafe;
027
028/**
029 * Immutable allocation and structural limits for SCIM filter syntax. Character counts use UTF-16
030 * code units. All limits are finite; literal length must not exceed expression length.
031 *
032 * @since 1.0.0
033 */
034@Immutable
035@CheckReturnValue
036public final class ScimFilterLimits {
037    private static final @NonNull ScimFilterLimits DEFAULT = new Builder().build();
038    private final int maximumExpressionCharacters;
039    private final int maximumDepth;
040    private final int maximumNodes;
041    private final int maximumLiteralCharacters;
042    private final int maximumNumberCharacters;
043    private final int maximumNumberExponentMagnitude;
044
045    private ScimFilterLimits(@NonNull Builder builder) {
046        maximumExpressionCharacters = resolve(builder.maximumExpressionCharacters, Limits.SCIM_FILTER_LENGTH);
047        maximumDepth = resolve(builder.maximumDepth, Limits.SCIM_FILTER_DEPTH);
048        maximumNodes = resolve(builder.maximumNodes, Limits.SCIM_FILTER_NODES);
049        maximumLiteralCharacters = resolve(builder.maximumLiteralCharacters, Limits.SCIM_FILTER_LITERAL_LENGTH);
050        maximumNumberCharacters = resolve(builder.maximumNumberCharacters, Limits.SCIM_FILTER_NUMBER_LENGTH);
051        maximumNumberExponentMagnitude = resolve(builder.maximumNumberExponentMagnitude,
052                Limits.SCIM_FILTER_NUMBER_EXPONENT_MAGNITUDE);
053        if (maximumLiteralCharacters > maximumExpressionCharacters)
054            throw new IllegalArgumentException("SCIM filter literal length must not exceed expression length.");
055    }
056
057    /**
058     * Starts limit configuration with the registered defaults.
059     *
060     * @return a new builder
061     * @since 1.0.0
062     */
063    public static @NonNull Builder builder() {
064        return new Builder();
065    }
066
067    /**
068     * Returns the shared immutable default filter limits.
069     *
070     * @return the shared default filter limits
071     * @since 1.0.0
072     */
073    public static @NonNull ScimFilterLimits defaultInstance() {
074        return DEFAULT;
075    }
076
077    /**
078     * Returns maximum expression UTF-16 units.
079     *
080     * @return maximum expression UTF-16 units
081     * @since 1.0.0
082     */
083    public @NonNull Integer getMaximumExpressionCharacters() { return maximumExpressionCharacters; }
084    /**
085     * Returns maximum AST depth.
086     *
087     * @return maximum AST depth
088     * @since 1.0.0
089     */
090    public @NonNull Integer getMaximumDepth() { return maximumDepth; }
091    /**
092     * Returns maximum AST nodes.
093     *
094     * @return maximum AST nodes
095     * @since 1.0.0
096     */
097    public @NonNull Integer getMaximumNodes() { return maximumNodes; }
098    /**
099     * Returns maximum decoded string-literal UTF-16 units.
100     *
101     * @return maximum decoded string-literal UTF-16 units
102     * @since 1.0.0
103     */
104    public @NonNull Integer getMaximumLiteralCharacters() { return maximumLiteralCharacters; }
105    /**
106     * Returns maximum number-literal UTF-16 units.
107     *
108     * @return maximum number-literal UTF-16 units
109     * @since 1.0.0
110     */
111    public @NonNull Integer getMaximumNumberCharacters() { return maximumNumberCharacters; }
112    /**
113     * Returns maximum magnitude of a number literal's exponent.
114     *
115     * @return maximum magnitude of a number literal's exponent
116     * @since 1.0.0
117     */
118    public @NonNull Integer getMaximumNumberExponentMagnitude() { return maximumNumberExponentMagnitude; }
119
120    /**
121     * Returns a bounded description of the configured limits.
122     *
123     * @return a bounded description of the configured limits
124     * @since 1.0.0
125     */
126    @Override public @NonNull String toString() {
127        return "ScimFilterLimits{expression=" + maximumExpressionCharacters + ", depth=" + maximumDepth
128                + ", nodes=" + maximumNodes + ", literal=" + maximumLiteralCharacters + ", number="
129                + maximumNumberCharacters + ", exponent=" + maximumNumberExponentMagnitude + "}";
130    }
131
132    private static int resolve(@Nullable Integer value, @NonNull Limit limit) {
133        return limit.require(value == null ? limit.getDefaultIntValue() : value);
134    }
135
136    /**
137     * Mutable, non-thread-safe filter-limit configuration. Null restores the registered default.
138     *
139     * @since 1.0.0
140     */
141    @NotThreadSafe
142    @CheckReturnValue
143    public static final class Builder {
144        private @Nullable Integer maximumExpressionCharacters;
145        private @Nullable Integer maximumDepth;
146        private @Nullable Integer maximumNodes;
147        private @Nullable Integer maximumLiteralCharacters;
148        private @Nullable Integer maximumNumberCharacters;
149        private @Nullable Integer maximumNumberExponentMagnitude;
150
151        private Builder() { }
152
153        /**
154         * Sets the expression limit: default 4,096, range 256–65,536 UTF-16 units.
155         * @param value the limit, or null to restore its default
156         * @return this builder
157         * @since 1.0.0
158         */
159        public @NonNull Builder maximumExpressionCharacters(@Nullable Integer value) {
160            maximumExpressionCharacters = value; return this;
161        }
162
163        /**
164         * Sets the AST depth limit: default 16, range 4–64 levels.
165         * @param value the limit, or null to restore its default
166         * @return this builder
167         * @since 1.0.0
168         */
169        public @NonNull Builder maximumDepth(@Nullable Integer value) {
170            maximumDepth = value; return this;
171        }
172
173        /**
174         * Sets the AST node limit: default 128, range 8–4,096.
175         * @param value the limit, or null to restore its default
176         * @return this builder
177         * @since 1.0.0
178         */
179        public @NonNull Builder maximumNodes(@Nullable Integer value) {
180            maximumNodes = value; return this;
181        }
182
183        /**
184         * Sets the decoded literal limit: default 2,048, range 1–16,384 UTF-16 units, within the expression limit.
185         * @param value the limit, or null to restore its default
186         * @return this builder
187         * @since 1.0.0
188         */
189        public @NonNull Builder maximumLiteralCharacters(@Nullable Integer value) {
190            maximumLiteralCharacters = value; return this;
191        }
192
193        /**
194         * Sets the number-text limit: default 64, range 1–256 UTF-16 units.
195         * @param value the limit, or null to restore its default
196         * @return this builder
197         * @since 1.0.0
198         */
199        public @NonNull Builder maximumNumberCharacters(@Nullable Integer value) {
200            maximumNumberCharacters = value; return this;
201        }
202
203        /**
204         * Sets the exponent-magnitude limit: default 1,000, range 0–10,000.
205         * @param value the limit, or null to restore its default
206         * @return this builder
207         * @since 1.0.0
208         */
209        public @NonNull Builder maximumNumberExponentMagnitude(@Nullable Integer value) {
210            maximumNumberExponentMagnitude = value; return this;
211        }
212
213        /**
214         * Checks all registered bounds and creates an immutable snapshot.
215         * @return filter limits
216         * @since 1.0.0
217         */
218        public @NonNull ScimFilterLimits build() { return new ScimFilterLimits(this); }
219    }
220}