20221013A

Author: hugoalh

CODE_OF_CONDUCT.md

@@ -67,7 +67,7 @@ Please provide as much as you can to help the community leaders for better under
 - Your account's platform (e.g.: GitHub, GitLab, ...).
 - Your account's username (e.g.: `@octocat`).
 - Project's ID or repository URI.
-  - Project's ID is displayed at the top part of Readme (file: `README.md`), below the project display name (i.e.: header), inside a code block.
+  - Project's ID is displayed at the top part of the Readme (file: `README.md`), below the project display name (i.e.: header), inside a code block.
 - Defendants and witnesses.
 - Are defendants include any staffs, moderators, and/or administrators?
   - This can affect who will proceed this complaint.

CONTRIBUTING.md

@@ -39,7 +39,7 @@ To improve the wiki, create an issue.
 
 This project and repository does not have necessary things to do i18ns and/or translations.
 
-If you want to do i18ns and/or translations on the documentations, documents and/or wiki, please see section "[Documentations, Documents & Wiki](#documentations-documents--wiki)".
+If you want to do i18ns and/or translations on the documentations, documents and/or wiki, please see the section "[Documentations, Documents & Wiki](#documentations-documents--wiki)".
 
 ## Issues
 

SECURITY.md

@@ -46,7 +46,7 @@ Please provide as much as you can to help the security vulnerability report supe
 - Your account's platform (e.g.: GitHub, GitLab, ...).
 - Your account's username (e.g.: `@octocat`).
 - Project's ID or repository URI.
-  - Project's ID is displayed at the top part of Readme (file: `README.md`), below the project display name (i.e.: header), inside a code block.
+  - Project's ID is displayed at the top part of the Readme (file: `README.md`), below the project display name (i.e.: header), inside a code block.
 - Affected branches, commits, tags, and/or versions.
   - Versions must be listed as supported.
   - For multiple versions, you can use version range instead.

hugoalh.GitHubActionsToolkit/hugoalh.GitHubActionsToolkit.psd1

@@ -242,7 +242,7 @@
 			ReleaseNotes = '(Please visit https://github.com/hugoalh-studio/ghactions-toolkit-powershell/releases.)'
 
 			# Prerelease string of this module
-			Prerelease = 'beta2'
+			Prerelease = 'beta3'
 
 			# Flag to indicate whether the module requires explicit user acceptance for install/update/save
 			RequireLicenseAcceptance = $False

hugoalh.GitHubActionsToolkit/module/artifact.psm1

@@ -11,19 +11,19 @@ Import-Module -Name (
 .SYNOPSIS
 GitHub Actions - Export Artifact
 .DESCRIPTION
-Export artifact to persist data and/or share with future job in the same workflow.
+Export artifact to persist the data and/or share with the future jobs in the same workflow.
 .PARAMETER Name
 Name of the artifact.
 .PARAMETER Path
-Paths to the files that need to export as artifact.
+Paths of the files that need to export as artifact.
 .PARAMETER LiteralPath
-Literal paths to the files that need to export as artifact.
+Literal paths of the files that need to export as artifact.
 .PARAMETER BaseRoot
 Absolute literal path of the base root directory of the files for control files structure.
 .PARAMETER ContinueOnIssue
-Whether the export should continue in the event of files fail to export; If not set and issue is encountered, export will stop and queued files will not export; The partial artifact availables which include files up until the issue; If set and issue is encountered, the issue file will ignore and skip, and queued files will still export; The partial artifact availables which include everything but exclude issue files.
+Whether the export should continue in the event of files fail to export; If not set and issue is encountered, export will stop and queued files will not export, the partial artifact availables which include files up until the issue; If set and issue is encountered, the issue file will ignore and skip, and queued files will still export, the partial artifact availables which include everything but exclude issue files.
 .PARAMETER RetentionTime
-Duration of the artifact become expire, by days.
+Retention time of the artifact, by days.
 .OUTPUTS
 [PSCustomObject] Metadata of the exported artifact.
 #>
@@ -34,7 +34,7 @@ Function Export-Artifact {
 		[Parameter(Mandatory = $True, Position = 0, ValueFromPipelineByPropertyName = $True)][String]$Name,
 		[Parameter(Mandatory = $True, ParameterSetName = 'Path', Position = 1, ValueFromPipelineByPropertyName = $True)][SupportsWildcards()][Alias('File', 'Files', 'Paths')][String[]]$Path,
 		[Parameter(Mandatory = $True, ParameterSetName = 'LiteralPath', ValueFromPipelineByPropertyName = $True)][Alias('LiteralFile', 'LiteralFiles', 'LiteralPaths', 'LP', 'PSPath', 'PSPaths')][String[]]$LiteralPath,
-		[Parameter(ValueFromPipelineByPropertyName = $True)][Alias('Root')][String]$BaseRoot = $Env:GITHUB_WORKSPACE,
+		[Parameter(ValueFromPipelineByPropertyName = $True)][ValidateScript({ [System.IO.Path]::IsPathRooted($_) -and (Test-Path -LiteralPath $_ -PathType 'Container') }, ErrorMessage = '`{0}` is not an exist and valid GitHub Actions artifact base root!')][Alias('Root')][String]$BaseRoot = $Env:GITHUB_WORKSPACE,
 		[Parameter(ValueFromPipelineByPropertyName = $True)][Alias('ContinueOnError')][Switch]$ContinueOnIssue,
 		[Parameter(ValueFromPipelineByPropertyName = $True)][Alias('RetentionDay')][Byte]$RetentionTime
 	)
@@ -48,12 +48,26 @@ Function Export-Artifact {
 		If ($NoOperation) {
 			Return
 		}
+		Switch ($PSCmdlet.ParameterSetName) {
+			'LiteralPath' {
+				[String[]]$PathsProceed = $LiteralPath |
+					ForEach-Object -Process { [System.IO.Path]::IsPathRooted($_) ? $_ : (Join-Path -Path $BaseRoot -ChildPath $_) }
+			}
+			'Path' {
+				[String[]]$PathsProceed = @()
+				ForEach ($Item In $Path) {
+					Try {
+						$PathsProceed += Resolve-Path -Path ([System.IO.Path]::IsPathRooted($Item) ? $Item : (Join-Path -Path $BaseRoot -ChildPath $Item))
+					}
+					Catch {
+						$PathsProceed += $Item
+					}
+				}
+			}
+		}
 		[Hashtable]$InputObject = @{
 			Name = $Name
-			Path = ($PSCmdlet.ParameterSetName -ieq 'LiteralPath') ? (
-				$LiteralPath |
-					ForEach-Object -Process { [WildcardPattern]::Escape($_) }
-			) : $Path
+			Path = $PathsProceed
 			BaseRoot = $BaseRoot
 			ContinueOnIssue = $ContinueOnIssue.IsPresent
 		}
@@ -69,15 +83,15 @@ Set-Alias -Name 'Save-Artifact' -Value 'Export-Artifact' -Option 'ReadOnly' -Sco
 .SYNOPSIS
 GitHub Actions - Import Artifact
 .DESCRIPTION
-Import artifact that shared data from past job in the same workflow.
+Import artifact that shared the data from the past jobs in the same workflow.
 .PARAMETER Name
 Name of the artifact.
 .PARAMETER CreateSubfolder
-Whether to create a subfolder with artifact name and put data into here.
+Whether to create a subfolder with artifact name and put the data into there.
 .PARAMETER All
-Import all of the artifacts that shared data from past job in the same workflow; Always create subfolders.
+Import all of the artifacts that shared the data from the past jobs in the same workflow; Always create subfolders.
 .PARAMETER Destination
-Absolute literal path(s) of the destination of the artifact(s).
+Absolute literal path of the destination of the artifact(s).
 .OUTPUTS
 [PSCustomObject] Metadata of the imported artifact.
 [PSCustomObject[]] Metadata of the imported artifacts.
@@ -90,7 +104,7 @@ Function Import-Artifact {
 		[Parameter(Mandatory = $True, ParameterSetName = 'Single', Position = 0, ValueFromPipeline = $True, ValueFromPipelineByPropertyName = $True)][String]$Name,
 		[Parameter(ParameterSetName = 'Single', ValueFromPipelineByPropertyName = $True)][Switch]$CreateSubfolder,
 		[Parameter(Mandatory = $True, ParameterSetName = 'All')][Switch]$All,
-		[Parameter(ValueFromPipelineByPropertyName = $True)][Alias('Dest', 'Target')][String]$Destination = $Env:GITHUB_WORKSPACE
+		[Parameter(ValueFromPipelineByPropertyName = $True)][Alias('Dest', 'Path', 'Target')][String]$Destination = $Env:GITHUB_WORKSPACE
 	)
 	Begin {
 		[Boolean]$NoOperation = !(Test-GitHubActionsEnvironment -Artifact)# When the requirements are not fulfill, only stop this function but not others.

hugoalh.GitHubActionsToolkit/module/cache.psm1

@@ -11,9 +11,9 @@ Import-Module -Name (
 .SYNOPSIS
 GitHub Actions - Restore Cache
 .DESCRIPTION
-Restore cache that shared data from past job in the same workflow.
+Restore cache that shared the data from the past jobs in the same workflow.
 .PARAMETER Key
-Key of the cache.
+Keys of the cache.
 .PARAMETER Path
 Paths of the cache.
 .PARAMETER LiteralPath
@@ -24,6 +24,8 @@ Whether to not use Azure Blob SDK to download the cache that stored on the Azure
 Number of parallel downloads of the cache (only for Azure SDK).
 .PARAMETER Timeout
 Maximum time for each download request of the cache, by seconds (only for Azure SDK).
+.PARAMETER SegmentTimeout
+Maximum time for each segment download request of the cache, by minutes; This allows the segment download to get aborted and hence allow the job to proceed with a cache miss.
 .OUTPUTS
 [String] The key of the cache hit.
 #>
@@ -36,30 +38,33 @@ Function Restore-Cache {
 		[Parameter(Mandatory = $True, ParameterSetName = 'LiteralPath', ValueFromPipeline = $True, ValueFromPipelineByPropertyName = $True)][Alias('LiteralFile', 'LiteralFiles', 'LiteralPaths', 'LP', 'PSPath', 'PSPaths')][String[]]$LiteralPath,
 		[Parameter(ValueFromPipelineByPropertyName = $True)][Alias('NoAzureSdk')][Switch]$NotUseAzureSdk,
 		[Parameter(ValueFromPipelineByPropertyName = $True)][ValidateRange(1, 16)][Alias('Concurrency')][Byte]$DownloadConcurrency,
-		[Parameter(ValueFromPipelineByPropertyName = $True)][ValidateRange(5, 900)][UInt16]$Timeout
+		[Parameter(ValueFromPipelineByPropertyName = $True)][ValidateRange(5, 900)][UInt16]$Timeout,
+		[Parameter(ValueFromPipelineByPropertyName = $True)][ValidateRange(1, 360)][UInt16]$SegmentTimeout = 60
 	)
 	Begin {
 		[Boolean]$NoOperation = !(Test-GitHubActionsEnvironment -Cache)# When the requirements are not fulfill, only stop this function but not others.
 		If ($NoOperation) {
 			Write-Error -Message 'Unable to get GitHub Actions cache resources!' -Category 'ResourceUnavailable'
 		}
+		$Env:SEGMENT_DOWNLOAD_TIMEOUT_MINS = $SegmentTimeout.ToString()
 	}
 	Process {
 		If ($NoOperation) {
 			Return
 		}
 		[Hashtable]$InputObject = @{
 			PrimaryKey = $Key[0]
-			RestoreKey = (
-				$Key |
-					Select-Object -SkipIndex 0
-			) ?? @()
 			Path = ($PSCmdlet.ParameterSetName -ieq 'LiteralPath') ? (
 				$LiteralPath |
 					ForEach-Object -Process { [WildcardPattern]::Escape($_) }
 			) : $Path
 			UseAzureSdk = !$NotUseAzureSdk.IsPresent
 		}
+		[String[]]$RestoreKey = $Key |
+			Select-Object -SkipIndex 0
+		If ($RestoreKey.Count -igt 0) {
+			$InputObject.RestoreKey = $RestoreKey
+		}
 		If (!$NotUseAzureSdk.IsPresent) {
 			If ($DownloadConcurrency -igt 0) {
 				$InputObject.DownloadConcurrency = $DownloadConcurrency
@@ -77,7 +82,7 @@ Set-Alias -Name 'Import-Cache' -Value 'Restore-Cache' -Option 'ReadOnly' -Scope
 .SYNOPSIS
 GitHub Actions - Save cache
 .DESCRIPTION
-Save cache to persist data and/or share with future job in the same workflow.
+Save cache to persist the data and/or share with the future jobs in the same workflow.
 .PARAMETER Key
 Key of the cache.
 .PARAMETER Path
@@ -96,8 +101,8 @@ Function Save-Cache {
 	[OutputType([String])]
 	Param (
 		[Parameter(Mandatory = $True, Position = 0, ValueFromPipelineByPropertyName = $True)][Alias('Name')][String]$Key,
-		[Parameter(Mandatory = $True, ParameterSetName = 'Path', Position = 1, ValueFromPipeline = $True, ValueFromPipelineByPropertyName = $True)][SupportsWildcards()][Alias('File', 'Files', 'Paths')][String[]]$Path,
-		[Parameter(Mandatory = $True, ParameterSetName = 'LiteralPath', ValueFromPipeline = $True, ValueFromPipelineByPropertyName = $True)][Alias('LiteralFile', 'LiteralFiles', 'LiteralPaths', 'LP', 'PSPath', 'PSPaths')][String[]]$LiteralPath,
+		[Parameter(Mandatory = $True, ParameterSetName = 'Path', Position = 1, ValueFromPipelineByPropertyName = $True)][SupportsWildcards()][Alias('File', 'Files', 'Paths')][String[]]$Path,
+		[Parameter(Mandatory = $True, ParameterSetName = 'LiteralPath', ValueFromPipelineByPropertyName = $True)][Alias('LiteralFile', 'LiteralFiles', 'LiteralPaths', 'LP', 'PSPath', 'PSPaths')][String[]]$LiteralPath,
 		[Parameter(ValueFromPipelineByPropertyName = $True)][ValidateRange(1, 1MB)][Alias('ChunkSize', 'ChunkSizes', 'UploadChunkSize')][UInt32]$UploadChunkSizes,
 		[Parameter(ValueFromPipelineByPropertyName = $True)][ValidateRange(1, 16)][Alias('Concurrency')][Byte]$UploadConcurrency
 	)
@@ -129,27 +134,6 @@ Function Save-Cache {
 	}
 }
 Set-Alias -Name 'Export-Cache' -Value 'Save-Cache' -Option 'ReadOnly' -Scope 'Local'
-<#
-.SYNOPSIS
-GitHub Actions (Private) - Test Cache Key
-.DESCRIPTION
-Test the key of the GitHub Actions cache whether is valid.
-.PARAMETER InputObject
-Key of the GitHub Actions cache that need to test.
-.OUTPUTS
-[Boolean] Test result.
-#>
-Function Test-CacheKey {
-	[CmdletBinding()]
-	[OutputType([Boolean])]
-	Param (
-		[Parameter(Mandatory = $True, Position = 0, ValueFromPipeline = $True)][Alias('Input', 'Object')][String]$InputObject
-	)
-	Process {
-		$InputObject.Length -ile 512 -and $InputObject -imatch '^[^,\n\r]+$' |
-			Write-Output
-	}
-}
 Export-ModuleMember -Function @(
 	'Restore-Cache',
 	'Save-Cache'

hugoalh.GitHubActionsToolkit/module/command-base.psm1

@@ -6,7 +6,6 @@ Import-Module -Name (
 	) |
 		ForEach-Object -Process { Join-Path -Path $PSScriptRoot -ChildPath $_ }
 ) -Prefix 'GitHubActions' -Scope 'Local'
-[String[]]$GitHubActionsFileCommandTokensUsed = @()
 <#
 .SYNOPSIS
 GitHub Actions (Private) - Format Command Parameter Value
@@ -50,8 +49,11 @@ Function Format-CommandValue {
 			Write-Output
 	}
 }
-Set-Alias -Name 'Format-CommandContent' -Value 'Format-CommandValue' -Option 'ReadOnly' -Scope 'Local'
-Set-Alias -Name 'Format-CommandMessage' -Value 'Format-CommandValue' -Option 'ReadOnly' -Scope 'Local'
+@(
+	'Format-CommandContent',
+	'Format-CommandMessage'
+) |
+	Set-Alias -Value 'Format-CommandValue' -Option 'ReadOnly' -Scope 'Local'
 <#
 .SYNOPSIS
 GitHub Actions - Write Command
@@ -106,19 +108,22 @@ Function Write-FileCommand {
 		[Parameter(Mandatory = $True, Position = 2, ValueFromPipelineByPropertyName = $True)][String]$Value
 	)
 	Process {
-		Add-Content -LiteralPath $LiteralPath -Value $(
-			If ($Value -imatch '^.+$') {
-				Write-Output -InputObject "$($Name)=$($Value)"
+		If ($Value -imatch '^.+$') {
+			Add-Content -LiteralPath $LiteralPath -Value "$Name=$Value" -Confirm:$False -Encoding 'UTF8NoBOM'
+		}
+		Else {
+			[String]$ItemRaw = "$Name=$Value" -ireplace '\r?\n', ''
+			Do {
+				[String]$Token = New-GitHubActionsRandomToken -Length 16
 			}
-			Else {
-				Do {
-					[String]$Token = New-GitHubActionsRandomToken -Length 64
-				}
-				While ( $Token -iin $GitHubActionsFileCommandTokensUsed )
-				$Script:GitHubActionsFileCommandTokensUsed += $Token
-				Write-Output -InputObject "$Name<<$Token`n$($Value -ireplace '\r?\n', "`n")`n$Token"
-			}
-		) -Confirm:$False -Encoding 'UTF8NoBOM'
+			While ( $ItemRaw -imatch [RegEx]::Escape($Token) )
+			@(
+				"$Name<<$Token",
+				$Value -ireplace '\r?\n', "`n",
+				$Token
+			) |
+				Add-Content -LiteralPath $LiteralPath -Confirm:$False -Encoding 'UTF8NoBOM'
+		}
 	}
 }
 Export-ModuleMember -Function @(