@amazon/vinyl-util 1.0.0

package/docs/NETWORKING.md

@@ -0,0 +1,161 @@
+# Networking
+
+The Amazon Vinyl Networking layer is an enhanced wrapper around a Fetch
+implementation (such as `fetch` or `node-fetch`) that offers several advanced
+features:
+
+- Implements exponential back-off on client requests when a service fails,
+  reducing the risk of prolonged traffic surges.
+- Automatically retries specific types of failures, addressing potential
+  transient service issues.
+
+- Standardizes abort and timeout behavior across all network requests.
+- Collects and provides detailed networking metrics, including service failure
+  rates and data transfer speeds.
+
+## Usage
+
+The API is similar to `fetch`, with a couple key differences.
+
+- Responses with a !ok status will reject, not resolve.
+- An optional third parameter can be provided with Requester configuration such
+  as setting a service id or an Abort controller (note that `signal` is not
+  supported). Service ids may be any string that identifies the service for
+  metrics and backoff.
+
+```typescript
+import { Abort, requesterWithRetryRef } from '@amazon/vinyl-util'
+
+const abort = new Abort()
+const response = await requestWithRetry(
+    'https://example.com',
+    {
+        method: 'POST',
+        headers: {
+            exampleHeader: 'value',
+        },
+        body: JSON.stringify(requestWithRetry),
+    },
+    {
+        serviceId: 'example.com',
+        abort,
+    }
+)
+```
+
+In most cases, `requesterWithRetryRef` should be used, which uses a client set
+to reasonable defaults for retry policies, backoff distribution, retryable
+status codes, etc.
+
+`requesterWithRetryRef` is configured to use a single retry when the response
+code is one of:
+
+```
+429, // Too many requests
+503, // Service unavailable
+504, // Gateway timeout
+```
+
+The backoff time is a clamped exponential backoff with a randomized jitter.
+Backoff applies only when a service id is set.
+
+In advanced cases a new `RequesterImpl` may be created.
+
+```typescript
+const requester = new RequesterImpl({
+    networkMetricsController: networkMetricsControllerRef.value,
+    networkState: networkStateRef.value,
+    fetch: nativeFetchRef.value,
+})
+requester.configure({
+    retryOptions: RetryStrategy.ONE_RETRY,
+    timeout: 90,
+})
+networkLoggingHandler(requester)
+```
+
+## Control Flow
+
+```
+                                +-------------+
+                                |   fetch     |
+                                +-------------+
+                                       |
+                                       v
+                               +------------------------+
+                               | emit requestWithRetry  |
+                               +-------+----------------+
+                                       |
+                                       v
+                                     +---+
++----------------------------------> |try|
+|                                    +---+
+|                                      |
+|                            < retry-after marked? >
+|                                      |
+|                    +------ no -------+------- yes -------+
+|                    |                                     |
+|                    v                                     v
+|       +-----------------------------+       +-----------------------------+
+|       | sleep until backOff         |       | sleep until retry-after +   |
+|       |                             |       | jitter                      |
+|       +-------------+---------------+       +-------------+---------------+
+|                     |                                     |
+|                     |-------------------------------------+
+|                     v
+|            +------------------------+
+|            | emit fetchAttemptStart |
+|            +----------+-------------+
+|                      |
+|                      v
+|                  +----------------+
+|                  | window.fetch() |
+|                  +--------+-------+
+|                           |
+|                 < response received? >
+|                           |
+|                           v
+|                    +- no ------------------ yes ---------+
+|                    |                                     |
+|               < aborted? >                        < ok response? >
+|                    |                                     |
+|                    v                                     v
+|       +-- no -------- yes ---+                  +- no ------ yes -----------+
+|       |                      |                  |                           |
+|       v                      v                  v                           v
+| +--------------+        +--------------+     +---------------+         +--------------+
+| |lastResult =  |        |lastResult =  |     |lastResult =   |         |lastResult =  |
+| |network error |        |abort error   |     |response error |         |success       |
+| +--------------+        +--------------+     +---------------+         +--------------+
+|                                                     |                              |
+|                                                     |--set retry-after             |
+|                                           < status is retryable? >                 |
+|                                                     |                              |
+|                           +--------------yes--------+---------no----+              |
+|                           |                                         |              |
+|                   < was last retry? >                               |              |
+|                           |                                         |              |
+|               (last try will be true if                             |              |
+|                retry count is reached or                            |              |
+|                failure count for the service                        |              |
+|                reaches retryFailureCutoff)                          |              |
+|                           |                                         |              |
+|          +--- no ---------+---------- yes ---+                      |              |
+|          |                                   |                      |              |
+|          v                                   v  v-------------------+              v
+|      +-------+                           +------+                                +----+
++----- | retry |                           | fail |                                | ok |
+       +-------+                           +------+                                +----+
+           |                                   |                                      |     +------------------------+
+           +-----------------------------------+->------------------------------------+->-->| Network metrics update |
+                                               |                                      |     +------------------------+
+                                               v      v-------------------------------+
+                                     +--------------------+
+                                     | emit fetchComplete |
+                                     +--------------------+
+                                               |
+                                               v
+                                           +--------+
+                                           | settle |
+                                           +--------|
+```

package/package.json

@@ -0,0 +1,118 @@
+{
+    "name": "@amazon/vinyl-util",
+    "version": "1.0.0",
+    "description": "Standard utilities for browser and node.",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/amazonmusic/vinyl.git"
+    },
+    "license": "UNLICENSED",
+    "module": "./dist/index.js",
+    "main": "./dist/index.cjs",
+    "types": "./dist/types/ts3.7/index.d.ts",
+    "type": "module",
+    "sideEffects": [
+        "**/polyfill/**",
+        "test/**/*"
+    ],
+    "files": [
+        "dist/*",
+        "docs/*"
+    ],
+    "typesVersions": {
+        ">=5.4": {
+            "*": [
+                "./dist/types/current/index.d.ts"
+            ],
+            "testUtil": [
+                "./dist/testUtil/types/current/index.d.ts"
+            ],
+            "browserTestUtil": [
+                "./dist/browserTestUtil/types/current/index.d.ts"
+            ]
+        },
+        ">=4.7": {
+            "*": [
+                "./dist/types/ts4.7/index.d.ts"
+            ],
+            "testUtil": [
+                "./dist/testUtil/types/ts4.7/index.d.ts"
+            ],
+            "browserTestUtil": [
+                "./dist/browserTestUtil/types/ts4.7/index.d.ts"
+            ]
+        },
+        ">=4.1": {
+            "*": [
+                "./dist/types/ts4.1/index.d.ts"
+            ],
+            "testUtil": [
+                "./dist/testUtil/types/ts4.1/index.d.ts"
+            ],
+            "browserTestUtil": [
+                "./dist/browserTestUtil/types/ts4.1/index.d.ts"
+            ]
+        },
+        ">=3.7": {
+            "*": [
+                "./dist/types/ts3.7/index.d.ts"
+            ],
+            "testUtil": [
+                "./dist/testUtil/types/ts3.7/index.d.ts"
+            ],
+            "browserTestUtil": [
+                "./dist/browserTestUtil/types/ts3.7/index.d.ts"
+            ]
+        }
+    },
+    "exports": {
+        ".": {
+            "types@>=5.4": "./dist/types/current/index.d.ts",
+            "types@>=4.7": "./dist/types/ts4.7/index.d.ts",
+            "require": "./dist/index.cjs",
+            "import": "./dist/index.js"
+        },
+        "./testUtil": {
+            "types@>=5.4": "./dist/testUtil/types/current/index.d.ts",
+            "types@>=4.7": "./dist/testUtil/types/ts4.7/index.d.ts",
+            "import": "./dist/testUtil/index.js"
+        },
+        "./polyfill": {
+            "import": "./dist/polyfill/index.js"
+        },
+        "./browserTestUtil": {
+            "types@>=5.4": "./dist/browserTestUtil/types/current/index.d.ts",
+            "types@>=4.7": "./dist/browserTestUtil/types/ts4.7/index.d.ts",
+            "import": "./dist/browserTestUtil/index.js"
+        }
+    },
+    "scripts": {
+        "analyzeExports": "tsx buildSrc/analyzeExports.ts",
+        "analyzeExports:write": "tsx buildSrc/analyzeExports.ts --write",
+        "clean": "rimraf --glob dist .eslintcache \"**/*.tsbuildinfo\"",
+        "indexFiles:check": "tsx buildSrc/writeIndexFiles.ts --check",
+        "indexFiles:write": "tsx buildSrc/writeIndexFiles.ts",
+        "generateDomMocks": "tsx buildSrc/generateDomMocks.ts && npm run prettier:write",
+        "build": "tsx buildSrc/build.ts",
+        "build:release": "tsx buildSrc/build.ts --release",
+        "prettier:check": "prettier . --ignore-path ../../.prettierignore --cache --check",
+        "prettier:write": "prettier . --ignore-path ../../.prettierignore --cache --write",
+        "eslint:check": "eslint . --cache --max-warnings=0",
+        "eslint:write": "eslint . --cache --fix",
+        "lint": "npm run indexFiles:check && npm run eslint:check && npm run prettier:check",
+        "lint:write": "npm run indexFiles:write && npm run eslint:write && npm run prettier:write",
+        "validate": "tsc --project test/unit && npm run lint && npm run test",
+        "test": "tsx --tsconfig ../../tsconfig.flat.json ../../node_modules/jasmine/bin/jasmine --config=test/unit/jasmine.config.json",
+        "test:coverage": "c8 npm run test",
+        "watch": "tsx buildSrc/build.ts --watch",
+        "watch:release": "tsx buildSrc/build.ts --watch --release"
+    },
+    "devDependencies": {
+        "@amazon/vinyl-build-utils": "^1.0.0",
+        "@amazon/vinyl-jasmine-wrapper": "^1.0.0",
+        "@amazon/vinyl-mock-generator": "^1.0.0"
+    },
+    "browserslist": [
+        "defaults, chrome 52, firefox 54, edge 15, safari 8"
+    ]
+}