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; 021import org.jspecify.annotations.NonNull; 022import org.jspecify.annotations.Nullable; 023 024import javax.annotation.concurrent.Immutable; 025import java.util.Optional; 026 027/** 028 * A fixed SCIM error with redacted detail. No request input or exception cause is retained. An 029 * engine-produced filter or path syntax error may carry a UTF-16 expression offset; that offset is 030 * programmatic metadata and must not be appended to the wire detail. 031 * 032 * @since 1.0.0 033 */ 034@Immutable 035@CheckReturnValue 036public final class ScimError { 037 private static final @NonNull ScimError INVALID_FILTER = new ScimError(400, ScimErrorType.INVALID_FILTER, "Invalid filter expression.", null); 038 private static final @NonNull ScimError TOO_MANY = new ScimError(400, ScimErrorType.TOO_MANY, "Too many matching resources.", null); 039 private static final @NonNull ScimError INVALID_SYNTAX = new ScimError(400, ScimErrorType.INVALID_SYNTAX, "Invalid request syntax.", null); 040 private static final @NonNull ScimError INVALID_PATH = new ScimError(400, ScimErrorType.INVALID_PATH, "Invalid attribute path.", null); 041 private static final @NonNull ScimError NO_TARGET = new ScimError(400, ScimErrorType.NO_TARGET, "The operation has no target.", null); 042 private static final @NonNull ScimError INVALID_VALUE = new ScimError(400, ScimErrorType.INVALID_VALUE, "Invalid attribute value.", null); 043 private static final @NonNull ScimError MUTABILITY = new ScimError(400, ScimErrorType.MUTABILITY, "The operation violates attribute mutability.", null); 044 private static final @NonNull ScimError INVALID_VERSION = new ScimError(400, ScimErrorType.INVALID_VERSION, "Invalid SCIM version.", null); 045 private static final @NonNull ScimError INVALID_CURSOR = new ScimError(400, ScimErrorType.INVALID_CURSOR, "Invalid pagination cursor.", null); 046 private static final @NonNull ScimError EXPIRED_CURSOR = new ScimError(400, ScimErrorType.EXPIRED_CURSOR, "The pagination cursor has expired.", null); 047 private static final @NonNull ScimError INVALID_COUNT = new ScimError(400, ScimErrorType.INVALID_COUNT, "Invalid pagination count.", null); 048 private static final @NonNull ScimError UNIQUENESS = new ScimError(409, ScimErrorType.UNIQUENESS, "The operation violates attribute uniqueness.", null); 049 private static final @NonNull ScimError SENSITIVE = new ScimError(403, ScimErrorType.SENSITIVE, "The sensitive operation is forbidden.", null); 050 private static final @NonNull ScimError UNAUTHENTICATED = new ScimError(401, null, "Authentication is required.", null); 051 private static final @NonNull ScimError FORBIDDEN = new ScimError(403, null, "The operation is forbidden.", null); 052 private static final @NonNull ScimError NOT_FOUND = new ScimError(404, null, "The resource was not found.", null); 053 private static final @NonNull ScimError PRECONDITION_FAILED = new ScimError(412, null, "The request precondition was not satisfied.", null); 054 private static final @NonNull ScimError REQUEST_TOO_LARGE = new ScimError(413, null, "The request exceeds the size limit.", null); 055 private static final @NonNull ScimError UNSUPPORTED_MEDIA_TYPE = new ScimError(415, null, "Unsupported media type.", null); 056 private static final @NonNull ScimError METHOD_NOT_ALLOWED = new ScimError(405, null, "The request method is not allowed.", null); 057 private static final @NonNull ScimError NOT_IMPLEMENTED = new ScimError(501, null, "The operation is not implemented.", null); 058 private static final @NonNull ScimError INTERNAL_ERROR = new ScimError(500, null, "The request could not be processed.", null); 059 private static final @NonNull ScimError RESPONSE_TOO_LARGE = new ScimError(500, null, "The response exceeds the size limit.", null); 060 private static final @NonNull ScimError UNAVAILABLE = new ScimError(503, null, "The service is unavailable.", null); 061 062 private final int statusCode; 063 private final @Nullable ScimErrorType errorType; 064 private final @NonNull String detail; 065 private final @Nullable Integer expressionOffset; 066 067 private ScimError(int statusCode, @Nullable ScimErrorType errorType, @NonNull String detail, 068 @Nullable Integer expressionOffset) { 069 this.statusCode = statusCode; 070 this.errorType = errorType; 071 this.detail = detail; 072 this.expressionOffset = expressionOffset; 073 } 074 075 /** 076 * Returns the HTTP status code. 077 * 078 * @return the HTTP status code 079 * @since 1.0.0 080 */ 081 public @NonNull Integer getStatusCode() { return statusCode; } 082 /** 083 * Returns the fixed SCIM error type, when defined. 084 * 085 * @return the fixed SCIM error type, when defined 086 * @since 1.0.0 087 */ 088 public @NonNull Optional<@NonNull ScimErrorType> getErrorType() { return Optional.ofNullable(errorType); } 089 /** 090 * Returns the fixed redacted detail. 091 * 092 * @return the fixed redacted detail 093 * @since 1.0.0 094 */ 095 public @NonNull String getDetail() { return detail; } 096 /** 097 * Returns the zero-based UTF-16 syntax-error offset, if the engine produced one. End-of-input 098 * errors can point one unit past the final character. 099 * @return the optional expression offset 100 * @since 1.0.0 101 */ 102 public @NonNull Optional<@NonNull Integer> getExpressionOffset() { return Optional.ofNullable(expressionOffset); } 103 104 /** 105 * Returns the fixed invalidFilter error with no expression offset. 106 * @return the singleton error 107 * @since 1.0.0 108 */ 109 public static @NonNull ScimError invalidFilterInstance() { return INVALID_FILTER; } 110 111 /** 112 * Returns the fixed tooMany error with no expression offset. 113 * @return the singleton error 114 * @since 1.0.0 115 */ 116 public static @NonNull ScimError tooManyInstance() { return TOO_MANY; } 117 118 /** 119 * Returns the fixed invalidSyntax error with no expression offset. 120 * @return the singleton error 121 * @since 1.0.0 122 */ 123 public static @NonNull ScimError invalidSyntaxInstance() { return INVALID_SYNTAX; } 124 125 /** 126 * Returns the fixed invalidPath error with no expression offset. 127 * @return the singleton error 128 * @since 1.0.0 129 */ 130 public static @NonNull ScimError invalidPathInstance() { return INVALID_PATH; } 131 132 /** 133 * Returns the fixed noTarget error with no expression offset. 134 * @return the singleton error 135 * @since 1.0.0 136 */ 137 public static @NonNull ScimError noTargetInstance() { return NO_TARGET; } 138 139 /** 140 * Returns the fixed invalidValue error with no expression offset. 141 * @return the singleton error 142 * @since 1.0.0 143 */ 144 public static @NonNull ScimError invalidValueInstance() { return INVALID_VALUE; } 145 146 /** 147 * Returns the fixed mutability error with no expression offset. 148 * @return the singleton error 149 * @since 1.0.0 150 */ 151 public static @NonNull ScimError mutabilityInstance() { return MUTABILITY; } 152 153 /** 154 * Returns the fixed invalidVersion error with no expression offset. 155 * @return the singleton error 156 * @since 1.0.0 157 */ 158 public static @NonNull ScimError invalidVersionInstance() { return INVALID_VERSION; } 159 160 /** 161 * Returns the fixed invalidCursor error with no expression offset. 162 * @return the singleton error 163 * @since 1.0.0 164 */ 165 public static @NonNull ScimError invalidCursorInstance() { return INVALID_CURSOR; } 166 167 /** 168 * Returns the fixed expiredCursor error with no expression offset. 169 * @return the singleton error 170 * @since 1.0.0 171 */ 172 public static @NonNull ScimError expiredCursorInstance() { return EXPIRED_CURSOR; } 173 174 /** 175 * Returns the fixed invalidCount error with no expression offset. 176 * @return the singleton error 177 * @since 1.0.0 178 */ 179 public static @NonNull ScimError invalidCountInstance() { return INVALID_COUNT; } 180 181 /** 182 * Returns the fixed uniqueness error with no expression offset. 183 * @return the singleton error 184 * @since 1.0.0 185 */ 186 public static @NonNull ScimError uniquenessInstance() { return UNIQUENESS; } 187 188 /** 189 * Returns the fixed sensitive error with no expression offset. 190 * @return the singleton error 191 * @since 1.0.0 192 */ 193 public static @NonNull ScimError sensitiveInstance() { return SENSITIVE; } 194 195 /** 196 * Returns the fixed unauthenticated error with no expression offset. 197 * @return the singleton error 198 * @since 1.0.0 199 */ 200 public static @NonNull ScimError unauthenticatedInstance() { return UNAUTHENTICATED; } 201 202 /** 203 * Returns the fixed forbidden error with no expression offset. 204 * @return the singleton error 205 * @since 1.0.0 206 */ 207 public static @NonNull ScimError forbiddenInstance() { return FORBIDDEN; } 208 209 /** 210 * Returns the fixed notFound error with no expression offset. 211 * @return the singleton error 212 * @since 1.0.0 213 */ 214 public static @NonNull ScimError notFoundInstance() { return NOT_FOUND; } 215 216 /** 217 * Returns the fixed preconditionFailed error with no expression offset. 218 * @return the singleton error 219 * @since 1.0.0 220 */ 221 public static @NonNull ScimError preconditionFailedInstance() { return PRECONDITION_FAILED; } 222 223 /** 224 * Returns the fixed requestTooLarge error with no expression offset. 225 * @return the singleton error 226 * @since 1.0.0 227 */ 228 public static @NonNull ScimError requestTooLargeInstance() { return REQUEST_TOO_LARGE; } 229 230 /** 231 * Returns the fixed unsupportedMediaType error with no expression offset. 232 * @return the singleton error 233 * @since 1.0.0 234 */ 235 public static @NonNull ScimError unsupportedMediaTypeInstance() { return UNSUPPORTED_MEDIA_TYPE; } 236 237 /** 238 * Returns the fixed methodNotAllowed error with no expression offset. 239 * @return the singleton error 240 * @since 1.0.0 241 */ 242 public static @NonNull ScimError methodNotAllowedInstance() { return METHOD_NOT_ALLOWED; } 243 244 /** 245 * Returns the fixed notImplemented error with no expression offset. 246 * @return the singleton error 247 * @since 1.0.0 248 */ 249 public static @NonNull ScimError notImplementedInstance() { return NOT_IMPLEMENTED; } 250 251 /** 252 * Returns the fixed internalError error with no expression offset. 253 * @return the singleton error 254 * @since 1.0.0 255 */ 256 public static @NonNull ScimError internalErrorInstance() { return INTERNAL_ERROR; } 257 258 /** 259 * Returns the fixed responseTooLarge error with no expression offset. 260 * @return the singleton error 261 * @since 1.0.0 262 */ 263 public static @NonNull ScimError responseTooLargeInstance() { return RESPONSE_TOO_LARGE; } 264 265 /** 266 * Returns the fixed unavailable error with no expression offset. 267 * @return the singleton error 268 * @since 1.0.0 269 */ 270 public static @NonNull ScimError unavailableInstance() { return UNAVAILABLE; } 271 272 static @NonNull ScimError invalidFilterAt(int offset) { 273 return withOffset(INVALID_FILTER, offset); 274 } 275 276 static @NonNull ScimError invalidPathAt(int offset) { 277 return withOffset(INVALID_PATH, offset); 278 } 279 280 private static @NonNull ScimError withOffset(@NonNull ScimError error, int offset) { 281 if (offset < 0 || offset > Limits.SCIM_FILTER_LENGTH.getCap()) 282 throw new IllegalArgumentException("SCIM expression offset exceeds its bound."); 283 return new ScimError(error.statusCode, error.errorType, error.detail, offset); 284 } 285 286 /** 287 * Returns a fixed redacted description. 288 * 289 * @return a fixed redacted description 290 * @since 1.0.0 291 */ 292 @Override public @NonNull String toString() { 293 return "ScimError{status=" + statusCode + ", type=" + (errorType == null ? "absent" : errorType.getValue()) 294 + ", <redacted>}"; 295 } 296}