[Artifacts] @actions/artifact list artifact functionality + download interface setup (#1495)

* actions/artifact preparation for download-artifact v4

* Test matrix strategy

* Fix needs dependency

* Improve list artifact test

* Fix typo

* Fix variables

* Cleanup download-all interfaces

* Fix tsc error

* Simplify to just name instead of artifactName

* Simplify to id instead of ArtifactId

* PR cleanup

packages/artifact/src/internal/client.ts

@@ -1,18 +1,27 @@
-import {UploadOptions} from './upload/upload-options'
-import {UploadResponse} from './upload/upload-response'
-import {uploadArtifact} from './upload/upload-artifact'
 import {warning} from '@actions/core'
 import {isGhes} from './shared/config'
+import {
+  UploadOptions,
+  UploadResponse,
+  DownloadArtifactOptions,
+  GetArtifactResponse,
+  ListArtifactsResponse,
+  DownloadArtifactResponse
+} from './shared/interfaces'
+import {uploadArtifact} from './upload/upload-artifact'
+import {downloadArtifact} from './download/download-artifact'
+import {getArtifact} from './find/get-artifact'
+import {listArtifacts} from './find/list-artifacts'
 
 export interface ArtifactClient {
   /**
    * Uploads an artifact
    *
-   * @param name the name of the artifact, required
-   * @param files a list of absolute or relative paths that denote what files should be uploaded
-   * @param rootDirectory an absolute or relative file path that denotes the root parent directory of the files being uploaded
-   * @param options extra options for customizing the upload behavior
-   * @returns single UploadInfo object
+   * @param name The name of the artifact, required
+   * @param files A list of absolute or relative paths that denote what files should be uploaded
+   * @param rootDirectory An absolute or relative file path that denotes the root parent directory of the files being uploaded
+   * @param options Extra options for customizing the upload behavior
+   * @returns single UploadResponse object
    */
   uploadArtifact(
     name: string,
@@ -21,7 +30,64 @@ export interface ArtifactClient {
     options?: UploadOptions
   ): Promise<UploadResponse>
 
-  // TODO Download functionality
+  /**
+   * Lists all artifacts that are part of a workflow run.
+   *
+   * This calls the public List-Artifacts API https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28#list-workflow-run-artifacts
+   * Due to paginated responses from the public API. This function will return at most 1000 artifacts per workflow run (100 per page * maximum 10 calls)
+   *
+   * @param workflowRunId The workflow run id that the artifact belongs to
+   * @param repositoryOwner The owner of the repository that the artifact belongs to
+   * @param repositoryName The name of the repository that the artifact belongs to
+   * @param token A token with the appropriate permission to the repository to list artifacts
+   * @returns ListArtifactResponse object
+   */
+  listArtifacts(
+    workflowRunId: number,
+    repositoryOwner: string,
+    repositoryName: string,
+    token: string
+  ): Promise<ListArtifactsResponse>
+
+  /**
+   * Finds an artifact by name given a repository and workflow run id.
+   *
+   * This calls the public List-Artifacts API with a name filter https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28#list-workflow-run-artifacts
+   * @actions/artifact > 2.0.0 does not allow for creating multiple artifacts with the same name in the same workflow run.
+   * It is possible to have multiple artifacts with the same name in the same workflow run by using old versions of upload-artifact (v1,v2 and v3) or @actions/artifact < v2.0.0
+   * If there are multiple artifacts with the same name in the same workflow run this function will return the first artifact that matches the name.
+   *
+   * @param artifactName The name of the artifact to find
+   * @param workflowRunId The workflow run id that the artifact belongs to
+   * @param repositoryOwner The owner of the repository that the artifact belongs to
+   * @param repositoryName The name of the repository that the artifact belongs to
+   * @param token A token with the appropriate permission to the repository to find the artifact
+   */
+  getArtifact(
+    artifactName: string,
+    workflowRunId: number,
+    repositoryOwner: string,
+    repositoryName: string,
+    token: string
+  ): Promise<GetArtifactResponse>
+
+  /**
+   * Downloads an artifact and unzips the content
+   *
+   * @param artifactId The name of the artifact to download
+   * @param repositoryOwner The owner of the repository that the artifact belongs to
+   * @param repositoryName The name of the repository that the artifact belongs to
+   * @param token A token with the appropriate permission to the repository to download the artifact
+   * @param options Extra options that allow for the customization of the download behavior
+   * @returns single DownloadArtifactResponse object
+   */
+  downloadArtifact(
+    artifactId: number,
+    repositoryOwner: string,
+    repositoryName: string,
+    token: string,
+    options?: DownloadArtifactOptions
+  ): Promise<DownloadArtifactResponse>
 }
 
 export class Client implements ArtifactClient {
@@ -33,7 +99,7 @@ export class Client implements ArtifactClient {
   }
 
   /**
-   * Uploads an artifact
+   * Upload Artifact
    */
   async uploadArtifact(
     name: string,
@@ -43,7 +109,7 @@ export class Client implements ArtifactClient {
   ): Promise<UploadResponse> {
     if (isGhes()) {
       warning(
-        `@actions/artifact v2 and upload-artifact v4 are not currently supported on GHES.`
+        `@actions/artifact v2.0.0+ and upload-artifact@v4+ are not currently supported on GHES.`
       )
       return {
         success: false
@@ -56,9 +122,132 @@ export class Client implements ArtifactClient {
       warning(
         `Artifact upload failed with error: ${error}.
 
-Errors can be temporary, so please try again and optionally run the action with debug enabled for more information.
+Errors can be temporary, so please try again and optionally run the action with debug mode enabled for more information.
 
-If the error persists, please check whether Actions is running normally at [https://githubstatus.com](https://www.githubstatus.com).`
+If the error persists, please check whether Actions is operating normally at [https://githubstatus.com](https://www.githubstatus.com).`
+      )
+      return {
+        success: false
+      }
+    }
+  }
+
+  /**
+   * Download Artifact
+   */
+  async downloadArtifact(
+    artifactId: number,
+    repositoryOwner: string,
+    repositoryName: string,
+    token: string,
+    options?: DownloadArtifactOptions
+  ): Promise<DownloadArtifactResponse> {
+    if (isGhes()) {
+      warning(
+        `@actions/artifact v2.0.0+ and download-artifact@v4+ are not currently supported on GHES.`
+      )
+      return {
+        success: false
+      }
+    }
+
+    try {
+      return downloadArtifact(
+        artifactId,
+        repositoryOwner,
+        repositoryName,
+        token,
+        options
+      )
+    } catch (error) {
+      warning(
+        `Artifact download failed with error: ${error}.
+
+Errors can be temporary, so please try again and optionally run the action with debug mode enabled for more information.
+
+If the error persists, please check whether Actions and API requests are operating normally at [https://githubstatus.com](https://www.githubstatus.com).`
+      )
+
+      return {
+        success: false
+      }
+    }
+  }
+
+  /**
+   * List Artifacts
+   */
+  async listArtifacts(
+    workflowRunId: number,
+    repositoryOwner: string,
+    repositoryName: string,
+    token: string
+  ): Promise<ListArtifactsResponse> {
+    if (isGhes()) {
+      warning(
+        `@actions/artifact v2.0.0+ and download-artifact@v4+ are not currently supported on GHES.`
+      )
+      return {
+        artifacts: []
+      }
+    }
+
+    try {
+      return listArtifacts(
+        workflowRunId,
+        repositoryOwner,
+        repositoryName,
+        token
+      )
+    } catch (error: unknown) {
+      warning(
+        `Listing Artifacts failed with error: ${error}.
+
+Errors can be temporary, so please try again and optionally run the action with debug mode enabled for more information.
+
+If the error persists, please check whether Actions and API requests are operating normally at [https://githubstatus.com](https://www.githubstatus.com).`
+      )
+
+      return {
+        artifacts: []
+      }
+    }
+  }
+
+  /**
+   * Get Artifact
+   */
+  async getArtifact(
+    artifactName: string,
+    workflowRunId: number,
+    repositoryOwner: string,
+    repositoryName: string,
+    token: string
+  ): Promise<GetArtifactResponse> {
+    if (isGhes()) {
+      warning(
+        `@actions/artifact v2.0.0+ and download-artifact@v4+ are not currently supported on GHES.`
+      )
+      return {
+        success: false
+      }
+    }
+
+    try {
+      return getArtifact(
+        artifactName,
+        workflowRunId,
+        repositoryOwner,
+        repositoryName,
+        token
+      )
+    } catch (error: unknown) {
+      warning(
+        `Fetching Artifact failed with error: ${error}.
+
+Errors can be temporary, so please try again and optionally run the action with debug mode enabled for more information.
+
+If the error persists, please check whether Actions and API requests are operating normally at [https://githubstatus.com](https://www.githubstatus.com).`
       )
       return {
         success: false

packages/artifact/src/internal/download/download-artifact.ts

@@ -0,0 +1,14 @@
+import {
+  DownloadArtifactOptions,
+  DownloadArtifactResponse
+} from '../shared/interfaces'
+
+export async function downloadArtifact(
+  artifactId: number,
+  repositoryOwner: string,
+  repositoryName: string,
+  token: string,
+  options?: DownloadArtifactOptions
+): Promise<DownloadArtifactResponse> {
+  throw new Error('Not implemented')
+}

packages/artifact/src/internal/find/get-artifact.ts

@@ -0,0 +1,11 @@
+import {GetArtifactResponse} from '../shared/interfaces'
+
+export async function getArtifact(
+  artifactName: string,
+  workflowRunId: number,
+  repositoryOwner: string,
+  repositoryName: string,
+  token: string
+): Promise<GetArtifactResponse> {
+  throw new Error('Not implemented')
+}

packages/artifact/src/internal/find/list-artifacts.ts

@@ -0,0 +1,115 @@
+import {info, warning, debug} from '@actions/core'
+import {getOctokit} from '@actions/github'
+import {ListArtifactsResponse, Artifact} from '../shared/interfaces'
+import {getUserAgentString} from '../shared/user-agent'
+import {RetryOptions, getRetryOptions} from './retry-options'
+import {defaults as defaultGitHubOptions} from '@actions/github/lib/utils'
+import {requestLog} from '@octokit/plugin-request-log'
+import {retry} from '@octokit/plugin-retry'
+import {RequestRequestOptions} from '@octokit/types'
+
+type Options = {
+  log?: Console
+  userAgent?: string
+  previews?: string[]
+  retry?: RetryOptions
+  request?: RequestRequestOptions
+}
+
+// Limiting to 1000 for perf reasons
+const maximumArtifactCount = 1000
+const paginationCount = 100
+const maxNumberOfPages = maximumArtifactCount / paginationCount
+const maxRetryNumber = 5
+const exemptStatusCodes = [400, 401, 403, 404, 422] // https://github.com/octokit/plugin-retry.js/blob/9a2443746c350b3beedec35cf26e197ea318a261/src/index.ts#L14
+
+export async function listArtifacts(
+  workflowRunId: number,
+  repositoryOwner: string,
+  repositoryName: string,
+  token: string
+): Promise<ListArtifactsResponse> {
+  info(`Fetching artifact list for workflow run ${workflowRunId} in repository ${repositoryOwner}/${repositoryName}`)
+
+  const artifacts: Artifact[] = []
+  const [retryOpts, requestOpts] = getRetryOptions(
+    maxRetryNumber,
+    exemptStatusCodes,
+    defaultGitHubOptions
+  )
+
+  const opts: Options = {
+    log: undefined,
+    userAgent: getUserAgentString(),
+    previews: undefined,
+    retry: retryOpts,
+    request: requestOpts
+  }
+
+  const github = getOctokit(token, opts, retry, requestLog)
+
+  let currentPageNumber = 1
+  const {data: listArtifactResponse} =
+    await github.rest.actions.listWorkflowRunArtifacts({
+      owner: repositoryOwner,
+      repo: repositoryName,
+      run_id: workflowRunId,
+      per_page: paginationCount,
+      page: currentPageNumber
+    })
+
+  let numberOfPages = Math.ceil(
+    listArtifactResponse.total_count / paginationCount
+  )
+  const totalArtifactCount = listArtifactResponse.total_count
+  if (totalArtifactCount > maximumArtifactCount) {
+    warning(
+      `Workflow run ${workflowRunId} has more than 1000 artifacts. Results will be incomplete as only the first ${maximumArtifactCount} artifacts will be returned`
+    )
+    numberOfPages = maxNumberOfPages
+  }
+
+  // Iterate over the first page
+  listArtifactResponse.artifacts.forEach(artifact => {
+    artifacts.push({
+      name: artifact.name,
+      id: artifact.id,
+      url: artifact.url,
+      size: artifact.size_in_bytes
+    })
+  })
+
+  // Iterate over any remaining pages
+  for (
+    currentPageNumber;
+    currentPageNumber < numberOfPages;
+    currentPageNumber++
+  ) {
+    currentPageNumber++
+    debug(`Fetching page ${currentPageNumber} of artifact list`)
+
+    const {data: listArtifactResponse} =
+      await github.rest.actions.listWorkflowRunArtifacts({
+        owner: repositoryOwner,
+        repo: repositoryName,
+        run_id: workflowRunId,
+        per_page: paginationCount,
+        page: currentPageNumber
+      })
+
+    listArtifactResponse.artifacts.forEach(artifact => {
+      artifacts.push({
+        name: artifact.name,
+        id: artifact.id,
+        url: artifact.url,
+        size: artifact.size_in_bytes
+      })
+    })
+  }
+
+  info(`Finished fetching artifact list`)
+
+  return {
+    artifacts: artifacts
+  }
+}

packages/artifact/src/internal/find/retry-options.ts

@@ -0,0 +1,44 @@
+import * as core from '@actions/core'
+import {OctokitOptions} from '@octokit/core/dist-types/types'
+import {RequestRequestOptions} from '@octokit/types'
+
+export type RetryOptions = {
+  doNotRetry?: number[]
+  enabled?: boolean
+}
+
+export function getRetryOptions(
+  retries: number,
+  exemptStatusCodes: number[],
+  defaultOptions: OctokitOptions
+): [RetryOptions, RequestRequestOptions | undefined] {
+  if (retries <= 0) {
+    return [{enabled: false}, defaultOptions.request]
+  }
+
+  const retryOptions: RetryOptions = {
+    enabled: true
+  }
+
+  if (exemptStatusCodes.length > 0) {
+    retryOptions.doNotRetry = exemptStatusCodes
+  }
+
+  // The GitHub type has some defaults for `options.request`
+  // see: https://github.com/actions/toolkit/blob/4fbc5c941a57249b19562015edbd72add14be93d/packages/github/src/utils.ts#L15
+  // We pass these in here so they are not overridden.
+  const requestOptions: RequestRequestOptions = {
+    ...defaultOptions.request,
+    retries
+  }
+
+  core.debug(
+    `GitHub client configured with: (retries: ${
+      requestOptions.retries
+    }, retry-exempt-status-code: ${
+      retryOptions.doNotRetry ?? 'octokit default: [400, 401, 403, 404, 422]'
+    })`
+  )
+
+  return [retryOptions, requestOptions]
+}

packages/artifact/src/internal/shared/interfaces.ts

@@ -0,0 +1,123 @@
+/*****************************************************************************
+ *                                                                           *
+ *                            UploadArtifact                                 *
+ *                                                                           *
+ *****************************************************************************/
+export interface UploadResponse {
+  /**
+   * Denotes if an artifact was successfully uploaded
+   */
+  success: boolean
+
+  /**
+   * Total size of the artifact in bytes. Not provided if no artifact was uploaded
+   */
+  size?: number
+
+  /**
+   * The id of the artifact that was created. Not provided if no artifact was uploaded
+   * This ID can be used as input to other APIs to download, delete or get more information about an artifact: https://docs.github.com/en/rest/actions/artifacts
+   */
+  id?: number
+}
+
+export interface UploadOptions {
+  /**
+   * Duration after which artifact will expire in days.
+   *
+   * By default artifact expires after 90 days:
+   * https://docs.github.com/en/actions/configuring-and-managing-workflows/persisting-workflow-data-using-artifacts#downloading-and-deleting-artifacts-after-a-workflow-run-is-complete
+   *
+   * Use this option to override the default expiry.
+   *
+   * Min value: 1
+   * Max value: 90 unless changed by repository setting
+   *
+   * If this is set to a greater value than the retention settings allowed, the retention on artifacts
+   * will be reduced to match the max value allowed on server, and the upload process will continue. An
+   * input of 0 assumes default retention setting.
+   */
+  retentionDays?: number
+}
+
+/*****************************************************************************
+ *                                                                           *
+ *                              GetArtifact                                  *
+ *                                                                           *
+ *****************************************************************************/
+
+export interface GetArtifactResponse {
+  /**
+   * If an artifact was found
+   */
+  success: boolean
+
+  /**
+   * Metadata about the artifact that was found
+   */
+  artifact?: Artifact
+}
+
+/*****************************************************************************
+ *                                                                           *
+ *                             ListArtifact                                  *
+ *                                                                           *
+ *****************************************************************************/
+export interface ListArtifactsResponse {
+  /**
+   * A list of artifacts that were found
+   */
+  artifacts: Artifact[]
+}
+
+/*****************************************************************************
+ *                                                                           *
+ *                           DownloadArtifact                                *
+ *                                                                           *
+ *****************************************************************************/
+export interface DownloadArtifactResponse {
+  /**
+   * If the artifact download was successful
+   */
+  success: boolean
+}
+
+export interface DownloadArtifactOptions {
+  /**
+   * Denotes where the artifact will be downloaded to. If not specified then the artifact is download to GITHUB_WORKSPACE
+   */
+  path?: string
+
+  /**
+   * Specifies if a root folder with the artifact name is created for the artifact that is downloaded
+   * Zip contents are expanded into this folder. Defaults to false if not specified
+   * */
+  createArtifactFolder?: boolean
+}
+
+/*****************************************************************************
+ *                                                                           *
+ *                                 Shared                                    *
+ *                                                                           *
+ *****************************************************************************/
+export interface Artifact {
+  /**
+   * The name of the artifact
+   */
+  name: string
+
+  /**
+   * The ID of the artifact
+   */
+  id: number
+
+  /**
+   * The URL of the artifact
+   */
+  url: string
+
+  /**
+   * The size of the artifact in bytes
+   */
+  size: number
+}

packages/artifact/src/internal/shared/user-agent.ts

@@ -0,0 +1,8 @@
+var packageJson = require('../../../package.json')
+
+/**
+ * Ensure that this User Agent String is used in all HTTP calls so that we can monitor telemetry between different versions of this package
+ */
+export function getUserAgentString(): string {
+  return `@actions/artifact-${packageJson.version}`
+}

packages/artifact/src/internal/upload/blob-upload.ts

@@ -70,18 +70,21 @@ export async function uploadZipToBlobStorage(
     hashStream.end()
     md5Hash = hashStream.read() as string
     core.info(`MD5 hash of uploaded artifact zip is ${md5Hash}`)
-
   } catch (error) {
-    core.warning(`Failed to upload artifact zip to blob storage, error: ${error}`)
+    core.warning(
+      `Failed to upload artifact zip to blob storage, error: ${error}`
+    )
     return {
       isSuccess: false
     }
   }
 
   if (uploadByteCount === 0) {
-    core.warning(`No data was uploaded to blob storage. Reported upload byte count is 0`)
+    core.warning(
+      `No data was uploaded to blob storage. Reported upload byte count is 0`
+    )
     return {
-        isSuccess: false,
+      isSuccess: false
     }
   }
 

packages/artifact/src/internal/upload/upload-artifact.ts

@@ -1,6 +1,5 @@
 import * as core from '@actions/core'
-import {UploadOptions} from './upload-options'
-import {UploadResponse} from './upload-response'
+import {UploadOptions, UploadResponse} from '../shared/interfaces'
 import {getExpiration} from './retention'
 import {validateArtifactName} from './path-and-artifact-name-validation'
 import {createArtifactTwirpClient} from '../shared/artifact-twirp-client'

packages/artifact/src/internal/upload/upload-options.ts

@@ -1,18 +0,0 @@
-export interface UploadOptions {
-  /**
-   * Duration after which artifact will expire in days.
-   *
-   * By default artifact expires after 90 days:
-   * https://docs.github.com/en/actions/configuring-and-managing-workflows/persisting-workflow-data-using-artifacts#downloading-and-deleting-artifacts-after-a-workflow-run-is-complete
-   *
-   * Use this option to override the default expiry.
-   *
-   * Min value: 1
-   * Max value: 90 unless changed by repository setting
-   *
-   * If this is set to a greater value than the retention settings allowed, the retention on artifacts
-   * will be reduced to match the max value allowed on server, and the upload process will continue. An
-   * input of 0 assumes default retention setting.
-   */
-  retentionDays?: number
-}

packages/artifact/src/internal/upload/upload-response.ts

@@ -1,17 +0,0 @@
-export interface UploadResponse {
-  /**
-   * Denotes if an artifact was successfully uploaded
-   */
-  success: boolean
-
-  /**
-   * Total size of the artifact in bytes. Not provided if no artifact was uploaded
-   */
-  size?: number
-
-  /**
-   * The id of the artifact that was created. Not provided if no artifact was uploaded
-   * This ID can be used as input to other APIs to download, delete or get more information about an artifact: https://docs.github.com/en/rest/actions/artifacts
-   */
-  id?: number
-}