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 static java.util.Objects.requireNonNull;
020
021import com.google.errorprone.annotations.CheckReturnValue;
022import org.jspecify.annotations.NonNull;
023import org.jspecify.annotations.Nullable;
024
025import javax.annotation.concurrent.Immutable;
026import java.util.Collections;
027import java.util.LinkedHashSet;
028import java.util.List;
029import java.util.Optional;
030import java.util.Set;
031
032/**
033 * Ordered, ID-only Group membership instructions and the remaining resource operations.
034 * Applications execute both parts in original operation-index order under one authorization
035 * decision, transaction and version predicate. Existing member metadata and represented order
036 * must be retained when adding an existing ID or retaining an ID during replacement; removing
037 * then adding an ID creates a new member without the removed metadata.
038 * <p>
039 * Reduction does not inspect current membership and cannot establish whether anything changed.
040 * Applications require assigned, unique member IDs in their keyed storage snapshot and preserve
041 * whether the optional members attribute is absent or holds an empty array. Duplicate IDs in a
042 * whole-array replacement require full evaluation.
043 * Explicit value getters may disclose personal data; diagnostics redact them.
044 *
045 * @since 1.0.0
046 */
047@Immutable
048@CheckReturnValue
049public final class ScimMembershipPatch {
050    private final @NonNull ScimResourceType resourceType;
051    private final @NonNull List<@NonNull Step> steps;
052    private final @Nullable ScimPatchRequest remainingPatchRequest;
053    private final @NonNull Set<@NonNull ScimAttributePath> requestedAttributePaths;
054    private final @NonNull Set<@NonNull ScimAttributePath> suppliedAttributePaths;
055
056    ScimMembershipPatch(@NonNull ScimResourceType resourceType,
057            @NonNull List<@NonNull Step> steps, @Nullable ScimPatchRequest remainingPatchRequest,
058            @NonNull Set<@NonNull ScimAttributePath> requestedAttributePaths,
059            @NonNull Set<@NonNull ScimAttributePath> suppliedAttributePaths) {
060        this.resourceType = requireNonNull(resourceType);
061        this.steps = List.copyOf(steps);
062        this.remainingPatchRequest = remainingPatchRequest;
063        this.requestedAttributePaths = Collections.unmodifiableSet(new LinkedHashSet<>(requestedAttributePaths));
064        this.suppliedAttributePaths = Collections.unmodifiableSet(new LinkedHashSet<>(suppliedAttributePaths));
065    }
066
067    /** Returns the original resource-type registration.
068     * @return resource type
069     * @since 1.0.0
070     */
071    public @NonNull ScimResourceType getResourceType() { return resourceType; }
072
073    /** Returns membership steps in original request order.
074     * @return immutable ordered steps
075     * @since 1.0.0
076     */
077    public @NonNull List<@NonNull Step> getSteps() { return steps; }
078
079    /** Returns remaining nonmember operations with their original indexes and private provenance.
080     * @return the remaining request, or empty when every operation was reduced
081     * @since 1.0.0
082     */
083    public @NonNull Optional<@NonNull ScimPatchRequest> getRemainingPatchRequest() {
084        return Optional.ofNullable(remainingPatchRequest);
085    }
086
087    /** Returns attempted canonical paths from the complete original request, including no-op attempts.
088     * @return immutable requested paths
089     * @since 1.0.0
090     */
091    public @NonNull Set<@NonNull ScimAttributePath> getRequestedAttributePaths() { return requestedAttributePaths; }
092
093    /** Returns canonical paths actually supplied by the complete original request.
094     * @return immutable supplied paths
095     * @since 1.0.0
096     */
097    public @NonNull Set<@NonNull ScimAttributePath> getSuppliedAttributePaths() { return suppliedAttributePaths; }
098
099    /** Returns a fixed redacted diagnostic.
100     * @return redacted description
101     * @since 1.0.0
102     */
103    @Override public @NonNull String toString() { return "ScimMembershipPatch{<redacted>}"; }
104
105    /** One executable membership instruction at its original zero-based operation position.
106     * @since 1.0.0
107     */
108    @Immutable
109    @CheckReturnValue
110    public static final class Step {
111        private final int operationIndex;
112        private final @NonNull Kind kind;
113        private final @NonNull List<@NonNull String> values;
114
115        Step(int operationIndex, @NonNull Kind kind, @NonNull List<@NonNull String> values) {
116            this.operationIndex = operationIndex;
117            this.kind = requireNonNull(kind);
118            this.values = List.copyOf(values);
119        }
120
121        /** Returns the original zero-based operation index.
122         * @return original index
123         * @since 1.0.0
124         */
125        public @NonNull Integer getOperationIndex() { return operationIndex; }
126
127        /** Returns the instruction kind.
128         * @return kind
129         * @since 1.0.0
130         */
131        public @NonNull Kind getKind() { return kind; }
132
133        /** Returns exact IDs in input order; CLEAR has an empty list.
134         * @return immutable ID values, which may contain personal data
135         * @since 1.0.0
136         */
137        public @NonNull List<@NonNull String> getValues() { return values; }
138
139        /** Returns a fixed redacted diagnostic.
140         * @return redacted description
141         * @since 1.0.0
142         */
143        @Override public @NonNull String toString() { return "ScimMembershipPatch.Step{<redacted>}"; }
144    }
145
146    /** Ordered instruction kinds; compare member IDs exactly, regardless of text collation.
147     * @since 1.0.0
148     */
149    @Immutable
150    public enum Kind {
151        /** Append IDs absent from current membership, preserving existing metadata and order.
152         * An empty values list is a no-op that preserves absent, empty or assigned membership. */
153        ADD_IDS,
154        /** Remove the exact IDs if present; absent IDs are no-ops.
155         * Removing the last value from an existing members array leaves it present and empty. */
156        REMOVE_IDS,
157        /** Remove the optional members attribute, yielding absence rather than a present empty array.
158         * This differs from REPLACE_IDS with an empty list. */
159        CLEAR,
160        /** Replace represented sequence, retaining metadata for surviving exact IDs; an empty list represents an empty array. */
161        REPLACE_IDS
162    }
163}