Merge pull request #3 from BlackyDrum/main

Add static api authentication with bearer token

Author: CodeWithKyrian

.github/workflows/test.yml

@@ -15,11 +15,20 @@ jobs:
     name: Tests on PHP ${{ matrix.php }} - ${{ matrix.dependency-version }}
 
     services:
-      chroma:
+      chroma-wo-auth:
         image: chromadb/chroma
         ports:
           - 8000:8000
 
+      chroma-w-auth:
+        image: chromadb/chroma
+        ports:
+          - 8001:8000
+        env:
+          CHROMA_SERVER_AUTH_CREDENTIALS: 'test-token'
+          CHROMA_SERVER_AUTH_CREDENTIALS_PROVIDER: 'chromadb.auth.token.TokenConfigServerAuthCredentialsProvider'
+          CHROMA_SERVER_AUTH_PROVIDER: 'chromadb.auth.token.TokenAuthServerProvider'
+
     steps:
       - name: Checkout
         uses: actions/checkout@v3

README.md

@@ -136,7 +136,7 @@ composer require codewithkyrian/chromadb-php
 ```php
 use Codewithkyrian\ChromaDB\ChromaDB;
 
-$chromaDB = ChromaDB::client();
+$chroma = ChromaDB::client();
 
 ```
 
@@ -147,7 +147,7 @@ factory method:
 ```php
 use Codewithkyrian\ChromaDB\ChromaDB;
 
-$chromaDB = ChromaDB::factory()
+$chroma = ChromaDB::factory()
                 ->withHost('http://localhost')
                 ->withPort(8000)
                 ->withDatabase('new_database')
@@ -157,6 +157,47 @@ $chromaDB = ChromaDB::factory()
 
 If the tenant or database doesn't exist, the package will automatically create them for you.
 
+### Authentication
+
+ChromaDB supports static token-based authentication. To use it, you need to start the Chroma server passing the required
+environment variables as stated in the documentation. If you're using the docker image, you can pass in the environment
+variables using the `--env` flag or by using a `.env` file and for the docker-compose file, you can use the `env_file`
+option, or pass in the environment variables directly like so:
+
+```yaml
+version: '3.9'
+  
+services:
+  chroma:
+    image: 'chromadb/chroma'
+    ports:
+      - '8000:8000'
+    environment:
+      - CHROMA_SERVER_AUTH_CREDENTIALS=test-token
+      - CHROMA_SERVER_AUTH_CREDENTIALS_PROVIDER=chromadb.auth.token.TokenConfigServerAuthCredentialsProvider
+      - CHROMA_SERVER_AUTH_PROVIDER=chromadb.auth.token.TokenAuthServerProvider
+      
+    ...
+```   
+    
+You can then connect to ChromaDB using the factory method:
+
+```php
+use Codewithkyrian\ChromaDB\ChromaDB;
+
+$chroma = ChromaDB::factory()
+                ->withAuthToken('test-token')
+                ->connect();                
+```
+
+### Getting the version
+
+```php
+
+echo $chroma->version(); // 0.4.0
+
+```
+
 ### Creating a Collection
 
 Creating a collection is as simple as calling the `createCollection` method on the client and passing in the name of

docker-compose.yml

@@ -1,13 +1,16 @@
 version: '3.9'
 
 services:
-  server:
+  chroma_wo_auth:
     image: 'chromadb/chroma'
     ports:
       - '8000:8000'
-    volumes:
-      - chroma-data:/chroma/chroma
 
-volumes:
-  chroma-data:
-    driver: local
+  chroma_w_auth:
+    image: 'chromadb/chroma'
+    ports:
+      - '8001:8000'
+    environment:
+      CHROMA_SERVER_AUTH_CREDENTIALS: 'test-token'
+      CHROMA_SERVER_AUTH_CREDENTIALS_PROVIDER: 'chromadb.auth.token.TokenConfigServerAuthCredentialsProvider'
+      CHROMA_SERVER_AUTH_PROVIDER: 'chromadb.auth.token.TokenAuthServerProvider'

src/Factory.php

@@ -33,12 +33,16 @@ class Factory
      */
     protected string $tenant = 'default_tenant';
 
+    /**
+     * The bearer token used for authentication.
+     */
+    protected string $authToken;
+
     /**
      * The http client to use for the requests.
      */
     protected \GuzzleHttp\Client $httpClient;
 
-
     /**
      * The ChromaDB api provider for the instance.
      */
@@ -80,6 +84,15 @@ public function withTenant(string $tenant): self
         return $this;
     }
 
+    /**
+     * The bearer token used to authenticate requests.
+     */
+    public function withAuthToken(string $authToken): self
+    {
+        $this->authToken = $authToken;
+        return $this;
+    }
+
     /**
      * The http client to use for the requests.
      */
@@ -100,14 +113,20 @@ public function createApiClient() : ChromaApiClient
     {
         $this->baseUrl = $this->host . ':' . $this->port;
 
-        $this->httpClient ??=  new \GuzzleHttp\Client([
+        $headers = [
+            'Content-Type' => 'application/json',
+            'Accept' => 'application/json',
+        ];
+
+        if (!empty($this->authToken)) {
+            $headers['Authorization'] = 'Bearer ' . $this->authToken;
+        }
+
+        $this->httpClient ??= new \GuzzleHttp\Client([
             'base_uri' => $this->baseUrl,
-            'headers' => [
-                'Content-Type' => 'application/json',
-                'Accept' => 'application/json'
-            ],
+            'headers' => $headers,
         ]);
 
         return new ChromaApiClient($this->httpClient);
     }
-}
+}

src/Generated/ChromaApiClient.php

@@ -318,7 +318,7 @@ public function reset(): bool
 
     private function handleChromaApiException(\Exception|ClientExceptionInterface $e): void
     {
-        if ($e instanceof ServerException) {
+        if ($e instanceof ClientExceptionInterface) {
             $errorString = $e->getResponse()->getBody()->getContents();
 
             if (preg_match('/(?<={"\"error\"\:\")([^"]*)/', $errorString, $matches)) {
@@ -357,6 +357,11 @@ private function handleChromaApiException(\Exception|ClientExceptionInterface $e
                     ChromaException::throwSpecific($message, $error_type, $e->getCode());
                 }
 
+                // If the structure is {'error': 'Error Type', 'message' : 'Error message'}
+                if (isset($error['error']) && isset($error['message'])) {
+                    ChromaException::throwSpecific($error['message'], $error['error'], $e->getCode());
+                }
+
                 // If the structure is 'error' => 'Collection not found'
                 if (isset($error['error'])) {
                     $message = $error['error'];

src/Generated/Exceptions/ChromaAuthorizationException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+
+namespace Codewithkyrian\ChromaDB\Generated\Exceptions;
+
+class ChromaAuthorizationException extends ChromaException
+{
+
+}

src/Generated/Exceptions/ChromaException.php

@@ -12,6 +12,7 @@ public static function throwSpecific(string $message, string $type, int $code)
     {
         throw match ($type) {
             'NotFoundError' => new ChromaNotFoundException($message, $code),
+            'AuthorizationError' => new ChromaAuthorizationException($message, $code),
             'ValueError' => new ChromaValueException($message, $code),
             'UniqueConstraintError' => new ChromaUniqueConstraintException($message, $code),
             'DimensionalityError' => new ChromaDimensionalityException($message, $code),
@@ -25,6 +26,7 @@ public static function inferTypeFromMessage(string $message): string
     {
         return match (true) {
             str_contains($message, 'NotFoundError') => 'NotFoundError',
+            str_contains($message, 'AuthorizationError') => 'AuthorizationError',
             str_contains($message, 'UniqueConstraintError') => 'UniqueConstraintError',
             str_contains($message, 'ValueError') => 'ValueError',
             str_contains($message, 'dimensionality') => 'DimensionalityError',

tests/ChromaDB.php

@@ -4,18 +4,41 @@
 
 use Codewithkyrian\ChromaDB\Client;
 use Codewithkyrian\ChromaDB\ChromaDB;
+use Codewithkyrian\ChromaDB\Generated\Exceptions\ChromaAuthorizationException;
 
-it('can create a client instance', function () {
+it('can connect to a normal chroma server', function () {
     $client = ChromaDB::client();
 
     expect($client)->toBeInstanceOf(Client::class);
 });
 
-it('can create a client instance via factory', function () {
+it('can connect to a chroma server using factory', function () {
     $client = ChromaDB::factory()
         ->withHost('http://localhost')
         ->withPort(8000)
         ->connect();
 
     expect($client)->toBeInstanceOf(Client::class);
 });
+
+test('can connect to an API token authenticated chroma server', function () {
+    $client = ChromaDB::factory()
+        ->withPort(8001)
+        ->withAuthToken('test-token')
+        ->connect();
+
+    expect($client)->toBeInstanceOf(Client::class);
+});
+
+it('cannot connect to an API token authenticated chroma server with wrong token', function () {
+    ChromaDB::factory()
+        ->withPort(8001)
+        ->withAuthToken('wrong-token')
+        ->connect();
+})->throws(ChromaAuthorizationException::class);
+
+it('throws exception when connecting to API token authenticated chroma server with no token', function () {
+    ChromaDB::factory()
+        ->withPort(8001)
+        ->connect();
+})->throws(ChromaAuthorizationException::class);