Merge #1461

1461: feat: added support for custom request config r=bidoubiwa a=amgadserry

feat: added support for custom http client

# Pull Request

## Related issue


## What does this PR do?
- adds support for usages with preconfigured http clients like axios for using ms through a proxy for example
```
const client: MeiliSearch = new MeiliSearch({
      host: 'http://localhost:3000/api/v0/meilisearch/proxy',
      httpClient: async (url, opts) => {
        const response = await $charles.http!.getClient().request({
          url,
          data: opts?.body,
          headers: opts?.headers
        })

        return response.data
      }
    })
```
- adds support for customizing the requests created by `httpRequests` 

### BREAKING CHANGES:
- removes `headers` config param and introduces `requestConfig` instead which can be used to customize all fetch config

## PR checklist
Please check if your PR fulfills the following requirements:
- [x] Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
- [x] Have you read the contributing guidelines?
- [x] Have you made sure that the title is accurate and descriptive of the changes?

Thank you so much for contributing to Meilisearch!


Co-authored-by: Amgad Serry <[email protected]>

Author: meili-bors[bot]

README.md

@@ -327,6 +327,46 @@ index
 controller.abort()
 ```
 
+
+### Using Meilisearch behind a proxy <!-- omit in toc -->
+
+#### Custom request config <!-- omit in toc -->
+
+You can provide a custom request configuration. for example, with custom headers.
+
+```ts
+const client: MeiliSearch = new MeiliSearch({
+  host: 'http://localhost:3000/api/meilisearch/proxy',
+  requestConfig: {
+    headers: {
+      Authorization: AUTH_TOKEN
+    },
+    // OR
+    credentials: 'include'
+  }
+})
+```
+
+#### Custom http client <!-- omit in toc -->
+
+You can use your own HTTP client, for example, with [`axios`](https://github.com/axios/axios).
+
+```ts
+const client: MeiliSearch = new MeiliSearch({
+  host: 'http://localhost:3000/api/meilisearch/proxy',
+  httpClient: async (url, opts) => {
+    const response = await $axios.request({
+      url,
+      data: opts?.body,
+      headers: opts?.headers,
+      method: (opts?.method?.toLocaleUpperCase() as Method) ?? 'GET'
+    })
+
+    return response.data
+  }
+})
+```
+
 ## 🤖 Compatibility with Meilisearch
 
 This package guarantees compatibility with [version v1.x of Meilisearch](https://github.com/meilisearch/meilisearch/releases/latest), but some features may not be present. Please check the [issues](https://github.com/meilisearch/meilisearch-js/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+label%3Aenhancement) for more info.

src/clients/browser-client.ts

@@ -1,5 +1,5 @@
-import { Client } from './client'
 import { Config } from '../types'
+import { Client } from './client'
 
 class MeiliSearch extends Client {
   constructor(config: Config) {

src/http-requests.ts

@@ -40,19 +40,34 @@ function constructHostURL(host: string): string {
   }
 }
 
+function cloneAndParseHeaders(headers: HeadersInit): Record<string, string> {
+  if (Array.isArray(headers)) {
+    return headers.reduce((acc, headerPair) => {
+      acc[headerPair[0]] = headerPair[1]
+      return acc
+    }, {} as Record<string, string>)
+  } else if ('has' in headers) {
+    const clonedHeaders: Record<string, string> = {}
+    ;(headers as Headers).forEach((value, key) => (clonedHeaders[key] = value))
+    return clonedHeaders
+  } else {
+    return Object.assign({}, headers)
+  }
+}
+
 function createHeaders(config: Config): Record<string, any> {
   const agentHeader = 'X-Meilisearch-Client'
   const packageAgent = `Meilisearch JavaScript (v${PACKAGE_VERSION})`
   const contentType = 'Content-Type'
-  config.headers = config.headers || {}
-
-  const headers: Record<string, any> = Object.assign({}, config.headers) // Create a hard copy and not a reference to config.headers
+  const authorization = 'Authorization'
+  const headers = cloneAndParseHeaders(config.requestConfig?.headers ?? {})
 
-  if (config.apiKey) {
-    headers['Authorization'] = `Bearer ${config.apiKey}`
+  // do not override if user provided the header
+  if (config.apiKey && !headers[authorization]) {
+    headers[authorization] = `Bearer ${config.apiKey}`
   }
 
-  if (!config.headers[contentType]) {
+  if (!headers[contentType]) {
     headers['Content-Type'] = 'application/json'
   }
 
@@ -76,9 +91,13 @@ function createHeaders(config: Config): Record<string, any> {
 class HttpRequests {
   headers: Record<string, any>
   url: URL
+  requestConfig?: Config['requestConfig']
+  httpClient?: Required<Config>['httpClient']
 
   constructor(config: Config) {
     this.headers = createHeaders(config)
+    this.requestConfig = config.requestConfig
+    this.httpClient = config.httpClient
 
     try {
       const host = constructHostURL(config.host)
@@ -111,12 +130,23 @@ class HttpRequests {
     }
 
     try {
-      const response: any = await fetch(constructURL.toString(), {
+      const fetchFn = this.httpClient ? this.httpClient : fetch
+      const result = fetchFn(constructURL.toString(), {
         ...config,
+        ...this.requestConfig,
         method,
         body: JSON.stringify(body),
         headers: this.headers,
-      }).then((res) => httpResponseErrorHandler(res))
+      })
+
+      // When using a custom HTTP client, the response is returned to allow the user to parse/handle it as they see fit
+      if (this.httpClient) {
+        return await result
+      }
+
+      const response = await result.then((res: any) =>
+        httpResponseErrorHandler(res)
+      )
       const parsedBody = await response.json().catch(() => undefined)
 
       return parsedBody

src/types/types.ts

@@ -10,7 +10,8 @@ export type Config = {
   host: string
   apiKey?: string
   clientAgents?: string[]
-  headers?: Record<string, any>
+  requestConfig?: Partial<Omit<RequestInit, 'body' | 'method'>>
+  httpClient?: (input: string, init?: RequestInit) => Promise<any>
 }
 
 ///

tests/client.test.ts

@@ -49,16 +49,48 @@ describe.each([
     expect(health).toBe(true)
   })
 
-  test(`${permission} key: Create client with custom headers`, async () => {
+  test(`${permission} key: Create client with custom headers (object)`, async () => {
     const key = await getKey(permission)
     const client = new MeiliSearch({
       ...config,
       apiKey: key,
-      headers: {
-        Expect: '200-OK',
+      requestConfig: {
+        headers: {
+          Expect: '200-OK',
+        },
+      },
+    })
+    expect(client.httpRequest.headers['Expect']).toBe('200-OK')
+    const health = await client.isHealthy()
+    expect(health).toBe(true)
+  })
+
+  test(`${permission} key: Create client with custom headers (array)`, async () => {
+    const key = await getKey(permission)
+    const client = new MeiliSearch({
+      ...config,
+      apiKey: key,
+      requestConfig: {
+        headers: [['Expect', '200-OK']],
       },
     })
-    expect(client.config.headers).toStrictEqual({ Expect: '200-OK' })
+    expect(client.httpRequest.headers['Expect']).toBe('200-OK')
+    const health = await client.isHealthy()
+    expect(health).toBe(true)
+  })
+
+  test(`${permission} key: Create client with custom headers (Headers)`, async () => {
+    const key = await getKey(permission)
+    const headers = new Headers()
+    headers.append('Expect', '200-OK')
+    const client = new MeiliSearch({
+      ...config,
+      apiKey: key,
+      requestConfig: {
+        headers,
+      },
+    })
+    expect(client.httpRequest.headers.expect).toBe('200-OK')
     const health = await client.isHealthy()
     expect(health).toBe(true)
   })
@@ -169,11 +201,15 @@ describe.each([{ permission: 'Master' }, { permission: 'Admin' }])(
       const client = new MeiliSearch({
         ...config,
         apiKey: key,
-        headers: {
-          Expect: '200-OK',
+        requestConfig: {
+          headers: {
+            Expect: '200-OK',
+          },
         },
       })
-      expect(client.config.headers).toStrictEqual({ Expect: '200-OK' })
+      expect(client.config.requestConfig?.headers).toStrictEqual({
+        Expect: '200-OK',
+      })
       const health = await client.isHealthy()
 
       expect(health).toBe(true)
@@ -186,12 +222,46 @@ describe.each([{ permission: 'Master' }, { permission: 'Admin' }])(
       expect(results.length).toBe(1)
     })
 
+    test(`${permission} key: Create client with custom http client`, async () => {
+      const key = await getKey(permission)
+      const client = new MeiliSearch({
+        ...config,
+        apiKey: key,
+        async httpClient(url, init) {
+          const result = await fetch(url, init)
+          return result.json()
+        },
+      })
+      const health = await client.isHealthy()
+
+      expect(health).toBe(true)
+
+      const task = await client.createIndex('test')
+      await client.waitForTask(task.taskUid)
+
+      const { results } = await client.getIndexes()
+
+      expect(results.length).toBe(1)
+
+      const index = await client.getIndex('test')
+
+      const { taskUid } = await index.addDocuments([
+        { id: 1, title: 'index_2' },
+      ])
+      await client.waitForTask(taskUid)
+
+      const { results: documents } = await index.getDocuments()
+      expect(documents.length).toBe(1)
+    })
+
     test(`${permission} key: Create client with no custom client agents`, async () => {
       const key = await getKey(permission)
       const client = new MeiliSearch({
         ...config,
         apiKey: key,
-        headers: {},
+        requestConfig: {
+          headers: {},
+        },
       })
 
       expect(client.httpRequest.headers['X-Meilisearch-Client']).toStrictEqual(