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}