chore(main): release 3.25.0 (#1017)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: guybedford <[email protected]>

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 3.25.0 (2024-10-22)
+
+### Added
+
+* support backend property on both Request and Response, as a Backend instance ([#1019](https://github.com/fastly/js-compute-runtime/issues/1019)) ([4e3b93d](https://github.com/fastly/js-compute-runtime/commit/4e3b93d9de1f0af9eed7c900eedb8a509d7723da))
+
+### Fixed
+
+* set SSL properly for created dynamic backends ([#1016](https://github.com/fastly/js-compute-runtime/issues/1016)) ([616e898](https://github.com/fastly/js-compute-runtime/commit/616e89827087623b8180665591127143532dc309))
+
 ## 3.24.3 (2024-10-16)
 
 ### Fixed

documentation/versioned_docs/version-3.25.0/backend/Backend/Backend.mdx

@@ -0,0 +1,188 @@
+---
+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 Fastly Compute service.
+
+>**Note**: Dynamic backends are by default disabled at the Fastly service level. Contact [Fastly Support](https://support.fastly.com/hc/en-us/requests/new?ticket_form_id=360000269711) to request dynamic backends on Fastly Services.
+
+To disable the usage of dynamic backends, see [enforceExplicitBackends](../enforceExplicitBackends.mdx).
+
+## 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.
+    - `clientCertificate` _: object_ _**optional**_
+      - The client certificate to provide for the TLS handshake
+      - `certificate` _: string_
+        - The PEM certificate string.
+      - `key` _: SecretStoreEntry_
+        - The `SecretStoreEntry` to use for the key, created via [`SecretStore.prototype.get`](../../fastly:secret-store/SecretStore/prototype/get.mdx) or alteratively via [`SecretStore.fromBytes`](../../fastly:secret-store/SecretStore/fromBytes.mdx).
+    - `httpKeepalive` _: number_ _**optional**_
+      - Enable HTTP keepalive, setting the timout in milliseconds.
+    - `tcpKeepalive` _: boolean | object_ _**optional**_
+      - Enable TCP keepalive. When an object, optionally setting the keepalive configuration options.
+      - `timeSecs` _: number_ _**optional**_
+        - Configure how long to wait after the last sent data over the TCP connection before starting to send TCP keepalive probes.
+      - `intervalSecs` _: number_ _**optional**_
+        - Configure how long to wait between each TCP keepalive probe sent to the backend to determine if it is still active.
+      - `probes` _: number_ _**optional**_
+        - Number of probes to send to the backend before it is considered dead.
+    - `grpc` _: boolean_ _**optional**_
+      - **_Experimental feature_**
+      - When enabled, sets that this backend is to be used for gRPC traffic. 
+      - _Warning: When using this experimental feature, no guarantees are provided for behaviours for backends that do not provide gRPC traffic._
+
+All optional generic options can have their defaults set via [`setDefaultDynamicBackendConfig()`](../setDefaultDynamicBackendConfig.mdx).
+
+This includes all configuration options above except for `name`, `target`, `hostOverride`, `sniHostname` and `grpc`.
+
+### Return value
+
+A new `Backend` object.
+
+## Examples
+
+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 { Backend } from "fastly:backend";
+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,
+    tlsMinVersion: 1.3,
+    tlsMaxVersion: 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 { Backend } from "fastly:backend";
+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,
+    tlsMinVersion: 1.3,
+    tlsMaxVersion: 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>

documentation/versioned_docs/version-3.25.0/backend/Backend/exists.mdx

@@ -0,0 +1,20 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# Backend.exists()
+
+The **`Backend.exists()`** method returns a boolean indicating if a Backend with the given name exists or not.
+
+## Syntax
+
+```js
+exists(name)
+```
+
+### Return value
+
+A boolean indicating if a Backend with the given name exists or not.

documentation/versioned_docs/version-3.25.0/backend/Backend/fromName.mdx

@@ -0,0 +1,20 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# Backend.fromName()
+
+Returns the `Backend` instance with the given name, if one exists. If one does not exist, an error is thrown.
+
+## Syntax
+
+```js
+fromName(name)
+```
+
+### Return value
+
+A `Backend` instance.

documentation/versioned_docs/version-3.25.0/backend/Backend/health.mdx

@@ -0,0 +1,31 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# Backend.health()
+
+:::info
+
+This method is deprecated, use [`Backend.prototype.health`](./prototype/health.mdx) instead.
+
+:::
+
+The **`Backend.health()`** method returns a string representing the health of the given Backend instance.
+
+## Syntax
+
+```js
+Backend.health(backend)
+```
+
+### Return value
+
+A string representing the health of the specified Backend value.
+
+Possible values are:
+- `"healthy"` - The backend's health check has succeeded, indicating the backend is working as expected and should receive requests.
+- `"unhealthy"` - The backend's health check has failed, indicating the backend is not working as expected and should not receive requests.
+- `"unknown"` - The backend does not have a health check configured.

documentation/versioned_docs/version-3.25.0/backend/Backend/prototype/betweenBytesTimeout.mdx

@@ -0,0 +1,18 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# Backend.betweenBytesTimeout
+
+The read-only **`betweenBytesTimeout`** property of a `Backend` instance is an integer number
+providing the between bytes timeout for this backend in milliseconds.
+
+When not set or in environments that do not support this property (such as Viceroy), `null`
+may be returned.
+
+## Value
+
+A `number` or `null`.

documentation/versioned_docs/version-3.25.0/backend/Backend/prototype/connectTimeout.mdx

@@ -0,0 +1,18 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# Backend.connectTimeout
+
+The read-only **`connectTimeout`** property of a `Backend` instance is an integer number
+providing the connect timeout for this backend in milliseconds.
+
+When not set or in environments that do not support this property (such as Viceroy), `null`
+may be returned.
+
+## Value
+
+A `number` or `null`.

documentation/versioned_docs/version-3.25.0/backend/Backend/prototype/firstByteTimeout.mdx

@@ -0,0 +1,18 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# Backend.firstByteTimeout
+
+The read-only **`firstByteTimeout`** property of a `Backend` instance is an integer number
+providing the first byte timeout for this backend in milliseconds.
+
+When not set or in environments that do not support this property (such as Viceroy), `null`
+may be returned.
+
+## Value
+
+A `number` or `null`.

documentation/versioned_docs/version-3.25.0/backend/Backend/prototype/health.mdx

@@ -0,0 +1,25 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# Backend.prototype.health()
+
+The **`Backend.prototype.health()`** method returns a string representing the health of the given Backend instance.
+
+## Syntax
+
+```js
+health()
+```
+
+### Return value
+
+A string representing the health of the specified Backend value.
+
+Possible values are:
+- `"healthy"` - The backend's health check has succeeded, indicating the backend is working as expected and should receive requests.
+- `"unhealthy"` - The backend's health check has failed, indicating the backend is not working as expected and should not receive requests.
+- `"unknown"` - The backend does not have a health check configured.

documentation/versioned_docs/version-3.25.0/backend/Backend/prototype/hostOverride.mdx

@@ -0,0 +1,15 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# Backend.hostOverride
+
+The read-only **`hostOverride`** property of a `Backend` instance is the host header
+override string used when sending requests to this backend.
+
+## Value
+
+A `string`.

documentation/versioned_docs/version-3.25.0/backend/Backend/prototype/httpKeepaliveTime.mdx

@@ -0,0 +1,15 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# Backend.httpKeepaliveTime
+
+The read-only **`httpKeepaliveTime`** property of a `Backend` instance is the HTTP keepalive
+time for this backend in milliseconds, or 0 if no keepalive is set.
+
+## Value
+
+A `number`.