File: PostProcessing\ArtifactProcessingManager.cs
Web Access
Project: Microsoft.TestPlatform.CrossPlatEngine.csproj (Microsoft.TestPlatform.CrossPlatEngine)
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.IO;
using System.Linq;
using System.Runtime.InteropServices;
using System.Security;
using System.Text;
using System.Threading;
using System.Threading.Tasks;

using Microsoft.VisualStudio.TestPlatform.Common;
using Microsoft.VisualStudio.TestPlatform.CommunicationUtilities;
using Microsoft.VisualStudio.TestPlatform.CommunicationUtilities.Interfaces;
using Microsoft.VisualStudio.TestPlatform.CommunicationUtilities.ObjectModel;
using Microsoft.VisualStudio.TestPlatform.CoreUtilities.Tracing;
using Microsoft.VisualStudio.TestPlatform.CrossPlatEngine.TestRunAttachmentsProcessing;
using Microsoft.VisualStudio.TestPlatform.ObjectModel;
using Microsoft.VisualStudio.TestPlatform.ObjectModel.Client;
using Microsoft.VisualStudio.TestPlatform.ObjectModel.Engine;
using Microsoft.VisualStudio.TestPlatform.Utilities;
using Microsoft.VisualStudio.TestPlatform.Utilities.Helpers;
using Microsoft.VisualStudio.TestPlatform.Utilities.Helpers.Interfaces;

namespace Microsoft.VisualStudio.TestPlatform.CrossPlatEngine.ArtifactProcessing;

internal class ArtifactProcessingManager : IArtifactProcessingManager
{
    private const string RunsettingsFileName = "runsettings.xml";
    private const string ExecutionCompleteFileName = "executionComplete.json";

    /// <summary>
    /// Set by the .NET SDK to the directory it wants the test session artifacts written into. It already
    /// exists, it is not ours to create or to delete, and on Linux it is restricted to the current user.
    /// </summary>
    /// <remarks>
    /// The name is a cross repository contract with dotnet/sdk, where it is declared in
    /// src/Cli/dotnet/Commands/Test/VSTest/VSTestArtifactsDirectory.cs. Every vstest.console process of one
    /// CLI invocation receives the same value, which is what lets the collecting run and the post processing
    /// run resolve the same path.
    /// </remarks>
    internal const string ArtifactsDirectoryEnvironmentVariableName = "VSTEST_ARTIFACTS_DIRECTORY";

    private readonly string? _testSessionCorrelationId;
    private readonly IFileHelper _fileHelper;
    private readonly ITestRunAttachmentsProcessingManager _testRunAttachmentsProcessingManager;
    private readonly string? _testSessionProcessArtifactFolder;
    private readonly string? _processArtifactFolder;
    private readonly string? _artifactsDirectory;
    private readonly bool _artifactsDirectoryWasProvided;
    private readonly IDataSerializer _dataSerialized;
    private readonly ITestRunAttachmentsProcessingEventsHandler _testRunAttachmentsProcessingEventsHandler;
    private readonly IFeatureFlag _featureFlag;

    public ArtifactProcessingManager(string? testSessionCorrelationId) :
        this(testSessionCorrelationId,
            new FileHelper(),
            new TestRunAttachmentsProcessingManager(TestPlatformEventSource.Instance, new DataCollectorAttachmentsProcessorsFactory()),
            JsonDataSerializer.Instance,
            new PostProcessingTestRunAttachmentsProcessingEventsHandler(ConsoleOutput.Instance),
            FeatureFlag.Instance)
    { }

    public ArtifactProcessingManager(string? testSessionCorrelationId,
        IFileHelper fileHelper,
        ITestRunAttachmentsProcessingManager testRunAttachmentsProcessingManager,
        IDataSerializer dataSerialized,
        ITestRunAttachmentsProcessingEventsHandler testRunAttachmentsProcessingEventsHandler,
        IFeatureFlag featureFlag)
    {
        _fileHelper = fileHelper ?? throw new ArgumentNullException(nameof(fileHelper));
        _testRunAttachmentsProcessingManager = testRunAttachmentsProcessingManager ?? throw new ArgumentNullException(nameof(testRunAttachmentsProcessingManager));
        _dataSerialized = dataSerialized ?? throw new ArgumentNullException(nameof(dataSerialized));
        _testRunAttachmentsProcessingEventsHandler = testRunAttachmentsProcessingEventsHandler ?? throw new ArgumentNullException(nameof(testRunAttachmentsProcessingEventsHandler));
        _featureFlag = featureFlag ?? throw new ArgumentNullException(nameof(featureFlag));

        // We don't validate for null, it's expected, we'll have testSessionCorrelationId only in case of .NET SDK run.
        if (testSessionCorrelationId is not null && IsSafeSessionDirectoryName(testSessionCorrelationId))
        {
            _testSessionCorrelationId = testSessionCorrelationId;
            _artifactsDirectory = ResolveArtifactsDirectory(out _artifactsDirectoryWasProvided);

            _processArtifactFolder = Path.Combine(_artifactsDirectory, _testSessionCorrelationId);
#if NET
            var pid = Environment.ProcessId;
#else
            int pid;
            using (var p = Process.GetCurrentProcess())
                pid = p.Id;
#endif
            _testSessionProcessArtifactFolder = Path.Combine(_processArtifactFolder, $"{pid}_{Guid.NewGuid()}");
        }
        else if (testSessionCorrelationId is not null)
        {
            // The SDK generates this as a plain token (a GUID). A rooted value makes Path.Combine discard
            // _artifactsDirectory outright, and any separator - including a bare ".." - lets the combined path
            // land outside the directory that was verified, so treat it the same as a missing id: every caller
            // already handles a null _testSessionCorrelationId by skipping collection and post processing.
            EqtTrace.Error($"ArtifactProcessingManager: Ignoring unsafe testSessionCorrelationId '{testSessionCorrelationId}'.");
        }
    }

    /// <summary>
    /// Returns the directory the session artifacts belong in: the one the SDK handed over, or the current
    /// user's private temporary directory when it did not.
    /// </summary>
    private static string ResolveArtifactsDirectory(out bool wasProvided)
    {
        // Not trimmed: on Unix leading and trailing whitespace is part of a valid directory name, and using a
        // different spelling than the SDK would point at a different directory.
        var providedDirectory = Environment.GetEnvironmentVariable(ArtifactsDirectoryEnvironmentVariableName);
        wasProvided = false;

        if (!providedDirectory.IsNullOrWhiteSpace())
        {
            try
            {
                // The contract says an absolute path. Anything that resolves against a current directory,
                // including a Windows drive relative path such as C:artifacts, would be resolved differently
                // by the collecting and the post processing process, and the two would then silently
                // disagree about where the artifacts are.
                if (IsFullyQualified(providedDirectory))
                {
                    // Assigned only once the path is known to be usable, so that a failure below leaves this
                    // reporting the user-private temporary directory it actually falls back to.
                    var fullPath = Path.GetFullPath(providedDirectory);
                    wasProvided = true;
                    return fullPath;
                }

                EqtTrace.Warning($"ArtifactProcessingManager: Ignoring {ArtifactsDirectoryEnvironmentVariableName}, '{providedDirectory}' is not an absolute path.");
            }
            catch (Exception e) when (e is ArgumentException or NotSupportedException or PathTooLongException or SecurityException)
            {
                // A malformed value must not take the whole run down, the user-private temporary directory
                // still works.
                EqtTrace.Warning($"ArtifactProcessingManager: Ignoring {ArtifactsDirectoryEnvironmentVariableName}, '{providedDirectory}' is not a usable path: {e}");
            }
        }

        return GetUserPrivateTempPath();
    }

    /// <summary>
    /// Returns the current user's private temporary directory, used as the base for the artifacts directory
    /// when the .NET SDK does not provide one.
    /// </summary>
    /// <remarks>
    /// Never derived from the environment variable that normally sets the shared temporary directory
    /// (TMP/TEMP on Windows, TMPDIR on Unix, and the value <see cref="Path.GetTempPath()"/> would return):
    /// any process in the same session could repoint that variable at a world writable location, which
    /// would make the "temporary directory" fallback no safer than a path an attacker chose.
    /// </remarks>
    internal /* for testing */ static string GetUserPrivateTempPath()
    {
#if NETFRAMEWORK
        // .NET Framework only runs on Windows.
        return Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
#else
        if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
        {
            return Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
        }

        if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
        {
            return GetMacUserTempPath();
        }

        // Linux (and other Unix platforms): the XDG_RUNTIME_DIR convention, "/run/user/<uid>", built from
        // the real uid rather than trusted from the XDG_RUNTIME_DIR environment variable.
        return $"/run/user/{NativeGetEuid()}";
#endif
    }

    /// <summary>
    /// True when <paramref name="name"/> is safe to use as a single path segment under the artifacts
    /// directory: not rooted, not containing a directory separator, and not "." or "..".
    /// </summary>
    private static bool IsSafeSessionDirectoryName(string name)
        => !Path.IsPathRooted(name)
        && name.IndexOfAny(new[] { Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar }) < 0
        && name is not ("." or "..");

    /// <summary>
    /// Whether a path resolves to the same place regardless of the current directory of the process reading
    /// it. Being rooted is not enough on Windows, where "C:artifacts" is rooted but resolves against the
    /// current directory of that drive.
    /// </summary>
    private static bool IsFullyQualified(string path)
    {
#if NET
        return Path.IsPathFullyQualified(path);
#else
        if (!Path.IsPathRooted(path))
        {
            return false;
        }

        // On Unix a rooted path starts at the filesystem root, so it is already fully qualified.
        if (Path.DirectorySeparatorChar == '/')
        {
            return true;
        }

        // A UNC path, "\\server\share".
        if (path.Length >= 2 && IsSeparator(path[0]) && IsSeparator(path[1]))
        {
            return true;
        }

        // A drive together with a separator, "C:\artifacts".
        return path.Length >= 3 && path[1] == ':' && IsSeparator(path[2]);

        static bool IsSeparator(char c) => c is '\\' or '/';
#endif
    }

    public string? CollectArtifacts(TestRunCompleteEventArgs testRunCompleteEventArgs, string runSettingsXml)
    {
        ValidateArg.NotNull(testRunCompleteEventArgs, nameof(testRunCompleteEventArgs));
        ValidateArg.NotNull(runSettingsXml, nameof(runSettingsXml));

        if (_featureFlag.IsSet(FeatureFlag.VSTEST_DISABLE_ARTIFACTS_POSTPROCESSING))
        {
            EqtTrace.Verbose("ArtifactProcessingManager.CollectArtifacts: Feature disabled");
            return null;
        }

        if (_testSessionCorrelationId.IsNullOrEmpty())
        {
            EqtTrace.Verbose("ArtifactProcessingManager.CollectArtifacts: null testSessionCorrelationId");
            return null;
        }

        // A correlation id means the .NET SDK wants artifacts produced here and consumed by itself later, so
        // a silent fallback away from the directory it asked for is worth a warning the user actually sees,
        // not just a trace that needs --diag. Computed as soon as the id is known to be present, rather than
        // only once there happens to be something to persist, so it is reported on every such run.
        string? artifactsDirectoryFallbackWarning = null;
        if (!_artifactsDirectoryWasProvided)
        {
            // Not provided covers both an absent variable and one whose value ResolveArtifactsDirectory
            // rejected, and the two need different advice.
            var rawArtifactsDirectory = Environment.GetEnvironmentVariable(ArtifactsDirectoryEnvironmentVariableName);
            artifactsDirectoryFallbackWarning = rawArtifactsDirectory.IsNullOrWhiteSpace()
                ? $"{ArtifactsDirectoryEnvironmentVariableName} environment variable was not found, falling back to a user-private temporary directory. This is most likely caused by an outdated Microsoft.NET.Test.Sdk package reference in the test project."
                : $"{ArtifactsDirectoryEnvironmentVariableName} environment variable was set but ignored because its value '{rawArtifactsDirectory}' is not a usable absolute path, falling back to a user-private temporary directory.";
        }

        // We need to save in case of attachements, we'll show these at the end on console.
        // A null collection is treated the same as an empty one, there is nothing to persist either way.
        if (testRunCompleteEventArgs.AttachmentSets is not { Count: > 0 })
        {
            return artifactsDirectoryFallbackWarning;
        }

        TPDebug.Assert(_testSessionProcessArtifactFolder is not null, "_testSessionProcessArtifactFolder is null");
        TPDebug.Assert(_processArtifactFolder is not null, "_processArtifactFolder is null");

        try
        {
            EqtTrace.Verbose($"ArtifactProcessingManager.CollectArtifacts: Saving data collectors artifacts for post process into {_processArtifactFolder}");
            Stopwatch watch = Stopwatch.StartNew();
            ValidateArtifactsDirectory();
            CreateDirectoryWithUserOnlyAccess(_processArtifactFolder);
            _fileHelper.CreateDirectory(_testSessionProcessArtifactFolder);
            EqtTrace.Verbose($"ArtifactProcessingManager.CollectArtifacts: Persist runsettings \n{runSettingsXml}");
            _fileHelper.WriteAllTextToFile(Path.Combine(_testSessionProcessArtifactFolder, RunsettingsFileName), runSettingsXml);
            var serializedExecutionComplete = _dataSerialized.SerializePayload(MessageType.ExecutionComplete, testRunCompleteEventArgs);
            EqtTrace.Verbose($"ArtifactProcessingManager.CollectArtifacts: Persist ExecutionComplete message \n{serializedExecutionComplete}");
            _fileHelper.WriteAllTextToFile(Path.Combine(_testSessionProcessArtifactFolder, ExecutionCompleteFileName), serializedExecutionComplete);
            EqtTrace.Verbose($"ArtifactProcessingManager.CollectArtifacts: Artifacts saved in {watch.Elapsed}");
            return artifactsDirectoryFallbackWarning;
        }
        catch (ArtifactDirectoryVerificationException e)
        {
            // Rejecting the directory means the artifacts of this session are dropped, which is worth more
            // than a verbose trace even though, like every other collection failure, it leaves the result of
            // the test run alone. This one is also reported back to the caller: unlike a generic I/O failure
            // below, it is expected to recur on every run in an affected environment (e.g. a container with
            // no per-user runtime directory), so a one-off trace that needs --diag to see is not enough.
            EqtTrace.Warning("ArtifactProcessingManager.CollectArtifacts: The test session artifacts were not saved: " + e);
            return $"The test session artifacts were not saved: {e.Message}";
        }
        catch (Exception e)
        {
            EqtTrace.Error("ArtifactProcessingManager.CollectArtifacts: Exception during artifact post processing: " + e);
            return null;
        }
    }

    public async Task PostProcessArtifactsAsync()
    {
        if (_featureFlag.IsSet(FeatureFlag.VSTEST_DISABLE_ARTIFACTS_POSTPROCESSING))
        {
            EqtTrace.Verbose("ArtifactProcessingManager.PostProcessArtifacts: Feature disabled");
            return;
        }

        // This is not expected, anyway we prefer avoid exception for post processing
        if (_testSessionCorrelationId.IsNullOrEmpty())
        {
            EqtTrace.Error("ArtifactProcessingManager.PostProcessArtifacts: Unexpected null testSessionCorrelationId");
            return;
        }

        TPDebug.Assert(_processArtifactFolder is not null, "_processArtifactFolder is null");

        // Validated before checking whether the session directory exists, so a bad artifacts directory is
        // always reported instead of being masked by the more specific "no session directory" message below.
        // A failure here reaches the argument processor, which reports it and exits non zero.
        ValidateArtifactsDirectory();

        if (!_fileHelper.DirectoryExists(_processArtifactFolder))
        {
            // The SDK only starts this mode because it saw the session directory, so not finding it means the
            // collecting process and this one disagreed about where the artifacts go.
            EqtTrace.Warning($"ArtifactProcessingManager.PostProcessArtifacts: There are no artifacts to postprocess in '{_processArtifactFolder}'");
            return;
        }

        EnsureDirectoryIsPrivateToCurrentUser(_processArtifactFolder, $"The test session directory '{_processArtifactFolder}'");

        var testArtifacts = LoadTestArtifacts();
        if (testArtifacts?.Length > 0)
        {
            try
            {
                await DataCollectorsAttachmentsPostProcessing(testArtifacts);
            }
            finally
            {
                try
                {
                    _fileHelper.DeleteDirectory(_processArtifactFolder, true);
                    EqtTrace.Verbose($"ArtifactProcessingManager.PostProcessArtifacts: Directory '{_processArtifactFolder}' removed.");
                }
                catch (Exception ex)
                {
                    EqtTrace.Error($"ArtifactProcessingManager.PostProcessArtifacts: Unable to removed directory the '{_processArtifactFolder}'.\n{ex}");
                }
            }
        }
        else
        {
            EqtTrace.Warning($"ArtifactProcessingManager.PostProcessArtifacts: There are no artifacts to postprocess also if the artifact directory '{_processArtifactFolder}' exits");
        }
    }

    // We don't put everything inside a try/catch, we prefer get the exceptions because
    // we don't want partial results, it could confuse the user, better have a "failure".
    private async Task DataCollectorsAttachmentsPostProcessing(TestArtifacts[] testArtifacts)
    {
        // We take the biggest runsettings in size, it should be the one with more configuration.
        // In future we can think to merge...but it's not easy for custom config, we could break something.
        string? runsettingsFile = testArtifacts
            .SelectMany(x => x.Artifacts.Where(x => x.Type == ArtifactType.Runsettings))
            .OrderByDescending(x => _fileHelper.GetFileLength(x.FileName))
            .FirstOrDefault()?.FileName;

        string? runsettingsXml = null;
        if (runsettingsFile is not null)
        {
            using var artifactStream = _fileHelper.GetStream(runsettingsFile, FileMode.Open, FileAccess.Read);
            using var streamReader = new StreamReader(artifactStream);
            runsettingsXml = await streamReader.ReadToEndAsync();
            EqtTrace.Verbose($"ArtifactProcessingManager.MergeDataCollectorAttachments: Chosen runsettings \n{runsettingsXml}");
        }
        else
        {
            EqtTrace.Verbose($"ArtifactProcessingManager.MergeDataCollectorAttachments: Null runsettings");
        }

        HashSet<InvokedDataCollector> invokedDataCollectors = new();
        List<AttachmentSet> attachments = new();
        foreach (var artifact in testArtifacts
            .SelectMany(x => x.Artifacts)
            .Where(x => x.Type == ArtifactType.ExecutionComplete))
        {
            using var artifactStream = _fileHelper.GetStream(artifact.FileName, FileMode.Open, FileAccess.Read);
            using var streamReader = new StreamReader(artifactStream);
            string executionCompleteMessage = await streamReader.ReadToEndAsync();
            EqtTrace.Verbose($"ArtifactProcessingManager.MergeDataCollectorAttachments: ExecutionComplete message \n{executionCompleteMessage}");
            TestRunCompleteEventArgs? eventArgs = _dataSerialized.DeserializePayload<TestRunCompleteEventArgs>(_dataSerialized.DeserializeMessage(executionCompleteMessage));
            foreach (var invokedDataCollector in eventArgs?.InvokedDataCollectors ?? Enumerable.Empty<InvokedDataCollector>())
            {
                invokedDataCollectors.Add(invokedDataCollector);
            }
            foreach (var attachmentSet in eventArgs?.AttachmentSets ?? Enumerable.Empty<AttachmentSet>())
            {
                attachments.Add(attachmentSet);
            }
        }

        await _testRunAttachmentsProcessingManager.ProcessTestRunAttachmentsAsync(runsettingsXml,
            new RequestData()
            {
                IsTelemetryOptedIn = IsTelemetryOptedIn(),
                ProtocolConfig = ObjectModel.Constants.DefaultProtocolConfig
            },
            attachments,
            invokedDataCollectors,
            _testRunAttachmentsProcessingEventsHandler,
            CancellationToken.None);
    }

    private TestArtifacts[] LoadTestArtifacts()
    {
        TPDebug.Assert(_processArtifactFolder is not null, "_processArtifactFolder is null");
        return _fileHelper.GetFiles(_processArtifactFolder, "*.*", SearchOption.AllDirectories)
            .Select(file => new { TestSessionId = Path.GetFileName(Path.GetDirectoryName(file)), Artifact = file })
            .GroupBy(grp => grp.TestSessionId)
            .Select(testSessionArtifact => new TestArtifacts(testSessionArtifact.Key!, testSessionArtifact.Select(x => ParseArtifact(x.Artifact)).Where(x => x is not null).ToArray()!)) // Bang because null dataflow doesn't yet backport learning from the `Where` clause
            .ToArray();
    }

    private static Artifact? ParseArtifact(string fileName)
    {
        ValidateArg.NotNull(fileName, nameof(fileName));

        return Path.GetFileName(fileName) switch
        {
            RunsettingsFileName => new Artifact(fileName, ArtifactType.Runsettings),
            ExecutionCompleteFileName => new Artifact(fileName, ArtifactType.ExecutionComplete),
            _ => null
        };
    }

    private static bool IsTelemetryOptedIn() => Environment.GetEnvironmentVariable("VSTEST_TELEMETRY_OPTEDIN")?.Equals("1", StringComparison.Ordinal) == true;

    /// <summary>
    /// Creates a directory that only the current user can access on Unix.
    /// </summary>
    internal /* for testing */ void CreateDirectoryWithUserOnlyAccess(string path)
    {
        _fileHelper.CreateDirectory(path);
        VerifyDirectoryHasUserOnlyAccess(path);
    }

    /// <summary>
    /// Restricts an existing directory to the current user on Unix.
    /// </summary>
    /// <remarks>
    /// This mutates and is only used on directories vstest.console creates itself. Directories handed over by
    /// the SDK are checked with <see cref="EnsureDirectoryIsPrivateToCurrentUser"/> instead, never modified.
    /// <para>
    /// The directory is opened with O_NOFOLLOW | O_DIRECTORY rather than stat'd by path and then chmod'd by
    /// path: the kernel itself refuses to open a final symlink (ELOOP) or anything that is not a directory
    /// (ENOTDIR), and the resulting file descriptor then refers to exactly the object that both the ownership
    /// read below and fchmod act on, so nothing can be swapped in at that path between the check and the
    /// action, unlike with two separate by-path calls.
    /// </para>
    /// <para>
    /// The owner is checked explicitly rather than inferred from chmod succeeding: chmod (and fchmod) succeed
    /// for root against a directory owned by anyone, so when running as root a successful chmod alone would
    /// not prove this user owns the directory. A directory already owned by someone else is rejected instead
    /// of being narrowed and written into. The read path has no second action a race could target - it is a
    /// single stat call that never mutates anything - so it checks the owner by path instead.
    /// </para>
    /// </remarks>
    internal /* for testing */ void VerifyDirectoryHasUserOnlyAccess(string path)
    {
        if (_featureFlag.IsSet(FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION))
        {
            EqtTrace.Verbose("ArtifactProcessingManager.VerifyDirectoryHasUserOnlyAccess: Verification disabled");
            return;
        }

#if !NETFRAMEWORK
        if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows) || !Directory.Exists(path))
        {
            return;
        }

        // A trailing separator makes the kernel resolve a final symlink before O_NOFOLLOW is applied.
        path = TrimTrailingSeparators(path);
        if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
        {
            EnsurePathCannotBeReplacedByOtherUsers(path, $"'{path}'");
        }

        int fd = NativeOpen(path, GetOpenNoFollowDirectoryFlags());
        if (fd < 0)
        {
            int openErrno = Marshal.GetLastWin32Error();
            if (IsSymlinkOrNotADirectoryErrno(openErrno))
            {
                throw new ArtifactDirectoryVerificationException(
                    $"'{path}' is not a directory. A symbolic link is not accepted, because the artifacts would be written somewhere other than the directory that was checked. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
            }

            throw new ArtifactDirectoryVerificationException($"Could not open '{path}', errno: {openErrno}. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
        }

        try
        {
            // Read through the fd, not the path, so this reports the owner of the object fchmod below
            // narrows, not whatever the path happens to resolve to by the time this runs.
            var status = GetUnixStatus(fd, string.Empty, AtEmptyPath, $"'{path}'");
            uint effectiveUserId = NativeGetEuid();
            if (status is not null)
            {
                if (status.Value.OwnerId != effectiveUserId)
                {
                    throw new ArtifactDirectoryVerificationException(
                        $"'{path}' is owned by uid {status.Value.OwnerId} rather than by uid {effectiveUserId}. The test session artifacts are not written into a directory left behind by another user. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
                }
            }
            else if (effectiveUserId == 0)
            {
                // Can't verify ownership, and fchmod would succeed even on a directory we don't own because
                // we're root: the kernel won't stop us the way it does a non-root caller. Refuse instead of
                // silently narrowing permissions on a directory that might belong to someone else. A non-root
                // caller proceeds, as fchmod below fails with EPERM when it does not own the directory.
                throw new ArtifactDirectoryVerificationException(
                    $"Could not read the owner of '{path}' (statx unavailable), and refusing to modify it while running as root. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
            }

            // Narrows the directory to its owner, through the same fd that was just opened with
            // O_NOFOLLOW | O_DIRECTORY, rather than chmod(path, ...), so this cannot be redirected by a
            // symlink swapped in at that path after the checks above.
            int chmodErrno = NativeFchmod(fd, OwnerFullAccess) == 0 ? 0 : Marshal.GetLastWin32Error();
            if (chmodErrno != 0)
            {
                throw new ArtifactDirectoryVerificationException(
                    $"Could not restrict '{path}' to the current user, errno: {chmodErrno}. The test session artifacts are not written when the directory holding them cannot be protected. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this.");
            }
        }
        finally
        {
            _ = NativeClose(fd);
        }
#endif
    }

    /// <summary>
    /// Checks the directory the session artifacts are written into, or read back from, before it is used.
    /// </summary>
    /// <remarks>
    /// A directory handed over by the SDK is verified rather than modified: it has to exist, and on Linux it
    /// has to be a real directory owned by the current user that nobody else can reach, and that no other user
    /// can replace through one of its parent directories. When vstest.console picks the location itself the
    /// base is the current user's own private temporary directory (see <see cref="GetUserPrivateTempPath"/>),
    /// which the platform already keeps private to the user, so only its existence is checked here, and the
    /// session directory created inside it, verified together with every directory leading to it, is what
    /// carries the restricted permissions.
    /// </remarks>
    private void ValidateArtifactsDirectory()
    {
        TPDebug.Assert(_artifactsDirectory is not null, "_artifactsDirectory is null");

        if (!_fileHelper.DirectoryExists(_artifactsDirectory))
        {
            throw new ArtifactDirectoryVerificationException(_artifactsDirectoryWasProvided
                ? $"The directory given by {ArtifactsDirectoryEnvironmentVariableName}, '{_artifactsDirectory}', does not exist."
                : $"The user-private temporary directory '{_artifactsDirectory}' does not exist.");
        }

        // The ownership and the permissions only mean something on Linux, which is also the only platform
        // where the SDK restricts the directory it hands over.
        if (_artifactsDirectoryWasProvided)
        {
            EnsureDirectoryIsPrivateToCurrentUser(
                _artifactsDirectory,
                $"The directory given by {ArtifactsDirectoryEnvironmentVariableName}, '{_artifactsDirectory}',");
        }
    }

    /// <summary>
    /// Verifies on Linux that a path is a real directory, owned by the current user, that no other user can
    /// reach or replace through one of its parent directories. Does nothing anywhere else, never modifies the
    /// directory, and fails rather than skipping a check the platform cannot answer.
    /// </summary>
    private void EnsureDirectoryIsPrivateToCurrentUser(string path, string description)
    {
        if (_featureFlag.IsSet(FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION))
        {
            EqtTrace.Verbose("ArtifactProcessingManager.EnsureDirectoryIsPrivateToCurrentUser: Verification disabled");
            return;
        }

#if !NETFRAMEWORK
        if (!RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
        {
            return;
        }

        EnsurePathCannotBeReplacedByOtherUsers(path, description);

        // Taken from a single statx call, so a symlink cannot be swapped in between the type, owner and mode
        // checks below.
        (uint ownerId, ushort mode) = RequireUnixPathStatus(path, description);
        if ((mode & FileTypeMask) != DirectoryFileType)
        {
            throw new ArtifactDirectoryVerificationException(
                $"{description} is not a directory. A symbolic link is not accepted, because the artifacts would be written somewhere other than the directory that was checked. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
        }

        uint effectiveUserId = NativeGetEuid();
        if (ownerId != effectiveUserId)
        {
            throw new ArtifactDirectoryVerificationException(
                $"{description} is owned by uid {ownerId} rather than by uid {effectiveUserId}. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
        }

        // 0077 octal = any permission for the group or for everybody else.
        const ushort groupAndOtherPermissions = 0x3F;
        if ((mode & groupAndOtherPermissions) != 0)
        {
            throw new ArtifactDirectoryVerificationException(
                $"{description} can be accessed by users other than its owner, it should allow the owner only. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
        }
#endif
    }

#if !NETFRAMEWORK
    /// <summary>
    /// Verifies on Linux that no user other than the current one or root can make <paramref name="path"/>
    /// resolve to something else after it has been checked.
    /// </summary>
    /// <remarks>
    /// Checking only the final directory is not enough: a user who can rename entries in one of its parent
    /// directories can move the checked directory away and put a symlink, or a directory of their own, in its
    /// place, and every later by-path read or write then follows that instead. So every directory the kernel
    /// walks through to reach <paramref name="path"/> has to be owned by the current user or by root, and every
    /// entry on the way, <paramref name="path"/> included, has to sit in a directory that no other user can
    /// write to, or in a sticky directory such as /tmp while being owned by the current user or by root.
    /// Symbolic links on the way are followed: a link cannot be changed, only replaced through the directory
    /// holding it, which is held to the same rule. The final entry is not followed, its own type, owner and
    /// mode are for the caller to check.
    /// </remarks>
    private static void EnsurePathCannotBeReplacedByOtherUsers(string path, string description)
    {
        // The kernel's own limit (MAXSYMLINKS), past which it fails a lookup with ELOOP.
        const int maxSymbolicLinks = 40;
        // 0022 octal = write permission for the group or for everybody else.
        const ushort groupOrOtherWrite = 0x12;
        // 01000 octal = sticky bit, only the owner of an entry (or of the directory) can rename or delete it.
        const ushort sticky = 0x200;

        uint effectiveUserId = NativeGetEuid();

        // The directories resolved so far, from "/" down, none of them a symbolic link.
        var resolved = new List<(string Path, ushort Mode)>();
        (uint rootOwnerId, ushort rootMode) = RequireUnixPathStatus("/", description);
        if (!IsTrustedOwner(rootOwnerId))
        {
            throw new ArtifactDirectoryVerificationException(
                $"{description} cannot be verified, '/' is owned by uid {rootOwnerId}. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
        }

        resolved.Add(("/", rootMode));

        // The components still to walk, the next one on top so that a symlink target can be pushed in front
        // of the rest.
        var pending = new Stack<string>();
        PushComponents(pending, path);
        int symbolicLinks = 0;
        while (pending.Count > 0)
        {
            string name = pending.Pop();
            if (name == ".")
            {
                continue;
            }

            if (name == "..")
            {
                // Every directory in the list was verified on the way down, so going back up needs no new check.
                if (resolved.Count > 1)
                {
                    resolved.RemoveAt(resolved.Count - 1);
                }

                continue;
            }

            (string parentPath, ushort parentMode) = resolved[resolved.Count - 1];
            string entry = parentPath == "/" ? "/" + name : parentPath + "/" + name;
            (uint ownerId, ushort mode) = RequireUnixPathStatus(entry, description);

            if ((parentMode & groupOrOtherWrite) != 0 && ((parentMode & sticky) == 0 || !IsTrustedOwner(ownerId)))
            {
                throw new ArtifactDirectoryVerificationException(
                    $"{description} cannot be verified, because users other than its owner can replace '{entry}': '{parentPath}' can be written by its group or by everybody{((parentMode & sticky) == 0 ? " and is not sticky" : $", and '{entry}' is owned by uid {ownerId}")}. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
            }

            if (pending.Count == 0)
            {
                return;
            }

            switch (mode & FileTypeMask)
            {
                case SymbolicLinkFileType:
                    if (++symbolicLinks > maxSymbolicLinks)
                    {
                        throw new ArtifactDirectoryVerificationException(
                            $"{description} cannot be verified, resolving it follows more than {maxSymbolicLinks} symbolic links. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
                    }

                    string target = ReadSymbolicLink(entry, description);
                    if (target.StartsWith("/", StringComparison.Ordinal))
                    {
                        resolved.RemoveRange(1, resolved.Count - 1);
                    }

                    PushComponents(pending, target);
                    break;

                case DirectoryFileType:
                    if (!IsTrustedOwner(ownerId))
                    {
                        throw new ArtifactDirectoryVerificationException(
                            $"{description} cannot be verified, because '{entry}' on the way to it is owned by uid {ownerId}, who can replace what it contains. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
                    }

                    resolved.Add((entry, mode));
                    break;

                default:
                    throw new ArtifactDirectoryVerificationException(
                        $"{description} cannot be verified, '{entry}' on the way to it is not a directory. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
            }
        }

        bool IsTrustedOwner(uint ownerId) => ownerId == 0 || ownerId == effectiveUserId;

        static void PushComponents(Stack<string> stack, string value)
        {
            string[] components = value.Split(new[] { '/' }, StringSplitOptions.RemoveEmptyEntries);
            for (int i = components.Length - 1; i >= 0; i--)
            {
                stack.Push(components[i]);
            }
        }
    }

    /// <summary>
    /// Reads the target of a symbolic link, exactly as stored.
    /// </summary>
    private static string ReadSymbolicLink(string path, string description)
    {
        // PATH_MAX on Linux. readlink does not null terminate, and a result that fills the whole buffer may
        // have been truncated.
        var buffer = new byte[4096];
        long length = (long)NativeReadLink(path, buffer, (UIntPtr)buffer.Length);
        if (length < 0)
        {
            throw new ArtifactDirectoryVerificationException(
                $"{description} cannot be verified, could not read the symbolic link '{path}', errno: {Marshal.GetLastWin32Error()}. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
        }

        if (length >= buffer.Length)
        {
            throw new ArtifactDirectoryVerificationException(
                $"{description} cannot be verified, the target of the symbolic link '{path}' is too long. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
        }

        // Decoded strictly: a lossy decode would turn invalid bytes into U+FFFD, so the walk would check a
        // different path than the one the kernel follows.
        try
        {
            return StrictUtf8.GetString(buffer, 0, (int)length);
        }
        catch (DecoderFallbackException)
        {
            throw new ArtifactDirectoryVerificationException(
                $"{description} cannot be verified, the target of the symbolic link '{path}' is not valid UTF-8. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
        }
    }

    private static readonly UTF8Encoding StrictUtf8 = new(encoderShouldEmitUTF8Identifier: false, throwOnInvalidBytes: true);

    /// <summary>
    /// Removes trailing '/' separators, keeping "/" itself.
    /// </summary>
    /// <remarks>
    /// With a trailing separator the kernel resolves a final symlink before AT_SYMLINK_NOFOLLOW or O_NOFOLLOW
    /// is applied, so "/tmp/link/" would be checked as the directory the link points to rather than as a link.
    /// </remarks>
    private static string TrimTrailingSeparators(string path)
    {
        string trimmed = path.TrimEnd('/');
        return trimmed.Length == 0 && path.Length > 0 ? "/" : trimmed;
    }

    /// <summary>
    /// Reads the owner and the mode of a path without following a final symlink, failing when that cannot be
    /// done, so that a directory is never used unverified unless verification is explicitly disabled.
    /// </summary>
    private static (uint OwnerId, ushort Mode) RequireUnixPathStatus(string path, string description)
        => GetUnixPathStatus(path)
            ?? throw new ArtifactDirectoryVerificationException(
                $"{description} cannot be verified, because statx is not available on this system. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");

    /// <summary>
    /// Reads the owner and the mode of a path without following a final symlink, or <see langword="null"/>
    /// when the platform has no usable statx.
    /// </summary>
    private static (uint OwnerId, ushort Mode)? GetUnixPathStatus(string path)
        => GetUnixStatus(AtFdCwd, TrimTrailingSeparators(path), AtSymlinkNoFollow, $"'{path}'");

    /// <summary>
    /// Reads the owner and the mode of a path, or of an already open file descriptor, through statx, or
    /// <see langword="null"/> when the platform has no usable statx.
    /// </summary>
    /// <param name="dirFileDescriptor">
    /// A directory file descriptor <paramref name="pathname"/> is resolved against, <see cref="AtFdCwd"/> to
    /// resolve it against the current directory instead, or the descriptor to read directly when
    /// <paramref name="pathname"/> is empty and <paramref name="flags"/> includes <see cref="AtEmptyPath"/>.
    /// </param>
    /// <param name="pathname">The path to resolve, or empty to read <paramref name="dirFileDescriptor"/> itself.</param>
    /// <param name="flags"><see cref="AtSymlinkNoFollow"/> or <see cref="AtEmptyPath"/>.</param>
    /// <param name="description">How to refer to what is being read in an exception or a trace message.</param>
    private static (uint OwnerId, ushort Mode)? GetUnixStatus(int dirFileDescriptor, string pathname, int flags, string description)
    {
        // struct statx has the same layout on every architecture, unlike struct stat: stx_mask sits at
        // offset 0, stx_uid at 20 and stx_mode at 28, so the fields can be read out of a plain buffer.
        const int statxBufferSize = 256;
        const int maskOffset = 0;
        const int ownerIdOffset = 20;
        const int modeOffset = 28;

        var buffer = new byte[statxBufferSize];
        int result;
        try
        {
            result = NativeStatx(dirFileDescriptor, pathname, flags, StatxRequestedFields, buffer);
        }
        catch (Exception e) when (e is EntryPointNotFoundException or DllNotFoundException)
        {
            // statx reached glibc in 2.28 and musl in 1.2.5, so it can genuinely be absent on a distribution
            // that is otherwise supported, and it does not exist on macOS at all.
            EqtTrace.Warning($"ArtifactProcessingManager.GetUnixStatus: statx is unavailable, cannot read the owner of {description}: {e}");
            return null;
        }

        if (result != 0)
        {
            int errno = Marshal.GetLastWin32Error();

            // ENOSYS / EOPNOTSUPP mean the same thing as a missing symbol: this platform cannot answer.
            const int enosys = 38;
            const int eopnotsupp = 95;
            if (errno is enosys or eopnotsupp)
            {
                EqtTrace.Warning($"ArtifactProcessingManager.GetUnixStatus: statx is not supported here, cannot read the owner of {description}, errno: {errno}");
                return null;
            }

            throw new ArtifactDirectoryVerificationException($"Could not read the owner and the permissions of {description}, errno: {errno}. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
        }

        // stx_mask reports which fields the kernel actually filled. An unreported owner reads back as 0,
        // which would otherwise be indistinguishable from a directory owned by root.
        uint filled = BitConverter.ToUInt32(buffer, maskOffset);
        if ((filled & StatxRequestedFields) != StatxRequestedFields)
        {
            throw new ArtifactDirectoryVerificationException($"The status of {description} does not report the owner and the mode, so it cannot be verified. Set {FeatureFlag.VSTEST_DISABLE_ARTIFACTS_DIRECTORY_VERIFICATION}=1 to skip this check.");
        }

        return (BitConverter.ToUInt32(buffer, ownerIdOffset), BitConverter.ToUInt16(buffer, modeOffset));
    }

    private const int AtFdCwd = -100;
    private const int AtSymlinkNoFollow = 0x100;
    // Tells statx to read the file descriptor itself rather than a path resolved against it, used together
    // with an empty pathname.
    private const int AtEmptyPath = 0x1000;
    // STATX_TYPE | STATX_MODE | STATX_UID. The type bits are requested explicitly because STATX_MODE alone
    // only covers the permission bits.
    private const uint StatxRequestedFields = 0x00000001 | 0x00000002 | 0x00000008;

    // 0700 octal = owner read/write/execute only.
    private const int OwnerFullAccess = 0x1C0;

    // 0170000 octal masks the file type in a mode, 0040000 is a directory and 0120000 a symbolic link.
    private const ushort FileTypeMask = 0xF000;
    private const ushort DirectoryFileType = 0x4000;
    private const ushort SymbolicLinkFileType = 0xA000;

    /// <summary>
    /// The O_NOFOLLOW | O_DIRECTORY | O_RDONLY flags used to open a directory while rejecting a final
    /// symlink or anything that is not a directory at the kernel level.
    /// </summary>
    /// <remarks>
    /// The bit values differ between Darwin and Linux, and on Linux between architectures: arm, arm64 and
    /// powerpc define their own in &lt;asm/fcntl.h&gt;, where the generic values mean O_DIRECT and O_LARGEFILE
    /// instead. Every other architecture uses &lt;asm-generic/fcntl.h&gt;.
    /// </remarks>
    private static int GetOpenNoFollowDirectoryFlags()
    {
        if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
        {
            return 0x000100 | 0x100000; // O_NOFOLLOW | O_DIRECTORY (Darwin <fcntl.h>)
        }

        // Compared by value: the netstandard2.0 Architecture enum predates Armv6 and Ppc64le, but the runtime
        // still reports them.
        return (int)RuntimeInformation.ProcessArchitecture switch
        {
            2 /* Arm */ or 3 /* Arm64 */ or 7 /* Armv6 */ or 8 /* Ppc64le */ => 0x8000 | 0x4000, // O_NOFOLLOW | O_DIRECTORY (arm, arm64, powerpc)
            _ => 0x020000 | 0x010000, // O_NOFOLLOW | O_DIRECTORY (asm-generic)
        };
    }

    /// <summary>
    /// Whether an errno from the open above means the path was a symlink (ELOOP) or not a directory
    /// (ENOTDIR). ELOOP differs between Linux and Darwin.
    /// </summary>
    private static bool IsSymlinkOrNotADirectoryErrno(int errno)
    {
        const int enotdir = 20;
        int eloop = RuntimeInformation.IsOSPlatform(OSPlatform.OSX) ? 62 : 40;
        return errno == enotdir || errno == eloop;
    }

    /// <summary>
    /// Returns macOS's per-user temporary directory, e.g. "/var/folders/&lt;xx&gt;/&lt;...&gt;/T/", read
    /// through confstr(_CS_DARWIN_USER_TEMP_DIR) rather than the TMPDIR environment variable.
    /// </summary>
    /// <remarks>
    /// TMPDIR is normally seeded from the same source, but nothing stops another process in the same
    /// session from repointing it first, so it is not trusted here. confstr asks the OS directly, the same
    /// way NSTemporaryDirectory() does.
    /// </remarks>
    private static string GetMacUserTempPath()
    {
        // _CS_DARWIN_USER_TEMP_DIR, from <unistd.h> on macOS.
        const int csDarwinUserTempDir = 65537;

        try
        {
            // Called once with no buffer to ask confstr how large one needs to be.
            var requiredSize = NativeConfstr(csDarwinUserTempDir, null, UIntPtr.Zero);
            if (requiredSize == UIntPtr.Zero)
            {
                EqtTrace.Warning("ArtifactProcessingManager.GetMacUserTempPath: confstr reported no value for _CS_DARWIN_USER_TEMP_DIR.");
                return string.Empty;
            }

            var buffer = new byte[checked((int)requiredSize)];
            var written = NativeConfstr(csDarwinUserTempDir, buffer, requiredSize);
            if (written == UIntPtr.Zero)
            {
                EqtTrace.Warning($"ArtifactProcessingManager.GetMacUserTempPath: confstr failed for _CS_DARWIN_USER_TEMP_DIR, errno: {Marshal.GetLastWin32Error()}.");
                return string.Empty;
            }

            // The returned length includes the trailing null terminator that confstr always writes.
            var length = Math.Min(checked((int)written), buffer.Length) - 1;
            return length > 0 ? Encoding.UTF8.GetString(buffer, 0, length) : string.Empty;
        }
        catch (Exception e) when (e is EntryPointNotFoundException or DllNotFoundException)
        {
            EqtTrace.Warning($"ArtifactProcessingManager.GetMacUserTempPath: confstr is unavailable: {e}");
            return string.Empty;
        }
    }

    [DllImport("libc", EntryPoint = "statx", SetLastError = true)]
    private static extern int NativeStatx(int dirFileDescriptor, string pathname, int flags, uint mask, byte[] buffer);

    [DllImport("libc", EntryPoint = "geteuid")]
    private static extern uint NativeGetEuid();

    [DllImport("libc", EntryPoint = "open", SetLastError = true)]
    private static extern int NativeOpen(string pathname, int flags);

    [DllImport("libc", EntryPoint = "close", SetLastError = true)]
    private static extern int NativeClose(int fd);

    [DllImport("libc", EntryPoint = "fchmod", SetLastError = true)]
    private static extern int NativeFchmod(int fd, int mode);

    [DllImport("libc", EntryPoint = "readlink", SetLastError = true)]
    private static extern IntPtr NativeReadLink(string pathname, byte[] buffer, UIntPtr size);

    [DllImport("libc", EntryPoint = "confstr", SetLastError = true)]
    private static extern UIntPtr NativeConfstr(int name, byte[]? buffer, UIntPtr length);
#endif
}