global-agent 3.0.0 → 4.1.0

package/.babelrc

@@ -0,0 +1,23 @@
+{
+  "env": {
+    "test": {
+      "plugins": [
+        "istanbul"
+      ]
+    }
+  },
+  "plugins": [
+    "transform-export-default-name",
+    "@babel/transform-flow-strip-types"
+  ],
+  "presets": [
+    [
+      "@babel/env",
+      {
+        "targets": {
+          "node": "12"
+        }
+      }
+    ]
+  ]
+}

package/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true

package/.eslintignore

@@ -0,0 +1 @@
+/bootstrap.js

package/.eslintrc

@@ -0,0 +1,27 @@
+{
+  "extends": [
+    "canonical",
+    "canonical/node",
+    "canonical/typescript"
+  ],
+  "parserOptions": {
+    "project": "./tsconfig.json"
+  },
+  "root": true,
+  "rules": {
+    "@typescript-eslint/prefer-regexp-exec": 0,
+    "class-methods-use-this": 0,
+    "fp/no-class": 0,
+    "fp/no-events": 0,
+    "fp/no-this": 0,
+    "import/no-cycle": 0,
+    "no-continue": 0,
+    "no-restricted-syntax": 0,
+    "no-unused-expressions": [
+      2,
+      {
+        "allowTaggedTemplates": true
+      }
+    ]
+  }
+}

package/.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: gajus
+patreon: gajus

package/.github/workflows/feature.yaml

@@ -0,0 +1,35 @@
+jobs:
+  test:
+    name: Test (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ['20', '22', '24']
+    steps:
+      - name: setup repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: setup node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: setup npm
+        uses: npm/action-setup@v4
+        with:
+          version: 10
+      - run: npm install
+      - run: npm run lint
+      - run: npm run test
+      - run: npm run build
+    timeout-minutes: 10
+name: Test
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - ready_for_review

package/.github/workflows/main.yaml

@@ -0,0 +1,50 @@
+jobs:
+  test:
+    name: Test (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ['20', '22', '24']
+    steps:
+      - name: setup repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: setup node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - run: npm run lint
+      - run: npm run test
+      - run: npm run build
+    timeout-minutes: 10
+  release:
+    needs: test
+    environment: release
+    name: Release
+    permissions:
+      contents: write
+      id-token: write
+      issues: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: setup repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: setup node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - run: npm install
+      - run: npm run build
+      - env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: npx semantic-release
+name: Release
+on:
+  push:
+    branches:
+      - main

package/.gitignore

@@ -0,0 +1,14 @@
+coverage
+dist
+node_modules
+*.log
+.*
+!.babelrc
+!.editorconfig
+!.eslintignore
+!.eslintrc
+!.github
+!.gitignore
+!.npmignore
+!.npmrc
+!.README

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2019, Gajus Kuizinas (http://gajus.com/)
+Copyright (c) 2026, Gajus Kuizinas (https://gajus.com/)
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
@@ -8,7 +8,7 @@ modification, are permitted provided that the following conditions are met:
     * Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
-    * Neither the name of the Gajus Kuizinas (http://gajus.com/) nor the
+    * Neither the name of the Gajus Kuizinas (https://gajus.com/) nor the
       names of its contributors may be used to endorse or promote products
       derived from this software without specific prior written permission.
 

package/README.md

@@ -1,7 +1,5 @@
 # global-agent
 
-[![GitSpo Mentions](https://gitspo.com/badges/mentions/gajus/global-agent?style=flat-square)](https://gitspo.com/mentions/gajus/global-agent)
-[![Travis build status](http://img.shields.io/travis/gajus/global-agent/master.svg?style=flat-square)](https://travis-ci.org/gajus/global-agent)
 [![Coveralls](https://img.shields.io/coveralls/gajus/global-agent.svg?style=flat-square)](https://coveralls.io/github/gajus/global-agent)
 [![NPM version](http://img.shields.io/npm/v/global-agent.svg?style=flat-square)](https://www.npmjs.org/package/global-agent)
 [![Canonical Code Style](https://img.shields.io/badge/code%20style-canonical-blue.svg?style=flat-square)](https://github.com/gajus/canonical)
@@ -14,7 +12,6 @@ Global HTTP/HTTPS proxy configurable using environment variables.
   * [Setup proxy using `bootstrap` routine](#setup-proxy-using-bootstrap-routine)
   * [Runtime configuration](#runtime-configuration)
   * [Exclude URLs](#exclude-urls)
-  * [Enable logging](#enable-logging)
 * [API](#api)
   * [`createGlobalProxyAgent`](#createglobalproxyagent)
   * [Environment variables](#environment-variables)
@@ -125,7 +122,7 @@ global.GLOBAL_AGENT.HTTP_PROXY = 'http://127.0.0.1:8002';
 
 ```
 
-The first HTTP request is going to use http://127.0.0.1:8001 proxy and the secord request is going to use http://127.0.0.1:8002.
+The first HTTP request is going to use http://127.0.0.1:8001 proxy and the second request is going to use http://127.0.0.1:8002.
 
 All `global-agent` configuration is available under `global.GLOBAL_AGENT` namespace.
 
@@ -144,20 +141,6 @@ says to contact all machines with the 'foo.com' TLD and 'baz.com' domains direct
 
 The environment variable `GLOBAL_AGENT_HTTPS_PROXY` can be set to specify a separate proxy for HTTPS requests. When this variable is not set `GLOBAL_AGENT_HTTP_PROXY` is used for both HTTP and HTTPS requests.
 
-### Enable logging
-
-`global-agent` is using [`roarr`](https://www.npmjs.com/package/roarr) logger to log HTTP requests and response (HTTP status code and headers), e.g.
-
-```json
-{"context":{"program":"global-agent","namespace":"Agent","logLevel":10,"destination":"http://gajus.com","proxy":"http://127.0.0.1:8076"},"message":"proxying request","sequence":1,"time":1556269669663,"version":"1.0.0"}
-{"context":{"program":"global-agent","namespace":"Agent","logLevel":10,"headers":{"content-type":"text/plain","content-length":"2","date":"Fri, 26 Apr 2019 12:07:50 GMT","connection":"close"},"requestId":6,"statusCode":200},"message":"proxying response","sequence":2,"time":1557133856955,"version":"1.0.0"}
-
-```
-
-Export `ROARR_LOG=true` environment variable to enable log printing to stdout.
-
-Use [`roarr-cli`](https://github.com/gajus/roarr-cli) program to pretty-print the logs.
-
 ## API
 
 ### `createGlobalProxyAgent`
@@ -167,17 +150,53 @@ Use [`roarr-cli`](https://github.com/gajus/roarr-cli) program to pretty-print th
  * @property environmentVariableNamespace Defines namespace of `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables. (Default: `GLOBAL_AGENT_`)
  * @property forceGlobalAgent Forces to use `global-agent` HTTP(S) agent even when request was explicitly constructed with another agent. (Default: `true`)
  * @property socketConnectionTimeout Destroys socket if connection is not established within the timeout. (Default: `60000`)
+ * @property ca Single CA certificate or an array of CA certificates that is trusted for secure connections to the registry.
+ * @property logger Custom logger instance for debug logging. Must implement `child`, `debug`, `error`, `info`, `trace`, and `warn` methods.
  */
 type ProxyAgentConfigurationInputType = {|
   +environmentVariableNamespace?: string,
   +forceGlobalAgent?: boolean,
   +socketConnectionTimeout?: number,
+  +ca?: string[] | string,
+  +logger?: Logger,
 |};
 
 (configurationInput: ProxyAgentConfigurationInputType) => ProxyAgentConfigurationType;
 
 ```
 
+### Custom Logger
+
+You can provide a custom logger to `global-agent` for debugging purposes. The logger must implement the following interface:
+
+```ts
+type Logger = {
+  child: (context: object) => Logger,
+  debug: (context: object | string, message?: string) => void,
+  error: (context: object | string, message?: string) => void,
+  info: (context: object | string, message?: string) => void,
+  trace: (context: object | string, message?: string) => void,
+  warn: (context: object | string, message?: string) => void,
+};
+```
+
+Example using a custom logger:
+
+```js
+import { createGlobalProxyAgent } from 'global-agent';
+
+createGlobalProxyAgent({
+  logger: {
+    child: () => logger,
+    debug: console.debug,
+    error: console.error,
+    info: console.info,
+    trace: console.trace,
+    warn: console.warn,
+  },
+});
+```
+
 ### Environment variables
 
 |Name|Description|Default|
@@ -185,9 +204,9 @@ type ProxyAgentConfigurationInputType = {|
 |`GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE`|Defines namespace of `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables.|`GLOBAL_AGENT_`|
 |`GLOBAL_AGENT_FORCE_GLOBAL_AGENT`|Forces to use `global-agent` HTTP(S) agent even when request was explicitly constructed with another agent.|`true`|
 |`GLOBAL_AGENT_SOCKET_CONNECTION_TIMEOUT`|Destroys socket if connection is not established within the timeout.|`60000`|
-|`${NAMESPACE}_HTTP_PROXY`|Sets the initial proxy controller HTTP_PROXY value.|N/A|
-|`${NAMESPACE}_HTTPS_PROXY`|Sets the initial proxy controller HTTPS_PROXY value.|N/A|
-|`${NAMESPACE}_NO_PROXY`|Sets the initial proxy controller NO_PROXY value.|N/A|
+|`${NAMESPACE}HTTP_PROXY`|Sets the initial proxy controller HTTP_PROXY value.|N/A|
+|`${NAMESPACE}HTTPS_PROXY`|Sets the initial proxy controller HTTPS_PROXY value.|N/A|
+|`${NAMESPACE}NO_PROXY`|Sets the initial proxy controller NO_PROXY value.|N/A|
 
 ### `global.GLOBAL_AGENT`
 
@@ -195,12 +214,71 @@ type ProxyAgentConfigurationInputType = {|
 
 `global.GLOBAL_AGENT` has the following properties:
 
-|Name|Description|Configurable|
+|Name|Configurable|Description|
 |---|---|---|
 |`HTTP_PROXY`|Yes|Sets HTTP proxy to use.|
 |`HTTPS_PROXY`|Yes|Sets a distinct proxy to use for HTTPS requests.|
 |`NO_PROXY`|Yes|Specifies a pattern of URLs that should be excluded from proxying. See [Exclude URLs](#exclude-urls).|
 
+## Certificate Authority (CA)
+
+### `addCACertificates`
+This method can be accessed using https to add CA certificates to the global-agent.
+
+Uses:
+```js
+if (typeof https.globalAgent.addCACertificates === 'function') {
+  //certificate - an array of ca certificates to be added to the global-agent
+  https.globalAgent.addCACertificates(certificate);
+}
+```
+
+Method Definition:
+```js
+/**
+ * This method can be used to append new ca certificates to existing ca certificates
+ * @param {string[] | string} ca a ca certificate or an array of ca certificates
+ */
+public addCACertificates (ca: string[] | string) {
+  if (!ca) {
+    log.error('Invalid input ca certificate');
+  } else if (this.ca) {
+    if (typeof ca === typeof this.ca) {
+      // concat valid ca certificates with the existing certificates,
+      if (typeof this.ca === 'string') {
+        this.ca = this.ca.concat(ca as string);
+      } else {
+        this.ca = this.ca.concat(ca as string[]);
+      }
+    } else {
+      log.error('Input ca certificate type mismatched with existing ca certificate type');
+    }
+  } else {
+    this.ca = ca;
+  }
+}
+```
+
+### `clearCACertificates`
+This method can be accessed using https to clear existing CA certificates from global-agent.
+
+Uses:
+```js
+if (typeof https.globalAgent.clearCACertificates === 'function') {
+  https.globalAgent.clearCACertificates();
+}
+```
+Method Definition:
+```js
+/**
+ * This method clears existing CA Certificates.
+ * It sets ca to undefined
+ */
+public clearCACertificates () {
+  this.ca = undefined;
+}
+```
+
 ## Supported libraries
 
 `global-agent` works with all libraries that internally use [`http.request`](https://nodejs.org/api/http.html#http_http_request_options_callback).
@@ -209,7 +287,7 @@ type ProxyAgentConfigurationInputType = {|
 
 * [`got`](https://www.npmjs.com/package/got)
 * [`axios`](https://www.npmjs.com/package/axios)
-* [`request`](https://www.npmjs.com/package/axios)
+* [`request`](https://www.npmjs.com/package/request)
 
 ## FAQ
 

package/package.json

@@ -5,53 +5,60 @@
     "url": "http://gajus.com"
   },
   "ava": {
-    "babel": {
-      "compileAsTests": [
-        "test/helpers/**/*"
-      ]
-    },
+    "extensions": [
+      "ts"
+    ],
     "files": [
       "test/global-agent/**/*"
     ],
     "require": [
-      "@babel/register"
+      "ts-node/register/transpile-only"
     ]
   },
   "dependencies": {
-    "boolean": "^3.0.1",
     "es6-error": "^4.1.1",
-    "matcher": "^3.0.0",
-    "roarr": "^2.15.3",
-    "semver": "^7.3.2",
-    "serialize-error": "^7.0.1"
+    "globalthis": "^1.0.2",
+    "matcher": "^4.0.0",
+    "omit-undefined": "^1.0.1",
+    "semver": "^7.3.5",
+    "serialize-error": "^8.1.0"
   },
   "description": "Global HTTP/HTTPS proxy configurable using environment variables.",
   "devDependencies": {
-    "@ava/babel": "^1.0.1",
-    "@babel/cli": "^7.10.1",
-    "@babel/core": "^7.10.2",
-    "@babel/node": "^7.10.1",
-    "@babel/plugin-transform-flow-strip-types": "^7.10.1",
-    "@babel/preset-env": "^7.10.2",
-    "@babel/register": "^7.10.1",
-    "anyproxy": "^4.1.2",
-    "ava": "^3.8.2",
-    "axios": "^0.19.2",
+    "@ava/babel": "^2.0.0",
+    "@babel/cli": "^7.14.8",
+    "@babel/core": "^7.14.8",
+    "@babel/node": "^7.14.7",
+    "@babel/plugin-transform-flow-strip-types": "^7.14.5",
+    "@babel/preset-env": "^7.14.8",
+    "@babel/register": "^7.14.5",
+    "@istanbuljs/nyc-config-typescript": "^1.0.1",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/github": "^12.0.3",
+    "@semantic-release/npm": "^13.1.3",
+    "@types/globalthis": "^1.0.1",
+    "@types/pem": "^1.14.4",
+    "@types/request": "^2.48.6",
+    "@types/semver": "^7.3.8",
+    "@types/sinon": "^10.0.2",
+    "ava": "^3.15.0",
+    "axios": "^0.21.1",
     "babel-plugin-istanbul": "^6.0.0",
-    "babel-plugin-transform-export-default-name": "^2.0.4",
-    "coveralls": "^3.1.0",
-    "eslint": "^7.1.0",
-    "eslint-config-canonical": "^20.0.5",
-    "flow-bin": "^0.125.1",
-    "flow-copy-source": "^2.0.9",
+    "babel-plugin-transform-export-default-name": "^2.1.0",
+    "coveralls": "^3.1.1",
+    "del-cli": "^4.0.1",
+    "eslint": "^7.31.0",
+    "eslint-config-canonical": "^26.2.3",
     "get-port": "^5.1.1",
-    "got": "^11.1.4",
-    "husky": "^4.2.5",
+    "got": "^11.8.2",
+    "husky": "^7.0.1",
     "nyc": "^15.1.0",
     "pem": "^1.14.4",
     "request": "^2.88.2",
-    "semantic-release": "^17.0.8",
-    "sinon": "^9.0.2"
+    "semantic-release": "^25.0.3",
+    "sinon": "^11.1.2",
+    "ts-node": "^10.1.0",
+    "typescript": "^4.3.5"
   },
   "engines": {
     "node": ">=10.0"
@@ -68,38 +75,22 @@
     "agent"
   ],
   "license": "BSD-3-Clause",
-  "main": "./dist/index.js",
+  "main": "./dist/src/index.js",
   "name": "global-agent",
   "nyc": {
-    "all": true,
-    "exclude": [
-      "src/bin",
-      "src/queries/*.js"
-    ],
-    "include": [
-      "src/**/*.js"
-    ],
-    "instrument": false,
-    "reporter": [
-      "html",
-      "text-summary"
-    ],
-    "require": [
-      "@babel/register"
-    ],
-    "silent": true,
-    "sourceMap": false
+    "extends": "@istanbuljs/nyc-config-typescript",
+    "all": true
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/gajus/global-agent"
   },
   "scripts": {
-    "build": "rm -fr ./dist && NODE_ENV=production babel ./src --out-dir ./dist --copy-files --source-maps && flow-copy-source src dist",
-    "create-readme": "gitdown ./.README/README.md --output-file ./README.md",
-    "dev": "NODE_ENV=development babel ./src --out-dir ./dist --copy-files --source-maps --watch",
-    "lint": "eslint ./src ./test && flow",
-    "test": "NODE_TLS_REJECT_UNAUTHORIZED=false NODE_ENV=test nyc ava --verbose --serial"
+    "build": "del-cli ./dist && tsc",
+    "lint": "eslint ./src ./test && tsc",
+    "test": "ava --verbose --serial",
+    "create-readme": "gitdown ./.README/README.md --output-file ./README.md"
   },
-  "version": "3.0.0"
+  "typings": "./dist/src/index.d.ts",
+  "version": "4.1.0"
 }

package/src/Logger.ts

@@ -0,0 +1,70 @@
+export type LogMethod = (context: object | string, message?: string) => void;
+
+export type Logger = {
+  child: (context: object) => Logger,
+  debug: LogMethod,
+  error: LogMethod,
+  info: LogMethod,
+  trace: LogMethod,
+  warn: LogMethod,
+};
+
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+const noop = () => {};
+
+const createNoopLogger = (): Logger => {
+  return {
+    child: () => {
+      return createNoopLogger();
+    },
+    debug: noop,
+    error: noop,
+    info: noop,
+    trace: noop,
+    warn: noop,
+  };
+};
+
+let currentLogger: Logger = createNoopLogger();
+
+export const setLogger = (newLogger: Logger): void => {
+  currentLogger = newLogger;
+};
+
+const createDelegatingLogger = (getContext: () => object): Logger => {
+  const getLogger = () => {
+    let targetLogger = currentLogger;
+    for (const [key, value] of Object.entries(getContext())) {
+      targetLogger = targetLogger.child({[key]: value});
+    }
+
+    return targetLogger;
+  };
+
+  return {
+    child: (context: object) => {
+      return createDelegatingLogger(() => {
+        return {...getContext(), ...context};
+      });
+    },
+    debug: (context, message) => {
+      getLogger().debug(context, message);
+    },
+    error: (context, message) => {
+      getLogger().error(context, message);
+    },
+    info: (context, message) => {
+      getLogger().info(context, message);
+    },
+    trace: (context, message) => {
+      getLogger().trace(context, message);
+    },
+    warn: (context, message) => {
+      getLogger().warn(context, message);
+    },
+  };
+};
+
+export const logger = createDelegatingLogger(() => {
+  return {package: 'global-agent'};
+});