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}