/*
 * Copyright 2022-2026 Revetware LLC.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.soklet;

import org.jspecify.annotations.NonNull;
import org.jspecify.annotations.Nullable;

import javax.annotation.concurrent.NotThreadSafe;
import javax.annotation.concurrent.ThreadSafe;
import java.net.URI;
import java.util.List;
import java.util.Optional;
import java.util.Set;

import static java.util.Objects.requireNonNull;

/**
 * Immutable programmatic registration for one MCP resource-read route.
 *
 * <p>Registration is staged so a handler must be supplied before optional
 * descriptor metadata can be configured. Exact and template registrations
 * intentionally expose different builders: only an exact resource may
 * advertise a size. The registration cache policy owns the fixed scope and
 * default time to live for reads; the default is
 * {@link McpCachePolicy#privateNoCacheInstance()}.
 *
 * <p>Registration validates address structure and routing, not deployment
 * safety. The application owns an allowlist based on how each URI is delivered
 * or dereferenced. Direct-client addresses and handler-only custom addresses
 * commonly require different scheme, authority, credential, query, and
 * fragment rules. A filesystem-backed handler additionally owns canonical
 * root containment, symlink policy, authorization, and safe opening; Soklet
 * does not map registered URIs to files.
 *
 * @author <a href="https://www.revetkn.com">Mark Allen</a>
 */
@ThreadSafe
public final class McpResourceRegistration {
        @NonNull
        private final McpResourceAddressType addressType;
        @Nullable
        private final URI uri;
        @Nullable
        private final String uriTemplate;
        @NonNull
        private final String name;
        @NonNull
        private final Set<@NonNull McpProtocolVersion> protocolVersions;
        @Nullable
        private final String title;
        @Nullable
        private final String description;
        @Nullable
        private final String mimeType;
        @NonNull
        private final List<@NonNull McpIcon> icons;
        @Nullable
        private final McpContentAnnotations annotations;
        @Nullable
        private final Long sizeInBytes;
        @NonNull
        private final McpCachePolicy cachePolicy;
        @NonNull
        private final List<@NonNull McpInputRequestDeclaration> inputRequestDeclarations;
        @NonNull
        private final McpRequestStateMode requestStateMode;
        @NonNull
        private final McpJsonObject metadata;
        @NonNull
        private final McpResourceReadHandler handler;
        @Nullable
        private final McpCompletionHandler completionHandler;
        @NonNull
        private final Set<@NonNull McpProtocolVersion> completionProtocolVersions;

        /**
         * Begins a staged exact-resource registration.
         *
         * <p>Acceptance here does not mean that the URI is safe for direct client
         * loading or for application-side dereference. Apply a deployment policy
         * for the address's intended delivery path.
         *
         * <p>This method validates the URI's shape. Construction of the enclosing
         * {@link McpServer} later applies the 1,048,576-byte ASCII wire limit and
         * complete endpoint route validation.
         * IPv6 zone identifiers are excluded from the RFC 3986 URI contract.
         *
         * @param uri absolute normalized resource URI in ASCII wire form
         * @param name nonblank resource name
         * @param protocolVersions nonempty exact revisions serving this resource
         * @return required-handler stage
         * @throws IllegalArgumentException if the URI is relative, not normalized,
         * not in ASCII wire form, contains an IPv6 zone identifier, or the name is blank
         */
        @NonNull
        public static ExactHandlerStage withUriAndName(@NonNull URI uri,
                        @NonNull String name,
                        @NonNull Set<@NonNull McpProtocolVersion> protocolVersions) {
                return new ExactHandlerStage(requireExactUri(uri), requireName(name),
                                McpProtocolVersion.requiredSet(protocolVersions));
        }

        /**
         * Begins a staged URI-template resource registration.
         *
         * <p>This method performs inexpensive local validation. Construction of the
         * enclosing {@link McpServer} performs complete RFC 6570 Level 1 parsing and
         * route validation, including the template-size, variable-name,
         * variable-count, and overlap-work limits documented in the MCP guide. It
         * also enforces the limit of 256 URI templates per endpoint at server
         * construction. IPv6 zone identifiers are excluded from the RFC 3986 URI
         * contract, including identifiers containing template variables.
         *
         * <p>Level 1 simple variables do not consume a raw slash. For example,
         * {@code file:///{path}} matches {@code file:///src%2Fmain.rs} with variable
         * value {@code src/main.rs}, but does not match {@code file:///src/main.rs}.
         * Captured values are UTF-8 percent-decoded exactly once; {@code %252F}
         * becomes the literal string {@code %2F}. Reserved expansion
         * ({@code {+path}}), explode and prefix modifiers are unsupported.
         *
         * <p>Neither validation step authorizes expanded URIs or establishes that
         * their scheme is safe for the application's delivery intent.
         *
         * @param uriTemplate nonblank URI template containing simple
         * {@code {variable}} expressions
         * @param name nonblank resource name
         * @param protocolVersions nonempty exact revisions serving this resource
         * @return required-handler stage
         * @throws IllegalArgumentException if the template fails local structural
         * validation or the name is blank
         */
        @NonNull
        public static TemplateHandlerStage withUriTemplateAndName(
                        @NonNull String uriTemplate, @NonNull String name,
                        @NonNull Set<@NonNull McpProtocolVersion> protocolVersions) {
                return new TemplateHandlerStage(
                                requireBasicUriTemplate(uriTemplate), requireName(name),
                                McpProtocolVersion.requiredSet(protocolVersions));
        }

        private McpResourceRegistration(@NonNull BuilderState state) {
                this.addressType = state.addressType;
                this.uri = state.uri;
                this.uriTemplate = state.uriTemplate;
                this.name = state.name;
                this.protocolVersions = state.protocolVersions;
                this.title = state.title;
                this.description = state.description;
                this.mimeType = state.mimeType;
                this.icons = List.copyOf(state.icons);
                this.annotations = state.annotations;
                this.sizeInBytes = state.sizeInBytes;
                this.cachePolicy = state.cachePolicy;
                this.inputRequestDeclarations =
                                List.copyOf(state.inputRequestDeclarations);
                this.requestStateMode = state.requestStateMode;
                this.metadata = com.soklet.internal.mcp.protocol.McpApplicationMetadata.requireApplicationMetadata(state.metadata);
                this.handler = state.handler;
                this.completionHandler = state.completionHandler;
                this.completionProtocolVersions = state.completionProtocolVersions;
        }

        /** @return whether this registration uses an exact URI or URI template */
        @NonNull
        public McpResourceAddressType getAddressType() {
                return this.addressType;
        }

        /** @return exact resource URI, or empty for a template registration */
        @NonNull
        public Optional<@NonNull URI> getUri() {
                return Optional.ofNullable(this.uri);
        }

        /** @return resource URI template, or empty for an exact registration */
        @NonNull
        public Optional<@NonNull String> getUriTemplate() {
                return Optional.ofNullable(this.uriTemplate);
        }

        /** @return nonblank resource name */
        @NonNull
        public String getName() {
                return this.name;
        }

        /** @return exact protocol revisions on which this resource is available */
        @NonNull
        public Set<@NonNull McpProtocolVersion> getProtocolVersions() {
                return this.protocolVersions;
        }

        /** @return human-readable title, if configured */
        @NonNull
        public Optional<@NonNull String> getTitle() {
                return Optional.ofNullable(this.title);
        }

        /** @return human-readable description, if configured */
        @NonNull
        public Optional<@NonNull String> getDescription() {
                return Optional.ofNullable(this.description);
        }

        /** @return resource MIME type, if configured */
        @NonNull
        public Optional<@NonNull String> getMimeType() {
                return Optional.ofNullable(this.mimeType);
        }

        /** @return immutable icon list in insertion order */
        @NonNull
        public List<@NonNull McpIcon> getIcons() {
                return this.icons;
        }

        /** @return content annotations, if configured */
        @NonNull
        public Optional<@NonNull McpContentAnnotations> getAnnotations() {
                return Optional.ofNullable(this.annotations);
        }

        /**
         * Returns the exact resource's advertised size.
         *
         * @return nonnegative byte count, or empty when omitted or templated
         */
        @NonNull
        public Optional<@NonNull Long> getSizeInBytes() {
                return Optional.ofNullable(this.sizeInBytes);
        }

        /** @return fixed scope and default time to live for resource reads */
        @NonNull
        public McpCachePolicy getCachePolicy() {
                return this.cachePolicy;
        }

        /**
         * Returns the input requests this resource-read operation may emit.
         *
         * @return immutable declarations in registration order
         */
        @NonNull
        public List<@NonNull McpInputRequestDeclaration>
                        getInputRequestDeclarations() {
                return this.inputRequestDeclarations;
        }

        /**
         * Returns the request-state contract for this resource-read operation.
         *
         * @return request-state mode
         */
        @NonNull
        public McpRequestStateMode getRequestStateMode() {
                return this.requestStateMode;
        }

        /** @return immutable protocol extension metadata */
        @NonNull
        public McpJsonObject getMetadata() {
                return this.metadata;
        }

        /** @return resource-read handler */
        @NonNull
        public McpResourceReadHandler getHandler() {
                return this.handler;
        }

        /**
         * Returns the template's argument completer, when configured.
         *
         * @return configured completer, or empty for exact resources and templates
         * without one
         */
        @NonNull
        public Optional<@NonNull McpCompletionHandler> getCompletionHandler() {
                return Optional.ofNullable(this.completionHandler);
        }

        /** @return exact revisions on which the completion handler is available */
        @NonNull
        public Set<@NonNull McpProtocolVersion> getCompletionProtocolVersions() {
                return this.completionProtocolVersions;
        }

        @NonNull
        private static URI requireExactUri(@NonNull URI uri) {
                return McpResourceValueSupport.requireAbsoluteNormalizedUri(uri);
        }

        @NonNull
        private static String requireName(@NonNull String name) {
                McpContentValueSupport.requireWellFormedString(name);
                if (name.isBlank())
                        throw new IllegalArgumentException(
                                        "MCP resource names must not be blank.");
                return name;
        }

        @NonNull
        private static String requireMimeType(@NonNull String mimeType) {
                return McpContentValueSupport.requireMimeType(mimeType);
        }

        @NonNull
        private static String requireBasicUriTemplate(
                        @NonNull String uriTemplate) {
                McpContentValueSupport.requireWellFormedString(uriTemplate);
                if (uriTemplate.isBlank())
                        throw new IllegalArgumentException(
                                        "MCP resource URI templates must not be blank.");

                boolean foundVariable = false;
                for (int index = 0; index < uriTemplate.length(); index++) {
                        char character = uriTemplate.charAt(index);
                        if (character == '}')
                                throw invalidUriTemplate();
                        if (character != '{')
                                continue;

                        int close = uriTemplate.indexOf('}', index + 1);
                        if (close < 0)
                                throw invalidUriTemplate();
                        String variable = uriTemplate.substring(index + 1, close);
                        if (variable.isEmpty() || variable.indexOf('{') >= 0)
                                throw invalidUriTemplate();
                        foundVariable = true;
                        index = close;
                }
                if (!foundVariable)
                        throw new IllegalArgumentException(
                                        "MCP resource URI templates must contain a variable expression.");
                return uriTemplate;
        }

        @NonNull
        private static IllegalArgumentException invalidUriTemplate() {
                return new IllegalArgumentException(
                                "MCP resource URI templates must use balanced {variable} expressions.");
        }

        /**
         * Required-handler stage for an exact resource.
         *
         * @author <a href="https://www.revetkn.com">Mark Allen</a>
         */
        @NotThreadSafe
        public static final class ExactHandlerStage {
                @NonNull
                private final URI uri;
                @NonNull
                private final String name;
                @NonNull
                private final Set<@NonNull McpProtocolVersion> protocolVersions;

                private ExactHandlerStage(@NonNull URI uri, @NonNull String name,
                                @NonNull Set<@NonNull McpProtocolVersion> protocolVersions) {
                        this.uri = requireNonNull(uri);
                        this.name = McpContentValueSupport.requireWellFormedString(name);
                        this.protocolVersions = requireNonNull(protocolVersions);
                }

                /**
                 * Supplies the required resource-read handler.
                 *
                 * @param handler resource-read handler
                 * @return exact-resource optional-metadata builder
                 */
                @NonNull
                public ExactBuilder handler(@NonNull McpResourceReadHandler handler) {
                        return new ExactBuilder(new BuilderState(this.uri, null,
                                        this.name, this.protocolVersions, requireNonNull(handler)));
                }
        }

        /**
         * Required-handler stage for a URI-template resource.
         *
         * @author <a href="https://www.revetkn.com">Mark Allen</a>
         */
        @NotThreadSafe
        public static final class TemplateHandlerStage {
                @NonNull
                private final String uriTemplate;
                @NonNull
                private final String name;
                @NonNull
                private final Set<@NonNull McpProtocolVersion> protocolVersions;

                private TemplateHandlerStage(@NonNull String uriTemplate,
                                @NonNull String name,
                                @NonNull Set<@NonNull McpProtocolVersion> protocolVersions) {
                        this.uriTemplate = McpContentValueSupport.requireWellFormedString(uriTemplate);
                        this.name = McpContentValueSupport.requireWellFormedString(name);
                        this.protocolVersions = requireNonNull(protocolVersions);
                }

                /**
                 * Supplies the required resource-read handler.
                 *
                 * @param handler resource-read handler
                 * @return template-resource optional-metadata builder
                 */
                @NonNull
                public TemplateBuilder handler(@NonNull McpResourceReadHandler handler) {
                        return new TemplateBuilder(new BuilderState(null,
                                        this.uriTemplate, this.name, this.protocolVersions,
                                        requireNonNull(handler)));
                }
        }

        /**
         * Mutable builder for an immutable exact-resource registration.
         *
         * @author <a href="https://www.revetkn.com">Mark Allen</a>
         */
        @NotThreadSafe
        public static final class ExactBuilder {
                @NonNull
                private final BuilderState state;

                private ExactBuilder(@NonNull BuilderState state) {
                        this.state = requireNonNull(state);
                }

                /** @param title human-readable title
                 * @return this builder */
                @NonNull
                public ExactBuilder title(@NonNull String title) {
                        this.state.title = McpContentValueSupport.requireWellFormedString(title);
                        return this;
                }

                /** @param description human-readable description
                 * @return this builder */
                @NonNull
                public ExactBuilder description(@NonNull String description) {
                        this.state.description = McpContentValueSupport.requireWellFormedString(description);
                        return this;
                }

                /** @param mimeType syntactically valid resource MIME type
                 * @return this builder
                 * @throws IllegalArgumentException if {@code mimeType} is malformed */
                @NonNull
                public ExactBuilder mimeType(@NonNull String mimeType) {
                        this.state.mimeType = requireMimeType(mimeType);
                        return this;
                }

                /**
                 * Replaces icon descriptors in supplied order.
                 * Null or empty clears the property. The complete list is validated and
                 * snapshotted before replacing the prior value.
                 *
                 * @param icons icon descriptors, or null to clear
                 * @return this builder
                 * @throws NullPointerException if a list element is null
                 */
                @NonNull
                public ExactBuilder icons(
                                @Nullable List<@NonNull McpIcon> icons) {
                        this.state.icons = icons == null ? List.of()
                                        : List.copyOf(icons);
                        return this;
                }

                /** @param annotations content annotations
                 * @return this builder */
                @NonNull
                public ExactBuilder annotations(
                                @NonNull McpContentAnnotations annotations) {
                        this.state.annotations = requireNonNull(annotations);
                        return this;
                }

                /**
                 * Sets the exact resource's size in bytes.
                 *
                 * @param sizeInBytes nonnegative byte count
                 * @return this builder
                 * @throws NullPointerException if {@code sizeInBytes} is null
                 * @throws IllegalArgumentException if {@code sizeInBytes} is negative
                 */
                @NonNull
                public ExactBuilder sizeInBytes(@NonNull Long sizeInBytes) {
                        requireNonNull(sizeInBytes);
                        if (sizeInBytes < 0)
                                throw new IllegalArgumentException(
                                                "MCP resource sizes must not be negative.");
                        this.state.sizeInBytes = sizeInBytes;
                        return this;
                }

                /** @param cachePolicy fixed scope and default time to live
                 * @return this builder */
                @NonNull
                public ExactBuilder cachePolicy(@NonNull McpCachePolicy cachePolicy) {
                        this.state.cachePolicy = requireNonNull(cachePolicy);
                        return this;
                }

                /**
                 * Replaces input-request declarations in supplied order.
                 * Null or empty clears the property. The complete list is validated and
                 * snapshotted before replacing the prior value.
                 *
                 * @param inputRequestDeclarations input-request declarations, or null to clear
                 * @return this builder
                 * @throws NullPointerException if a list element is null
                 */
                @NonNull
                public ExactBuilder inputRequestDeclarations(
                                @Nullable List<@NonNull McpInputRequestDeclaration> inputRequestDeclarations) {
                        this.state.inputRequestDeclarations = inputRequestDeclarations == null ? List.of()
                                        : List.copyOf(inputRequestDeclarations);
                        return this;
                }

                /**
                 * Sets the request-state contract for this resource operation.
                 *
                 * @param requestStateMode request-state mode
                 * @return this builder
                 */
                @NonNull
                public ExactBuilder requestStateMode(
                                @NonNull McpRequestStateMode requestStateMode) {
                        this.state.requestStateMode = requireNonNull(requestStateMode);
                        return this;
                }

                /** @param metadata protocol extension metadata
                 * @return this builder */
                @NonNull
                public ExactBuilder metadata(@NonNull McpJsonObject metadata) {
                        this.state.metadata = requireNonNull(metadata);
                        return this;
                }

                /** @return immutable exact-resource registration */
                @NonNull
                public McpResourceRegistration build() {
                        return new McpResourceRegistration(this.state);
                }
        }

        /**
         * Mutable builder for an immutable URI-template resource registration.
         *
         * <p>Template registrations do not advertise a size because the value can
         * vary for each concrete expansion.
         *
         * @author <a href="https://www.revetkn.com">Mark Allen</a>
         */
        @NotThreadSafe
        public static final class TemplateBuilder {
                @NonNull
                private final BuilderState state;

                private TemplateBuilder(@NonNull BuilderState state) {
                        this.state = requireNonNull(state);
                }

                /** @param title human-readable title
                 * @return this builder */
                @NonNull
                public TemplateBuilder title(@NonNull String title) {
                        this.state.title = McpContentValueSupport.requireWellFormedString(title);
                        return this;
                }

                /** @param description human-readable description
                 * @return this builder */
                @NonNull
                public TemplateBuilder description(@NonNull String description) {
                        this.state.description = McpContentValueSupport.requireWellFormedString(description);
                        return this;
                }

                /** @param mimeType syntactically valid resource MIME type
                 * @return this builder
                 * @throws IllegalArgumentException if {@code mimeType} is malformed */
                @NonNull
                public TemplateBuilder mimeType(@NonNull String mimeType) {
                        this.state.mimeType = requireMimeType(mimeType);
                        return this;
                }

                /**
                 * Replaces icon descriptors in supplied order.
                 * Null or empty clears the property. The complete list is validated and
                 * snapshotted before replacing the prior value.
                 *
                 * @param icons icon descriptors, or null to clear
                 * @return this builder
                 * @throws NullPointerException if a list element is null
                 */
                @NonNull
                public TemplateBuilder icons(
                                @Nullable List<@NonNull McpIcon> icons) {
                        this.state.icons = icons == null ? List.of()
                                        : List.copyOf(icons);
                        return this;
                }

                /** @param annotations content annotations
                 * @return this builder */
                @NonNull
                public TemplateBuilder annotations(
                                @NonNull McpContentAnnotations annotations) {
                        this.state.annotations = requireNonNull(annotations);
                        return this;
                }

                /** @param cachePolicy fixed scope and default time to live
                 * @return this builder */
                @NonNull
                public TemplateBuilder cachePolicy(
                                @NonNull McpCachePolicy cachePolicy) {
                        this.state.cachePolicy = requireNonNull(cachePolicy);
                        return this;
                }

                /**
                 * Replaces input-request declarations in supplied order.
                 * Null or empty clears the property. The complete list is validated and
                 * snapshotted before replacing the prior value.
                 *
                 * @param inputRequestDeclarations input-request declarations, or null to clear
                 * @return this builder
                 * @throws NullPointerException if a list element is null
                 */
                @NonNull
                public TemplateBuilder inputRequestDeclarations(
                                @Nullable List<@NonNull McpInputRequestDeclaration> inputRequestDeclarations) {
                        this.state.inputRequestDeclarations = inputRequestDeclarations == null ? List.of()
                                        : List.copyOf(inputRequestDeclarations);
                        return this;
                }

                /**
                 * Sets the request-state contract for this resource operation.
                 *
                 * @param requestStateMode request-state mode
                 * @return this builder
                 */
                @NonNull
                public TemplateBuilder requestStateMode(
                                @NonNull McpRequestStateMode requestStateMode) {
                        this.state.requestStateMode = requireNonNull(requestStateMode);
                        return this;
                }

                /** @param metadata protocol extension metadata
                 * @return this builder */
                @NonNull
                public TemplateBuilder metadata(@NonNull McpJsonObject metadata) {
                        this.state.metadata = requireNonNull(metadata);
                        return this;
                }

                /**
                 * Configures the handler for partial URI-template variable suggestions.
                 * Completion is supported for MCP 2025-06-18, 2025-11-25, and
                 * 2026-07-28. Repeated calls replace the previous handler and revision
                 * selection.
                 *
                 * @param completionHandler non-null argument completer
                 * @param protocolVersions nonempty subset of this resource's revisions
                 * @return this builder
                 */
                @NonNull
                public TemplateBuilder completionHandler(
                                @NonNull McpCompletionHandler completionHandler,
                                @NonNull Set<@NonNull McpProtocolVersion> protocolVersions) {
                        requireNonNull(completionHandler);
                        Set<McpProtocolVersion> versions = McpProtocolVersion.requiredSet(protocolVersions);
                        if (!this.state.protocolVersions.containsAll(versions))
                                throw new IllegalArgumentException(
                                                "MCP resource completion revisions must be a subset of resource revisions.");
                        this.state.completionHandler = completionHandler;
                        this.state.completionProtocolVersions = versions;
                        return this;
                }

                /** @return immutable URI-template resource registration */
                @NonNull
                public McpResourceRegistration build() {
                        return new McpResourceRegistration(this.state);
                }
        }

        @NotThreadSafe
        private static final class BuilderState {
                @NonNull
                private final McpResourceAddressType addressType;
                @Nullable
                private final URI uri;
                @Nullable
                private final String uriTemplate;
                @NonNull
                private final String name;
                @NonNull
                private final Set<@NonNull McpProtocolVersion> protocolVersions;
                @Nullable
                private String title;
                @Nullable
                private String description;
                @Nullable
                private String mimeType;
                @NonNull
                private List<@NonNull McpIcon> icons = List.of();
                @Nullable
                private McpContentAnnotations annotations;
                @Nullable
                private Long sizeInBytes;
                @NonNull
                private McpCachePolicy cachePolicy =
                                McpCachePolicy.privateNoCacheInstance();
                @NonNull
                private List<@NonNull McpInputRequestDeclaration>
                                inputRequestDeclarations = List.of();
                @NonNull
                private McpRequestStateMode requestStateMode = McpRequestStateMode.NONE;
                @NonNull
                private McpJsonObject metadata = McpJsonObject.emptyInstance();
                @NonNull
                private final McpResourceReadHandler handler;
                @Nullable
                private McpCompletionHandler completionHandler;
                @NonNull
                private Set<@NonNull McpProtocolVersion> completionProtocolVersions = Set.of();

                private BuilderState(@Nullable URI uri,
                                @Nullable String uriTemplate, @NonNull String name,
                                @NonNull Set<@NonNull McpProtocolVersion> protocolVersions,
                                @NonNull McpResourceReadHandler handler) {
                        if ((uri == null) == (uriTemplate == null))
                                throw new IllegalArgumentException(
                                                "Exactly one MCP resource address must be supplied.");
                        this.addressType = uri == null
                                        ? McpResourceAddressType.URI_TEMPLATE
                                        : McpResourceAddressType.URI;
                        this.uri = uri;
                        this.uriTemplate = uriTemplate;
                        this.name = McpContentValueSupport.requireWellFormedString(name);
                        this.protocolVersions = requireNonNull(protocolVersions);
                        this.handler = requireNonNull(handler);
                }
        }
}