RESTHelper.cs

// =============================================================================
// GPAL - Generally Positive Automation Library
// Copyright © 2026 Software Decisions, Inc. All rights reserved.
//
// This file is part of GPAL.
// Licensed under the Business Source License 1.1
//
// Primary development, architecture, and vision by Michael B. Vederman,
// CEO of Software Decisions, Inc., Texas.
//
// Internal development maintained privately.
// Public releases appear on GitHub: https://github.com/SoftwareDecisionsInc/GPAL.
//
// See LICENSE for full terms, including Additional Use Grant.
// =============================================================================
 
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
using System.Web;
using System.Windows.Forms;
using System.Xml.Serialization;
using GenerallyPositive;
using Newtonsoft.Json;
using YamlDotNet.Serialization;
using static GenerallyPositive.Enums;
 
namespace GenerallyPositive
{
    internal class RESTHelper
    {
        internal int StatusCode { get; set; }
 
        // how long the server asked us to wait before asking again, in seconds. Zero when the response carried
        // no Retry-After, which is every response that is not a 429 or a 503
        internal int RetryAfterSeconds { get; set; }
 
        private RESTClient _restClient;
 
        // UseCookies left on hands the Cookie header to the handler, which then writes it from its own jar. the
        // jar is new and empty on every call, so a Cookie the caller set is replaced by nothing and the request
        // goes out without it. off, the header the caller set is the header that is sent
        private HttpClient _httpClient { get; set; } = new HttpClient(new HttpClientHandler { UseCookies = false })
        {
            // HttpClient's own 100 second default outranks the token, so a caller asking for five minutes, or for
            // no limit at all, was still cut off at 100 and told it was cancelled. Every send below is bounded by
            // a CancellationTokenSource built from HttpTimeout, which this leaves as the only clock
            Timeout = System.Threading.Timeout.InfiniteTimeSpan
        };
 
        private readonly string _browserExtensionApiBase;
 
        // what one attempt is given when the caller did not say. long enough for a slow API to answer, short
        // enough that a host which accepts the connection and never replies is not a two minute wait
        internal static readonly TimeSpan DefaultTimeout = TimeSpan.FromSeconds(60);
 
        // settable after the base url, so a client handed a session by ContinueAsRESTClient can still be told how
        // long to wait. See RESTClient.WithTimeout
        internal TimeSpan HttpTimeout { get; set; } = DefaultTimeout;
        internal static Dictionary<ApiEndpoint, string> Endpoints { get; set; } = new Dictionary<ApiEndpoint, string>
        {
            [ApiEndpoint.Back] = "back",                       // history.back()
            [ApiEndpoint.CaptureVisibleTab] = "capture-visible-tab",    // for headles image matching
            [ApiEndpoint.CastDesktop] = "cast-desktop",
            [ApiEndpoint.CastTab] = "cast-tab",
            [ApiEndpoint.CheckNetworkIdle] = "check-network-idle", // ensure no more than 'maxConnections' are active - better than document.readyState in some scenarios
            [ApiEndpoint.CheckStatus] = "status",              // to test if the api is up
            [ApiEndpoint.ClearReferrer] = "clear-referrer",
            [ApiEndpoint.CloseBrowser] = "close-browser",
            [ApiEndpoint.CloseTab] = "close-tab",
            [ApiEndpoint.DeleteStorage] = "delete-storage",
            [ApiEndpoint.DragAndDrop] = "drag-and-drop",
            [ApiEndpoint.Evaluate] = "evaluate",               // xpath
            [ApiEndpoint.EvaluateAll] = "evaluate-all",        // xpath multiple elements
            [ApiEndpoint.EvaluatePersistent] = "evaluate-persistent",               // xpath
            [ApiEndpoint.EvaluateAllPersistent] = "evaluate-all-persistent",        // xpath multiple elements
            [ApiEndpoint.ExecuteJavaScript] = "execute-javascript",
            [ApiEndpoint.Fetch] = "fetch",
            [ApiEndpoint.FillInAppend] = "fill-in-append",
            [ApiEndpoint.FillInInsert] = "fill-in-insert",
            [ApiEndpoint.FillInOverwrite] = "fill-in-overwrite",
            [ApiEndpoint.FireChangeEvent] = "fire-change-event",
            [ApiEndpoint.Focus] = "focus",
            [ApiEndpoint.Forward] = "forward",                 // history.forward()
            [ApiEndpoint.FullScreen] = "fullscreen",
            [ApiEndpoint.GetAttribute] = "get-attribute",
            [ApiEndpoint.GetBoundingClientRect] = "get-bounding-client-rect",
            [ApiEndpoint.ElementFromPoint] = "element-from-point",
            [ApiEndpoint.GetContentAndCss] = "get-content-and-css",
            [ApiEndpoint.GetCssAttributes] = "get-css-attributes",
            [ApiEndpoint.GetCurrentUrl] = "get-current-url",
            [ApiEndpoint.GetDocumentStamp] = "get-document-stamp",
            [ApiEndpoint.GetHydrationScripts] = "get-hydration-scripts",
            [ApiEndpoint.GetDomAttributes] = "get-dom-attributes",
            [ApiEndpoint.GetDomProperties] = "get-dom-properties",
            [ApiEndpoint.GetElementAttributeHash] = "get-element-attribute-hash",
            [ApiEndpoint.GetPageSource] = "get-page-source",
            [ApiEndpoint.GetParentNode] = "get-parent-node",
            [ApiEndpoint.GetReadyStatus] = "get-ready-status",
            [ApiEndpoint.GetShadowRoot] = "get-shadow-root",
            [ApiEndpoint.GetStorage] = "get-storage",
            [ApiEndpoint.GetLanguages] = "get-languages",
            [ApiEndpoint.CaptureCalls] = "capture-calls",
            [ApiEndpoint.GetCapturedCalls] = "get-captured-calls",
            [ApiEndpoint.GetUserAgent] = "get-useragent",
            [ApiEndpoint.GoTo] = "goto",
            [ApiEndpoint.GoToTab] = "goto-tab",
            [ApiEndpoint.GetWindowRectangle] = "get-window-rectangle",
            [ApiEndpoint.HideElement] = "hide-element",
            [ApiEndpoint.Hover] = "hover",
            [ApiEndpoint.InjectScript] = "inject-script",
            [ApiEndpoint.ClearInjectedScripts] = "clear-injected-scripts",
            [ApiEndpoint.IsClickable] = "is-clickable",
            [ApiEndpoint.IsDisplayed] = "is-displayed",
            [ApiEndpoint.IsEnabled] = "is-enabled",
            [ApiEndpoint.IsEndOfPage] = "is-end-of-page",
            [ApiEndpoint.IsVisibleInViewport] = "is-visible-in-viewport",
            [ApiEndpoint.LeftClick] = "left-click",
            [ApiEndpoint.LeftClickAndDownload] = "left-click-download",
            [ApiEndpoint.LeftDoubleClick] = "left-double-click",
            [ApiEndpoint.Maximize] = "maximize",
            [ApiEndpoint.MiddleClick] = "middle-click",
            [ApiEndpoint.Minimize] = "minimize",
            [ApiEndpoint.MoveTo] = "move-to",
            [ApiEndpoint.NewTab] = "new-tab",
            [ApiEndpoint.NextTab] = "next-tab",
            [ApiEndpoint.NextWindow] = "next-window",
            [ApiEndpoint.Normal] = "normal",                   // restore window after fullscreen
            [ApiEndpoint.OverrideReferrer] = "override-referrer",
            [ApiEndpoint.PageDown] = "page-down",
            [ApiEndpoint.PageEnd] = "page-end",
            [ApiEndpoint.PageTop] = "page-top",
            [ApiEndpoint.PageUp] = "page-up",
            [ApiEndpoint.PressModifierKey] = "press-modifier-key",
            [ApiEndpoint.PreviousTab] = "previous-tab",
            [ApiEndpoint.PreviousWindow] = "previous-window",
            [ApiEndpoint.QuerySelector] = "query-selector",    // css
            [ApiEndpoint.QuerySelectors] = "query-selectors",  // css multiple elements
            [ApiEndpoint.QueryPersistentSelector] = "query-persistent-selector",    // css
            [ApiEndpoint.QueryPersistentSelectors] = "query-persistent-selectors",  // css multiple elements
            [ApiEndpoint.Refresh] = "refresh",
            [ApiEndpoint.ReleaseModifierKey] = "release-modifier-key",
            [ApiEndpoint.Restore] = "restore",
            [ApiEndpoint.RightClick] = "right-click",
            [ApiEndpoint.ScrollElement] = "scroll-element",
            [ApiEndpoint.ScrollIntoView] = "scroll-into-view",
            [ApiEndpoint.ScrollWindowByHorizontal] = "scroll-window",
            [ApiEndpoint.ScrollWindowByVertical] = "scroll-window",
            [ApiEndpoint.ScrollWindow] = "scroll-window",
            [ApiEndpoint.SelectClick] = "select-click",
            [ApiEndpoint.SendKey] = "send-key",
            [ApiEndpoint.SendString] = "send-string",
            [ApiEndpoint.SetAttribute] = "set-attribute",
            [ApiEndpoint.SetDownloadFilename] = "set-download-filename",
            [ApiEndpoint.SetGoogleReferrer] = "google-referrer",
            [ApiEndpoint.SetRange] = "set-range",
            [ApiEndpoint.SetStorage] = "set-storage",
            [ApiEndpoint.SetUserAgent] = "set-useragent",
            [ApiEndpoint.SetValueFromElement] = "set-value-from-element",
            [ApiEndpoint.StopCasting] = "stop-casting",
            [ApiEndpoint.SwitchToDefaultContent] = "switch-to-default-content",
            [ApiEndpoint.SwitchToElement] = "switch-to-element",
            [ApiEndpoint.SwitchToFrame] = "switch-to-frame",    // NOTE: puppeteer only, not used by rest, ottomagic runs in every frame
            [ApiEndpoint.SwitchToShadowRoot] = "switch-to-shadow-root",
            [ApiEndpoint.TabCount] = "tab-count",
            [ApiEndpoint.TopBrowser] = "top-browser",
            [ApiEndpoint.MoveToPoint] = "move-to-point",
            [ApiEndpoint.ClickPoint] = "click-point",
            [ApiEndpoint.TrustedLeftClick] = "trusted-left-click",
            [ApiEndpoint.TrustedMiddleClick] = "trusted-middle-click",
            [ApiEndpoint.Upload] = "upload",
            [ApiEndpoint.WindowInnerHeight] = "window-inner-height",
            [ApiEndpoint.WindowInnerWidth] = "window-inner-width",
            [ApiEndpoint.WindowOuterHeight] = "window-outer-height",
            [ApiEndpoint.WindowOuterWidth] = "window-outer-width",
            [ApiEndpoint.WindowPageOffsetX] = "window-page-xoffset",
            [ApiEndpoint.WindowPageOffsetY] = "window-page-yoffset",
            [ApiEndpoint.WindowScreenLeft] = "window-screen-left",
            [ApiEndpoint.WindowScreenTop] = "window-screen-top",
            [ApiEndpoint.OpenWindow] = "open-window",
            [ApiEndpoint.GoToWindow] = "goto-window",
            [ApiEndpoint.CloseWindow] = "close-window",
            [ApiEndpoint.GetCurrentWindow] = "get-current-window",
            #region GPAL STUDIO
            [ApiEndpoint.GetWorkflow] = "get-workflow",
            [ApiEndpoint.GetSettings] = "get-settings",
            [ApiEndpoint.GetGpalSettings] = "get-gpal-settings",
            [ApiEndpoint.GetBrowserSettings] = "get-browser-settings",
            #endregion GPAL STUDIO
        };
 
        public RESTHelper(string browserExtensionApiBase, RESTClient client, TimeSpan? httpTimeout = null)
        {
            if (browserExtensionApiBase == null)
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR,
                    "Browser extension API base cannot be null.",
                    null, GPALObjectType.None);
            }
            _browserExtensionApiBase = browserExtensionApiBase;
 
            // how long one attempt is given, from .WithAPIBase(url, timeout). Must be longer than the timeout in
            // OttoMagic: query, select and get-content-and-css wait 10 seconds for a frame before answering with
            // nothing. Timeout.InfiniteTimeSpan asks for no limit at all, which is what a long AI call needs
            HttpTimeout = httpTimeout ?? DefaultTimeout;
            _restClient = client;
        }
 
        public string GetEndpointUrl(ApiEndpoint endpoint)
        {
            return $"{_browserExtensionApiBase}{Endpoints[endpoint]}";
        }
 
        internal async Task<string> Call(ApiEndpoint endpoint, object parameters = null, string httpMethod = "GET", ContentEncoding contentEncoding = ContentEncoding.Json)
        {
            // no /status ahead of the real call. it doubled every call into two requests, and the second one
            // arrived at the server while the first was still out at the extension. a server that is not there
            // fails on the call itself, which says which call it was
            string url = GetEndpointUrl(endpoint);
 
            string result = await InternalCall(url, parameters, httpMethod, contentEncoding).ConfigureAwait(false);
 
            return result;
        }
 
        internal async Task<string> Call(string endpoint, object parameters = null, string httpMethod = "GET", ContentEncoding contentEncoding = ContentEncoding.Json)
        {
            // an endpoint that is already a whole url is used as it stands. a session carried out of a browser
            // is scoped to the origin it was earned on, but the calls a page makes are not all to that origin,
            // and appending one to the other produced a url belonging to neither
            string url = true == endpoint?.StartsWith("http", StringComparison.OrdinalIgnoreCase)
                ? endpoint
                : $"{_browserExtensionApiBase}{endpoint}";
 
            string result = await InternalCall(url, parameters, httpMethod, contentEncoding).ConfigureAwait(false);
 
            return result;
        }
 
        internal async Task<T> CallAndDeserialize<T>(ApiEndpoint endpoint, object parameters = null, string httpMethod = "GET", ContentEncoding contentEncoding = ContentEncoding.Json)
        {
//            string url = GetEndpointUrl(endpoint);
            string jsonResponse = await Call(endpoint, parameters, httpMethod, contentEncoding).ConfigureAwait(false);
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"[{endpoint}] result: [{jsonResponse}]");
 
            return string.IsNullOrEmpty(jsonResponse)
                ? default
                : JsonConvert.DeserializeObject<T>(jsonResponse);   // system.text.json can't deserialize as cleanly
        }

        private static string DecodeJsonString(string response)
        {
            string retVal = response;
 
            while (false == string.IsNullOrEmpty(retVal)
                && true == retVal.StartsWith("\"") && true == retVal.EndsWith("\""))
            {
                try
                {
                    string peeled = JsonConvert.DeserializeObject<string>(retVal);
 
                    // an encoding that decodes to itself is not an encoding, and looping on it never ends
                    if (peeled == retVal)
                        break;
 
                    retVal = peeled;
                }
                catch (Newtonsoft.Json.JsonException)
                {
                    break;   // not an encoded string after all, so it is the value already
                }
            }
 
            return retVal;
        }
 
        internal async Task<T> CallAndDeserialize<T>(string endpoint, object parameters = null, string httpMethod = "GET", ContentEncoding contentEncoding = ContentEncoding.Json)
        {
            string jsonResponse = await Call(endpoint, parameters, httpMethod, contentEncoding).ConfigureAwait(false);
 
            // Trim took the quote characters off and left every escape inside them, so an encoded string
            // holding a quote arrived broken and an encoded object arrived unparseable. one endpoint had
            // its own unescape written for it because of this. decoding properly serves all of them
            jsonResponse = DecodeJsonString(jsonResponse);
 
            if (typeof(GPALElement) == typeof(T) || typeof(List<GPALElement>) == typeof(T))
            {
                var settings = new JsonSerializerSettings
                {
                    Converters = new List<JsonConverter> { new GPALElementConverter(), new PointConverter(), new SizeConverter() },
                    NullValueHandling = NullValueHandling.Ignore
                };
                try
                {
                    return JsonConvert.DeserializeObject<T>(jsonResponse, settings);
                }
                catch (Exception ex)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Exception calling [{endpoint}]", null, GPALObjectType.None, ex);
                }
            }
            else if(string.IsNullOrEmpty(jsonResponse))
{
                if (endpoint.Equals(Endpoints[ApiEndpoint.IsEndOfPage]) &&
                    typeof(T) == typeof(bool))
                {
                    return (T)(object)true;
                }
 
                return default;
            }
 
            if (typeof(T) == typeof(bool))
                if ("OK".Equals(jsonResponse) || "true".Equals(jsonResponse))
                    return (T)(object)true;
                else if ("NOTOK".Equals(jsonResponse) || "false".Equals(jsonResponse))
                    return (T)(object)false;
                else
                {
                    var msg = jsonResponse.Replace("\\", "");
                    GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"[{msg}]", parameters, GPALObjectType.Other);
                    return (T)(object)false;
                }
 
            // OttoMagic answers get-css-attributes with an empty array when the element is not in the dom, which is
            // the ordinary answer to asking whether a hidden element is displayed, not something to report
            if (endpoint.Equals(Endpoints[ApiEndpoint.GetCssAttributes]) && "[]".Equals(jsonResponse?.Trim()))
                return default;
 
            try
            {
                if (null != jsonResponse)
                    return JsonConvert.DeserializeObject<T>(jsonResponse);
                else
                    return default;
            }
            catch (Newtonsoft.Json.JsonException ex)
            {
                // an endpoint that answers with a bare url or word is not answering with json, and for a caller
                // asking for a string the response already is the answer. A quoted json string still goes through
                // DeserializeObject above and arrives unquoted
                if (typeof(T) == typeof(string))
                    return (T)(object)jsonResponse;
 
                GPAL.PublishSimpleEvent(GPALEventType.WARNING,
                    $"Could not deserialize [{jsonResponse?.Substring(0, Math.Min(80, jsonResponse?.Length ?? 0))}] as [{typeof(T).Name}]",
                    null, GPALObjectType.None, ex);
                return default;
            }
        }
 
        private static T HandleUnsupportedContentType<T>(string contentType, string response)
        {
            GPAL.PublishSimpleEvent(
                GPALEventType.WARNING,
                $"Unsupported format: [{contentType}]. Unable to cast to [{typeof(T)}]. Returning raw response.",
                response,
                GPALObjectType.Other);
            return default;
        }
 
        // TODO: add out param to return the server status code
        // the headers .net insists live on HttpContent. everything else is the request's
        private static readonly string[] contentHeaders =
        {
            "content-type", "content-length", "content-encoding", "content-language", "content-location",
            "content-md5", "content-range", "content-disposition", "expires", "last-modified", "allow"
        };
 
        private static bool IsContentHeader(string name)
        {
            return Array.Exists(contentHeaders, content => content.Equals(name, StringComparison.OrdinalIgnoreCase));
        }

        private static string AppendQueryString(string route, object parameters)
        {
            string query;
 
            if (parameters is string written)
            {
                query = written.TrimStart('?', '&');
            }
            else
            {
                IEnumerable<KeyValuePair<string, object>> pairs;
 
                if (parameters is IDictionary<string, object> dictionary)
                    pairs = dictionary;
                else
                    pairs = parameters.GetType().GetProperties()
                        .Select(property => new KeyValuePair<string, object>(property.Name, property.GetValue(parameters)));
 
                query = string.Join("&", pairs
                    .Where(pair => null != pair.Value)
                    .Select(pair => $"{HttpUtility.UrlEncode(pair.Key)}={HttpUtility.UrlEncode(pair.Value.ToString())}"));
            }
 
            string retVal = route;
 
            if (false == string.IsNullOrEmpty(query))
                retVal = true == route.Contains("?") ? $"{route}&{query}" : $"{route}?{query}";
 
            return retVal;
        }

        private static int ReadRetryAfter(HttpResponseMessage response)
        {
            int seconds = 0;
 
            // the header is sent either as a count of seconds or as the date the wait is over, and both forms
            // are legal on the same endpoint, so both are read
            if (null != response?.Headers?.RetryAfter)
            {
                if (true == response.Headers.RetryAfter.Delta.HasValue)
                    seconds = (int)Math.Ceiling(response.Headers.RetryAfter.Delta.Value.TotalSeconds);
                else if (true == response.Headers.RetryAfter.Date.HasValue)
                    seconds = (int)Math.Ceiling((response.Headers.RetryAfter.Date.Value - DateTimeOffset.UtcNow).TotalSeconds);
            }
 
            return 0 < seconds ? seconds : 0;
        }
 
        internal async Task<string> InternalCall(string route, object parameters = null, string httpMethod = "GET", ContentEncoding contentEncoding = ContentEncoding.Json)
        {
            string upperMethod = httpMethod.ToUpperInvariant();
 
            // a GET or a HEAD says what it is asking about in the url. .net will not put a body on either one, so
            // parameters attached as content throw before the request leaves, and the caller is told the server
            // never answered when nothing was ever sent. they go on the query string instead, which leaves the
            // content branch below with nothing to do
            if (("GET" == upperMethod || "HEAD" == upperMethod) && null != parameters)
            {
                route = AppendQueryString(route, parameters);
                parameters = null;
            }
 
            // === RETRY ONCE ON TIMEOUT ===
            async Task<string> TryOnce()
            {
                using var cts = new System.Threading.CancellationTokenSource(HttpTimeout);
                HttpResponseMessage httpResponse = new HttpResponseMessage();
                string responseBody = "";
 
                try
                {
                    if (httpMethod.ToUpper() == "POST" &&
                        route.EndsWith("upload", StringComparison.OrdinalIgnoreCase))
                    {
                        var paramsDict = parameters as IDictionary<string, object>
                            ?? parameters?.GetType().GetProperties()
                                .ToDictionary(p => p.Name, p => p.GetValue(parameters));
 
                        paramsDict.TryGetValue("uploadPath", out var uploadPathObj);
                        string uploadPath = uploadPathObj?.ToString();
 
                        paramsDict.TryGetValue("elementId", out var elementIdObj);
                        string elementId = elementIdObj?.ToString();
 
                        if (!File.Exists(uploadPath))
                        {
                            GPAL.PublishSimpleEvent(GPALEventType.ERROR,
                                $"upload file not found: [{uploadPath}]", null, GPALObjectType.None);
                            return "";
                        }
 
                        byte[] fileBytes = File.ReadAllBytes(uploadPath);
                        string base64Data = Convert.ToBase64String(fileBytes);
                        string mimeType = MimeMapping.GetMimeMapping(uploadPath);
 
                        var payload = new
                        {
                            elementId,
                            uploadPath,
                            mimeType,
                            base64Data
                        };
 
                        string jsonBody = System.Text.Json.JsonSerializer.Serialize(payload);
                        HttpContent content = new StringContent(jsonBody, Encoding.UTF8, "application/json");
 
                        var attachRequest = new HttpRequestMessage(HttpMethod.Post, route);
                        attachRequest.Content = content;
 
                        httpResponse = await _httpClient.SendAsync(attachRequest, cts.Token).ConfigureAwait(false);
                    }
                    else
                    {
                        var request = new HttpRequestMessage(new HttpMethod(httpMethod.ToUpperInvariant()), route);
 
                        request.Headers.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
 
                        foreach (var header in _restClient._headers)
                        {
                            // a content header belongs on the content, and .net throws "misused header name"
                            // rather than ignoring one put on the request. compared without case, because a
                            // header copied from a page arrives however that page wrote it
                            if (false == IsContentHeader(header.Key) && !request.Headers.Contains(header.Key))
                            {
                                request.Headers.TryAddWithoutValidation(header.Key, header.Value);
                            }
                        }
 
                        if (parameters != null)
                        {
                            // a Content-Type set by the caller is the one to send. it is skipped above because
                            // it belongs on the content rather than the request, not because it is unwanted, and
                            // a site that asks for form-urlencoded while sending json means it: replaying that
                            // as json is a different request
                            string contentType = RESTClient.GetContentType(contentEncoding);
 
                            foreach (var header in _restClient._headers)
                                if (true == "Content-Type".Equals(header.Key, StringComparison.OrdinalIgnoreCase)
                                    && false == string.IsNullOrWhiteSpace(header.Value))
                                    contentType = header.Value.Split(';')[0].Trim();   // the charset is StringContent's to add
 
                            object parms = parameters;
 
                            string parmsEncodingType = StringFormatDetector.DetectFormat(parameters.ToString());
 
                            if ("none".Equals(parmsEncodingType) && "application/json".Equals(contentType))
                            {
                                parms = System.Text.Json.JsonSerializer.Serialize(parameters);
                            }
                            else if ("none".Equals(parmsEncodingType) && "application/x-www-form-urlencoded".Equals(contentType))
                            {
                                if (!(parameters is string))
                                    parms = HttpUtility.UrlEncode(parameters.ToString());
                            }
 
                            string bodyText = parms?.ToString() ?? "";
                            request.Content = new StringContent(bodyText, System.Text.Encoding.UTF8, contentType);
                        }
 
                        httpResponse = await _httpClient.SendAsync(request, cts.Token).ConfigureAwait(false);
                    }
 
                    StatusCode = (int)httpResponse.StatusCode;
                    RetryAfterSeconds = ReadRetryAfter(httpResponse);
 
                    responseBody = await httpResponse.Content.ReadAsStringAsync().ConfigureAwait(false);
 
                    // truncate the raw body for the debug event - this is only to get a sense of the contents when
                    // diagnosing downstream issues, not a full dump. Responses can be tens of MB, and interpolating
                    // the whole thing builds a giant string on every call, so cap it and note the real length.
                    const int maxRawLogChars = 200;
                    string rawForLog = string.IsNullOrEmpty(responseBody) || responseBody.Length <= maxRawLogChars
                        ? responseBody
                        : responseBody.Substring(0, maxRawLogChars) + $"...[truncated, {responseBody.Length} chars total]";
 
                    GPAL.PublishSimpleEvent(GPALEventType.DEEPDEBUG, $"raw result[{route}][{rawForLog}]", this, GPALObjectType.RestHelper);
 
                    string upperMethod = httpMethod.ToUpperInvariant();
                    if (string.IsNullOrEmpty(responseBody) &&
                        (upperMethod == "OPTIONS" || upperMethod == "HEAD"))
                    {
                        var headerDict = new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
 
                        foreach (var h in httpResponse.Headers)
                            headerDict[h.Key] = string.Join(", ", h.Value);
 
                        foreach (var h in httpResponse.Content.Headers)
                            if (!headerDict.ContainsKey(h.Key))
                                headerDict[h.Key] = string.Join(", ", h.Value);
 
                        responseBody = System.Text.Json.JsonSerializer.Serialize(headerDict,
                            new JsonSerializerOptions { WriteIndented = true });
                    }
 
                    if (false == httpResponse.IsSuccessStatusCode)
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.WARNING,
                            $"Request [{route}] failed with status code: [{StatusCode}] [{httpResponse.ReasonPhrase}]",
                            responseBody, GPALObjectType.None);
                    }
 
                    return responseBody;
                }
                catch (Exception ex)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION,
                        $"Error in TryOnce for [{httpMethod}] [{route}]", null, GPALObjectType.RestClient, ex);
                    throw;
                }
            }
 
            // === TRY TWICE ===
            try
            {
                return await TryOnce().ConfigureAwait(false);
            }
            // a transport error that came and went is worth asking again. a cancellation is the attempt having
            // spent the whole timeout without an answer, and asking again only spends it a second time, so the
            // host that accepts a connection and never replies costs one timeout rather than two
            catch (Exception first) when (false == IsCancellation(first))
            {
                try
                {
                    await Task.Delay(2_000).ConfigureAwait(false);
                    return await TryOnce().ConfigureAwait(false); // second attempt
                }
                catch (Exception ex)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION,
                        $"Unable to communicate with: [{route}]",
                        null, GPALObjectType.None, ex);
 
                    // this browser's own endpoint, unreachable twice, is the browser being gone, and there is
                    // nothing left for the workflow to decide. a third party service that is down is the
                    // workflow's business, so that still answers with nothing and the workflow chooses
                    if (true == IsOurBrowser(route))
                        throw new GPALException($"{GPAL.MyMethodName()}: The browser at [{_browserExtensionApiBase}] did not answer [{route}] on either attempt, so there is nothing to drive");
 
                    return "";
                }
            }
            catch (Exception timedOut)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION,
                    $"Nothing answered [{route}] in [{TimeoutText()}], so the call was given up on",
                    null, GPALObjectType.None, timedOut);
 
                if (true == IsOurBrowser(route))
                    throw new GPALException($"{GPAL.MyMethodName()}: The browser at [{_browserExtensionApiBase}] did not answer [{route}] in [{TimeoutText()}], so there is nothing to drive");
 
                return "";
            }
        }
        private static bool IsCancellation(Exception ex)
        {
            bool retVal = ex is OperationCanceledException || ex is TimeoutException;
 
            if (false == retVal && ex is HttpRequestException && null != ex.InnerException)
                retVal = ex.InnerException is OperationCanceledException || ex.InnerException is TimeoutException;
 
            return retVal;
        }

        private string TimeoutText()
        {
            return System.Threading.Timeout.InfiniteTimeSpan == HttpTimeout
                ? "no limit"
                : $"{HttpTimeout.TotalSeconds:0.#} seconds";
        }

        private bool IsOurBrowser(string route)
        {
            bool retVal = false;
 
            if (false == string.IsNullOrEmpty(_browserExtensionApiBase)
                && true == route.StartsWith(_browserExtensionApiBase, StringComparison.OrdinalIgnoreCase)
                && true == Uri.TryCreate(_browserExtensionApiBase, UriKind.Absolute, out Uri baseUri)
                && true == baseUri.IsLoopback)
            {
                string called = route.Substring(_browserExtensionApiBase.Length).Split('?')[0].Trim('/');
 
                retVal = Endpoints.Values.Any(known => known.Trim('/').Equals(called, StringComparison.OrdinalIgnoreCase));
            }
 
            return retVal;
        }
 
        public async Task<bool> CheckAPIStatus()
        {
            string route = $"{_browserExtensionApiBase}{Endpoints[ApiEndpoint.CheckStatus]}";
            using (HttpClient client = new HttpClient())
            {
                try
                {
                    HttpResponseMessage response = await client.GetAsync(route).ConfigureAwait(false);
                    string responseBody = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
 
                    return responseBody.Equals("Server is running");
                }
                catch (Exception)
                {
                    return false;
                }
            }
        }
    }
    public static class StringFormatDetector
    {
        public static string DetectFormat(string input)
        {
            if (string.IsNullOrWhiteSpace(input))
                return "none";
 
            // Trim to avoid false negatives from whitespace
            var trimmed = input.Trim();
 
            // Check JSON
            if (IsJson(trimmed))
                return "json";
 
            // Check URL encoding
            if (IsUrlEncoded(trimmed))
                return "url";
 
            return "none";
        }
 
        internal static bool IsJson(string input)
        {
            if ((input.StartsWith("{") && input.EndsWith("}")) ||
                (input.StartsWith("[") && input.EndsWith("]")))
            {
                try
                {
                    using var doc = JsonDocument.Parse(input);
                    return true;
                }
                catch
                {
                    return false;
                }
            }
            return false;
        }
 
        private static bool IsUrlEncoded(string input)
        {
            try
            {
                var decoded = HttpUtility.UrlDecode(input);
                var reencoded = HttpUtility.UrlEncode(decoded);
                return string.Equals(input, reencoded, StringComparison.Ordinal);
            }
            catch
            {
                return false;
            }
        }
    }
}