BrowserSettings.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.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows.Forms;
using OpenQA.Selenium;
using static GenerallyPositive.Enums;
using System.Drawing;
using System.Xml;
using System.Diagnostics;
using System.IO.Pipes;
using System.IO;
using Newtonsoft.Json.Linq;
 
namespace GenerallyPositive.Browser
{
    internal class TabInfo
    {
        public string URL { get; set; }
        public bool ActiveTab { get; set; }
 
        public TabInfo() { }
    }
    internal class URLInfo
    {
        public int TabId { get; set; }
        public bool ActiveTab { get; set; }
 
        public URLInfo() { }
    }
    public class BrowserSettings
    {
        internal IBrowser Browser { get; set; }
        // Suppresses script-failure events for this browser only. Set while waiting on document ready, where a
        // loading page rejecting script is expected
        internal bool SuppressJavaScriptFailures { get; set; } = false;
 
        internal bool ObeyRobotsTxt { get; set; } = false;
        internal bool RespectRobotMetaTags { get; set; } = false;
 
        internal List<string> RobotsTxt { get; set; }
        internal Dictionary<int, TabInfo> TabIdsToURL { get; set; } = new Dictionary<int, TabInfo>();    // tabId > url, activeTab
        internal Dictionary<string, URLInfo> URLsToTabId { get; set; } = new Dictionary<string, URLInfo>();    // ulr > tabId, activeTab
        internal Dictionary<string, WindowInfo> WindowIdsToURL { get; set; } = new Dictionary<string, WindowInfo>();
        // name of this browser instance, set by GPAL factory
        internal string BrowserName { get; set;  }  = null;
        internal string DriverLocation { get; set;  } = null;
        internal int ServiceDriverPid { get; set; } = 0;
        // load images on a web page?
        internal bool LoadImages { get; set; } = true;
        // open pdf documents in external program?
        internal bool OpenPDFExternally { get; set; } = false;
        // open file save dialog
        internal bool PromptForDownload { get; set; } = true;
 
        // what to answer an alert, confirm or prompt the page raises. null leaves them alone, so they open and
        // block the way they would for a person. set, and the browser answers them without anyone seeing one
        internal bool? DialogsAccepted { get; set; } = null;
 
        // what a prompt hands back when dialogs are accepted. null lets the prompt's own default stand
        internal string DialogText { get; set; } = null;
 
        // handlers for failures this browser is asked to decide about. Empty means fall through to the global ones
        internal List<Browser.CallOnFailDelegate> CallOnFail { get; set; } = new List<Browser.CallOnFailDelegate>();
 
        // who this browser is, supplied by .WithCredentials, acted on once at the first navigation. Whatever
        // mechanism carries it, basic and proxy and bearer all persist for the session, so it is presented once
        internal ICredentials Credentials { get; set; }
        internal DateTime? CredentialsPresented { get; set; }
        // filetypes to download, not open
        internal List<string> DownloadFileTypeList { get; set;  } = null;
        // filetypes to open, not download
        internal List<string> OpenFileTypeList { get; set; } = null;
        // when performing an action, do we wait on document.ready?
        internal bool WaitOnDocumentReady { get; set; } = true;
        internal bool WaitOnNetworkIdle { get; set; } = false;
        internal int NetworkIdleTimeoutMs { get; set; } = 30_000;
        internal int NetworkIdleMaxConnections { get; set; } = 0;
        internal int NetworkIdlePruneMs { get; set; } = 3_000;
        internal bool TempProfileCreated { get; set; } = false;     // so we know to delete it later
        internal bool DownloadBehaviorSet { get; set; } = false;    // we pointed the browser's downloads at our own directory, so it gets handed back when we close
        internal Dictionary<string, JToken> PreviousDownloadPreferences { get; set; } = null;   // the supplied profile's download settings as we found them, put back once the browser is gone
 
        internal Dictionary<string, string> PreviousFirefoxPreferences { get; set; } = null;    // the same for a firefox profile's user.js, which is where its download and pdf settings live
        internal string ProfileDataDirectory { get; set; }
        internal string ProfileName { get; set; }
        internal string ProfileUserName { get; set; }
        // current browser type
        internal BrowserType BrowserType { get; set; } = BrowserType.Chrome;
        internal string PlatformName { get; set; } = "Windows 10";
 
        // whether to connect to existing browser to start controlling something on-screen
        internal bool UseExistingBrowser { get; set; } = false;
        internal int? ExistingBrowserPort { get; set; } = null;
 
        // for using/connecting to an already open browser
        internal int? DebugPort { get; set; }
        internal bool DebugPipe { get; set; }
        public PipeStream InboundPipe { get; set; } // Parent writes, Chrome reads
        public PipeStream OutboundPipe { get; set; } // Parent reads, Chrome writes
        public PipeStream ErrorPipe { get; set; } // Parent error, Chrome writes
        internal string PuppeteerUrl { get; set; }
 
        // asked for by .CaptureCalls, which can be said before there is a browser to say it to. read when the
        // communicator comes up, so recording starts with the first request the first page makes
        internal bool CaptureCalls { get; set; } = false;
 
        // set by .WithCallFilter. when there is one, only calls whose url holds it are recorded, which keeps a
        // long run from accumulating every image a page asked for
        internal string CallFilter { get; set; }
 
        // so an engine that cannot capture says so once rather than on every ask
        internal bool CaptureUnavailableReported { get; set; } = false;
 
        PuppeteerCommunicator _puppeteerCommunicator = null;
 
        // whether there is one already, asked without the getter below building one. reaching for a communicator
        // before the browser is up starts it connecting to a debug port nothing is listening on yet
        internal bool HasPuppeteerCommunicator => null != _puppeteerCommunicator;
 
        internal PuppeteerCommunicator PuppeteerCommunicator
        {
            get
            {
                if (null == _puppeteerCommunicator && true == UsePuppeteer)
                {
                    if (null == PuppeteerUrl)
                    {
                        // no port means this browser has not been launched, and the default is not a spare: it is
                        // the port the first browser of the run took. pointed there, this one attaches to that
                        // browser and drives it, and both workflows quietly share a session. a port of our own
                        // that nothing is listening on fails to connect instead, which is the honest answer
                        int ours = BrowserHelper.FindFreePort();
 
                        GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"A Puppeteer connection was asked for before [{BrowserType}] had a debugging port, so it is pointed at [{ours}] where nothing is listening rather than at another browser", this, GPALObjectType.Browser);
 
                        PuppeteerUrl = $"http://localhost:{ours}";
                    }
 
                    // .CaptureCalls can be said before there is a browser, so what was asked for is handed to
                    // the communicator as it is built. it connects and attaches inside its constructor, so
                    // setting this afterwards would be too late for the page it attaches to
                    _puppeteerCommunicator = new PuppeteerCommunicator(PuppeteerUrl, Browser, DebugPipe, CaptureCalls);
                }
                else if (null == _puppeteerCommunicator && false == UsePuppeteer)
                {
                    // for example, if we are in debugger and inspect browser, it will attempt to resolve. built
                    // once like the other one, rather than replaced on every read
                    _puppeteerCommunicator = new PuppeteerCommunicator();
                }
 
                return _puppeteerCommunicator;
            }
            set
            {
                _puppeteerCommunicator = value;
            }
        }
        internal IPuppeteerClient PuppeteerClient
        {
            get => PuppeteerCommunicator?.PuppeteerClient;
            set => PuppeteerCommunicator.PuppeteerClient = value;
        }
        internal bool FullScreen { get; set; } = false;
        internal bool Maximize { get; set; } = false;
        internal bool Minimize { get; set; } = false;
        public bool UseHardware { get => AutomationEngine.OttoMagicHW == AutomationEngine || AutomationEngine.PuppeteerPipeHW == AutomationEngine || AutomationEngine.PuppeteerPortHW == AutomationEngine || AutomationEngine.SeleniumHW == AutomationEngine; }
        public bool UseJavaScript { get => AutomationEngine.OttoMagic == AutomationEngine || AutomationEngine.SeleniumJS == AutomationEngine; }
        public bool UseOttoMagic { get => AutomationEngine.OttoMagic == AutomationEngine || AutomationEngine.OttoMagicHW == AutomationEngine; }
        public bool UsePuppeteer { get => AutomationEngine.PuppeteerPipe == AutomationEngine || AutomationEngine.PuppeteerPort == AutomationEngine || AutomationEngine.PuppeteerPortHW == AutomationEngine || AutomationEngine.PuppeteerPipeHW == AutomationEngine; }
        public bool UseSelenium { get => AutomationEngine.Selenium == AutomationEngine || AutomationEngine.SeleniumJS == AutomationEngine || AutomationEngine.SeleniumHW == AutomationEngine; }
 
        public AutomationEngine AutomationEngine { get; set; } = AutomationEngine.PuppeteerPort;
 
        // run on a Win32 desktop object rather than the one the user is looking at
        internal bool HiddenDesktop { get; set; } = false;
 
        // set by the browser image search while it runs: true when the match is made against the page rather than
        // the screen, so CaptureScreen asks the engine for its own capture. false the rest of the time
        internal bool ImageSearchInPage { get; set; } = false;
 
        // which one. browsers naming the same desktop share it, and browsers naming different ones get one each
        // filled in by WithHiddenDesktop: a name of this browser's own when none was given, or the name it was
        // given. the value here only stands until one of those is called
        internal string HiddenDesktopName { get; set; } = GenerallyPositive.Browser.HiddenDesktop.DefaultName;
 
        // whether what a hidden desktop means for this browser has been worked out and said. WorkflowSetup runs
        // on every action, and the engine it settles on is worth saying once rather than on all of them
        internal bool HiddenDesktopReported { get; set; } = false;
 
        // whether the desktop has been asked what actually arrived on it, which is worth doing once after the
        // launch rather than on every action afterwards
        internal bool HiddenDesktopChecked { get; set; } = false;
 
        // whether hardware being turned down on this desktop has been said. a workflow on a hidden desktop
        // resolves nearly every selector, and saying it each time buries the log
        internal bool HiddenDesktopHardwareReported { get; set; } = false;
        internal int WaitForDocumentReadyTimeoutMs { get; set; } = 30_000;
 
        // how long a click waits to see whether it started a navigation. Only covers the browser committing the
        // new url, not loading it - CheckDocumentReady owns the loading half once we know we are going somewhere
        internal int NavigationGraceMs { get; set; } = 250;
 
        internal int WithAllThatMatch { get; set; } = int.MaxValue;   // all rows, default
 
        internal string RestApiBaseUrl { get; set; }
        // true when a workflow handed us the address rather than a browser announcing it, which means the
        // browser was started by someone else and is not ours to launch, top or kill
        internal bool AttachedRestApi { get; set; }
 
        internal IMagicHelper _magicHelper = null;
        public IMagicHelper MagicHelper
        {
            get => _magicHelper;
 
            internal set => _magicHelper = value;
        }

        internal void DetachFromRunningBrowser(Browser browser)
        {
            Browser = browser;
            BrowserDriver = null;
            Process = null;
            RestApiBaseUrl = null;
            _magicHelper = new MagicHelper(browser);
            _puppeteerCommunicator = null;
        }
        internal StealthType StealthType { get; set; } = StealthType.None;
        internal bool StealthApplied { get; set; } = false;
        internal string CurrentURL { get; set; }
        private GPALUrl _currentGPALUrl = null;
        internal GPALUrl CurrentGPALUrl 
        { 
            get => _currentGPALUrl; 
            set
            {
                _currentGPALUrl = value;
                StorageActionToRun = new StorageAction();   // any time we set this, we reset the action to run, but this doesn't help us clear values from a prior call
            }
        }
        internal List<GPALUrl> GPALUrlList { get; set; }
        internal string Referrer { get; set; } = null;
        internal string OverrideUserAgent { get; set; } = null;
 
        // launch a browser purely to read its real user agent, rather than working one out without one. Off by
        // default: a headless start should not pay for a browser nobody asked for
        internal bool UserAgentFromBrowser { get; set; } = false;
        internal Selector CurrentSelector { get; set; } = null;
        internal IWebDriver BrowserDriver { get; set; } = null;
        internal System.Windows.Forms.Form CurrentForm { get; set; } = null;
        internal int WaitForWindowTimeoutInSeconds { get; set; } = 30; // seconds
        internal bool BlockPopUps { get; set; } = true;
        internal int DownloadTimeoutInSec { get; set; } = 10;
        internal bool UseDirectDownload { get; set; } = false;
        internal string DownloadLocation { get; set; }
        internal bool DeleteFileBeforeDownload { get; set; } = false;
        internal bool OpenInTab { get; set; } = false;   // caveat: note: only good for one GoTo
        internal bool UseHeadless { get; set; } = false;
        internal bool? FileDownloaded { get; set; }
        internal bool ScrollIntoView { get; set; } = false;
        internal Rectangle WindowSize { get; set; }
        internal Size SavedWindowSize { get; set; }
        internal PageOrientation PageOrientation { get; set; }
        internal object JavaScriptResultObj { get; set; }
        internal string JavaScriptResultStr { get; set; }
        internal StorageAction StorageActionToRun { get; set; }
        internal bool StorageActionCalled { get; set; }
 
        internal string Version = string.Empty;
        internal int ServerResponseCode { get; set; }
 
        internal Bitmap ScreenShot;
        internal Process Process { get; set; } = null;  // set when using ottomatic/magic which launches the browser without a driver
        internal int WhileLoopTimeoutMs { get; set; } = 30000; // Default: 30 seconds
        internal int WhileLoopMaxIterations { get; set; } = 1000; // Default: 1000 iterations
        internal List<Action<IBrowser>> Workflows { get; set; }
        internal BrowserSettings(Browser browser)
        {
            DownloadFileTypeList = new List<string>();
            OpenFileTypeList = new List<string>();
            WindowSize = new Rectangle();
            SavedWindowSize = new Size();
            Workflows = new List<Action<IBrowser>>();
            Browser = browser;
            PageOrientation = PageOrientation.Portrait;
            RobotsTxt = new List<string>();
            StorageActionToRun = new StorageAction();
            StorageActionCalled = false;
            GPALUrlList = new List<GPALUrl>();
        }
    }
}