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.soklet;
018
019import com.google.errorprone.annotations.CheckReturnValue;
020import com.revetsec.scim.ScimAttributeSelectionResult;
021import com.revetsec.scim.ScimIfMatchResult;
022import com.revetsec.scim.ScimIfNoneMatchResult;
023import com.revetsec.scim.ScimQueryParseResult;
024import com.revetsec.scim.ScimPatchParseResult;
025import com.revetsec.scim.ScimResource;
026import com.revetsec.scim.ScimResourceParseResult;
027import com.revetsec.scim.ScimResourceType;
028import com.revetsec.scim.ScimResponse;
029import com.revetsec.scim.ScimServiceProvider;
030import com.soklet.MarshaledResponse;
031import com.soklet.Request;
032import org.jspecify.annotations.NonNull;
033
034import javax.annotation.concurrent.ThreadSafe;
035import java.util.AbstractList;
036import java.util.List;
037import java.util.Map;
038
039import static java.util.Objects.requireNonNull;
040
041/**
042 * Thin SCIM transport helpers for application-routed Soklet endpoints. Applications select the authenticated caller,
043 * tenant, resource type and transaction, and enforce route methods. Each parser invokes one core operation using the
044 * unchanged materialized raw query, body and physical header occurrences.
045 * Reject {@link Request#isContentTooLarge()} before invoking a body helper, using an application response such as
046 * {@code provider.errorResponse(ScimError.requestTooLargeInstance())}. Body helpers also fail closed if the caller
047 * omits this check. Soklet discards an oversized request body; the transport cannot pass it to core.
048 * Configure upstream body, complete-request and header limits before requests are materialized. The application
049 * also supplies authentication challenges and method-specific Allow headers when composing transport responses.
050 *
051 * @since 1.0.0
052 */
053@ThreadSafe
054public final class SokletScim {
055    private SokletScim() { }
056
057    /** Parses the untouched resource-list query.
058     * @param provider the application's configured service provider
059     * @param resourceType the application-selected registered resource type
060     * @param request the materialized routed request
061     * @return the core query result
062     * @since 1.0.0
063     */
064    @CheckReturnValue
065    public static @NonNull ScimQueryParseResult queryResultFor(@NonNull ScimServiceProvider provider,
066            @NonNull ScimResourceType resourceType, @NonNull Request request) {
067        requireNonNull(provider); requireNonNull(resourceType); requireNonNull(request);
068        return provider.parseQueryResult(resourceType, request.getRawQuery().orElse(""));
069    }
070
071    /** Parses unchanged SearchRequest bytes and original Content-Type occurrences.
072     * The application should reject {@code request.isContentTooLarge()} to emit an appropriate HTTP response.
073     * @param provider the application's configured service provider
074     * @param resourceType the application-selected registered resource type
075     * @param request the materialized routed request
076     * @return the core query result
077
078     * @since 1.0.0
079     */
080    @CheckReturnValue
081    public static @NonNull SokletRequestResult<@NonNull ScimQueryParseResult> searchRequestResultFor(@NonNull ScimServiceProvider provider,
082            @NonNull ScimResourceType resourceType, @NonNull Request request) {
083        requireNonNull(provider); requireNonNull(resourceType); requireNonNull(request);
084        if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge();
085        return SokletRequestResult.fromResult(provider.parseSearchRequestResult(resourceType, headerValues(request, "Content-Type"),
086                SokletOAuth.bodyBytesFor(request)));
087    }
088
089    /** Parses unchanged create-resource bytes and original Content-Type occurrences.
090     * The application should reject {@code request.isContentTooLarge()} to emit an appropriate HTTP response.
091     * @param provider the application's configured service provider
092     * @param resourceType the application-selected registered resource type
093     * @param request the materialized routed request
094     * @return the core candidate resource result
095
096     * @since 1.0.0
097     */
098    @CheckReturnValue
099    public static @NonNull SokletRequestResult<@NonNull ScimResourceParseResult> resourceResultFor(@NonNull ScimServiceProvider provider,
100            @NonNull ScimResourceType resourceType, @NonNull Request request) {
101        requireNonNull(provider); requireNonNull(resourceType); requireNonNull(request);
102        if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge();
103        return SokletRequestResult.fromResult(provider.parseResourceResult(resourceType, headerValues(request, "Content-Type"),
104                SokletOAuth.bodyBytesFor(request)));
105    }
106
107    /** Parses unchanged replacement bytes against the application-selected current resource.
108     * The application should reject {@code request.isContentTooLarge()} to emit an appropriate HTTP response.
109     * @param provider the application's configured service provider
110     * @param resourceType the application-selected registered resource type
111     * @param current the authoritative current resource used by the application transaction
112     * @param request the materialized routed request
113     * @return the core replacement candidate result
114
115     * @since 1.0.0
116     */
117    @CheckReturnValue
118    public static @NonNull SokletRequestResult<@NonNull ScimResourceParseResult> replacementResultFor(@NonNull ScimServiceProvider provider,
119            @NonNull ScimResourceType resourceType, @NonNull ScimResource current, @NonNull Request request) {
120        requireNonNull(provider); requireNonNull(resourceType); requireNonNull(current); requireNonNull(request);
121        if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge();
122        return SokletRequestResult.fromResult(provider.parseReplacementResult(resourceType, current, headerValues(request, "Content-Type"),
123                SokletOAuth.bodyBytesFor(request)));
124    }
125
126    /** Parses unchanged PatchOp bytes and original Content-Type occurrences.
127     * The application should reject {@code request.isContentTooLarge()} to emit an appropriate HTTP response.
128     * @param provider the application's configured service provider
129     * @param resourceType the application-selected registered resource type
130     * @param request the materialized routed request
131     * @return the core schema-bound PATCH request result
132
133     * @since 1.0.0
134     */
135    @CheckReturnValue
136    public static @NonNull SokletRequestResult<@NonNull ScimPatchParseResult> patchRequestResultFor(@NonNull ScimServiceProvider provider,
137            @NonNull ScimResourceType resourceType, @NonNull Request request) {
138        requireNonNull(provider); requireNonNull(resourceType); requireNonNull(request);
139        if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge();
140        return SokletRequestResult.fromResult(provider.parsePatchRequestResult(resourceType, headerValues(request, "Content-Type"),
141                SokletOAuth.bodyBytesFor(request)));
142    }
143
144    /** Parses resource-response selection from the unchanged raw query.
145     * @param provider the application's configured service provider
146     * @param resourceType the application-selected registered resource type
147     * @param request the materialized routed request
148     * @return the core attribute-selection result
149     * @since 1.0.0
150     */
151    @CheckReturnValue
152    public static @NonNull ScimAttributeSelectionResult attributeSelectionResultFor(@NonNull ScimServiceProvider provider,
153            @NonNull ScimResourceType resourceType, @NonNull Request request) {
154        requireNonNull(provider); requireNonNull(resourceType); requireNonNull(request);
155        return provider.parseAttributeSelectionResult(resourceType, request.getRawQuery().orElse(""));
156    }
157
158    /** Checks every original If-Match occurrence against the same current resource used by the application write.
159     * @param provider the application's configured service provider
160     * @param current the authoritative current resource
161     * @param request the materialized routed request
162     * @return the core conditional result
163     * @since 1.0.0
164     */
165    @CheckReturnValue
166    public static @NonNull ScimIfMatchResult ifMatchResultFor(@NonNull ScimServiceProvider provider,
167            @NonNull ScimResource current, @NonNull Request request) {
168        requireNonNull(provider); requireNonNull(current); requireNonNull(request);
169        return provider.checkIfMatchResult(headerValues(request, "If-Match"), current);
170    }
171
172    /** Checks every original If-None-Match occurrence for application-routed GET or HEAD handling.
173     * @param provider the application's configured service provider
174     * @param current the authoritative current resource
175     * @param request the materialized routed request
176     * @return the core conditional result
177     * @since 1.0.0
178     */
179    @CheckReturnValue
180    public static @NonNull ScimIfNoneMatchResult ifNoneMatchResultFor(@NonNull ScimServiceProvider provider,
181            @NonNull ScimResource current, @NonNull Request request) {
182        requireNonNull(provider); requireNonNull(current); requireNonNull(request);
183        return provider.checkIfNoneMatchResult(headerValues(request, "If-None-Match"), current);
184    }
185
186    /** Emits exactly the core-prepared status, header occurrences and body bytes, which may contain personal data.
187     * @param response the restricted core-prepared response
188     * @return the exact-byte Soklet response
189     * @since 1.0.0
190     */
191    @CheckReturnValue
192    public static @NonNull MarshaledResponse responseFor(@NonNull ScimResponse response) {
193        requireNonNull(response);
194        MarshaledResponse.Builder builder = MarshaledResponse.withStatusCode(response.getStatusCode()).headers(response.getHeaders());
195        byte[] bytes = response.toHttpBodyWithPersonalData();
196        // Soklet requires no entity for 204/304; supplying even a zero-length entity is rejected at dispatch.
197        if (bytes.length > 0) builder.body(bytes);
198        return builder.build();
199    }
200
201    /** A bounded core parser can inspect occurrence counts before any hostile collection is copied or joined. */
202    private static @NonNull List<@NonNull String> headerValues(@NonNull Request request, @NonNull String name) {
203        return new HeaderValues(request.getHeaders(), name);
204    }
205
206    @ThreadSafe
207    private static final class HeaderValues extends AbstractList<@NonNull String> {
208        private final @NonNull Map<@NonNull String, @NonNull List<@NonNull String>> fields;
209        private final @NonNull String name;
210        private HeaderValues(@NonNull Map<@NonNull String, @NonNull List<@NonNull String>> fields, @NonNull String name) {
211            this.fields = fields; this.name = name;
212        }
213        @Override public int size() {
214            long count = 0;
215            for (Map.Entry<String, List<String>> field : fields.entrySet()) if (sameName(name, field.getKey())) {
216                count += field.getValue().size();
217                if (count >= Integer.MAX_VALUE) return Integer.MAX_VALUE;
218            }
219            return (int) count;
220        }
221        @Override public @NonNull String get(int index) {
222            if (index < 0) throw new IndexOutOfBoundsException();
223            for (Map.Entry<String, List<String>> field : fields.entrySet()) if (sameName(name, field.getKey())) {
224                List<String> values = field.getValue();
225                if (index < values.size()) return values.get(index);
226                index -= values.size();
227            }
228            throw new IndexOutOfBoundsException();
229        }
230    }
231
232    private static boolean sameName(@NonNull String expected, @NonNull String actual) {
233        if (expected.length() != actual.length()) return false;
234        for (int index = 0; index < expected.length(); ++index) {
235            char left = expected.charAt(index), right = actual.charAt(index);
236            if (left >= 'A' && left <= 'Z') left = (char) (left + 32);
237            if (right >= 'A' && right <= 'Z') right = (char) (right + 32);
238            if (left != right) return false;
239        }
240        return true;
241    }
242}