chore(main): release 3.4.0 (#658)

Co-authored-by: JakeChampion <[email protected]>
fastly · Sep 13, 2023 · 76a647c · 76a647c
1 parent c16b001
commit 76a647c
Show file tree

Hide file tree

Showing 635 changed files with 23,704 additions and 1 deletion.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,13 @@
 # Changelog
 
 
+## 3.4.0 (2023-09-13)
+
+
+### Added
+
+* add ability to import ECDSA JWK keys via crypto.subtle.importKey ([#639](https://github.com/fastly/js-compute-runtime/issues/639)) ([c16b001](https://github.com/fastly/js-compute-runtime/commit/c16b001bddc2dc122c26837023ab9c53664adf8a))
+
 ## 3.3.5 (2023-09-11)
 
 

diff --git a/documentation/docs/globals/EcdsaParams/EcdsaParams.mdx b/documentation/docs/globals/EcdsaParams/EcdsaParams.mdx
@@ -0,0 +1,24 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# EcdsaParams
+
+The **`EcdsaParams`** dictionary represents the object that should be passed as the `algorithm` parameter into `SubtleCrypto.sign()` or `SubtleCrypto.verify()` when using the ECDSA algorithm.
+
+## Instance properties
+
+- `name`
+    - : A string. This should be set to `ECDSA`.
+- `hash`
+
+    - : A string. An identifier for the digest algorithm to use. This should be one of the following:
+
+        - `SHA-256`: selects the SHA-256 algorithm.
+        - `SHA-384`: selects the SHA-384 algorithm.
+        - `SHA-512`: selects the SHA-512 algorithm.
+
+        > **Warning:** `SHA-1` is also supported here but the SHA-1 algorithm is considered vulnerable and should no longer be used.
diff --git a/documentation/docs/globals/SubtleCrypto/prototype/importKey.mdx b/documentation/docs/globals/SubtleCrypto/prototype/importKey.mdx
@@ -33,6 +33,8 @@ importKey(format, keyData, algorithm, extractable, keyUsages)
       Pass an [`RsaHashedImportParams`](../../RsaHashedImportParams/RsaHashedImportParams.mdx) object.
     - For HMAC:
       Pass an [`HmacImportParams`](../../HmacImportParams/HmacImportParams.mdx) object.
+    - For ECDSA:
+      Pass an [`EcKeyImportParams`](../../EcKeyImportParams/EcKeyImportParams.mdx) object.
 - `extractable`
   - : A boolean value indicating whether it will be possible to export the key.
 - `keyUsages`

diff --git a/documentation/versioned_docs/version-3.4.0/fastly:backend/Backend/Backend.mdx b/documentation/versioned_docs/version-3.4.0/fastly:backend/Backend/Backend.mdx
@@ -0,0 +1,227 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+import {Fiddle} from '@site/src/components/fiddle';
+
+# `Backend()`
+
+The **`Backend` constructor** lets you dynamically create new [Fastly Backends](https://developer.fastly.com/reference/api/services/backend/) for your Compute@Edge service.
+
+Dynamically creating new [Fastly Backends](https://developer.fastly.com/reference/api/services/backend/) is disabled by default for Fastly Services. Please contact [Fastly Support](https://support.fastly.com/hc/requests/new?ticket_form_id=360000269711) to request the feature be enabled on the Fastly Services which require Dynamic Backends.
+
+By default, Dynamic Backends are disabled within a JavaScript application as it can be a potential avenue for third-party JavaScript code to send requests, potentially including sensitive/secret data, off to destinations that the JavaScript project was not intending, which could be a security issue.
+
+To enable Dynamic Backends the application will need to explicitly allow Dynamic Backends via:
+
+```js
+import { allowDynamicBackends } from "fastly:experimental";
+allowDynamicBackends(true);
+```
+
+**Note**: Can only be used when processing requests, not during build-time initialization.
+
+## Syntax
+
+```js
+new Backend(backendConfiguration)
+```
+
+> **Note:** `Backend()` can only be constructed with `new`. Attempting to call it without `new` throws a [`TypeError`](../../globals/TypeError/TypeError.mdx).
+
+### Parameters
+
+- `backendConfiguration`
+
+  - : An Object which contains all the configuration options to apply to the newly created Backend.
+
+    - `name` _: string_
+      - The name of the backend.
+      - The name has to be between 1 and 254 characters inclusive.
+      - The name can be whatever you would like, as long as it does not match the name of any of the static service backends nor match any other dynamic backends built during a single execution of the application.
+      - Throws a [`TypeError`](../../globals/TypeError/TypeError.mdx) if the value is not valid. I.E. The value is null, undefined, an empty string or a string with more than 254 characters.
+    - `target` _: string_
+      - A hostname, IPv4, or IPv6 address for the backend as well as an optional port.
+      - The target has to be at-least 1 character.
+      - Throws a [`TypeError`](../../globals/TypeError/TypeError.mdx) if the value is not valid. I.E. Is null, undefined, an empty string, not a valid IP address or host, or is the string `::`
+    - `hostOverride` _: string_ _**optional**_
+      - If set, will force the HTTP Host header on connections to this backend to be the supplied value.
+      - Throws a [`TypeError`](../../globals/TypeError/TypeError.mdx) if the value is an empty string.
+    - `connectTimeout` _: number_ _**optional**_
+      - Maximum duration in milliseconds to wait for a connection to this backend to be established.
+      - If exceeded, the connection is aborted and a 503 response will be presented instead.
+      - Throws a [`RangeError`](../../globals/RangeError/RangeError.mdx) if the value is negative or greater than or equal to 2^32
+    - `firstByteTimeout` _: number_ _**optional**_
+      - Maximum duration in milliseconds to wait for the server response to begin after a TCP connection is established and the request has been sent.
+      - If exceeded, the connection is aborted and a 503 response will be presented instead.
+      - Throws a [`RangeError`](../../globals/RangeError/RangeError.mdx) if the value is negative or greater than or equal to 2^32
+    - `betweenBytesTimeout` _: number_ _**optional**_
+      - Maximum duration in milliseconds that Fastly will wait while receiving no data on a download from a backend.
+      - If exceeded, the response received so far will be considered complete and the fetch will end.
+      - Throws a [`RangeError`](../../globals/RangeError/RangeError.mdx) if the value is negative or greater than or equal to 2^32
+    - `useSSL` _: boolean_ _**optional**_
+      - Whether or not to require TLS for connections to this backend.
+    - `dontPool` _: boolean_ _**optional**_
+      - Determine whether or not connections to the same backend should be pooled across different sessions.
+      - Fastly considers two backends “the same” if they're registered with the same name and the exact same settings.
+      - In those cases, when pooling is enabled, if Session 1 opens a connection to this backend it will be left open, and can be re-used by Session 2.
+      - This can help improve backend latency, by removing the need for the initial network / TLS handshake(s).
+      - By default, pooling is enabled for dynamic backends.
+    - `tlsMinVersion` _: 1 | 1.1 | 1.2 | 1.3_ _**optional**_
+      - Minimum allowed TLS version on SSL connections to this backend.
+      - If the backend server is not able to negotiate a connection meeting this constraint, a 503 response will be presented instead.
+      - Throws a [`RangeError`](../../globals/RangeError/RangeError.mdx) if the value is not 1, 1.1, 1.2, or 1.3
+    - `tlsMaxVersion` _: 1 | 1.1 | 1.2 | 1.3_ _**optional**_
+      - Maximum allowed TLS version on SSL connections to this backend.
+      - If the backend server is not able to negotiate a connection meeting this constraint, a 503 response will be presented instead.
+      - Throws a [`RangeError`](../../globals/RangeError/RangeError.mdx) if the value is not 1, 1.1, 1.2, or 1.3
+    - `certificateHostname` _: string_ _**optional**_
+      - Define the hostname that the server certificate should declare.
+      - Throws a [`TypeError`](../../globals/TypeError/TypeError.mdx) if the value is an empty string.
+    - `caCertificate` _: string_ _**optional**_
+      - The CA certificate to use when checking the validity of the backend.
+      - Throws a [`TypeError`](../../globals/TypeError/TypeError.mdx) if the value is an empty string.
+    - `ciphers` _: string_ _**optional**_
+      - List of OpenSSL ciphers to support for connections to this origin.
+      - If the backend server is not able to negotiate a connection meeting this constraint, a 503 response will be presented instead.
+      - [List of ciphers supported by Fastly](https://developer.fastly.com/learning/concepts/routing-traffic-to-fastly/#use-a-tls-configuration).
+      - Throws a [`TypeError`](../../globals/TypeError/TypeError.mdx) if the value is an empty string.
+    - `sniHostname` _: string_ _**optional**_
+      - The SNI hostname to use on connections to this backend.
+      - Throws a [`TypeError`](../../globals/TypeError/TypeError.mdx) if the value is an empty string.
+
+### Return value
+
+A new `Backend` object.
+
+## Examples
+
+In this example an implicit Dynamic Backend is created when making the fetch request to <https://www.fastly.com/> and the response is then returned to the client.
+<Fiddle config={{
+  "type": "javascript",
+  "title": "Implicit Dynamic Backend Example",
+  "origins": [
+    "https://http-me.glitch.me"
+  ],
+  "src": {
+    "deps": "{\n  \"@fastly/js-compute\": \"^1.0.1\"\n}",
+    "main": `
+/// <reference types="@fastly/js-compute" />
+import { allowDynamicBackends } from "fastly:experimental";
+allowDynamicBackends(true);
+async function app() {
+  // For any request, return the fastly homepage -- without defining a backend!
+  return fetch('https://www.fastly.com/');
+}
+addEventListener("fetch", event => event.respondWith(app(event)));
+`
+  },
+  "requests": [
+    {
+      "enableCluster": true,
+      "enableShield": false,
+      "enableWAF": false,
+      "method": "GET",
+      "path": "/status=200",
+      "useFreshCache": false,
+      "followRedirects": false,
+      "tests": "",
+      "delay": 0
+    }
+  ],
+  "srcVersion": 1
+}}>
+
+```js
+/// <reference types="@fastly/js-compute" />
+import { allowDynamicBackends } from "fastly:experimental";
+allowDynamicBackends(true);
+async function app() {
+  // For any request, return the fastly homepage -- without defining a backend!
+  return fetch('https://www.fastly.com/');
+}
+addEventListener("fetch", event => event.respondWith(app(event)));
+```
+
+</Fiddle>
+
+In this example an explicit Dynamic Backend is created and supplied to the fetch request, the response is then returned to the client.
+
+
+<Fiddle config={{
+  "type": "javascript",
+  "title": "Explicit Dynamic Backend Example",
+  "origins": [
+    "https://http-me.glitch.me"
+  ],
+  "src": {
+    "deps": "{\n  \"@fastly/js-compute\": \"^1.0.1\"\n}",
+    "main": `
+/// <reference types="@fastly/js-compute" />
+import { allowDynamicBackends } from "fastly:experimental";
+import { Backend } from "fastly:backend";
+allowDynamicBackends(true);
+async function app() {
+  // For any request, return the fastly homepage -- without defining a backend!
+  const backend = new Backend({
+    name: 'fastly',
+    target: 'fastly.com',
+    hostOverride: "www.fastly.com",
+    connectTimeout: 1000,
+    firstByteTimeout: 15000,
+    betweenBytesTimeout: 10000,
+    useSSL: true,
+    sslMinVersion: 1.3,
+    sslMaxVersion: 1.3,
+  });
+  return fetch('https://www.fastly.com/', {
+    backend // Here we are configuring this request to use the backend from above.
+  });
+}
+addEventListener("fetch", event => event.respondWith(app(event)));
+`
+  },
+  "requests": [
+    {
+      "enableCluster": true,
+      "enableShield": false,
+      "enableWAF": false,
+      "method": "GET",
+      "path": "/status=200",
+      "useFreshCache": false,
+      "followRedirects": false,
+      "tests": "",
+      "delay": 0
+    }
+  ],
+  "srcVersion": 1
+}}>
+
+```js
+/// <reference types="@fastly/js-compute" />
+import { allowDynamicBackends } from "fastly:experimental";
+import { Backend } from "fastly:backend";
+allowDynamicBackends(true);
+async function app() {
+  // For any request, return the fastly homepage -- without defining a backend!
+  const backend = new Backend({
+    name: 'fastly',
+    target: 'fastly.com',
+    hostOverride: "www.fastly.com",
+    connectTimeout: 1000,
+    firstByteTimeout: 15000,
+    betweenBytesTimeout: 10000,
+    useSSL: true,
+    sslMinVersion: 1.3,
+    sslMaxVersion: 1.3,
+  });
+  return fetch('https://www.fastly.com/', {
+    backend // Here we are configuring this request to use the backend from above.
+  });
+}
+addEventListener("fetch", event => event.respondWith(app(event)));
+```
+
+</Fiddle>
diff --git a/...tion/versioned_docs/version-3.4.0/fastly:backend/Backend/prototype/toString.mdx b/...tion/versioned_docs/version-3.4.0/fastly:backend/Backend/prototype/toString.mdx
@@ -0,0 +1,87 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+import {Fiddle} from '@site/src/components/fiddle';
+
+# toString
+
+The **`toString()`** method returns a string representing the specified Backend value.
+
+## Syntax
+
+```js
+toString()
+```
+
+### Return value
+
+A string representing the specified Backend value.
+
+## Description
+
+The [Backend](../Backend.mdx) object overrides the `toString()` method of [Object](../../../globals//Object/Object.mdx); it does not inherit
+[`Object.prototype.toString()`](../../../globals/Object/prototype/toString.mdx). For [Backend](../Backend.mdx) values, the `toString` method returns the name given to the [Backend](../Backend.mdx) object during construction.
+
+The `toString()` method requires its `this` value to be a [Backend](../Backend.mdx) object.
+
+If the `this` value does not inherit from `Backend.prototype`, a [TypeError](../../../globals/TypeError/TypeError.mdx) is thrown.
+
+## Examples
+
+### Using toString()
+
+The following example logs the string value of a [Backend](../Backend.mdx) object:
+
+<Fiddle config={{
+  "type": "javascript",
+  "title": "Backend.prototype.toString Example",
+  "origins": [
+    "https://http-me.glitch.me"
+  ],
+  "src": {
+    "deps": "{\n  \"@fastly/js-compute\": \"^1.0.1\"\n}",
+    "main": `
+/// <reference types=\"@fastly/js-compute\" />
+import { Backend } from "fastly:backend";
+async function app() {
+  const backend = new Backend({
+    name: "fastly",
+    target: "fastly.com",
+  });
+  console.log(backend.toString()); // "fastly"
+}
+addEventListener("fetch", event => event.respondWith(app(event)));
+`
+  },
+  "requests": [
+    {
+      "enableCluster": true,
+      "enableShield": false,
+      "enableWAF": false,
+      "method": "GET",
+      "path": "/status=200",
+      "useFreshCache": false,
+      "followRedirects": false,
+      "tests": "",
+      "delay": 0
+    }
+  ],
+  "srcVersion": 1
+}}>
+
+```js
+import { Backend } from "fastly:backend";
+async function app() {
+  const backend = new Backend({
+    name: "fastly",
+    target: "fastly.com",
+  });
+  console.log(backend.toString()); // "fastly"
+}
+addEventListener("fetch", event => event.respondWith(app(event)));
+```
+
+</Fiddle>