/*
 * 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.time.Duration;

import static java.util.Objects.requireNonNull;

/**
 * Immutable startup and shutdown deadline policy shared by every configured
 * lifecycle component.
 * <p>
 * Every timeout accepts {@link Duration#ZERO} as an immediate deadline, not
 * an unlimited wait or a disabled phase. Zero leaves no waiting allowance for
 * startup, startup cancelation, graceful drain or forced termination proof.
 * Use positive budgets for normal operation; shutdown completion depends on
 * physical termination evidence, not merely requesting interruption.
 * <p>
 * Each timeout and the sum of startup cancelation, graceful shutdown, and
 * forced shutdown timeouts must fit in signed 64-bit nanoseconds. These three
 * phases share one shutdown-intent origin; startup has its own independent
 * budget. The combined bound keeps monotonic deadline comparisons valid even
 * when the clock wraps.
 */
@ThreadSafe
public final class LifecyclePolicy {
        @NonNull
        private static final Duration DEFAULT_STARTUP_TIMEOUT = Duration.ofSeconds(30);
        @NonNull
        private static final Duration DEFAULT_STARTUP_CANCELATION_TIMEOUT =
                        Duration.ofSeconds(2);
        @NonNull
        private static final Duration DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT =
                        Duration.ofSeconds(15);
        @NonNull
        private static final Duration DEFAULT_FORCED_SHUTDOWN_TIMEOUT =
                        Duration.ofSeconds(3);
        @NonNull
        private static final LifecyclePolicy DEFAULT_INSTANCE = builder().build();

        @NonNull
        private final Duration startupTimeout;
        @NonNull
        private final Duration startupCancelationTimeout;
        @NonNull
        private final Duration gracefulShutdownTimeout;
        @NonNull
        private final Duration forcedShutdownTimeout;

        private LifecyclePolicy(@NonNull Builder builder) {
                Builder exactBuilder = requireNonNull(builder);
                this.startupTimeout = validate(exactBuilder.startupTimeout,
                                "startupTimeout");
                this.startupCancelationTimeout = validate(
                                exactBuilder.startupCancelationTimeout,
                                "startupCancelationTimeout");
                this.gracefulShutdownTimeout = validate(
                                exactBuilder.gracefulShutdownTimeout,
                                "gracefulShutdownTimeout");
                this.forcedShutdownTimeout = validate(
                                exactBuilder.forcedShutdownTimeout,
                                "forcedShutdownTimeout");
                LifecycleDeadlines.validateShutdownHorizon(this.startupCancelationTimeout,
                                this.gracefulShutdownTimeout, this.forcedShutdownTimeout);
        }

        /** @return the shared default lifecycle policy */
        @NonNull
        public static LifecyclePolicy defaultInstance() {
                return DEFAULT_INSTANCE;
        }

        /** @return a mutable builder initialized with the default policy */
        @NonNull
        public static Builder builder() {
                return new Builder();
        }

        /** @return startup timeout */
        @NonNull
        public Duration getStartupTimeout() {
                return this.startupTimeout;
        }

        /** @return budget for canceling an in-flight startup call */
        @NonNull
        public Duration getStartupCancelationTimeout() {
                return this.startupCancelationTimeout;
        }

        /** @return graceful shutdown timeout */
        @NonNull
        public Duration getGracefulShutdownTimeout() {
                return this.gracefulShutdownTimeout;
        }

        /** @return forced shutdown timeout */
        @NonNull
        public Duration getForcedShutdownTimeout() {
                return this.forcedShutdownTimeout;
        }

        /** @return whether this policy is structurally equal to the other policy */
        @Override
        public boolean equals(@Nullable Object other) {
                return this == other
                                || other instanceof LifecyclePolicy policy
                                && this.startupTimeout.equals(policy.startupTimeout)
                                && this.startupCancelationTimeout.equals(
                                                policy.startupCancelationTimeout)
                                && this.gracefulShutdownTimeout.equals(
                                                policy.gracefulShutdownTimeout)
                                && this.forcedShutdownTimeout.equals(
                                                policy.forcedShutdownTimeout);
        }

        /** @return structural lifecycle-policy hash code */
        @Override
        public int hashCode() {
                int result = this.startupTimeout.hashCode();
                result = 31 * result + this.startupCancelationTimeout.hashCode();
                result = 31 * result + this.gracefulShutdownTimeout.hashCode();
                result = 31 * result + this.forcedShutdownTimeout.hashCode();
                return result;
        }

        @NonNull
        InternalLifecyclePolicy toInternal() {
                return new InternalLifecyclePolicy(getStartupTimeout(),
                                getStartupCancelationTimeout(), getGracefulShutdownTimeout(),
                                getForcedShutdownTimeout());
        }

        @NonNull
        static LifecyclePolicy fromInternal(
                        @NonNull InternalLifecyclePolicy lifecyclePolicy) {
                requireNonNull(lifecyclePolicy);
                return builder()
                                .startupTimeout(lifecyclePolicy.startupTimeout())
                                .startupCancelationTimeout(
                                                lifecyclePolicy.startupCancelationTimeout())
                                .gracefulShutdownTimeout(
                                                lifecyclePolicy.gracefulShutdownTimeout())
                                .forcedShutdownTimeout(
                                                lifecyclePolicy.forcedShutdownTimeout())
                                .build();
        }

        @NonNull
        private static Duration validate(@NonNull Duration duration,
                        @NonNull String name) {
                requireNonNull(duration, requireNonNull(name));
                if (duration.isNegative())
                        throw new IllegalArgumentException(name + " must be >= 0");
                try {
                        long validatedNanoseconds = duration.toNanos();
                        if (validatedNanoseconds < 0L)
                                throw new IllegalArgumentException(name + " must be >= 0");
                } catch (ArithmeticException exception) {
                        throw new IllegalArgumentException(
                                        name + " exceeds signed nanoseconds", exception);
                }
                return duration;
        }

        /** Mutable builder for an immutable {@link LifecyclePolicy}. */
        @NotThreadSafe
        public static final class Builder {
                @NonNull
                private Duration startupTimeout;
                @NonNull
                private Duration startupCancelationTimeout;
                @NonNull
                private Duration gracefulShutdownTimeout;
                @NonNull
                private Duration forcedShutdownTimeout;

                private Builder() {
                        this.startupTimeout = DEFAULT_STARTUP_TIMEOUT;
                        this.startupCancelationTimeout =
                                        DEFAULT_STARTUP_CANCELATION_TIMEOUT;
                        this.gracefulShutdownTimeout = DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT;
                        this.forcedShutdownTimeout = DEFAULT_FORCED_SHUTDOWN_TIMEOUT;
                }

                /**
                 * Sets the startup timeout. Zero means an immediate boundary.
                 * A zero budget leaves no waiting allowance for framework setup or
                 * transport startup and can immediately produce
                 * {@link StartupDisposition#TIMED_OUT}; it does not disable the timeout.
                 *
                 * Passing {@code null} restores the built-in default of 30 seconds.
                 *
                 * @param startupTimeout startup timeout, or {@code null} to use the default
                 * @return this builder
                 * @throws IllegalArgumentException if negative or not representable as
                 * signed nanoseconds
                 */
                @NonNull
                public Builder startupTimeout(@Nullable Duration startupTimeout) {
                        this.startupTimeout = startupTimeout == null
                                        ? DEFAULT_STARTUP_TIMEOUT
                                        : validate(startupTimeout, "startupTimeout");
                        return this;
                }

                /**
                 * Sets the startup-cancelation budget. Zero means an immediate boundary.
                 * A zero budget leaves no waiting allowance for an active startup call
                 * to return after shutdown intent. Remaining startup work stays tracked
                 * through the graceful and forced shutdown phases.
                 *
                 * Passing {@code null} restores the built-in default of 2 seconds.
                 *
                 * @param startupCancelationTimeout cancelation budget, or {@code null}
                 * to use the default
                 * @return this builder
                 * @throws IllegalArgumentException if negative or not representable as
                 * signed nanoseconds
                 */
                @NonNull
                public Builder startupCancelationTimeout(
                                @Nullable Duration startupCancelationTimeout) {
                        this.startupCancelationTimeout = startupCancelationTimeout == null
                                        ? DEFAULT_STARTUP_CANCELATION_TIMEOUT
                                        : validate(startupCancelationTimeout,
                                                        "startupCancelationTimeout");
                        return this;
                }

                /**
                 * Sets the graceful shutdown timeout. Zero means an immediate boundary.
                 * Passing {@code null} restores the built-in default of 15 seconds.
                 * A zero budget leaves no waiting allowance for graceful drain;
                 * participants without termination proof proceed to forced shutdown.
                 * <p>
                 * This budget is independent of the server request-handler timeout (60 seconds by default).
                 * To let all permitted in-flight requests finish, allow their maximum remaining work and
                 * response transmission time. A shorter drain intentionally permits interruption and
                 * connection closure at the forced boundary. Interruption cannot guarantee that
                 * noncooperative application code stops. Long-lived streams need an explicit termination
                 * policy; the surrounding process/container budget must also include forced shutdown
                 * and operational margin.
                 * <p>
                 * After a closing response, the standard HTTP server closes promptly when the
                 * request was fully consumed and no surplus input was observed, including one
                 * nonblocking check for input already queued on the socket. If unread input
                 * may remain, its one-second lingering-input window consumes this budget even
                 * after the response has been written. Short graceful budgets can therefore
                 * proceed to forced shutdown while such a client connection still lingers.
                 *
                 * @param gracefulShutdownTimeout graceful shutdown timeout, or
                 * {@code null} to use the default
                 * @return this builder
                 * @throws IllegalArgumentException if negative or not representable as
                 * signed nanoseconds
                 */
                @NonNull
                public Builder gracefulShutdownTimeout(
                                @Nullable Duration gracefulShutdownTimeout) {
                        this.gracefulShutdownTimeout = gracefulShutdownTimeout == null
                                        ? DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT
                                        : validate(gracefulShutdownTimeout,
                                                        "gracefulShutdownTimeout");
                        return this;
                }

                /**
                 * Sets the forced shutdown timeout. Zero means an immediate boundary.
                 * Passing {@code null} restores the built-in default of 3 seconds.
                 * A zero budget leaves no waiting allowance for forced termination
                 * proof. Any still-unproven or residual work produces an incomplete
                 * result. In particular, zero graceful and forced budgets can make
                 * even an idle running listener's shutdown incomplete because its stop
                 * calls and termination proof are asynchronous.
                 *
                 * @param forcedShutdownTimeout forced shutdown timeout, or {@code null}
                 * to use the default
                 * @return this builder
                 * @throws IllegalArgumentException if negative or not representable as
                 * signed nanoseconds
                 */
                @NonNull
                public Builder forcedShutdownTimeout(
                                @Nullable Duration forcedShutdownTimeout) {
                        this.forcedShutdownTimeout = forcedShutdownTimeout == null
                                        ? DEFAULT_FORCED_SHUTDOWN_TIMEOUT
                                        : validate(forcedShutdownTimeout, "forcedShutdownTimeout");
                        return this;
                }

                /**
                 * @return immutable lifecycle policy
                 * @throws IllegalArgumentException if the combined startup-cancelation,
                 * graceful-shutdown, and forced-shutdown budget exceeds signed nanoseconds
                 */
                @NonNull
                public LifecyclePolicy build() {
                        return new LifecyclePolicy(this);
                }
        }
}