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 org.jspecify.annotations.NonNull;
021import org.jspecify.annotations.Nullable;
022import javax.annotation.concurrent.Immutable;
023import javax.annotation.concurrent.NotThreadSafe;
024import java.util.Collections;
025import java.util.EnumSet;
026import java.util.Set;
027
028/**
029 * Immutable, explicitly selected SCIM compatibility features. Presets are configuration only;
030 * no feature is inferred from User-Agent, credentials, payload, or earlier traffic.
031 * @since 1.0.0
032 */
033@Immutable
034@CheckReturnValue
035public final class ScimCompatibility {
036    private final @NonNull Set<@NonNull ScimCompatibilityFeature> features;
037    private ScimCompatibility(@NonNull Builder builder) { features = builder.features; }
038
039    /**
040     * Starts strict configuration with no enabled features.
041     * @return a new builder
042     * @since 1.0.0
043     */
044    public static @NonNull Builder builder() { return new Builder(); }
045
046    /**
047     * Returns strict configuration with no enabled compatibility relaxations.
048     * @return the shared strict snapshot
049     * @since 1.0.0
050     */
051    public static @NonNull ScimCompatibility strictInstance() { return Defaults.STRICT; }
052
053    /**
054     * Returns the exact reviewed Microsoft Entra ID feature set. Scalar Enterprise manager
055     * values and dropping unknown attributes remain disabled.
056     * @return the shared Microsoft Entra ID snapshot
057     * @since 1.0.0
058     */
059    public static @NonNull ScimCompatibility microsoftEntraIdInstance() { return Defaults.ENTRA; }
060
061    /**
062     * Returns the reviewed Okta feature set: operation-name casing, identical PATCH id echo and ignored Group member display input.
063     * @return the shared Okta snapshot
064     * @since 1.0.0
065     */
066    public static @NonNull ScimCompatibility oktaInstance() { return Defaults.OKTA; }
067
068    /**
069     * Returns the complete immutable selected feature set.
070     * @return the immutable feature set
071     * @since 1.0.0
072     */
073    public @NonNull Set<@NonNull ScimCompatibilityFeature> getFeatures() { return features; }
074
075    /**
076     * Compares the selected features.
077     * @param other the comparison value
078     * @return whether selected feature sets are equal
079     * @since 1.0.0
080     */
081    @Override public boolean equals(@Nullable Object other) {
082        return this == other || (other instanceof ScimCompatibility value && features.equals(value.features));
083    }
084
085    /**
086     * Returns the selected-feature hash.
087     * @return the selected-feature hash
088     * @since 1.0.0
089     */
090    @Override public int hashCode() { return features.hashCode(); }
091
092    /**
093     * Returns a bounded description containing only the number of selected fixed features.
094     * @return a bounded configuration description
095     * @since 1.0.0
096     */
097    @Override public @NonNull String toString() { return "ScimCompatibility{features=" + features.size() + "}"; }
098
099    private static final class Defaults {
100        private static final @NonNull ScimCompatibility STRICT = builder().build();
101        private static final @NonNull ScimCompatibility ENTRA = builder().features(Set.of(
102                ScimCompatibilityFeature.PATCH_OPERATION_NAME_CASE_INSENSITIVE,
103                ScimCompatibilityFeature.BOOLEAN_STRINGS,
104                ScimCompatibilityFeature.PATCH_REMOVE_WITH_VALUE,
105                ScimCompatibilityFeature.PATCH_VALUE_PATH_UPSERT,
106                ScimCompatibilityFeature.PATCH_VALUE_OBJECT_ATTRIBUTE_PATHS,
107                ScimCompatibilityFeature.FILTER_VALUE_PATH_SUB_ATTRIBUTE_COMPARISON,
108                ScimCompatibilityFeature.INFER_MISSING_EXTENSION_SCHEMAS,
109                ScimCompatibilityFeature.IGNORE_UNDECLARED_SCHEMA_URIS)).build();
110        private static final @NonNull ScimCompatibility OKTA = builder().features(Set.of(
111                ScimCompatibilityFeature.PATCH_OPERATION_NAME_CASE_INSENSITIVE,
112                ScimCompatibilityFeature.PATCH_READ_ONLY_ID_ECHO,
113                ScimCompatibilityFeature.PATCH_GROUP_MEMBER_DISPLAY_IGNORED)).build();
114        private Defaults() {}
115    }
116
117    /**
118     * Mutable, non-thread-safe complete feature-set configuration.
119     * @since 1.0.0
120     */
121    @NotThreadSafe
122    @CheckReturnValue
123    public static final class Builder {
124        private @NonNull Set<@NonNull ScimCompatibilityFeature> features = Set.of();
125        private Builder() {}
126
127        /**
128         * Replaces and snapshots all features; null restores the empty strict set.
129         * @param value the feature set, or null for strict behavior
130         * @return this builder
131         * @since 1.0.0
132         */
133        public @NonNull Builder features(@Nullable Set<@NonNull ScimCompatibilityFeature> value) {
134            if (value == null || value.isEmpty()) features = Set.of();
135            else {
136                if (value.size() > ScimCompatibilityFeature.values().length)
137                    throw new IllegalArgumentException("SCIM compatibility feature count exceeds its inventory.");
138                features = Collections.unmodifiableSet(EnumSet.copyOf(value));
139            }
140            return this;
141        }
142
143        /**
144         * Creates an immutable complete feature snapshot without callbacks.
145         * @return selected compatibility configuration
146         * @since 1.0.0
147         */
148        public @NonNull ScimCompatibility build() { return new ScimCompatibility(this); }
149    }
150}