global-agent 4.0.0 → 4.1.0

package/.github/workflows/feature.yaml

@@ -1,7 +1,10 @@
 jobs:
   test:
-    name: 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
@@ -10,7 +13,7 @@ jobs:
       - name: setup node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '24'
+          node-version: ${{ matrix.node-version }}
       - name: setup npm
         uses: npm/action-setup@v4
         with:

package/.github/workflows/main.yaml

@@ -1,5 +1,26 @@
 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:
@@ -18,8 +39,6 @@ jobs:
         with:
           node-version: '24'
       - run: npm install
-      - run: npm run lint
-      - run: npm run test
       - run: npm run build
       - env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/README.md

@@ -12,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)
@@ -142,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`
@@ -166,18 +151,52 @@ Use [`roarr-cli`](https://github.com/gajus/roarr-cli) program to pretty-print th
  * @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|

package/package.json

@@ -20,7 +20,6 @@
     "globalthis": "^1.0.2",
     "matcher": "^4.0.0",
     "omit-undefined": "^1.0.1",
-    "roarr": "^7.0.3",
     "semver": "^7.3.5",
     "serialize-error": "^8.1.0"
   },
@@ -93,5 +92,5 @@
     "create-readme": "gitdown ./.README/README.md --output-file ./README.md"
   },
   "typings": "./dist/src/index.d.ts",
-  "version": "4.0.0"
+  "version": "4.1.0"
 }

package/src/Logger.ts

@@ -1,10 +1,70 @@
-import {
-  Roarr,
-} from 'roarr';
+export type LogMethod = (context: object | string, message?: string) => void;
 
-const Logger = Roarr
-  .child({
-    package: 'global-agent',
-  });
+export type Logger = {
+  child: (context: object) => Logger,
+  debug: LogMethod,
+  error: LogMethod,
+  info: LogMethod,
+  trace: LogMethod,
+  warn: LogMethod,
+};
 
-export default Logger;
+// 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'};
+});

package/src/classes/Agent.ts

@@ -4,7 +4,9 @@ import net from 'net';
 import {
   serializeError,
 } from 'serialize-error';
-import Logger from '../Logger';
+import {
+  logger,
+} from '../Logger';
 import type {
   AgentType,
   ConnectionCallbackType,
@@ -15,7 +17,7 @@ import type {
   ProtocolType,
 } from '../types';
 
-const log = Logger.child({
+const log = logger.child({
   namespace: 'Agent',
 });
 

package/src/factories/createGlobalProxyAgent.ts

@@ -4,7 +4,10 @@ import {
   omitUndefined,
 } from 'omit-undefined';
 import semverGte from 'semver/functions/gte';
-import Logger from '../Logger';
+import {
+  logger,
+  setLogger,
+} from '../Logger';
 import {
   HttpProxyAgent,
   HttpsProxyAgent,
@@ -31,7 +34,7 @@ const httpRequest = http.request;
 const httpsGet = https.get;
 const httpsRequest = https.request;
 
-const log = Logger.child({
+const log = logger.child({
   namespace: 'createGlobalProxyAgent',
 });
 
@@ -60,6 +63,10 @@ const createConfiguration = (configurationInput: ProxyAgentConfigurationInputTyp
 export default (configurationInput: ProxyAgentConfigurationInputType = defaultConfigurationInput) => {
   const configuration = createConfiguration(configurationInput);
 
+  if (configurationInput.logger) {
+    setLogger(configurationInput.logger);
+  }
+
   const proxyController = createProxyController();
 
   // eslint-disable-next-line node/no-process-env

package/src/factories/createProxyController.ts

@@ -1,4 +1,6 @@
-import Logger from '../Logger';
+import {
+  logger,
+} from '../Logger';
 
 type ProxyController = {
   HTTP_PROXY: string | null,
@@ -6,7 +8,7 @@ type ProxyController = {
   NO_PROXY: string | null,
 };
 
-const log = Logger.child({
+const log = logger.child({
   namespace: 'createProxyController',
 });
 

package/src/index.ts

@@ -4,3 +4,6 @@ export {
 export {
   createGlobalProxyAgent,
 } from './factories';
+export type {
+  Logger,
+} from './Logger';

package/src/routines/bootstrap.ts

@@ -1,5 +1,7 @@
 import createGlobalThis from 'globalthis';
-import Logger from '../Logger';
+import {
+  logger,
+} from '../Logger';
 import {
   createGlobalProxyAgent,
 } from '../factories';
@@ -9,7 +11,7 @@ import type {
 
 const globalThis: any = createGlobalThis();
 
-const log = Logger.child({
+const log = logger.child({
   namespace: 'bootstrap',
 });
 

package/src/types.ts

@@ -10,6 +10,9 @@ import type {
 import type {
   TLSSocket,
 } from 'tls';
+import type {
+  Logger,
+} from './Logger';
 
 export type ProxyConfigurationType = {
   authorization: string | null,
@@ -56,6 +59,7 @@ export type ProxyAgentConfigurationInputType = {
   forceGlobalAgent?: boolean,
   socketConnectionTimeout?: number,
   ca?: string[] | string,
+  logger?: Logger,
 };
 
 export type ProxyAgentConfigurationType = {