personaEngine2/tests/Unit/RetryPolicy.Tests.ps1

#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }

<#
    NFR-003 and the OTD-007 retry table.

    The non-retryable cases carry the operational weight. A 403 retried five times per
    account turns an instant authorization failure into a long, expensive one, and
    hammers a tenant that is already refusing - so status extraction has to work even
    when the code appears only in the exception message, which is how
    Invoke-MgGraphRequest reports several of its failures.
#>

BeforeAll {
    $repoRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
    . (Join-Path $repoRoot 'tests/TestHelpers.ps1')
    foreach ($file in (Get-PersonaSourceFile -RepoRoot $repoRoot)) { . $file }

    function New-StatusError {
        param([int] $Status, [string] $Reason = 'Failed')
        [System.Management.Automation.ErrorRecord]::new(
            [System.Exception]::new("Response status code does not indicate success: $Status ($Reason)."),
            'GraphError', [System.Management.Automation.ErrorCategory]::InvalidResult, $null)
    }
}

Describe 'Status extraction from an error record' {

    It 'reads a status embedded only in the message' {
        Get-PersonaGraphStatusCode -ErrorRecord (New-StatusError -Status 403 -Reason 'Forbidden') | Should -Be 403
    }

    It 'reads each status the retry table names' {
        foreach ($status in @(400, 401, 403, 404, 409, 429, 500, 502, 503, 504)) {
            Get-PersonaGraphStatusCode -ErrorRecord (New-StatusError -Status $status) | Should -Be $status
        }
    }

    It 'returns null for a transport failure with no status anywhere' {
        $record = [System.Management.Automation.ErrorRecord]::new(
            [System.Exception]::new('The operation was canceled.'),
            'Timeout', [System.Management.Automation.ErrorCategory]::OperationTimeout, $null)

        Get-PersonaGraphStatusCode -ErrorRecord $record | Should -BeNullOrEmpty
    }

    It 'does not mistake an unrelated three-digit number for a status' {
        $record = [System.Management.Automation.ErrorRecord]::new(
            [System.Exception]::new('Processed 250 objects before the connection dropped.'),
            'Transport', [System.Management.Automation.ErrorCategory]::ConnectionError, $null)

        # 250 is outside the HTTP error range, so it is not treated as a status and
        # the failure stays retryable - which is the correct answer for a dropped
        # connection.
        Get-PersonaGraphStatusCode -ErrorRecord $record | Should -BeNullOrEmpty
    }
}

Describe 'Retry policy (OTD-007)' {

    # One It per status rather than a loop: Should -Invoke counts across the whole It
    # block, so a loop would accumulate calls and the second iteration would fail on
    # the first one's arithmetic.
    It 'never retries status <_>' -ForEach @(400, 401, 403, 404, 409) {
        $status = $_
        Mock Invoke-MgGraphRequest { throw "Response status code does not indicate success: $status (Failed)." }.GetNewClosure()

        { Invoke-PersonaGraphRequest -Uri '/v1.0/users' -BaseDelayMs 1 } | Should -Throw

        Should -Invoke Invoke-MgGraphRequest -Times 1 -Exactly -Because "status $status is a client-side defect that retrying would only hide"
    }

    It 'retries a retryable status up to the attempt limit' {
        Mock Invoke-MgGraphRequest { throw 'Response status code does not indicate success: 503 (Service Unavailable).' }

        { Invoke-PersonaGraphRequest -Uri '/v1.0/users' -MaxAttempts 3 -BaseDelayMs 1 } | Should -Throw

        Should -Invoke Invoke-MgGraphRequest -Times 3 -Exactly
    }

    It 'retries a transport failure that carries no status' {
        Mock Invoke-MgGraphRequest { throw 'The operation was canceled.' }

        { Invoke-PersonaGraphRequest -Uri '/v1.0/users' -MaxAttempts 2 -BaseDelayMs 1 } | Should -Throw

        Should -Invoke Invoke-MgGraphRequest -Times 2 -Exactly
    }

    It 'returns as soon as an attempt succeeds' {
        $script:attempts = 0
        Mock Invoke-MgGraphRequest {
            $script:attempts++
            if ($script:attempts -lt 3) { throw 'Response status code does not indicate success: 429 (Too Many Requests).' }
            @{ value = @('ok') }
        }

        $result = Invoke-PersonaGraphRequest -Uri '/v1.0/users' -BaseDelayMs 1

        $result['value'] | Should -Be @('ok')
        Should -Invoke Invoke-MgGraphRequest -Times 3 -Exactly
    }

    It 'passes the body through unchanged as JSON' {
        # SC-005 depends on this: the body a test captures must be the body sent.
        $script:sentBody = $null
        Mock Invoke-MgGraphRequest { $script:sentBody = $Body; @{} }

        $null = Invoke-PersonaGraphRequest -Uri '/v1.0/users/x' -Method 'PATCH' -Body @{ 'extension_x_Persona' = 'Employee' }

        ($script:sentBody | ConvertFrom-Json).'extension_x_Persona' | Should -Be 'Employee'
    }
}