@taskcluster/client-web 91.1.1 → 92.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taskcluster/client-web",
-  "version": "91.1.1",
+  "version": "92.0.1",
   "main": "src/index.js",
   "author": "Eli Perelman <eli@eliperelman.com>",
   "license": "MPL-2.0",
@@ -13,12 +13,12 @@
     "test": "NODE_OPTIONS=--openssl-legacy-provider karma start --single-run"
   },
   "devDependencies": {
-    "@babel/core": "^7.28.4",
+    "@babel/core": "^7.28.5",
     "chai": "^4.3.10",
     "chai-as-promised": "^8.0.2",
     "crypto-js": "^4.2.0",
     "dotenv": "^16.5.0",
-    "eslint": "^9.36.0",
+    "eslint": "^9.39.0",
     "karma": "^6.4.4",
     "karma-cli": "^2.0.0",
     "karma-coverage": "^2.2.1",

package/src/clients/Queue.js

@@ -458,13 +458,44 @@ export default class Queue extends Client {
   // browser, without using Taskcluster credentials, include a scope in the
   // `anonymous` role.  The convention is to include
   // `queue:get-artifact:public/*`.
-  // **API Clients**, this method will redirect you to the artifact, if it is
-  // stored externally. Either way, the response may not be JSON. So API
-  // client users might want to generate a signed URL for this end-point and
-  // use that URL with a normal HTTP client.
+  // **Response**: the HTTP response to this method is a 303 redirect to the
+  // URL from which the artifact can be downloaded.  The body of that response
+  // contains the data described in the output schema, contianing the same URL.
+  // Callers are encouraged to use whichever method of gathering the URL is
+  // most convenient.  Standard HTTP clients will follow the redirect, while
+  // API client libraries will return the JSON body.
+  // In order to download an artifact the following must be done:
+  // 1. Obtain queue url.  Building a signed url with a taskcluster client is
+  // recommended
+  // 1. Make a GET request which does not follow redirects
+  // 1. In all cases, if specified, the
+  // x-taskcluster-location-{content,transfer}-{sha256,length} values must be
+  // validated to be equal to the Content-Length and Sha256 checksum of the
+  // final artifact downloaded. as well as any intermediate redirects
+  // 1. If this response is a 500-series error, retry using an exponential
+  // backoff.  No more than 5 retries should be attempted
+  // 1. If this response is a 400-series error, treat it appropriately for
+  // your context.  This might be an error in responding to this request or
+  // an Error storage type body.  This request should not be retried.
+  // 1. If this response is a 200-series response, the response body is the artifact.
+  // If the x-taskcluster-location-{content,transfer}-{sha256,length} and
+  // x-taskcluster-location-content-encoding are specified, they should match
+  // this response body
+  // 1. If the response type is a 300-series redirect, the artifact will be at the
+  // location specified by the `Location` header.  There are multiple artifact storage
+  // types which use a 300-series redirect.
+  // 1. For all redirects followed, the user must verify that the content-sha256, content-length,
+  // transfer-sha256, transfer-length and content-encoding match every further request.  The final
+  // artifact must also be validated against the values specified in the original queue response
+  // 1. Caching of requests with an x-taskcluster-artifact-storage-type value of `reference`
+  // must not occur
+  // **Headers**
+  // The following important headers are set on the response to this method:
+  // * location: the url of the artifact if a redirect is to be performed
+  // * x-taskcluster-artifact-storage-type: the storage type.  Example: s3
   // **Remark**, this end-point is slightly slower than
   // `queue.getArtifact`, so consider that if you already know the `runId` of
-  // the latest run. Otherwise, just us the most convenient API end-point.
+  // the latest run. Otherwise, just use the most convenient API end-point.
   /* eslint-enable max-len */
   getLatestArtifact(...args) {
     this.validate(this.getLatestArtifact.entry, args);