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 javax.annotation.concurrent.ThreadSafe;
022import javax.annotation.concurrent.Immutable;
023
024/**
025 * Fixed redacted events for SCIM operations. Hooks must be fast, deterministic and thread-safe.
026 * The facade contains ordinary hook failures and restores interruption; fatal VM errors escape.
027 * Events never carry request bodies, filters, identifiers, credentials or arbitrary exceptions.
028 * @since 1.0.0
029 */
030@ThreadSafe
031public interface ScimObserver {
032    /**
033     * Returns the shared observer whose hooks do nothing.
034     * @return the disabled observer
035     * @since 1.0.0
036     */
037    @CheckReturnValue
038    static @NonNull ScimObserver disabledInstance() { return DisabledScimObserver.INSTANCE; }
039
040    /**
041     * Called once before a public processing operation.
042     * @param operation the fixed operation kind
043     * @since 1.0.0
044     */
045    default void willProcess(@NonNull Operation operation) {}
046
047    /**
048     * Called once for checked completion, including an expected rejection, of a public processing operation.
049     * An unexpected processing fault instead calls didFailToProcess, even when a fixed error result
050     * is returned to the caller.
051     * @param operation the fixed operation kind
052     * @param outcome the fixed result classification
053     * @since 1.0.0
054     */
055    default void didProcess(@NonNull Operation operation, @NonNull Outcome outcome) {}
056
057    /**
058     * Called once when an unexpected processing fault is contained as a fixed internalError result.
059     * This replaces didProcess for that operation; the caller still receives its fixed error outcome.
060     * Events disclose no fault payload. Interruption is preserved, and fatal VM errors escape.
061     * @param operation the fixed operation kind
062     * @since 1.0.0
063     */
064    default void didFailToProcess(@NonNull Operation operation) {}
065
066    /**
067     * Called once per feature actually used during a public operation.
068     * @param feature the explicitly configured fixed feature
069     * @since 1.0.0
070     */
071    default void didUseCompatibilityFeature(@NonNull ScimCompatibilityFeature feature) {}
072
073    /**
074     * Fixed public processing operation kinds, including separately sequenced PATCH operations.
075     * @since 1.0.0
076     */
077    @Immutable
078    enum Operation {
079        /** Parse and approve a filter. */
080        FILTER,
081        /** Parse a collection query. */
082        QUERY,
083        /** Parse a SearchRequest. */
084        SEARCH,
085        /** Parse a projection. */
086        ATTRIBUTE_SELECTION,
087        /** Parse a create candidate. */
088        RESOURCE_CREATE,
089        /** Parse a replacement candidate. */
090        RESOURCE_REPLACE,
091        /** Parse a PATCH request. */
092        PATCH_PARSE,
093        /** Apply a PATCH request. */
094        PATCH_APPLY,
095        /** Reduce reviewed membership steps. */
096        MEMBERSHIP_REDUCE,
097        /** Validate a request media type. */
098        CONTENT_TYPE,
099        /** Check If-Match. */
100        IF_MATCH,
101        /** Check If-None-Match. */
102        IF_NONE_MATCH,
103        /** Prepare a bounded response. */
104        RESPONSE_PREPARE,
105        /** Evaluate an approved filter. */
106        FILTER_EVALUATE
107    }
108
109    /**
110     * Fixed direct-result classifications, without data or exception payloads.
111     * @since 1.0.0
112     */
113    @Immutable
114    enum Outcome {
115        /** A checked candidate or query was produced. */
116        SUCCEEDED,
117        /** A bounded response was prepared. */
118        PREPARED,
119        /** Processing rejected input. */
120        REJECTED,
121        /** A precondition was satisfied. */
122        SATISFIED,
123        /** A request may proceed. */
124        PROCEED,
125        /** The existing resource matched a conditional read. */
126        NOT_MODIFIED,
127        /** A valid membership request requires full evaluation. */
128        REQUIRES_FULL_EVALUATION
129    }
130}
131
132final class DisabledScimObserver implements ScimObserver {
133    static final @NonNull ScimObserver INSTANCE = new DisabledScimObserver();
134    private DisabledScimObserver() {}
135}