Run npm format

* Check for newlines and carriage return in artifact paths and name

* Fix linting issue

* Update comments

* Add comment about spacing

* Remove extra space

.eslintignore

@@ -1,3 +1,4 @@
 node_modules/
 packages/*/node_modules/
-packages/*/lib/
+packages/*/lib/
+packages/glob/__tests__/_temp

.eslintrc.json

@@ -1,28 +1,42 @@
 {
   "plugins": ["jest", "@typescript-eslint"],
-  "extends": ["plugin:github/es6"],
+  "extends": ["plugin:github/recommended"],
   "parser": "@typescript-eslint/parser",
   "parserOptions": {
     "ecmaVersion": 9,
     "sourceType": "module",
-    "project": "./tsconfig.json"
+    "project": "./tsconfig.eslint.json"
   },
   "rules": {
     "eslint-comments/no-use": "off",
+    "github/no-then": "off",
     "import/no-namespace": "off",
+    "no-shadow": "off",
     "no-unused-vars": "off",
+    "no-undef": "off",
     "@typescript-eslint/no-unused-vars": "error",
     "@typescript-eslint/explicit-member-accessibility": ["error", {"accessibility": "no-public"}],
     "@typescript-eslint/no-require-imports": "error",
     "@typescript-eslint/array-type": "error",
     "@typescript-eslint/await-thenable": "error",
-    "@typescript-eslint/ban-ts-ignore": "error",
+    "@typescript-eslint/ban-ts-comment": "error",
     "camelcase": "off",
-    "@typescript-eslint/camelcase": "error",
-    "@typescript-eslint/class-name-casing": "error",
+    "@typescript-eslint/camelcase": "off",
+    "@typescript-eslint/consistent-type-assertions": "off",
     "@typescript-eslint/explicit-function-return-type": ["error", {"allowExpressions": true}],
     "@typescript-eslint/func-call-spacing": ["error", "never"],
-    "@typescript-eslint/generic-type-naming": ["error", "^[A-Z][A-Za-z]*$"],
+    "@typescript-eslint/naming-convention": [
+      "error",
+      {
+        "format": null,
+        "filter": {
+          // you can expand this regex as you find more cases that require quoting that you want to allow
+          "regex": "^[A-Z][A-Za-z]*$",
+          "match": true
+        },
+        "selector": "memberLike"
+      }
+    ],
     "@typescript-eslint/no-array-constructor": "error",
     "@typescript-eslint/no-empty-interface": "error",
     "@typescript-eslint/no-explicit-any": "error",
@@ -32,7 +46,6 @@
     "@typescript-eslint/no-misused-new": "error",
     "@typescript-eslint/no-namespace": "error",
     "@typescript-eslint/no-non-null-assertion": "warn",
-    "@typescript-eslint/no-object-literal-type-assertion": "error",
     "@typescript-eslint/no-unnecessary-qualifier": "error",
     "@typescript-eslint/no-unnecessary-type-assertion": "error",
     "@typescript-eslint/no-useless-constructor": "error",
@@ -40,7 +53,6 @@
     "@typescript-eslint/prefer-for-of": "warn",
     "@typescript-eslint/prefer-function-type": "warn",
     "@typescript-eslint/prefer-includes": "error",
-    "@typescript-eslint/prefer-interface": "error",
     "@typescript-eslint/prefer-string-starts-ends-with": "error",
     "@typescript-eslint/promise-function-async": "error",
     "@typescript-eslint/require-array-sort-compare": "error",

.github/CONTRIBUTING.md

@@ -1,4 +1,23 @@
-## Development
+# Contributions
+
+We welcome contributions in the form of issues and pull requests.  We view the contributions and process as the same for internal and external contributors.
+
+## Issues
+
+Log issues for both bugs and enhancement requests.  Logging issues are important for the open community.
+
+Issues in this repository should be for the toolkit packages. General feedback for GitHub Actions should be filed in the [community forums.](https://github.community/t5/GitHub-Actions/bd-p/actions) Runner specific issues can be filed [in the runner repository](https://github.com/actions/runner).
+
+## Enhancements and Feature Requests
+
+We ask that before significant effort is put into code changes, that we have agreement on taking the change before time is invested in code changes. 
+
+1. Create a feature request. 
+2. When we agree to take the enhancement, create an ADR to agree on the details of the change.
+
+An ADR is an Architectural Decision Record.  This allows consensus on the direction forward and also serves as a record of the change and motivation. [Read more here](../docs/adrs/README.md).
+
+## Development Life Cycle
 
 This repository uses [Lerna](https://github.com/lerna/lerna#readme) to manage multiple packages. Read the documentation there to begin contributing.
 
@@ -37,4 +56,4 @@ This will ask you some questions about the new package. Start with `0.0.0` as th
 }
 ```
 
-3. Start developing 😄 and open a pull request.
+3. Start developing 😄.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,46 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+Thank you 🙇‍♀ for wanting to create an issue in this repository. Before you do, please ensure you are filing the issue in the right place. Issues should only be opened on if the issue **relates to code in this repository**.  
+
+* If you have found a security issue [please submit it here](https://hackerone.com/github)
+* If you have questions about writing workflows or action files, then please [visit the GitHub Community Forum's Actions Board](https://github.community/t5/GitHub-Actions/bd-p/actions)
+* If you are having an issue or question about GitHub Actions then please [contact customer support](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/about-github-actions#contacting-support)
+
+If your issue is relevant to this repository, please include the information below:
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/enhancement_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature Request
+about: Create a request to help us improve
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+Thank you 🙇‍♀ for wanting to create an issue in this repository. Before you do, please ensure you are filing the issue in the right place. Issues should only be opened on if the issue **relates to code in this repository**.  
+
+* If you have found a security issue [please submit it here](https://hackerone.com/github)
+* If you have questions about writing workflows or action files, then please [visit the GitHub Community Forum's Actions Board](https://github.community/t5/GitHub-Actions/bd-p/actions)
+* If you are having an issue or question about GitHub Actions then please [contact customer support](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/about-github-actions#contacting-support)
+
+If your issue is relevant to this repository, please include the information below:
+
+**Describe the enhancement**
+A clear and concise description of what the features or enhancement you need.
+
+**Code Snippet**
+If applicable, add a code snippet to show the api enhancement.
+
+**Additional information**
+Add any other context about the feature here.

.github/workflows/artifact-tests.yml

@@ -0,0 +1,88 @@
+name: artifact-unit-tests
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+  pull_request:
+    paths-ignore:
+      - '**.md'
+
+jobs:
+  build:
+    name: Build
+
+    strategy:
+      matrix:
+        runs-on: [ubuntu-latest, windows-latest, macos-latest]
+      fail-fast: false
+
+    runs-on: ${{ matrix.runs-on }}
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Set Node.js 12.x
+      uses: actions/setup-node@v1
+      with:
+        node-version: 12.x
+
+    # In order to upload & download artifacts from a shell script, certain env variables need to be set that are only available in the
+    # node context. This runs a local action that gets and sets the necessary env variables that are needed
+    - name: Set env variables
+      uses: ./packages/artifact/__tests__/ci-test-action/
+
+    # Need root node_modules because certain npm packages like jest are configured for the entire repository and it won't be possible
+    # without these to just compile the artifacts package
+    - name: Install root npm packages
+      run: npm ci
+
+    - name: Compile artifact package
+      run: |
+        npm ci
+        npm run tsc
+      working-directory: packages/artifact
+    
+    - name: Set artifact file contents
+      shell: bash
+      run: |
+        echo "non-gzip-artifact-content=hello" >> $GITHUB_ENV
+        echo "gzip-artifact-content=Some large amount of text that has a compression ratio that is greater than 100%. If greater than 100%, gzip is used to upload the file" >> $GITHUB_ENV
+
+    - name: Create files that will be uploaded
+      run: |
+        mkdir artifact-path 
+        echo ${{ env.non-gzip-artifact-content }} > artifact-path/world.txt
+        echo ${{ env.gzip-artifact-content }} > artifact-path/gzip.txt
+
+    # We're using node -e to call the functions directly available in the @actions/artifact package
+    - name: Upload artifacts using uploadArtifact()
+      run: |
+        node -e "Promise.resolve(require('./packages/artifact/lib/artifact-client').create().uploadArtifact('my-artifact-1',['artifact-path/world.txt'], '${{ github.workspace }}'))"
+        node -e "Promise.resolve(require('./packages/artifact/lib/artifact-client').create().uploadArtifact('my-artifact-2',['artifact-path/gzip.txt'], '${{ github.workspace }}'))"
+
+    - name: Download artifacts using downloadArtifact()
+      run: |
+        mkdir artifact-1-directory
+        node -e "Promise.resolve(require('./packages/artifact/lib/artifact-client').create().downloadArtifact('my-artifact-1','artifact-1-directory'))"
+        mkdir artifact-2-directory
+        node -e "Promise.resolve(require('./packages/artifact/lib/artifact-client').create().downloadArtifact('my-artifact-2','artifact-2-directory'))"
+    
+    - name: Verify downloadArtifact()
+      shell: bash
+      run: |
+        packages/artifact/__tests__/test-artifact-file.sh "artifact-1-directory/artifact-path/world.txt" "${{ env.non-gzip-artifact-content }}"
+        packages/artifact/__tests__/test-artifact-file.sh "artifact-2-directory/artifact-path/gzip.txt" "${{ env.gzip-artifact-content }}"
+
+    - name: Download artifacts using downloadAllArtifacts()
+      run: |
+        mkdir multi-artifact-directory
+        node -e "Promise.resolve(require('./packages/artifact/lib/artifact-client').create().downloadAllArtifacts('multi-artifact-directory'))"
+
+    - name: Verify downloadAllArtifacts()
+      shell: bash
+      run: |
+        packages/artifact/__tests__/test-artifact-file.sh "multi-artifact-directory/my-artifact-1/artifact-path/world.txt" "${{ env.non-gzip-artifact-content }}"
+        packages/artifact/__tests__/test-artifact-file.sh "multi-artifact-directory/my-artifact-2/artifact-path/gzip.txt" "${{ env.gzip-artifact-content }}"

.github/workflows/audit.yml

@@ -0,0 +1,39 @@
+name: toolkit-audit
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+  pull_request:
+    paths-ignore:
+      - '**.md'
+
+jobs:
+
+  build:
+    name: Audit
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Set Node.js 12.x
+      uses: actions/setup-node@v1
+      with:
+        node-version: 12.x
+
+    - name: npm install
+      run: npm install
+
+    - name: Bootstrap
+      run: npm run bootstrap
+
+    - name: audit tools
+      # `|| npm audit` to pretty-print the output if vulnerabilies are found after filtering.
+      run: npm audit --audit-level=moderate --json | scripts/audit-allow-list || npm audit --audit-level=moderate
+
+    - name: audit packages
+      run: npm run audit-all

.github/workflows/cache-tests.yml

@@ -0,0 +1,91 @@
+name: cache-unit-tests
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+  pull_request:
+    paths-ignore:
+      - '**.md'
+
+jobs:
+  build:
+    name: Build
+
+    strategy:
+      matrix:
+        runs-on: [ubuntu-latest, windows-latest, macOS-latest]
+      fail-fast: false
+
+    runs-on: ${{ matrix.runs-on }}
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Set Node.js 12.x
+      uses: actions/setup-node@v1
+      with:
+        node-version: 12.x
+
+    # In order to save & restore cache from a shell script, certain env variables need to be set that are only available in the
+    # node context. This runs a local action that gets and sets the necessary env variables that are needed
+    - name: Set env variables
+      uses: ./packages/cache/__tests__/__fixtures__/
+
+    # Need root node_modules because certain npm packages like jest are configured for the entire repository and it won't be possible
+    # without these to just compile the cache package
+    - name: Install root npm packages
+      run: npm ci
+
+    - name: Compile cache package
+      run: |
+        npm ci
+        npm run tsc
+      working-directory: packages/cache
+    
+    - name: Generate files in working directory
+      shell: bash
+      run: packages/cache/__tests__/create-cache-files.sh ${{ runner.os }} test-cache
+
+    - name: Generate files outside working directory
+      shell: bash
+      run: packages/cache/__tests__/create-cache-files.sh ${{ runner.os }} ~/test-cache
+
+    # We're using node -e to call the functions directly available in the @actions/cache package
+    - name: Save cache using saveCache()
+      run: |
+        node -e "Promise.resolve(require('./packages/cache/lib/cache').saveCache(['test-cache','~/test-cache'],'test-${{ runner.os }}-${{ github.run_id }}'))"
+
+    - name: Delete cache folders before restoring
+      shell: bash
+      run: |
+        rm -rf test-cache
+        rm -rf ~/test-cache
+
+    - name: Restore cache using restoreCache() with http-client
+      run: |
+        node -e "Promise.resolve(require('./packages/cache/lib/cache').restoreCache(['test-cache','~/test-cache'],'test-${{ runner.os }}-${{ github.run_id }}',[],{useAzureSdk: false}))"
+
+    - name: Verify cache restored with http-client
+      shell: bash
+      run: |
+        packages/cache/__tests__/verify-cache-files.sh ${{ runner.os }} test-cache
+        packages/cache/__tests__/verify-cache-files.sh ${{ runner.os }} ~/test-cache
+
+    - name: Delete cache folders before restoring
+      shell: bash
+      run: |
+        rm -rf test-cache
+        rm -rf ~/test-cache
+
+    - name: Restore cache using restoreCache() with Azure SDK
+      run: |
+        node -e "Promise.resolve(require('./packages/cache/lib/cache').restoreCache(['test-cache','~/test-cache'],'test-${{ runner.os }}-${{ github.run_id }}'))"
+
+    - name: Verify cache restored with Azure SDK
+      shell: bash
+      run: |
+        packages/cache/__tests__/verify-cache-files.sh ${{ runner.os }} test-cache
+        packages/cache/__tests__/verify-cache-files.sh ${{ runner.os }} ~/test-cache

.github/workflows/codeql.yml

@@ -0,0 +1,37 @@
+name: "Code Scanning - Action"
+
+on:
+  push:
+    branches:    
+      - main
+  pull_request:
+  schedule:
+    - cron: '0 0 * * 0'
+
+jobs:
+  CodeQL-Build:
+
+    strategy:
+      fail-fast: false
+
+
+    # CodeQL runs on ubuntu-latest, windows-latest, and macos-latest
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      with:
+         languages: javascript
+        
+    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below)
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1

.github/workflows/releases.yml

@@ -0,0 +1,75 @@
+name: Publish NPM
+
+on:
+  workflow_dispatch:
+    inputs:
+      package:
+        required: true
+        description: 'core, artifact, cache, exec, github, glob, io, tool-cache'
+ 
+jobs:
+  test:
+    runs-on: macos-latest
+
+    steps:
+      - name: setup repo
+        uses: actions/checkout@v2
+
+      - name: verify package exists
+        run: ls packages/${{ github.event.inputs.package }}
+        
+      - name: npm install
+        run: npm install
+        
+      - name: bootstrap
+        run: npm run bootstrap
+        
+      - name: build
+        run: npm run build
+        
+      - name: test
+        run: npm run test
+
+      - name: pack
+        run: npm pack
+        working-directory: packages/${{ github.event.inputs.package }}
+        
+      - name: upload artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: ${{ github.event.inputs.package }}
+          path: packages/${{ github.event.inputs.package }}/*.tgz
+        
+  publish:
+    runs-on: macos-latest
+    needs: test
+    environment: npm-publish
+    steps:
+        
+      - name: download artifact
+        uses: actions/download-artifact@v2
+        with:
+          name: ${{ github.event.inputs.package }}
+
+      - name: setup authentication
+        run: echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" >> .npmrc
+        env: 
+          NPM_TOKEN: ${{ secrets.TOKEN }}
+
+      - name: publish
+        run: npm publish *.tgz
+
+      - name: notify slack on failure
+        if: failure()
+        run: |
+          curl -X POST -H 'Content-type: application/json' --data '{"text":":pb__failed: Failed to publish a new version of ${{ github.event.inputs.package }}"}' $SLACK_WEBHOOK
+        env: 
+          SLACK_WEBHOOK: ${{ secrets.SLACK }}
+        
+      - name: notify slack on success
+        if: success()
+        run: |
+          curl -X POST -H 'Content-type: application/json' --data '{"text":":dance: Successfully published a new version of ${{ github.event.inputs.package }}"}' $SLACK_WEBHOOK
+        env: 
+          SLACK_WEBHOOK: ${{ secrets.SLACK }}
+        

.github/workflows/unit-tests.yml

@@ -0,0 +1,51 @@
+name: toolkit-unit-tests
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+  pull_request:
+    paths-ignore:
+      - '**.md'
+
+jobs:
+
+  build:
+    name: Build
+
+    strategy:
+      matrix:
+        runs-on: [ubuntu-latest, macos-latest, windows-latest]
+      fail-fast: false
+
+    runs-on: ${{ matrix.runs-on }}
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Set Node.js 12.x
+      uses: actions/setup-node@v1
+      with:
+        node-version: 12.x
+
+    - name: npm install
+      run: npm install
+
+    - name: Bootstrap
+      run: npm run bootstrap
+
+    - name: Compile
+      run: npm run build
+
+    - name: npm test
+      run: npm test
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+
+    - name: Lint
+      run: npm run lint
+
+    - name: Format
+      run: npm run format-check

.github/workflows/update-github.yaml

@@ -0,0 +1,45 @@
+name: "UpdateOctokit"
+
+on:
+  workflow_dispatch:
+
+jobs:
+  UpdateOctokit:
+    runs-on: ubuntu-latest
+    if: ${{ github.repository_owner == 'actions' }}
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+    - name: Update Octokit
+      working-directory: packages/github 
+      run: |
+        npx npm-check-updates -u --dep prod
+        npm install
+    - name: Check Status
+      id: status
+      working-directory: packages/github 
+      run: | 
+        if [[ "$(git status --porcelain)" != "" ]]; then 
+        echo "::set-output name=createPR::true"
+        git config --global user.email "github-actions@github.com"
+        git config --global user.name "github-actions[bot]"
+        git checkout -b bots/updateGitHubDependencies-${{github.run_number}}
+        git add .
+        git commit -m "Update Dependencies"
+        git push --set-upstream origin bots/updateGitHubDependencies-${{github.run_number}}
+        fi
+    - name: Create PR
+      if: ${{steps.status.outputs.createPR}}
+      uses: actions/github-script@v2
+      with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          script: |
+            github.pulls.create(
+            {
+              base: "main",
+              owner: "${{github.repository_owner}}",
+              repo: "toolkit",
+              title: "Update Octokit dependencies",
+              body: "Update Octokit dependencies",
+              head: "bots/updateGitHubDependencies-${{github.run_number}}"
+            })

.github/workflows/workflow.yml

@@ -1,58 +0,0 @@
-name: Main workflow
-on: [push]
-jobs:
-  Ubuntu:
-    name: Run Ubuntu
-    runs-on: ubuntu-latest
-    steps:
-    - name: Checkout
-      uses: actions/checkout@master
-
-    - name: Set Node.js 10.x
-      uses: actions/setup-node@master
-      with:
-        version: 10.x
-
-    - name: npm install
-      run: npm install
-
-    - name: Bootstrap
-      run: npm run bootstrap
-
-    - name: Compile
-      run: npm run build
-
-    - name: npm test
-      run: npm test
-
-    - name: Lint
-      run: npm run lint
-
-    - name: Format
-      run: npm run format-check
-  Windows:
-    name: Run Windows
-    runs-on: windows-latest
-    steps:
-    - name: Checkout
-      uses: actions/checkout@master
-
-    - name: Set Node.js 10.x
-      uses: actions/setup-node@master
-      with:
-        version: 10.x
-
-    - name: npm install
-      run: npm install
-
-    - name: Bootstrap
-      run: npm run bootstrap
-
-    - name: Compile
-      run: npm run build
-
-    # TODO: This currently ignores exec due to issues with Node and spawning on Windows, which I think is exacerbated by Jest.
-    # It doesn't seem to affect behavior in actions themselves, just when testing with Jest.
-    # See other similar issues here: https://github.com/nodejs/node/issues/25484
-    - name: npm test
-      run: npm run test-ci

.gitignore

@@ -1,4 +1,7 @@
 node_modules/
 packages/*/node_modules/
 packages/*/lib/
-packages/*/__tests__/_temp/
+packages/*/__tests__/_temp/
+.DS_Store
+*.xar
+packages/*/audit.json

CODEOWNERS

@@ -0,0 +1,4 @@
+* @actions/actions-runtime
+
+/packages/artifact/   @actions/actions-service
+/packages/cache/      @actions/actions-service

CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when
+an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official
+project e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event. Representation of
+a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at opensource@github.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

LICENSE.md

@@ -1,3 +1,5 @@
+The MIT License (MIT)
+
 Copyright 2019 GitHub
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

README.md

@@ -3,35 +3,216 @@
   <img src="res/at-logo.png">
 </p>
 
-## Toolkit
+<p align="center">
+  <a href="https://github.com/actions/toolkit/actions?query=workflow%3Atoolkit-unit-tests"><img alt="Toolkit unit tests status" src="https://github.com/actions/toolkit/workflows/toolkit-unit-tests/badge.svg"></a>
+  <a href="https://github.com/actions/toolkit/actions?query=workflow%3Atoolkit-audit"><img alt="Toolkit audit status" src="https://github.com/actions/toolkit/workflows/toolkit-audit/badge.svg"></a>
+</p>
 
-The toolkit provides a set of packages to make creating actions easier and drive consistency.
+
+## GitHub Actions Toolkit
+
+The GitHub Actions ToolKit provides a set of packages to make creating actions easier.
+
+<br/>
+<h3 align="center">Get started with the <a href="https://github.com/actions/javascript-action">javascript-action template</a>!</h3>
+<br/>
 
 ## Packages
 
-The toolkit provides four separate packages.  Since actions are run by pulling actions from the github graph, dependencies including the packages are vendored into your action.
+:heavy_check_mark: [@actions/core](packages/core)
 
-| Package | Description |
-| ------- | ----------- |
-| [@actions/core](packages/core) | Core functions for getting inputs, setting outputs, setting results, logging, secrets and environment variables |
-| [@actions/exec](packages/exec) | Functions necessary for running tools on the command line |
-| [@actions/io](packages/io) | Core functions for CLI filesystem scenarios |
-| [@actions/tool-cache](packages/tool-cache) | Functions necessary for downloading and caching tools |
+Provides functions for inputs, outputs, results, logging, secrets and variables. Read more [here](packages/core)
+
+```bash
+$ npm install @actions/core
+```
+<br/>
+
+:runner: [@actions/exec](packages/exec)
+
+Provides functions to exec cli tools and process output. Read more [here](packages/exec)
+
+```bash
+$ npm install @actions/exec
+```
+<br/>
+
+:ice_cream: [@actions/glob](packages/glob)
+
+Provides functions to search for files matching glob patterns. Read more [here](packages/glob)
+
+```bash
+$ npm install @actions/glob
+```
+<br/>
+
+:pencil2: [@actions/io](packages/io)
+
+Provides disk i/o functions like cp, mv, rmRF, which etc. Read more [here](packages/io)
+
+```bash
+$ npm install @actions/io
+```
+<br/>
+
+:hammer: [@actions/tool-cache](packages/tool-cache)
+
+Provides functions for downloading and caching tools.  e.g. setup-* actions. Read more [here](packages/tool-cache)
+
+See @actions/cache for caching workflow dependencies.
+
+```bash
+$ npm install @actions/tool-cache
+```
+<br/>
+
+:octocat: [@actions/github](packages/github)
+
+Provides an Octokit client hydrated with the context that the current action is being run in. Read more [here](packages/github)
+
+```bash
+$ npm install @actions/github
+```
+<br/>
+
+:floppy_disk: [@actions/artifact](packages/artifact)
+
+Provides functions to interact with actions artifacts. Read more [here](packages/artifact)
+
+```bash
+$ npm install @actions/artifact
+```
+<br/>
+
+:dart: [@actions/cache](packages/cache)
+
+Provides functions to cache dependencies and build outputs to improve workflow execution time. Read more [here](packages/cache)
+
+```bash
+$ npm install @actions/cache
+```
+<br/>
 
 ## Creating an Action with the Toolkit
 
-Actions are units of work which can either run in a container or on the host machine.
+:question: [Choosing an action type](docs/action-types.md)
 
-[Choosing an action type](docs/action-types.md): Outlines the differences and why you would want to create a host or a container based action.
+Outlines the differences and why you would want to create a JavaScript or a container based action.
+<br/>
+<br/>
 
-[JavaScript Action Walthrough](docs/node12-action.md): Create an action which runs on the host using the toolkit
+:curly_loop: [Versioning](docs/action-versioning.md)
 
-[Docker Action Walkthrough](docs/container-action.md): Create an action that is delivered as a container and run with docker.
+Actions are downloaded and run from the GitHub graph of repos.  This contains guidance for versioning actions and safe releases.
+<br/>
+<br/>
 
-[Docker Action Walkthrough with Octokit](docs/container-action-toolkit.md): Create an action that is delivered as a container which uses the toolkit.  This example uses the GitHub context to construct an Octokit client.
+:warning: [Problem Matchers](docs/problem-matchers.md)
 
-[Versioning](docs/action-versioning.md): Recommendations on versioning, releases and tagging your action.
+Problem Matchers are a way to scan the output of actions for a specified regex pattern and surface that information prominently in the UI.
+<br/>
+<br/>
+
+:warning: [Proxy Server Support](docs/proxy-support.md)
+
+Self-hosted runners can be configured to run behind proxy servers.
+<br/>
+<br/>
+
+<h3><a href="https://github.com/actions/hello-world-javascript-action">Hello World JavaScript Action</a></h3>
+
+Illustrates how to create a simple hello world javascript action.
+
+```javascript
+...
+  const nameToGreet = core.getInput('who-to-greet');
+  console.log(`Hello ${nameToGreet}!`);
+...
+```
+<br/>
+
+<h3><a href="https://github.com/actions/javascript-action">JavaScript Action Walkthrough</a></h3>
+
+Walkthrough and template for creating a JavaScript Action with tests, linting, workflow, publishing, and versioning.
+
+```javascript
+async function run() {
+  try {
+    const ms = core.getInput('milliseconds');
+    console.log(`Waiting ${ms} milliseconds ...`)
+    ...
+```
+```javascript
+PASS ./index.test.js
+  ✓ throws invalid number
+  ✓ wait 500 ms
+  ✓ test runs
+
+Test Suites: 1 passed, 1 total
+Tests:       3 passed, 3 total
+```
+<br/>
+
+<h3><a href="https://github.com/actions/typescript-action">TypeScript Action Walkthrough</a></h3>
+
+Walkthrough creating a TypeScript Action with compilation, tests, linting, workflow, publishing, and versioning.
+
+```javascript
+import * as core from '@actions/core';
+
+async function run() {
+  try {
+    const ms = core.getInput('milliseconds');
+    console.log(`Waiting ${ms} milliseconds ...`)
+    ...
+```
+```javascript
+PASS ./index.test.js
+  ✓ throws invalid number
+  ✓ wait 500 ms
+  ✓ test runs
+
+Test Suites: 1 passed, 1 total
+Tests:       3 passed, 3 total
+```
+<br/>
+<br/>
+
+<h3><a href="docs/container-action.md">Docker Action Walkthrough</a></h3>
+
+Create an action that is delivered as a container and run with docker.
+
+```docker
+FROM alpine:3.10
+COPY LICENSE README.md /
+COPY entrypoint.sh /entrypoint.sh
+ENTRYPOINT ["/entrypoint.sh"]
+```
+<br/>
+
+<h3><a href="https://github.com/actions/container-toolkit-action">Docker Action Walkthrough with Octokit</a></h3>
+
+Create an action that is delivered as a container which uses the toolkit.  This example uses the GitHub context to construct an Octokit client.
+
+```docker
+FROM node:slim
+COPY . .
+RUN npm install --production
+ENTRYPOINT ["node", "/lib/main.js"]
+```
+```javascript
+const myInput = core.getInput('myInput');
+core.debug(`Hello ${myInput} from inside a container`);
+
+const context = github.context;
+console.log(`We can even get context data, like the repo: ${context.repo.repo}`)
+```
+<br/>
 
 ## Contributing
 
-We welcome contributions.  See [how to contribute](docs/contribute.md).
+We welcome contributions.  See [how to contribute](.github/CONTRIBUTING.md).
+
+## Code of Conduct
+
+See [our code of conduct](CODE_OF_CONDUCT.md).

SECURITY.md

@@ -0,0 +1,3 @@
+If you discover a security issue in this repo, please submit it through the [GitHub Security Bug Bounty](https://hackerone.com/github)
+
+Thanks for helping make GitHub Actions safe for everyone.

docs/action-debugging.md

@@ -0,0 +1,31 @@
+# Debugging
+If the job logs do not provide enough detail on why a job may be failing, some other options exist to assist with troubleshooting.
+
+## Step Debug Logs
+This is the primary way for customers to debug job failures caused by failed steps.
+
+Step debug logs increase the verbosity of a job's logs during and after a job's execution to assist with troubleshooting.
+
+Additional log events with the prefix `::debug::` will now also appear in the job's logs, these log events are provided by the Action's author and the runner process.
+
+### How to Access Step Debug Logs
+This flag can be enabled by [setting the secret](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets#creating-encrypted-secrets) `ACTIONS_STEP_DEBUG` to `true`.
+
+All actions ran while this secret is enabled will show debug events in the [Downloaded Logs](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/managing-a-workflow-run#downloading-logs) and [Web Logs](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/managing-a-workflow-run#viewing-logs-to-diagnose-failures).
+
+## Runner Diagnostic Logs
+Runner Diagnostic Logs provide additional log files detailing how the Runner is executing an action.
+
+You need the runner diagnostic logs only if you think there is an infrastructure problem with GitHub Actions and you want the product team to check the logs.
+
+Each file contains different logging information that corresponds to that process:
+  * The Runner process coordinates setting up workers to execute jobs.
+  * The Worker process executes the job.
+
+These files contain the prefix `Runner_` or `Worker_` to indicate the log source.
+
+### How to Access Runner Diagnostic Logs
+These log files are enabled by [setting the secret](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets#creating-encrypted-secrets) `ACTIONS_RUNNER_DEBUG` to `true`. 
+
+All actions ran while this secret is enabled contain additional diagnostic log files in the `runner-diagnostic-logs` folder of the [log archive](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/managing-a-workflow-run#downloading-logs).
+

docs/action-types.md

@@ -3,7 +3,7 @@
 There are two types of actions.  JavaScript and Docker actions.
 
 - **JavaScript Actions**: JavaScript actions run on the host machine.  The unit of work is decoupled from the environment.
-- **Docker Actions**: A container action is a container which carries both the unit of work along with the environment and it's dependencies packaged up as a container.
+- **Docker Actions**: A container action is a container which carries both the unit of work along with the environment and its dependencies packaged up as a container.
 
 Both have access to the workspace and the github event payload and context.
 
@@ -11,7 +11,7 @@ Both have access to the workspace and the github event payload and context.
 
 Docker actions carry both the unit of work and the environment.
 
-This creates a more consistent and reliable unit of work where the consumer of the action does not need to worry about the toolsets and it's dependencies.
+This creates a more consistent and reliable unit of work where the consumer of the action does not need to worry about the toolsets and its dependencies.
 
 Docker actions are currently limited to Linux only.
 
@@ -19,7 +19,7 @@ Docker actions are currently limited to Linux only.
 
 JavaScript actions decouple the unit of work from the environment and run directly on the host machine or VM.
 
-Consider a simple example of testing a node lib on node 8, 10 and running a custom action.  Each job will setup a node version on the host and custom-action will run it's unit of work on each environment (node8+ubunut16, node8+windows-2019, etc.)
+Consider a simple example of testing a node lib on node 8, 10 and running a custom action.  Each job will setup a node version on the host and custom-action will run its unit of work on each environment (node8+ubuntu16, node8+windows-2019, etc.)
 
 ```yaml
 on: push
@@ -32,14 +32,14 @@ jobs:
         os: [ubuntu-16.04, windows-2019]
     runs-on: ${{matrix.os}}
     actions:
-    - uses: actions/setup-node@master
+    - uses: actions/setup-node@v1
       with:
         version: ${{matrix.node}}
     - run: | 
         npm install
     - run: |
         npm test
-    - uses: actions/custom-action@master
+    - uses: actions/custom-action@v1
 ```
 
-JavaScript actions work on any environment that host action runtime is supported on which is currently node 12.  However, a host action that runs a toolset expects the environment that it's running on to have that toolset in it's PATH or using a setup-* action to acquire it on demand.
+JavaScript actions work on any environment that host action runtime is supported on which is currently node 12.  However, a host action that runs a toolset expects the environment that it's running on to have that toolset in its PATH or using a setup-* action to acquire it on demand.

docs/action-versioning.md

@@ -1,43 +1,63 @@
 # Versioning
 
-Actions are downloaded and run from the GitHub graph of repos.  The workflow references an action use a ref.
+Actions are downloaded and run from the GitHub graph of repos.  The workflow references an action using a ref.
 
 Examples:
 
 ```yaml
 steps:
-    - uses: actions/setup-node@74bc508
-    - uses: actions/setup-node@v1
-    - uses: actions/setup-node@master  # not recommended
+    - uses: actions/javascript-action@v1        # recommended. starter workflows use this
+    - uses: actions/javascript-action@v1.0.0    # if an action offers specific releases 
+    - uses: actions/javascript-action@41775a4da8ffae865553a738ab8ac1cd5a3c0044 # sha
 ```
 
-Binding to the immutable sha1 of a released version is the safest for stability and security.
+# Compatibility
 
-Binding to a specific major version allows for receiving critical fixes and security patches while still mainting compatibility and the assurance your workflow should still work.
+Binding to a major version is the latest of that major version ( e.g. `v1` == "1.*" )
 
-Binding to master is convenient but if a new major version is released which breaks compatilibility, your workflow could break. 
+Major versions should guarantee compatibility.  A major version can add net new capabilities but should not break existing input compatibility or break existing workflows. 
+
+Major version binding allows you to take advantage of bug fixes and critical functionality and security fixes.  The `main` branch has the latest code and is unstable to bind to since changes get committed to main and released to the market place by creating a tag.  In addition, a new major version carrying breaking changes will get implemented in main after branching off the previous major version.
+
+> Warning: do not reference `main` since that is the latest code and can be carrying breaking changes of the next major version.
+
+```yaml
+steps:
+    - uses: actions/javascript-action@main  # do not do this
+```
+
+Binding to the immutable full sha1 may offer more reliability.  However, note that the hosted images toolsets (e.g. ubuntu-latest) move forward and if there is a tool breaking issue, actions may react with a patch to a major version to compensate so binding to a specific SHA may prevent you from getting fixes.
+
+> Recommendation: bind to major versions to get functionality and fixes but reserve binding to a specific release or SHA as a mitigation strategy for unforeseen breaks. 
 
 # Recommendations
 
-1. **Don't check node_modules into master**: This will discourage people from attaching to master since the action will fail. You can enforce this by including `node_modules` in your `.gitignore` file.
-2. **Create a release branch for each major version**: This will act as an alpha release for that major version. Any time you are ready to publish a new version from master, you should pull those changes into this branch (following the same steps listed below).
-```
-git checkout -b releases/v1 # If this branch already exists, omit the -b flag
-rm -rf node_modules
-sed -i '/node_modules/d' .gitignore # Bash command that removes node_modules from .gitignore
-npm install --production
-git add node_modules .gitignore
-git commit -m node_modules
-git push origin releases/v1
-```
-3. **When ready for a stable release, add a major version tag**: Move the major version tag (v1, v2, etc.) to point to the ref of the current release. This will act as the stable release for that major version. You should keep this tag updated to the most recent stable minor/patch release.
-```
-git checkout releases/v1
-git push origin :refs/tags/v1
-git tag -fa v1 -m "Update v1 tag"
-git push origin v1
-```
-4. **Create releases for minor and patch version updates**: From the GitHub UI create a release for each minor or patch version update titled with that release version (e.g. v1.2.3).
-5. **Compatibility Breaks**:  introduce a new major version branch (releases/v2) and tag (v2) if changes will break existing workflows.  For example, changing inputs.
+1. **Create a GitHub release for each specific version**: Creating a release like [ v1.0.0 ](https://github.com/actions/javascript-action/releases/tag/v1.0.0) allows users to bind back to a specific version if an issue is encountered with the latest major version.  
 
-See [Git-Basics-Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging)
+2. **Publish the specific version to the marketplace**:  When you release a specific version, choose the option to "Publish this Action to the GitHub Marketplace".
+
+<img src="https://user-images.githubusercontent.com/33549821/78670739-36f5ae00-78ac-11ea-9660-57d5687ce520.png" alt="screenshot" height="250"/>
+
+3. **Make the new release available to those binding to the major version tag**: Move the major version tag (v1, v2, etc.) to point to the ref of the current release. This will act as the stable release for that major version. You should keep this tag updated to the most recent stable minor/patch release.
+
+```
+git tag -fa v1 -m "Update v1 tag"
+git push origin v1 --force
+```
+# Major Versions
+
+All releases for a major version should hold compat including input compatibility and behavior compatibility.
+
+Introduce a major version for compatibility breaks and major rewrites of the action.
+
+Ideally, a major version would carry other benefits to the user to entice them to upgrade their workflows.  Since updating their workflows will need to be done with an understanding of the changes and what compatibility was broken, introducing a new major version shouldn't be taken lightly. 
+
+To get feedback and to set expectations, the new major version can be initially released with `v2-beta` tag to indicate you can try it out but it's still going under some churn.  Upon release the `-beta` can be dropped and there's an expectation of compatibility from that point forward.
+
+[An example of v2-beta with checkout](https://github.com/actions/checkout/tree/c170eefc2657d93cc91397be50a299bff978a052#checkout-v2-beta)
+
+# Sample Workflow
+
+This illustrates the versioning workflow covered above.
+
+![versioning](assets/action-releases.png)

docs/adrs/0381-glob-module.md

@@ -0,0 +1,216 @@
+# ADR 381: `glob` module
+
+**Date**: 2019-12-05
+
+**Status**: Accepted
+
+## Context
+
+This ADR proposes adding a `glob` function to the toolkit.
+
+First party actions should have a consistent glob experience.
+
+Related to artifact upload/download v2.
+
+## Decision
+
+### New module
+
+Create a new module `@actions/glob` that can be versioned at it's own pace - not tied to `@actions/io`.
+
+### Signature
+
+```js
+/**
+ * Constructs a globber from patterns
+ *
+ * @param patterns  Patterns separated by newlines
+ * @param options   Glob options
+ */
+export function create(
+  patterns: string,
+  options?: GlobOptions
+): Promise<Globber> {}
+
+/**
+ * Used to match files and directories
+ */
+export interface Globber {
+  /**
+   * Returns the search path preceding the first glob segment, from each pattern.
+   * Duplicates and descendants of other paths are filtered out.
+   *
+   * Example 1: The patterns `/foo/*` and `/bar/*` returns `/foo` and `/bar`.
+   *
+   * Example 2: The patterns `/foo/*` and `/foo/bar/*` returns `/foo`.
+   */
+  getSearchPaths(): string[]
+
+  /**
+   * Returns files and directories matching the glob patterns.
+   *
+   * Order of the results is not guaranteed.
+   */
+  glob(): Promise<string[]>
+
+  /**
+   * Returns files and directories matching the glob patterns.
+   *
+   * Order of the results is not guaranteed.
+   */
+  globGenerator(): AsyncGenerator<string, void>
+}
+
+/**
+ * Options to control globbing behavior
+ */
+export interface GlobOptions {
+  /**
+   * Indicates whether to follow symbolic links. Generally should set to false
+   * when deleting files.
+   *
+   * @default true
+   */
+  followSymbolicLinks?: boolean
+
+  /**
+   * Indicates whether directories that match a glob pattern, should implicitly
+   * cause all descendant paths to be matched.
+   *
+   * For example, given the directory `my-dir`, the following glob patterns
+   * would produce the same results: `my-dir/**`, `my-dir/`, `my-dir`
+   *
+   * @default true
+   */
+  implicitDescendants?: boolean
+
+  /**
+   * Indicates whether broken symbolic should be ignored and omitted from the
+   * result set. Otherwise an error will be thrown.
+   *
+   * @default true
+   */
+  omitBrokenSymbolicLinks?: boolean
+}
+```
+
+### Toolkit usage
+
+Example, do not follow symbolic links:
+
+```js
+const patterns = core.getInput('path')
+const globber = glob.create(patterns, {followSymbolicLinks: false})
+const files = globber.glob()
+```
+
+Example, iterator:
+
+```js
+const patterns = core.getInput('path')
+const globber = glob.create(patterns)
+for await (const file of this.globGenerator()) {
+  console.log(file)
+}
+```
+
+### Action usage
+
+Actions should follow symbolic links by default.
+
+Users can opt-out.
+
+Example:
+
+```yaml
+jobs:
+  build:
+    steps:
+      - uses: actions/upload-artifact@v1
+        with:
+          path: |
+            **/*.tar.gz
+            **/*.pkg
+          follow-symbolic-links: false    # opt out, should default to true
+```
+
+### HashFiles function
+
+Hash files should not follow symbolic links by default.
+
+User can opt-in by specifying flag `--follow-symbolic-links`.
+
+Example:
+
+```yaml
+jobs:
+  build:
+    steps:
+      - uses: actions/cache@v1
+        with:
+          hash: ${{ hashFiles('--follow-symbolic-links', '**/package-lock.json') }}
+```
+
+### Glob behavior
+
+Patterns `*`, `?`, `[...]`, `**` (globstar) are supported.
+
+With the following behaviors:
+
+- File names that begin with `.` may be included in the results
+- Case insensitive on Windows
+- Directory separator `/` and `\` both supported on Windows
+
+Note:
+- Refer [here](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html#Pattern-Matching) for more information about Bash glob patterns.
+- Refer [here](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html) for more information about Bash glob options.
+
+### Tilde expansion
+
+Support basic tilde expansion, for current user HOME replacement only.
+
+For example, on macOS:
+- `~` may expand to `/Users/johndoe`
+- `~/foo` may expand to `/Users/johndoe/foo`
+
+Note:
+- Refer [here](https://www.gnu.org/software/bash/manual/html_node/Tilde-Expansion.html) for more information about Bash tilde expansion.
+- All other forms of tilde expansion are not supported.
+- Use `os.homedir()` to resolve the HOME path
+
+### Root and normalize paths
+
+An unrooted pattern will be rooted using the current working directory, prior to searching. Additionally the search path will be normalized prior to searching (relative pathing removed, slashes normalized on Windows, extra slashes removed).
+
+The two side effects are:
+1. Rooted and normalized paths are always returned
+2. The pattern `**` will include the working directory in the results
+
+These side effects diverge from Bash behavior. Whereas Bash is designed to be a shell, we are designing an API. This decision is intended to improve predictability of the API results.
+
+Note:
+- In Bash, the results are not rooted when the pattern is relative.
+- In Bash, the results are not normalized. For example, the results from `./*` may look like: `./foo ./bar`
+- In Bash, the results from the pattern `**` does not include the working directory. However the results from `/foo/**` would include the directory `/foo`. Also the results from `foo/**` would include the directory `foo`.
+
+## Comments
+
+Patterns that begin with `#` are treated as comments.
+
+## Exclude patterns
+
+Leading `!` changes the meaning of an include pattern to exclude.
+
+Note:
+- Multiple leading `!` flips the meaning.
+
+## Escaping
+
+Wrapping special characters in `[]` can be used to escape literal glob characters in a file name. For example the literal file name `hello[a-z]` can be escaped as `hello[[]a-z]`.
+
+On Linux/macOS `\` is also treated as an escape character.
+
+## Consequences
+
+- Publish new module `@actions/glob`
+- Publish docs for the module (add link from `./README.md` to new doc `./packages/glob/README.md`)

docs/adrs/README.md

@@ -0,0 +1,19 @@
+# ADRs
+
+ADR, short for "Architecture Decision Record" is a way of capturing important architectural decisions, along with their context and consequences.
+
+This folder includes ADRs for the actions toolkit. ADRs are proposed in the form of a pull request, and they commonly follow this format:
+
+* **Title**: short present tense imperative phrase, less than 50 characters, like a git commit message.
+
+* **Status**: proposed, accepted, rejected, deprecated, superseded, etc.
+
+* **Context**: what is the issue that we're seeing that is motivating this decision or change.
+
+* **Decision**: what is the change that we're actually proposing or doing.
+
+* **Consequences**: what becomes easier or more difficult to do because of this change.
+
+---
+
+- More information about ADRs can be found [here](https://github.com/joelparkerhenderson/architecture_decision_record).

docs/assets/action-releases.drawio

@@ -0,0 +1 @@
+<mxfile modified="2019-12-12T18:56:00.899Z" host="www.draw.io" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.108 Safari/537.36" etag="CISsL8yLQ-3TSrXBbF_M" version="12.3.8" type="device" pages="1"><diagram name="Page-1" id="ff44883e-f642-bcb2-894b-16b3d25a3f0b">7VvbctsqFP0aP9YjkISkx9hJcx7amZ7mTNs8dYiEZVpZeBC+9esPyMi64UsdW3Ymdh4Mm5tgrbU3AqdnDyfLR46n488sIkkPWtGyZ9/3IASWi+SXsqzWFhf5a0PMaaQrlYYn+ocULbV1RiOS1SoKxhJBp3VjyNKUhKJmw5yzRb3aiCX1Uac4Ji3DU4iTwtp3S/t3GomxtgMUlAX/EBqP9eA+1FN+weHvmLNZqkfsQXuUf9bFE1z0paeajXHEFhWT/dCzh5wxsU5NlkOSqNUtFq5oJ1bF0/bswVhMEpkBMpkXf9zSGBzSWE6Ok1RUh9vW38h6CcMgsC2HoJGLPwSt/kkkV1ZnU5bKr0E443MS6RErg2cCc6HJIJlgD0ga3Sk0ZT5McJbRcG38SJOijcxVW2SCs99kyBLG8+FtK/9sSgos1bRHLN2MBvOuBF/92PQrM88yY0kq6Oy94re1ya2K3JKKH5V0pZXMlY1UpmjTXucCGTbjITEvLtRKwDwmwlxF96IWvdKtxu6RsAmRTy4rcJJgQed1EWCtmnhTb9P0C6PyQaGlFe4UQtX69jyr3sV6GrpVyR+ZqDxGacpZdRjDADo1xfaxaSdnTNjvRH7Dsgqxnquk28Kyoxhjd0MH5NfpgNwGHdaUPQsd1gPNcTIrHFqLHkki44ZixWJMBXma4ny5FjJ01cmRe+2cNTn4hWMGJr+C8k+LI06dI7bqCCc0TpULk8gRripIwlW6GrnqbxfEc8IFWe5EUJfCBhJuIcxFGcSKKuNq+LK2Y15D62+gaUeqa1PqHi99bEQ4Sqtov3eH3cjZDRoksjuTM2zJud/vX1TR4MKKdrzrUbR9Xc720tB4Th0aH14OGucGTQ2apgu7ZBx0bnHwL+Kgsz8Oom7ioGdfLA6im5yrckbO5eQc/+T3377+Gz/Mp9/++5SxT+Hwg/G1AyVy1MGLTMR5guM0lM92V5TIgTaF8htPFE7pS6a+JFMJzkgm68zbZzQSs6lKhjhJ2Ezsh3xKOJUTVbAUjb6UpsGUZVRQlsJcxcA/kc9FjUMBpw0SgF2idNuv1AACln25DYsRoFtk3BUZd3F6V3js6NTHQ6DvAdeDvufK2OgFdW45xtI9B4Tto6XGRg6hs8Vg43L7+x19yAkWZL2eyon3lKoGOUbxVvdvgT7o25u+eCUw1Hvf2UnnsULCeBJXFDjNWAHasQJ1GtGtW7DYhdDlt1xtrr+xYHG80y/IeW6X7lsNbwsbaB7qtv3GqRUC3bptELTUPMGZEk2TQ1IOokmVqkI1r6pK06aWGpW4qHShd7pgQqMo2eYt6i4ip5d+qIbyFVgn2f017uyQZdieewZFg2A7jV6laNh2ubvfg94PVm5jo24f+CrV1OvpsDrkoq28rtfLHuFsbPLGBy/ZXodXWRDXsB6F7ZV+ETSu1bymOzvULwLg7enpdI4xcFf8bjX8NcOfvybsz+Pz/XffcMFysv2s1bfe3H7WLvezLXUaCLn93rVx9uEEBsGeaz9rBNp09nEKoOvnVvAkqLddydtA3XP9K0PddA10HtTBu0U9gAdovWBGJ6i753PqoA/frVNH1rU59fa10ASnqxyoZYmt3D1bhl9NXOPu+fUgOY5bA8kFBpDsM22VjSB5LZCGcs6YpgoXMVbSk5tRkqlt4QT/kgudL0Em+XulmJ0iVDbPcQ3HSYHbIUqG874RVSKi6QamjPA5DWkay7S+zoMWG6mJczKnbJa9JwiDxqtLYFKa6UjwCAxltvwJ/Prdp/xPA/vhfw==</diagram></mxfile>

docs/commands.md

@@ -0,0 +1,203 @@
+# :: Commands
+
+The [core toolkit package](https://github.com/actions/toolkit/tree/main/packages/core) offers a number of convenience functions for
+setting results, logging, registering secrets and exporting variables across actions. Sometimes, however, its useful to be able to do
+these things in a script or other tool.
+
+To allow this, we provide a special `::` syntax which, if logged to `stdout` on a new line, will allow the runner to perform special behavior on
+your commands. The following commands are all supported:
+
+### Set outputs
+
+To set an output for the step, use `::set-output`:
+
+```sh
+echo "::set-output name=FOO::BAR"
+```
+
+Running `steps.[step-id].outputs.FOO` in your Yaml will now give you `BAR`
+
+```yaml
+steps:
+  - name: Set the value
+    id: step_one
+    run: echo "::set-output name=FOO::BAR"
+  - name: Use it
+    run: echo ${{ steps.step_one.outputs.FOO }}
+```
+
+This is wrapped by the core setOutput method:
+
+```javascript
+export function setOutput(name: string, value: string): void {}
+```
+
+### Register a secret
+
+If a script or action does work to create a secret at runtime, it can be registered with the runner to be masked in logs.
+
+To mask a value in the logs, use `::add-mask`:
+
+```sh
+echo "::add-mask::mysecretvalue"
+```
+
+This is wrapped by the core setSecret method
+
+```javascript
+function setSecret(secret: string): void {}
+```
+
+Now, future logs containing BAR will be masked. E.g. running `echo "Hello FOO BAR World"` will now print `Hello FOO **** World`.
+
+**WARNING** The add-mask and setSecret  commands only support single line secrets. To register a multiline secrets you must register each line individually otherwise it will not be masked.
+
+**WARNING** Do **not** mask short values if you can avoid it, it could render your output unreadable (and future steps' output as well).
+For example, if you mask the letter `l`, running `echo "Hello FOO BAR World"` will now print `He*********o FOO BAR Wor****d`
+
+### Group and Ungroup Log Lines
+
+Emitting a group with a title will instruct the logs to create a collapsible region up to the next endgroup command.
+
+```bash
+echo "::group::my title"   
+echo "::endgroup::"
+```
+
+This is wrapped by the core methods:
+
+```javascript
+function startGroup(name: string): void {}
+function endGroup(): void {}
+```
+
+### Problem Matchers
+
+Problems matchers can be used to scan a build's output to automatically surface lines to the user that matches the provided pattern. A file path to a .json Problem Matcher must be provided. See [Problem Matchers](problem-matchers.md) for more information on how to define a Problem Matcher.
+
+```bash
+echo "::add-matcher::eslint-compact-problem-matcher.json"   
+echo "::remove-matcher owner=eslint-compact::"
+```
+
+`add-matcher` takes a path to a Problem Matcher file
+`remove-matcher` removes a Problem Matcher by owner
+
+### Save State
+
+Save a state to an environmental variable that can later be used in the main or post action.
+
+```bash
+echo "::save-state name=FOO::foovalue"
+```
+
+Because `save-state` prepends the string `STATE_` to the name, the environment variable `STATE_FOO` will be available to use in the post or main action. See [Sending Values to the pre and post actions](https://help.github.com/en/actions/reference/workflow-commands-for-github-actions#sending-values-to-the-pre-and-post-actions) for more information.
+
+### Log Level
+
+There are several commands to emit different levels of log output:
+
+| log level | example usage |
+|---|---|
+| [debug](action-debugging.md)  | `echo "::debug::My debug message"` |
+| warning | `echo "::warning::My warning message"` |
+| error | `echo "::error::My error message"` |
+
+### Command Echoing
+
+By default, the echoing of commands to stdout only occurs if [Step Debugging is enabled](./action-debugging.md#How-to-Access-Step-Debug-Logs)
+
+You can enable or disable this for the current step by using the `echo` command.
+
+```bash
+echo "::echo::on"
+```
+
+You can also disable echoing.
+
+```bash
+echo "::echo::off"
+```
+
+This is wrapped by the core method:
+
+```javascript
+function setCommandEcho(enabled: boolean): void {}
+```
+
+The `add-mask`, `debug`, `warning` and `error` commands do not support echoing.
+
+### Command Prompt
+
+CMD processes the `"` character differently from other shells when echoing. In CMD, the above snippets should have the `"` characters removed in order to correctly process. For example, the set output command would be:
+
+```cmd
+echo ::set-output name=FOO::BAR
+```
+
+## Environment files
+
+During the execution of a workflow, the runner generates temporary files that can be used to perform certain actions. The path to these files are exposed via environment variables. You will need to use the `utf-8` encoding when writing to these files to ensure proper processing of the commands. Multiple commands can be written to the same file, separated by newlines.
+
+### Set an environment variable
+
+To set an environment variable for future out of process steps, write to the file located at `GITHUB_ENV` or use the equivalent `actions/core` function
+
+```sh
+echo "FOO=BAR" >> $GITHUB_ENV
+```
+
+Running `$FOO` in a future step will now return `BAR`
+
+For multiline strings, you may use a heredoc style syntax with your choice of delimeter. In the below example, we use `EOF`.
+
+```
+steps:
+  - name: Set the value
+    id: step_one
+    run: |
+        echo 'JSON_RESPONSE<<EOF' >> $GITHUB_ENV
+        curl https://httpbin.org/json >> $GITHUB_ENV
+        echo 'EOF' >> $GITHUB_ENV
+```
+
+This would set the value of the `JSON_RESPONSE` env variable to the value of the curl response.
+
+The expected syntax for the heredoc style is:
+
+```
+{VARIABLE_NAME}<<{DELIMETER}
+{VARIABLE_VALUE}
+{DELIMETER}
+```
+
+This is wrapped by the core `exportVariable` method which sets for future steps but also updates the variable for this step.
+
+```javascript
+export function exportVariable(name: string, val: string): void {}
+```
+
+### PATH Manipulation
+
+To prepend a string to PATH write to the file located at `GITHUB_PATH` or use the equivalent `actions/core` function
+
+```sh
+echo "/Users/test/.nvm/versions/node/v12.18.3/bin" >> $GITHUB_PATH
+```
+
+Running `$PATH` in a future step will now return `/Users/test/.nvm/versions/node/v12.18.3/bin:{Previous Path}`;
+
+This is wrapped by the core addPath method:
+
+```javascript
+export function addPath(inputPath: string): void {}
+```
+
+### Powershell
+
+Powershell does not use UTF8 by default. You will want to make sure you write in the correct encoding. For example, to set the path:
+
+```
+steps:
+  - run: echo "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+```

docs/container-action.md

@@ -14,11 +14,11 @@ Complete creating your repo and clone the repo.
 
 > NOTE: The location of the repo will be how users will reference your action in their workflow file with the using keyword.
 
-e.g. To use https://github.com/actions/setup-node, user's will author:
+e.g. To use https://github.com/actions/setup-node, users will author:
 
 ```yaml
 steps:
-    using: actions/setup-node@master
+    using: actions/setup-node@v1
 ```
 
 # Define Metadata
@@ -64,7 +64,7 @@ $ git push
 
 The runner will download the action and build the docker container on the fly at runtime.
 
-> Consider versioning your actions with tags.  See [versioning](docs/action-versioning.md)
+> Consider versioning your actions with tags.  See [versioning](/docs/action-versioning.md)
 
 
 

docs/github-package.md

@@ -1,100 +1,288 @@
-# Github Package
+# Creating an Action using the GitHub Context
 
-In order to support using actions to interact with GitHub, I propose adding a `github` package to the toolkit.
+## Goal
 
-Its main purpose will be to provide a hydrated GitHub context/Octokit client with some convenience functions. It is largely pulled from the GitHub utilities provided in https://github.com/JasonEtco/actions-toolkit, though it has been condensed.
+In this walkthrough we will learn how to build a basic action using GitHub context data to greet users when they open an issue or PR. In the process we will explore how to access this context and how to make authenticated requests to the GitHub API.
 
-### Spec
+Note that a complete version of this action can be found at https://github.com/damccorm/issue-greeter.
 
-##### interfaces.ts
+## Prerequisites
 
+This walkthrough assumes that you have gone through the basic [javascript action walkthrough](https://github.com/actions/javascript-action) and have a basic action set up. If not, we recommend you go through that first.
+
+## Installing dependencies
+
+All of the dependencies we need should come packaged for us in this library's core and github packages. To install, run the following in your action:
+
+`npm install @actions/core && npm install @actions/github`
+
+## Metadata
+
+Next, we will need a welcome message and a repo token as an input. Recall that inputs are defined in the `action.yml` metadata file - update your `action.yml` file to define `welcome-message` and `repo-token` as inputs.
+
+```yaml
+name: "Welcome"
+description: "A basic welcome action"
+author: "GitHub"
+inputs:
+  welcome-message:
+    description: "Message to display when a user opens an issue or PR"
+    default: "Thanks for opening an issue! Make sure you've followed CONTRIBUTING.md"
+  repo-token:
+    description: "Token for the repo. Can be passed in using {{ secrets.GITHUB_TOKEN }}"
+    required: true
+runs:
+  using: "node12"
+  main: "lib/main.js"
 ```
-/*
- * Interfaces
- */
- 
-export interface PayloadRepository {
-  [key: string]: any
-  full_name?: string
-  name: string
-  owner: {
-    [key: string]: any
-    login: string
-    name?: string
-  }
-  html_url?: string
+
+## Action logic
+
+Now that we've installed our dependencies and defined our inputs, we're ready to start writing the action logic in `src/main.ts`! For clarity, we'll structure our action up as follows:
+
+```ts
+import * as core from '@actions/core';
+import * as github from '@actions/github';
+
+export async function run() {
+    try {
+    const welcomeMessage: string = core.getInput('welcome-message');
+    // TODO - Get context data
+
+    // TODO - make request to the GitHub API to comment on the issue 
+    }
+    catch (error) {
+      core.setFailed(error.message);
+      throw error;
+    }
 }
 
-export interface WebhookPayloadWithRepository {
-  [key: string]: any
-  repository?: PayloadRepository
-  issue?: {
-    [key: string]: any
-    number: number
-    html_url?: string
-    body?: string
-  }
-  pull_request?: {
-    [key: string]: any
-    number: number
-    html_url?: string
-    body?: string
-  }
-  sender?: {
-    [key: string]: any
-    type: string
-  }
-  action?: string
-  installation?: {
-    id: number
-    [key: string]: any
-  }
+run();
+```
+
+### Getting context data
+
+For the purpose of this walkthrough, we will need the following pieces of context data:
+
+- the name of the repo that the action is being run on
+- the organization/owner of that repo
+- the number of the issue that has been opened
+
+Fortunately, the GitHub package provides all of this to us with [a single convenience function](https://github.com/actions/toolkit/blob/ac007c06984bc483fae2ba649788dfc858bc6a8b/packages/github/src/context.ts#L34), so we can simply do:
+
+`const issue: {owner: string; repo: string; number: number} = github.context.issue;`
+
+The context object also contains a number of easily accessed properties, as well as easy access to the full [GitHub payload](https://developer.github.com/v3/activity/events/types/). We can use this to check and make sure we're actually looking at a recently opened issue (and not something else, like a comment on an existing issue):
+
+```ts
+if (github.context.payload.action !== 'opened') {
+  console.log('No issue or PR was opened, skipping');
+  return;
 }
 ```
 
-##### context.ts
+Our whole `src/main.ts` file now looks like:
 
-Contains a GitHub context
+```ts
+import * as core from '@actions/core';
+import * as github from '@actions/github';
 
-```
-export class Context {
-   /**
-   * Webhook payload object that triggered the workflow
-   */
-  public payload: WebhookPayloadWithRepository
+export async function run() {
+    try {
+    const welcomeMessage: string = core.getInput('welcome-message', {required: true});
+    const repoToken: string = core.getInput('repo-token', {required: true});
+    const issue: {owner: string; repo: string; number: number} = github.context.issue;
 
-  /**
-   * Name of the event that triggered the workflow
-   */
-  public event: string
-  public sha: string
-  public ref: string
-  public workflow: string
-  public action: string
-  public actor: string
-  
-  /**
-   * Hydrate the context from the environment
-   */
-  constructor ()
-  
-  public get issue ()
-  
-  public get repo ()
+    if (github.context.payload.action !== 'opened') {
+      console.log('No issue or pull request was opened, skipping');
+      return;
+    }
+
+    // TODO - make request to the GitHub API to comment on the issue 
+    }
+    catch (error) {
+      core.setFailed(error.message);
+      throw error;
+    }
 }
 
+run();
 ```
 
-##### github.ts
+### Sending requests to the GitHub API
 
-Contains a hydrated Octokit client
+Now that we have our context data, we are able to send a request to the GitHub API using the [Octokit REST client](https://github.com/octokit/rest.js). The REST client exposes a number of easy convenience functions, including one for adding comments to issues/PRs (issues and PRs are treated as one concept by the Octokit client):
 
+```ts
+const client: github.GitHub = new github.GitHub(repoToken);
+await client.issues.createComment({
+  owner: issue.owner,
+  repo: issue.repo,
+  issue_number: issue.number,
+  body: welcomeMessage
+});
 ```
-export class GithubClient extends Octokit {
- // For making GraphQL requests
- public graphql: (query: string, variables?: Variables) => Promise<GraphQlQueryResponse>
- 
- // Calls super and initializes graphql
- constructor (token: string)
+
+For more docs on the client, you can visit the [Octokit REST documentation](https://octokit.github.io/rest.js/). Now our action code should be complete:
+
+```ts
+import * as core from '@actions/core';
+import * as github from '@actions/github';
+
+export async function run() {
+    try {
+    const welcomeMessage: string = core.getInput('welcome-message', {required: true});
+    const repoToken: string = core.getInput('repo-token', {required: true});
+    const issue: {owner: string; repo: string; number: number} = github.context.issue;
+
+    if (github.context.payload.action !== 'opened') {
+      console.log('No issue or pull request was opened, skipping');
+      return;
+    }
+
+    const client: github.GitHub = new github.GitHub(repoToken);
+    await client.issues.createComment({
+      owner: issue.owner,
+      repo: issue.repo,
+      issue_number: issue.number,
+      body: welcomeMessage
+    });
+    }
+    catch (error) {
+      core.setFailed(error.message);
+      throw error;
+    }
+}
+
+run();
+```
+
+## Writing unit tests for your action
+
+Next, we're going to write a basic unit test for our action using jest. If you followed the [javascript walkthrough](https://github.com/actions/javascript-action), you should have a file `__tests__/main.test.ts` that runs tests when `npm test` is called. We're going to start by populating that with one test:
+
+```ts
+const nock = require('nock');
+const path = require('path');
+
+describe('action test suite', () => {
+  it('It posts a comment on an opened issue', async () => {
+    // TODO
+  });
+});
+```
+
+For the purposes of this walkthrough, we'll focus on populating this test and leave the remaining test coverage as an exercise for the reader.
+
+### Mocking inputs
+
+First, we want to make sure that we can mock our inputs (welcome-message, and repo-token). Actions handles inputs by populating process.env.INPUT_${input name in all caps}, so we can mock that simply by setting those environment variables:
+
+```ts
+const nock = require('nock');
+const path = require('path');
+
+describe('action test suite', () => {
+  it('It posts a comment on an opened issue', async () => {
+    const welcomeMessage = 'hello';
+    const repoToken = 'token';
+    process.env['INPUT_WELCOME-MESSAGE'] = welcomeMessage;
+    process.env['INPUT_REPO-TOKEN'] = repoToken;
+
+    // TODO
+  });
+});
+```
+
+### Mocking the GitHub context
+
+Mocking the GitHub context is relatively straightforward. Since most of it is simply populated by environment variables, you can just set the corresponding environment variables defined [here](https://github.com/actions/toolkit/blob/ac007c06984bc483fae2ba649788dfc858bc6a8b/packages/github/src/context.ts#L23) and test that it works in that environment. In this case, we can setup our test with:
+
+```ts
+const nock = require('nock');
+const path = require('path');
+
+describe('action test suite', () => {
+  it('It posts a comment on an opened issue', async () => {
+    const welcomeMessage = 'hello';
+    const repoToken = 'token';
+    process.env['INPUT_WELCOME-MESSAGE'] = welcomeMessage;
+    process.env['INPUT_REPO-TOKEN'] = repoToken;
+
+    process.env['GITHUB_REPOSITORY'] = 'foo/bar';
+    process.env['GITHUB_EVENT_PATH'] = path.join(__dirname, 'payload.json');
+
+    // TODO
+  });
+});
+```
+
+Note that the payload is loaded from GITHUB_EVENT_PATH. Since we set that to `path.join(__dirname, 'payload.json')`, we need to go save our payload there. For the purposes of this test, we can simply save the following to `__tests__/payload.json`:
+
+```json
+{
+    "issue": {
+        "number": 10
+    },
+    "action": "opened"
 }
 ```
+
+Now, calling `github.context.issue` should return `{owner: foo, repo: bar, number: 10}`, and `github.context.payload.action` should get set to 'opened'
+
+> One important detail here is that because the GitHub context loads these environment variables as soon as it is required, you should set them before you require your action. In most cases, this means you need to rerequire your action in every test. If this is a problem, you can get around it by mocking the class directly using jest (or whatever framework you choose).
+
+### Mocking the Octokit Client
+
+To mock the client calls, we recommend using [nock](https://github.com/nock/nock) which allows you to mock the http requests made by the client. First, install nock with `npm install nock --save-dev`.
+
+For this test, we expect the following call:
+
+```ts
+client.issues.createComment({
+  owner: 'foo',
+  repo: 'bar',
+  issue_number: 10,
+  body: 'you posted your first issue'
+});
+```
+
+From [the GitHub endpoint docs](https://developer.github.com/v3/issues/comments/#create-a-comment), we expect this to get make a POST request to `https://api.github.com/repos/foo/bar/issues/10/comments` with body of `{"body":"hello"}`
+
+We can mock this with:
+
+```ts
+const nock = require('nock');
+const path = require('path');
+
+describe('action test suite', () => {
+  it('It posts a comment on an opened issue', async () => {
+    const welcomeMessage = 'hello';
+    const repoToken = 'token';
+    process.env['INPUT_WELCOME-MESSAGE'] = welcomeMessage;
+    process.env['INPUT_REPO-TOKEN'] = repoToken;
+
+    process.env['GITHUB_REPOSITORY'] = 'foo/bar';
+    process.env['GITHUB_EVENT_PATH'] = path.join(__dirname, 'payload.json');
+
+    nock('https://api.github.com')
+      .persist()
+      .post('/repos/foo/bar/issues/10/comments', '{\"body\":\"hello\"}')
+      .reply(200);
+      
+    const main = require('../src/main');
+
+    await main.run();
+  });
+});
+```
+
+This will fail if the url or body doesn't exactly match the parameters passed into the nock function. We can now run `npm test` and the test should succeed.
+
+## Build and publish
+
+Now that we've written and unit tested our action, we can build our action with `npm run build` and push it to a repo where it can be consumed by workflows. For more info on versioning your action, see [our versioning docs](./action-versioning.md).
+
+## Next steps
+
+If you're interested in building out this action further, try extending your action to only run on a user's first issue. See our [first-contribution action](https://github.com/actions/first-interaction) for inspiration.

docs/node12-action.md

@@ -1,167 +0,0 @@
-# Creating a JavaScript Action
-
-The [node12-template](https://github.com/actions/node12-template) repo contains everything you need to get started.
-
-# Create a Repo from the Template
-
-Navigate to https://github.com/actions/node12-template
-
-Click on `Use this template` to create the repo for your action.
-
-![template](assets/node12-template.png)
-
-Complete creating your repo and clone the repo.
-
-> NOTE: The location of the repo will be how users will reference your action in their workflow file with the using keyword.
-
-e.g. To use https://github.com/actions/setup-node, user's will author:
-
-```yaml
-steps:
-    using: actions/setup-node@master
-```
-
-# Dev Workflow
-
-The workflow below describes one possible workflow with a branching strategy.  Others exist.  
-
-> Key Point: the branch that users reference in their workflow files should reference an action that has **only** the production dependencies. 
-
-The workflow below describes a strategy where you code in master (with node_modules ignored) with a v1 branch users reference and contains the product references.  Actions are self contained referenced on the github graph of repos.
-
-## Install Dependencies
-
-After creating a repo from the template and cloning it, you will be in master.  The command below will install the toolkit, other dependencies and dev dependencies
-
-```bash
-$ npm install
-```
-
-## Define Metadata
-
-Your action has a name and a description.  Update the author.
-
-Create inputs that your unit of work will need.  These will be what workflow authors set with the `with:` keyword.
-
-```yaml
-name: 'My new action'
-description: 'A test action'
-author: 'GitHub'
-inputs: 
-  myInput:
-    description: 'Input to use'
-    default: 'world'
-runs:
-  using: 'node12'
-  main: 'lib/main.js'
-
-```
-
-Note that the action will be run with node 12 (carried by the runner) and the entry point is specified with `main:` 
-
-## Change Code and Add Tests
-
-The entry point is in main.ts
-
-```typescript
-import * as core from '@actions/core';
-
-async function run() {
-  try {
-    const myInput = core.getInput('myInput');
-    core.debug(`Hello ${myInput}!`);
-  } catch (error) {
-    core.setFailed(error.message);
-  }
-}
-
-run();
-```
-
-Modify tests in `__tests__\main.test.ts`.  The template uses [jest](https://github.com/facebook/jest).
-
-## Format the Code
-
-```bash
-$ npm run format
-```
-
-## Build and Test
-
-```bash
-$ npm run build
-
-> node12-template-action@0.0.0 build /Users/user/Projects/testnode12
-> tsc
-
-$ npm test
-
-> jest
-
- PASS  __tests__/main.test.ts
-  TODO - Add a test suite
-    ✓ TODO - Add a test (1ms)
-
-Test Suites: 1 passed, 1 total
-...
-```
-
-## Commit and Push Changes
-
-```bash
-$ git add <whatever only files you added>
-$ git commit -m "Message"
-```
-
-## Publish a v1-release Action
-
-After changing some files, create a v1-release branch which we will release 
-
-```bash
-$ git checkout -b v1-release
-```
-
-> NOTE: We will provide tooling and an action to automate this soon.
-
-Checkin production dependencies:
-1. **Do not ignore node_modules**:  Add a `!` in front of the `node_modules` line.
-2. **Delete node_modules**: rm -Rf node_modules
-3. **Install production dependencies**: npm install --production
-4. **Add**: git add node_modules
-
-
-Simply commit and push your action to publish.
-
-```bash
-$ git commit -a -m "publishing v1 of action"
-$ git push
-```
-
-> NOTE: Consider versioning your actions with tags.  See [versioning](action-versioning.md)
-
-## Test End To End
-
-Once the action has a self contained version in the v1-release branch, you can test it by referencing the latest (and potentially unstable) version in the release branch.  If you are fixing an issue that someone else is having with your action, you can have them try it before you officially releasing it as the 'v1' version.
-
-```yaml
-steps:
-    using: {org}/{reponame}@v1-release
-```
-
-## Release Current Changes as v1
-
-Once you have tested end to end, push a tag of 'v1' to the commit in the release branch.
-
-See [action versioning](action-versioning.md) for more details.
-
-# Users Referencing
-
-Users can now reference your action in their workflows with
-
-```yaml
-steps:
-    using: {org}/{reponame}@v1
-```
-
-
-

docs/problem-matchers.md

@@ -0,0 +1,149 @@
+# Problem Matchers
+
+Problem Matchers are a way to scan the output of actions for a specified regex pattern and surface that information prominently in the UI. Both [GitHub Annotations](https://developer.github.com/v3/checks/runs/#annotations-object-1) and log file decorations are created when a match is detected.
+
+## Limitations
+
+Currently, GitHub Actions limit the annotation count in a workflow run.
+
+- 10 warning annotations, 10 error annotations, and 10 notice annotations per step
+- 50 annotations per job (sum of annotations from all the steps)
+- 50 annotations per run (separate from the job annotations, these annotations aren’t created by users)
+
+If your workflow may exceed these annotation counts, consider filtering of the log messages which the Problem Matcher is exposed to (e.g. by PR touched files, lines, or other).
+
+## Single Line Matchers
+
+Let's consider the ESLint compact output:
+
+```
+badFile.js: line 50, col 11, Error - 'myVar' is defined but never used. (no-unused-vars)
+```
+
+We can define a problem matcher in json that detects input in that format:
+
+```json
+{
+    "problemMatcher": [
+        {
+            "owner": "eslint-compact",
+            "pattern": [
+                {
+                    "regexp": "^(.+):\\sline\\s(\\d+),\\scol\\s(\\d+),\\s(Error|Warning|Info)\\s-\\s(.+)\\s\\((.+)\\)$",
+                    "file": 1,
+                    "line": 2,
+                    "column": 3,
+                    "severity": 4,
+                    "message": 5,
+                    "code": 6
+                }
+            ]
+        }
+    ]
+}
+```
+
+The following fields are available for problem matchers:
+
+```
+{
+    owner: an ID field that can be used to remove or replace the problem matcher. **required**
+    severity: indicates the default severity, either 'warning' or 'error' case-insensitive. Defaults to 'error'
+    pattern: [
+        {
+            regexp: the regex pattern that provides the groups to match against **required**
+            file: a group number containing the file name
+            fromPath: a group number containing a filepath used to root the file (e.g. a project file)
+            line: a group number containing the line number
+            column: a group number containing the column information
+            severity: a group number containing either 'warning' or 'error' case-insensitive. Defaults to `error`
+            code: a group number containing the error code
+            message: a group number containing the error message. **required** at least one pattern must set the message
+            loop: whether to loop until a match is not found, only valid on the last pattern of a multipattern matcher
+        }
+    ]
+}
+```
+
+## Multiline Matching
+Consider the following output:
+
+```
+test.js
+  1:0   error  Missing "use strict" statement                 strict
+  5:10  error  'addOne' is defined but never used             no-unused-vars
+✖ 2 problems (2 errors, 0 warnings)
+```
+
+The file name is printed once, yet multiple error lines are printed. The `loop` keyword provides a way to discover multiple errors in outputs. 
+
+The eslint-stylish problem matcher defined below catches that output, and creates two annotations from it.
+
+```
+{
+    "problemMatcher": [
+        {
+            "owner": "eslint-stylish",
+            "pattern": [
+                {
+                    // Matches the 1st line in the output
+                    "regexp": "^([^\\s].*)$",
+                    "file": 1
+                },
+                {
+                    // Matches the 2nd and 3rd line in the output
+                    "regexp": "^\\s+(\\d+):(\\d+)\\s+(error|warning|info)\\s+(.*)\\s\\s+(.*)$",
+                    // File is carried through from above, so we define the rest of the groups
+                    "line": 1,
+                    "column": 2,
+                    "severity": 3,
+                    "message": 4,
+                    "code": 5,
+                    "loop": true
+                }
+            ]
+        }
+    ]
+}
+```
+
+The first pattern matches the `test.js` line and records the file information. This line is not decorated in the UI.
+The second pattern loops through the remaining lines with `loop: true` until it fails to find a match, and surfaces these lines prominently in the UI.
+
+Note that the pattern matches must be on consecutive lines. The following would not result in any match findings.
+
+```
+test.js
+  extraneous log line of no interest
+  1:0   error  Missing "use strict" statement                 strict
+  5:10  error  'addOne' is defined but never used             no-unused-vars
+✖ 2 problems (2 errors, 0 warnings)
+```
+
+## Adding and Removing Problem Matchers
+
+Problem Matchers are enabled and removed via the toolkit [commands](commands.md#problem-matchers).
+
+## Duplicate Problem Matchers
+
+Registering two problem-matchers with the same owner will result in only the problem matcher registered last running.
+
+## Examples
+
+Some of the starter actions are already using problem matchers, for example:
+- [setup-node](https://github.com/actions/setup-node/tree/main/.github)
+- [setup-python](https://github.com/actions/setup-python/tree/main/.github)
+- [setup-go](https://github.com/actions/setup-go/tree/main/.github)
+- [setup-dotnet](https://github.com/actions/setup-dotnet/tree/main/.github)
+
+## Troubleshooting
+
+### Regular expression not matching
+
+Use ECMAScript regular expression syntax when testing patterns.
+
+### File property getting dropped
+
+[Enable debug logging](https://docs.github.com/en/actions/managing-workflow-runs/enabling-debug-logging) to determine why the file is getting dropped.
+
+This usually happens when the file does not exist or is not under the workflow repo.

docs/proxy-support.md

@@ -0,0 +1,10 @@
+# Proxy Server Support
+
+Self-hosted runners [can be configured](https://help.github.com/en/actions/hosting-your-own-runners/using-a-proxy-server-with-self-hosted-runners) to run behind a proxy server in enterprises.
+
+For actions to **just work** behind a proxy server:
+
+  1. Use [tool-cache] version >= 1.3.1
+  2. Optionally use [actions/http-client](https://github.com/actions/http-client)
+
+If you are using other http clients, refer to the [environment variables set by the runner](https://help.github.com/en/actions/hosting-your-own-runners/using-a-proxy-server-with-self-hosted-runners).

docs/specs/github-package.md

@@ -0,0 +1,100 @@
+# Github Package
+
+In order to support using actions to interact with GitHub, I propose adding a `github` package to the toolkit.
+
+Its main purpose will be to provide a hydrated GitHub context/Octokit client with some convenience functions. It is largely pulled from the GitHub utilities provided in https://github.com/JasonEtco/actions-toolkit, though it has been condensed.
+
+### Spec
+
+##### interfaces.ts
+
+```ts
+/*
+ * Interfaces
+ */
+ 
+export interface PayloadRepository {
+  [key: string]: any
+  full_name?: string
+  name: string
+  owner: {
+    [key: string]: any
+    login: string
+    name?: string
+  }
+  html_url?: string
+}
+
+export interface WebhookPayloadWithRepository {
+  [key: string]: any
+  repository?: PayloadRepository
+  issue?: {
+    [key: string]: any
+    number: number
+    html_url?: string
+    body?: string
+  }
+  pull_request?: {
+    [key: string]: any
+    number: number
+    html_url?: string
+    body?: string
+  }
+  sender?: {
+    [key: string]: any
+    type: string
+  }
+  action?: string
+  installation?: {
+    id: number
+    [key: string]: any
+  }
+}
+```
+
+##### context.ts
+
+Contains a GitHub context
+
+```ts
+export class Context {
+   /**
+   * Webhook payload object that triggered the workflow
+   */
+  public payload: WebhookPayloadWithRepository
+
+  /**
+   * Name of the event that triggered the workflow
+   */
+  public event: string
+  public sha: string
+  public ref: string
+  public workflow: string
+  public action: string
+  public actor: string
+  
+  /**
+   * Hydrate the context from the environment
+   */
+  constructor ()
+  
+  public get issue ()
+  
+  public get repo ()
+}
+
+```
+
+##### github.ts
+
+Contains a hydrated Octokit client
+
+```ts
+export class GithubClient extends Octokit {
+ // For making GraphQL requests
+ public graphql: (query: string, variables?: Variables) => Promise<GraphQlQueryResponse>
+ 
+ // Calls super and initializes graphql
+ constructor (token: string)
+}
+```

docs/specs/package-specs.md

@@ -6,7 +6,7 @@ In order to support the node-config action, I propose adding the following into
 
 Holds all the functions necessary for interacting with the runner/environment.
 
-```
+```ts
 // Logging functions
 export function debug(message: string): void
 export function warning(message: string): void
@@ -66,7 +66,7 @@ export function setFailed(message: string): void
 
 Holds all the functions necessary for file system manipulation (cli scenarios, not fs replacements):
 
-```
+```ts
 /**
  * Interface for cp/mv options
  */
@@ -132,7 +132,7 @@ export function which(tool: string, options?: WhichOptions): Promise<string>
 
 Holds all the functions necessary for running the tools node-config depends on (aka 7-zip and tar)
 
-```
+```ts
 /**
  * Interface for exec options
  */
@@ -155,7 +155,7 @@ export function exec(commandLine: string, args?: string[], options?: IExecOption
 
 Holds all the functions necessary for downloading and caching node.
 
-```
+```ts
 /**
  * Download a tool from an url and stream it into a file
  *

jest.config.js

@@ -4,7 +4,6 @@ module.exports = {
   roots: ['<rootDir>/packages'],
   testEnvironment: 'node',
   testMatch: ['**/__tests__/*.test.ts'],
-  testRunner: 'jest-circus/runner',
   transform: {
     '^.+\\.ts$': 'ts-jest'
   },

package.json

@@ -2,30 +2,31 @@
   "name": "root",
   "private": true,
   "scripts": {
+    "audit-all": "lerna run audit-moderate",
     "bootstrap": "lerna bootstrap",
     "build": "lerna run tsc",
     "check-all": "concurrently \"npm:format-check\" \"npm:lint\" \"npm:test\" \"npm:build -- -- --noEmit\"",
     "format": "prettier --write packages/**/*.ts",
     "format-check": "prettier --check packages/**/*.ts",
     "lint": "eslint packages/**/*.ts",
+    "lint-fix": "eslint packages/**/*.ts --fix",
     "new-package": "scripts/create-package",
-    "test": "jest",
-    "test-ci": "jest --testPathIgnorePatterns=\"<rootDir>/packages/exec/__tests__/exec.test.ts\""
+    "test": "jest --testTimeout 10000"
   },
   "devDependencies": {
-    "@types/jest": "^24.0.11",
-    "@types/node": "^11.13.5",
-    "@types/signale": "^1.2.1",
-    "@typescript-eslint/parser": "^1.9.0",
-    "concurrently": "^4.1.0",
-    "eslint": "^5.16.0",
-    "eslint-plugin-github": "^2.0.0",
-    "eslint-plugin-jest": "^22.5.1",
-    "jest": "^24.7.1",
-    "jest-circus": "^24.7.1",
-    "lerna": "^3.13.3",
-    "prettier": "^1.17.0",
-    "ts-jest": "^24.0.2",
-    "typescript": "^3.4.4"
+    "@types/jest": "^27.0.2",
+    "@types/node": "^12.20.13",
+    "@types/signale": "^1.4.1",
+    "@typescript-eslint/parser": "^4.0.0",
+    "concurrently": "^6.1.0",
+    "eslint": "^7.23.0",
+    "eslint-plugin-github": "^4.1.3",
+    "eslint-plugin-jest": "^22.21.0",
+    "flow-bin": "^0.115.0",
+    "jest": "^27.2.5",
+    "lerna": "^4.0.0",
+    "prettier": "^1.19.1",
+    "ts-jest": "^27.0.5",
+    "typescript": "^3.9.9"
   }
 }

packages/artifact/CONTRIBUTIONS.md

@@ -0,0 +1,30 @@
+# Contributions
+
+This package is used internally by the v2+ versions of [upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact). This package can also be used by other actions to interact with artifacts. Any changes or updates to this package will propagate updates to these actions so it is important that major changes or updates get properly tested. 
+
+Any issues or feature requests that are related to the artifact actions should be filled in the appropriate repo.
+
+A limited range of unit tests run as part of each PR when making changes to the artifact packages. For small contributions and fixes, they should be sufficient.
+
+If making large changes, there are a few scenarios that should be tested.
+
+- Uploading very large artifacts (large artifacts get compressed using gzip so compression/decompression must be tested)
+- Uploading artifacts with lots of small files (each file is uploaded with its own HTTP call, timeouts and non-success HTTP responses can be expected so they must be properly handled)
+- Uploading artifacts using a self-hosted runner (uploads and downloads behave differently due to extra latency)
+- Downloading a single artifact (large and small, if lots of small files are part of an artifact, timeouts and non-success HTTP responses can be expected)
+- Downloading all artifacts at once
+
+Large architectural changes can impact upload/download performance so it is important to separately run extra tests. We request that any large contributions/changes have extra detailed testing so we can verify performance and possible regressions.
+
+It is not possible to run end-to-end tests for artifacts as part of a PR in this repo because certain env variables such as `ACTIONS_RUNTIME_URL` are only available from the context of an action as opposed to a shell script. These env variables are needed in order to make the necessary API calls.
+
+# Testing
+
+Any easy way to test changes is to fork the artifact actions and to use `npm link` to test your changes.
+
+1. Fork the [upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact) repos
+2. Clone the forks locally
+3. With your local changes to the toolkit repo, type `npm link` after ensuring there are no errors when running `tsc`
+4. In the locally cloned fork, type `npm link @actions/artifact`
+4. Create a new release for your local fork using `tsc` and `npm run release` (this will create a new `dist/index.js` file using `@vercel/ncc`)
+5. Commit and push your local changes, you will then be able to test your changes with your forked action

packages/artifact/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright 2019 GitHub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/artifact/README.md

@@ -0,0 +1,213 @@
+# `@actions/artifact`
+
+## Usage
+
+You can use this package to interact with the actions artifacts.
+- [Upload an Artifact](#Upload-an-Artifact)
+- [Download a Single Artifact](#Download-a-Single-Artifact)
+- [Download All Artifacts](#Download-all-Artifacts)
+- [Additional Documentation](#Additional-Documentation)
+- [Contributions](#Contributions)
+
+Relative paths and absolute paths are both allowed. Relative paths are rooted against the current working directory.
+
+## Upload an Artifact
+
+Method Name: `uploadArtifact`
+
+#### Inputs
+ - `name`
+    - The name of the artifact that is being uploaded
+    - Required
+ - `files`
+    - A list of file paths that describe what should be uploaded as part of the artifact
+    - If a path is provided that does not exist, an error will be thrown
+    - Can be absolute or relative. Internally everything is normalized and resolved
+    - Required
+ - `rootDirectory`
+    - A file path that denotes the root directory of the files being uploaded. This path is used to strip the paths provided in `files` to control how they are uploaded and structured
+    - If a file specified in `files` is not in the `rootDirectory`, an error will be thrown
+    - Required
+ - `options`
+    - Extra options that allow for the customization of the upload behavior
+    - Optional
+
+#### Available Options
+
+ - `continueOnError`
+    - Indicates if the artifact upload should continue in the event a file fails to upload. If there is a error during upload, a partial artifact will always be created and available for download at the end. The `size` reported will be the amount of storage that the user or org will be charged for the partial artifact.
+    - If set to `false`, and an error is encountered, all other uploads will stop and any files that were queued will not be attempted to be uploaded. The partial artifact available will only include files up until the failure.
+    - If set to `true` and an error is encountered, the failed file will be skipped and ignored and all other queued files will be attempted to be uploaded. There will be an artifact available for download at the end with everything excluding the file that failed to upload
+    - Optional, defaults to `true` if not specified
+- `retentionDays`
+    - Duration after which artifact will expire in days
+    - Minimum value: 1
+    - Maximum 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 the server, and the upload process will continue. An input of 0 assumes default retention value.
+
+#### Example using Absolute File Paths
+
+```js
+const artifact = require('@actions/artifact');
+const artifactClient = artifact.create()
+const artifactName = 'my-artifact';
+const files = [
+    '/home/user/files/plz-upload/file1.txt',
+    '/home/user/files/plz-upload/file2.txt',
+    '/home/user/files/plz-upload/dir/file3.txt'
+]
+const rootDirectory = '/home/user/files/plz-upload'
+const options = {
+    continueOnError: true
+}
+
+const uploadResult = await artifactClient.uploadArtifact(artifactName, files, rootDirectory, options)
+```
+
+#### Example using Relative File Paths
+```js
+// Assuming the current working directory is /home/user/files/plz-upload
+const artifact = require('@actions/artifact');
+const artifactClient = artifact.create()
+const artifactName = 'my-artifact';
+const files = [
+    'file1.txt',
+    'file2.txt',
+    'dir/file3.txt'
+]
+
+const rootDirectory = '.' // Also possible to use __dirname
+const options = {
+    continueOnError: false
+}
+
+const uploadResponse = await artifactClient.uploadArtifact(artifactName, files, rootDirectory, options)
+```
+
+#### Upload Result
+
+The returned `UploadResponse` will contain the following information
+
+- `artifactName`
+    - The name of the artifact that was uploaded
+- `artifactItems`
+    - A list of all files that describe what is uploaded if there are no errors encountered. Usually this will be equal to the inputted `files` with the exception of empty directories (will not be uploaded)
+- `size`
+    - Total size of the artifact that was uploaded in bytes
+- `failedItems`
+    - A list of items that were not uploaded successfully (this will include queued items that were not uploaded if `continueOnError` is set to false). This is a subset of `artifactItems`
+
+## Download a Single Artifact
+
+Method Name: `downloadArtifact`
+
+#### Inputs
+ - `name`
+    - The name of the artifact to download
+    - Required
+ - `path`
+    - Path that denotes where the artifact will be downloaded to
+    - Optional. Defaults to the GitHub workspace directory(`$GITHUB_WORKSPACE`) if not specified
+ - `options`
+    - Extra options that allow for the customization of the download behavior
+    - Optional
+
+
+#### Available Options
+
+ - `createArtifactFolder`
+    - Specifies if a folder (the artifact name) is created for the artifact that is downloaded (contents downloaded into this folder),
+    - Optional. Defaults to false if not specified
+
+#### Example
+
+```js
+const artifact = require('@actions/artifact');
+const artifactClient = artifact.create()
+const artifactName = 'my-artifact';
+const path = 'some/directory'
+const options = {
+    createArtifactFolder: false
+}
+
+const downloadResponse = await artifactClient.downloadArtifact(artifactName, path, options)
+
+// Post download, the directory structure will look like this
+/some
+    /directory
+        /file1.txt
+        /file2.txt
+        /dir
+            /file3.txt
+
+// If createArtifactFolder is set to true, the directory structure will look like this
+/some
+    /directory
+        /my-artifact
+            /file1.txt
+            /file2.txt
+            /dir
+                /file3.txt
+```
+
+#### Download Response
+
+The returned `DownloadResponse` will contain the following information
+
+  - `artifactName`
+    - The name of the artifact that was downloaded
+  - `downloadPath`
+    - The full Path to where the artifact was downloaded
+
+
+## Download All Artifacts
+
+Method Name: `downloadAllArtifacts`
+
+#### Inputs
+ - `path`
+    - Path that denotes where the artifact will be downloaded to
+    - Optional. Defaults to the GitHub workspace directory(`$GITHUB_WORKSPACE`) if not specified
+
+```js
+const artifact = require('@actions/artifact');
+const artifactClient = artifact.create();
+const downloadResponse = await artifactClient.downloadAllArtifacts();
+
+// output result
+for (response in downloadResponse) {
+    console.log(response.artifactName);
+    console.log(response.downloadPath);
+}
+```
+
+Because there are multiple artifacts, an extra directory (denoted by the name of the artifact) will be created for each artifact in the path. With 2 artifacts(`my-artifact-1` and `my-artifact-2` for example) and the default path, the directory structure will be as follows:
+```js
+/GITHUB_WORKSPACE
+    /my-artifact-1
+        / .. contents of `my-artifact-1`
+    /my-artifact-2
+        / .. contents of `my-artifact-2`
+```
+
+#### Download Result
+
+An array will be returned that describes the results for downloading all artifacts. The number of items in the array indicates the number of artifacts that were downloaded.
+
+Each artifact will have the same `DownloadResponse` as if it was individually downloaded
+  - `artifactName`
+    - The name of the artifact that was downloaded
+  - `downloadPath`
+    - The full Path to where the artifact was downloaded
+
+## Additional Documentation
+
+Check out [additional-information](docs/additional-information.md) for extra documentation around usage, restrictions and behavior.
+
+Check out [implementation-details](docs/implementation-details.md) for extra information about the implementation of this package.
+
+## Contributions
+
+See [contributor guidelines](https://github.com/actions/toolkit/blob/main/.github/CONTRIBUTING.md) for general guidelines and information about toolkit contributions.
+
+For contributions related to this package, see [artifact contributions](CONTRIBUTIONS.md) for more information.

packages/artifact/RELEASES.md

@@ -0,0 +1,63 @@
+# @actions/artifact Releases
+
+### 0.1.0
+
+- Initial release
+
+### 0.2.0
+
+- Fixes to TCP connections not closing
+- GZip file compression to speed up downloads
+- Improved logging and output
+- Extra documentation
+
+### 0.3.0
+
+- Fixes to gzip decompression when downloading artifacts
+- Support handling 429 response codes
+- Improved download experience when dealing with empty files
+- Exponential backoff when retryable status codes are encountered
+- Clearer error message if storage quota has been reached
+- Improved logging and output during artifact download
+
+### 0.3.1
+
+- Fix to ensure temporary gzip files get correctly deleted during artifact upload
+- Remove spaces as a forbidden character during upload
+
+### 0.3.2
+
+- Fix to ensure readstreams get correctly reset in the event of a retry
+
+### 0.3.3
+
+- Increase chunk size during upload from 4MB to 8MB
+- Improve user-agent strings during API calls to help internally diagnose issues
+
+### 0.3.5
+
+- Retry in the event of a 413 response
+
+### 0.4.0
+
+- Add option to specify custom retentions on artifacts
+
+### 0.4.1
+
+- Update to latest @actions/core version
+
+### 0.4.2
+
+- Improved retry-ability when a partial artifact download is encountered
+
+### 0.5.0
+
+- Improved retry-ability for all http calls during artifact upload and download if an error is encountered
+
+### 0.5.1
+
+- Bump @actions/http-client to version 1.0.11 to fix proxy related issues during artifact upload and download
+
+### 0.5.2
+
+- Add HTTP 500 as a retryable status code for artifact upload and download.

packages/artifact/__tests__/ci-test-action/action.yml

@@ -0,0 +1,5 @@
+name: 'Set env variables'
+description: 'Sets certain env variables so that e2e artifact upload and download can be tested in a shell'
+runs:
+  using: 'node12'
+  main: 'index.js'

packages/artifact/__tests__/ci-test-action/index.js

@@ -0,0 +1,14 @@
+// Certain env variables are not set by default in a shell context and are only available in a node context from a running action
+// In order to be able to upload and download artifacts e2e in a shell when running CI tests, we need these env variables set
+const fs = require('fs');
+const os = require('os');
+const filePath = process.env[`GITHUB_ENV`]
+fs.appendFileSync(filePath, `ACTIONS_RUNTIME_URL=${process.env.ACTIONS_RUNTIME_URL}${os.EOL}`, {
+    encoding: 'utf8'
+})
+fs.appendFileSync(filePath, `ACTIONS_RUNTIME_TOKEN=${process.env.ACTIONS_RUNTIME_TOKEN}${os.EOL}`, {
+    encoding: 'utf8'
+})
+fs.appendFileSync(filePath, `GITHUB_RUN_ID=${process.env.GITHUB_RUN_ID}${os.EOL}`, {
+    encoding: 'utf8'
+})

packages/artifact/__tests__/download-specification.test.ts

@@ -0,0 +1,552 @@
+import * as path from 'path'
+import * as core from '@actions/core'
+import {URL} from 'url'
+import {getDownloadSpecification} from '../src/internal/download-specification'
+import {ContainerEntry} from '../src/internal/contracts'
+
+const artifact1Name = 'my-artifact'
+const artifact2Name = 'my-artifact-extra'
+
+// Populating with only the information that is necessary
+function getPartialContainerEntry(): ContainerEntry {
+  return {
+    containerId: 10,
+    scopeIdentifier: '00000000-0000-0000-0000-000000000000',
+    path: 'ADD_INFORMATION',
+    itemType: 'ADD_INFORMATION',
+    status: 'created',
+    dateCreated: '2020-02-06T22:13:35.373Z',
+    dateLastModified: '2020-02-06T22:13:35.453Z',
+    createdBy: '82f0bf89-6e55-4e5a-b8b6-f75eb992578c',
+    lastModifiedBy: '82f0bf89-6e55-4e5a-b8b6-f75eb992578c',
+    itemLocation: 'ADD_INFORMATION',
+    contentLocation: 'ADD_INFORMATION',
+    contentId: '',
+    fileLength: 100
+  }
+}
+
+function createFileEntry(entryPath: string): ContainerEntry {
+  const newFileEntry = getPartialContainerEntry()
+  newFileEntry.path = entryPath
+  newFileEntry.itemType = 'file'
+  newFileEntry.itemLocation = createItemLocation(entryPath)
+  newFileEntry.contentLocation = createContentLocation(entryPath)
+  return newFileEntry
+}
+
+function createDirectoryEntry(directoryPath: string): ContainerEntry {
+  const newDirectoryEntry = getPartialContainerEntry()
+  newDirectoryEntry.path = directoryPath
+  newDirectoryEntry.itemType = 'folder'
+  newDirectoryEntry.itemLocation = createItemLocation(directoryPath)
+  newDirectoryEntry.contentLocation = createContentLocation(directoryPath)
+  return newDirectoryEntry
+}
+
+function createItemLocation(relativePath: string): string {
+  const itemLocation = new URL(
+    'https://testing/_apis/resources/Containers/10000'
+  )
+  itemLocation.searchParams.append('itemPath', relativePath)
+  itemLocation.searchParams.append('metadata', 'true')
+  return itemLocation.toString()
+}
+
+function createContentLocation(relativePath: string): string {
+  const itemLocation = new URL(
+    'https://testing/_apis/resources/Containers/10000'
+  )
+  itemLocation.searchParams.append('itemPath', relativePath)
+  return itemLocation.toString()
+}
+
+/*
+    Represents a set of container entries for two artifacts with the following directory structure
+
+    /my-artifact
+        /file1.txt
+        /file2.txt
+        /dir1
+            /file3.txt
+            /dir2
+                /dir3
+                    /dir4
+                        file4.txt
+                        file5.txt (no length property)
+                        file6.txt (empty file)
+    /my-artifact-extra
+        /file1.txt
+*/
+
+// main artifact
+const file1Path = path.join(artifact1Name, 'file1.txt')
+const file2Path = path.join(artifact1Name, 'file2.txt')
+const dir1Path = path.join(artifact1Name, 'dir1')
+const file3Path = path.join(dir1Path, 'file3.txt')
+const dir2Path = path.join(dir1Path, 'dir2')
+const dir3Path = path.join(dir2Path, 'dir3')
+const dir4Path = path.join(dir3Path, 'dir4')
+const file4Path = path.join(dir4Path, 'file4.txt')
+const file5Path = path.join(dir4Path, 'file5.txt')
+const file6Path = path.join(dir4Path, 'file6.txt')
+
+const rootDirectoryEntry = createDirectoryEntry(artifact1Name)
+const directoryEntry1 = createDirectoryEntry(dir1Path)
+const directoryEntry2 = createDirectoryEntry(dir2Path)
+const directoryEntry3 = createDirectoryEntry(dir3Path)
+const directoryEntry4 = createDirectoryEntry(dir4Path)
+const fileEntry1 = createFileEntry(file1Path)
+const fileEntry2 = createFileEntry(file2Path)
+const fileEntry3 = createFileEntry(file3Path)
+const fileEntry4 = createFileEntry(file4Path)
+
+const missingLengthFileEntry = createFileEntry(file5Path)
+missingLengthFileEntry.fileLength = undefined // one file does not have a fileLength
+const emptyLengthFileEntry = createFileEntry(file6Path)
+emptyLengthFileEntry.fileLength = 0 // empty file path
+
+// extra artifact
+const artifact2File1Path = path.join(artifact2Name, 'file1.txt')
+const rootDirectoryEntry2 = createDirectoryEntry(artifact2Name)
+const extraFileEntry = createFileEntry(artifact2File1Path)
+
+const artifactContainerEntries: ContainerEntry[] = [
+  rootDirectoryEntry,
+  fileEntry1,
+  fileEntry2,
+  directoryEntry1,
+  fileEntry3,
+  directoryEntry2,
+  directoryEntry3,
+  directoryEntry4,
+  fileEntry4,
+  missingLengthFileEntry,
+  emptyLengthFileEntry,
+  rootDirectoryEntry2,
+  extraFileEntry
+]
+
+describe('Search', () => {
+  beforeAll(async () => {
+    // mock all output so that there is less noise when running tests
+    jest.spyOn(console, 'log').mockImplementation(() => {})
+    jest.spyOn(core, 'debug').mockImplementation(() => {})
+    jest.spyOn(core, 'info').mockImplementation(() => {})
+    jest.spyOn(core, 'warning').mockImplementation(() => {})
+  })
+
+  it('Download Specification - Absolute Path with no root directory', () => {
+    const testDownloadPath = path.join(
+      __dirname,
+      'some',
+      'destination',
+      'folder'
+    )
+
+    const specification = getDownloadSpecification(
+      artifact1Name,
+      artifactContainerEntries,
+      testDownloadPath,
+      false
+    )
+
+    expect(specification.rootDownloadLocation).toEqual(testDownloadPath)
+    expect(specification.filesToDownload.length).toEqual(5)
+
+    const item1ExpectedTargetPath = path.join(testDownloadPath, 'file1.txt')
+    const item2ExpectedTargetPath = path.join(testDownloadPath, 'file2.txt')
+    const item3ExpectedTargetPath = path.join(
+      testDownloadPath,
+      'dir1',
+      'file3.txt'
+    )
+    const item4ExpectedTargetPath = path.join(
+      testDownloadPath,
+      'dir1',
+      'dir2',
+      'dir3',
+      'dir4',
+      'file4.txt'
+    )
+    const item5ExpectedTargetPath = path.join(
+      testDownloadPath,
+      'dir1',
+      'dir2',
+      'dir3',
+      'dir4',
+      'file5.txt'
+    )
+    const item6ExpectedTargetPath = path.join(
+      testDownloadPath,
+      'dir1',
+      'dir2',
+      'dir3',
+      'dir4',
+      'file6.txt'
+    )
+
+    const targetLocations = specification.filesToDownload.map(
+      item => item.targetPath
+    )
+    expect(targetLocations).toContain(item1ExpectedTargetPath)
+    expect(targetLocations).toContain(item2ExpectedTargetPath)
+    expect(targetLocations).toContain(item3ExpectedTargetPath)
+    expect(targetLocations).toContain(item4ExpectedTargetPath)
+    expect(targetLocations).toContain(item5ExpectedTargetPath)
+
+    for (const downloadItem of specification.filesToDownload) {
+      if (downloadItem.targetPath === item1ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file1Path)
+        )
+      } else if (downloadItem.targetPath === item2ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file2Path)
+        )
+      } else if (downloadItem.targetPath === item3ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file3Path)
+        )
+      } else if (downloadItem.targetPath === item4ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file4Path)
+        )
+      } else if (downloadItem.targetPath === item5ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file5Path)
+        )
+      } else {
+        throw new Error('this should never be reached')
+      }
+    }
+
+    expect(specification.directoryStructure.length).toEqual(3)
+    expect(specification.directoryStructure).toContain(testDownloadPath)
+    expect(specification.directoryStructure).toContain(
+      path.join(testDownloadPath, 'dir1')
+    )
+    expect(specification.directoryStructure).toContain(
+      path.join(testDownloadPath, 'dir1', 'dir2', 'dir3', 'dir4')
+    )
+
+    expect(specification.emptyFilesToCreate.length).toEqual(1)
+    expect(specification.emptyFilesToCreate).toContain(item6ExpectedTargetPath)
+  })
+
+  it('Download Specification - Relative Path with no root directory', () => {
+    const testDownloadPath = path.join('some', 'destination', 'folder')
+
+    const specification = getDownloadSpecification(
+      artifact1Name,
+      artifactContainerEntries,
+      testDownloadPath,
+      false
+    )
+
+    expect(specification.rootDownloadLocation).toEqual(testDownloadPath)
+    expect(specification.filesToDownload.length).toEqual(5)
+
+    const item1ExpectedTargetPath = path.join(testDownloadPath, 'file1.txt')
+    const item2ExpectedTargetPath = path.join(testDownloadPath, 'file2.txt')
+    const item3ExpectedTargetPath = path.join(
+      testDownloadPath,
+      'dir1',
+      'file3.txt'
+    )
+    const item4ExpectedTargetPath = path.join(
+      testDownloadPath,
+      'dir1',
+      'dir2',
+      'dir3',
+      'dir4',
+      'file4.txt'
+    )
+    const item5ExpectedTargetPath = path.join(
+      testDownloadPath,
+      'dir1',
+      'dir2',
+      'dir3',
+      'dir4',
+      'file5.txt'
+    )
+    const item6ExpectedTargetPath = path.join(
+      testDownloadPath,
+      'dir1',
+      'dir2',
+      'dir3',
+      'dir4',
+      'file6.txt'
+    )
+
+    const targetLocations = specification.filesToDownload.map(
+      item => item.targetPath
+    )
+    expect(targetLocations).toContain(item1ExpectedTargetPath)
+    expect(targetLocations).toContain(item2ExpectedTargetPath)
+    expect(targetLocations).toContain(item3ExpectedTargetPath)
+    expect(targetLocations).toContain(item4ExpectedTargetPath)
+    expect(targetLocations).toContain(item5ExpectedTargetPath)
+
+    for (const downloadItem of specification.filesToDownload) {
+      if (downloadItem.targetPath === item1ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file1Path)
+        )
+      } else if (downloadItem.targetPath === item2ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file2Path)
+        )
+      } else if (downloadItem.targetPath === item3ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file3Path)
+        )
+      } else if (downloadItem.targetPath === item4ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file4Path)
+        )
+      } else if (downloadItem.targetPath === item5ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file5Path)
+        )
+      } else {
+        throw new Error('this should never be reached')
+      }
+    }
+
+    expect(specification.directoryStructure.length).toEqual(3)
+    expect(specification.directoryStructure).toContain(testDownloadPath)
+    expect(specification.directoryStructure).toContain(
+      path.join(testDownloadPath, 'dir1')
+    )
+    expect(specification.directoryStructure).toContain(
+      path.join(testDownloadPath, 'dir1', 'dir2', 'dir3', 'dir4')
+    )
+
+    expect(specification.emptyFilesToCreate.length).toEqual(1)
+    expect(specification.emptyFilesToCreate).toContain(item6ExpectedTargetPath)
+  })
+
+  it('Download Specification - Absolute Path with root directory', () => {
+    const testDownloadPath = path.join(
+      __dirname,
+      'some',
+      'destination',
+      'folder'
+    )
+
+    const specification = getDownloadSpecification(
+      artifact1Name,
+      artifactContainerEntries,
+      testDownloadPath,
+      true
+    )
+
+    expect(specification.rootDownloadLocation).toEqual(
+      path.join(testDownloadPath, artifact1Name)
+    )
+    expect(specification.filesToDownload.length).toEqual(5)
+
+    const item1ExpectedTargetPath = path.join(
+      testDownloadPath,
+      artifact1Name,
+      'file1.txt'
+    )
+    const item2ExpectedTargetPath = path.join(
+      testDownloadPath,
+      artifact1Name,
+      'file2.txt'
+    )
+    const item3ExpectedTargetPath = path.join(
+      testDownloadPath,
+      artifact1Name,
+      'dir1',
+      'file3.txt'
+    )
+    const item4ExpectedTargetPath = path.join(
+      testDownloadPath,
+      artifact1Name,
+      'dir1',
+      'dir2',
+      'dir3',
+      'dir4',
+      'file4.txt'
+    )
+    const item5ExpectedTargetPath = path.join(
+      testDownloadPath,
+      artifact1Name,
+      'dir1',
+      'dir2',
+      'dir3',
+      'dir4',
+      'file5.txt'
+    )
+    const item6ExpectedTargetPath = path.join(
+      testDownloadPath,
+      artifact1Name,
+      'dir1',
+      'dir2',
+      'dir3',
+      'dir4',
+      'file6.txt'
+    )
+
+    const targetLocations = specification.filesToDownload.map(
+      item => item.targetPath
+    )
+    expect(targetLocations).toContain(item1ExpectedTargetPath)
+    expect(targetLocations).toContain(item2ExpectedTargetPath)
+    expect(targetLocations).toContain(item3ExpectedTargetPath)
+    expect(targetLocations).toContain(item4ExpectedTargetPath)
+    expect(targetLocations).toContain(item5ExpectedTargetPath)
+
+    for (const downloadItem of specification.filesToDownload) {
+      if (downloadItem.targetPath === item1ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file1Path)
+        )
+      } else if (downloadItem.targetPath === item2ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file2Path)
+        )
+      } else if (downloadItem.targetPath === item3ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file3Path)
+        )
+      } else if (downloadItem.targetPath === item4ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file4Path)
+        )
+      } else if (downloadItem.targetPath === item5ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file5Path)
+        )
+      } else {
+        throw new Error('this should never be reached')
+      }
+    }
+
+    expect(specification.directoryStructure.length).toEqual(3)
+    expect(specification.directoryStructure).toContain(
+      path.join(testDownloadPath, artifact1Name)
+    )
+    expect(specification.directoryStructure).toContain(
+      path.join(testDownloadPath, dir1Path)
+    )
+    expect(specification.directoryStructure).toContain(
+      path.join(testDownloadPath, dir4Path)
+    )
+
+    expect(specification.emptyFilesToCreate.length).toEqual(1)
+    expect(specification.emptyFilesToCreate).toContain(item6ExpectedTargetPath)
+  })
+
+  it('Download Specification - Relative Path with root directory', () => {
+    const testDownloadPath = path.join('some', 'destination', 'folder')
+
+    const specification = getDownloadSpecification(
+      artifact1Name,
+      artifactContainerEntries,
+      testDownloadPath,
+      true
+    )
+
+    expect(specification.rootDownloadLocation).toEqual(
+      path.join(testDownloadPath, artifact1Name)
+    )
+    expect(specification.filesToDownload.length).toEqual(5)
+
+    const item1ExpectedTargetPath = path.join(
+      testDownloadPath,
+      artifact1Name,
+      'file1.txt'
+    )
+    const item2ExpectedTargetPath = path.join(
+      testDownloadPath,
+      artifact1Name,
+      'file2.txt'
+    )
+    const item3ExpectedTargetPath = path.join(
+      testDownloadPath,
+      artifact1Name,
+      'dir1',
+      'file3.txt'
+    )
+    const item4ExpectedTargetPath = path.join(
+      testDownloadPath,
+      artifact1Name,
+      'dir1',
+      'dir2',
+      'dir3',
+      'dir4',
+      'file4.txt'
+    )
+    const item5ExpectedTargetPath = path.join(
+      testDownloadPath,
+      artifact1Name,
+      'dir1',
+      'dir2',
+      'dir3',
+      'dir4',
+      'file5.txt'
+    )
+    const item6ExpectedTargetPath = path.join(
+      testDownloadPath,
+      artifact1Name,
+      'dir1',
+      'dir2',
+      'dir3',
+      'dir4',
+      'file6.txt'
+    )
+
+    const targetLocations = specification.filesToDownload.map(
+      item => item.targetPath
+    )
+    expect(targetLocations).toContain(item1ExpectedTargetPath)
+    expect(targetLocations).toContain(item2ExpectedTargetPath)
+    expect(targetLocations).toContain(item3ExpectedTargetPath)
+    expect(targetLocations).toContain(item4ExpectedTargetPath)
+    expect(targetLocations).toContain(item5ExpectedTargetPath)
+
+    for (const downloadItem of specification.filesToDownload) {
+      if (downloadItem.targetPath === item1ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file1Path)
+        )
+      } else if (downloadItem.targetPath === item2ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file2Path)
+        )
+      } else if (downloadItem.targetPath === item3ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file3Path)
+        )
+      } else if (downloadItem.targetPath === item4ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file4Path)
+        )
+      } else if (downloadItem.targetPath === item5ExpectedTargetPath) {
+        expect(downloadItem.sourceLocation).toEqual(
+          createContentLocation(file5Path)
+        )
+      } else {
+        throw new Error('this should never be reached')
+      }
+    }
+
+    expect(specification.directoryStructure.length).toEqual(3)
+    expect(specification.directoryStructure).toContain(
+      path.join(testDownloadPath, artifact1Name)
+    )
+    expect(specification.directoryStructure).toContain(
+      path.join(testDownloadPath, dir1Path)
+    )
+    expect(specification.directoryStructure).toContain(
+      path.join(testDownloadPath, dir4Path)
+    )
+
+    expect(specification.emptyFilesToCreate.length).toEqual(1)
+    expect(specification.emptyFilesToCreate).toContain(item6ExpectedTargetPath)
+  })
+})

packages/artifact/__tests__/download.test.ts

@@ -0,0 +1,490 @@
+import * as core from '@actions/core'
+import * as http from 'http'
+import * as io from '../../io/src/io'
+import * as net from 'net'
+import * as path from 'path'
+import * as configVariables from '../src/internal/config-variables'
+import {promises as fs} from 'fs'
+import {DownloadItem} from '../src/internal/download-specification'
+import {HttpClient, HttpClientResponse} from '@actions/http-client'
+import {DownloadHttpClient} from '../src/internal/download-http-client'
+import {
+  ListArtifactsResponse,
+  QueryArtifactResponse
+} from '../src/internal/contracts'
+import * as stream from 'stream'
+import {gzip} from 'zlib'
+import {promisify} from 'util'
+
+const root = path.join(__dirname, '_temp', 'artifact-download-tests')
+const defaultEncoding = 'utf8'
+
+jest.mock('../src/internal/config-variables')
+jest.mock('@actions/http-client')
+
+describe('Download Tests', () => {
+  beforeAll(async () => {
+    await io.rmRF(root)
+    await fs.mkdir(path.join(root), {
+      recursive: true
+    })
+
+    // mock all output so that there is less noise when running tests
+    jest.spyOn(console, 'log').mockImplementation(() => {})
+    jest.spyOn(core, 'debug').mockImplementation(() => {})
+    jest.spyOn(core, 'info').mockImplementation(() => {})
+    jest.spyOn(core, 'warning').mockImplementation(() => {})
+    jest.spyOn(core, 'error').mockImplementation(() => {})
+  })
+
+  /**
+   * Test Listing Artifacts
+   */
+  it('List Artifacts - Success', async () => {
+    setupSuccessfulListArtifactsResponse()
+    const downloadHttpClient = new DownloadHttpClient()
+    const artifacts = await downloadHttpClient.listArtifacts()
+    expect(artifacts.count).toEqual(2)
+
+    const artifactNames = artifacts.value.map(item => item.name)
+    expect(artifactNames).toContain('artifact1-name')
+    expect(artifactNames).toContain('artifact2-name')
+
+    for (const artifact of artifacts.value) {
+      if (artifact.name === 'artifact1-name') {
+        expect(artifact.url).toEqual(
+          `${configVariables.getRuntimeUrl()}_apis/pipelines/1/runs/1/artifacts?artifactName=artifact1-name`
+        )
+      } else if (artifact.name === 'artifact2-name') {
+        expect(artifact.url).toEqual(
+          `${configVariables.getRuntimeUrl()}_apis/pipelines/1/runs/1/artifacts?artifactName=artifact2-name`
+        )
+      } else {
+        throw new Error(
+          'Invalid artifact combination. This should never be reached'
+        )
+      }
+    }
+  })
+
+  it('List Artifacts - Failure', async () => {
+    setupFailedResponse()
+    const downloadHttpClient = new DownloadHttpClient()
+    expect(downloadHttpClient.listArtifacts()).rejects.toThrow(
+      'List Artifacts failed: Artifact service responded with 400'
+    )
+  })
+
+  /**
+   * Test Container Items
+   */
+  it('Container Items - Success', async () => {
+    setupSuccessfulContainerItemsResponse()
+    const downloadHttpClient = new DownloadHttpClient()
+    const response = await downloadHttpClient.getContainerItems(
+      'artifact-name',
+      configVariables.getRuntimeUrl()
+    )
+    expect(response.count).toEqual(2)
+
+    const itemPaths = response.value.map(item => item.path)
+    expect(itemPaths).toContain('artifact-name')
+    expect(itemPaths).toContain('artifact-name/file1.txt')
+
+    for (const containerEntry of response.value) {
+      if (containerEntry.path === 'artifact-name') {
+        expect(containerEntry.itemType).toEqual('folder')
+      } else if (containerEntry.path === 'artifact-name/file1.txt') {
+        expect(containerEntry.itemType).toEqual('file')
+      } else {
+        throw new Error(
+          'Invalid container combination. This should never be reached'
+        )
+      }
+    }
+  })
+
+  it('Container Items - Failure', async () => {
+    setupFailedResponse()
+    const downloadHttpClient = new DownloadHttpClient()
+    expect(
+      downloadHttpClient.getContainerItems(
+        'artifact-name',
+        configVariables.getRuntimeUrl()
+      )
+    ).rejects.toThrow(
+      `Get Container Items failed: Artifact service responded with 400`
+    )
+  })
+
+  it('Test downloading an individual artifact with gzip', async () => {
+    const fileContents = Buffer.from(
+      'gzip worked on the first try\n',
+      defaultEncoding
+    )
+    const targetPath = path.join(root, 'FileA.txt')
+
+    setupDownloadItemResponse(fileContents, true, 200, false, false)
+    const downloadHttpClient = new DownloadHttpClient()
+
+    const items: DownloadItem[] = []
+    items.push({
+      sourceLocation: `${configVariables.getRuntimeUrl()}_apis/resources/Containers/13?itemPath=my-artifact%2FFileA.txt`,
+      targetPath
+    })
+
+    await expect(
+      downloadHttpClient.downloadSingleArtifact(items)
+    ).resolves.not.toThrow()
+
+    await checkDestinationFile(targetPath, fileContents)
+  })
+
+  it('Test downloading an individual artifact without gzip', async () => {
+    const fileContents = Buffer.from(
+      'plaintext worked on the first try\n',
+      defaultEncoding
+    )
+    const targetPath = path.join(root, 'FileB.txt')
+
+    setupDownloadItemResponse(fileContents, false, 200, false, false)
+    const downloadHttpClient = new DownloadHttpClient()
+
+    const items: DownloadItem[] = []
+    items.push({
+      sourceLocation: `${configVariables.getRuntimeUrl()}_apis/resources/Containers/13?itemPath=my-artifact%2FFileB.txt`,
+      targetPath
+    })
+
+    await expect(
+      downloadHttpClient.downloadSingleArtifact(items)
+    ).resolves.not.toThrow()
+
+    await checkDestinationFile(targetPath, fileContents)
+  })
+
+  it('Test retryable status codes during artifact download', async () => {
+    // The first http response should return a retryable status call while the subsequent call should return a 200 so
+    // the download should successfully finish
+    const retryableStatusCodes = [429, 500, 502, 503, 504]
+    for (const statusCode of retryableStatusCodes) {
+      const fileContents = Buffer.from('try, try again\n', defaultEncoding)
+      const targetPath = path.join(root, `FileC-${statusCode}.txt`)
+
+      setupDownloadItemResponse(fileContents, false, statusCode, false, true)
+      const downloadHttpClient = new DownloadHttpClient()
+
+      const items: DownloadItem[] = []
+      items.push({
+        sourceLocation: `${configVariables.getRuntimeUrl()}_apis/resources/Containers/13?itemPath=my-artifact%2FFileC.txt`,
+        targetPath
+      })
+
+      await expect(
+        downloadHttpClient.downloadSingleArtifact(items)
+      ).resolves.not.toThrow()
+
+      await checkDestinationFile(targetPath, fileContents)
+    }
+  })
+
+  it('Test retry on truncated response with gzip', async () => {
+    const fileContents = Buffer.from(
+      'Sometimes gunzip fails on the first try\n',
+      defaultEncoding
+    )
+    const targetPath = path.join(root, 'FileD.txt')
+
+    setupDownloadItemResponse(fileContents, true, 200, true, true)
+    const downloadHttpClient = new DownloadHttpClient()
+
+    const items: DownloadItem[] = []
+    items.push({
+      sourceLocation: `${configVariables.getRuntimeUrl()}_apis/resources/Containers/13?itemPath=my-artifact%2FFileD.txt`,
+      targetPath
+    })
+
+    await expect(
+      downloadHttpClient.downloadSingleArtifact(items)
+    ).resolves.not.toThrow()
+
+    await checkDestinationFile(targetPath, fileContents)
+  })
+
+  it('Test retry on truncated response without gzip', async () => {
+    const fileContents = Buffer.from(
+      'You have to inspect the content-length header to know if you got everything\n',
+      defaultEncoding
+    )
+    const targetPath = path.join(root, 'FileE.txt')
+
+    setupDownloadItemResponse(fileContents, false, 200, true, true)
+    const downloadHttpClient = new DownloadHttpClient()
+
+    const items: DownloadItem[] = []
+    items.push({
+      sourceLocation: `${configVariables.getRuntimeUrl()}_apis/resources/Containers/13?itemPath=my-artifact%2FFileD.txt`,
+      targetPath
+    })
+
+    await expect(
+      downloadHttpClient.downloadSingleArtifact(items)
+    ).resolves.not.toThrow()
+
+    await checkDestinationFile(targetPath, fileContents)
+  })
+
+  /**
+   * Helper used to setup mocking for the HttpClient
+   */
+  async function emptyMockReadBody(): Promise<string> {
+    return new Promise(resolve => {
+      resolve()
+    })
+  }
+
+  /**
+   * Setups up HTTP GET response for a successful listArtifacts() call
+   */
+  function setupSuccessfulListArtifactsResponse(): void {
+    jest.spyOn(HttpClient.prototype, 'get').mockImplementationOnce(async () => {
+      const mockMessage = new http.IncomingMessage(new net.Socket())
+      let mockReadBody = emptyMockReadBody
+
+      mockMessage.statusCode = 201
+      const response: ListArtifactsResponse = {
+        count: 2,
+        value: [
+          {
+            containerId: '13',
+            size: -1,
+            signedContent: 'false',
+            fileContainerResourceUrl: `${configVariables.getRuntimeUrl()}_apis/resources/Containers/13`,
+            type: 'actions_storage',
+            name: 'artifact1-name',
+            url: `${configVariables.getRuntimeUrl()}_apis/pipelines/1/runs/1/artifacts?artifactName=artifact1-name`
+          },
+          {
+            containerId: '13',
+            size: -1,
+            signedContent: 'false',
+            fileContainerResourceUrl: `${configVariables.getRuntimeUrl()}_apis/resources/Containers/13`,
+            type: 'actions_storage',
+            name: 'artifact2-name',
+            url: `${configVariables.getRuntimeUrl()}_apis/pipelines/1/runs/1/artifacts?artifactName=artifact2-name`
+          }
+        ]
+      }
+      const returnData: string = JSON.stringify(response, null, 2)
+      mockReadBody = async function(): Promise<string> {
+        return new Promise(resolve => {
+          resolve(returnData)
+        })
+      }
+
+      return new Promise<HttpClientResponse>(resolve => {
+        resolve({
+          message: mockMessage,
+          readBody: mockReadBody
+        })
+      })
+    })
+  }
+
+  /**
+   * Setups up HTTP GET response for downloading items
+   * @param isGzip is the downloaded item gzip encoded
+   * @param firstHttpResponseCode the http response code that should be returned
+   */
+  function setupDownloadItemResponse(
+    fileContents: Buffer,
+    isGzip: boolean,
+    firstHttpResponseCode: number,
+    truncateFirstResponse: boolean,
+    retryExpected: boolean
+  ): void {
+    const spyInstance = jest
+      .spyOn(HttpClient.prototype, 'get')
+      .mockImplementationOnce(async () => {
+        if (firstHttpResponseCode === 200) {
+          const fullResponse = await constructResponse(isGzip, fileContents)
+          const actualResponse = truncateFirstResponse
+            ? fullResponse.subarray(0, 3)
+            : fullResponse
+
+          return {
+            message: getDownloadResponseMessage(
+              firstHttpResponseCode,
+              isGzip,
+              fullResponse.length,
+              actualResponse
+            ),
+            readBody: emptyMockReadBody
+          }
+        } else {
+          return {
+            message: getDownloadResponseMessage(
+              firstHttpResponseCode,
+              false,
+              0,
+              null
+            ),
+            readBody: emptyMockReadBody
+          }
+        }
+      })
+
+    // set up a second mock only if we expect a retry. Otherwise this mock will affect other tests.
+    if (retryExpected) {
+      spyInstance.mockImplementationOnce(async () => {
+        // chained response, if the HTTP GET function gets called again, return a successful response
+        const fullResponse = await constructResponse(isGzip, fileContents)
+        return {
+          message: getDownloadResponseMessage(
+            200,
+            isGzip,
+            fullResponse.length,
+            fullResponse
+          ),
+          readBody: emptyMockReadBody
+        }
+      })
+    }
+  }
+
+  async function constructResponse(
+    isGzip: boolean,
+    plaintext: Buffer | string
+  ): Promise<Buffer> {
+    if (isGzip) {
+      return await promisify(gzip)(plaintext)
+    } else if (typeof plaintext === 'string') {
+      return Buffer.from(plaintext, defaultEncoding)
+    } else {
+      return plaintext
+    }
+  }
+
+  function getDownloadResponseMessage(
+    httpResponseCode: number,
+    isGzip: boolean,
+    contentLength: number,
+    response: Buffer | null
+  ): http.IncomingMessage {
+    let readCallCount = 0
+    const mockMessage = <http.IncomingMessage>new stream.Readable({
+      read(size) {
+        switch (readCallCount++) {
+          case 0:
+            if (!!response && response.byteLength > size) {
+              throw new Error(
+                `test response larger than requested size (${size})`
+              )
+            }
+            this.push(response)
+            break
+
+          default:
+            // end the stream
+            this.push(null)
+            break
+        }
+      }
+    })
+
+    mockMessage.statusCode = httpResponseCode
+    mockMessage.headers = {
+      'content-length': contentLength.toString()
+    }
+
+    if (isGzip) {
+      mockMessage.headers['content-encoding'] = 'gzip'
+    }
+
+    return mockMessage
+  }
+
+  /**
+   * Setups up HTTP GET response when querying for container items
+   */
+  function setupSuccessfulContainerItemsResponse(): void {
+    jest.spyOn(HttpClient.prototype, 'get').mockImplementationOnce(async () => {
+      const mockMessage = new http.IncomingMessage(new net.Socket())
+      let mockReadBody = emptyMockReadBody
+
+      mockMessage.statusCode = 201
+      const response: QueryArtifactResponse = {
+        count: 2,
+        value: [
+          {
+            containerId: 10000,
+            scopeIdentifier: '00000000-0000-0000-0000-000000000000',
+            path: 'artifact-name',
+            itemType: 'folder',
+            status: 'created',
+            dateCreated: '2020-02-06T22:13:35.373Z',
+            dateLastModified: '2020-02-06T22:13:35.453Z',
+            createdBy: '82f0bf89-6e55-4e5a-b8b6-f75eb992578c',
+            lastModifiedBy: '82f0bf89-6e55-4e5a-b8b6-f75eb992578c',
+            itemLocation: `${configVariables.getRuntimeUrl()}/_apis/resources/Containers/10000?itemPath=artifact-name&metadata=True`,
+            contentLocation: `${configVariables.getRuntimeUrl()}/_apis/resources/Containers/10000?itemPath=artifact-name`,
+            contentId: ''
+          },
+          {
+            containerId: 10000,
+            scopeIdentifier: '00000000-0000-0000-0000-000000000000',
+            path: 'artifact-name/file1.txt',
+            itemType: 'file',
+            status: 'created',
+            dateCreated: '2020-02-06T22:13:35.373Z',
+            dateLastModified: '2020-02-06T22:13:35.453Z',
+            createdBy: '82f0bf89-6e55-4e5a-b8b6-f75eb992578c',
+            lastModifiedBy: '82f0bf89-6e55-4e5a-b8b6-f75eb992578c',
+            itemLocation: `${configVariables.getRuntimeUrl()}/_apis/resources/Containers/10000?itemPath=artifact-name%2Ffile1.txt&metadata=True`,
+            contentLocation: `${configVariables.getRuntimeUrl()}/_apis/resources/Containers/10000?itemPath=artifact-name%2Ffile1.txt`,
+            contentId: ''
+          }
+        ]
+      }
+      const returnData: string = JSON.stringify(response, null, 2)
+      mockReadBody = async function(): Promise<string> {
+        return new Promise(resolve => {
+          resolve(returnData)
+        })
+      }
+
+      return new Promise<HttpClientResponse>(resolve => {
+        resolve({
+          message: mockMessage,
+          readBody: mockReadBody
+        })
+      })
+    })
+  }
+
+  /**
+   * Setups up HTTP GET response for a generic failed request
+   */
+  function setupFailedResponse(): void {
+    jest.spyOn(HttpClient.prototype, 'get').mockImplementationOnce(async () => {
+      const mockMessage = new http.IncomingMessage(new net.Socket())
+      mockMessage.statusCode = 400
+      return new Promise<HttpClientResponse>(resolve => {
+        resolve({
+          message: mockMessage,
+          readBody: emptyMockReadBody
+        })
+      })
+    })
+  }
+
+  async function checkDestinationFile(
+    targetPath: string,
+    expectedContents: Buffer
+  ): Promise<void> {
+    const fileContents = await fs.readFile(targetPath)
+
+    expect(fileContents.byteLength).toEqual(expectedContents.byteLength)
+    expect(fileContents.equals(expectedContents)).toBeTruthy()
+  }
+})

packages/artifact/__tests__/path-and-artifact-name-validation.test.ts

@@ -0,0 +1,78 @@
+import {
+  checkArtifactName,
+  checkArtifactFilePath
+} from '../src/internal/path-and-artifact-name-validation'
+import * as core from '@actions/core'
+
+describe('Path and artifact name validation', () => {
+  beforeAll(() => {
+    // mock all output so that there is less noise when running tests
+    jest.spyOn(console, 'log').mockImplementation(() => {})
+    jest.spyOn(core, 'debug').mockImplementation(() => {})
+    jest.spyOn(core, 'info').mockImplementation(() => {})
+    jest.spyOn(core, 'warning').mockImplementation(() => {})
+  })
+
+  it('Check Artifact Name for any invalid characters', () => {
+    const invalidNames = [
+      'my\\artifact',
+      'my/artifact',
+      'my"artifact',
+      'my:artifact',
+      'my<artifact',
+      'my>artifact',
+      'my|artifact',
+      'my*artifact',
+      'my?artifact',
+      ''
+    ]
+    for (const invalidName of invalidNames) {
+      expect(() => {
+        checkArtifactName(invalidName)
+      }).toThrow()
+    }
+
+    const validNames = [
+      'my-normal-artifact',
+      'myNormalArtifact',
+      'm¥ñðrmålÄr†ï£å¢†'
+    ]
+    for (const validName of validNames) {
+      expect(() => {
+        checkArtifactName(validName)
+      }).not.toThrow()
+    }
+  })
+
+  it('Check Artifact File Path for any invalid characters', () => {
+    const invalidNames = [
+      'some/invalid"artifact/path',
+      'some/invalid:artifact/path',
+      'some/invalid<artifact/path',
+      'some/invalid>artifact/path',
+      'some/invalid|artifact/path',
+      'some/invalid*artifact/path',
+      'some/invalid?artifact/path',
+      'some/invalid\rartifact/path',
+      'some/invalid\nartifact/path',
+      'some/invalid\r\nartifact/path',
+      ''
+    ]
+    for (const invalidName of invalidNames) {
+      expect(() => {
+        checkArtifactFilePath(invalidName)
+      }).toThrow()
+    }
+
+    const validNames = [
+      'my/perfectly-normal/artifact-path',
+      'my/perfectly\\Normal/Artifact-path',
+      'm¥/ñðrmål/Är†ï£å¢†'
+    ]
+    for (const validName of validNames) {
+      expect(() => {
+        checkArtifactFilePath(validName)
+      }).not.toThrow()
+    }
+  })
+})

packages/artifact/__tests__/retry.test.ts

@@ -0,0 +1,114 @@
+import * as http from 'http'
+import * as net from 'net'
+import * as core from '@actions/core'
+import * as configVariables from '../src/internal/config-variables'
+import {retry} from '../src/internal/requestUtils'
+import {IHttpClientResponse} from '@actions/http-client/interfaces'
+import {HttpClientResponse} from '@actions/http-client'
+
+jest.mock('../src/internal/config-variables')
+
+interface ITestResult {
+  responseCode: number
+  errorMessage: string | null
+}
+
+async function testRetry(
+  responseCodes: number[],
+  expectedResult: ITestResult
+): Promise<void> {
+  const reverse = responseCodes.reverse() // Reverse responses since we pop from end
+  if (expectedResult.errorMessage) {
+    // we expect some exception to be thrown
+    expect(
+      retry(
+        'test',
+        async () => handleResponse(reverse.pop()),
+        new Map(), // extra error message for any particular http codes
+        configVariables.getRetryLimit()
+      )
+    ).rejects.toThrow(expectedResult.errorMessage)
+  } else {
+    // we expect a correct status code to be returned
+    const actualResult = await retry(
+      'test',
+      async () => handleResponse(reverse.pop()),
+      new Map(), // extra error message for any particular http codes
+      configVariables.getRetryLimit()
+    )
+    expect(actualResult.message.statusCode).toEqual(expectedResult.responseCode)
+  }
+}
+
+async function handleResponse(
+  testResponseCode: number | undefined
+): Promise<IHttpClientResponse> {
+  if (!testResponseCode) {
+    throw new Error(
+      'Test incorrectly set up. reverse.pop() was called too many times so not enough test response codes were supplied'
+    )
+  }
+
+  return setupSingleMockResponse(testResponseCode)
+}
+
+beforeAll(async () => {
+  // mock all output so that there is less noise when running tests
+  jest.spyOn(console, 'log').mockImplementation(() => {})
+  jest.spyOn(core, 'debug').mockImplementation(() => {})
+  jest.spyOn(core, 'info').mockImplementation(() => {})
+  jest.spyOn(core, 'warning').mockImplementation(() => {})
+  jest.spyOn(core, 'error').mockImplementation(() => {})
+})
+
+/**
+ * Helpers used to setup mocking for the HttpClient
+ */
+async function emptyMockReadBody(): Promise<string> {
+  return new Promise(resolve => {
+    resolve()
+  })
+}
+
+async function setupSingleMockResponse(
+  statusCode: number
+): Promise<IHttpClientResponse> {
+  const mockMessage = new http.IncomingMessage(new net.Socket())
+  const mockReadBody = emptyMockReadBody
+  mockMessage.statusCode = statusCode
+  return new Promise<HttpClientResponse>(resolve => {
+    resolve({
+      message: mockMessage,
+      readBody: mockReadBody
+    })
+  })
+}
+
+test('retry works on successful response', async () => {
+  await testRetry([200], {
+    responseCode: 200,
+    errorMessage: null
+  })
+})
+
+test('retry works after retryable status code', async () => {
+  await testRetry([503, 200], {
+    responseCode: 200,
+    errorMessage: null
+  })
+})
+
+test('retry fails after exhausting retries', async () => {
+  // __mocks__/config-variables caps the max retry count in tests to 2
+  await testRetry([503, 503, 200], {
+    responseCode: 200,
+    errorMessage: 'test failed: Artifact service responded with 503'
+  })
+})
+
+test('retry fails after non-retryable status code', async () => {
+  await testRetry([400, 200], {
+    responseCode: 400,
+    errorMessage: 'test failed: Artifact service responded with 400'
+  })
+})

packages/artifact/__tests__/test-artifact-file.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+path="$1"
+expectedContent="$2"
+
+if [ "$path" == "" ]; then
+    echo "File path not provided"
+    exit 1
+fi
+
+if [ "$expectedContent" == "" ]; then
+    echo "Expected file contents not provided"
+    exit 1
+fi
+
+if [ ! -f "$path" ]; then
+    echo "Expected file $path does not exist"
+    exit 1
+fi
+
+actualContent=$(cat $path)
+if [ "$actualContent" != "$expectedContent" ];then
+    echo "File contents are not correct, expected $expectedContent, received $actualContent"
+    exit 1
+fi

packages/artifact/__tests__/upload-specification.test.ts

@@ -0,0 +1,353 @@
+import * as io from '../../io/src/io'
+import * as path from 'path'
+import {promises as fs} from 'fs'
+import * as core from '@actions/core'
+import {getUploadSpecification} from '../src/internal/upload-specification'
+
+const artifactName = 'my-artifact'
+const root = path.join(__dirname, '_temp', 'upload-specification')
+const goodItem1Path = path.join(
+  root,
+  'folder-a',
+  'folder-b',
+  'folder-c',
+  'good-item1.txt'
+)
+const goodItem2Path = path.join(root, 'folder-d', 'good-item2.txt')
+const goodItem3Path = path.join(root, 'folder-d', 'good-item3.txt')
+const goodItem4Path = path.join(root, 'folder-d', 'good-item4.txt')
+const goodItem5Path = path.join(root, 'good-item5.txt')
+const badItem1Path = path.join(
+  root,
+  'folder-a',
+  'folder-b',
+  'folder-c',
+  'bad-item1.txt'
+)
+const badItem2Path = path.join(root, 'folder-d', 'bad-item2.txt')
+const badItem3Path = path.join(root, 'folder-f', 'bad-item3.txt')
+const badItem4Path = path.join(root, 'folder-h', 'folder-i', 'bad-item4.txt')
+const badItem5Path = path.join(root, 'folder-h', 'folder-i', 'bad-item5.txt')
+const extraFileInFolderCPath = path.join(
+  root,
+  'folder-a',
+  'folder-b',
+  'folder-c',
+  'extra-file-in-folder-c.txt'
+)
+const amazingFileInFolderHPath = path.join(root, 'folder-h', 'amazing-item.txt')
+
+const artifactFilesToUpload = [
+  goodItem1Path,
+  goodItem2Path,
+  goodItem3Path,
+  goodItem4Path,
+  goodItem5Path,
+  extraFileInFolderCPath,
+  amazingFileInFolderHPath
+]
+
+describe('Search', () => {
+  beforeAll(async () => {
+    // mock all output so that there is less noise when running tests
+    jest.spyOn(console, 'log').mockImplementation(() => {})
+    jest.spyOn(core, 'debug').mockImplementation(() => {})
+    jest.spyOn(core, 'info').mockImplementation(() => {})
+    jest.spyOn(core, 'warning').mockImplementation(() => {})
+
+    // clear temp directory
+    await io.rmRF(root)
+    await fs.mkdir(path.join(root, 'folder-a', 'folder-b', 'folder-c'), {
+      recursive: true
+    })
+    await fs.mkdir(path.join(root, 'folder-a', 'folder-b', 'folder-e'), {
+      recursive: true
+    })
+    await fs.mkdir(path.join(root, 'folder-d'), {
+      recursive: true
+    })
+    await fs.mkdir(path.join(root, 'folder-f'), {
+      recursive: true
+    })
+    await fs.mkdir(path.join(root, 'folder-g'), {
+      recursive: true
+    })
+    await fs.mkdir(path.join(root, 'folder-h', 'folder-i'), {
+      recursive: true
+    })
+
+    await fs.writeFile(goodItem1Path, 'good item1 file')
+    await fs.writeFile(goodItem2Path, 'good item2 file')
+    await fs.writeFile(goodItem3Path, 'good item3 file')
+    await fs.writeFile(goodItem4Path, 'good item4 file')
+    await fs.writeFile(goodItem5Path, 'good item5 file')
+
+    await fs.writeFile(badItem1Path, 'bad item1 file')
+    await fs.writeFile(badItem2Path, 'bad item2 file')
+    await fs.writeFile(badItem3Path, 'bad item3 file')
+    await fs.writeFile(badItem4Path, 'bad item4 file')
+    await fs.writeFile(badItem5Path, 'bad item5 file')
+
+    await fs.writeFile(extraFileInFolderCPath, 'extra file')
+
+    await fs.writeFile(amazingFileInFolderHPath, 'amazing file')
+    /*
+      Directory structure of files that get created:
+      root/
+          folder-a/
+              folder-b/
+                  folder-c/
+                      good-item1.txt
+                      bad-item1.txt
+                      extra-file-in-folder-c.txt
+                  folder-e/
+          folder-d/
+              good-item2.txt
+              good-item3.txt
+              good-item4.txt
+              bad-item2.txt
+          folder-f/
+              bad-item3.txt
+          folder-g/
+          folder-h/
+              amazing-item.txt
+              folder-i/
+                  bad-item4.txt
+                  bad-item5.txt
+          good-item5.txt
+    */
+  })
+
+  it('Upload Specification - Fail non-existent rootDirectory', async () => {
+    const invalidRootDirectory = path.join(
+      __dirname,
+      '_temp',
+      'upload-specification-invalid'
+    )
+    expect(() => {
+      getUploadSpecification(
+        artifactName,
+        invalidRootDirectory,
+        artifactFilesToUpload
+      )
+    }).toThrow(`Provided rootDirectory ${invalidRootDirectory} does not exist`)
+  })
+
+  it('Upload Specification - Fail invalid rootDirectory', async () => {
+    expect(() => {
+      getUploadSpecification(artifactName, goodItem1Path, artifactFilesToUpload)
+    }).toThrow(
+      `Provided rootDirectory ${goodItem1Path} is not a valid directory`
+    )
+  })
+
+  it('Upload Specification - File does not exist', async () => {
+    const fakeFilePath = path.join(
+      artifactName,
+      'folder-a',
+      'folder-b',
+      'non-existent-file.txt'
+    )
+    expect(() => {
+      getUploadSpecification(artifactName, root, [fakeFilePath])
+    }).toThrow(`File ${fakeFilePath} does not exist`)
+  })
+
+  it('Upload Specification - Non parent directory', async () => {
+    const folderADirectory = path.join(root, 'folder-a')
+    const artifactFiles = [
+      goodItem1Path,
+      badItem1Path,
+      extraFileInFolderCPath,
+      goodItem5Path
+    ]
+    expect(() => {
+      getUploadSpecification(artifactName, folderADirectory, artifactFiles)
+    }).toThrow(
+      `The rootDirectory: ${folderADirectory} is not a parent directory of the file: ${goodItem5Path}`
+    )
+  })
+
+  it('Upload Specification - Success', async () => {
+    const specifications = getUploadSpecification(
+      artifactName,
+      root,
+      artifactFilesToUpload
+    )
+    expect(specifications.length).toEqual(7)
+
+    const absolutePaths = specifications.map(item => item.absoluteFilePath)
+    expect(absolutePaths).toContain(goodItem1Path)
+    expect(absolutePaths).toContain(goodItem2Path)
+    expect(absolutePaths).toContain(goodItem3Path)
+    expect(absolutePaths).toContain(goodItem4Path)
+    expect(absolutePaths).toContain(goodItem5Path)
+    expect(absolutePaths).toContain(extraFileInFolderCPath)
+    expect(absolutePaths).toContain(amazingFileInFolderHPath)
+
+    for (const specification of specifications) {
+      if (specification.absoluteFilePath === goodItem1Path) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(
+            artifactName,
+            'folder-a',
+            'folder-b',
+            'folder-c',
+            'good-item1.txt'
+          )
+        )
+      } else if (specification.absoluteFilePath === goodItem2Path) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(artifactName, 'folder-d', 'good-item2.txt')
+        )
+      } else if (specification.absoluteFilePath === goodItem3Path) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(artifactName, 'folder-d', 'good-item3.txt')
+        )
+      } else if (specification.absoluteFilePath === goodItem4Path) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(artifactName, 'folder-d', 'good-item4.txt')
+        )
+      } else if (specification.absoluteFilePath === goodItem5Path) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(artifactName, 'good-item5.txt')
+        )
+      } else if (specification.absoluteFilePath === extraFileInFolderCPath) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(
+            artifactName,
+            'folder-a',
+            'folder-b',
+            'folder-c',
+            'extra-file-in-folder-c.txt'
+          )
+        )
+      } else if (specification.absoluteFilePath === amazingFileInFolderHPath) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(artifactName, 'folder-h', 'amazing-item.txt')
+        )
+      } else {
+        throw new Error(
+          'Invalid specification found. This should never be reached'
+        )
+      }
+    }
+  })
+
+  it('Upload Specification - Success with extra slash', async () => {
+    const rootWithSlash = `${root}/`
+    const specifications = getUploadSpecification(
+      artifactName,
+      rootWithSlash,
+      artifactFilesToUpload
+    )
+    expect(specifications.length).toEqual(7)
+
+    const absolutePaths = specifications.map(item => item.absoluteFilePath)
+    expect(absolutePaths).toContain(goodItem1Path)
+    expect(absolutePaths).toContain(goodItem2Path)
+    expect(absolutePaths).toContain(goodItem3Path)
+    expect(absolutePaths).toContain(goodItem4Path)
+    expect(absolutePaths).toContain(goodItem5Path)
+    expect(absolutePaths).toContain(extraFileInFolderCPath)
+    expect(absolutePaths).toContain(amazingFileInFolderHPath)
+
+    for (const specification of specifications) {
+      if (specification.absoluteFilePath === goodItem1Path) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(
+            artifactName,
+            'folder-a',
+            'folder-b',
+            'folder-c',
+            'good-item1.txt'
+          )
+        )
+      } else if (specification.absoluteFilePath === goodItem2Path) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(artifactName, 'folder-d', 'good-item2.txt')
+        )
+      } else if (specification.absoluteFilePath === goodItem3Path) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(artifactName, 'folder-d', 'good-item3.txt')
+        )
+      } else if (specification.absoluteFilePath === goodItem4Path) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(artifactName, 'folder-d', 'good-item4.txt')
+        )
+      } else if (specification.absoluteFilePath === goodItem5Path) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(artifactName, 'good-item5.txt')
+        )
+      } else if (specification.absoluteFilePath === extraFileInFolderCPath) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(
+            artifactName,
+            'folder-a',
+            'folder-b',
+            'folder-c',
+            'extra-file-in-folder-c.txt'
+          )
+        )
+      } else if (specification.absoluteFilePath === amazingFileInFolderHPath) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(artifactName, 'folder-h', 'amazing-item.txt')
+        )
+      } else {
+        throw new Error(
+          'Invalid specification found. This should never be reached'
+        )
+      }
+    }
+  })
+
+  it('Upload Specification - Directories should not be included', async () => {
+    const folderEPath = path.join(root, 'folder-a', 'folder-b', 'folder-e')
+    const filesWithDirectory = [
+      goodItem1Path,
+      goodItem4Path,
+      folderEPath,
+      badItem3Path
+    ]
+    const specifications = getUploadSpecification(
+      artifactName,
+      root,
+      filesWithDirectory
+    )
+    expect(specifications.length).toEqual(3)
+    const absolutePaths = specifications.map(item => item.absoluteFilePath)
+    expect(absolutePaths).toContain(goodItem1Path)
+    expect(absolutePaths).toContain(goodItem4Path)
+    expect(absolutePaths).toContain(badItem3Path)
+
+    for (const specification of specifications) {
+      if (specification.absoluteFilePath === goodItem1Path) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(
+            artifactName,
+            'folder-a',
+            'folder-b',
+            'folder-c',
+            'good-item1.txt'
+          )
+        )
+      } else if (specification.absoluteFilePath === goodItem2Path) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(artifactName, 'folder-d', 'good-item2.txt')
+        )
+      } else if (specification.absoluteFilePath === goodItem4Path) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(artifactName, 'folder-d', 'good-item4.txt')
+        )
+      } else if (specification.absoluteFilePath === badItem3Path) {
+        expect(specification.uploadFilePath).toEqual(
+          path.join(artifactName, 'folder-f', 'bad-item3.txt')
+        )
+      } else {
+        throw new Error(
+          'Invalid specification found. This should never be reached'
+        )
+      }
+    }
+  })
+})

packages/artifact/__tests__/upload.test.ts

@@ -0,0 +1,548 @@
+import * as http from 'http'
+import * as io from '../../io/src/io'
+import * as net from 'net'
+import * as path from 'path'
+import {mocked} from 'ts-jest/utils'
+import {exec, execSync} from 'child_process'
+import {createGunzip} from 'zlib'
+import {promisify} from 'util'
+import {UploadHttpClient} from '../src/internal/upload-http-client'
+import * as core from '@actions/core'
+import {promises as fs} from 'fs'
+import {getRuntimeUrl} from '../src/internal/config-variables'
+import {HttpClient, HttpClientResponse} from '@actions/http-client'
+import {
+  ArtifactResponse,
+  PatchArtifactSizeSuccessResponse
+} from '../src/internal/contracts'
+import {UploadSpecification} from '../src/internal/upload-specification'
+import {getArtifactUrl} from '../src/internal/utils'
+import {UploadOptions} from '../src/internal/upload-options'
+
+const root = path.join(__dirname, '_temp', 'artifact-upload')
+const file1Path = path.join(root, 'file1.txt')
+const file2Path = path.join(root, 'file2.txt')
+const file3Path = path.join(root, 'folder1', 'file3.txt')
+const file4Path = path.join(root, 'folder1', 'file4.txt')
+const file5Path = path.join(root, 'folder1', 'folder2', 'folder3', 'file5.txt')
+
+let file1Size = 0
+let file2Size = 0
+let file3Size = 0
+let file4Size = 0
+let file5Size = 0
+
+jest.mock('../src/internal/config-variables')
+jest.mock('@actions/http-client')
+
+describe('Upload Tests', () => {
+  beforeAll(async () => {
+    // mock all output so that there is less noise when running tests
+    jest.spyOn(console, 'log').mockImplementation(() => {})
+    jest.spyOn(core, 'debug').mockImplementation(() => {})
+    jest.spyOn(core, 'info').mockImplementation(() => {})
+    jest.spyOn(core, 'warning').mockImplementation(() => {})
+    jest.spyOn(core, 'error').mockImplementation(() => {})
+
+    // setup mocking for calls that got through the HttpClient
+    setupHttpClientMock()
+
+    // clear temp directory and create files that will be "uploaded"
+    await io.rmRF(root)
+    await fs.mkdir(path.join(root, 'folder1', 'folder2', 'folder3'), {
+      recursive: true
+    })
+    await fs.writeFile(file1Path, 'this is file 1')
+    await fs.writeFile(file2Path, 'this is file 2')
+    await fs.writeFile(file3Path, 'this is file 3')
+    await fs.writeFile(file4Path, 'this is file 4')
+    await fs.writeFile(file5Path, 'this is file 5')
+    /*
+      Directory structure for files that get created:
+      root/
+        file1.txt
+        file2.txt
+        folder1/
+          file3.txt
+          file4.txt
+          folder2/
+            folder3/
+              file5.txt
+    */
+
+    file1Size = (await fs.stat(file1Path)).size
+    file2Size = (await fs.stat(file2Path)).size
+    file3Size = (await fs.stat(file3Path)).size
+    file4Size = (await fs.stat(file4Path)).size
+    file5Size = (await fs.stat(file5Path)).size
+  })
+
+  /**
+   * Artifact Creation Tests
+   */
+  it('Create Artifact - Success', async () => {
+    const artifactName = 'valid-artifact-name'
+    const uploadHttpClient = new UploadHttpClient()
+    const response = await uploadHttpClient.createArtifactInFileContainer(
+      artifactName
+    )
+    expect(response.containerId).toEqual('13')
+    expect(response.size).toEqual(-1)
+    expect(response.signedContent).toEqual('false')
+    expect(response.fileContainerResourceUrl).toEqual(
+      `${getRuntimeUrl()}_apis/resources/Containers/13`
+    )
+    expect(response.type).toEqual('actions_storage')
+    expect(response.name).toEqual(artifactName)
+    expect(response.url).toEqual(
+      `${getRuntimeUrl()}_apis/pipelines/1/runs/1/artifacts?artifactName=${artifactName}`
+    )
+  })
+
+  it('Create Artifact - Failure', async () => {
+    const artifactName = 'invalid-artifact-name'
+    const uploadHttpClient = new UploadHttpClient()
+    expect(
+      uploadHttpClient.createArtifactInFileContainer(artifactName)
+    ).rejects.toEqual(
+      new Error(
+        `Create Artifact Container failed: The artifact name invalid-artifact-name is not valid. Request URL ${getArtifactUrl()}`
+      )
+    )
+  })
+
+  it('Create Artifact - Retention Less Than Min Value Error', async () => {
+    const artifactName = 'valid-artifact-name'
+    const options: UploadOptions = {
+      retentionDays: -1
+    }
+    const uploadHttpClient = new UploadHttpClient()
+    expect(
+      uploadHttpClient.createArtifactInFileContainer(artifactName, options)
+    ).rejects.toEqual(new Error('Invalid retention, minimum value is 1.'))
+  })
+
+  it('Create Artifact - Storage Quota Error', async () => {
+    const artifactName = 'storage-quota-hit'
+    const uploadHttpClient = new UploadHttpClient()
+    expect(
+      uploadHttpClient.createArtifactInFileContainer(artifactName)
+    ).rejects.toEqual(
+      new Error(
+        'Create Artifact Container failed: Artifact storage quota has been hit. Unable to upload any new artifacts'
+      )
+    )
+  })
+
+  /**
+   * Artifact Upload Tests
+   */
+  it('Upload Artifact - Success', async () => {
+    /**
+     * Normally search.findFilesToUpload() would be used for providing information about what to upload. These tests however
+     * focuses solely on the upload APIs so searchResult[] will be hard-coded
+     */
+    const artifactName = 'successful-artifact'
+    const uploadSpecification: UploadSpecification[] = [
+      {
+        absoluteFilePath: file1Path,
+        uploadFilePath: `${artifactName}/file1.txt`
+      },
+      {
+        absoluteFilePath: file2Path,
+        uploadFilePath: `${artifactName}/file2.txt`
+      },
+      {
+        absoluteFilePath: file3Path,
+        uploadFilePath: `${artifactName}/folder1/file3.txt`
+      },
+      {
+        absoluteFilePath: file4Path,
+        uploadFilePath: `${artifactName}/folder1/file4.txt`
+      },
+      {
+        absoluteFilePath: file5Path,
+        uploadFilePath: `${artifactName}/folder1/folder2/folder3/file5.txt`
+      }
+    ]
+
+    const expectedTotalSize =
+      file1Size + file2Size + file3Size + file4Size + file5Size
+    const uploadUrl = `${getRuntimeUrl()}_apis/resources/Containers/13`
+    const uploadHttpClient = new UploadHttpClient()
+    const uploadResult = await uploadHttpClient.uploadArtifactToFileContainer(
+      uploadUrl,
+      uploadSpecification
+    )
+    expect(uploadResult.failedItems.length).toEqual(0)
+    expect(uploadResult.uploadSize).toEqual(expectedTotalSize)
+  })
+
+  function hasMkfifo(): boolean {
+    try {
+      // make sure we drain the stdout
+      return execSync('which mkfifo').toString().length > 0
+    } catch (e) {
+      return false
+    }
+  }
+  const withMkfifoIt = hasMkfifo() ? it : it.skip
+  withMkfifoIt(
+    'Upload Artifact with content from named pipe - Success',
+    async () => {
+      // create a named pipe 'pipe' with content 'hello pipe'
+      const content = Buffer.from('hello pipe')
+      const pipeFilePath = path.join(root, 'pipe')
+      await promisify(exec)('mkfifo pipe', {cwd: root})
+      // don't want to await here as that would block until read
+      fs.writeFile(pipeFilePath, content)
+
+      const artifactName = 'successful-artifact'
+      const uploadSpecification: UploadSpecification[] = [
+        {
+          absoluteFilePath: pipeFilePath,
+          uploadFilePath: `${artifactName}/pipe`
+        }
+      ]
+
+      const uploadUrl = `${getRuntimeUrl()}_apis/resources/Containers/13`
+      const uploadHttpClient = new UploadHttpClient()
+      const uploadResult = await uploadHttpClient.uploadArtifactToFileContainer(
+        uploadUrl,
+        uploadSpecification
+      )
+
+      // accesses the ReadableStream that was passed into sendStream
+      // eslint-disable-next-line @typescript-eslint/unbound-method
+      const stream = mocked(HttpClient.prototype.sendStream).mock.calls[0][2]
+      expect(stream).not.toBeNull()
+      // decompresses the passed stream
+      const data: Buffer[] = []
+      for await (const chunk of stream.pipe(createGunzip())) {
+        data.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as string))
+      }
+      const uploaded = Buffer.concat(data)
+
+      expect(uploadResult.failedItems.length).toEqual(0)
+      expect(uploaded).toEqual(content)
+    }
+  )
+
+  it('Upload Artifact - Failed Single File Upload', async () => {
+    const uploadSpecification: UploadSpecification[] = [
+      {
+        absoluteFilePath: file1Path,
+        uploadFilePath: `this-file-upload-will-fail`
+      }
+    ]
+
+    const uploadUrl = `${getRuntimeUrl()}_apis/resources/Containers/13`
+    const uploadHttpClient = new UploadHttpClient()
+    const uploadResult = await uploadHttpClient.uploadArtifactToFileContainer(
+      uploadUrl,
+      uploadSpecification
+    )
+    expect(uploadResult.failedItems.length).toEqual(1)
+    expect(uploadResult.uploadSize).toEqual(0)
+  })
+
+  it('Upload Artifact - Partial Upload Continue On Error', async () => {
+    const artifactName = 'partial-artifact'
+    const uploadSpecification: UploadSpecification[] = [
+      {
+        absoluteFilePath: file1Path,
+        uploadFilePath: `${artifactName}/file1.txt`
+      },
+      {
+        absoluteFilePath: file2Path,
+        uploadFilePath: `${artifactName}/file2.txt`
+      },
+      {
+        absoluteFilePath: file3Path,
+        uploadFilePath: `${artifactName}/folder1/file3.txt`
+      },
+      {
+        absoluteFilePath: file4Path,
+        uploadFilePath: `this-file-upload-will-fail`
+      },
+      {
+        absoluteFilePath: file5Path,
+        uploadFilePath: `${artifactName}/folder1/folder2/folder3/file5.txt`
+      }
+    ]
+
+    const expectedPartialSize = file1Size + file2Size + file4Size + file5Size
+    const uploadUrl = `${getRuntimeUrl()}_apis/resources/Containers/13`
+    const uploadHttpClient = new UploadHttpClient()
+    const uploadResult = await uploadHttpClient.uploadArtifactToFileContainer(
+      uploadUrl,
+      uploadSpecification,
+      {continueOnError: true}
+    )
+    expect(uploadResult.failedItems.length).toEqual(1)
+    expect(uploadResult.uploadSize).toEqual(expectedPartialSize)
+  })
+
+  it('Upload Artifact - Partial Upload Fail Fast', async () => {
+    const artifactName = 'partial-artifact'
+    const uploadSpecification: UploadSpecification[] = [
+      {
+        absoluteFilePath: file1Path,
+        uploadFilePath: `${artifactName}/file1.txt`
+      },
+      {
+        absoluteFilePath: file2Path,
+        uploadFilePath: `${artifactName}/file2.txt`
+      },
+      {
+        absoluteFilePath: file3Path,
+        uploadFilePath: `${artifactName}/folder1/file3.txt`
+      },
+      {
+        absoluteFilePath: file4Path,
+        uploadFilePath: `this-file-upload-will-fail`
+      },
+      {
+        absoluteFilePath: file5Path,
+        uploadFilePath: `${artifactName}/folder1/folder2/folder3/file5.txt`
+      }
+    ]
+
+    const expectedPartialSize = file1Size + file2Size + file3Size
+    const uploadUrl = `${getRuntimeUrl()}_apis/resources/Containers/13`
+    const uploadHttpClient = new UploadHttpClient()
+    const uploadResult = await uploadHttpClient.uploadArtifactToFileContainer(
+      uploadUrl,
+      uploadSpecification,
+      {continueOnError: false}
+    )
+    expect(uploadResult.failedItems.length).toEqual(2)
+    expect(uploadResult.uploadSize).toEqual(expectedPartialSize)
+  })
+
+  it('Upload Artifact - Failed upload with no options', async () => {
+    const artifactName = 'partial-artifact'
+    const uploadSpecification: UploadSpecification[] = [
+      {
+        absoluteFilePath: file1Path,
+        uploadFilePath: `${artifactName}/file1.txt`
+      },
+      {
+        absoluteFilePath: file2Path,
+        uploadFilePath: `${artifactName}/file2.txt`
+      },
+      {
+        absoluteFilePath: file3Path,
+        uploadFilePath: `${artifactName}/folder1/file3.txt`
+      },
+      {
+        absoluteFilePath: file4Path,
+        uploadFilePath: `this-file-upload-will-fail`
+      },
+      {
+        absoluteFilePath: file5Path,
+        uploadFilePath: `${artifactName}/folder1/folder2/folder3/file5.txt`
+      }
+    ]
+
+    const expectedPartialSize = file1Size + file2Size + file3Size + file5Size
+    const uploadUrl = `${getRuntimeUrl()}_apis/resources/Containers/13`
+    const uploadHttpClient = new UploadHttpClient()
+    const uploadResult = await uploadHttpClient.uploadArtifactToFileContainer(
+      uploadUrl,
+      uploadSpecification
+    )
+    expect(uploadResult.failedItems.length).toEqual(1)
+    expect(uploadResult.uploadSize).toEqual(expectedPartialSize)
+  })
+
+  it('Upload Artifact - Failed upload with empty options', async () => {
+    const artifactName = 'partial-artifact'
+    const uploadSpecification: UploadSpecification[] = [
+      {
+        absoluteFilePath: file1Path,
+        uploadFilePath: `${artifactName}/file1.txt`
+      },
+      {
+        absoluteFilePath: file2Path,
+        uploadFilePath: `${artifactName}/file2.txt`
+      },
+      {
+        absoluteFilePath: file3Path,
+        uploadFilePath: `${artifactName}/folder1/file3.txt`
+      },
+      {
+        absoluteFilePath: file4Path,
+        uploadFilePath: `this-file-upload-will-fail`
+      },
+      {
+        absoluteFilePath: file5Path,
+        uploadFilePath: `${artifactName}/folder1/folder2/folder3/file5.txt`
+      }
+    ]
+
+    const expectedPartialSize = file1Size + file2Size + file3Size + file5Size
+    const uploadUrl = `${getRuntimeUrl()}_apis/resources/Containers/13`
+    const uploadHttpClient = new UploadHttpClient()
+    const uploadResult = await uploadHttpClient.uploadArtifactToFileContainer(
+      uploadUrl,
+      uploadSpecification,
+      {}
+    )
+    expect(uploadResult.failedItems.length).toEqual(1)
+    expect(uploadResult.uploadSize).toEqual(expectedPartialSize)
+  })
+
+  /**
+   * Artifact Association Tests
+   */
+  it('Associate Artifact - Success', async () => {
+    const uploadHttpClient = new UploadHttpClient()
+    expect(async () => {
+      uploadHttpClient.patchArtifactSize(130, 'my-artifact')
+    }).not.toThrow()
+  })
+
+  it('Associate Artifact - Not Found', async () => {
+    const uploadHttpClient = new UploadHttpClient()
+    expect(
+      uploadHttpClient.patchArtifactSize(100, 'non-existent-artifact')
+    ).rejects.toThrow(
+      'An Artifact with the name non-existent-artifact was not found'
+    )
+  })
+
+  it('Associate Artifact - Error', async () => {
+    const uploadHttpClient = new UploadHttpClient()
+    expect(
+      uploadHttpClient.patchArtifactSize(-2, 'my-artifact')
+    ).rejects.toThrow(
+      'Finalize artifact upload failed: Artifact service responded with 400'
+    )
+  })
+
+  /**
+   * Helpers used to setup mocking for the HttpClient
+   */
+  async function emptyMockReadBody(): Promise<string> {
+    return new Promise(resolve => {
+      resolve()
+    })
+  }
+
+  function setupHttpClientMock(): void {
+    /**
+     * Mocks Post calls that are used during Artifact Creation tests
+     *
+     * Simulates success and non-success status codes depending on the artifact name along with an appropriate
+     * payload that represents an expected response
+     */
+    jest
+      .spyOn(HttpClient.prototype, 'post')
+      .mockImplementation(async (requestdata, data) => {
+        // parse the input data and use the provided artifact name as part of the response
+        const inputData = JSON.parse(data)
+        const mockMessage = new http.IncomingMessage(new net.Socket())
+        let mockReadBody = emptyMockReadBody
+
+        if (inputData.Name === 'invalid-artifact-name') {
+          mockMessage.statusCode = 400
+        } else if (inputData.Name === 'storage-quota-hit') {
+          mockMessage.statusCode = 403
+        } else {
+          mockMessage.statusCode = 201
+          const response: ArtifactResponse = {
+            containerId: '13',
+            size: -1,
+            signedContent: 'false',
+            fileContainerResourceUrl: `${getRuntimeUrl()}_apis/resources/Containers/13`,
+            type: 'actions_storage',
+            name: inputData.Name,
+            url: `${getRuntimeUrl()}_apis/pipelines/1/runs/1/artifacts?artifactName=${
+              inputData.Name
+            }`
+          }
+          const returnData: string = JSON.stringify(response, null, 2)
+          mockReadBody = async function(): Promise<string> {
+            return new Promise(resolve => {
+              resolve(returnData)
+            })
+          }
+        }
+        return new Promise<HttpClientResponse>(resolve => {
+          resolve({
+            message: mockMessage,
+            readBody: mockReadBody
+          })
+        })
+      })
+
+    /**
+     * Mocks SendStream calls that are made during Artifact Upload tests
+     *
+     * A 500 response is used to simulate a failed upload stream. The uploadUrl can be set to
+     * include 'fail' to specify that the upload should fail
+     */
+    jest
+      .spyOn(HttpClient.prototype, 'sendStream')
+      .mockImplementation(async (verb, requestUrl) => {
+        const mockMessage = new http.IncomingMessage(new net.Socket())
+        mockMessage.statusCode = 200
+        if (requestUrl.includes('fail')) {
+          mockMessage.statusCode = 500
+        }
+
+        return new Promise<HttpClientResponse>(resolve => {
+          resolve({
+            message: mockMessage,
+            readBody: emptyMockReadBody
+          })
+        })
+      })
+
+    /**
+     * Mocks Patch calls that are made during Artifact Association tests
+     *
+     * Simulates success and non-success status codes depending on the input size along with an appropriate
+     * payload that represents an expected response
+     */
+    jest
+      .spyOn(HttpClient.prototype, 'patch')
+      .mockImplementation(async (requestdata, data) => {
+        const inputData = JSON.parse(data)
+        const mockMessage = new http.IncomingMessage(new net.Socket())
+
+        // Get the name from the end of requestdata. Will be something like https://www.example.com/_apis/pipelines/workflows/15/artifacts?api-version=6.0-preview&artifactName=my-artifact
+        const artifactName = requestdata.split('=')[2]
+        let mockReadBody = emptyMockReadBody
+        if (inputData.Size < 1) {
+          mockMessage.statusCode = 400
+        } else if (artifactName === 'non-existent-artifact') {
+          mockMessage.statusCode = 404
+        } else {
+          mockMessage.statusCode = 200
+          const response: PatchArtifactSizeSuccessResponse = {
+            containerId: 13,
+            size: inputData.Size,
+            signedContent: 'false',
+            type: 'actions_storage',
+            name: artifactName,
+            url: `${getRuntimeUrl()}_apis/pipelines/1/runs/1/artifacts?artifactName=${artifactName}`,
+            uploadUrl: `${getRuntimeUrl()}_apis/resources/Containers/13`
+          }
+          const returnData: string = JSON.stringify(response, null, 2)
+          mockReadBody = async function(): Promise<string> {
+            return new Promise(resolve => {
+              resolve(returnData)
+            })
+          }
+        }
+        return new Promise<HttpClientResponse>(resolve => {
+          resolve({
+            message: mockMessage,
+            readBody: mockReadBody
+          })
+        })
+      })
+  }
+})

packages/artifact/__tests__/util.test.ts

@@ -0,0 +1,222 @@
+import * as fs from 'fs'
+import * as io from '../../io/src/io'
+import * as path from 'path'
+import * as utils from '../src/internal/utils'
+import * as core from '@actions/core'
+import {HttpCodes} from '@actions/http-client'
+import {
+  getRuntimeUrl,
+  getWorkFlowRunId,
+  getInitialRetryIntervalInMilliseconds,
+  getRetryMultiplier
+} from '../src/internal/config-variables'
+
+jest.mock('../src/internal/config-variables')
+
+describe('Utils', () => {
+  beforeAll(() => {
+    // mock all output so that there is less noise when running tests
+    jest.spyOn(console, 'log').mockImplementation(() => {})
+    jest.spyOn(core, 'debug').mockImplementation(() => {})
+    jest.spyOn(core, 'info').mockImplementation(() => {})
+    jest.spyOn(core, 'warning').mockImplementation(() => {})
+  })
+
+  it('Check exponential retry range', () => {
+    // No retries should return the initial retry interval
+    const retryWaitTime0 = utils.getExponentialRetryTimeInMilliseconds(0)
+    expect(retryWaitTime0).toEqual(getInitialRetryIntervalInMilliseconds())
+
+    const testMinMaxRange = (retryCount: number): void => {
+      const retryWaitTime = utils.getExponentialRetryTimeInMilliseconds(
+        retryCount
+      )
+      const minRange =
+        getInitialRetryIntervalInMilliseconds() *
+        getRetryMultiplier() *
+        retryCount
+      const maxRange = minRange * getRetryMultiplier()
+
+      expect(retryWaitTime).toBeGreaterThanOrEqual(minRange)
+      expect(retryWaitTime).toBeLessThan(maxRange)
+    }
+
+    for (let i = 1; i < 10; i++) {
+      testMinMaxRange(i)
+    }
+  })
+
+  it('Test negative artifact retention throws', () => {
+    expect(() => {
+      utils.getProperRetention(-1, undefined)
+    }).toThrow()
+  })
+
+  it('Test no setting specified takes artifact retention input', () => {
+    expect(utils.getProperRetention(180, undefined)).toEqual(180)
+  })
+
+  it('Test artifact retention must conform to max allowed', () => {
+    expect(utils.getProperRetention(180, '45')).toEqual(45)
+  })
+
+  it('Test constructing artifact URL', () => {
+    const runtimeUrl = getRuntimeUrl()
+    const runId = getWorkFlowRunId()
+    const artifactUrl = utils.getArtifactUrl()
+    expect(artifactUrl).toEqual(
+      `${runtimeUrl}_apis/pipelines/workflows/${runId}/artifacts?api-version=${utils.getApiVersion()}`
+    )
+  })
+
+  it('Test constructing upload headers with all optional parameters', () => {
+    const contentType = 'application/octet-stream'
+    const size = 24
+    const uncompressedLength = 100
+    const range = 'bytes 0-199/200'
+    const headers = utils.getUploadHeaders(
+      contentType,
+      true,
+      true,
+      uncompressedLength,
+      size,
+      range
+    )
+    expect(Object.keys(headers).length).toEqual(8)
+    expect(headers['Accept']).toEqual(
+      `application/json;api-version=${utils.getApiVersion()}`
+    )
+    expect(headers['Content-Type']).toEqual(contentType)
+    expect(headers['Connection']).toEqual('Keep-Alive')
+    expect(headers['Keep-Alive']).toEqual('10')
+    expect(headers['Content-Encoding']).toEqual('gzip')
+    expect(headers['x-tfs-filelength']).toEqual(uncompressedLength)
+    expect(headers['Content-Length']).toEqual(size)
+    expect(headers['Content-Range']).toEqual(range)
+  })
+
+  it('Test constructing upload headers with only required parameter', () => {
+    const headers = utils.getUploadHeaders('application/octet-stream')
+    expect(Object.keys(headers).length).toEqual(2)
+    expect(headers['Accept']).toEqual(
+      `application/json;api-version=${utils.getApiVersion()}`
+    )
+    expect(headers['Content-Type']).toEqual('application/octet-stream')
+  })
+
+  it('Test constructing download headers with all optional parameters', () => {
+    const contentType = 'application/json'
+    const headers = utils.getDownloadHeaders(contentType, true, true)
+    expect(Object.keys(headers).length).toEqual(5)
+    expect(headers['Content-Type']).toEqual(contentType)
+    expect(headers['Connection']).toEqual('Keep-Alive')
+    expect(headers['Keep-Alive']).toEqual('10')
+    expect(headers['Accept-Encoding']).toEqual('gzip')
+    expect(headers['Accept']).toEqual(
+      `application/octet-stream;api-version=${utils.getApiVersion()}`
+    )
+  })
+
+  it('Test constructing download headers with only required parameter', () => {
+    const headers = utils.getDownloadHeaders('application/octet-stream')
+    expect(Object.keys(headers).length).toEqual(2)
+    expect(headers['Content-Type']).toEqual('application/octet-stream')
+    // check for default accept type
+    expect(headers['Accept']).toEqual(
+      `application/json;api-version=${utils.getApiVersion()}`
+    )
+  })
+
+  it('Test Success Status Code', () => {
+    expect(utils.isSuccessStatusCode(HttpCodes.OK)).toEqual(true)
+    expect(utils.isSuccessStatusCode(201)).toEqual(true)
+    expect(utils.isSuccessStatusCode(299)).toEqual(true)
+    expect(utils.isSuccessStatusCode(HttpCodes.NotFound)).toEqual(false)
+    expect(utils.isSuccessStatusCode(HttpCodes.BadGateway)).toEqual(false)
+    expect(utils.isSuccessStatusCode(HttpCodes.Forbidden)).toEqual(false)
+  })
+
+  it('Test Retry Status Code', () => {
+    expect(utils.isRetryableStatusCode(HttpCodes.BadGateway)).toEqual(true)
+    expect(utils.isRetryableStatusCode(HttpCodes.ServiceUnavailable)).toEqual(
+      true
+    )
+    expect(utils.isRetryableStatusCode(HttpCodes.GatewayTimeout)).toEqual(true)
+    expect(utils.isRetryableStatusCode(HttpCodes.TooManyRequests)).toEqual(true)
+    expect(utils.isRetryableStatusCode(HttpCodes.OK)).toEqual(false)
+    expect(utils.isRetryableStatusCode(HttpCodes.NotFound)).toEqual(false)
+    expect(utils.isRetryableStatusCode(HttpCodes.Forbidden)).toEqual(false)
+    expect(utils.isRetryableStatusCode(413)).toEqual(true) // Payload Too Large
+  })
+
+  it('Test Throttled Status Code', () => {
+    expect(utils.isThrottledStatusCode(HttpCodes.TooManyRequests)).toEqual(true)
+    expect(utils.isThrottledStatusCode(HttpCodes.InternalServerError)).toEqual(
+      false
+    )
+    expect(utils.isThrottledStatusCode(HttpCodes.BadGateway)).toEqual(false)
+    expect(utils.isThrottledStatusCode(HttpCodes.ServiceUnavailable)).toEqual(
+      false
+    )
+  })
+
+  it('Test Forbidden Status Code', () => {
+    expect(utils.isForbiddenStatusCode(HttpCodes.Forbidden)).toEqual(true)
+    expect(utils.isForbiddenStatusCode(HttpCodes.InternalServerError)).toEqual(
+      false
+    )
+    expect(utils.isForbiddenStatusCode(HttpCodes.TooManyRequests)).toEqual(
+      false
+    )
+    expect(utils.isForbiddenStatusCode(HttpCodes.OK)).toEqual(false)
+  })
+
+  it('Test Creating Artifact Directories', async () => {
+    const root = path.join(__dirname, '_temp', 'artifact-download')
+    // remove directory before starting
+    await io.rmRF(root)
+
+    const directory1 = path.join(root, 'folder2', 'folder3')
+    const directory2 = path.join(directory1, 'folder1')
+
+    // Initially should not exist
+    await expect(fs.promises.access(directory1)).rejects.not.toBeUndefined()
+    await expect(fs.promises.access(directory2)).rejects.not.toBeUndefined()
+    const directoryStructure = [directory1, directory2]
+    await utils.createDirectoriesForArtifact(directoryStructure)
+    // directories should now be created
+    await expect(fs.promises.access(directory1)).resolves.toEqual(undefined)
+    await expect(fs.promises.access(directory2)).resolves.toEqual(undefined)
+  })
+
+  it('Test Creating Empty Files', async () => {
+    const root = path.join(__dirname, '_temp', 'empty-files')
+    await io.rmRF(root)
+
+    const emptyFile1 = path.join(root, 'emptyFile1')
+    const directoryToCreate = path.join(root, 'folder1')
+    const emptyFile2 = path.join(directoryToCreate, 'emptyFile2')
+
+    // empty files should only be created after the directory structure is fully setup
+    // ensure they are first created by using the createDirectoriesForArtifact method
+    const directoryStructure = [root, directoryToCreate]
+    await utils.createDirectoriesForArtifact(directoryStructure)
+    await expect(fs.promises.access(root)).resolves.toEqual(undefined)
+    await expect(fs.promises.access(directoryToCreate)).resolves.toEqual(
+      undefined
+    )
+
+    await expect(fs.promises.access(emptyFile1)).rejects.not.toBeUndefined()
+    await expect(fs.promises.access(emptyFile2)).rejects.not.toBeUndefined()
+
+    const emptyFilesToCreate = [emptyFile1, emptyFile2]
+    await utils.createEmptyFilesForArtifact(emptyFilesToCreate)
+
+    await expect(fs.promises.access(emptyFile1)).resolves.toEqual(undefined)
+    const size1 = (await fs.promises.stat(emptyFile1)).size
+    expect(size1).toEqual(0)
+    await expect(fs.promises.access(emptyFile2)).resolves.toEqual(undefined)
+    const size2 = (await fs.promises.stat(emptyFile2)).size
+    expect(size2).toEqual(0)
+  })
+})

packages/artifact/docs/additional-information.md

@@ -0,0 +1,53 @@
+# Additional Information
+
+Extra information 
+- [Non-Supported Characters](#Non-Supported-Characters)
+- [Permission loss](#Permission-Loss)
+- [Considerations](#Considerations)
+- [Compression](#Is-my-artifact-compressed)
+
+## Non-Supported Characters
+
+When uploading an artifact, the inputted `name` parameter along with the files specified in `files` cannot contain any of the following characters. They will be rejected by the server if attempted to be sent over and the upload will fail. These characters are not allowed due to limitations and restrictions with certain file systems such as NTFS. To maintain platform-agnostic behavior, all characters that are not supported by an individual filesystem/platform will not be supported on all filesystems/platforms.
+
+- "
+- :
+- <
+- \>
+- |
+- \*
+- ?
+
+In addition to the aforementioned characters, the inputted `name` also cannot include the following
+- \
+- /
+
+
+## Permission Loss
+
+File permissions are not maintained between uploaded and downloaded artifacts. If file permissions are something that need to be maintained (such as an executable), consider archiving all of the files using something like `tar` and then uploading the single archive. After downloading the artifact, you can `un-tar` the individual file and permissions will be preserved.
+
+```js
+const artifact = require('@actions/artifact');
+const artifactClient = artifact.create()
+const artifactName = 'my-artifact';
+const files = [
+    '/home/user/files/plz-upload/my-archive.tgz',
+]
+const rootDirectory = '/home/user/files/plz-upload'
+const uploadResult = await artifactClient.uploadArtifact(artifactName, files, rootDirectory)
+```
+
+## Considerations
+
+During upload, each file is uploaded concurrently in 4MB chunks using a separate HTTPS connection per file. Chunked uploads are used so that in the event of a failure (which is entirely possible because the internet is not perfect), the upload can be retried. If there is an error, a retry will be attempted after a certain period of time.
+
+Uploading will be generally be faster if there are fewer files that are larger in size vs if there are lots of smaller files. Depending on the types and quantities of files being uploaded, it might be beneficial to separately compress and archive everything into a single archive (using something like `tar` or `zip`) before starting and artifact upload to speed things up.
+
+## Is my artifact compressed?
+
+GZip is used internally to compress individual files before starting an upload. Compression helps reduce the total amount of data that must be uploaded and stored while helping to speed up uploads (this performance benefit is significant especially on self hosted runners). If GZip does not reduce the size of the file that is being uploaded, the original file is uploaded as-is.
+
+Compression using GZip also helps speed up artifact download as part of a workflow. Header information is used to determine if an individual file was uploaded using GZip and if necessary, decompression is used. 
+
+When downloading an artifact from the GitHub UI (this differs from downloading an artifact during a workflow), a single Zip file is dynamically created that contains all of the files uploaded as part of an artifact. Any files that were uploaded using GZip will be decompressed on the server before being added to the Zip file with the remaining files.

packages/artifact/docs/implementation-details.md

@@ -0,0 +1,57 @@
+# Implementation Details
+
+Warning: Implementation details may change at any time without notice. This is meant to serve as a reference to help users understand the package.
+
+## Upload/Compression flow
+
+![image](https://user-images.githubusercontent.com/16109154/79765587-19522b00-8327-11ea-9679-410bb10e1b13.png)
+
+During artifact upload, gzip is used to compress individual files that then get uploaded. This is used to minimize the amount of data that gets uploaded which reduces the total amount of HTTP calls (upload happens in 4MB chunks). This results in considerably faster uploads with huge performance implications especially on self-hosted runners.
+
+If a file is less than 64KB in size, a passthrough stream (readable and writable) is used to convert an in-memory buffer into a readable stream without any extra streams or pipping.
+
+## Retry Logic when downloading an individual file
+
+![image](https://user-images.githubusercontent.com/16109154/78555461-5be71400-780d-11ea-9abd-b05b77a95a3f.png)
+
+## Proxy support
+
+This package uses the `@actions/http-client` NPM package internally which supports proxied requests out of the box.
+
+## HttpManager
+
+### `keep-alive` header
+
+When an HTTP call is made to upload or download an individual file, the server will close the HTTP connection after the upload/download is complete and respond with a header indicating `Connection: close`.
+
+[HTTP closed connection header information](https://tools.ietf.org/html/rfc2616#section-14.10)
+
+TCP connections are sometimes not immediately closed by the node client (Windows might hold on to the port for an extra period of time before actually releasing it for example) and a large amount of closed connections can cause port exhaustion before ports get released and are available again.
+
+VMs hosted by GitHub Actions have 1024 available ports so uploading 1000+ files very quickly can cause port exhaustion if connections get closed immediately. This can start to cause strange undefined behavior and timeouts.
+
+In order for connections to not close immediately, the `keep-alive` header is used to indicate to the server that the connection should stay open. If a `keep-alive` header is used, the connection needs to be disposed of by calling `dispose()` in the `HttpClient`. 
+
+[`keep-alive` header information](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Keep-Alive)
+[@actions/http-client client disposal](https://github.com/actions/http-client/blob/04e5ad73cd3fd1f5610a32116b0759eddf6570d2/index.ts#L292)
+
+
+### Multiple HTTP clients
+
+During an artifact upload or download, files are concurrently uploaded or downloaded using `async/await`. When an error or retry is encountered, the `HttpClient` that made a call is disposed of and a new one is created. If a single `HttpClient` was used for all HTTP calls and it had to be disposed, it could inadvertently effect any other calls that could be concurrently happening.
+
+Any other concurrent uploads or downloads should be left untouched. Because of this, each concurrent upload or download gets its own `HttpClient`. The `http-manager` is used to manage all available clients and each concurrent upload or download maintains a `httpClientIndex` that keep track of which client should be used (and potentially disposed and recycled if necessary)
+
+### Potential resource leaks
+
+When an HTTP response is received, it consists of two parts
+- `message`
+- `body`
+
+The `message` contains information such as the response code and header information and it is available immediately. The body however is not available immediately and it can be read by calling `await response.readBody()`.
+
+TCP connections consist of an input and output buffer to manage what is sent and received across a connection. If the body is not read (even if its contents are not needed) the buffers can stay in use even after `dispose()` gets called on the `HttpClient`. The buffers get released automatically after a certain period of time, but in order for them to be explicitly cleared, `readBody()` is always called.
+
+### Non Concurrent calls
+
+Both `upload-http-client` and `download-http-client` do not instantiate or create any HTTP clients (the `HttpManager` has that responsibility). If an HTTP call has to be made that does not require the `keep-alive` header (such as when calling `listArtifacts` or `patchArtifactSize`), the first `HttpClient` in the `HttpManager` is used. The number of available clients is equal to the upload or download concurrency and there will always be at least one available.

packages/artifact/package-lock.json

@@ -0,0 +1,139 @@
+{
+  "name": "@actions/artifact",
+  "version": "0.5.2",
+  "lockfileVersion": 1,
+  "requires": true,
+  "dependencies": {
+    "@actions/core": {
+      "version": "1.2.6",
+      "resolved": "https://registry.npmjs.org/@actions/core/-/core-1.2.6.tgz",
+      "integrity": "sha512-ZQYitnqiyBc3D+k7LsgSBmMDVkOVidaagDG7j3fOym77jNunWRuYx7VSHa9GNfFZh+zh61xsCjRj4JxMZlDqTA=="
+    },
+    "@actions/http-client": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-1.0.11.tgz",
+      "integrity": "sha512-VRYHGQV1rqnROJqdMvGUbY/Kn8vriQe/F9HR2AlYHzmKuM/p3kjNuXhmdBfcVgsvRWTz5C5XW5xvndZrVBuAYg==",
+      "requires": {
+        "tunnel": "0.0.6"
+      }
+    },
+    "@types/tmp": {
+      "version": "0.2.1",
+      "resolved": "https://registry.npmjs.org/@types/tmp/-/tmp-0.2.1.tgz",
+      "integrity": "sha512-7cTXwKP/HLOPVgjg+YhBdQ7bMiobGMuoBmrGmqwIWJv8elC6t1DfVc/mn4fD9UE1IjhwmhaQ5pGVXkmXbH0rhg==",
+      "dev": true
+    },
+    "balanced-match": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="
+    },
+    "brace-expansion": {
+      "version": "1.1.11",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
+      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "requires": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
+    "concat-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
+      "integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s="
+    },
+    "fs.realpath": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
+      "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8="
+    },
+    "glob": {
+      "version": "7.1.7",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-7.1.7.tgz",
+      "integrity": "sha512-OvD9ENzPLbegENnYP5UUfJIirTg4+XwMWGaQfQTY0JenxNvvIKP3U3/tAQSPIu/lHxXYSZmpXlUHeqAIdKzBLQ==",
+      "requires": {
+        "fs.realpath": "^1.0.0",
+        "inflight": "^1.0.4",
+        "inherits": "2",
+        "minimatch": "^3.0.4",
+        "once": "^1.3.0",
+        "path-is-absolute": "^1.0.0"
+      }
+    },
+    "inflight": {
+      "version": "1.0.6",
+      "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz",
+      "integrity": "sha1-Sb1jMdfQLQwJvJEKEHW6gWW1bfk=",
+      "requires": {
+        "once": "^1.3.0",
+        "wrappy": "1"
+      }
+    },
+    "inherits": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
+      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="
+    },
+    "minimatch": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz",
+      "integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==",
+      "requires": {
+        "brace-expansion": "^1.1.7"
+      }
+    },
+    "once": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
+      "integrity": "sha1-WDsap3WWHUsROsF9nFC6753Xa9E=",
+      "requires": {
+        "wrappy": "1"
+      }
+    },
+    "path-is-absolute": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
+      "integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18="
+    },
+    "rimraf": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-3.0.2.tgz",
+      "integrity": "sha512-JZkJMZkAGFFPP2YqXZXPbMlMBgsxzE8ILs4lMIX/2o0L9UBw9O/Y3o6wFw/i9YLapcUJWwqbi3kdxIPdC62TIA==",
+      "requires": {
+        "glob": "^7.1.3"
+      }
+    },
+    "tmp": {
+      "version": "0.2.1",
+      "resolved": "https://registry.npmjs.org/tmp/-/tmp-0.2.1.tgz",
+      "integrity": "sha512-76SUhtfqR2Ijn+xllcI5P1oyannHNHByD80W1q447gU3mp9G9PSpGdWmjUOHRDPiHYacIk66W7ubDTuPF3BEtQ==",
+      "requires": {
+        "rimraf": "^3.0.0"
+      }
+    },
+    "tmp-promise": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/tmp-promise/-/tmp-promise-3.0.2.tgz",
+      "integrity": "sha512-OyCLAKU1HzBjL6Ev3gxUeraJNlbNingmi8IrHHEsYH8LTmEuhvYfqvhn2F/je+mjf4N58UmZ96OMEy1JanSCpA==",
+      "requires": {
+        "tmp": "^0.2.0"
+      }
+    },
+    "tunnel": {
+      "version": "0.0.6",
+      "resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz",
+      "integrity": "sha512-1h/Lnq9yajKY2PEbBadPXj3VxsDDu844OnaAo52UVmIzIvwwtBPIuNvkjuzBlTWpfJyUbG3ez0KSBibQkj4ojg=="
+    },
+    "typescript": {
+      "version": "3.8.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-3.8.3.tgz",
+      "integrity": "sha512-MYlEfn5VrLNsgudQTVJeNaQFUAI7DkhnOjdpAp4T+ku1TfQClewlbSuTVHiA+8skNBgaf02TL/kLOvig4y3G8w==",
+      "dev": true
+    },
+    "wrappy": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
+      "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8="
+    }
+  }
+}

packages/artifact/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@actions/artifact",
+  "version": "0.5.2",
+  "preview": true,
+  "description": "Actions artifact lib",
+  "keywords": [
+    "github",
+    "actions",
+    "artifact"
+  ],
+  "homepage": "https://github.com/actions/toolkit/tree/main/packages/artifact",
+  "license": "MIT",
+  "main": "lib/artifact-client.js",
+  "types": "lib/artifact-client.d.ts",
+  "directories": {
+    "lib": "lib",
+    "test": "__tests__"
+  },
+  "files": [
+    "lib",
+    "!.DS_Store"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/actions/toolkit.git",
+    "directory": "packages/artifact"
+  },
+  "scripts": {
+    "audit-moderate": "npm install && npm audit --json --audit-level=moderate > audit.json",
+    "test": "echo \"Error: run tests from root\" && exit 1",
+    "tsc": "tsc"
+  },
+  "bugs": {
+    "url": "https://github.com/actions/toolkit/issues"
+  },
+  "dependencies": {
+    "@actions/core": "^1.2.6",
+    "@actions/http-client": "^1.0.11",
+    "tmp": "^0.2.1",
+    "tmp-promise": "^3.0.2"
+  },
+  "devDependencies": {
+    "@types/tmp": "^0.2.1",
+    "typescript": "^3.8.3"
+  }
+}

packages/artifact/src/artifact-client.ts

@@ -0,0 +1,20 @@
+import {UploadOptions} from './internal/upload-options'
+import {UploadResponse} from './internal/upload-response'
+import {DownloadOptions} from './internal/download-options'
+import {DownloadResponse} from './internal/download-response'
+import {ArtifactClient, DefaultArtifactClient} from './internal/artifact-client'
+
+export {
+  ArtifactClient,
+  UploadResponse,
+  UploadOptions,
+  DownloadResponse,
+  DownloadOptions
+}
+
+/**
+ * Constructs an ArtifactClient
+ */
+export function create(): ArtifactClient {
+  return DefaultArtifactClient.create()
+}

packages/artifact/src/internal/__mocks__/config-variables.ts

@@ -0,0 +1,51 @@
+/**
+ *  Mocks default limits for easier testing
+ */
+export function getUploadFileConcurrency(): number {
+  return 1
+}
+
+export function getUploadChunkConcurrency(): number {
+  return 1
+}
+
+export function getUploadChunkSize(): number {
+  return 4 * 1024 * 1024 // 4 MB Chunks
+}
+
+export function getRetryLimit(): number {
+  return 2
+}
+
+export function getRetryMultiplier(): number {
+  return 1.5
+}
+
+export function getInitialRetryIntervalInMilliseconds(): number {
+  return 10
+}
+
+export function getDownloadFileConcurrency(): number {
+  return 1
+}
+
+/**
+ * Mocks the 'ACTIONS_RUNTIME_TOKEN', 'ACTIONS_RUNTIME_URL' and 'GITHUB_RUN_ID' env variables
+ * that are only available from a node context on the runner. This allows for tests to run
+ * locally without the env variables actually being set
+ */
+export function getRuntimeToken(): string {
+  return 'totally-valid-token'
+}
+
+export function getRuntimeUrl(): string {
+  return 'https://www.example.com/'
+}
+
+export function getWorkFlowRunId(): string {
+  return '15'
+}
+
+export function getRetentionDays(): string | undefined {
+  return '45'
+}

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

@@ -0,0 +1,279 @@
+import * as core from '@actions/core'
+import {
+  UploadSpecification,
+  getUploadSpecification
+} from './upload-specification'
+import {UploadHttpClient} from './upload-http-client'
+import {UploadResponse} from './upload-response'
+import {UploadOptions} from './upload-options'
+import {DownloadOptions} from './download-options'
+import {DownloadResponse} from './download-response'
+import {
+  createDirectoriesForArtifact,
+  createEmptyFilesForArtifact
+} from './utils'
+import {checkArtifactName} from './path-and-artifact-name-validation'
+import {DownloadHttpClient} from './download-http-client'
+import {getDownloadSpecification} from './download-specification'
+import {getWorkSpaceDirectory} from './config-variables'
+import {normalize, resolve} from 'path'
+
+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
+   */
+  uploadArtifact(
+    name: string,
+    files: string[],
+    rootDirectory: string,
+    options?: UploadOptions
+  ): Promise<UploadResponse>
+
+  /**
+   * Downloads a single artifact associated with a run
+   *
+   * @param name the name of the artifact being downloaded
+   * @param path optional path that denotes where the artifact will be downloaded to
+   * @param options extra options that allow for the customization of the download behavior
+   */
+  downloadArtifact(
+    name: string,
+    path?: string,
+    options?: DownloadOptions
+  ): Promise<DownloadResponse>
+
+  /**
+   * Downloads all artifacts associated with a run. Because there are multiple artifacts being downloaded, a folder will be created for each one in the specified or default directory
+   * @param path optional path that denotes where the artifacts will be downloaded to
+   */
+  downloadAllArtifacts(path?: string): Promise<DownloadResponse[]>
+}
+
+export class DefaultArtifactClient implements ArtifactClient {
+  /**
+   * Constructs a DefaultArtifactClient
+   */
+  static create(): DefaultArtifactClient {
+    return new DefaultArtifactClient()
+  }
+
+  /**
+   * Uploads an artifact
+   */
+  async uploadArtifact(
+    name: string,
+    files: string[],
+    rootDirectory: string,
+    options?: UploadOptions | undefined
+  ): Promise<UploadResponse> {
+    core.info(
+      `Starting artifact upload
+For more detailed logs during the artifact upload process, enable step-debugging: https://docs.github.com/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging#enabling-step-debug-logging`
+    )
+    checkArtifactName(name)
+
+    // Get specification for the files being uploaded
+    const uploadSpecification: UploadSpecification[] = getUploadSpecification(
+      name,
+      rootDirectory,
+      files
+    )
+    const uploadResponse: UploadResponse = {
+      artifactName: name,
+      artifactItems: [],
+      size: 0,
+      failedItems: []
+    }
+
+    const uploadHttpClient = new UploadHttpClient()
+
+    if (uploadSpecification.length === 0) {
+      core.warning(`No files found that can be uploaded`)
+    } else {
+      // Create an entry for the artifact in the file container
+      const response = await uploadHttpClient.createArtifactInFileContainer(
+        name,
+        options
+      )
+      if (!response.fileContainerResourceUrl) {
+        core.debug(response.toString())
+        throw new Error(
+          'No URL provided by the Artifact Service to upload an artifact to'
+        )
+      }
+
+      core.debug(`Upload Resource URL: ${response.fileContainerResourceUrl}`)
+      core.info(
+        `Container for artifact "${name}" successfully created. Starting upload of file(s)`
+      )
+
+      // Upload each of the files that were found concurrently
+      const uploadResult = await uploadHttpClient.uploadArtifactToFileContainer(
+        response.fileContainerResourceUrl,
+        uploadSpecification,
+        options
+      )
+
+      // Update the size of the artifact to indicate we are done uploading
+      // The uncompressed size is used for display when downloading a zip of the artifact from the UI
+      core.info(
+        `File upload process has finished. Finalizing the artifact upload`
+      )
+      await uploadHttpClient.patchArtifactSize(uploadResult.totalSize, name)
+
+      if (uploadResult.failedItems.length > 0) {
+        core.info(
+          `Upload finished. There were ${uploadResult.failedItems.length} items that failed to upload`
+        )
+      } else {
+        core.info(
+          `Artifact has been finalized. All files have been successfully uploaded!`
+        )
+      }
+
+      core.info(
+        `
+The raw size of all the files that were specified for upload is ${uploadResult.totalSize} bytes
+The size of all the files that were uploaded is ${uploadResult.uploadSize} bytes. This takes into account any gzip compression used to reduce the upload size, time and storage
+
+Note: The size of downloaded zips can differ significantly from the reported size. For more information see: https://github.com/actions/upload-artifact#zipped-artifact-downloads \r\n`
+      )
+
+      uploadResponse.artifactItems = uploadSpecification.map(
+        item => item.absoluteFilePath
+      )
+      uploadResponse.size = uploadResult.uploadSize
+      uploadResponse.failedItems = uploadResult.failedItems
+    }
+    return uploadResponse
+  }
+
+  async downloadArtifact(
+    name: string,
+    path?: string | undefined,
+    options?: DownloadOptions | undefined
+  ): Promise<DownloadResponse> {
+    const downloadHttpClient = new DownloadHttpClient()
+
+    const artifacts = await downloadHttpClient.listArtifacts()
+    if (artifacts.count === 0) {
+      throw new Error(
+        `Unable to find any artifacts for the associated workflow`
+      )
+    }
+
+    const artifactToDownload = artifacts.value.find(artifact => {
+      return artifact.name === name
+    })
+    if (!artifactToDownload) {
+      throw new Error(`Unable to find an artifact with the name: ${name}`)
+    }
+
+    const items = await downloadHttpClient.getContainerItems(
+      artifactToDownload.name,
+      artifactToDownload.fileContainerResourceUrl
+    )
+
+    if (!path) {
+      path = getWorkSpaceDirectory()
+    }
+    path = normalize(path)
+    path = resolve(path)
+
+    // During upload, empty directories are rejected by the remote server so there should be no artifacts that consist of only empty directories
+    const downloadSpecification = getDownloadSpecification(
+      name,
+      items.value,
+      path,
+      options?.createArtifactFolder || false
+    )
+
+    if (downloadSpecification.filesToDownload.length === 0) {
+      core.info(
+        `No downloadable files were found for the artifact: ${artifactToDownload.name}`
+      )
+    } else {
+      // Create all necessary directories recursively before starting any download
+      await createDirectoriesForArtifact(
+        downloadSpecification.directoryStructure
+      )
+      core.info('Directory structure has been setup for the artifact')
+      await createEmptyFilesForArtifact(
+        downloadSpecification.emptyFilesToCreate
+      )
+      await downloadHttpClient.downloadSingleArtifact(
+        downloadSpecification.filesToDownload
+      )
+    }
+
+    return {
+      artifactName: name,
+      downloadPath: downloadSpecification.rootDownloadLocation
+    }
+  }
+
+  async downloadAllArtifacts(
+    path?: string | undefined
+  ): Promise<DownloadResponse[]> {
+    const downloadHttpClient = new DownloadHttpClient()
+
+    const response: DownloadResponse[] = []
+    const artifacts = await downloadHttpClient.listArtifacts()
+    if (artifacts.count === 0) {
+      core.info('Unable to find any artifacts for the associated workflow')
+      return response
+    }
+
+    if (!path) {
+      path = getWorkSpaceDirectory()
+    }
+    path = normalize(path)
+    path = resolve(path)
+
+    let downloadedArtifacts = 0
+    while (downloadedArtifacts < artifacts.count) {
+      const currentArtifactToDownload = artifacts.value[downloadedArtifacts]
+      downloadedArtifacts += 1
+
+      // Get container entries for the specific artifact
+      const items = await downloadHttpClient.getContainerItems(
+        currentArtifactToDownload.name,
+        currentArtifactToDownload.fileContainerResourceUrl
+      )
+
+      const downloadSpecification = getDownloadSpecification(
+        currentArtifactToDownload.name,
+        items.value,
+        path,
+        true
+      )
+      if (downloadSpecification.filesToDownload.length === 0) {
+        core.info(
+          `No downloadable files were found for any artifact ${currentArtifactToDownload.name}`
+        )
+      } else {
+        await createDirectoriesForArtifact(
+          downloadSpecification.directoryStructure
+        )
+        await createEmptyFilesForArtifact(
+          downloadSpecification.emptyFilesToCreate
+        )
+        await downloadHttpClient.downloadSingleArtifact(
+          downloadSpecification.filesToDownload
+        )
+      }
+
+      response.push({
+        artifactName: currentArtifactToDownload.name,
+        downloadPath: downloadSpecification.rootDownloadLocation
+      })
+    }
+    return response
+  }
+}

packages/artifact/src/internal/config-variables.ts

@@ -0,0 +1,67 @@
+// The number of concurrent uploads that happens at the same time
+export function getUploadFileConcurrency(): number {
+  return 2
+}
+
+// When uploading large files that can't be uploaded with a single http call, this controls
+// the chunk size that is used during upload
+export function getUploadChunkSize(): number {
+  return 8 * 1024 * 1024 // 8 MB Chunks
+}
+
+// The maximum number of retries that can be attempted before an upload or download fails
+export function getRetryLimit(): number {
+  return 5
+}
+
+// With exponential backoff, the larger the retry count, the larger the wait time before another attempt
+// The retry multiplier controls by how much the backOff time increases depending on the number of retries
+export function getRetryMultiplier(): number {
+  return 1.5
+}
+
+// The initial wait time if an upload or download fails and a retry is being attempted for the first time
+export function getInitialRetryIntervalInMilliseconds(): number {
+  return 3000
+}
+
+// The number of concurrent downloads that happens at the same time
+export function getDownloadFileConcurrency(): number {
+  return 2
+}
+
+export function getRuntimeToken(): string {
+  const token = process.env['ACTIONS_RUNTIME_TOKEN']
+  if (!token) {
+    throw new Error('Unable to get ACTIONS_RUNTIME_TOKEN env variable')
+  }
+  return token
+}
+
+export function getRuntimeUrl(): string {
+  const runtimeUrl = process.env['ACTIONS_RUNTIME_URL']
+  if (!runtimeUrl) {
+    throw new Error('Unable to get ACTIONS_RUNTIME_URL env variable')
+  }
+  return runtimeUrl
+}
+
+export function getWorkFlowRunId(): string {
+  const workFlowRunId = process.env['GITHUB_RUN_ID']
+  if (!workFlowRunId) {
+    throw new Error('Unable to get GITHUB_RUN_ID env variable')
+  }
+  return workFlowRunId
+}
+
+export function getWorkSpaceDirectory(): string {
+  const workspaceDirectory = process.env['GITHUB_WORKSPACE']
+  if (!workspaceDirectory) {
+    throw new Error('Unable to get GITHUB_WORKSPACE env variable')
+  }
+  return workspaceDirectory
+}
+
+export function getRetentionDays(): string | undefined {
+  return process.env['GITHUB_RETENTION_DAYS']
+}

packages/artifact/src/internal/contracts.ts

@@ -0,0 +1,76 @@
+export interface ArtifactResponse {
+  containerId: string
+  size: number
+  signedContent: string
+  fileContainerResourceUrl: string
+  type: string
+  name: string
+  url: string
+}
+
+export interface CreateArtifactParameters {
+  Type: string
+  Name: string
+  RetentionDays?: number
+}
+
+export interface PatchArtifactSize {
+  Size: number
+}
+
+export interface PatchArtifactSizeSuccessResponse {
+  containerId: number
+  size: number
+  signedContent: string
+  type: string
+  name: string
+  url: string
+  uploadUrl: string
+}
+
+export interface UploadResults {
+  /**
+   * The size in bytes of data that was transferred during the upload process to the actions backend service. This takes into account possible
+   * gzip compression to reduce the amount of data that needs to be transferred
+   */
+  uploadSize: number
+
+  /**
+   * The raw size of the files that were specified for upload
+   */
+  totalSize: number
+
+  /**
+   * An array of files that failed to upload
+   */
+  failedItems: string[]
+}
+
+export interface ListArtifactsResponse {
+  count: number
+  value: ArtifactResponse[]
+}
+
+export interface QueryArtifactResponse {
+  count: number
+  value: ContainerEntry[]
+}
+
+export interface ContainerEntry {
+  containerId: number
+  scopeIdentifier: string
+  path: string
+  itemType: string
+  status: string
+  fileLength?: number
+  fileEncoding?: number
+  fileType?: number
+  dateCreated: string
+  dateLastModified: string
+  createdBy: string
+  lastModifiedBy: string
+  itemLocation: string
+  contentLocation: string
+  fileId?: number
+  contentId: string
+}

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

@@ -0,0 +1,358 @@
+import * as fs from 'fs'
+import * as core from '@actions/core'
+import * as zlib from 'zlib'
+import {
+  getArtifactUrl,
+  getDownloadHeaders,
+  isSuccessStatusCode,
+  isRetryableStatusCode,
+  isThrottledStatusCode,
+  getExponentialRetryTimeInMilliseconds,
+  tryGetRetryAfterValueTimeInMilliseconds,
+  displayHttpDiagnostics,
+  getFileSize,
+  rmFile,
+  sleep
+} from './utils'
+import {URL} from 'url'
+import {StatusReporter} from './status-reporter'
+import {performance} from 'perf_hooks'
+import {ListArtifactsResponse, QueryArtifactResponse} from './contracts'
+import {IHttpClientResponse} from '@actions/http-client/interfaces'
+import {HttpManager} from './http-manager'
+import {DownloadItem} from './download-specification'
+import {getDownloadFileConcurrency, getRetryLimit} from './config-variables'
+import {IncomingHttpHeaders} from 'http'
+import {retryHttpClientRequest} from './requestUtils'
+
+export class DownloadHttpClient {
+  // http manager is used for concurrent connections when downloading multiple files at once
+  private downloadHttpManager: HttpManager
+  private statusReporter: StatusReporter
+
+  constructor() {
+    this.downloadHttpManager = new HttpManager(
+      getDownloadFileConcurrency(),
+      '@actions/artifact-download'
+    )
+    // downloads are usually significantly faster than uploads so display status information every second
+    this.statusReporter = new StatusReporter(1000)
+  }
+
+  /**
+   * Gets a list of all artifacts that are in a specific container
+   */
+  async listArtifacts(): Promise<ListArtifactsResponse> {
+    const artifactUrl = getArtifactUrl()
+
+    // use the first client from the httpManager, `keep-alive` is not used so the connection will close immediately
+    const client = this.downloadHttpManager.getClient(0)
+    const headers = getDownloadHeaders('application/json')
+    const response = await retryHttpClientRequest('List Artifacts', async () =>
+      client.get(artifactUrl, headers)
+    )
+    const body: string = await response.readBody()
+    return JSON.parse(body)
+  }
+
+  /**
+   * Fetches a set of container items that describe the contents of an artifact
+   * @param artifactName the name of the artifact
+   * @param containerUrl the artifact container URL for the run
+   */
+  async getContainerItems(
+    artifactName: string,
+    containerUrl: string
+  ): Promise<QueryArtifactResponse> {
+    // the itemPath search parameter controls which containers will be returned
+    const resourceUrl = new URL(containerUrl)
+    resourceUrl.searchParams.append('itemPath', artifactName)
+
+    // use the first client from the httpManager, `keep-alive` is not used so the connection will close immediately
+    const client = this.downloadHttpManager.getClient(0)
+    const headers = getDownloadHeaders('application/json')
+    const response = await retryHttpClientRequest(
+      'Get Container Items',
+      async () => client.get(resourceUrl.toString(), headers)
+    )
+    const body: string = await response.readBody()
+    return JSON.parse(body)
+  }
+
+  /**
+   * Concurrently downloads all the files that are part of an artifact
+   * @param downloadItems information about what items to download and where to save them
+   */
+  async downloadSingleArtifact(downloadItems: DownloadItem[]): Promise<void> {
+    const DOWNLOAD_CONCURRENCY = getDownloadFileConcurrency()
+    // limit the number of files downloaded at a single time
+    core.debug(`Download file concurrency is set to ${DOWNLOAD_CONCURRENCY}`)
+    const parallelDownloads = [...new Array(DOWNLOAD_CONCURRENCY).keys()]
+    let currentFile = 0
+    let downloadedFiles = 0
+
+    core.info(
+      `Total number of files that will be downloaded: ${downloadItems.length}`
+    )
+
+    this.statusReporter.setTotalNumberOfFilesToProcess(downloadItems.length)
+    this.statusReporter.start()
+
+    await Promise.all(
+      parallelDownloads.map(async index => {
+        while (currentFile < downloadItems.length) {
+          const currentFileToDownload = downloadItems[currentFile]
+          currentFile += 1
+
+          const startTime = performance.now()
+          await this.downloadIndividualFile(
+            index,
+            currentFileToDownload.sourceLocation,
+            currentFileToDownload.targetPath
+          )
+
+          if (core.isDebug()) {
+            core.debug(
+              `File: ${++downloadedFiles}/${downloadItems.length}. ${
+                currentFileToDownload.targetPath
+              } took ${(performance.now() - startTime).toFixed(
+                3
+              )} milliseconds to finish downloading`
+            )
+          }
+
+          this.statusReporter.incrementProcessedCount()
+        }
+      })
+    )
+      .catch(error => {
+        throw new Error(`Unable to download the artifact: ${error}`)
+      })
+      .finally(() => {
+        this.statusReporter.stop()
+        // safety dispose all connections
+        this.downloadHttpManager.disposeAndReplaceAllClients()
+      })
+  }
+
+  /**
+   * Downloads an individual file
+   * @param httpClientIndex the index of the http client that is used to make all of the calls
+   * @param artifactLocation origin location where a file will be downloaded from
+   * @param downloadPath destination location for the file being downloaded
+   */
+  private async downloadIndividualFile(
+    httpClientIndex: number,
+    artifactLocation: string,
+    downloadPath: string
+  ): Promise<void> {
+    let retryCount = 0
+    const retryLimit = getRetryLimit()
+    let destinationStream = fs.createWriteStream(downloadPath)
+    const headers = getDownloadHeaders('application/json', true, true)
+
+    // a single GET request is used to download a file
+    const makeDownloadRequest = async (): Promise<IHttpClientResponse> => {
+      const client = this.downloadHttpManager.getClient(httpClientIndex)
+      return await client.get(artifactLocation, headers)
+    }
+
+    // check the response headers to determine if the file was compressed using gzip
+    const isGzip = (incomingHeaders: IncomingHttpHeaders): boolean => {
+      return (
+        'content-encoding' in incomingHeaders &&
+        incomingHeaders['content-encoding'] === 'gzip'
+      )
+    }
+
+    // Increments the current retry count and then checks if the retry limit has been reached
+    // If there have been too many retries, fail so the download stops. If there is a retryAfterValue value provided,
+    // it will be used
+    const backOff = async (retryAfterValue?: number): Promise<void> => {
+      retryCount++
+      if (retryCount > retryLimit) {
+        return Promise.reject(
+          new Error(
+            `Retry limit has been reached. Unable to download ${artifactLocation}`
+          )
+        )
+      } else {
+        this.downloadHttpManager.disposeAndReplaceClient(httpClientIndex)
+        if (retryAfterValue) {
+          // Back off by waiting the specified time denoted by the retry-after header
+          core.info(
+            `Backoff due to too many requests, retry #${retryCount}. Waiting for ${retryAfterValue} milliseconds before continuing the download`
+          )
+          await sleep(retryAfterValue)
+        } else {
+          // Back off using an exponential value that depends on the retry count
+          const backoffTime = getExponentialRetryTimeInMilliseconds(retryCount)
+          core.info(
+            `Exponential backoff for retry #${retryCount}. Waiting for ${backoffTime} milliseconds before continuing the download`
+          )
+          await sleep(backoffTime)
+        }
+        core.info(
+          `Finished backoff for retry #${retryCount}, continuing with download`
+        )
+      }
+    }
+
+    const isAllBytesReceived = (
+      expected?: string,
+      received?: number
+    ): boolean => {
+      // be lenient, if any input is missing, assume success, i.e. not truncated
+      if (
+        !expected ||
+        !received ||
+        process.env['ACTIONS_ARTIFACT_SKIP_DOWNLOAD_VALIDATION']
+      ) {
+        core.info('Skipping download validation.')
+        return true
+      }
+
+      return parseInt(expected) === received
+    }
+
+    const resetDestinationStream = async (
+      fileDownloadPath: string
+    ): Promise<void> => {
+      destinationStream.close()
+      await rmFile(fileDownloadPath)
+      destinationStream = fs.createWriteStream(fileDownloadPath)
+    }
+
+    // keep trying to download a file until a retry limit has been reached
+    while (retryCount <= retryLimit) {
+      let response: IHttpClientResponse
+      try {
+        response = await makeDownloadRequest()
+        if (core.isDebug()) {
+          displayHttpDiagnostics(response)
+        }
+      } catch (error) {
+        // if an error is caught, it is usually indicative of a timeout so retry the download
+        core.info('An error occurred while attempting to download a file')
+        // eslint-disable-next-line no-console
+        console.log(error)
+
+        // increment the retryCount and use exponential backoff to wait before making the next request
+        await backOff()
+        continue
+      }
+
+      let forceRetry = false
+      if (isSuccessStatusCode(response.message.statusCode)) {
+        // The body contains the contents of the file however calling response.readBody() causes all the content to be converted to a string
+        // which can cause some gzip encoded data to be lost
+        // Instead of using response.readBody(), response.message is a readableStream that can be directly used to get the raw body contents
+        try {
+          const isGzipped = isGzip(response.message.headers)
+          await this.pipeResponseToFile(response, destinationStream, isGzipped)
+
+          if (
+            isGzipped ||
+            isAllBytesReceived(
+              response.message.headers['content-length'],
+              await getFileSize(downloadPath)
+            )
+          ) {
+            return
+          } else {
+            forceRetry = true
+          }
+        } catch (error) {
+          // retry on error, most likely streams were corrupted
+          forceRetry = true
+        }
+      }
+
+      if (forceRetry || isRetryableStatusCode(response.message.statusCode)) {
+        core.info(
+          `A ${response.message.statusCode} response code has been received while attempting to download an artifact`
+        )
+        resetDestinationStream(downloadPath)
+        // if a throttled status code is received, try to get the retryAfter header value, else differ to standard exponential backoff
+        isThrottledStatusCode(response.message.statusCode)
+          ? await backOff(
+              tryGetRetryAfterValueTimeInMilliseconds(response.message.headers)
+            )
+          : await backOff()
+      } else {
+        // Some unexpected response code, fail immediately and stop the download
+        displayHttpDiagnostics(response)
+        return Promise.reject(
+          new Error(
+            `Unexpected http ${response.message.statusCode} during download for ${artifactLocation}`
+          )
+        )
+      }
+    }
+  }
+
+  /**
+   * Pipes the response from downloading an individual file to the appropriate destination stream while decoding gzip content if necessary
+   * @param response the http response received when downloading a file
+   * @param destinationStream the stream where the file should be written to
+   * @param isGzip a boolean denoting if the content is compressed using gzip and if we need to decode it
+   */
+  async pipeResponseToFile(
+    response: IHttpClientResponse,
+    destinationStream: fs.WriteStream,
+    isGzip: boolean
+  ): Promise<void> {
+    await new Promise((resolve, reject) => {
+      if (isGzip) {
+        const gunzip = zlib.createGunzip()
+        response.message
+          .on('error', error => {
+            core.error(
+              `An error occurred while attempting to read the response stream`
+            )
+            gunzip.close()
+            destinationStream.close()
+            reject(error)
+          })
+          .pipe(gunzip)
+          .on('error', error => {
+            core.error(
+              `An error occurred while attempting to decompress the response stream`
+            )
+            destinationStream.close()
+            reject(error)
+          })
+          .pipe(destinationStream)
+          .on('close', () => {
+            resolve()
+          })
+          .on('error', error => {
+            core.error(
+              `An error occurred while writing a downloaded file to ${destinationStream.path}`
+            )
+            reject(error)
+          })
+      } else {
+        response.message
+          .on('error', error => {
+            core.error(
+              `An error occurred while attempting to read the response stream`
+            )
+            destinationStream.close()
+            reject(error)
+          })
+          .pipe(destinationStream)
+          .on('close', () => {
+            resolve()
+          })
+          .on('error', error => {
+            core.error(
+              `An error occurred while writing a downloaded file to ${destinationStream.path}`
+            )
+            reject(error)
+          })
+      }
+    })
+    return
+  }
+}

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

@@ -0,0 +1,7 @@
+export interface DownloadOptions {
+  /**
+   * Specifies if a folder is created for the artifact that is downloaded (contents downloaded into this folder),
+   * defaults to false if not specified
+   * */
+  createArtifactFolder?: boolean
+}

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

@@ -0,0 +1,11 @@
+export interface DownloadResponse {
+  /**
+   * The name of the artifact that was downloaded
+   */
+  artifactName: string
+
+  /**
+   * The full Path to where the artifact was downloaded
+   */
+  downloadPath: string
+}

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

@@ -0,0 +1,87 @@
+import * as path from 'path'
+import {ContainerEntry} from './contracts'
+
+export interface DownloadSpecification {
+  // root download location for the artifact
+  rootDownloadLocation: string
+
+  // directories that need to be created for all the items in the artifact
+  directoryStructure: string[]
+
+  // empty files that are part of the artifact that don't require any downloading
+  emptyFilesToCreate: string[]
+
+  // individual files that need to be downloaded as part of the artifact
+  filesToDownload: DownloadItem[]
+}
+
+export interface DownloadItem {
+  // Url that denotes where to download the item from
+  sourceLocation: string
+
+  // Information about where the file should be downloaded to
+  targetPath: string
+}
+
+/**
+ * Creates a specification for a set of files that will be downloaded
+ * @param artifactName the name of the artifact
+ * @param artifactEntries a set of container entries that describe that files that make up an artifact
+ * @param downloadPath the path where the artifact will be downloaded to
+ * @param includeRootDirectory specifies if there should be an extra directory (denoted by the artifact name) where the artifact files should be downloaded to
+ */
+export function getDownloadSpecification(
+  artifactName: string,
+  artifactEntries: ContainerEntry[],
+  downloadPath: string,
+  includeRootDirectory: boolean
+): DownloadSpecification {
+  // use a set for the directory paths so that there are no duplicates
+  const directories = new Set<string>()
+
+  const specifications: DownloadSpecification = {
+    rootDownloadLocation: includeRootDirectory
+      ? path.join(downloadPath, artifactName)
+      : downloadPath,
+    directoryStructure: [],
+    emptyFilesToCreate: [],
+    filesToDownload: []
+  }
+
+  for (const entry of artifactEntries) {
+    // Ignore artifacts in the container that don't begin with the same name
+    if (
+      entry.path.startsWith(`${artifactName}/`) ||
+      entry.path.startsWith(`${artifactName}\\`)
+    ) {
+      // normalize all separators to the local OS
+      const normalizedPathEntry = path.normalize(entry.path)
+      // entry.path always starts with the artifact name, if includeRootDirectory is false, remove the name from the beginning of the path
+      const filePath = path.join(
+        downloadPath,
+        includeRootDirectory
+          ? normalizedPathEntry
+          : normalizedPathEntry.replace(artifactName, '')
+      )
+
+      // Case insensitive folder structure maintained in the backend, not every folder is created so the 'folder'
+      // itemType cannot be relied upon. The file must be used to determine the directory structure
+      if (entry.itemType === 'file') {
+        // Get the directories that we need to create from the filePath for each individual file
+        directories.add(path.dirname(filePath))
+        if (entry.fileLength === 0) {
+          // An empty file was uploaded, create the empty files locally so that no extra http calls are made
+          specifications.emptyFilesToCreate.push(filePath)
+        } else {
+          specifications.filesToDownload.push({
+            sourceLocation: entry.contentLocation,
+            targetPath: filePath
+          })
+        }
+      }
+    }
+  }
+
+  specifications.directoryStructure = Array.from(directories)
+  return specifications
+}

packages/artifact/src/internal/http-manager.ts

@@ -0,0 +1,35 @@
+import {HttpClient} from '@actions/http-client/index'
+import {createHttpClient} from './utils'
+
+/**
+ * Used for managing http clients during either upload or download
+ */
+export class HttpManager {
+  private clients: HttpClient[]
+  private userAgent: string
+
+  constructor(clientCount: number, userAgent: string) {
+    if (clientCount < 1) {
+      throw new Error('There must be at least one client')
+    }
+    this.userAgent = userAgent
+    this.clients = new Array(clientCount).fill(createHttpClient(userAgent))
+  }
+
+  getClient(index: number): HttpClient {
+    return this.clients[index]
+  }
+
+  // client disposal is necessary if a keep-alive connection is used to properly close the connection
+  // for more information see: https://github.com/actions/http-client/blob/04e5ad73cd3fd1f5610a32116b0759eddf6570d2/index.ts#L292
+  disposeAndReplaceClient(index: number): void {
+    this.clients[index].dispose()
+    this.clients[index] = createHttpClient(this.userAgent)
+  }
+
+  disposeAndReplaceAllClients(): void {
+    for (const [index] of this.clients.entries()) {
+      this.disposeAndReplaceClient(index)
+    }
+  }
+}

packages/artifact/src/internal/path-and-artifact-name-validation.ts

@@ -0,0 +1,82 @@
+import {info} from '@actions/core'
+
+/**
+ * Invalid characters that cannot be in the artifact name or an uploaded file. Will be rejected
+ * from the server if attempted to be sent over. These characters are not allowed due to limitations with certain
+ * file systems such as NTFS. To maintain platform-agnostic behavior, all characters that are not supported by an
+ * individual filesystem/platform will not be supported on all fileSystems/platforms
+ *
+ * FilePaths can include characters such as \ and / which are not permitted in the artifact name alone
+ */
+const invalidArtifactFilePathCharacters = new Map<string, string>([
+  ['"', ' Double quote "'],
+  [':', ' Colon :'],
+  ['<', ' Less than <'],
+  ['>', ' Greater than >'],
+  ['|', ' Vertical bar |'],
+  ['*', ' Asterisk *'],
+  ['?', ' Question mark ?'],
+  ['\r', ' Carriage return \\r'],
+  ['\n', ' Line feed \\n']
+])
+
+const invalidArtifactNameCharacters = new Map<string, string>([
+  ...invalidArtifactFilePathCharacters,
+  ['\\', ' Backslash \\'],
+  ['/', ' Forward slash /']
+])
+
+/**
+ * Scans the name of the artifact to make sure there are no illegal characters
+ */
+export function checkArtifactName(name: string): void {
+  if (!name) {
+    throw new Error(`Artifact name: ${name}, is incorrectly provided`)
+  }
+
+  for (const [
+    invalidCharacterKey,
+    errorMessageForCharacter
+  ] of invalidArtifactNameCharacters) {
+    if (name.includes(invalidCharacterKey)) {
+      throw new Error(
+        `Artifact name is not valid: ${name}. Contains the following character: ${errorMessageForCharacter}
+          
+Invalid characters include: ${Array.from(
+          invalidArtifactNameCharacters.values()
+        ).toString()}
+          
+These characters are not allowed in the artifact name due to limitations with certain file systems such as NTFS. To maintain file system agnostic behavior, these characters are intentionally not allowed to prevent potential problems with downloads on different file systems.`
+      )
+    }
+  }
+
+  info(`Artifact name is valid!`)
+}
+
+/**
+ * Scans the name of the filePath used to make sure there are no illegal characters
+ */
+export function checkArtifactFilePath(path: string): void {
+  if (!path) {
+    throw new Error(`Artifact path: ${path}, is incorrectly provided`)
+  }
+
+  for (const [
+    invalidCharacterKey,
+    errorMessageForCharacter
+  ] of invalidArtifactFilePathCharacters) {
+    if (path.includes(invalidCharacterKey)) {
+      throw new Error(
+        `Artifact path is not valid: ${path}. Contains the following character: ${errorMessageForCharacter}
+          
+Invalid characters include: ${Array.from(
+          invalidArtifactFilePathCharacters.values()
+        ).toString()}
+          
+The following characters are not allowed in files that are uploaded due to limitations with certain file systems such as NTFS. To maintain file system agnostic behavior, these characters are intentionally not allowed to prevent potential problems with downloads on different file systems.
+          `
+      )
+    }
+  }
+}

packages/artifact/src/internal/requestUtils.ts

@@ -0,0 +1,79 @@
+import {IHttpClientResponse} from '@actions/http-client/interfaces'
+import {
+  isRetryableStatusCode,
+  isSuccessStatusCode,
+  sleep,
+  getExponentialRetryTimeInMilliseconds,
+  displayHttpDiagnostics
+} from './utils'
+import * as core from '@actions/core'
+import {getRetryLimit} from './config-variables'
+
+export async function retry(
+  name: string,
+  operation: () => Promise<IHttpClientResponse>,
+  customErrorMessages: Map<number, string>,
+  maxAttempts: number
+): Promise<IHttpClientResponse> {
+  let response: IHttpClientResponse | undefined = undefined
+  let statusCode: number | undefined = undefined
+  let isRetryable = false
+  let errorMessage = ''
+  let customErrorInformation: string | undefined = undefined
+  let attempt = 1
+
+  while (attempt <= maxAttempts) {
+    try {
+      response = await operation()
+      statusCode = response.message.statusCode
+
+      if (isSuccessStatusCode(statusCode)) {
+        return response
+      }
+
+      // Extra error information that we want to display if a particular response code is hit
+      if (statusCode) {
+        customErrorInformation = customErrorMessages.get(statusCode)
+      }
+
+      isRetryable = isRetryableStatusCode(statusCode)
+      errorMessage = `Artifact service responded with ${statusCode}`
+    } catch (error) {
+      isRetryable = true
+      errorMessage = error.message
+    }
+
+    if (!isRetryable) {
+      core.info(`${name} - Error is not retryable`)
+      if (response) {
+        displayHttpDiagnostics(response)
+      }
+      break
+    }
+
+    core.info(
+      `${name} - Attempt ${attempt} of ${maxAttempts} failed with error: ${errorMessage}`
+    )
+
+    await sleep(getExponentialRetryTimeInMilliseconds(attempt))
+    attempt++
+  }
+
+  if (response) {
+    displayHttpDiagnostics(response)
+  }
+
+  if (customErrorInformation) {
+    throw Error(`${name} failed: ${customErrorInformation}`)
+  }
+  throw Error(`${name} failed: ${errorMessage}`)
+}
+
+export async function retryHttpClientRequest(
+  name: string,
+  method: () => Promise<IHttpClientResponse>,
+  customErrorMessages: Map<number, string> = new Map(),
+  maxAttempts = getRetryLimit()
+): Promise<IHttpClientResponse> {
+  return await retry(name, method, customErrorMessages, maxAttempts)
+}

packages/artifact/src/internal/status-reporter.ts

@@ -0,0 +1,78 @@
+import {info} from '@actions/core'
+
+/**
+ * Status Reporter that displays information about the progress/status of an artifact that is being uploaded or downloaded
+ *
+ * Variable display time that can be adjusted using the displayFrequencyInMilliseconds variable
+ * The total status of the upload/download gets displayed according to this value
+ * If there is a large file that is being uploaded, extra information about the individual status can also be displayed using the updateLargeFileStatus function
+ */
+
+export class StatusReporter {
+  private totalNumberOfFilesToProcess = 0
+  private processedCount = 0
+  private displayFrequencyInMilliseconds: number
+  private largeFiles = new Map<string, string>()
+  private totalFileStatus: NodeJS.Timeout | undefined
+
+  constructor(displayFrequencyInMilliseconds: number) {
+    this.totalFileStatus = undefined
+    this.displayFrequencyInMilliseconds = displayFrequencyInMilliseconds
+  }
+
+  setTotalNumberOfFilesToProcess(fileTotal: number): void {
+    this.totalNumberOfFilesToProcess = fileTotal
+    this.processedCount = 0
+  }
+
+  start(): void {
+    // displays information about the total upload/download status
+    this.totalFileStatus = setInterval(() => {
+      // display 1 decimal place without any rounding
+      const percentage = this.formatPercentage(
+        this.processedCount,
+        this.totalNumberOfFilesToProcess
+      )
+      info(
+        `Total file count: ${
+          this.totalNumberOfFilesToProcess
+        } ---- Processed file #${this.processedCount} (${percentage.slice(
+          0,
+          percentage.indexOf('.') + 2
+        )}%)`
+      )
+    }, this.displayFrequencyInMilliseconds)
+  }
+
+  // if there is a large file that is being uploaded in chunks, this is used to display extra information about the status of the upload
+  updateLargeFileStatus(
+    fileName: string,
+    chunkStartIndex: number,
+    chunkEndIndex: number,
+    totalUploadFileSize: number
+  ): void {
+    // display 1 decimal place without any rounding
+    const percentage = this.formatPercentage(chunkEndIndex, totalUploadFileSize)
+    info(
+      `Uploaded ${fileName} (${percentage.slice(
+        0,
+        percentage.indexOf('.') + 2
+      )}%) chunks ${chunkStartIndex}:${chunkEndIndex}`
+    )
+  }
+
+  stop(): void {
+    if (this.totalFileStatus) {
+      clearInterval(this.totalFileStatus)
+    }
+  }
+
+  incrementProcessedCount(): void {
+    this.processedCount++
+  }
+
+  private formatPercentage(numerator: number, denominator: number): string {
+    // toFixed() rounds, so use extra precision to display accurate information even though 4 decimal places are not displayed
+    return ((numerator / denominator) * 100).toFixed(4).toString()
+  }
+}

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

@@ -0,0 +1,53 @@
+import * as fs from 'fs'
+import * as zlib from 'zlib'
+import {promisify} from 'util'
+const stat = promisify(fs.stat)
+
+/**
+ * Creates a Gzip compressed file of an original file at the provided temporary filepath location
+ * @param {string} originalFilePath filepath of whatever will be compressed. The original file will be unmodified
+ * @param {string} tempFilePath the location of where the Gzip file will be created
+ * @returns the size of gzip file that gets created
+ */
+export async function createGZipFileOnDisk(
+  originalFilePath: string,
+  tempFilePath: string
+): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const inputStream = fs.createReadStream(originalFilePath)
+    const gzip = zlib.createGzip()
+    const outputStream = fs.createWriteStream(tempFilePath)
+    inputStream.pipe(gzip).pipe(outputStream)
+    outputStream.on('finish', async () => {
+      // wait for stream to finish before calculating the size which is needed as part of the Content-Length header when starting an upload
+      const size = (await stat(tempFilePath)).size
+      resolve(size)
+    })
+    outputStream.on('error', error => {
+      // eslint-disable-next-line no-console
+      console.log(error)
+      reject
+    })
+  })
+}
+
+/**
+ * Creates a GZip file in memory using a buffer. Should be used for smaller files to reduce disk I/O
+ * @param originalFilePath the path to the original file that is being GZipped
+ * @returns a buffer with the GZip file
+ */
+export async function createGZipFileInBuffer(
+  originalFilePath: string
+): Promise<Buffer> {
+  return new Promise(async resolve => {
+    const inputStream = fs.createReadStream(originalFilePath)
+    const gzip = zlib.createGzip()
+    inputStream.pipe(gzip)
+    // read stream into buffer, using experimental async iterators see https://github.com/nodejs/readable-stream/issues/403#issuecomment-479069043
+    const chunks = []
+    for await (const chunk of gzip) {
+      chunks.push(chunk)
+    }
+    resolve(Buffer.concat(chunks))
+  })
+}

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

@@ -0,0 +1,566 @@
+import * as fs from 'fs'
+import * as core from '@actions/core'
+import * as tmp from 'tmp-promise'
+import * as stream from 'stream'
+import {
+  ArtifactResponse,
+  CreateArtifactParameters,
+  PatchArtifactSize,
+  UploadResults
+} from './contracts'
+import {
+  getArtifactUrl,
+  getContentRange,
+  getUploadHeaders,
+  isRetryableStatusCode,
+  isSuccessStatusCode,
+  isThrottledStatusCode,
+  displayHttpDiagnostics,
+  getExponentialRetryTimeInMilliseconds,
+  tryGetRetryAfterValueTimeInMilliseconds,
+  getProperRetention,
+  sleep
+} from './utils'
+import {
+  getUploadChunkSize,
+  getUploadFileConcurrency,
+  getRetryLimit,
+  getRetentionDays
+} from './config-variables'
+import {promisify} from 'util'
+import {URL} from 'url'
+import {performance} from 'perf_hooks'
+import {StatusReporter} from './status-reporter'
+import {HttpCodes} from '@actions/http-client'
+import {IHttpClientResponse} from '@actions/http-client/interfaces'
+import {HttpManager} from './http-manager'
+import {UploadSpecification} from './upload-specification'
+import {UploadOptions} from './upload-options'
+import {createGZipFileOnDisk, createGZipFileInBuffer} from './upload-gzip'
+import {retryHttpClientRequest} from './requestUtils'
+const stat = promisify(fs.stat)
+
+export class UploadHttpClient {
+  private uploadHttpManager: HttpManager
+  private statusReporter: StatusReporter
+
+  constructor() {
+    this.uploadHttpManager = new HttpManager(
+      getUploadFileConcurrency(),
+      '@actions/artifact-upload'
+    )
+    this.statusReporter = new StatusReporter(10000)
+  }
+
+  /**
+   * Creates a file container for the new artifact in the remote blob storage/file service
+   * @param {string} artifactName Name of the artifact being created
+   * @returns The response from the Artifact Service if the file container was successfully created
+   */
+  async createArtifactInFileContainer(
+    artifactName: string,
+    options?: UploadOptions | undefined
+  ): Promise<ArtifactResponse> {
+    const parameters: CreateArtifactParameters = {
+      Type: 'actions_storage',
+      Name: artifactName
+    }
+
+    // calculate retention period
+    if (options && options.retentionDays) {
+      const maxRetentionStr = getRetentionDays()
+      parameters.RetentionDays = getProperRetention(
+        options.retentionDays,
+        maxRetentionStr
+      )
+    }
+
+    const data: string = JSON.stringify(parameters, null, 2)
+    const artifactUrl = getArtifactUrl()
+
+    // use the first client from the httpManager, `keep-alive` is not used so the connection will close immediately
+    const client = this.uploadHttpManager.getClient(0)
+    const headers = getUploadHeaders('application/json', false)
+
+    // Extra information to display when a particular HTTP code is returned
+    // If a 403 is returned when trying to create a file container, the customer has exceeded
+    // their storage quota so no new artifact containers can be created
+    const customErrorMessages: Map<number, string> = new Map([
+      [
+        HttpCodes.Forbidden,
+        'Artifact storage quota has been hit. Unable to upload any new artifacts'
+      ],
+      [
+        HttpCodes.BadRequest,
+        `The artifact name ${artifactName} is not valid. Request URL ${artifactUrl}`
+      ]
+    ])
+
+    const response = await retryHttpClientRequest(
+      'Create Artifact Container',
+      async () => client.post(artifactUrl, data, headers),
+      customErrorMessages
+    )
+    const body: string = await response.readBody()
+    return JSON.parse(body)
+  }
+
+  /**
+   * Concurrently upload all of the files in chunks
+   * @param {string} uploadUrl Base Url for the artifact that was created
+   * @param {SearchResult[]} filesToUpload A list of information about the files being uploaded
+   * @returns The size of all the files uploaded in bytes
+   */
+  async uploadArtifactToFileContainer(
+    uploadUrl: string,
+    filesToUpload: UploadSpecification[],
+    options?: UploadOptions
+  ): Promise<UploadResults> {
+    const FILE_CONCURRENCY = getUploadFileConcurrency()
+    const MAX_CHUNK_SIZE = getUploadChunkSize()
+    core.debug(
+      `File Concurrency: ${FILE_CONCURRENCY}, and Chunk Size: ${MAX_CHUNK_SIZE}`
+    )
+
+    const parameters: UploadFileParameters[] = []
+    // by default, file uploads will continue if there is an error unless specified differently in the options
+    let continueOnError = true
+    if (options) {
+      if (options.continueOnError === false) {
+        continueOnError = false
+      }
+    }
+
+    // prepare the necessary parameters to upload all the files
+    for (const file of filesToUpload) {
+      const resourceUrl = new URL(uploadUrl)
+      resourceUrl.searchParams.append('itemPath', file.uploadFilePath)
+      parameters.push({
+        file: file.absoluteFilePath,
+        resourceUrl: resourceUrl.toString(),
+        maxChunkSize: MAX_CHUNK_SIZE,
+        continueOnError
+      })
+    }
+
+    const parallelUploads = [...new Array(FILE_CONCURRENCY).keys()]
+    const failedItemsToReport: string[] = []
+    let currentFile = 0
+    let completedFiles = 0
+    let uploadFileSize = 0
+    let totalFileSize = 0
+    let abortPendingFileUploads = false
+
+    this.statusReporter.setTotalNumberOfFilesToProcess(filesToUpload.length)
+    this.statusReporter.start()
+
+    // only allow a certain amount of files to be uploaded at once, this is done to reduce potential errors
+    await Promise.all(
+      parallelUploads.map(async index => {
+        while (currentFile < filesToUpload.length) {
+          const currentFileParameters = parameters[currentFile]
+          currentFile += 1
+          if (abortPendingFileUploads) {
+            failedItemsToReport.push(currentFileParameters.file)
+            continue
+          }
+
+          const startTime = performance.now()
+          const uploadFileResult = await this.uploadFileAsync(
+            index,
+            currentFileParameters
+          )
+
+          if (core.isDebug()) {
+            core.debug(
+              `File: ${++completedFiles}/${filesToUpload.length}. ${
+                currentFileParameters.file
+              } took ${(performance.now() - startTime).toFixed(
+                3
+              )} milliseconds to finish upload`
+            )
+          }
+
+          uploadFileSize += uploadFileResult.successfulUploadSize
+          totalFileSize += uploadFileResult.totalSize
+          if (uploadFileResult.isSuccess === false) {
+            failedItemsToReport.push(currentFileParameters.file)
+            if (!continueOnError) {
+              // fail fast
+              core.error(`aborting artifact upload`)
+              abortPendingFileUploads = true
+            }
+          }
+          this.statusReporter.incrementProcessedCount()
+        }
+      })
+    )
+
+    this.statusReporter.stop()
+    // done uploading, safety dispose all connections
+    this.uploadHttpManager.disposeAndReplaceAllClients()
+
+    core.info(`Total size of all the files uploaded is ${uploadFileSize} bytes`)
+    return {
+      uploadSize: uploadFileSize,
+      totalSize: totalFileSize,
+      failedItems: failedItemsToReport
+    }
+  }
+
+  /**
+   * Asynchronously uploads a file. The file is compressed and uploaded using GZip if it is determined to save space.
+   * If the upload file is bigger than the max chunk size it will be uploaded via multiple calls
+   * @param {number} httpClientIndex The index of the httpClient that is being used to make all of the calls
+   * @param {UploadFileParameters} parameters Information about the file that needs to be uploaded
+   * @returns The size of the file that was uploaded in bytes along with any failed uploads
+   */
+  private async uploadFileAsync(
+    httpClientIndex: number,
+    parameters: UploadFileParameters
+  ): Promise<UploadFileResult> {
+    const fileStat: fs.Stats = await stat(parameters.file)
+    const totalFileSize = fileStat.size
+    // on Windows with mkfifo from MSYS2 stats.isFIFO returns false, so we check if running on Windows node and
+    // if the file has size of 0 to compensate
+    const isFIFO =
+      fileStat.isFIFO() || (process.platform === 'win32' && totalFileSize === 0)
+    let offset = 0
+    let isUploadSuccessful = true
+    let failedChunkSizes = 0
+    let uploadFileSize = 0
+    let isGzip = true
+
+    // the file that is being uploaded is less than 64k in size to increase throughput and to minimize disk I/O
+    // for creating a new GZip file, an in-memory buffer is used for compression
+    // with named pipes the file size is reported as zero in that case don't read the file in memory
+    if (!isFIFO && totalFileSize < 65536) {
+      core.debug(
+        `${parameters.file} is less than 64k in size. Creating a gzip file in-memory to potentially reduce the upload size`
+      )
+      const buffer = await createGZipFileInBuffer(parameters.file)
+
+      // An open stream is needed in the event of a failure and we need to retry. If a NodeJS.ReadableStream is directly passed in,
+      // it will not properly get reset to the start of the stream if a chunk upload needs to be retried
+      let openUploadStream: () => NodeJS.ReadableStream
+
+      if (totalFileSize < buffer.byteLength) {
+        // compression did not help with reducing the size, use a readable stream from the original file for upload
+        core.debug(
+          `The gzip file created for ${parameters.file} did not help with reducing the size of the file. The original file will be uploaded as-is`
+        )
+        openUploadStream = () => fs.createReadStream(parameters.file)
+        isGzip = false
+        uploadFileSize = totalFileSize
+      } else {
+        // create a readable stream using a PassThrough stream that is both readable and writable
+        core.debug(
+          `A gzip file created for ${parameters.file} helped with reducing the size of the original file. The file will be uploaded using gzip.`
+        )
+        openUploadStream = () => {
+          const passThrough = new stream.PassThrough()
+          passThrough.end(buffer)
+          return passThrough
+        }
+        uploadFileSize = buffer.byteLength
+      }
+
+      const result = await this.uploadChunk(
+        httpClientIndex,
+        parameters.resourceUrl,
+        openUploadStream,
+        0,
+        uploadFileSize - 1,
+        uploadFileSize,
+        isGzip,
+        totalFileSize
+      )
+
+      if (!result) {
+        // chunk failed to upload
+        isUploadSuccessful = false
+        failedChunkSizes += uploadFileSize
+        core.warning(`Aborting upload for ${parameters.file} due to failure`)
+      }
+
+      return {
+        isSuccess: isUploadSuccessful,
+        successfulUploadSize: uploadFileSize - failedChunkSizes,
+        totalSize: totalFileSize
+      }
+    } else {
+      // the file that is being uploaded is greater than 64k in size, a temporary file gets created on disk using the
+      // npm tmp-promise package and this file gets used to create a GZipped file
+      const tempFile = await tmp.file()
+      core.debug(
+        `${parameters.file} is greater than 64k in size. Creating a gzip file on-disk ${tempFile.path} to potentially reduce the upload size`
+      )
+
+      // create a GZip file of the original file being uploaded, the original file should not be modified in any way
+      uploadFileSize = await createGZipFileOnDisk(
+        parameters.file,
+        tempFile.path
+      )
+
+      let uploadFilePath = tempFile.path
+
+      // compression did not help with size reduction, use the original file for upload and delete the temp GZip file
+      // for named pipes totalFileSize is zero, this assumes compression did help
+      if (!isFIFO && totalFileSize < uploadFileSize) {
+        core.debug(
+          `The gzip file created for ${parameters.file} did not help with reducing the size of the file. The original file will be uploaded as-is`
+        )
+        uploadFileSize = totalFileSize
+        uploadFilePath = parameters.file
+        isGzip = false
+      } else {
+        core.debug(
+          `The gzip file created for ${parameters.file} is smaller than the original file. The file will be uploaded using gzip.`
+        )
+      }
+
+      let abortFileUpload = false
+      // upload only a single chunk at a time
+      while (offset < uploadFileSize) {
+        const chunkSize = Math.min(
+          uploadFileSize - offset,
+          parameters.maxChunkSize
+        )
+
+        const startChunkIndex = offset
+        const endChunkIndex = offset + chunkSize - 1
+        offset += parameters.maxChunkSize
+
+        if (abortFileUpload) {
+          // if we don't want to continue in the event of an error, any pending upload chunks will be marked as failed
+          failedChunkSizes += chunkSize
+          continue
+        }
+
+        const result = await this.uploadChunk(
+          httpClientIndex,
+          parameters.resourceUrl,
+          () =>
+            fs.createReadStream(uploadFilePath, {
+              start: startChunkIndex,
+              end: endChunkIndex,
+              autoClose: false
+            }),
+          startChunkIndex,
+          endChunkIndex,
+          uploadFileSize,
+          isGzip,
+          totalFileSize
+        )
+
+        if (!result) {
+          // Chunk failed to upload, report as failed and do not continue uploading any more chunks for the file. It is possible that part of a chunk was
+          // successfully uploaded so the server may report a different size for what was uploaded
+          isUploadSuccessful = false
+          failedChunkSizes += chunkSize
+          core.warning(`Aborting upload for ${parameters.file} due to failure`)
+          abortFileUpload = true
+        } else {
+          // if an individual file is greater than 8MB (1024*1024*8) in size, display extra information about the upload status
+          if (uploadFileSize > 8388608) {
+            this.statusReporter.updateLargeFileStatus(
+              parameters.file,
+              startChunkIndex,
+              endChunkIndex,
+              uploadFileSize
+            )
+          }
+        }
+      }
+
+      // Delete the temporary file that was created as part of the upload. If the temp file does not get manually deleted by
+      // calling cleanup, it gets removed when the node process exits. For more info see: https://www.npmjs.com/package/tmp-promise#about
+      core.debug(`deleting temporary gzip file ${tempFile.path}`)
+      await tempFile.cleanup()
+
+      return {
+        isSuccess: isUploadSuccessful,
+        successfulUploadSize: uploadFileSize - failedChunkSizes,
+        totalSize: totalFileSize
+      }
+    }
+  }
+
+  /**
+   * Uploads a chunk of an individual file to the specified resourceUrl. If the upload fails and the status code
+   * indicates a retryable status, we try to upload the chunk as well
+   * @param {number} httpClientIndex The index of the httpClient being used to make all the necessary calls
+   * @param {string} resourceUrl Url of the resource that the chunk will be uploaded to
+   * @param {NodeJS.ReadableStream} openStream Stream of the file that will be uploaded
+   * @param {number} start Starting byte index of file that the chunk belongs to
+   * @param {number} end Ending byte index of file that the chunk belongs to
+   * @param {number} uploadFileSize Total size of the file in bytes that is being uploaded
+   * @param {boolean} isGzip Denotes if we are uploading a Gzip compressed stream
+   * @param {number} totalFileSize Original total size of the file that is being uploaded
+   * @returns if the chunk was successfully uploaded
+   */
+  private async uploadChunk(
+    httpClientIndex: number,
+    resourceUrl: string,
+    openStream: () => NodeJS.ReadableStream,
+    start: number,
+    end: number,
+    uploadFileSize: number,
+    isGzip: boolean,
+    totalFileSize: number
+  ): Promise<boolean> {
+    // prepare all the necessary headers before making any http call
+    const headers = getUploadHeaders(
+      'application/octet-stream',
+      true,
+      isGzip,
+      totalFileSize,
+      end - start + 1,
+      getContentRange(start, end, uploadFileSize)
+    )
+
+    const uploadChunkRequest = async (): Promise<IHttpClientResponse> => {
+      const client = this.uploadHttpManager.getClient(httpClientIndex)
+      return await client.sendStream('PUT', resourceUrl, openStream(), headers)
+    }
+
+    let retryCount = 0
+    const retryLimit = getRetryLimit()
+
+    // Increments the current retry count and then checks if the retry limit has been reached
+    // If there have been too many retries, fail so the download stops
+    const incrementAndCheckRetryLimit = (
+      response?: IHttpClientResponse
+    ): boolean => {
+      retryCount++
+      if (retryCount > retryLimit) {
+        if (response) {
+          displayHttpDiagnostics(response)
+        }
+        core.info(
+          `Retry limit has been reached for chunk at offset ${start} to ${resourceUrl}`
+        )
+        return true
+      }
+      return false
+    }
+
+    const backOff = async (retryAfterValue?: number): Promise<void> => {
+      this.uploadHttpManager.disposeAndReplaceClient(httpClientIndex)
+      if (retryAfterValue) {
+        core.info(
+          `Backoff due to too many requests, retry #${retryCount}. Waiting for ${retryAfterValue} milliseconds before continuing the upload`
+        )
+        await sleep(retryAfterValue)
+      } else {
+        const backoffTime = getExponentialRetryTimeInMilliseconds(retryCount)
+        core.info(
+          `Exponential backoff for retry #${retryCount}. Waiting for ${backoffTime} milliseconds before continuing the upload at offset ${start}`
+        )
+        await sleep(backoffTime)
+      }
+      core.info(
+        `Finished backoff for retry #${retryCount}, continuing with upload`
+      )
+      return
+    }
+
+    // allow for failed chunks to be retried multiple times
+    while (retryCount <= retryLimit) {
+      let response: IHttpClientResponse
+
+      try {
+        response = await uploadChunkRequest()
+      } catch (error) {
+        // if an error is caught, it is usually indicative of a timeout so retry the upload
+        core.info(
+          `An error has been caught http-client index ${httpClientIndex}, retrying the upload`
+        )
+        // eslint-disable-next-line no-console
+        console.log(error)
+
+        if (incrementAndCheckRetryLimit()) {
+          return false
+        }
+        await backOff()
+        continue
+      }
+
+      // Always read the body of the response. There is potential for a resource leak if the body is not read which will
+      // result in the connection remaining open along with unintended consequences when trying to dispose of the client
+      await response.readBody()
+
+      if (isSuccessStatusCode(response.message.statusCode)) {
+        return true
+      } else if (isRetryableStatusCode(response.message.statusCode)) {
+        core.info(
+          `A ${response.message.statusCode} status code has been received, will attempt to retry the upload`
+        )
+        if (incrementAndCheckRetryLimit(response)) {
+          return false
+        }
+        isThrottledStatusCode(response.message.statusCode)
+          ? await backOff(
+              tryGetRetryAfterValueTimeInMilliseconds(response.message.headers)
+            )
+          : await backOff()
+      } else {
+        core.error(
+          `Unexpected response. Unable to upload chunk to ${resourceUrl}`
+        )
+        displayHttpDiagnostics(response)
+        return false
+      }
+    }
+    return false
+  }
+
+  /**
+   * Updates the size of the artifact from -1 which was initially set when the container was first created for the artifact.
+   * Updating the size indicates that we are done uploading all the contents of the artifact
+   */
+  async patchArtifactSize(size: number, artifactName: string): Promise<void> {
+    const resourceUrl = new URL(getArtifactUrl())
+    resourceUrl.searchParams.append('artifactName', artifactName)
+
+    const parameters: PatchArtifactSize = {Size: size}
+    const data: string = JSON.stringify(parameters, null, 2)
+    core.debug(`URL is ${resourceUrl.toString()}`)
+
+    // use the first client from the httpManager, `keep-alive` is not used so the connection will close immediately
+    const client = this.uploadHttpManager.getClient(0)
+    const headers = getUploadHeaders('application/json', false)
+
+    // Extra information to display when a particular HTTP code is returned
+    const customErrorMessages: Map<number, string> = new Map([
+      [
+        HttpCodes.NotFound,
+        `An Artifact with the name ${artifactName} was not found`
+      ]
+    ])
+
+    // TODO retry for all possible response codes, the artifact upload is pretty much complete so it at all costs we should try to finish this
+    const response = await retryHttpClientRequest(
+      'Finalize artifact upload',
+      async () => client.patch(resourceUrl.toString(), data, headers),
+      customErrorMessages
+    )
+    await response.readBody()
+    core.debug(
+      `Artifact ${artifactName} has been successfully uploaded, total size in bytes: ${size}`
+    )
+  }
+}
+
+interface UploadFileParameters {
+  file: string
+  resourceUrl: string
+  maxChunkSize: number
+  continueOnError: boolean
+}
+
+interface UploadFileResult {
+  isSuccess: boolean
+  successfulUploadSize: number
+  totalSize: number
+}

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

@@ -0,0 +1,35 @@
+export interface UploadOptions {
+  /**
+   * Indicates if the artifact upload should continue if file or chunk fails to upload from any error.
+   * If there is a error during upload, a partial artifact will always be associated and available for
+   * download at the end. The size reported will be the amount of storage that the user or org will be
+   * charged for the partial artifact. Defaults to true if not specified
+   *
+   * If set to false, and an error is encountered, all other uploads will stop and any files or chunks
+   * that were queued will not be attempted to be uploaded. The partial artifact available will only
+   * include files and chunks up until the failure
+   *
+   * If set to true and an error is encountered, the failed file will be skipped and ignored and all
+   * other queued files will be attempted to be uploaded. The partial artifact at the end will have all
+   * files with the exception of the problematic files(s)/chunks(s) that failed to upload
+   *
+   */
+  continueOnError?: boolean
+
+  /**
+   * 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-response.ts

@@ -0,0 +1,22 @@
+export interface UploadResponse {
+  /**
+   * The name of the artifact that was uploaded
+   */
+  artifactName: string
+
+  /**
+   * A list of all items that are meant to be uploaded as part of the artifact
+   */
+  artifactItems: string[]
+
+  /**
+   * Total size of the artifact in bytes that was uploaded
+   */
+  size: number
+
+  /**
+   * A list of items that were not uploaded as part of the artifact (includes queued items that were not uploaded if
+   * continueOnError is set to false). This is a subset of artifactItems.
+   */
+  failedItems: string[]
+}

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

@@ -0,0 +1,94 @@
+import * as fs from 'fs'
+import {debug} from '@actions/core'
+import {join, normalize, resolve} from 'path'
+import {checkArtifactFilePath} from './path-and-artifact-name-validation'
+
+export interface UploadSpecification {
+  absoluteFilePath: string
+  uploadFilePath: string
+}
+
+/**
+ * Creates a specification that describes how each file that is part of the artifact will be uploaded
+ * @param artifactName the name of the artifact being uploaded. Used during upload to denote where the artifact is stored on the server
+ * @param rootDirectory an absolute file path that denotes the path that should be removed from the beginning of each artifact file
+ * @param artifactFiles a list of absolute file paths that denote what should be uploaded as part of the artifact
+ */
+export function getUploadSpecification(
+  artifactName: string,
+  rootDirectory: string,
+  artifactFiles: string[]
+): UploadSpecification[] {
+  // artifact name was checked earlier on, no need to check again
+  const specifications: UploadSpecification[] = []
+
+  if (!fs.existsSync(rootDirectory)) {
+    throw new Error(`Provided rootDirectory ${rootDirectory} does not exist`)
+  }
+  if (!fs.lstatSync(rootDirectory).isDirectory()) {
+    throw new Error(
+      `Provided rootDirectory ${rootDirectory} is not a valid directory`
+    )
+  }
+  // Normalize and resolve, this allows for either absolute or relative paths to be used
+  rootDirectory = normalize(rootDirectory)
+  rootDirectory = resolve(rootDirectory)
+
+  /*
+     Example to demonstrate behavior
+     
+     Input:
+       artifactName: my-artifact
+       rootDirectory: '/home/user/files/plz-upload'
+       artifactFiles: [
+         '/home/user/files/plz-upload/file1.txt',
+         '/home/user/files/plz-upload/file2.txt',
+         '/home/user/files/plz-upload/dir/file3.txt'
+       ]
+     
+     Output:
+       specifications: [
+         ['/home/user/files/plz-upload/file1.txt', 'my-artifact/file1.txt'],
+         ['/home/user/files/plz-upload/file1.txt', 'my-artifact/file2.txt'],
+         ['/home/user/files/plz-upload/file1.txt', 'my-artifact/dir/file3.txt']
+       ]
+  */
+  for (let file of artifactFiles) {
+    if (!fs.existsSync(file)) {
+      throw new Error(`File ${file} does not exist`)
+    }
+    if (!fs.lstatSync(file).isDirectory()) {
+      // Normalize and resolve, this allows for either absolute or relative paths to be used
+      file = normalize(file)
+      file = resolve(file)
+      if (!file.startsWith(rootDirectory)) {
+        throw new Error(
+          `The rootDirectory: ${rootDirectory} is not a parent directory of the file: ${file}`
+        )
+      }
+
+      // Check for forbidden characters in file paths that will be rejected during upload
+      const uploadPath = file.replace(rootDirectory, '')
+      checkArtifactFilePath(uploadPath)
+
+      /*
+        uploadFilePath denotes where the file will be uploaded in the file container on the server. During a run, if multiple artifacts are uploaded, they will all
+        be saved in the same container. The artifact name is used as the root directory in the container to separate and distinguish uploaded artifacts
+
+        path.join handles all the following cases and would return 'artifact-name/file-to-upload.txt
+          join('artifact-name/', 'file-to-upload.txt')
+          join('artifact-name/', '/file-to-upload.txt')
+          join('artifact-name', 'file-to-upload.txt')
+          join('artifact-name', '/file-to-upload.txt')
+      */
+      specifications.push({
+        absoluteFilePath: file,
+        uploadFilePath: join(artifactName, uploadPath)
+      })
+    } else {
+      // Directories are rejected by the server during upload
+      debug(`Removing ${file} from rawSearchResults because it is a directory`)
+    }
+  }
+  return specifications
+}

packages/artifact/src/internal/utils.ts

@@ -0,0 +1,293 @@
+import {debug, info, warning} from '@actions/core'
+import {promises as fs} from 'fs'
+import {HttpCodes, HttpClient} from '@actions/http-client'
+import {BearerCredentialHandler} from '@actions/http-client/auth'
+import {IHeaders, IHttpClientResponse} from '@actions/http-client/interfaces'
+import {IncomingHttpHeaders} from 'http'
+import {
+  getRuntimeToken,
+  getRuntimeUrl,
+  getWorkFlowRunId,
+  getRetryMultiplier,
+  getInitialRetryIntervalInMilliseconds
+} from './config-variables'
+
+/**
+ * Returns a retry time in milliseconds that exponentially gets larger
+ * depending on the amount of retries that have been attempted
+ */
+export function getExponentialRetryTimeInMilliseconds(
+  retryCount: number
+): number {
+  if (retryCount < 0) {
+    throw new Error('RetryCount should not be negative')
+  } else if (retryCount === 0) {
+    return getInitialRetryIntervalInMilliseconds()
+  }
+
+  const minTime =
+    getInitialRetryIntervalInMilliseconds() * getRetryMultiplier() * retryCount
+  const maxTime = minTime * getRetryMultiplier()
+
+  // returns a random number between the minTime (inclusive) and the maxTime (exclusive)
+  return Math.trunc(Math.random() * (maxTime - minTime) + minTime)
+}
+
+/**
+ * Parses a env variable that is a number
+ */
+export function parseEnvNumber(key: string): number | undefined {
+  const value = Number(process.env[key])
+  if (Number.isNaN(value) || value < 0) {
+    return undefined
+  }
+  return value
+}
+
+/**
+ * Various utility functions to help with the necessary API calls
+ */
+export function getApiVersion(): string {
+  return '6.0-preview'
+}
+
+export function isSuccessStatusCode(statusCode?: number): boolean {
+  if (!statusCode) {
+    return false
+  }
+  return statusCode >= 200 && statusCode < 300
+}
+
+export function isForbiddenStatusCode(statusCode?: number): boolean {
+  if (!statusCode) {
+    return false
+  }
+  return statusCode === HttpCodes.Forbidden
+}
+
+export function isRetryableStatusCode(statusCode: number | undefined): boolean {
+  if (!statusCode) {
+    return false
+  }
+
+  const retryableStatusCodes = [
+    HttpCodes.BadGateway,
+    HttpCodes.GatewayTimeout,
+    HttpCodes.InternalServerError,
+    HttpCodes.ServiceUnavailable,
+    HttpCodes.TooManyRequests,
+    413 // Payload Too Large
+  ]
+  return retryableStatusCodes.includes(statusCode)
+}
+
+export function isThrottledStatusCode(statusCode?: number): boolean {
+  if (!statusCode) {
+    return false
+  }
+  return statusCode === HttpCodes.TooManyRequests
+}
+
+/**
+ * Attempts to get the retry-after value from a set of http headers. The retry time
+ * is originally denoted in seconds, so if present, it is converted to milliseconds
+ * @param headers all the headers received when making an http call
+ */
+export function tryGetRetryAfterValueTimeInMilliseconds(
+  headers: IncomingHttpHeaders
+): number | undefined {
+  if (headers['retry-after']) {
+    const retryTime = Number(headers['retry-after'])
+    if (!isNaN(retryTime)) {
+      info(`Retry-After header is present with a value of ${retryTime}`)
+      return retryTime * 1000
+    }
+    info(
+      `Returned retry-after header value: ${retryTime} is non-numeric and cannot be used`
+    )
+    return undefined
+  }
+  info(
+    `No retry-after header was found. Dumping all headers for diagnostic purposes`
+  )
+  // eslint-disable-next-line no-console
+  console.log(headers)
+  return undefined
+}
+
+export function getContentRange(
+  start: number,
+  end: number,
+  total: number
+): string {
+  // Format: `bytes start-end/fileSize
+  // start and end are inclusive
+  // For a 200 byte chunk starting at byte 0:
+  // Content-Range: bytes 0-199/200
+  return `bytes ${start}-${end}/${total}`
+}
+
+/**
+ * Sets all the necessary headers when downloading an artifact
+ * @param {string} contentType the type of content being uploaded
+ * @param {boolean} isKeepAlive is the same connection being used to make multiple calls
+ * @param {boolean} acceptGzip can we accept a gzip encoded response
+ * @param {string} acceptType the type of content that we can accept
+ * @returns appropriate headers to make a specific http call during artifact download
+ */
+export function getDownloadHeaders(
+  contentType: string,
+  isKeepAlive?: boolean,
+  acceptGzip?: boolean
+): IHeaders {
+  const requestOptions: IHeaders = {}
+
+  if (contentType) {
+    requestOptions['Content-Type'] = contentType
+  }
+  if (isKeepAlive) {
+    requestOptions['Connection'] = 'Keep-Alive'
+    // keep alive for at least 10 seconds before closing the connection
+    requestOptions['Keep-Alive'] = '10'
+  }
+  if (acceptGzip) {
+    // if we are expecting a response with gzip encoding, it should be using an octet-stream in the accept header
+    requestOptions['Accept-Encoding'] = 'gzip'
+    requestOptions[
+      'Accept'
+    ] = `application/octet-stream;api-version=${getApiVersion()}`
+  } else {
+    // default to application/json if we are not working with gzip content
+    requestOptions['Accept'] = `application/json;api-version=${getApiVersion()}`
+  }
+
+  return requestOptions
+}
+
+/**
+ * Sets all the necessary headers when uploading an artifact
+ * @param {string} contentType the type of content being uploaded
+ * @param {boolean} isKeepAlive is the same connection being used to make multiple calls
+ * @param {boolean} isGzip is the connection being used to upload GZip compressed content
+ * @param {number} uncompressedLength the original size of the content if something is being uploaded that has been compressed
+ * @param {number} contentLength the length of the content that is being uploaded
+ * @param {string} contentRange the range of the content that is being uploaded
+ * @returns appropriate headers to make a specific http call during artifact upload
+ */
+export function getUploadHeaders(
+  contentType: string,
+  isKeepAlive?: boolean,
+  isGzip?: boolean,
+  uncompressedLength?: number,
+  contentLength?: number,
+  contentRange?: string
+): IHeaders {
+  const requestOptions: IHeaders = {}
+  requestOptions['Accept'] = `application/json;api-version=${getApiVersion()}`
+  if (contentType) {
+    requestOptions['Content-Type'] = contentType
+  }
+  if (isKeepAlive) {
+    requestOptions['Connection'] = 'Keep-Alive'
+    // keep alive for at least 10 seconds before closing the connection
+    requestOptions['Keep-Alive'] = '10'
+  }
+  if (isGzip) {
+    requestOptions['Content-Encoding'] = 'gzip'
+    requestOptions['x-tfs-filelength'] = uncompressedLength
+  }
+  if (contentLength) {
+    requestOptions['Content-Length'] = contentLength
+  }
+  if (contentRange) {
+    requestOptions['Content-Range'] = contentRange
+  }
+
+  return requestOptions
+}
+
+export function createHttpClient(userAgent: string): HttpClient {
+  return new HttpClient(userAgent, [
+    new BearerCredentialHandler(getRuntimeToken())
+  ])
+}
+
+export function getArtifactUrl(): string {
+  const artifactUrl = `${getRuntimeUrl()}_apis/pipelines/workflows/${getWorkFlowRunId()}/artifacts?api-version=${getApiVersion()}`
+  debug(`Artifact Url: ${artifactUrl}`)
+  return artifactUrl
+}
+
+/**
+ * Uh oh! Something might have gone wrong during either upload or download. The IHtttpClientResponse object contains information
+ * about the http call that was made by the actions http client. This information might be useful to display for diagnostic purposes, but
+ * this entire object is really big and most of the information is not really useful. This function takes the response object and displays only
+ * the information that we want.
+ *
+ * Certain information such as the TLSSocket and the Readable state are not really useful for diagnostic purposes so they can be avoided.
+ * Other information such as the headers, the response code and message might be useful, so this is displayed.
+ */
+export function displayHttpDiagnostics(response: IHttpClientResponse): void {
+  info(
+    `##### Begin Diagnostic HTTP information #####
+Status Code: ${response.message.statusCode}
+Status Message: ${response.message.statusMessage}
+Header Information: ${JSON.stringify(response.message.headers, undefined, 2)}
+###### End Diagnostic HTTP information ######`
+  )
+}
+
+export async function createDirectoriesForArtifact(
+  directories: string[]
+): Promise<void> {
+  for (const directory of directories) {
+    await fs.mkdir(directory, {
+      recursive: true
+    })
+  }
+}
+
+export async function createEmptyFilesForArtifact(
+  emptyFilesToCreate: string[]
+): Promise<void> {
+  for (const filePath of emptyFilesToCreate) {
+    await (await fs.open(filePath, 'w')).close()
+  }
+}
+
+export async function getFileSize(filePath: string): Promise<number> {
+  const stats = await fs.stat(filePath)
+  debug(
+    `${filePath} size:(${stats.size}) blksize:(${stats.blksize}) blocks:(${stats.blocks})`
+  )
+  return stats.size
+}
+
+export async function rmFile(filePath: string): Promise<void> {
+  await fs.unlink(filePath)
+}
+
+export function getProperRetention(
+  retentionInput: number,
+  retentionSetting: string | undefined
+): number {
+  if (retentionInput < 0) {
+    throw new Error('Invalid retention, minimum value is 1.')
+  }
+
+  let retention = retentionInput
+  if (retentionSetting) {
+    const maxRetention = parseInt(retentionSetting)
+    if (!isNaN(maxRetention) && maxRetention < retention) {
+      warning(
+        `Retention days is greater than the max value allowed by the repository setting, reduce retention to ${maxRetention} days`
+      )
+      retention = maxRetention
+    }
+  }
+  return retention
+}
+
+export async function sleep(milliseconds: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, milliseconds))
+}

packages/artifact/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": "./",
+    "outDir": "./lib",
+    "rootDir": "./src"
+  },
+  "include": [
+    "./src"
+  ]
+}

packages/cache/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright 2019 GitHub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/cache/README.md

@@ -0,0 +1,44 @@
+# `@actions/cache`
+
+> Functions necessary for caching dependencies and build outputs to improve workflow execution time.
+
+See ["Caching dependencies to speed up workflows"](https://help.github.com/github/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows) for how caching works.
+
+Note that GitHub will remove any cache entries that have not been accessed in over 7 days. There is no limit on the number of caches you can store, but the total size of all caches in a repository is limited to 10 GB. If you exceed this limit, GitHub will save your cache but will begin evicting caches until the total size is less than 10 GB.
+
+## Usage
+
+This package is used by the v2+ versions of our first party cache action. You can find an example implementation in the cache repo [here](https://github.com/actions/cache). 
+
+#### Save Cache
+
+Saves a cache containing the files in `paths` using the `key` provided. The files would be compressed using zstandard compression algorithm if zstd is installed, otherwise gzip is used. Function returns the cache id if the cache was saved succesfully and throws an error if cache upload fails. 
+
+```js
+const cache = require('@actions/cache');
+const paths = [
+    'node_modules',
+    'packages/*/node_modules/'
+]
+const key = 'npm-foobar-d5ea0750'
+const cacheId = await cache.saveCache(paths, key)
+```
+
+#### Restore Cache
+
+Restores a cache based on `key` and `restoreKeys` to the `paths` provided. Function returns the cache key for cache hit and returns undefined if cache not found. 
+
+```js
+const cache = require('@actions/cache');
+const paths = [
+    'node_modules',
+    'packages/*/node_modules/'
+]
+const key = 'npm-foobar-d5ea0750'
+const restoreKeys = [
+    'npm-foobar-',
+    'npm-'
+]
+const cacheKey = await cache.restoreCache(paths, key, restoreKeys)
+```
+

packages/cache/RELEASES.md

@@ -0,0 +1,45 @@
+# @actions/cache Releases
+
+### 0.1.0
+
+- Initial release
+
+### 0.2.0
+- Fixes issues with the zstd compression algorithm on Windows and Ubuntu 16.04 [#469](https://github.com/actions/toolkit/pull/469)
+
+### 0.2.1
+- Fix to await async function getCompressionMethod
+
+### 1.0.0
+- Downloads Azure-hosted caches using the Azure SDK for speed and reliability
+- Displays download progress
+- Includes changes that break compatibility with earlier versions, including:
+  - `retry`, `retryTypedResponse`, and `retryHttpClientResponse` moved from `cacheHttpClient` to `requestUtils`
+
+### 1.0.1
+- Fix bug in downloading large files (> 2 GBs) with the Azure SDK
+
+### 1.0.2
+- Use posix archive format to add support for some tools
+
+### 1.0.3
+- Use http-client v1.0.9
+- Fixes error handling so retries are not attempted on non-retryable errors (409 Conflict, for example)
+- Adds 5 second delay between retry attempts
+
+### 1.0.4
+- Use @actions/core v1.2.6
+- Fixes uploadChunk to throw an error if any unsuccessful response code is received
+
+### 1.0.5
+- Fix to ensure Windows cache paths get resolved correctly
+
+### 1.0.6
+- Make caching more verbose [#650](https://github.com/actions/toolkit/pull/650)
+- Use GNU tar on macOS if available [#701](https://github.com/actions/toolkit/pull/701)
+
+### 1.0.7
+- Fixes permissions issue extracting archives with GNU tar on macOS ([issue](https://github.com/actions/cache/issues/527))
+
+### 1.0.8
+- Increase the allowed artifact cache size from 5GB to 10GB ([issue](https://github.com/actions/cache/discussions/497))

packages/cache/__tests__/__fixtures__/action.yml

@@ -0,0 +1,5 @@
+name: 'Set env variables'
+description: 'Sets certain env variables so that e2e restore and save cache can be tested in a shell'
+runs:
+  using: 'node12'
+  main: 'index.js'

packages/cache/__tests__/__fixtures__/helloWorld.txt

@@ -0,0 +1 @@
+hello world

packages/cache/__tests__/__fixtures__/index.js

@@ -0,0 +1,14 @@
+// Certain env variables are not set by default in a shell context and are only available in a node context from a running action
+// In order to be able to restore and save cache e2e in a shell when running CI tests, we need these env variables set
+const fs = require('fs');
+const os = require('os');
+const filePath = process.env[`GITHUB_ENV`]
+fs.appendFileSync(filePath, `ACTIONS_RUNTIME_URL=${process.env.ACTIONS_RUNTIME_URL}${os.EOL}`, {
+    encoding: 'utf8'
+})
+fs.appendFileSync(filePath, `ACTIONS_RUNTIME_TOKEN=${process.env.ACTIONS_RUNTIME_TOKEN}${os.EOL}`, {
+    encoding: 'utf8'
+})
+fs.appendFileSync(filePath, `GITHUB_RUN_ID=${process.env.GITHUB_RUN_ID}${os.EOL}`, {
+    encoding: 'utf8'
+})

packages/cache/__tests__/cacheHttpClient.test.ts

@@ -0,0 +1,141 @@
+import {downloadCache, getCacheVersion} from '../src/internal/cacheHttpClient'
+import {CompressionMethod} from '../src/internal/constants'
+import * as downloadUtils from '../src/internal/downloadUtils'
+import {DownloadOptions, getDownloadOptions} from '../src/options'
+
+jest.mock('../src/internal/downloadUtils')
+
+test('getCacheVersion with one path returns version', async () => {
+  const paths = ['node_modules']
+  const result = getCacheVersion(paths)
+  expect(result).toEqual(
+    'b3e0c6cb5ecf32614eeb2997d905b9c297046d7cbf69062698f25b14b4cb0985'
+  )
+})
+
+test('getCacheVersion with multiple paths returns version', async () => {
+  const paths = ['node_modules', 'dist']
+  const result = getCacheVersion(paths)
+  expect(result).toEqual(
+    '165c3053bc646bf0d4fac17b1f5731caca6fe38e0e464715c0c3c6b6318bf436'
+  )
+})
+
+test('getCacheVersion with zstd compression returns version', async () => {
+  const paths = ['node_modules']
+  const result = getCacheVersion(paths, CompressionMethod.Zstd)
+
+  expect(result).toEqual(
+    '273877e14fd65d270b87a198edbfa2db5a43de567c9a548d2a2505b408befe24'
+  )
+})
+
+test('getCacheVersion with gzip compression does not change vesion', async () => {
+  const paths = ['node_modules']
+  const result = getCacheVersion(paths, CompressionMethod.Gzip)
+
+  expect(result).toEqual(
+    'b3e0c6cb5ecf32614eeb2997d905b9c297046d7cbf69062698f25b14b4cb0985'
+  )
+})
+
+test('downloadCache uses http-client for non-Azure URLs', async () => {
+  const downloadCacheHttpClientMock = jest.spyOn(
+    downloadUtils,
+    'downloadCacheHttpClient'
+  )
+  const downloadCacheStorageSDKMock = jest.spyOn(
+    downloadUtils,
+    'downloadCacheStorageSDK'
+  )
+
+  const archiveLocation = 'http://www.actionscache.test/download'
+  const archivePath = '/foo/bar'
+
+  await downloadCache(archiveLocation, archivePath)
+
+  expect(downloadCacheHttpClientMock).toHaveBeenCalledTimes(1)
+  expect(downloadCacheHttpClientMock).toHaveBeenCalledWith(
+    archiveLocation,
+    archivePath
+  )
+
+  expect(downloadCacheStorageSDKMock).toHaveBeenCalledTimes(0)
+})
+
+test('downloadCache uses storage SDK for Azure storage URLs', async () => {
+  const downloadCacheHttpClientMock = jest.spyOn(
+    downloadUtils,
+    'downloadCacheHttpClient'
+  )
+  const downloadCacheStorageSDKMock = jest.spyOn(
+    downloadUtils,
+    'downloadCacheStorageSDK'
+  )
+
+  const archiveLocation = 'http://foo.blob.core.windows.net/bar/baz'
+  const archivePath = '/foo/bar'
+
+  await downloadCache(archiveLocation, archivePath)
+
+  expect(downloadCacheStorageSDKMock).toHaveBeenCalledTimes(1)
+  expect(downloadCacheStorageSDKMock).toHaveBeenCalledWith(
+    archiveLocation,
+    archivePath,
+    getDownloadOptions()
+  )
+
+  expect(downloadCacheHttpClientMock).toHaveBeenCalledTimes(0)
+})
+
+test('downloadCache passes options to download methods', async () => {
+  const downloadCacheHttpClientMock = jest.spyOn(
+    downloadUtils,
+    'downloadCacheHttpClient'
+  )
+  const downloadCacheStorageSDKMock = jest.spyOn(
+    downloadUtils,
+    'downloadCacheStorageSDK'
+  )
+
+  const archiveLocation = 'http://foo.blob.core.windows.net/bar/baz'
+  const archivePath = '/foo/bar'
+  const options: DownloadOptions = {downloadConcurrency: 4}
+
+  await downloadCache(archiveLocation, archivePath, options)
+
+  expect(downloadCacheStorageSDKMock).toHaveBeenCalledTimes(1)
+  expect(downloadCacheStorageSDKMock).toHaveBeenCalled()
+  expect(downloadCacheStorageSDKMock).toHaveBeenCalledWith(
+    archiveLocation,
+    archivePath,
+    getDownloadOptions(options)
+  )
+
+  expect(downloadCacheHttpClientMock).toHaveBeenCalledTimes(0)
+})
+
+test('downloadCache uses http-client when overridden', async () => {
+  const downloadCacheHttpClientMock = jest.spyOn(
+    downloadUtils,
+    'downloadCacheHttpClient'
+  )
+  const downloadCacheStorageSDKMock = jest.spyOn(
+    downloadUtils,
+    'downloadCacheStorageSDK'
+  )
+
+  const archiveLocation = 'http://foo.blob.core.windows.net/bar/baz'
+  const archivePath = '/foo/bar'
+  const options: DownloadOptions = {useAzureSdk: false}
+
+  await downloadCache(archiveLocation, archivePath, options)
+
+  expect(downloadCacheHttpClientMock).toHaveBeenCalledTimes(1)
+  expect(downloadCacheHttpClientMock).toHaveBeenCalledWith(
+    archiveLocation,
+    archivePath
+  )
+
+  expect(downloadCacheStorageSDKMock).toHaveBeenCalledTimes(0)
+})

packages/cache/__tests__/cacheUtils.test.ts

@@ -0,0 +1,34 @@
+import {promises as fs} from 'fs'
+import * as path from 'path'
+import * as cacheUtils from '../src/internal/cacheUtils'
+
+test('getArchiveFileSizeInBytes returns file size', () => {
+  const filePath = path.join(__dirname, '__fixtures__', 'helloWorld.txt')
+
+  const size = cacheUtils.getArchiveFileSizeInBytes(filePath)
+
+  expect(size).toBe(11)
+})
+
+test('unlinkFile unlinks file', async () => {
+  const testDirectory = await fs.mkdtemp('unlinkFileTest')
+  const testFile = path.join(testDirectory, 'test.txt')
+  await fs.writeFile(testFile, 'hello world')
+
+  await expect(fs.stat(testFile)).resolves.not.toThrow()
+
+  await cacheUtils.unlinkFile(testFile)
+
+  // This should throw as testFile should not exist
+  await expect(fs.stat(testFile)).rejects.toThrow()
+
+  await fs.rmdir(testDirectory)
+})
+
+test('assertDefined throws if undefined', () => {
+  expect(() => cacheUtils.assertDefined('test', undefined)).toThrowError()
+})
+
+test('assertDefined returns value', () => {
+  expect(cacheUtils.assertDefined('test', 5)).toBe(5)
+})

packages/cache/__tests__/create-cache-files.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+
+# Validate args
+prefix="$1"
+if [ -z "$prefix" ]; then
+  echo "Must supply prefix argument"
+  exit 1
+fi
+
+path="$2"
+if [ -z "$path" ]; then
+  echo "Must supply path argument"
+  exit 1
+fi
+
+mkdir -p $path
+echo "$prefix $GITHUB_RUN_ID" > $path/test-file.txt

packages/cache/__tests__/downloadUtils.test.ts

@@ -0,0 +1,160 @@
+import * as core from '@actions/core'
+import {DownloadProgress} from '../src/internal/downloadUtils'
+
+test('download progress tracked correctly', () => {
+  const progress = new DownloadProgress(1000)
+
+  expect(progress.contentLength).toBe(1000)
+  expect(progress.receivedBytes).toBe(0)
+  expect(progress.segmentIndex).toBe(0)
+  expect(progress.segmentOffset).toBe(0)
+  expect(progress.segmentSize).toBe(0)
+  expect(progress.displayedComplete).toBe(false)
+  expect(progress.timeoutHandle).toBeUndefined()
+  expect(progress.getTransferredBytes()).toBe(0)
+  expect(progress.isDone()).toBe(false)
+
+  progress.nextSegment(500)
+
+  expect(progress.contentLength).toBe(1000)
+  expect(progress.receivedBytes).toBe(0)
+  expect(progress.segmentIndex).toBe(1)
+  expect(progress.segmentOffset).toBe(0)
+  expect(progress.segmentSize).toBe(500)
+  expect(progress.displayedComplete).toBe(false)
+  expect(progress.timeoutHandle).toBeUndefined()
+  expect(progress.getTransferredBytes()).toBe(0)
+  expect(progress.isDone()).toBe(false)
+
+  progress.setReceivedBytes(250)
+
+  expect(progress.contentLength).toBe(1000)
+  expect(progress.receivedBytes).toBe(250)
+  expect(progress.segmentIndex).toBe(1)
+  expect(progress.segmentOffset).toBe(0)
+  expect(progress.segmentSize).toBe(500)
+  expect(progress.displayedComplete).toBe(false)
+  expect(progress.timeoutHandle).toBeUndefined()
+  expect(progress.getTransferredBytes()).toBe(250)
+  expect(progress.isDone()).toBe(false)
+
+  progress.setReceivedBytes(500)
+
+  expect(progress.contentLength).toBe(1000)
+  expect(progress.receivedBytes).toBe(500)
+  expect(progress.segmentIndex).toBe(1)
+  expect(progress.segmentOffset).toBe(0)
+  expect(progress.segmentSize).toBe(500)
+  expect(progress.displayedComplete).toBe(false)
+  expect(progress.timeoutHandle).toBeUndefined()
+  expect(progress.getTransferredBytes()).toBe(500)
+  expect(progress.isDone()).toBe(false)
+
+  progress.nextSegment(500)
+
+  expect(progress.contentLength).toBe(1000)
+  expect(progress.receivedBytes).toBe(0)
+  expect(progress.segmentIndex).toBe(2)
+  expect(progress.segmentOffset).toBe(500)
+  expect(progress.segmentSize).toBe(500)
+  expect(progress.displayedComplete).toBe(false)
+  expect(progress.timeoutHandle).toBeUndefined()
+  expect(progress.getTransferredBytes()).toBe(500)
+  expect(progress.isDone()).toBe(false)
+
+  progress.setReceivedBytes(250)
+
+  expect(progress.contentLength).toBe(1000)
+  expect(progress.receivedBytes).toBe(250)
+  expect(progress.segmentIndex).toBe(2)
+  expect(progress.segmentOffset).toBe(500)
+  expect(progress.segmentSize).toBe(500)
+  expect(progress.displayedComplete).toBe(false)
+  expect(progress.timeoutHandle).toBeUndefined()
+  expect(progress.getTransferredBytes()).toBe(750)
+  expect(progress.isDone()).toBe(false)
+
+  progress.setReceivedBytes(500)
+
+  expect(progress.contentLength).toBe(1000)
+  expect(progress.receivedBytes).toBe(500)
+  expect(progress.segmentIndex).toBe(2)
+  expect(progress.segmentOffset).toBe(500)
+  expect(progress.segmentSize).toBe(500)
+  expect(progress.displayedComplete).toBe(false)
+  expect(progress.timeoutHandle).toBeUndefined()
+  expect(progress.getTransferredBytes()).toBe(1000)
+  expect(progress.isDone()).toBe(true)
+})
+
+test('display timer works correctly', done => {
+  const progress = new DownloadProgress(1000)
+
+  const infoMock = jest.spyOn(core, 'info')
+  infoMock.mockImplementation(() => {})
+
+  const check = (): void => {
+    expect(infoMock).toHaveBeenLastCalledWith(
+      expect.stringContaining('Received 500 of 1000')
+    )
+  }
+
+  // Validate no further updates are displayed after stopping the timer.
+  const test2 = (): void => {
+    check()
+    expect(progress.timeoutHandle).toBeUndefined()
+    done()
+  }
+
+  // Validate the progress is displayed, stop the timer, and call test2.
+  const test1 = (): void => {
+    check()
+
+    progress.stopDisplayTimer()
+    progress.setReceivedBytes(1000)
+
+    setTimeout(() => test2(), 500)
+  }
+
+  // Start the timer, update the received bytes, and call test1.
+  const start = (): void => {
+    progress.startDisplayTimer(10)
+    expect(progress.timeoutHandle).toBeDefined()
+
+    progress.setReceivedBytes(500)
+
+    setTimeout(() => test1(), 500)
+  }
+
+  start()
+})
+
+test('display does not print completed line twice', () => {
+  const progress = new DownloadProgress(1000)
+
+  const infoMock = jest.spyOn(core, 'info')
+  infoMock.mockImplementation(() => {})
+
+  progress.display()
+
+  expect(progress.displayedComplete).toBe(false)
+  expect(infoMock).toHaveBeenCalledTimes(1)
+
+  progress.nextSegment(1000)
+  progress.setReceivedBytes(500)
+  progress.display()
+
+  expect(progress.displayedComplete).toBe(false)
+  expect(infoMock).toHaveBeenCalledTimes(2)
+
+  progress.setReceivedBytes(1000)
+  progress.display()
+
+  expect(progress.displayedComplete).toBe(true)
+  expect(infoMock).toHaveBeenCalledTimes(3)
+
+  progress.display()
+
+  expect(progress.displayedComplete).toBe(true)
+  expect(infoMock).toHaveBeenCalledTimes(3)
+})

packages/cache/__tests__/options.test.ts

@@ -0,0 +1,54 @@
+import {
+  DownloadOptions,
+  UploadOptions,
+  getDownloadOptions,
+  getUploadOptions
+} from '../src/options'
+
+const useAzureSdk = true
+const downloadConcurrency = 8
+const timeoutInMs = 30000
+const uploadConcurrency = 4
+const uploadChunkSize = 32 * 1024 * 1024
+
+test('getDownloadOptions sets defaults', async () => {
+  const actualOptions = getDownloadOptions()
+
+  expect(actualOptions).toEqual({
+    useAzureSdk,
+    downloadConcurrency,
+    timeoutInMs
+  })
+})
+
+test('getDownloadOptions overrides all settings', async () => {
+  const expectedOptions: DownloadOptions = {
+    useAzureSdk: false,
+    downloadConcurrency: 14,
+    timeoutInMs: 20000
+  }
+
+  const actualOptions = getDownloadOptions(expectedOptions)
+
+  expect(actualOptions).toEqual(expectedOptions)
+})
+
+test('getUploadOptions sets defaults', async () => {
+  const actualOptions = getUploadOptions()
+
+  expect(actualOptions).toEqual({
+    uploadConcurrency,
+    uploadChunkSize
+  })
+})
+
+test('getUploadOptions overrides all settings', async () => {
+  const expectedOptions: UploadOptions = {
+    uploadConcurrency: 2,
+    uploadChunkSize: 16 * 1024 * 1024
+  }
+
+  const actualOptions = getUploadOptions(expectedOptions)
+
+  expect(actualOptions).toEqual(expectedOptions)
+})

packages/cache/__tests__/requestUtils.test.ts

@@ -0,0 +1,147 @@
+import {retry} from '../src/internal/requestUtils'
+import {HttpClientError} from '@actions/http-client'
+
+interface ITestResponse {
+  statusCode: number
+  result: string | null
+  error: Error | null
+}
+
+function TestResponse(
+  action: number | Error,
+  result: string | null = null
+): ITestResponse {
+  if (action instanceof Error) {
+    return {
+      statusCode: -1,
+      result,
+      error: action
+    }
+  } else {
+    return {
+      statusCode: action,
+      result,
+      error: null
+    }
+  }
+}
+
+async function handleResponse(
+  response: ITestResponse | undefined
+): Promise<ITestResponse> {
+  if (!response) {
+    fail('Retry method called too many times')
+  }
+
+  if (response.error) {
+    throw response.error
+  } else {
+    return Promise.resolve(response)
+  }
+}
+
+async function testRetryExpectingResult(
+  responses: ITestResponse[],
+  expectedResult: string | null
+): Promise<void> {
+  responses = responses.reverse() // Reverse responses since we pop from end
+
+  const actualResult = await retry(
+    'test',
+    async () => handleResponse(responses.pop()),
+    (response: ITestResponse) => response.statusCode,
+    2, // maxAttempts
+    0 // delay
+  )
+
+  expect(actualResult.result).toEqual(expectedResult)
+}
+
+async function testRetryConvertingErrorToResult(
+  responses: ITestResponse[],
+  expectedStatus: number,
+  expectedResult: string | null
+): Promise<void> {
+  responses = responses.reverse() // Reverse responses since we pop from end
+
+  const actualResult = await retry(
+    'test',
+    async () => handleResponse(responses.pop()),
+    (response: ITestResponse) => response.statusCode,
+    2, // maxAttempts
+    0, // delay
+    (e: Error) => {
+      if (e instanceof HttpClientError) {
+        return {
+          statusCode: e.statusCode,
+          result: null,
+          error: null
+        }
+      }
+    }
+  )
+
+  expect(actualResult.statusCode).toEqual(expectedStatus)
+  expect(actualResult.result).toEqual(expectedResult)
+}
+
+async function testRetryExpectingError(
+  responses: ITestResponse[]
+): Promise<void> {
+  responses = responses.reverse() // Reverse responses since we pop from end
+
+  expect(
+    retry(
+      'test',
+      async () => handleResponse(responses.pop()),
+      (response: ITestResponse) => response.statusCode,
+      2, // maxAttempts,
+      0 // delay
+    )
+  ).rejects.toBeInstanceOf(Error)
+}
+
+test('retry works on successful response', async () => {
+  await testRetryExpectingResult([TestResponse(200, 'Ok')], 'Ok')
+})
+
+test('retry works after retryable status code', async () => {
+  await testRetryExpectingResult(
+    [TestResponse(503), TestResponse(200, 'Ok')],
+    'Ok'
+  )
+})
+
+test('retry fails after exhausting retries', async () => {
+  await testRetryExpectingError([
+    TestResponse(503),
+    TestResponse(503),
+    TestResponse(200, 'Ok')
+  ])
+})
+
+test('retry fails after non-retryable status code', async () => {
+  await testRetryExpectingError([TestResponse(500), TestResponse(200, 'Ok')])
+})
+
+test('retry works after error', async () => {
+  await testRetryExpectingResult(
+    [TestResponse(new Error('Test error')), TestResponse(200, 'Ok')],
+    'Ok'
+  )
+})
+
+test('retry returns after client error', async () => {
+  await testRetryExpectingResult(
+    [TestResponse(400), TestResponse(200, 'Ok')],
+    null
+  )
+})
+
+test('retry converts errors to response object', async () => {
+  await testRetryConvertingErrorToResult(
+    [TestResponse(new HttpClientError('Test error', 409))],
+    409,
+    null
+  )
+})

packages/cache/__tests__/restoreCache.test.ts

@@ -0,0 +1,271 @@
+import * as core from '@actions/core'
+import * as path from 'path'
+import {restoreCache} from '../src/cache'
+import * as cacheHttpClient from '../src/internal/cacheHttpClient'
+import * as cacheUtils from '../src/internal/cacheUtils'
+import {CacheFilename, CompressionMethod} from '../src/internal/constants'
+import {ArtifactCacheEntry} from '../src/internal/contracts'
+import * as tar from '../src/internal/tar'
+
+jest.mock('../src/internal/cacheHttpClient')
+jest.mock('../src/internal/cacheUtils')
+jest.mock('../src/internal/tar')
+
+beforeAll(() => {
+  jest.spyOn(console, 'log').mockImplementation(() => {})
+  jest.spyOn(core, 'debug').mockImplementation(() => {})
+  jest.spyOn(core, 'info').mockImplementation(() => {})
+  jest.spyOn(core, 'warning').mockImplementation(() => {})
+  jest.spyOn(core, 'error').mockImplementation(() => {})
+
+  jest.spyOn(cacheUtils, 'getCacheFileName').mockImplementation(cm => {
+    const actualUtils = jest.requireActual('../src/internal/cacheUtils')
+    return actualUtils.getCacheFileName(cm)
+  })
+})
+
+test('restore with no path should fail', async () => {
+  const paths: string[] = []
+  const key = 'node-test'
+  await expect(restoreCache(paths, key)).rejects.toThrowError(
+    `Path Validation Error: At least one directory or file path is required`
+  )
+})
+
+test('restore with too many keys should fail', async () => {
+  const paths = ['node_modules']
+  const key = 'node-test'
+  const restoreKeys = [...Array(20).keys()].map(x => x.toString())
+  await expect(restoreCache(paths, key, restoreKeys)).rejects.toThrowError(
+    `Key Validation Error: Keys are limited to a maximum of 10.`
+  )
+})
+
+test('restore with large key should fail', async () => {
+  const paths = ['node_modules']
+  const key = 'foo'.repeat(512) // Over the 512 character limit
+  await expect(restoreCache(paths, key)).rejects.toThrowError(
+    `Key Validation Error: ${key} cannot be larger than 512 characters.`
+  )
+})
+
+test('restore with invalid key should fail', async () => {
+  const paths = ['node_modules']
+  const key = 'comma,comma'
+  await expect(restoreCache(paths, key)).rejects.toThrowError(
+    `Key Validation Error: ${key} cannot contain commas.`
+  )
+})
+
+test('restore with no cache found', async () => {
+  const paths = ['node_modules']
+  const key = 'node-test'
+
+  jest.spyOn(cacheHttpClient, 'getCacheEntry').mockImplementation(async () => {
+    return Promise.resolve(null)
+  })
+
+  const cacheKey = await restoreCache(paths, key)
+
+  expect(cacheKey).toBe(undefined)
+})
+
+test('restore with server error should fail', async () => {
+  const paths = ['node_modules']
+  const key = 'node-test'
+
+  jest.spyOn(cacheHttpClient, 'getCacheEntry').mockImplementation(() => {
+    throw new Error('HTTP Error Occurred')
+  })
+
+  await expect(restoreCache(paths, key)).rejects.toThrowError(
+    'HTTP Error Occurred'
+  )
+})
+
+test('restore with restore keys and no cache found', async () => {
+  const paths = ['node_modules']
+  const key = 'node-test'
+  const restoreKey = 'node-'
+
+  jest.spyOn(cacheHttpClient, 'getCacheEntry').mockImplementation(async () => {
+    return Promise.resolve(null)
+  })
+
+  const cacheKey = await restoreCache(paths, key, [restoreKey])
+
+  expect(cacheKey).toBe(undefined)
+})
+
+test('restore with gzip compressed cache found', async () => {
+  const paths = ['node_modules']
+  const key = 'node-test'
+
+  const cacheEntry: ArtifactCacheEntry = {
+    cacheKey: key,
+    scope: 'refs/heads/main',
+    archiveLocation: 'www.actionscache.test/download'
+  }
+  const getCacheMock = jest.spyOn(cacheHttpClient, 'getCacheEntry')
+  getCacheMock.mockImplementation(async () => {
+    return Promise.resolve(cacheEntry)
+  })
+
+  const tempPath = '/foo/bar'
+
+  const createTempDirectoryMock = jest.spyOn(cacheUtils, 'createTempDirectory')
+  createTempDirectoryMock.mockImplementation(async () => {
+    return Promise.resolve(tempPath)
+  })
+
+  const archivePath = path.join(tempPath, CacheFilename.Gzip)
+  const downloadCacheMock = jest.spyOn(cacheHttpClient, 'downloadCache')
+
+  const fileSize = 142
+  const getArchiveFileSizeInBytesMock = jest
+    .spyOn(cacheUtils, 'getArchiveFileSizeInBytes')
+    .mockReturnValue(fileSize)
+
+  const extractTarMock = jest.spyOn(tar, 'extractTar')
+  const unlinkFileMock = jest.spyOn(cacheUtils, 'unlinkFile')
+
+  const compression = CompressionMethod.Gzip
+  const getCompressionMock = jest
+    .spyOn(cacheUtils, 'getCompressionMethod')
+    .mockReturnValue(Promise.resolve(compression))
+
+  const cacheKey = await restoreCache(paths, key)
+
+  expect(cacheKey).toBe(key)
+  expect(getCacheMock).toHaveBeenCalledWith([key], paths, {
+    compressionMethod: compression
+  })
+  expect(createTempDirectoryMock).toHaveBeenCalledTimes(1)
+  expect(downloadCacheMock).toHaveBeenCalledWith(
+    cacheEntry.archiveLocation,
+    archivePath,
+    undefined
+  )
+  expect(getArchiveFileSizeInBytesMock).toHaveBeenCalledWith(archivePath)
+
+  expect(extractTarMock).toHaveBeenCalledTimes(1)
+  expect(extractTarMock).toHaveBeenCalledWith(archivePath, compression)
+
+  expect(unlinkFileMock).toHaveBeenCalledTimes(1)
+  expect(unlinkFileMock).toHaveBeenCalledWith(archivePath)
+
+  expect(getCompressionMock).toHaveBeenCalledTimes(1)
+})
+
+test('restore with zstd compressed cache found', async () => {
+  const paths = ['node_modules']
+  const key = 'node-test'
+
+  const infoMock = jest.spyOn(core, 'info')
+
+  const cacheEntry: ArtifactCacheEntry = {
+    cacheKey: key,
+    scope: 'refs/heads/main',
+    archiveLocation: 'www.actionscache.test/download'
+  }
+  const getCacheMock = jest.spyOn(cacheHttpClient, 'getCacheEntry')
+  getCacheMock.mockImplementation(async () => {
+    return Promise.resolve(cacheEntry)
+  })
+  const tempPath = '/foo/bar'
+
+  const createTempDirectoryMock = jest.spyOn(cacheUtils, 'createTempDirectory')
+  createTempDirectoryMock.mockImplementation(async () => {
+    return Promise.resolve(tempPath)
+  })
+
+  const archivePath = path.join(tempPath, CacheFilename.Zstd)
+  const downloadCacheMock = jest.spyOn(cacheHttpClient, 'downloadCache')
+
+  const fileSize = 62915000
+  const getArchiveFileSizeInBytesMock = jest
+    .spyOn(cacheUtils, 'getArchiveFileSizeInBytes')
+    .mockReturnValue(fileSize)
+
+  const extractTarMock = jest.spyOn(tar, 'extractTar')
+  const compression = CompressionMethod.Zstd
+  const getCompressionMock = jest
+    .spyOn(cacheUtils, 'getCompressionMethod')
+    .mockReturnValue(Promise.resolve(compression))
+
+  const cacheKey = await restoreCache(paths, key)
+
+  expect(cacheKey).toBe(key)
+  expect(getCacheMock).toHaveBeenCalledWith([key], paths, {
+    compressionMethod: compression
+  })
+  expect(createTempDirectoryMock).toHaveBeenCalledTimes(1)
+  expect(downloadCacheMock).toHaveBeenCalledWith(
+    cacheEntry.archiveLocation,
+    archivePath,
+    undefined
+  )
+  expect(getArchiveFileSizeInBytesMock).toHaveBeenCalledWith(archivePath)
+  expect(infoMock).toHaveBeenCalledWith(`Cache Size: ~60 MB (62915000 B)`)
+
+  expect(extractTarMock).toHaveBeenCalledTimes(1)
+  expect(extractTarMock).toHaveBeenCalledWith(archivePath, compression)
+  expect(getCompressionMock).toHaveBeenCalledTimes(1)
+})
+
+test('restore with cache found for restore key', async () => {
+  const paths = ['node_modules']
+  const key = 'node-test'
+  const restoreKey = 'node-'
+
+  const infoMock = jest.spyOn(core, 'info')
+
+  const cacheEntry: ArtifactCacheEntry = {
+    cacheKey: restoreKey,
+    scope: 'refs/heads/main',
+    archiveLocation: 'www.actionscache.test/download'
+  }
+  const getCacheMock = jest.spyOn(cacheHttpClient, 'getCacheEntry')
+  getCacheMock.mockImplementation(async () => {
+    return Promise.resolve(cacheEntry)
+  })
+  const tempPath = '/foo/bar'
+
+  const createTempDirectoryMock = jest.spyOn(cacheUtils, 'createTempDirectory')
+  createTempDirectoryMock.mockImplementation(async () => {
+    return Promise.resolve(tempPath)
+  })
+
+  const archivePath = path.join(tempPath, CacheFilename.Zstd)
+  const downloadCacheMock = jest.spyOn(cacheHttpClient, 'downloadCache')
+
+  const fileSize = 142
+  const getArchiveFileSizeInBytesMock = jest
+    .spyOn(cacheUtils, 'getArchiveFileSizeInBytes')
+    .mockReturnValue(fileSize)
+
+  const extractTarMock = jest.spyOn(tar, 'extractTar')
+  const compression = CompressionMethod.Zstd
+  const getCompressionMock = jest
+    .spyOn(cacheUtils, 'getCompressionMethod')
+    .mockReturnValue(Promise.resolve(compression))
+
+  const cacheKey = await restoreCache(paths, key, [restoreKey])
+
+  expect(cacheKey).toBe(restoreKey)
+  expect(getCacheMock).toHaveBeenCalledWith([key, restoreKey], paths, {
+    compressionMethod: compression
+  })
+  expect(createTempDirectoryMock).toHaveBeenCalledTimes(1)
+  expect(downloadCacheMock).toHaveBeenCalledWith(
+    cacheEntry.archiveLocation,
+    archivePath,
+    undefined
+  )
+  expect(getArchiveFileSizeInBytesMock).toHaveBeenCalledWith(archivePath)
+  expect(infoMock).toHaveBeenCalledWith(`Cache Size: ~0 MB (142 B)`)
+
+  expect(extractTarMock).toHaveBeenCalledTimes(1)
+  expect(extractTarMock).toHaveBeenCalledWith(archivePath, compression)
+  expect(getCompressionMock).toHaveBeenCalledTimes(1)
+})

packages/cache/__tests__/saveCache.test.ts

@@ -0,0 +1,188 @@
+import * as core from '@actions/core'
+import * as path from 'path'
+import {saveCache} from '../src/cache'
+import * as cacheHttpClient from '../src/internal/cacheHttpClient'
+import * as cacheUtils from '../src/internal/cacheUtils'
+import {CacheFilename, CompressionMethod} from '../src/internal/constants'
+import * as tar from '../src/internal/tar'
+
+jest.mock('../src/internal/cacheHttpClient')
+jest.mock('../src/internal/cacheUtils')
+jest.mock('../src/internal/tar')
+
+beforeAll(() => {
+  jest.spyOn(console, 'log').mockImplementation(() => {})
+  jest.spyOn(core, 'debug').mockImplementation(() => {})
+  jest.spyOn(core, 'info').mockImplementation(() => {})
+  jest.spyOn(core, 'warning').mockImplementation(() => {})
+  jest.spyOn(core, 'error').mockImplementation(() => {})
+
+  jest.spyOn(cacheUtils, 'getCacheFileName').mockImplementation(cm => {
+    const actualUtils = jest.requireActual('../src/internal/cacheUtils')
+    return actualUtils.getCacheFileName(cm)
+  })
+
+  jest.spyOn(cacheUtils, 'resolvePaths').mockImplementation(async filePaths => {
+    return filePaths.map(x => path.resolve(x))
+  })
+
+  jest.spyOn(cacheUtils, 'createTempDirectory').mockImplementation(async () => {
+    return Promise.resolve('/foo/bar')
+  })
+})
+
+test('save with missing input should fail', async () => {
+  const paths: string[] = []
+  const primaryKey = 'Linux-node-bb828da54c148048dd17899ba9fda624811cfb43'
+  await expect(saveCache(paths, primaryKey)).rejects.toThrowError(
+    `Path Validation Error: At least one directory or file path is required`
+  )
+})
+
+test('save with large cache outputs should fail', async () => {
+  const filePath = 'node_modules'
+  const primaryKey = 'Linux-node-bb828da54c148048dd17899ba9fda624811cfb43'
+  const cachePaths = [path.resolve(filePath)]
+
+  const createTarMock = jest.spyOn(tar, 'createTar')
+
+  const cacheSize = 11 * 1024 * 1024 * 1024 //~11GB, over the 10GB limit
+  jest
+    .spyOn(cacheUtils, 'getArchiveFileSizeInBytes')
+    .mockReturnValueOnce(cacheSize)
+  const compression = CompressionMethod.Gzip
+  const getCompressionMock = jest
+    .spyOn(cacheUtils, 'getCompressionMethod')
+    .mockReturnValueOnce(Promise.resolve(compression))
+
+  await expect(saveCache([filePath], primaryKey)).rejects.toThrowError(
+    'Cache size of ~11264 MB (11811160064 B) is over the 10GB limit, not saving cache.'
+  )
+
+  const archiveFolder = '/foo/bar'
+
+  expect(createTarMock).toHaveBeenCalledTimes(1)
+  expect(createTarMock).toHaveBeenCalledWith(
+    archiveFolder,
+    cachePaths,
+    compression
+  )
+  expect(getCompressionMock).toHaveBeenCalledTimes(1)
+})
+
+test('save with reserve cache failure should fail', async () => {
+  const paths = ['node_modules']
+  const primaryKey = 'Linux-node-bb828da54c148048dd17899ba9fda624811cfb43'
+
+  const reserveCacheMock = jest
+    .spyOn(cacheHttpClient, 'reserveCache')
+    .mockImplementation(async () => {
+      return -1
+    })
+
+  const createTarMock = jest.spyOn(tar, 'createTar')
+  const saveCacheMock = jest.spyOn(cacheHttpClient, 'saveCache')
+  const compression = CompressionMethod.Zstd
+  const getCompressionMock = jest
+    .spyOn(cacheUtils, 'getCompressionMethod')
+    .mockReturnValueOnce(Promise.resolve(compression))
+
+  await expect(saveCache(paths, primaryKey)).rejects.toThrowError(
+    `Unable to reserve cache with key ${primaryKey}, another job may be creating this cache.`
+  )
+  expect(reserveCacheMock).toHaveBeenCalledTimes(1)
+  expect(reserveCacheMock).toHaveBeenCalledWith(primaryKey, paths, {
+    compressionMethod: compression
+  })
+  expect(createTarMock).toHaveBeenCalledTimes(0)
+  expect(saveCacheMock).toHaveBeenCalledTimes(0)
+  expect(getCompressionMock).toHaveBeenCalledTimes(1)
+})
+
+test('save with server error should fail', async () => {
+  const filePath = 'node_modules'
+  const primaryKey = 'Linux-node-bb828da54c148048dd17899ba9fda624811cfb43'
+  const cachePaths = [path.resolve(filePath)]
+
+  const cacheId = 4
+  const reserveCacheMock = jest
+    .spyOn(cacheHttpClient, 'reserveCache')
+    .mockImplementation(async () => {
+      return cacheId
+    })
+
+  const createTarMock = jest.spyOn(tar, 'createTar')
+
+  const saveCacheMock = jest
+    .spyOn(cacheHttpClient, 'saveCache')
+    .mockImplementationOnce(() => {
+      throw new Error('HTTP Error Occurred')
+    })
+  const compression = CompressionMethod.Zstd
+  const getCompressionMock = jest
+    .spyOn(cacheUtils, 'getCompressionMethod')
+    .mockReturnValueOnce(Promise.resolve(compression))
+
+  await expect(saveCache([filePath], primaryKey)).rejects.toThrowError(
+    'HTTP Error Occurred'
+  )
+  expect(reserveCacheMock).toHaveBeenCalledTimes(1)
+  expect(reserveCacheMock).toHaveBeenCalledWith(primaryKey, [filePath], {
+    compressionMethod: compression
+  })
+
+  const archiveFolder = '/foo/bar'
+  const archiveFile = path.join(archiveFolder, CacheFilename.Zstd)
+
+  expect(createTarMock).toHaveBeenCalledTimes(1)
+  expect(createTarMock).toHaveBeenCalledWith(
+    archiveFolder,
+    cachePaths,
+    compression
+  )
+
+  expect(saveCacheMock).toHaveBeenCalledTimes(1)
+  expect(saveCacheMock).toHaveBeenCalledWith(cacheId, archiveFile, undefined)
+  expect(getCompressionMock).toHaveBeenCalledTimes(1)
+})
+
+test('save with valid inputs uploads a cache', async () => {
+  const filePath = 'node_modules'
+  const primaryKey = 'Linux-node-bb828da54c148048dd17899ba9fda624811cfb43'
+  const cachePaths = [path.resolve(filePath)]
+
+  const cacheId = 4
+  const reserveCacheMock = jest
+    .spyOn(cacheHttpClient, 'reserveCache')
+    .mockImplementation(async () => {
+      return cacheId
+    })
+  const createTarMock = jest.spyOn(tar, 'createTar')
+
+  const saveCacheMock = jest.spyOn(cacheHttpClient, 'saveCache')
+  const compression = CompressionMethod.Zstd
+  const getCompressionMock = jest
+    .spyOn(cacheUtils, 'getCompressionMethod')
+    .mockReturnValue(Promise.resolve(compression))
+
+  await saveCache([filePath], primaryKey)
+
+  expect(reserveCacheMock).toHaveBeenCalledTimes(1)
+  expect(reserveCacheMock).toHaveBeenCalledWith(primaryKey, [filePath], {
+    compressionMethod: compression
+  })
+
+  const archiveFolder = '/foo/bar'
+  const archiveFile = path.join(archiveFolder, CacheFilename.Zstd)
+
+  expect(createTarMock).toHaveBeenCalledTimes(1)
+  expect(createTarMock).toHaveBeenCalledWith(
+    archiveFolder,
+    cachePaths,
+    compression
+  )
+
+  expect(saveCacheMock).toHaveBeenCalledTimes(1)
+  expect(saveCacheMock).toHaveBeenCalledWith(cacheId, archiveFile, undefined)
+  expect(getCompressionMock).toHaveBeenCalledTimes(1)
+})

packages/cache/__tests__/tar.test.ts

@@ -0,0 +1,267 @@
+import * as exec from '@actions/exec'
+import * as io from '@actions/io'
+import * as path from 'path'
+import {CacheFilename, CompressionMethod} from '../src/internal/constants'
+import * as tar from '../src/internal/tar'
+import * as utils from '../src/internal/cacheUtils'
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+import fs = require('fs')
+
+jest.mock('@actions/exec')
+jest.mock('@actions/io')
+
+const IS_WINDOWS = process.platform === 'win32'
+const IS_MAC = process.platform === 'darwin'
+
+const defaultTarPath = process.platform === 'darwin' ? 'gtar' : 'tar'
+
+function getTempDir(): string {
+  return path.join(__dirname, '_temp', 'tar')
+}
+
+beforeAll(async () => {
+  jest.spyOn(io, 'which').mockImplementation(async tool => {
+    return tool
+  })
+
+  process.env['GITHUB_WORKSPACE'] = process.cwd()
+  await jest.requireActual('@actions/io').rmRF(getTempDir())
+})
+
+afterAll(async () => {
+  delete process.env['GITHUB_WORKSPACE']
+  await jest.requireActual('@actions/io').rmRF(getTempDir())
+})
+
+test('zstd extract tar', async () => {
+  const mkdirMock = jest.spyOn(io, 'mkdirP')
+  const execMock = jest.spyOn(exec, 'exec')
+
+  const archivePath = IS_WINDOWS
+    ? `${process.env['windir']}\\fakepath\\cache.tar`
+    : 'cache.tar'
+  const workspace = process.env['GITHUB_WORKSPACE']
+
+  await tar.extractTar(archivePath, CompressionMethod.Zstd)
+
+  expect(mkdirMock).toHaveBeenCalledWith(workspace)
+  expect(execMock).toHaveBeenCalledTimes(1)
+  expect(execMock).toHaveBeenCalledWith(
+    `"${defaultTarPath}"`,
+    [
+      '--use-compress-program',
+      'zstd -d --long=30',
+      '-xf',
+      IS_WINDOWS ? archivePath.replace(/\\/g, '/') : archivePath,
+      '-P',
+      '-C',
+      IS_WINDOWS ? workspace?.replace(/\\/g, '/') : workspace
+    ]
+      .concat(IS_WINDOWS ? ['--force-local'] : [])
+      .concat(IS_MAC ? ['--delay-directory-restore'] : []),
+    {cwd: undefined}
+  )
+})
+
+test('gzip extract tar', async () => {
+  const mkdirMock = jest.spyOn(io, 'mkdirP')
+  const execMock = jest.spyOn(exec, 'exec')
+  const archivePath = IS_WINDOWS
+    ? `${process.env['windir']}\\fakepath\\cache.tar`
+    : 'cache.tar'
+  const workspace = process.env['GITHUB_WORKSPACE']
+
+  await tar.extractTar(archivePath, CompressionMethod.Gzip)
+
+  expect(mkdirMock).toHaveBeenCalledWith(workspace)
+  const tarPath = IS_WINDOWS
+    ? `${process.env['windir']}\\System32\\tar.exe`
+    : defaultTarPath
+  expect(execMock).toHaveBeenCalledTimes(1)
+  expect(execMock).toHaveBeenCalledWith(
+    `"${tarPath}"`,
+    [
+      '-z',
+      '-xf',
+      IS_WINDOWS ? archivePath.replace(/\\/g, '/') : archivePath,
+      '-P',
+      '-C',
+      IS_WINDOWS ? workspace?.replace(/\\/g, '/') : workspace
+    ].concat(IS_MAC ? ['--delay-directory-restore'] : []),
+    {cwd: undefined}
+  )
+})
+
+test('gzip extract GNU tar on windows', async () => {
+  if (IS_WINDOWS) {
+    jest.spyOn(fs, 'existsSync').mockReturnValueOnce(false)
+
+    const isGnuMock = jest
+      .spyOn(utils, 'isGnuTarInstalled')
+      .mockReturnValue(Promise.resolve(true))
+    const execMock = jest.spyOn(exec, 'exec')
+    const archivePath = `${process.env['windir']}\\fakepath\\cache.tar`
+    const workspace = process.env['GITHUB_WORKSPACE']
+
+    await tar.extractTar(archivePath, CompressionMethod.Gzip)
+
+    expect(isGnuMock).toHaveBeenCalledTimes(1)
+    expect(execMock).toHaveBeenCalledTimes(1)
+    expect(execMock).toHaveBeenCalledWith(
+      `"tar"`,
+      [
+        '-z',
+        '-xf',
+        archivePath.replace(/\\/g, '/'),
+        '-P',
+        '-C',
+        workspace?.replace(/\\/g, '/'),
+        '--force-local'
+      ],
+      {cwd: undefined}
+    )
+  }
+})
+
+test('zstd create tar', async () => {
+  const execMock = jest.spyOn(exec, 'exec')
+
+  const archiveFolder = getTempDir()
+  const workspace = process.env['GITHUB_WORKSPACE']
+  const sourceDirectories = ['~/.npm/cache', `${workspace}/dist`]
+
+  await fs.promises.mkdir(archiveFolder, {recursive: true})
+
+  await tar.createTar(archiveFolder, sourceDirectories, CompressionMethod.Zstd)
+
+  expect(execMock).toHaveBeenCalledTimes(1)
+  expect(execMock).toHaveBeenCalledWith(
+    `"${defaultTarPath}"`,
+    [
+      '--posix',
+      '--use-compress-program',
+      'zstd -T0 --long=30',
+      '-cf',
+      IS_WINDOWS ? CacheFilename.Zstd.replace(/\\/g, '/') : CacheFilename.Zstd,
+      '-P',
+      '-C',
+      IS_WINDOWS ? workspace?.replace(/\\/g, '/') : workspace,
+      '--files-from',
+      'manifest.txt'
+    ]
+      .concat(IS_WINDOWS ? ['--force-local'] : [])
+      .concat(IS_MAC ? ['--delay-directory-restore'] : []),
+    {
+      cwd: archiveFolder
+    }
+  )
+})
+
+test('gzip create tar', async () => {
+  const execMock = jest.spyOn(exec, 'exec')
+
+  const archiveFolder = getTempDir()
+  const workspace = process.env['GITHUB_WORKSPACE']
+  const sourceDirectories = ['~/.npm/cache', `${workspace}/dist`]
+
+  await fs.promises.mkdir(archiveFolder, {recursive: true})
+
+  await tar.createTar(archiveFolder, sourceDirectories, CompressionMethod.Gzip)
+
+  const tarPath = IS_WINDOWS
+    ? `${process.env['windir']}\\System32\\tar.exe`
+    : defaultTarPath
+
+  expect(execMock).toHaveBeenCalledTimes(1)
+  expect(execMock).toHaveBeenCalledWith(
+    `"${tarPath}"`,
+    [
+      '--posix',
+      '-z',
+      '-cf',
+      IS_WINDOWS ? CacheFilename.Gzip.replace(/\\/g, '/') : CacheFilename.Gzip,
+      '-P',
+      '-C',
+      IS_WINDOWS ? workspace?.replace(/\\/g, '/') : workspace,
+      '--files-from',
+      'manifest.txt'
+    ].concat(IS_MAC ? ['--delay-directory-restore'] : []),
+    {
+      cwd: archiveFolder
+    }
+  )
+})
+
+test('zstd list tar', async () => {
+  const execMock = jest.spyOn(exec, 'exec')
+
+  const archivePath = IS_WINDOWS
+    ? `${process.env['windir']}\\fakepath\\cache.tar`
+    : 'cache.tar'
+
+  await tar.listTar(archivePath, CompressionMethod.Zstd)
+
+  expect(execMock).toHaveBeenCalledTimes(1)
+  expect(execMock).toHaveBeenCalledWith(
+    `"${defaultTarPath}"`,
+    [
+      '--use-compress-program',
+      'zstd -d --long=30',
+      '-tf',
+      IS_WINDOWS ? archivePath.replace(/\\/g, '/') : archivePath,
+      '-P'
+    ]
+      .concat(IS_WINDOWS ? ['--force-local'] : [])
+      .concat(IS_MAC ? ['--delay-directory-restore'] : []),
+    {cwd: undefined}
+  )
+})
+
+test('zstdWithoutLong list tar', async () => {
+  const execMock = jest.spyOn(exec, 'exec')
+
+  const archivePath = IS_WINDOWS
+    ? `${process.env['windir']}\\fakepath\\cache.tar`
+    : 'cache.tar'
+
+  await tar.listTar(archivePath, CompressionMethod.ZstdWithoutLong)
+
+  expect(execMock).toHaveBeenCalledTimes(1)
+  expect(execMock).toHaveBeenCalledWith(
+    `"${defaultTarPath}"`,
+    [
+      '--use-compress-program',
+      'zstd -d',
+      '-tf',
+      IS_WINDOWS ? archivePath.replace(/\\/g, '/') : archivePath,
+      '-P'
+    ]
+      .concat(IS_WINDOWS ? ['--force-local'] : [])
+      .concat(IS_MAC ? ['--delay-directory-restore'] : []),
+    {cwd: undefined}
+  )
+})
+
+test('gzip list tar', async () => {
+  const execMock = jest.spyOn(exec, 'exec')
+  const archivePath = IS_WINDOWS
+    ? `${process.env['windir']}\\fakepath\\cache.tar`
+    : 'cache.tar'
+
+  await tar.listTar(archivePath, CompressionMethod.Gzip)
+
+  const tarPath = IS_WINDOWS
+    ? `${process.env['windir']}\\System32\\tar.exe`
+    : defaultTarPath
+  expect(execMock).toHaveBeenCalledTimes(1)
+  expect(execMock).toHaveBeenCalledWith(
+    `"${tarPath}"`,
+    [
+      '-z',
+      '-tf',
+      IS_WINDOWS ? archivePath.replace(/\\/g, '/') : archivePath,
+      '-P'
+    ].concat(IS_MAC ? ['--delay-directory-restore'] : []),
+    {cwd: undefined}
+  )
+})

packages/cache/__tests__/verify-cache-files.sh

@@ -0,0 +1,36 @@
+#!/bin/sh
+
+# Validate args
+prefix="$1"
+if [ -z "$prefix" ]; then
+  echo "Must supply prefix argument"
+  exit 1
+fi
+
+path="$2"
+if [ -z "$path" ]; then
+  echo "Must specify path argument"
+  exit 1
+fi
+
+# Sanity check GITHUB_RUN_ID defined
+if [ -z "$GITHUB_RUN_ID" ]; then
+  echo "GITHUB_RUN_ID not defined"
+  exit 1
+fi
+
+# Verify file exists
+file="$path/test-file.txt"
+echo "Checking for $file"
+if [ ! -e $file ]; then
+  echo "File does not exist"
+  exit 1
+fi
+
+# Verify file content
+content="$(cat $file)"
+echo "File content:\n$content"
+if [ -z "$(echo $content | grep --fixed-strings "$prefix $GITHUB_RUN_ID")" ]; then
+  echo "Unexpected file content"
+  exit 1
+fi

packages/cache/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@actions/cache",
+  "version": "1.0.8",
+  "preview": true,
+  "description": "Actions cache lib",
+  "keywords": [
+    "github",
+    "actions",
+    "cache"
+  ],
+  "homepage": "https://github.com/actions/toolkit/tree/main/packages/cache",
+  "license": "MIT",
+  "main": "lib/cache.js",
+  "types": "lib/cache.d.ts",
+  "directories": {
+    "lib": "lib",
+    "test": "__tests__"
+  },
+  "files": [
+    "lib",
+    "!.DS_Store"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/actions/toolkit.git",
+    "directory": "packages/cache"
+  },
+  "scripts": {
+    "audit-moderate": "npm install && npm audit --json --audit-level=moderate > audit.json",
+    "test": "echo \"Error: run tests from root\" && exit 1",
+    "tsc": "tsc"
+  },
+  "bugs": {
+    "url": "https://github.com/actions/toolkit/issues"
+  },
+  "dependencies": {
+    "@actions/core": "^1.2.6",
+    "@actions/exec": "^1.0.1",
+    "@actions/glob": "^0.1.0",
+    "@actions/http-client": "^1.0.9",
+    "@actions/io": "^1.0.1",
+    "@azure/ms-rest-js": "^2.0.7",
+    "@azure/storage-blob": "^12.1.2",
+    "semver": "^6.1.0",
+    "uuid": "^3.3.3"
+  },
+  "devDependencies": {
+    "typescript": "^3.8.3",
+    "@types/semver": "^6.0.0",
+    "@types/uuid": "^3.4.5"
+  }
+}

packages/cache/src/cache.ts

@@ -0,0 +1,198 @@
+import * as core from '@actions/core'
+import * as path from 'path'
+import * as utils from './internal/cacheUtils'
+import * as cacheHttpClient from './internal/cacheHttpClient'
+import {createTar, extractTar, listTar} from './internal/tar'
+import {DownloadOptions, UploadOptions} from './options'
+
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ValidationError'
+    Object.setPrototypeOf(this, ValidationError.prototype)
+  }
+}
+
+export class ReserveCacheError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ReserveCacheError'
+    Object.setPrototypeOf(this, ReserveCacheError.prototype)
+  }
+}
+
+function checkPaths(paths: string[]): void {
+  if (!paths || paths.length === 0) {
+    throw new ValidationError(
+      `Path Validation Error: At least one directory or file path is required`
+    )
+  }
+}
+
+function checkKey(key: string): void {
+  if (key.length > 512) {
+    throw new ValidationError(
+      `Key Validation Error: ${key} cannot be larger than 512 characters.`
+    )
+  }
+  const regex = /^[^,]*$/
+  if (!regex.test(key)) {
+    throw new ValidationError(
+      `Key Validation Error: ${key} cannot contain commas.`
+    )
+  }
+}
+
+/**
+ * Restores cache from keys
+ *
+ * @param paths a list of file paths to restore from the cache
+ * @param primaryKey an explicit key for restoring the cache
+ * @param restoreKeys an optional ordered list of keys to use for restoring the cache if no cache hit occurred for key
+ * @param downloadOptions cache download options
+ * @returns string returns the key for the cache hit, otherwise returns undefined
+ */
+export async function restoreCache(
+  paths: string[],
+  primaryKey: string,
+  restoreKeys?: string[],
+  options?: DownloadOptions
+): Promise<string | undefined> {
+  checkPaths(paths)
+
+  restoreKeys = restoreKeys || []
+  const keys = [primaryKey, ...restoreKeys]
+
+  core.debug('Resolved Keys:')
+  core.debug(JSON.stringify(keys))
+
+  if (keys.length > 10) {
+    throw new ValidationError(
+      `Key Validation Error: Keys are limited to a maximum of 10.`
+    )
+  }
+  for (const key of keys) {
+    checkKey(key)
+  }
+
+  const compressionMethod = await utils.getCompressionMethod()
+
+  // path are needed to compute version
+  const cacheEntry = await cacheHttpClient.getCacheEntry(keys, paths, {
+    compressionMethod
+  })
+  if (!cacheEntry?.archiveLocation) {
+    // Cache not found
+    return undefined
+  }
+
+  const archivePath = path.join(
+    await utils.createTempDirectory(),
+    utils.getCacheFileName(compressionMethod)
+  )
+  core.debug(`Archive Path: ${archivePath}`)
+
+  try {
+    // Download the cache from the cache entry
+    await cacheHttpClient.downloadCache(
+      cacheEntry.archiveLocation,
+      archivePath,
+      options
+    )
+
+    if (core.isDebug()) {
+      await listTar(archivePath, compressionMethod)
+    }
+
+    const archiveFileSize = utils.getArchiveFileSizeInBytes(archivePath)
+    core.info(
+      `Cache Size: ~${Math.round(
+        archiveFileSize / (1024 * 1024)
+      )} MB (${archiveFileSize} B)`
+    )
+
+    await extractTar(archivePath, compressionMethod)
+    core.info('Cache restored successfully')
+  } finally {
+    // Try to delete the archive to save space
+    try {
+      await utils.unlinkFile(archivePath)
+    } catch (error) {
+      core.debug(`Failed to delete archive: ${error}`)
+    }
+  }
+
+  return cacheEntry.cacheKey
+}
+
+/**
+ * Saves a list of files with the specified key
+ *
+ * @param paths a list of file paths to be cached
+ * @param key an explicit key for restoring the cache
+ * @param options cache upload options
+ * @returns number returns cacheId if the cache was saved successfully and throws an error if save fails
+ */
+export async function saveCache(
+  paths: string[],
+  key: string,
+  options?: UploadOptions
+): Promise<number> {
+  checkPaths(paths)
+  checkKey(key)
+
+  const compressionMethod = await utils.getCompressionMethod()
+
+  core.debug('Reserving Cache')
+  const cacheId = await cacheHttpClient.reserveCache(key, paths, {
+    compressionMethod
+  })
+  if (cacheId === -1) {
+    throw new ReserveCacheError(
+      `Unable to reserve cache with key ${key}, another job may be creating this cache.`
+    )
+  }
+  core.debug(`Cache ID: ${cacheId}`)
+
+  const cachePaths = await utils.resolvePaths(paths)
+  core.debug('Cache Paths:')
+  core.debug(`${JSON.stringify(cachePaths)}`)
+
+  const archiveFolder = await utils.createTempDirectory()
+  const archivePath = path.join(
+    archiveFolder,
+    utils.getCacheFileName(compressionMethod)
+  )
+
+  core.debug(`Archive Path: ${archivePath}`)
+
+  try {
+    await createTar(archiveFolder, cachePaths, compressionMethod)
+    if (core.isDebug()) {
+      await listTar(archivePath, compressionMethod)
+    }
+
+    const fileSizeLimit = 10 * 1024 * 1024 * 1024 // 10GB per repo limit
+    const archiveFileSize = utils.getArchiveFileSizeInBytes(archivePath)
+    core.debug(`File Size: ${archiveFileSize}`)
+    if (archiveFileSize > fileSizeLimit) {
+      throw new Error(
+        `Cache size of ~${Math.round(
+          archiveFileSize / (1024 * 1024)
+        )} MB (${archiveFileSize} B) is over the 10GB limit, not saving cache.`
+      )
+    }
+
+    core.debug(`Saving Cache (ID: ${cacheId})`)
+    await cacheHttpClient.saveCache(cacheId, archivePath, options)
+  } finally {
+    // Try to delete the archive to save space
+    try {
+      await utils.unlinkFile(archivePath)
+    } catch (error) {
+      core.debug(`Failed to delete archive: ${error}`)
+    }
+  }
+
+  return cacheId
+}

packages/cache/src/internal/cacheHttpClient.ts

@@ -0,0 +1,316 @@
+import * as core from '@actions/core'
+import {HttpClient} from '@actions/http-client'
+import {BearerCredentialHandler} from '@actions/http-client/auth'
+import {IRequestOptions, ITypedResponse} from '@actions/http-client/interfaces'
+import * as crypto from 'crypto'
+import * as fs from 'fs'
+import {URL} from 'url'
+
+import * as utils from './cacheUtils'
+import {CompressionMethod} from './constants'
+import {
+  ArtifactCacheEntry,
+  InternalCacheOptions,
+  CommitCacheRequest,
+  ReserveCacheRequest,
+  ReserveCacheResponse
+} from './contracts'
+import {downloadCacheHttpClient, downloadCacheStorageSDK} from './downloadUtils'
+import {
+  DownloadOptions,
+  UploadOptions,
+  getDownloadOptions,
+  getUploadOptions
+} from '../options'
+import {
+  isSuccessStatusCode,
+  retryHttpClientResponse,
+  retryTypedResponse
+} from './requestUtils'
+
+const versionSalt = '1.0'
+
+function getCacheApiUrl(resource: string): string {
+  // Ideally we just use ACTIONS_CACHE_URL
+  const baseUrl: string = (
+    process.env['ACTIONS_CACHE_URL'] ||
+    process.env['ACTIONS_RUNTIME_URL'] ||
+    ''
+  ).replace('pipelines', 'artifactcache')
+  if (!baseUrl) {
+    throw new Error('Cache Service Url not found, unable to restore cache.')
+  }
+
+  const url = `${baseUrl}_apis/artifactcache/${resource}`
+  core.debug(`Resource Url: ${url}`)
+  return url
+}
+
+function createAcceptHeader(type: string, apiVersion: string): string {
+  return `${type};api-version=${apiVersion}`
+}
+
+function getRequestOptions(): IRequestOptions {
+  const requestOptions: IRequestOptions = {
+    headers: {
+      Accept: createAcceptHeader('application/json', '6.0-preview.1')
+    }
+  }
+
+  return requestOptions
+}
+
+function createHttpClient(): HttpClient {
+  const token = process.env['ACTIONS_RUNTIME_TOKEN'] || ''
+  const bearerCredentialHandler = new BearerCredentialHandler(token)
+
+  return new HttpClient(
+    'actions/cache',
+    [bearerCredentialHandler],
+    getRequestOptions()
+  )
+}
+
+export function getCacheVersion(
+  paths: string[],
+  compressionMethod?: CompressionMethod
+): string {
+  const components = paths.concat(
+    !compressionMethod || compressionMethod === CompressionMethod.Gzip
+      ? []
+      : [compressionMethod]
+  )
+
+  // Add salt to cache version to support breaking changes in cache entry
+  components.push(versionSalt)
+
+  return crypto
+    .createHash('sha256')
+    .update(components.join('|'))
+    .digest('hex')
+}
+
+export async function getCacheEntry(
+  keys: string[],
+  paths: string[],
+  options?: InternalCacheOptions
+): Promise<ArtifactCacheEntry | null> {
+  const httpClient = createHttpClient()
+  const version = getCacheVersion(paths, options?.compressionMethod)
+  const resource = `cache?keys=${encodeURIComponent(
+    keys.join(',')
+  )}&version=${version}`
+
+  const response = await retryTypedResponse('getCacheEntry', async () =>
+    httpClient.getJson<ArtifactCacheEntry>(getCacheApiUrl(resource))
+  )
+  if (response.statusCode === 204) {
+    return null
+  }
+  if (!isSuccessStatusCode(response.statusCode)) {
+    throw new Error(`Cache service responded with ${response.statusCode}`)
+  }
+
+  const cacheResult = response.result
+  const cacheDownloadUrl = cacheResult?.archiveLocation
+  if (!cacheDownloadUrl) {
+    throw new Error('Cache not found.')
+  }
+  core.setSecret(cacheDownloadUrl)
+  core.debug(`Cache Result:`)
+  core.debug(JSON.stringify(cacheResult))
+
+  return cacheResult
+}
+
+export async function downloadCache(
+  archiveLocation: string,
+  archivePath: string,
+  options?: DownloadOptions
+): Promise<void> {
+  const archiveUrl = new URL(archiveLocation)
+  const downloadOptions = getDownloadOptions(options)
+
+  if (
+    downloadOptions.useAzureSdk &&
+    archiveUrl.hostname.endsWith('.blob.core.windows.net')
+  ) {
+    // Use Azure storage SDK to download caches hosted on Azure to improve speed and reliability.
+    await downloadCacheStorageSDK(archiveLocation, archivePath, downloadOptions)
+  } else {
+    // Otherwise, download using the Actions http-client.
+    await downloadCacheHttpClient(archiveLocation, archivePath)
+  }
+}
+
+// Reserve Cache
+export async function reserveCache(
+  key: string,
+  paths: string[],
+  options?: InternalCacheOptions
+): Promise<number> {
+  const httpClient = createHttpClient()
+  const version = getCacheVersion(paths, options?.compressionMethod)
+
+  const reserveCacheRequest: ReserveCacheRequest = {
+    key,
+    version
+  }
+  const response = await retryTypedResponse('reserveCache', async () =>
+    httpClient.postJson<ReserveCacheResponse>(
+      getCacheApiUrl('caches'),
+      reserveCacheRequest
+    )
+  )
+  return response?.result?.cacheId ?? -1
+}
+
+function getContentRange(start: number, end: number): string {
+  // Format: `bytes start-end/filesize
+  // start and end are inclusive
+  // filesize can be *
+  // For a 200 byte chunk starting at byte 0:
+  // Content-Range: bytes 0-199/*
+  return `bytes ${start}-${end}/*`
+}
+
+async function uploadChunk(
+  httpClient: HttpClient,
+  resourceUrl: string,
+  openStream: () => NodeJS.ReadableStream,
+  start: number,
+  end: number
+): Promise<void> {
+  core.debug(
+    `Uploading chunk of size ${end -
+      start +
+      1} bytes at offset ${start} with content range: ${getContentRange(
+      start,
+      end
+    )}`
+  )
+  const additionalHeaders = {
+    'Content-Type': 'application/octet-stream',
+    'Content-Range': getContentRange(start, end)
+  }
+
+  const uploadChunkResponse = await retryHttpClientResponse(
+    `uploadChunk (start: ${start}, end: ${end})`,
+    async () =>
+      httpClient.sendStream(
+        'PATCH',
+        resourceUrl,
+        openStream(),
+        additionalHeaders
+      )
+  )
+
+  if (!isSuccessStatusCode(uploadChunkResponse.message.statusCode)) {
+    throw new Error(
+      `Cache service responded with ${uploadChunkResponse.message.statusCode} during upload chunk.`
+    )
+  }
+}
+
+async function uploadFile(
+  httpClient: HttpClient,
+  cacheId: number,
+  archivePath: string,
+  options?: UploadOptions
+): Promise<void> {
+  // Upload Chunks
+  const fileSize = utils.getArchiveFileSizeInBytes(archivePath)
+  const resourceUrl = getCacheApiUrl(`caches/${cacheId.toString()}`)
+  const fd = fs.openSync(archivePath, 'r')
+  const uploadOptions = getUploadOptions(options)
+
+  const concurrency = utils.assertDefined(
+    'uploadConcurrency',
+    uploadOptions.uploadConcurrency
+  )
+  const maxChunkSize = utils.assertDefined(
+    'uploadChunkSize',
+    uploadOptions.uploadChunkSize
+  )
+
+  const parallelUploads = [...new Array(concurrency).keys()]
+  core.debug('Awaiting all uploads')
+  let offset = 0
+
+  try {
+    await Promise.all(
+      parallelUploads.map(async () => {
+        while (offset < fileSize) {
+          const chunkSize = Math.min(fileSize - offset, maxChunkSize)
+          const start = offset
+          const end = offset + chunkSize - 1
+          offset += maxChunkSize
+
+          await uploadChunk(
+            httpClient,
+            resourceUrl,
+            () =>
+              fs
+                .createReadStream(archivePath, {
+                  fd,
+                  start,
+                  end,
+                  autoClose: false
+                })
+                .on('error', error => {
+                  throw new Error(
+                    `Cache upload failed because file read failed with ${error.message}`
+                  )
+                }),
+            start,
+            end
+          )
+        }
+      })
+    )
+  } finally {
+    fs.closeSync(fd)
+  }
+  return
+}
+
+async function commitCache(
+  httpClient: HttpClient,
+  cacheId: number,
+  filesize: number
+): Promise<ITypedResponse<null>> {
+  const commitCacheRequest: CommitCacheRequest = {size: filesize}
+  return await retryTypedResponse('commitCache', async () =>
+    httpClient.postJson<null>(
+      getCacheApiUrl(`caches/${cacheId.toString()}`),
+      commitCacheRequest
+    )
+  )
+}
+
+export async function saveCache(
+  cacheId: number,
+  archivePath: string,
+  options?: UploadOptions
+): Promise<void> {
+  const httpClient = createHttpClient()
+
+  core.debug('Upload cache')
+  await uploadFile(httpClient, cacheId, archivePath, options)
+
+  // Commit Cache
+  core.debug('Commiting cache')
+  const cacheSize = utils.getArchiveFileSizeInBytes(archivePath)
+  core.info(
+    `Cache Size: ~${Math.round(cacheSize / (1024 * 1024))} MB (${cacheSize} B)`
+  )
+
+  const commitCacheResponse = await commitCache(httpClient, cacheId, cacheSize)
+  if (!isSuccessStatusCode(commitCacheResponse.statusCode)) {
+    throw new Error(
+      `Cache service responded with ${commitCacheResponse.statusCode} during commit cache.`
+    )
+  }
+
+  core.info('Cache saved successfully')
+}

packages/cache/src/internal/cacheUtils.ts

@@ -0,0 +1,125 @@
+import * as core from '@actions/core'
+import * as exec from '@actions/exec'
+import * as glob from '@actions/glob'
+import * as io from '@actions/io'
+import * as fs from 'fs'
+import * as path from 'path'
+import * as semver from 'semver'
+import * as util from 'util'
+import {v4 as uuidV4} from 'uuid'
+import {CacheFilename, CompressionMethod} from './constants'
+
+// From https://github.com/actions/toolkit/blob/main/packages/tool-cache/src/tool-cache.ts#L23
+export async function createTempDirectory(): Promise<string> {
+  const IS_WINDOWS = process.platform === 'win32'
+
+  let tempDirectory: string = process.env['RUNNER_TEMP'] || ''
+
+  if (!tempDirectory) {
+    let baseLocation: string
+    if (IS_WINDOWS) {
+      // On Windows use the USERPROFILE env variable
+      baseLocation = process.env['USERPROFILE'] || 'C:\\'
+    } else {
+      if (process.platform === 'darwin') {
+        baseLocation = '/Users'
+      } else {
+        baseLocation = '/home'
+      }
+    }
+    tempDirectory = path.join(baseLocation, 'actions', 'temp')
+  }
+
+  const dest = path.join(tempDirectory, uuidV4())
+  await io.mkdirP(dest)
+  return dest
+}
+
+export function getArchiveFileSizeInBytes(filePath: string): number {
+  return fs.statSync(filePath).size
+}
+
+export async function resolvePaths(patterns: string[]): Promise<string[]> {
+  const paths: string[] = []
+  const workspace = process.env['GITHUB_WORKSPACE'] ?? process.cwd()
+  const globber = await glob.create(patterns.join('\n'), {
+    implicitDescendants: false
+  })
+
+  for await (const file of globber.globGenerator()) {
+    const relativeFile = path
+      .relative(workspace, file)
+      .replace(new RegExp(`\\${path.sep}`, 'g'), '/')
+    core.debug(`Matched: ${relativeFile}`)
+    // Paths are made relative so the tar entries are all relative to the root of the workspace.
+    paths.push(`${relativeFile}`)
+  }
+
+  return paths
+}
+
+export async function unlinkFile(filePath: fs.PathLike): Promise<void> {
+  return util.promisify(fs.unlink)(filePath)
+}
+
+async function getVersion(app: string): Promise<string> {
+  core.debug(`Checking ${app} --version`)
+  let versionOutput = ''
+  try {
+    await exec.exec(`${app} --version`, [], {
+      ignoreReturnCode: true,
+      silent: true,
+      listeners: {
+        stdout: (data: Buffer): string => (versionOutput += data.toString()),
+        stderr: (data: Buffer): string => (versionOutput += data.toString())
+      }
+    })
+  } catch (err) {
+    core.debug(err.message)
+  }
+
+  versionOutput = versionOutput.trim()
+  core.debug(versionOutput)
+  return versionOutput
+}
+
+// Use zstandard if possible to maximize cache performance
+export async function getCompressionMethod(): Promise<CompressionMethod> {
+  if (process.platform === 'win32' && !(await isGnuTarInstalled())) {
+    // Disable zstd due to bug https://github.com/actions/cache/issues/301
+    return CompressionMethod.Gzip
+  }
+
+  const versionOutput = await getVersion('zstd')
+  const version = semver.clean(versionOutput)
+
+  if (!versionOutput.toLowerCase().includes('zstd command line interface')) {
+    // zstd is not installed
+    return CompressionMethod.Gzip
+  } else if (!version || semver.lt(version, 'v1.3.2')) {
+    // zstd is installed but using a version earlier than v1.3.2
+    // v1.3.2 is required to use the `--long` options in zstd
+    return CompressionMethod.ZstdWithoutLong
+  } else {
+    return CompressionMethod.Zstd
+  }
+}
+
+export function getCacheFileName(compressionMethod: CompressionMethod): string {
+  return compressionMethod === CompressionMethod.Gzip
+    ? CacheFilename.Gzip
+    : CacheFilename.Zstd
+}
+
+export async function isGnuTarInstalled(): Promise<boolean> {
+  const versionOutput = await getVersion('tar')
+  return versionOutput.toLowerCase().includes('gnu tar')
+}
+
+export function assertDefined<T>(name: string, value?: T): T {
+  if (value === undefined) {
+    throw Error(`Expected ${name} but value was undefiend`)
+  }
+
+  return value
+}

packages/cache/src/internal/constants.ts

@@ -0,0 +1,23 @@
+export enum CacheFilename {
+  Gzip = 'cache.tgz',
+  Zstd = 'cache.tzst'
+}
+
+export enum CompressionMethod {
+  Gzip = 'gzip',
+  // Long range mode was added to zstd in v1.3.2.
+  // This enum is for earlier version of zstd that does not have --long support
+  ZstdWithoutLong = 'zstd-without-long',
+  Zstd = 'zstd'
+}
+
+// The default number of retry attempts.
+export const DefaultRetryAttempts = 2
+
+// The default delay in milliseconds between retry attempts.
+export const DefaultRetryDelay = 5000
+
+// Socket timeout in milliseconds during download.  If no traffic is received
+// over the socket during this period, the socket is destroyed and the download
+// is aborted.
+export const SocketTimeout = 5000

packages/cache/src/internal/contracts.d.ts

@@ -0,0 +1,25 @@
+import {CompressionMethod} from './constants'
+
+export interface ArtifactCacheEntry {
+  cacheKey?: string
+  scope?: string
+  creationTime?: string
+  archiveLocation?: string
+}
+
+export interface CommitCacheRequest {
+  size: number
+}
+
+export interface ReserveCacheRequest {
+  key: string
+  version?: string
+}
+
+export interface ReserveCacheResponse {
+  cacheId: number
+}
+
+export interface InternalCacheOptions {
+  compressionMethod?: CompressionMethod
+}

packages/cache/src/internal/downloadUtils.ts

@@ -0,0 +1,278 @@
+import * as core from '@actions/core'
+import {HttpClient} from '@actions/http-client'
+import {IHttpClientResponse} from '@actions/http-client/interfaces'
+import {BlockBlobClient} from '@azure/storage-blob'
+import {TransferProgressEvent} from '@azure/ms-rest-js'
+import * as buffer from 'buffer'
+import * as fs from 'fs'
+import * as stream from 'stream'
+import * as util from 'util'
+
+import * as utils from './cacheUtils'
+import {SocketTimeout} from './constants'
+import {DownloadOptions} from '../options'
+import {retryHttpClientResponse} from './requestUtils'
+
+/**
+ * Pipes the body of a HTTP response to a stream
+ *
+ * @param response the HTTP response
+ * @param output the writable stream
+ */
+async function pipeResponseToStream(
+  response: IHttpClientResponse,
+  output: NodeJS.WritableStream
+): Promise<void> {
+  const pipeline = util.promisify(stream.pipeline)
+  await pipeline(response.message, output)
+}
+
+/**
+ * Class for tracking the download state and displaying stats.
+ */
+export class DownloadProgress {
+  contentLength: number
+  segmentIndex: number
+  segmentSize: number
+  segmentOffset: number
+  receivedBytes: number
+  startTime: number
+  displayedComplete: boolean
+  timeoutHandle?: ReturnType<typeof setTimeout>
+
+  constructor(contentLength: number) {
+    this.contentLength = contentLength
+    this.segmentIndex = 0
+    this.segmentSize = 0
+    this.segmentOffset = 0
+    this.receivedBytes = 0
+    this.displayedComplete = false
+    this.startTime = Date.now()
+  }
+
+  /**
+   * Progress to the next segment. Only call this method when the previous segment
+   * is complete.
+   *
+   * @param segmentSize the length of the next segment
+   */
+  nextSegment(segmentSize: number): void {
+    this.segmentOffset = this.segmentOffset + this.segmentSize
+    this.segmentIndex = this.segmentIndex + 1
+    this.segmentSize = segmentSize
+    this.receivedBytes = 0
+
+    core.debug(
+      `Downloading segment at offset ${this.segmentOffset} with length ${this.segmentSize}...`
+    )
+  }
+
+  /**
+   * Sets the number of bytes received for the current segment.
+   *
+   * @param receivedBytes the number of bytes received
+   */
+  setReceivedBytes(receivedBytes: number): void {
+    this.receivedBytes = receivedBytes
+  }
+
+  /**
+   * Returns the total number of bytes transferred.
+   */
+  getTransferredBytes(): number {
+    return this.segmentOffset + this.receivedBytes
+  }
+
+  /**
+   * Returns true if the download is complete.
+   */
+  isDone(): boolean {
+    return this.getTransferredBytes() === this.contentLength
+  }
+
+  /**
+   * Prints the current download stats. Once the download completes, this will print one
+   * last line and then stop.
+   */
+  display(): void {
+    if (this.displayedComplete) {
+      return
+    }
+
+    const transferredBytes = this.segmentOffset + this.receivedBytes
+    const percentage = (100 * (transferredBytes / this.contentLength)).toFixed(
+      1
+    )
+    const elapsedTime = Date.now() - this.startTime
+    const downloadSpeed = (
+      transferredBytes /
+      (1024 * 1024) /
+      (elapsedTime / 1000)
+    ).toFixed(1)
+
+    core.info(
+      `Received ${transferredBytes} of ${this.contentLength} (${percentage}%), ${downloadSpeed} MBs/sec`
+    )
+
+    if (this.isDone()) {
+      this.displayedComplete = true
+    }
+  }
+
+  /**
+   * Returns a function used to handle TransferProgressEvents.
+   */
+  onProgress(): (progress: TransferProgressEvent) => void {
+    return (progress: TransferProgressEvent) => {
+      this.setReceivedBytes(progress.loadedBytes)
+    }
+  }
+
+  /**
+   * Starts the timer that displays the stats.
+   *
+   * @param delayInMs the delay between each write
+   */
+  startDisplayTimer(delayInMs = 1000): void {
+    const displayCallback = (): void => {
+      this.display()
+
+      if (!this.isDone()) {
+        this.timeoutHandle = setTimeout(displayCallback, delayInMs)
+      }
+    }
+
+    this.timeoutHandle = setTimeout(displayCallback, delayInMs)
+  }
+
+  /**
+   * Stops the timer that displays the stats. As this typically indicates the download
+   * is complete, this will display one last line, unless the last line has already
+   * been written.
+   */
+  stopDisplayTimer(): void {
+    if (this.timeoutHandle) {
+      clearTimeout(this.timeoutHandle)
+      this.timeoutHandle = undefined
+    }
+
+    this.display()
+  }
+}
+
+/**
+ * Download the cache using the Actions toolkit http-client
+ *
+ * @param archiveLocation the URL for the cache
+ * @param archivePath the local path where the cache is saved
+ */
+export async function downloadCacheHttpClient(
+  archiveLocation: string,
+  archivePath: string
+): Promise<void> {
+  const writeStream = fs.createWriteStream(archivePath)
+  const httpClient = new HttpClient('actions/cache')
+  const downloadResponse = await retryHttpClientResponse(
+    'downloadCache',
+    async () => httpClient.get(archiveLocation)
+  )
+
+  // Abort download if no traffic received over the socket.
+  downloadResponse.message.socket.setTimeout(SocketTimeout, () => {
+    downloadResponse.message.destroy()
+    core.debug(`Aborting download, socket timed out after ${SocketTimeout} ms`)
+  })
+
+  await pipeResponseToStream(downloadResponse, writeStream)
+
+  // Validate download size.
+  const contentLengthHeader = downloadResponse.message.headers['content-length']
+
+  if (contentLengthHeader) {
+    const expectedLength = parseInt(contentLengthHeader)
+    const actualLength = utils.getArchiveFileSizeInBytes(archivePath)
+
+    if (actualLength !== expectedLength) {
+      throw new Error(
+        `Incomplete download. Expected file size: ${expectedLength}, actual file size: ${actualLength}`
+      )
+    }
+  } else {
+    core.debug('Unable to validate download, no Content-Length header')
+  }
+}
+
+/**
+ * Download the cache using the Azure Storage SDK.  Only call this method if the
+ * URL points to an Azure Storage endpoint.
+ *
+ * @param archiveLocation the URL for the cache
+ * @param archivePath the local path where the cache is saved
+ * @param options the download options with the defaults set
+ */
+export async function downloadCacheStorageSDK(
+  archiveLocation: string,
+  archivePath: string,
+  options: DownloadOptions
+): Promise<void> {
+  const client = new BlockBlobClient(archiveLocation, undefined, {
+    retryOptions: {
+      // Override the timeout used when downloading each 4 MB chunk
+      // The default is 2 min / MB, which is way too slow
+      tryTimeoutInMs: options.timeoutInMs
+    }
+  })
+
+  const properties = await client.getProperties()
+  const contentLength = properties.contentLength ?? -1
+
+  if (contentLength < 0) {
+    // We should never hit this condition, but just in case fall back to downloading the
+    // file as one large stream
+    core.debug(
+      'Unable to determine content length, downloading file with http-client...'
+    )
+
+    await downloadCacheHttpClient(archiveLocation, archivePath)
+  } else {
+    // Use downloadToBuffer for faster downloads, since internally it splits the
+    // file into 4 MB chunks which can then be parallelized and retried independently
+    //
+    // If the file exceeds the buffer maximum length (~1 GB on 32-bit systems and ~2 GB
+    // on 64-bit systems), split the download into multiple segments
+    const maxSegmentSize = buffer.constants.MAX_LENGTH
+    const downloadProgress = new DownloadProgress(contentLength)
+
+    const fd = fs.openSync(archivePath, 'w')
+
+    try {
+      downloadProgress.startDisplayTimer()
+
+      while (!downloadProgress.isDone()) {
+        const segmentStart =
+          downloadProgress.segmentOffset + downloadProgress.segmentSize
+
+        const segmentSize = Math.min(
+          maxSegmentSize,
+          contentLength - segmentStart
+        )
+
+        downloadProgress.nextSegment(segmentSize)
+
+        const result = await client.downloadToBuffer(
+          segmentStart,
+          segmentSize,
+          {
+            concurrency: options.downloadConcurrency,
+            onProgress: downloadProgress.onProgress()
+          }
+        )
+
+        fs.writeFileSync(fd, result)
+      }
+    } finally {
+      downloadProgress.stopDisplayTimer()
+      fs.closeSync(fd)
+    }
+  }
+}