/* ========================================================================
 * Copyright (c) 2005-2025 The OPC Foundation, Inc. All rights reserved.
 *
 * OPC Foundation MIT License 1.00
 *
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use,
 * copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following
 * conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
 *
 * The complete license agreement can be found here:
 * http://opcfoundation.org/License/MIT/1.00/
 * ======================================================================*/

using System;

namespace Opc.Ua.Server.Fluent
{
    /// <summary>
    /// Strongly-typed fluent builder for a
    /// <see cref="FiniteStateMachineState"/> instance. Returned by
    /// <see cref="StateMachineBuilderExtensions.AsStateMachine{TState}(INodeBuilder{TState})"/>.
    /// </summary>
    /// <remarks>
    /// <para>
    /// The builder is a <b>configurator</b> over an existing
    /// <see cref="FiniteStateMachineState"/> subclass — typically one
    /// emitted by the source generator (e.g.
    /// <c>InstallationStateMachineState</c>) or a stack-shipped
    /// subclass (<see cref="ProgramStateMachineState"/>,
    /// <see cref="ShelvedStateMachineState"/>,
    /// <see cref="ExclusiveLimitStateMachineState"/>). It does NOT
    /// attempt to build the state/transition/cause tables at runtime;
    /// those remain compiled into the subclass.
    /// </para>
    /// <para>
    /// Identifiers exchanged with the builder are <b>internal numeric
    /// state IDs / transition IDs / cause IDs</b> (e.g.
    /// <c>Objects.ProgramStateMachineType_Ready</c>), NOT the OPC UA
    /// <c>Number</c> field on the state variable. Use the
    /// <c>StateIds</c> / <c>TransitionIds</c> / <c>MethodIds</c>
    /// generated by the source generator wherever possible.
    /// </para>
    /// <para>
    /// All callbacks are <i>composed</i> with any pre-existing handler
    /// on the underlying state machine: pre-wired
    /// <see cref="FiniteStateMachineState.OnBeforeTransition"/> /
    /// <see cref="FiniteStateMachineState.OnAfterTransition"/> handlers
    /// run alongside the builder's coordinator, so stack default
    /// behaviour is preserved.
    /// </para>
    /// </remarks>
    /// <typeparam name="TState">
    /// Concrete state-machine type. Must derive from
    /// <see cref="FiniteStateMachineState"/>.
    /// </typeparam>
    public interface IStateMachineBuilder<TState>
        where TState : FiniteStateMachineState
    {
        /// <summary>
        /// The configured state machine.
        /// </summary>
        TState StateMachine { get; }

        /// <summary>
        /// The owning node builder, for chain termination via
        /// <see cref="StateMachineBuilderExtensions.Done{TState}(IStateMachineBuilder{TState})"/>.
        /// </summary>
        INodeBuilder Builder { get; }

        /// <summary>
        /// Forces the machine into the specified state via
        /// <see cref="FiniteStateMachineState.SetState"/>. Intended
        /// for setting the initial state during configuration; does
        /// NOT fire transition callbacks (matches stack semantics for
        /// <c>SetState</c>).
        /// </summary>
        /// <param name="stateId">
        /// The internal state ID (e.g.
        /// <c>Objects.ProgramStateMachineType_Ready</c>).
        /// </param>
        IStateMachineBuilder<TState> WithInitialState(uint stateId);

        /// <summary>
        /// Runs after the machine transitions <i>into</i> the specified
        /// state. Fired by the composed
        /// <see cref="FiniteStateMachineState.OnAfterTransition"/>
        /// coordinator after the stack has updated
        /// <see cref="FiniteStateMachineState.CurrentState"/>.
        /// </summary>
        /// <param name="stateId">The destination state ID.</param>
        /// <param name="handler">Callback invoked once per matching
        /// transition.</param>
        IStateMachineBuilder<TState> OnEnterState(
            uint stateId,
            Action<ISystemContext, TState> handler);

        /// <summary>
        /// Runs when the machine transitions <i>out of</i> the specified
        /// state. Fired by the composed coordinator using the
        /// <c>from</c> state captured in
        /// <see cref="FiniteStateMachineState.OnBeforeTransition"/>.
        /// </summary>
        IStateMachineBuilder<TState> OnExitState(
            uint stateId,
            Action<ISystemContext, TState> handler);

        /// <summary>
        /// Runs for every successful transition. Receives the
        /// <c>fromStateId</c> (captured pre-transition) and
        /// <c>toStateId</c> (the new <see cref="FiniteStateMachineState.CurrentState"/>).
        /// </summary>
        IStateMachineBuilder<TState> OnTransition(
            Action<ISystemContext, TState, uint /*fromStateId*/, uint /*toStateId*/> handler);

        /// <summary>
        /// Installs a pre-transition guard. Return a non-<c>Good</c>
        /// <see cref="ServiceResult"/> to cancel the transition. The
        /// guard is composed with any existing
        /// <see cref="FiniteStateMachineState.OnBeforeTransition"/>
        /// handler (existing first, then fluent guards in registration
        /// order; first bad result wins).
        /// </summary>
        /// <remarks>
        /// Guards receive the <c>fromStateId</c> (the machine's
        /// current state before the transition); the destination state
        /// is computed by the stack from internal
        /// <c>TransitionMappings</c> and is not exposed to guards in
        /// this MVP. Read <c>StateMachine.CurrentState.Id.Value</c> for
        /// the same information from inside the guard if needed.
        /// </remarks>
        IStateMachineBuilder<TState> OnBeforeTransition(
            Func<ISystemContext, TState, uint /*fromStateId*/, ServiceResult> guard);

        /// <summary>
        /// Wires the supplied method node so calling it invokes
        /// <see cref="FiniteStateMachineState.DoCause"/> with the
        /// supplied cause ID. The cause-to-transition lookup happens
        /// inside the stack via the subclass's
        /// <c>CauseMappings</c>.
        /// </summary>
        /// <param name="methodNodeId">
        /// NodeId of the method that triggers the cause.
        /// </param>
        /// <param name="causeId">
        /// The internal cause ID (e.g.
        /// <c>Methods.ProgramStateMachineType_Start</c>).
        /// </param>
        IStateMachineBuilder<TState> WithCause(NodeId methodNodeId, uint causeId);

        /// <summary>
        /// Auto-fires <see cref="FiniteStateMachineState.DoCause"/> for
        /// <paramref name="causeId"/> when the machine has been in
        /// <paramref name="fromStateId"/> for at least
        /// <paramref name="timeout"/>. Uses the owning manager's
        /// simulation registry — the manager must derive from
        /// <see cref="FluentNodeManagerBase"/>.
        /// </summary>
        /// <param name="fromStateId">
        /// State the machine must be in for the timer to be armed.
        /// </param>
        /// <param name="timeout">
        /// Duration the machine must remain in
        /// <paramref name="fromStateId"/> before the cause fires. Must
        /// be positive.
        /// </param>
        /// <param name="causeId">
        /// Cause ID passed to <see cref="FiniteStateMachineState.DoCause"/>
        /// when the timeout elapses.
        /// </param>
        /// <exception cref="InvalidOperationException">
        /// Thrown when the owning manager does not derive from
        /// <see cref="FluentNodeManagerBase"/>.
        /// </exception>
        IStateMachineBuilder<TState> WithTimedTransition(
            uint fromStateId,
            TimeSpan timeout,
            uint causeId);

        /// <summary>
        /// Escape hatch: directly mutate the underlying state machine
        /// for properties not covered by the narrow MVP surface (e.g.
        /// <see cref="FiniteStateMachineState.SuppressTransitionEvents"/>,
        /// <see cref="FiniteStateMachineState.OnCheckUserPermission"/>).
        /// </summary>
        IStateMachineBuilder<TState> ConfigureStateMachine(Action<TState> configure);
    }
}