Bump module version to 1.5.4 and update Invoke-GiteaFileDownload to handle URL encoded characters in file names. Update pester tests to account for changes.

PS-GiteaUtilities/PS-GiteaUtilities.psd1

@@ -12,7 +12,7 @@
 RootModule = 'PS-GiteaUtilities.psm1'
 
 # Version number of this module.
-ModuleVersion = '1.4.4'
+ModuleVersion = '1.5.4'
 
 # Supported PSEditions
 # CompatiblePSEditions = @()

PS-GiteaUtilities/PS-GiteaUtilities.psm1

@@ -207,7 +207,7 @@ Function Get-GiteaFileContent {
                     Content = $content
                     Size = $fileContent.size
                     SHA = $fileContent.sha
-                    Success = $true
+                    Result = 'Success'
                     Error = $null
                 }
             }
@@ -218,7 +218,7 @@ Function Get-GiteaFileContent {
                     Content = $null
                     Size = $null
                     SHA = $null
-                    Success = $false
+                    Result = 'Failure'
                     Error = $_.Exception.Message
                 }
             }
@@ -337,6 +337,9 @@ Function Invoke-GiteaFileDownload {
     If used with outputPath, treats the outputPath as the base directory to append the relative path to.
     Cannot be used with outputName.
 
+    .PARAMETER OverwriteByHash
+    A switch parameter to overwrite the file if it exists based on its hash.
+    
     .PARAMETER force
     A switch parameter to force overwriting of an existing file at the output path.
 
@@ -344,6 +347,10 @@ Function Invoke-GiteaFileDownload {
     The type of the item to download (file, dir, lfs). This parameter is typically used with pipeline input from Get-GiteaChildItem.
     Directories will be skipped with a verbose message.
 
+    .PARAMETER sha
+    The SHA of the file to download. This parameter is typically used with pipeline input from Get-GiteaChildItem.
+    Can be combined with OverwriteByHash to overwrite an existing file if the hashes do not match.
+
     .EXAMPLE
     # Example 1: Download a file to the current directory
     Invoke-GiteaFileDownload -downloadURL "https://gitea.example.com/api/v1/repos/owner/repo/raw/path/to/file.txt" -token "your_token"
@@ -375,9 +382,12 @@ Function Invoke-GiteaFileDownload {
         [Parameter(ValueFromPipelineByPropertyName)]
         [string]$outputName,
         [switch]$PreserveRelativePath,
+        [switch]$OverwriteByHash,
         [switch]$force,
         [Parameter(ValueFromPipelineByPropertyName)]
-        [string]$type
+        [string]$type,
+        [Parameter(ValueFromPipelineByPropertyName)]
+        [string]$sha
     )
 
     begin {
@@ -424,8 +434,8 @@ Function Invoke-GiteaFileDownload {
             return [PSCustomObject]@{
                 SourceURL = $downloadURL
                 Type = $type
-                Success = $true
-                Error = "Skipped - item is a directory"
+                Result = 'Skipped'
+                Error = $null
                 Timestamp = Get-Date
                 FileSize = $null
             }
@@ -438,7 +448,7 @@ Function Invoke-GiteaFileDownload {
             return [PSCustomObject]@{
                 SourceURL = $downloadURL
                 Type = $type
-                Success = $false
+                Result = 'Failure'
                 Error = $errorMsg
                 Timestamp = Get-Date
                 FileSize = $null
@@ -461,9 +471,13 @@ Function Invoke-GiteaFileDownload {
             # Everything after the branch + 1 segment is considered the file path with the last segment being the file name
             $branchIndex = [Array]::IndexOf($pathSegments, "branch") + 2
             $DownloadFilePath = $pathSegments[$branchIndex..($pathSegments.Length - 2)] -join '/'
+            # Replace any URL encoded characters in the file name
             $DownloadFileName = $pathSegments[-1]
         }
 
+        $DownloadFilePath = [System.Uri]::UnescapeDataString($DownloadFilePath)
+        $DownloadFileName = [System.Uri]::UnescapeDataString($DownloadFileName)
+                
         if ($PreserveRelativePath -and $outputPath) {
             # If PreserveRelativePath is used, set up the directory structure
             Write-Verbose "Preserving relative path structure for: $DownloadFileName"
@@ -509,18 +523,37 @@ Function Invoke-GiteaFileDownload {
             Path = $fileOutputPath
             SourceURL = $downloadURL
             Type = "file"
-            Success = $false
+            Result = $null
             Error = $null
             Timestamp = Get-Date
             FileSize = $null
         }
 
         if((Test-Path -Path $fileOutputPath -PathType Leaf) -and (-not $force)) {
+            # Check if OverwriteByHash is set
+            if ($OverwriteByHash) {
+                Write-Verbose "OverwriteByHash is set; checking file hash for existing file: $fileOutputPath"
+                $existingFileHash = (Get-FileHash -Path $fileOutputPath -Algorithm SHA256).Hash
+                $downloadFileHash = $sha
+                
+                if ($existingFileHash -eq $downloadFileHash) {
+                    Write-Host "The file '$fileOutputPath' already exists and hashes match. Skipping download."
+                    $result.Result = 'Skipped'
+                    return $result
+                }
+                else {
+                    Write-Host "The file '$fileOutputPath' already exists but hashes do not match and OverwriteByHash is set; overwriting file."
+
+                }
+            }
+            else {
+                $result.Result = 'Skipped'
                 $errorMsg = "The file '$fileOutputPath' already exists. Use the -Force switch to overwrite the file."
                 Write-Error $errorMsg
                 $result.Error = $errorMsg
                 return $result
             }
+        }
 
         try {
             # Create the directory structure if it doesn't exist
@@ -544,10 +577,11 @@ Function Invoke-GiteaFileDownload {
                 $result.FileSize = $fileInfo.Length
             }
             
-            $result.Success = $true
+            $result.Result = 'Success'
             return $result
         }
         catch {
+            $result.Result = 'Failure'
             $errorMsg = "Failed to download file from Gitea: $_"
             Write-Error $errorMsg
             $result.Error = $errorMsg
@@ -754,7 +788,7 @@ Function Get-GiteaChildItem {
                         size = $item.size
                         sha = $item.sha
                         downloadURL = $item.download_url
-                        Success = $true
+                        Result = 'Success'
                         Error = $null
                         Level = 0
                     }
@@ -837,7 +871,7 @@ Function Get-GiteaChildItem {
                                     size = $subItem.size
                                     sha = $subItem.sha
                                     downloadURL = $subItem.download_url
-                                    Success = $true
+                                    Result = 'Success'
                                     Error = $null
                                     Level = $currentLevel
                                 }
@@ -884,7 +918,7 @@ Function Get-GiteaChildItem {
                     size = $null
                     sha = $null
                     downloadURL = $null
-                    Success = $false
+                    Result = 'Failure'
                     Error = $_.Exception.Message
                     Level = 0
                 }

Tests/Get-GiteaFileContent.Tests.ps1

@@ -21,7 +21,7 @@ Describe 'Get-GiteaFileContent' {
             $result = Get-GiteaFileContent -repoOwner 'user' -repoName 'repo' -filePath 'README.md' -token 'abc123'
 
             $result | Should -Not -BeNullOrEmpty
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
             $result.Content | Should -Be ([System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes('Hello World')))
         }
 
@@ -29,7 +29,7 @@ Describe 'Get-GiteaFileContent' {
             $result = Get-GiteaFileContent -repoOwner 'user' -repoName 'repo' -filePath 'README.md' -token 'abc123' -decode
 
             $result | Should -Not -BeNullOrEmpty
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
             $result.Content | Should -Be 'Hello World'
         }
     }
@@ -73,7 +73,7 @@ Describe 'Get-GiteaFileContent' {
         It 'Should capture error and mark result as unsuccessful' {
             $result = Get-GiteaFileContent -repoOwner 'user' -repoName 'repo' -filePath 'badfile.ps1' -token 'abc123'
     
-            $result.Success | Should -Be $false
+            $result.Result | Should -Be 'Failure'
             $result.Error | Should -Match 'API call failed'
         }
     }
@@ -103,7 +103,7 @@ Describe 'Get-GiteaFileContent' {
             $result = Get-GiteaFileContent -repoOwner 'user' -repoName 'repo' -filePath 'testfile.txt' -token 'abc123'
     
             $result | Should -Not -BeNullOrEmpty
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
             $result.Content | Should -Be ([System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes('Hello from API!')))
         }
     
@@ -111,7 +111,7 @@ Describe 'Get-GiteaFileContent' {
             $result = Get-GiteaFileContent -repoOwner 'user' -repoName 'repo' -filePath 'testfile.txt' -token 'abc123' -decode
     
             $result | Should -Not -BeNullOrEmpty
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
             $result.Content | Should -Be 'Hello from API!'
         }
     }

Tests/Invoke-GiteaFileDownload.Tests.ps1

@@ -46,51 +46,59 @@ Describe 'Invoke-GiteaFileDownload' {
 
     Context 'When all parameters are valid' {
         It 'Should download a file successfully' {
-            $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/raw/path/to/file.txt' -token 'abc123'
+            $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/test/example/raw/branch/dev/path/to/file.txt' -token 'abc123'
 
             $result | Should -Not -BeNullOrEmpty
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
             $result.Path | Should -Match 'file\.txt$'
         }
     }
 
     Context 'When specifying an outputPath' {
         It 'Should create a path based on outputPath' {
-            $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/raw/path/to/file.txt' `
+            $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/test/example/raw/branch/dev/path/to/file.txt' `
             -outputPath 'docs/manual/' -token 'abc123'
 
             $result.Path | Should -Match 'docs[\\/]+manual[\\/]+file\.txt$'
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
         }
     }
 
     Context 'When specifying an outputName' {
         It 'Should download file and name it based on outputName' {
-            $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/raw/path/to/file.txt' `
+            $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/test/example/raw/branch/dev/path/to/file.txt' `
             -outputName 'newfile.txt' -token 'abc123'
 
             $result.Path | Should -Match 'newfile\.txt$'
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
         }
     }
 
     Context 'When specifying an outputName and outputPath' {
         It 'Should download file and name it based on outputName' {
-            $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/raw/path/to/file.txt' `
+            $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/test/example/raw/branch/dev/path/to/file.txt' `
             -outputPath 'docs/manual/' -outputName 'newfile.txt' -token 'abc123'
 
             $result.Path | Should -Match 'docs[\\/]+manual[\\/]+newfile\.txt$'
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
         }
     }
 
     Context 'When using -PreserveRelativePath' {
         It 'Should preserve the relative path structure' {
-            $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/raw/path/to/file.txt' `
+            $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/test/example/raw/branch/dev/path/to/file.txt' `
             -PreserveRelativePath -token 'abc123'
 
             $result.Path | Should -Match 'path[\\/]+to[\\/]+file\.txt$'
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
+        }
+
+        It 'Should ensure the outputPath does not contain any URL encoding' {
+            $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/test/example/raw/branch/dev/Client%20Files/Certificates/file name.txt' `
+            -PreserveRelativePath -token 'abc123'
+
+            $result.Path | Should -Match 'Client[ ]Files[\\/]+Certificates[\\/]+file name\.txt$'
+            $result.Result | Should -Be 'Success'
         }
     }
 
@@ -98,8 +106,7 @@ Describe 'Invoke-GiteaFileDownload' {
         It 'Should skip items with type = dir' {
             $result = Invoke-GiteaFileDownload -outputPath 'docs/' -type 'dir' -token 'abc123'
 
-            $result.Success | Should -Be $true
-            $result.Error | Should -Match 'Skipped'
+            $result.Result | Should -Be 'Skipped'
         }
     }
 
@@ -114,10 +121,9 @@ Describe 'Invoke-GiteaFileDownload' {
         }
 
         It 'Should not overwrite existing file without Force' {
-            $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/raw/path/to/existingfile.txt' -token 'abc123'
+            $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/test/example/raw/branch/dev/path/to/existingfile.txt' -token 'abc123'
 
-            $result.Success | Should -Be $false
-            $result.Error | Should -Match 'already exists'
+            $result.Result | Should -Be 'Skipped'
         }
     }
 
@@ -143,9 +149,9 @@ Describe 'Invoke-GiteaFileDownload' {
         }
     
         It 'Should capture error and mark download as failed' {
-            $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/raw/path/to/badfile.txt' -token 'abc123'
+            $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/test/example/raw/branch/dev/path/to/badfile.txt' -token 'abc123'
     
-            $result.Success | Should -Be $false
+            $result.Result | Should -Be 'Failure'
             $result.Error | Should -Match 'Failed to download'
         }
     }