scadalink-design/src/ScadaLink.InboundAPI/RouteHelper.cs

using ScadaLink.Commons.Interfaces.Services;
using ScadaLink.Commons.Messages.InboundApi;
using ScadaLink.Commons.Types;

namespace ScadaLink.InboundAPI;

/// <summary>
/// WP-4: Route.To() helper for cross-site calls from inbound API scripts.
/// Resolves instance to site, routes via <see cref="IInstanceRouter"/>, blocks until
/// response or timeout. Site unreachable returns error (no store-and-forward).
///
/// InboundAPI-016: the helper carries the executing method's <see cref="CancellationToken"/>
/// (the method-level timeout). Routed calls inherit that deadline by default, so a
/// natural script — <c>Route.To("inst").Call("doWork", p)</c> — is timeout-bounded
/// without the script having to thread a token explicitly.
/// </summary>
public class RouteHelper
{
    private readonly IInstanceLocator _instanceLocator;
    private readonly IInstanceRouter _instanceRouter;
    private readonly CancellationToken _deadlineToken;
    private readonly Guid? _parentExecutionId;

    public RouteHelper(
        IInstanceLocator instanceLocator,
        IInstanceRouter instanceRouter)
        : this(instanceLocator, instanceRouter, CancellationToken.None, parentExecutionId: null)
    {
    }

    private RouteHelper(
        IInstanceLocator instanceLocator,
        IInstanceRouter instanceRouter,
        CancellationToken deadlineToken,
        Guid? parentExecutionId)
    {
        _instanceLocator = instanceLocator;
        _instanceRouter = instanceRouter;
        _deadlineToken = deadlineToken;
        _parentExecutionId = parentExecutionId;
    }

    /// <summary>
    /// InboundAPI-016: returns a <see cref="RouteHelper"/> whose routed calls inherit
    /// <paramref name="deadlineToken"/> (the executing method's timeout) by default.
    /// <see cref="InboundScriptExecutor"/> calls this when it builds the script
    /// context so the method timeout actually covers routed calls, as the design doc
    /// requires.
    /// </summary>
    public RouteHelper WithDeadline(CancellationToken deadlineToken) =>
        new(_instanceLocator, _instanceRouter, deadlineToken, _parentExecutionId);

    /// <summary>
    /// Audit Log #23 (ParentExecutionId): returns a <see cref="RouteHelper"/> whose
    /// routed <see cref="RouteTarget.Call"/> requests carry
    /// <paramref name="parentExecutionId"/> as <see cref="RouteToCallRequest.ParentExecutionId"/>.
    /// For an inbound API request this is the inbound request's own per-request
    /// execution id, so the routed site script records the inbound request as its
    /// parent. <see cref="InboundScriptExecutor"/> calls this when it builds the
    /// script context.
    /// </summary>
    public RouteHelper WithParentExecutionId(Guid? parentExecutionId) =>
        new(_instanceLocator, _instanceRouter, _deadlineToken, parentExecutionId);

    /// <summary>
    /// Creates a route target for the specified instance.
    /// </summary>
    public RouteTarget To(string instanceCode)
    {
        return new RouteTarget(
            instanceCode, _instanceLocator, _instanceRouter, _deadlineToken, _parentExecutionId);
    }
}

/// <summary>
/// WP-4: Represents a route target (an instance) for cross-site calls.
/// </summary>
public class RouteTarget
{
    private readonly string _instanceCode;
    private readonly IInstanceLocator _instanceLocator;
    private readonly IInstanceRouter _instanceRouter;
    private readonly CancellationToken _deadlineToken;
    private readonly Guid? _parentExecutionId;

    internal RouteTarget(
        string instanceCode,
        IInstanceLocator instanceLocator,
        IInstanceRouter instanceRouter,
        CancellationToken deadlineToken,
        Guid? parentExecutionId)
    {
        _instanceCode = instanceCode;
        _instanceLocator = instanceLocator;
        _instanceRouter = instanceRouter;
        _deadlineToken = deadlineToken;
        _parentExecutionId = parentExecutionId;
    }

    /// <summary>
    /// Calls a script on the remote instance. Synchronous from API caller's
    /// perspective. <paramref name="parameters"/> may be a dictionary or an
    /// anonymous object (<c>new { name = "Bob" }</c>) — see <see cref="ScriptArgs"/>.
    ///
    /// InboundAPI-016: when <paramref name="cancellationToken"/> is not supplied the
    /// routed call inherits the executing method's timeout, so the call is bounded by
    /// the method-level deadline with no token argument.
    /// </summary>
    public async Task<object?> Call(
        string scriptName,
        object? parameters = null,
        CancellationToken cancellationToken = default)
    {
        var token = Effective(cancellationToken);
        var siteId = await ResolveSiteAsync(token);
        var correlationId = Guid.NewGuid().ToString();

        // Audit Log #23 (ParentExecutionId): stamp the spawning execution's id
        // (the inbound API request's ExecutionId) so the routed site script
        // records this call's parent. CorrelationId above is a separate concern
        // — the per-operation lifecycle id, freshly minted per routed call.
        var request = new RouteToCallRequest(
            correlationId, _instanceCode, scriptName, ScriptArgs.Normalize(parameters),
            DateTimeOffset.UtcNow, _parentExecutionId);

        var response = await _instanceRouter.RouteToCallAsync(siteId, request, token);

        if (!response.Success)
        {
            throw new InvalidOperationException(
                response.ErrorMessage ?? "Remote script call failed");
        }

        return response.ReturnValue;
    }

    /// <summary>
    /// Gets a single attribute value from the remote instance.
    /// </summary>
    public async Task<object?> GetAttribute(
        string attributeName,
        CancellationToken cancellationToken = default)
    {
        var result = await GetAttributes(new[] { attributeName }, cancellationToken);
        return result.TryGetValue(attributeName, out var value) ? value : null;
    }

    /// <summary>
    /// Gets multiple attribute values from the remote instance (batch read).
    /// </summary>
    public async Task<IReadOnlyDictionary<string, object?>> GetAttributes(
        IEnumerable<string> attributeNames,
        CancellationToken cancellationToken = default)
    {
        var token = Effective(cancellationToken);
        var siteId = await ResolveSiteAsync(token);
        var correlationId = Guid.NewGuid().ToString();

        var request = new RouteToGetAttributesRequest(
            correlationId, _instanceCode, attributeNames.ToList(), DateTimeOffset.UtcNow);

        var response = await _instanceRouter.RouteToGetAttributesAsync(siteId, request, token);

        if (!response.Success)
        {
            throw new InvalidOperationException(
                response.ErrorMessage ?? "Remote attribute read failed");
        }

        return response.Values;
    }

    /// <summary>
    /// Sets a single attribute value on the remote instance.
    /// </summary>
    public async Task SetAttribute(
        string attributeName,
        string value,
        CancellationToken cancellationToken = default)
    {
        await SetAttributes(
            new Dictionary<string, string> { { attributeName, value } },
            cancellationToken);
    }

    /// <summary>
    /// Sets multiple attribute values on the remote instance (batch write).
    /// </summary>
    public async Task SetAttributes(
        IReadOnlyDictionary<string, string> attributeValues,
        CancellationToken cancellationToken = default)
    {
        var token = Effective(cancellationToken);
        var siteId = await ResolveSiteAsync(token);
        var correlationId = Guid.NewGuid().ToString();

        var request = new RouteToSetAttributesRequest(
            correlationId, _instanceCode, attributeValues, DateTimeOffset.UtcNow);

        var response = await _instanceRouter.RouteToSetAttributesAsync(siteId, request, token);

        if (!response.Success)
        {
            throw new InvalidOperationException(
                response.ErrorMessage ?? "Remote attribute write failed");
        }
    }

    /// <summary>
    /// InboundAPI-016: a routed call with no explicit token inherits the executing
    /// method's deadline. An explicitly supplied token (for a tighter bound) wins.
    /// </summary>
    private CancellationToken Effective(CancellationToken explicitToken) =>
        explicitToken.CanBeCanceled ? explicitToken : _deadlineToken;

    private async Task<string> ResolveSiteAsync(CancellationToken cancellationToken)
    {
        var siteId = await _instanceLocator.GetSiteIdForInstanceAsync(_instanceCode, cancellationToken);
        if (siteId == null)
        {
            throw new InvalidOperationException(
                $"Instance '{_instanceCode}' not found or has no assigned site");
        }

        return siteId;
    }
}