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.Limits;
021
022import org.jspecify.annotations.NonNull;
023import org.jspecify.annotations.Nullable;
024
025import java.util.*;
026
027import javax.annotation.concurrent.Immutable;
028import javax.annotation.concurrent.NotThreadSafe;
029
030/** Immutable SCIM operation budgets. Each original operation uses one shared work budget.
031 * Wire input and emitted JSON cost one work unit per started 16-byte block. JSON output blocks
032 * accumulate across the complete response. Node visits, validation, matching, headers and framing
033 * have their own additional charges. Byte and node limits are independent hard ceilings, not a
034 * promise that every document below them fits work; builders validate each configured range.
035 * @since 1.0.0
036 */
037@Immutable
038@CheckReturnValue
039public final class ScimLimits {
040    private final int maximumBodyBytes;
041    private final int maximumPatchOperations;
042    private final int maximumJsonNodes;
043    private final int maximumRawQueryBytes;
044    private final int maximumQueryParameters;
045    private final int maximumParameterCharacters;
046    private final int maximumProjectionPaths;
047    private final int maximumPageSize;
048    private final int maximumCursorCharacters;
049    private final int maximumConditionalHeaderBytes;
050    private final int maximumConditionalTags;
051    private final int maximumResponseHeaderBytes;
052    private final int maximumResponseBytes;
053    private final int maximumWorkUnits;
054    private final @NonNull ScimFilterLimits filterLimits;
055
056    private ScimLimits(@NonNull Builder b) {
057        maximumBodyBytes =
058                Limits.SCIM_BODY_SIZE.require(
059                        b.maximumBodyBytes == null
060                                ? Limits.SCIM_BODY_SIZE.getDefaultIntValue()
061                                : b.maximumBodyBytes);
062        maximumPatchOperations =
063                Limits.SCIM_PATCH_OPERATIONS.require(
064                        b.maximumPatchOperations == null
065                                ? Limits.SCIM_PATCH_OPERATIONS.getDefaultIntValue()
066                                : b.maximumPatchOperations);
067        maximumJsonNodes =
068                Limits.SCIM_JSON_NODES.require(
069                        b.maximumJsonNodes == null
070                                ? Limits.SCIM_JSON_NODES.getDefaultIntValue()
071                                : b.maximumJsonNodes);
072        maximumRawQueryBytes =
073                Limits.SCIM_RAW_QUERY_BYTES.require(
074                        b.maximumRawQueryBytes == null
075                                ? Limits.SCIM_RAW_QUERY_BYTES.getDefaultIntValue()
076                                : b.maximumRawQueryBytes);
077        maximumQueryParameters =
078                Limits.SCIM_QUERY_PARAMETERS.require(
079                        b.maximumQueryParameters == null
080                                ? Limits.SCIM_QUERY_PARAMETERS.getDefaultIntValue()
081                                : b.maximumQueryParameters);
082        maximumParameterCharacters =
083                Limits.SCIM_PARAMETER_CHARACTERS.require(
084                        b.maximumParameterCharacters == null
085                                ? Limits.SCIM_PARAMETER_CHARACTERS.getDefaultIntValue()
086                                : b.maximumParameterCharacters);
087        maximumProjectionPaths =
088                Limits.SCIM_PROJECTION_PATHS.require(
089                        b.maximumProjectionPaths == null
090                                ? Limits.SCIM_PROJECTION_PATHS.getDefaultIntValue()
091                                : b.maximumProjectionPaths);
092        maximumPageSize =
093                Limits.SCIM_PAGE_SIZE.require(
094                        b.maximumPageSize == null
095                                ? Limits.SCIM_PAGE_SIZE.getDefaultIntValue()
096                                : b.maximumPageSize);
097        maximumCursorCharacters =
098                Limits.SCIM_CURSOR_CHARACTERS.require(
099                        b.maximumCursorCharacters == null
100                                ? Limits.SCIM_CURSOR_CHARACTERS.getDefaultIntValue()
101                                : b.maximumCursorCharacters);
102        maximumConditionalHeaderBytes =
103                Limits.SCIM_CONDITIONAL_HEADER_BYTES.require(
104                        b.maximumConditionalHeaderBytes == null
105                                ? Limits.SCIM_CONDITIONAL_HEADER_BYTES.getDefaultIntValue()
106                                : b.maximumConditionalHeaderBytes);
107        maximumConditionalTags =
108                Limits.SCIM_CONDITIONAL_TAGS.require(
109                        b.maximumConditionalTags == null
110                                ? Limits.SCIM_CONDITIONAL_TAGS.getDefaultIntValue()
111                                : b.maximumConditionalTags);
112        maximumResponseHeaderBytes =
113                Limits.SCIM_RESPONSE_HEADER_BYTES.require(
114                        b.maximumResponseHeaderBytes == null
115                                ? Limits.SCIM_RESPONSE_HEADER_BYTES.getDefaultIntValue()
116                                : b.maximumResponseHeaderBytes);
117        maximumResponseBytes =
118                Limits.SCIM_RESPONSE_BYTES.require(
119                        b.maximumResponseBytes == null
120                                ? Limits.SCIM_RESPONSE_BYTES.getDefaultIntValue()
121                                : b.maximumResponseBytes);
122        maximumWorkUnits =
123                Limits.SCIM_WORK_UNITS.require(
124                        b.maximumWorkUnits == null
125                                ? Limits.SCIM_WORK_UNITS.getDefaultIntValue()
126                                : b.maximumWorkUnits);
127        filterLimits = b.filterLimits == null ? ScimFilterLimits.defaultInstance() : b.filterLimits;
128    }
129
130    /** Starts budget configuration.
131     * @return a fresh builder
132     * @since 1.0.0
133     */
134    public static @NonNull Builder builder() {
135        return new Builder();
136    }
137
138    /** Creates a default snapshot.
139     * @return defaults
140     * @since 1.0.0
141     */
142    public static @NonNull ScimLimits fromDefaults() {
143        return builder().build();
144    }
145
146    /** Returns the inclusive original request-body byte ceiling.
147     * Before decoding, the body also requires {@code ceil(bytes / 16)} remaining work units;
148     * schema/structural processing needs additional work. The ceiling is not an acceptance guarantee.
149     * @return configured inclusive bound
150     * @since 1.0.0
151     */
152    public @NonNull Integer getMaximumBodyBytes() {
153        return maximumBodyBytes;
154    }
155
156    /** Returns the maximumPatchOperations budget.
157     * @return configured inclusive bound
158     * @since 1.0.0
159     */
160    public @NonNull Integer getMaximumPatchOperations() {
161        return maximumPatchOperations;
162    }
163
164    /** Returns the maximumJsonNodes budget.
165     * @return configured inclusive bound
166     * @since 1.0.0
167     */
168    public @NonNull Integer getMaximumJsonNodes() {
169        return maximumJsonNodes;
170    }
171
172    /** Returns the maximumRawQueryBytes budget.
173     * @return configured inclusive bound
174     * @since 1.0.0
175     */
176    public @NonNull Integer getMaximumRawQueryBytes() {
177        return maximumRawQueryBytes;
178    }
179
180    /** Returns the maximumQueryParameters budget.
181     * @return configured inclusive bound
182     * @since 1.0.0
183     */
184    public @NonNull Integer getMaximumQueryParameters() {
185        return maximumQueryParameters;
186    }
187
188    /** Returns the maximumParameterCharacters budget.
189     * @return configured inclusive bound
190     * @since 1.0.0
191     */
192    public @NonNull Integer getMaximumParameterCharacters() {
193        return maximumParameterCharacters;
194    }
195
196    /** Returns the maximumProjectionPaths budget.
197     * @return configured inclusive bound
198     * @since 1.0.0
199     */
200    public @NonNull Integer getMaximumProjectionPaths() {
201        return maximumProjectionPaths;
202    }
203
204    /** Returns the maximumPageSize budget.
205     * @return configured inclusive bound
206     * @since 1.0.0
207     */
208    public @NonNull Integer getMaximumPageSize() {
209        return maximumPageSize;
210    }
211
212    /** Returns the maximumCursorCharacters budget.
213     * @return configured inclusive bound
214     * @since 1.0.0
215     */
216    public @NonNull Integer getMaximumCursorCharacters() {
217        return maximumCursorCharacters;
218    }
219
220    /** Returns the maximumConditionalHeaderBytes budget.
221     * @return configured inclusive bound
222     * @since 1.0.0
223     */
224    public @NonNull Integer getMaximumConditionalHeaderBytes() {
225        return maximumConditionalHeaderBytes;
226    }
227
228    /** Returns the maximumConditionalTags budget.
229     * @return configured inclusive bound
230     * @since 1.0.0
231     */
232    public @NonNull Integer getMaximumConditionalTags() {
233        return maximumConditionalTags;
234    }
235
236    /** Returns the maximumResponseHeaderBytes budget.
237     * @return configured inclusive bound
238     * @since 1.0.0
239     */
240    public @NonNull Integer getMaximumResponseHeaderBytes() {
241        return maximumResponseHeaderBytes;
242    }
243
244    /** Returns the inclusive prepared-response budget, including body, encoded headers and framing.
245     * JSON emission additionally costs {@code ceil(bodyBytes / 16)} work units for the entire body,
246     * plus node visits; projection and headers share that same operation budget.
247     * @return configured inclusive bound
248     * @since 1.0.0
249     */
250    public @NonNull Integer getMaximumResponseBytes() {
251        return maximumResponseBytes;
252    }
253
254    /** Returns the aggregate operation work allowance.
255     * Input decoding admission and JSON emission charge started 16-byte blocks; structural and
256     * semantic work remains separately charged. A low work allowance can intentionally refuse
257     * requests/responses below their byte ceilings. No budget resets per phase or resource.
258     * @return configured inclusive bound
259     * @since 1.0.0
260     */
261    public @NonNull Integer getMaximumWorkUnits() {
262        return maximumWorkUnits;
263    }
264
265    /** Returns the filter budget snapshot.
266     * @return filter limits
267     * @since 1.0.0
268     */
269    public @NonNull ScimFilterLimits getFilterLimits() {
270        return filterLimits;
271    }
272
273    /** Returns a fixed description.
274     * @return diagnostic
275     * @since 1.0.0
276     */
277    @Override
278    public @NonNull String toString() {
279        return "ScimLimits{bounded}";
280    }
281
282    /** Mutable complete budget configuration; null restores each default.
283     * @since 1.0.0
284     */
285    @NotThreadSafe
286    @CheckReturnValue
287    public static final class Builder {
288        private Builder() {}
289
290        private @Nullable Integer maximumBodyBytes;
291
292        /** Replaces the maximumBodyBytes setting.
293         * @param value bound or null for default
294         * @return this builder
295         * @since 1.0.0
296         */
297        public @NonNull Builder maximumBodyBytes(@Nullable Integer value) {
298            maximumBodyBytes = value;
299            return this;
300        }
301
302        private @Nullable Integer maximumPatchOperations;
303
304        /** Replaces the maximumPatchOperations setting.
305         * @param value bound or null for default
306         * @return this builder
307         * @since 1.0.0
308         */
309        public @NonNull Builder maximumPatchOperations(@Nullable Integer value) {
310            maximumPatchOperations = value;
311            return this;
312        }
313
314        private @Nullable Integer maximumJsonNodes;
315
316        /** Replaces the maximumJsonNodes setting.
317         * @param value bound or null for default
318         * @return this builder
319         * @since 1.0.0
320         */
321        public @NonNull Builder maximumJsonNodes(@Nullable Integer value) {
322            maximumJsonNodes = value;
323            return this;
324        }
325
326        private @Nullable Integer maximumRawQueryBytes;
327
328        /** Replaces the maximumRawQueryBytes setting.
329         * @param value bound or null for default
330         * @return this builder
331         * @since 1.0.0
332         */
333        public @NonNull Builder maximumRawQueryBytes(@Nullable Integer value) {
334            maximumRawQueryBytes = value;
335            return this;
336        }
337
338        private @Nullable Integer maximumQueryParameters;
339
340        /** Replaces the maximumQueryParameters setting.
341         * @param value bound or null for default
342         * @return this builder
343         * @since 1.0.0
344         */
345        public @NonNull Builder maximumQueryParameters(@Nullable Integer value) {
346            maximumQueryParameters = value;
347            return this;
348        }
349
350        private @Nullable Integer maximumParameterCharacters;
351
352        /** Replaces the maximumParameterCharacters setting.
353         * @param value bound or null for default
354         * @return this builder
355         * @since 1.0.0
356         */
357        public @NonNull Builder maximumParameterCharacters(@Nullable Integer value) {
358            maximumParameterCharacters = value;
359            return this;
360        }
361
362        private @Nullable Integer maximumProjectionPaths;
363
364        /** Replaces the maximumProjectionPaths setting.
365         * @param value bound or null for default
366         * @return this builder
367         * @since 1.0.0
368         */
369        public @NonNull Builder maximumProjectionPaths(@Nullable Integer value) {
370            maximumProjectionPaths = value;
371            return this;
372        }
373
374        private @Nullable Integer maximumPageSize;
375
376        /** Replaces the maximumPageSize setting.
377         * @param value bound or null for default
378         * @return this builder
379         * @since 1.0.0
380         */
381        public @NonNull Builder maximumPageSize(@Nullable Integer value) {
382            maximumPageSize = value;
383            return this;
384        }
385
386        private @Nullable Integer maximumCursorCharacters;
387
388        /** Replaces the maximumCursorCharacters setting.
389         * @param value bound or null for default
390         * @return this builder
391         * @since 1.0.0
392         */
393        public @NonNull Builder maximumCursorCharacters(@Nullable Integer value) {
394            maximumCursorCharacters = value;
395            return this;
396        }
397
398        private @Nullable Integer maximumConditionalHeaderBytes;
399
400        /** Replaces the maximumConditionalHeaderBytes setting.
401         * @param value bound or null for default
402         * @return this builder
403         * @since 1.0.0
404         */
405        public @NonNull Builder maximumConditionalHeaderBytes(@Nullable Integer value) {
406            maximumConditionalHeaderBytes = value;
407            return this;
408        }
409
410        private @Nullable Integer maximumConditionalTags;
411
412        /** Replaces the maximumConditionalTags setting.
413         * @param value bound or null for default
414         * @return this builder
415         * @since 1.0.0
416         */
417        public @NonNull Builder maximumConditionalTags(@Nullable Integer value) {
418            maximumConditionalTags = value;
419            return this;
420        }
421
422        private @Nullable Integer maximumResponseHeaderBytes;
423
424        /** Replaces the maximumResponseHeaderBytes setting.
425         * @param value bound or null for default
426         * @return this builder
427         * @since 1.0.0
428         */
429        public @NonNull Builder maximumResponseHeaderBytes(@Nullable Integer value) {
430            maximumResponseHeaderBytes = value;
431            return this;
432        }
433
434        private @Nullable Integer maximumResponseBytes;
435
436        /** Replaces the maximumResponseBytes setting.
437         * @param value bound or null for default
438         * @return this builder
439         * @since 1.0.0
440         */
441        public @NonNull Builder maximumResponseBytes(@Nullable Integer value) {
442            maximumResponseBytes = value;
443            return this;
444        }
445
446        private @Nullable Integer maximumWorkUnits;
447
448        /** Replaces the maximumWorkUnits setting.
449         * @param value bound or null for default
450         * @return this builder
451         * @since 1.0.0
452         */
453        public @NonNull Builder maximumWorkUnits(@Nullable Integer value) {
454            maximumWorkUnits = value;
455            return this;
456        }
457
458        private @Nullable ScimFilterLimits filterLimits;
459
460        /** Replaces all filter limits.
461         * @param value snapshot or null for defaults
462         * @return this builder
463         * @since 1.0.0
464         */
465        public @NonNull Builder filterLimits(@Nullable ScimFilterLimits value) {
466            filterLimits = value;
467            return this;
468        }
469
470        /** Validates all budgets before use.
471         * @return immutable limits
472         * @since 1.0.0
473         */
474        public @NonNull ScimLimits build() {
475            return new ScimLimits(this);
476        }
477    }
478}