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}