Add example of proxying (#281)

## Problem

The community has requested clearer direction regarding using proxy
servers and other http-related customizations with our Typescript
client.

Asana ticket https://app.asana.com/0/1203260648987893/1205491455268495/f

## Solution

Add proxying section to README + clarify some code comments.

## Type of Change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] This change requires a documentation update
- [ ] Infrastructure change (CI configs, etc)
- [x] Non-code change (docs, etc)
- [ ] None of the above: (explain here)

## Test Plan

Describe specific steps for validating this change.


---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1205491455268495

.gitignore

@@ -15,3 +15,6 @@ ts-compilation-test/lib/
 .vscode
 .DS_Store
 scratch
+
+# Jetbrains
+.idea

README.md

@@ -77,6 +77,65 @@ const pc = new Pinecone({
 });
 ```
 
+### Using a proxy server
+
+If your network setup requires you to interact with Pinecone via a proxy, you can pass a custom `ProxyAgent` from
+the [`undici` library](https://undici.nodejs.org/#/). Below is an example of how to
+construct an `undici` `ProxyAgent` that routes network traffic through a [`mitm` proxy server](https://mitmproxy.
+org/) while hitting Pinecone's `/indexes` endpoint.
+
+**Note:** The following strategy relies on Node's native `fetch` implementation, [released in Node v16 and
+stabilized in Node v21](https://nodejs.org/docs/latest/api/globals.html#fetch). If you are running Node versions
+18-21, you may experience issues stemming from the instability of the feature. There are currently no known issues
+related to proxying in Node v18+.
+
+```typescript
+import {
+  Pinecone,
+  type PineconeConfiguration,
+} from '@pinecone-database/pinecone';
+import { Dispatcher, ProxyAgent } from 'undici';
+import * as fs from 'fs';
+
+const cert = fs.readFileSync('path-to-your-mitm-proxy-cert-pem-file');
+
+const client = new ProxyAgent({
+  uri: '<your proxy server URI>',
+  requestTls: {
+    port: '<your proxy server port>',
+    ca: cert,
+    host: '<your proxy server host>',
+  },
+});
+
+const customFetch = (
+  input: string | URL | Request,
+  init: RequestInit | undefined
+) => {
+  return fetch(input, {
+    ...init,
+    dispatcher: client as Dispatcher,
+    keepalive: true,  # optional
+  });
+};
+
+const config: PineconeConfiguration = {
+  apiKey:
+    '<your Pinecone API key, available in your dashboard at app.pinecone.io>',
+  fetchApi: customFetch,
+};
+
+const pc = new Pinecone(config);
+
+const indexes = async () => {
+  return await pc.listIndexes();
+};
+
+indexes().then((response) => {
+  console.log('My indexes: ', response);
+});
+```
+
 ## Indexes
 
 ### Create Index

src/data/types.ts

@@ -18,7 +18,7 @@ export type PineconeConfiguration = {
   controllerHostUrl?: string;
 
   /**
-   * Optional configuration field for specifying the fetch implementation. If not specified, the client will look for fetch in the global scope and if none is found it will fall back to a [cross-fetch](https://www.npmjs.com/package/cross-fetch) polyfill.
+   * Optional configuration field for specifying the fetch implementation. If not specified, the client will look for fetch in the global scope.
    */
   fetchApi?: FetchAPI;
 

src/utils/fetch.ts

@@ -6,12 +6,13 @@ export const getFetch = (config: PineconeConfiguration) => {
     // User-provided fetch implementation, if any, takes precedence.
     return config.fetchApi;
   } else if (global.fetch) {
-    // If a fetch implementation is already present in the global
-    // scope, use that. This should prevent confusing failures in
-    // nextjs projects where @vercel/fetch is mandated and
+    // If a fetch implementation is present in the global scope (will work with native fetch in Node18+, Edge runtimes,
+    // etc.), use that. This should prevent confusing failures in
+    // Next.js projects where @vercel/fetch is mandated and
     // other implementations are stubbed out.
     return global.fetch;
   } else {
+    // If no fetch implementation is found, throw an error.
     throw new PineconeConfigurationError(
       'No global or user-provided fetch implementations found. Please supply a fetch implementation.'
     );