@venos-inc/venos 0.1.12 → 0.1.14

package/etc/mcp-server/node_modules/undici/docs/api/ProxyAgent.md

@@ -0,0 +1,126 @@
+# Class: ProxyAgent
+
+Extends: `undici.Dispatcher`
+
+A Proxy Agent class that implements the Agent API. It allows the connection through proxy in a simple way.
+
+## `new ProxyAgent([options])`
+
+Arguments:
+
+* **options** `ProxyAgentOptions` (required) - It extends the `Agent` options.
+
+Returns: `ProxyAgent`
+
+### Parameter: `ProxyAgentOptions`
+
+Extends: [`AgentOptions`](Agent.md#parameter-agentoptions)
+
+* **uri** `string` (required) - It can be passed either by a string or a object containing `uri` as string.
+* **token** `string` (optional) - It can be passed by a string of token for authentication.
+* **auth** `string` (**deprecated**) - Use token.
+* **clientFactory** `(origin: URL, opts: Object) => Dispatcher` (optional) - Default: `(origin, opts) => new Pool(origin, opts)`
+* **requestTls** `BuildOptions` (optional) - Options object passed when creating the underlying socket via the connector builder for the request. See [TLS](https://nodejs.org/api/tls.html#tlsconnectoptions-callback).
+* **proxyTls** `BuildOptions` (optional) - Options object passed when creating the underlying socket via the connector builder for the proxy server. See [TLS](https://nodejs.org/api/tls.html#tlsconnectoptions-callback).
+
+Examples:
+
+```js
+import { ProxyAgent } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+// or
+const proxyAgent = new ProxyAgent({ uri: 'my.proxy.server' })
+```
+
+#### Example - Basic ProxyAgent instantiation
+
+This will instantiate the ProxyAgent. It will not do anything until registered as the agent to use with requests.
+
+```js
+import { ProxyAgent } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+```
+
+#### Example - Basic Proxy Request with global agent dispatcher
+
+```js
+import { setGlobalDispatcher, request, ProxyAgent } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+setGlobalDispatcher(proxyAgent)
+
+const { statusCode, body } = await request('http://localhost:3000/foo')
+
+console.log('response received', statusCode) // response received 200
+
+for await (const data of body) {
+  console.log('data', data.toString('utf8')) // data foo
+}
+```
+
+#### Example - Basic Proxy Request with local agent dispatcher
+
+```js
+import { ProxyAgent, request } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+
+const {
+  statusCode,
+  body
+} = await request('http://localhost:3000/foo', { dispatcher: proxyAgent })
+
+console.log('response received', statusCode) // response received 200
+
+for await (const data of body) {
+  console.log('data', data.toString('utf8')) // data foo
+}
+```
+
+#### Example - Basic Proxy Request with authentication
+
+```js
+import { setGlobalDispatcher, request, ProxyAgent } from 'undici';
+
+const proxyAgent = new ProxyAgent({
+  uri: 'my.proxy.server',
+  // token: 'Bearer xxxx'
+  token: `Basic ${Buffer.from('username:password').toString('base64')}`
+});
+setGlobalDispatcher(proxyAgent);
+
+const { statusCode, body } = await request('http://localhost:3000/foo');
+
+console.log('response received', statusCode); // response received 200
+
+for await (const data of body) {
+  console.log('data', data.toString('utf8')); // data foo
+}
+```
+
+### `ProxyAgent.close()`
+
+Closes the proxy agent and waits for registered pools and clients to also close before resolving.
+
+Returns: `Promise<void>`
+
+#### Example - clean up after tests are complete
+
+```js
+import { ProxyAgent, setGlobalDispatcher } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+setGlobalDispatcher(proxyAgent)
+
+await proxyAgent.close()
+```
+
+### `ProxyAgent.dispatch(options, handlers)`
+
+Implements [`Agent.dispatch(options, handlers)`](Agent.md#parameter-agentdispatchoptions).
+
+### `ProxyAgent.request(options[, callback])`
+
+See [`Dispatcher.request(options [, callback])`](Dispatcher.md#dispatcherrequestoptions-callback).

package/etc/mcp-server/node_modules/undici/docs/api/RetryHandler.md

@@ -0,0 +1,108 @@
+# Class: RetryHandler
+
+Extends: `undici.DispatcherHandlers`
+
+A handler class that implements the retry logic for a request.
+
+## `new RetryHandler(dispatchOptions, retryHandlers, [retryOptions])`
+
+Arguments:
+
+- **options** `Dispatch.DispatchOptions & RetryOptions` (required) - It is an intersection of `Dispatcher.DispatchOptions` and `RetryOptions`.
+- **retryHandlers** `RetryHandlers` (required) - Object containing the `dispatch` to be used on every retry, and `handler` for handling the `dispatch` lifecycle.
+
+Returns: `retryHandler`
+
+### Parameter: `Dispatch.DispatchOptions & RetryOptions`
+
+Extends: [`Dispatch.DispatchOptions`](Dispatcher.md#parameter-dispatchoptions).
+
+#### `RetryOptions`
+
+- **retry** `(err: Error, context: RetryContext, callback: (err?: Error | null) => void) => void` (optional) - Function to be called after every retry. It should pass error if no more retries should be performed.
+- **maxRetries** `number` (optional) - Maximum number of retries. Default: `5`
+- **maxTimeout** `number` (optional) - Maximum number of milliseconds to wait before retrying. Default: `30000` (30 seconds)
+- **minTimeout** `number` (optional) - Minimum number of milliseconds to wait before retrying. Default: `500` (half a second)
+- **timeoutFactor** `number` (optional) - Factor to multiply the timeout by for each retry attempt. Default: `2`
+- **retryAfter** `boolean` (optional) - It enables automatic retry after the `Retry-After` header is received. Default: `true`
+-
+- **methods** `string[]` (optional) - Array of HTTP methods to retry. Default: `['GET', 'PUT', 'HEAD', 'OPTIONS', 'DELETE']`
+- **statusCodes** `number[]` (optional) - Array of HTTP status codes to retry. Default: `[429, 500, 502, 503, 504]`
+- **errorCodes** `string[]` (optional) - Array of Error codes to retry. Default: `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN','ENETUNREACH', 'EHOSTDOWN',
+
+**`RetryContext`**
+
+- `state`: `RetryState` - Current retry state. It can be mutated.
+- `opts`: `Dispatch.DispatchOptions & RetryOptions` - Options passed to the retry handler.
+
+### Parameter `RetryHandlers`
+
+- **dispatch** `(options: Dispatch.DispatchOptions, handlers: Dispatch.DispatchHandlers) => Promise<Dispatch.DispatchResponse>` (required) - Dispatch function to be called after every retry.
+- **handler** Extends [`Dispatch.DispatchHandlers`](Dispatcher.md#dispatcherdispatchoptions-handler) (required) - Handler function to be called after the request is successful or the retries are exhausted.
+
+Examples:
+
+```js
+const client = new Client(`http://localhost:${server.address().port}`);
+const chunks = [];
+const handler = new RetryHandler(
+  {
+    ...dispatchOptions,
+    retryOptions: {
+      // custom retry function
+      retry: function (err, state, callback) {
+        counter++;
+
+        if (err.code && err.code === "UND_ERR_DESTROYED") {
+          callback(err);
+          return;
+        }
+
+        if (err.statusCode === 206) {
+          callback(err);
+          return;
+        }
+
+        setTimeout(() => callback(null), 1000);
+      },
+    },
+  },
+  {
+    dispatch: (...args) => {
+      return client.dispatch(...args);
+    },
+    handler: {
+      onConnect() {},
+      onBodySent() {},
+      onHeaders(status, _rawHeaders, resume, _statusMessage) {
+        // do something with headers
+      },
+      onData(chunk) {
+        chunks.push(chunk);
+        return true;
+      },
+      onComplete() {},
+      onError() {
+        // handle error properly
+      },
+    },
+  }
+);
+```
+
+#### Example - Basic RetryHandler with defaults
+
+```js
+const client = new Client(`http://localhost:${server.address().port}`);
+const handler = new RetryHandler(dispatchOptions, {
+  dispatch: client.dispatch.bind(client),
+  handler: {
+    onConnect() {},
+    onBodySent() {},
+    onHeaders(status, _rawHeaders, resume, _statusMessage) {},
+    onData(chunk) {},
+    onComplete() {},
+    onError(err) {},
+  },
+});
+```

package/etc/mcp-server/node_modules/undici/docs/api/WebSocket.md

@@ -0,0 +1,43 @@
+# Class: WebSocket
+
+> ⚠️ Warning: the WebSocket API is experimental.
+
+Extends: [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget)
+
+The WebSocket object provides a way to manage a WebSocket connection to a server, allowing bidirectional communication. The API follows the [WebSocket spec](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) and [RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455).
+
+## `new WebSocket(url[, protocol])`
+
+Arguments:
+
+* **url** `URL | string` - The url's protocol *must* be `ws` or `wss`.
+* **protocol** `string | string[] | WebSocketInit` (optional) - Subprotocol(s) to request the server use, or a [`Dispatcher`](./Dispatcher.md).
+
+### Example:
+
+This example will not work in browsers or other platforms that don't allow passing an object.
+
+```mjs
+import { WebSocket, ProxyAgent } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+
+const ws = new WebSocket('wss://echo.websocket.events', {
+  dispatcher: proxyAgent,
+  protocols: ['echo', 'chat']
+})
+```
+
+If you do not need a custom Dispatcher, it's recommended to use the following pattern:
+
+```mjs
+import { WebSocket } from 'undici'
+
+const ws = new WebSocket('wss://echo.websocket.events', ['echo', 'chat'])
+```
+
+## Read More
+
+- [MDN - WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+- [The WebSocket Specification](https://www.rfc-editor.org/rfc/rfc6455)
+- [The WHATWG WebSocket Specification](https://websockets.spec.whatwg.org/)

package/etc/mcp-server/node_modules/undici/docs/api/api-lifecycle.md

@@ -0,0 +1,62 @@
+# Client Lifecycle
+
+An Undici [Client](Client.md) can be best described as a state machine. The following list is a summary of the various state transitions the `Client` will go through in its lifecycle. This document also contains detailed breakdowns of each state.
+
+> This diagram is not a perfect representation of the undici Client. Since the Client class is not actually implemented as a state-machine, actual execution may deviate slightly from what is described below. Consider this as a general resource for understanding the inner workings of the Undici client rather than some kind of formal specification.
+
+## State Transition Overview
+
+* A `Client` begins in the **idle** state with no socket connection and no requests in queue.
+  * The *connect* event transitions the `Client` to the **pending** state where requests can be queued prior to processing.
+  * The *close* and *destroy* events transition the `Client` to the **destroyed** state. Since there are no requests in the queue, the *close* event immediately transitions to the **destroyed** state.
+* The **pending** state indicates the underlying socket connection has been successfully established and requests are queueing.
+  * The *process* event transitions the `Client` to the **processing** state where requests are processed.
+  * If requests are queued, the *close* event transitions to the **processing** state; otherwise, it transitions to the **destroyed** state.
+  * The *destroy* event transitions to the **destroyed** state.
+* The **processing** state initializes to the **processing.running** state.
+  * If the current request requires draining, the *needDrain* event transitions the `Client` into the **processing.busy** state which will return to the **processing.running** state with the *drainComplete* event.
+  * After all queued requests are completed, the *keepalive* event transitions the `Client` back to the **pending** state. If no requests are queued during the timeout, the **close** event transitions the `Client` to the **destroyed** state.
+  * If the *close* event is fired while the `Client` still has queued requests, the `Client` transitions to the **process.closing** state where it will complete all existing requests before firing the *done* event.
+  * The *done* event gracefully transitions the `Client` to the **destroyed** state.
+  * At any point in time, the *destroy* event will transition the `Client` from the **processing** state to the **destroyed** state, destroying any queued requests.
+* The **destroyed** state is a final state and the `Client` is no longer functional.
+
+![A state diagram representing an Undici Client instance](../assets/lifecycle-diagram.png)
+
+> The diagram was generated using Mermaid.js Live Editor. Modify the state diagram [here](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic3RhdGVEaWFncmFtLXYyXG4gICAgWypdIC0tPiBpZGxlXG4gICAgaWRsZSAtLT4gcGVuZGluZyA6IGNvbm5lY3RcbiAgICBpZGxlIC0tPiBkZXN0cm95ZWQgOiBkZXN0cm95L2Nsb3NlXG4gICAgXG4gICAgcGVuZGluZyAtLT4gaWRsZSA6IHRpbWVvdXRcbiAgICBwZW5kaW5nIC0tPiBkZXN0cm95ZWQgOiBkZXN0cm95XG5cbiAgICBzdGF0ZSBjbG9zZV9mb3JrIDw8Zm9yaz4-XG4gICAgcGVuZGluZyAtLT4gY2xvc2VfZm9yayA6IGNsb3NlXG4gICAgY2xvc2VfZm9yayAtLT4gcHJvY2Vzc2luZ1xuICAgIGNsb3NlX2ZvcmsgLS0-IGRlc3Ryb3llZFxuXG4gICAgcGVuZGluZyAtLT4gcHJvY2Vzc2luZyA6IHByb2Nlc3NcblxuICAgIHByb2Nlc3NpbmcgLS0-IHBlbmRpbmcgOiBrZWVwYWxpdmVcbiAgICBwcm9jZXNzaW5nIC0tPiBkZXN0cm95ZWQgOiBkb25lXG4gICAgcHJvY2Vzc2luZyAtLT4gZGVzdHJveWVkIDogZGVzdHJveVxuXG4gICAgc3RhdGUgcHJvY2Vzc2luZyB7XG4gICAgICAgIHJ1bm5pbmcgLS0-IGJ1c3kgOiBuZWVkRHJhaW5cbiAgICAgICAgYnVzeSAtLT4gcnVubmluZyA6IGRyYWluQ29tcGxldGVcbiAgICAgICAgcnVubmluZyAtLT4gWypdIDoga2VlcGFsaXZlXG4gICAgICAgIHJ1bm5pbmcgLS0-IGNsb3NpbmcgOiBjbG9zZVxuICAgICAgICBjbG9zaW5nIC0tPiBbKl0gOiBkb25lXG4gICAgICAgIFsqXSAtLT4gcnVubmluZ1xuICAgIH1cbiAgICAiLCJtZXJtYWlkIjp7InRoZW1lIjoiYmFzZSJ9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ)
+
+## State details
+
+### idle
+
+The **idle** state is the initial state of a `Client` instance. While an `origin` is required for instantiating a `Client` instance, the underlying socket connection will not be established until a request is queued using [`Client.dispatch()`](Client.md#clientdispatchoptions-handlers). By calling `Client.dispatch()` directly or using one of the multiple implementations ([`Client.connect()`](Client.md#clientconnectoptions-callback), [`Client.pipeline()`](Client.md#clientpipelineoptions-handler), [`Client.request()`](Client.md#clientrequestoptions-callback), [`Client.stream()`](Client.md#clientstreamoptions-factory-callback), and [`Client.upgrade()`](Client.md#clientupgradeoptions-callback)), the `Client` instance will transition from **idle** to [**pending**](#pending) and then most likely directly to [**processing**](#processing).
+
+Calling [`Client.close()`](Client.md#clientclosecallback) or [`Client.destroy()`](Client.md#clientdestroyerror-callback) transitions directly to the [**destroyed**](#destroyed) state since the `Client` instance will have no queued requests in this state.
+
+### pending
+
+The **pending** state signifies a non-processing `Client`. Upon entering this state, the `Client` establishes a socket connection and emits the [`'connect'`](Client.md#event-connect) event signalling a connection was successfully established with the `origin` provided during `Client` instantiation. The internal queue is initially empty, and requests can start queueing.
+
+Calling [`Client.close()`](Client.md#clientclosecallback) with queued requests, transitions the `Client` to the [**processing**](#processing) state. Without queued requests, it transitions to the [**destroyed**](#destroyed) state.
+
+Calling [`Client.destroy()`](Client.md#clientdestroyerror-callback) transitions directly to the [**destroyed**](#destroyed) state regardless of existing requests.
+
+### processing
+
+The **processing** state is a state machine within itself. It initializes to the [**processing.running**](#running) state. The [`Client.dispatch()`](Client.md#clientdispatchoptions-handlers), [`Client.close()`](Client.md#clientclosecallback), and [`Client.destroy()`](Client.md#clientdestroyerror-callback) can be called at any time while the `Client` is in this state. `Client.dispatch()` will add more requests to the queue while existing requests continue to be processed. `Client.close()` will transition to the [**processing.closing**](#closing) state. And `Client.destroy()` will transition to [**destroyed**](#destroyed).
+
+#### running
+
+In the **processing.running** sub-state, queued requests are being processed in a FIFO order. If a request body requires draining, the *needDrain* event transitions to the [**processing.busy**](#busy) sub-state. The *close* event transitions the Client to the [**process.closing**](#closing) sub-state. If all queued requests are processed and neither [`Client.close()`](Client.md#clientclosecallback) nor [`Client.destroy()`](Client.md#clientdestroyerror-callback) are called, then the [**processing**](#processing) machine will trigger a *keepalive* event transitioning the `Client` back to the [**pending**](#pending) state. During this time, the `Client` is waiting for the socket connection to timeout, and once it does, it triggers the *timeout* event and transitions to the [**idle**](#idle) state.
+
+#### busy
+
+This sub-state is only entered when a request body is an instance of [Stream](https://nodejs.org/api/stream.html) and requires draining. The `Client` cannot process additional requests while in this state and must wait until the currently processing request body is completely drained before transitioning back to [**processing.running**](#running).
+
+#### closing
+
+This sub-state is only entered when a `Client` instance has queued requests and the [`Client.close()`](Client.md#clientclosecallback) method is called. In this state, the `Client` instance continues to process requests as usual, with the one exception that no additional requests can be queued. Once all of the queued requests are processed, the `Client` will trigger the *done* event gracefully entering the [**destroyed**](#destroyed) state without an error.
+
+### destroyed
+
+The **destroyed** state is a final state for the `Client` instance. Once in this state, a `Client` is nonfunctional. Calling any other `Client` methods will result in an `ClientDestroyedError`.

package/etc/mcp-server/node_modules/undici/docs/best-practices/client-certificate.md

@@ -0,0 +1,64 @@
+# Client certificate
+
+Client certificate authentication can be configured with the `Client`, the required options are passed along through the `connect` option.
+
+The client certificates must be signed by a trusted CA. The Node.js default is to trust the well-known CAs curated by Mozilla.
+
+Setting the server option `requestCert: true` tells the server to request the client certificate.
+
+The server option `rejectUnauthorized: false` allows us to handle any invalid certificate errors in client code. The `authorized` property on the socket of the incoming request will show if the client certificate was valid. The `authorizationError` property will give the reason if the certificate was not valid.
+
+### Client Certificate Authentication
+
+```js
+const { readFileSync } = require('fs')
+const { join } = require('path')
+const { createServer } = require('https')
+const { Client } = require('undici')
+
+const serverOptions = {
+  ca: [
+    readFileSync(join(__dirname, 'client-ca-crt.pem'), 'utf8')
+  ],
+  key: readFileSync(join(__dirname, 'server-key.pem'), 'utf8'),
+  cert: readFileSync(join(__dirname, 'server-crt.pem'), 'utf8'),
+  requestCert: true,
+  rejectUnauthorized: false
+}
+
+const server = createServer(serverOptions, (req, res) => {
+  // true if client cert is valid
+  if(req.client.authorized === true) {
+    console.log('valid')
+  } else {
+    console.error(req.client.authorizationError)
+  }
+  res.end()
+})
+
+server.listen(0, function () {
+  const tls = {
+    ca: [
+      readFileSync(join(__dirname, 'server-ca-crt.pem'), 'utf8')
+    ],
+    key: readFileSync(join(__dirname, 'client-key.pem'), 'utf8'),
+    cert: readFileSync(join(__dirname, 'client-crt.pem'), 'utf8'),
+    rejectUnauthorized: false,
+    servername: 'agent1'
+  }
+  const client = new Client(`https://localhost:${server.address().port}`, {
+    connect: tls
+  })
+
+  client.request({
+    path: '/',
+    method: 'GET'
+  }, (err, { body }) => {
+    body.on('data', (buf) => {})
+    body.on('end', () => {
+      client.close()
+      server.close()
+    })
+  })
+})
+```

package/etc/mcp-server/node_modules/undici/docs/best-practices/mocking-request.md

@@ -0,0 +1,136 @@
+# Mocking Request
+
+Undici has its own mocking [utility](../api/MockAgent.md). It allow us to intercept undici HTTP requests and return mocked values instead. It can be useful for testing purposes.
+
+Example:
+
+```js
+// bank.mjs
+import { request } from 'undici'
+
+export async function bankTransfer(recipient, amount) {
+  const { body } = await request('http://localhost:3000/bank-transfer',
+    {
+      method: 'POST',
+      headers: {
+        'X-TOKEN-SECRET': 'SuperSecretToken',
+      },
+      body: JSON.stringify({
+        recipient,
+        amount
+      })
+    }
+  )
+  return await body.json()
+}
+```
+
+And this is what the test file looks like:
+
+```js
+// index.test.mjs
+import { strict as assert } from 'assert'
+import { MockAgent, setGlobalDispatcher, } from 'undici'
+import { bankTransfer } from './bank.mjs'
+
+const mockAgent = new MockAgent();
+
+setGlobalDispatcher(mockAgent);
+
+// Provide the base url to the request
+const mockPool = mockAgent.get('http://localhost:3000');
+
+// intercept the request
+mockPool.intercept({
+  path: '/bank-transfer',
+  method: 'POST',
+  headers: {
+    'X-TOKEN-SECRET': 'SuperSecretToken',
+  },
+  body: JSON.stringify({
+    recipient: '1234567890',
+    amount: '100'
+  })
+}).reply(200, {
+  message: 'transaction processed'
+})
+
+const success = await bankTransfer('1234567890', '100')
+
+assert.deepEqual(success, { message: 'transaction processed' })
+
+// if you dont want to check whether the body or the headers contain the same value
+// just remove it from interceptor
+mockPool.intercept({
+  path: '/bank-transfer',
+  method: 'POST',
+}).reply(400, {
+  message: 'bank account not found'
+})
+
+const badRequest = await bankTransfer('1234567890', '100')
+
+assert.deepEqual(badRequest, { message: 'bank account not found' })
+```
+
+Explore other MockAgent functionality [here](../api/MockAgent.md)
+
+## Debug Mock Value
+
+When the interceptor and the request options are not the same, undici will automatically make a real HTTP request. To prevent real requests from being made, use `mockAgent.disableNetConnect()`:
+
+```js
+const mockAgent = new MockAgent();
+
+setGlobalDispatcher(mockAgent);
+mockAgent.disableNetConnect()
+
+// Provide the base url to the request
+const mockPool = mockAgent.get('http://localhost:3000');
+
+mockPool.intercept({
+  path: '/bank-transfer',
+  method: 'POST',
+}).reply(200, {
+  message: 'transaction processed'
+})
+
+const badRequest = await bankTransfer('1234567890', '100')
+// Will throw an error
+// MockNotMatchedError: Mock dispatch not matched for path '/bank-transfer':
+// subsequent request to origin http://localhost:3000 was not allowed (net.connect disabled)
+```
+
+## Reply with data based on request
+
+If the mocked response needs to be dynamically derived from the request parameters, you can provide a function instead of an object to `reply`:
+
+```js
+mockPool.intercept({
+  path: '/bank-transfer',
+  method: 'POST',
+  headers: {
+    'X-TOKEN-SECRET': 'SuperSecretToken',
+  },
+  body: JSON.stringify({
+    recipient: '1234567890',
+    amount: '100'
+  })
+}).reply(200, (opts) => {
+  // do something with opts
+
+  return { message: 'transaction processed' }
+})
+```
+
+in this case opts will be
+
+```
+{
+  method: 'POST',
+  headers: { 'X-TOKEN-SECRET': 'SuperSecretToken' },
+  body: '{"recipient":"1234567890","amount":"100"}',
+  origin: 'http://localhost:3000',
+  path: '/bank-transfer'
+}
+```

package/etc/mcp-server/node_modules/undici/docs/best-practices/proxy.md

@@ -0,0 +1,127 @@
+# Connecting through a proxy
+
+Connecting through a proxy is possible by:
+
+- Using [AgentProxy](../api/ProxyAgent.md).
+- Configuring `Client` or `Pool` constructor.
+
+The proxy url should be passed to the `Client` or `Pool` constructor, while the upstream server url
+should be added to every request call in the `path`.
+For instance, if you need to send a request to the `/hello` route of your upstream server,
+the `path` should be `path: 'http://upstream.server:port/hello?foo=bar'`.
+
+If you proxy requires basic authentication, you can send it via the `proxy-authorization` header.
+
+### Connect without authentication
+
+```js
+import { Client } from 'undici'
+import { createServer } from 'http'
+import proxy from 'proxy'
+
+const server = await buildServer()
+const proxyServer = await buildProxy()
+
+const serverUrl = `http://localhost:${server.address().port}`
+const proxyUrl = `http://localhost:${proxyServer.address().port}`
+
+server.on('request', (req, res) => {
+  console.log(req.url) // '/hello?foo=bar'
+  res.setHeader('content-type', 'application/json')
+  res.end(JSON.stringify({ hello: 'world' }))
+})
+
+const client = new Client(proxyUrl)
+
+const response = await client.request({
+  method: 'GET',
+  path: serverUrl + '/hello?foo=bar'
+})
+
+response.body.setEncoding('utf8')
+let data = ''
+for await (const chunk of response.body) {
+  data += chunk
+}
+console.log(response.statusCode) // 200
+console.log(JSON.parse(data)) // { hello: 'world' }
+
+server.close()
+proxyServer.close()
+client.close()
+
+function buildServer () {
+  return new Promise((resolve, reject) => {
+    const server = createServer()
+    server.listen(0, () => resolve(server))
+  })
+}
+
+function buildProxy () {
+  return new Promise((resolve, reject) => {
+    const server = proxy(createServer())
+    server.listen(0, () => resolve(server))
+  })
+}
+```
+
+### Connect with authentication
+
+```js
+import { Client } from 'undici'
+import { createServer } from 'http'
+import proxy from 'proxy'
+
+const server = await buildServer()
+const proxyServer = await buildProxy()
+
+const serverUrl = `http://localhost:${server.address().port}`
+const proxyUrl = `http://localhost:${proxyServer.address().port}`
+
+proxyServer.authenticate = function (req, fn) {
+  fn(null, req.headers['proxy-authorization'] === `Basic ${Buffer.from('user:pass').toString('base64')}`)
+}
+
+server.on('request', (req, res) => {
+  console.log(req.url) // '/hello?foo=bar'
+  res.setHeader('content-type', 'application/json')
+  res.end(JSON.stringify({ hello: 'world' }))
+})
+
+const client = new Client(proxyUrl)
+
+const response = await client.request({
+  method: 'GET',
+  path: serverUrl + '/hello?foo=bar',
+  headers: {
+    'proxy-authorization': `Basic ${Buffer.from('user:pass').toString('base64')}`
+  }
+})
+
+response.body.setEncoding('utf8')
+let data = ''
+for await (const chunk of response.body) {
+  data += chunk
+}
+console.log(response.statusCode) // 200
+console.log(JSON.parse(data)) // { hello: 'world' }
+
+server.close()
+proxyServer.close()
+client.close()
+
+function buildServer () {
+  return new Promise((resolve, reject) => {
+    const server = createServer()
+    server.listen(0, () => resolve(server))
+  })
+}
+
+function buildProxy () {
+  return new Promise((resolve, reject) => {
+    const server = proxy(createServer())
+    server.listen(0, () => resolve(server))
+  })
+}
+```
+