Chroma v2 API, pull requests 80 and 82, and fixes: continued in ChromaDotNet.Client

.devcontainer/devcontainer.json

@@ -0,0 +1,17 @@
+{
+	"name": "ChromaDB.Client with Chroma",
+	"dockerComposeFile": "docker-compose.yml",
+	"service": "app",
+	"workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
+	"forwardPorts": [8000],
+	"portsAttributes": {
+		"8000": { "label": "Chroma" }
+	},
+	"postCreateCommand": "dotnet --version",
+	"postAttachCommand": "echo 'Chroma is on http://localhost:8000. Try the client: dotnet run Samples/quickstart.cs'",
+	"customizations": {
+		"vscode": {
+			"extensions": ["ms-dotnettools.csharp"]
+		}
+	}
+}

.devcontainer/docker-compose.yml

@@ -0,0 +1,12 @@
+services:
+  app:
+    image: mcr.microsoft.com/devcontainers/dotnet:1-10.0
+    volumes:
+      - ../..:/workspaces:cached
+    command: sleep infinity
+    # Chroma answers on localhost:8000 inside the app container too.
+    network_mode: service:chroma
+
+  chroma:
+    image: chromadb/chroma:1.5.9
+    restart: unless-stopped

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# The maintainers review every change.
+* @ChromaDotNet/maintainers

.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  # Security updates only: the library keeps the lowest versions of its dependencies on purpose.
+  - package-ecosystem: nuget
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 0
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns:
+          - '*'

.github/workflows/ci.yml

@@ -4,23 +4,55 @@ on:
   push:
     branches:
       - master
+      - main
     tags:
       - v*
   pull_request:
   schedule:
     - cron: '4 13 * * 2'
 
+permissions:
+  contents: read
+
 env:
   CONFIGURATION: Release
   DOTNET_VERSION: 8.0.x
+  # The seed of the property tests, so that every run checks the same cases: without it, each run takes new ones.
+  FSCHECK_REPLAY: '(5123468595321266860,8907826574119387873)'
 
 jobs:
   ci:
     runs-on: ubuntu-latest
-    name: ${{ github.event_name != 'schedule' && 'CI' || 'CI (schedule)' }}
+    name: ${{ github.event_name != 'schedule' && 'CI' || 'CI (schedule)' }} (Chroma ${{ matrix.chroma }})
+    strategy:
+      fail-fast: false
+      matrix:
+        # v2 API: 0.5.16, the first release with it; 0.5.20, the first that rejects embeddings of different dimensions;
+        # 0.6.3, the last 0.x; 1.0.0, the first 1.x; 1.5.9, the current release; latest catches new releases without blocking.
+        chroma: ['0.5.16', '0.5.20', '0.6.3', '1.0.0', '1.5.9', 'latest']
+        include:
+          # v1 API, with ChromaApiVersion.V1: 0.4.10, without tenants and databases; 0.4.15, without count_collections
+          # and $not_contains; 0.4.23, with both; 0.5.15, the last release with only the v1 API. See docs/COMPATIBILITY.md.
+          - chroma: '0.4.10'
+            api: v1
+          - chroma: '0.4.15'
+            api: v1
+          - chroma: '0.4.23'
+            api: v1
+          - chroma: '0.5.15'
+            api: v1
+          - chroma: '1.5.9'
+            pack: true
+    continue-on-error: ${{ matrix.chroma == 'latest' }}
+    env:
+      CHROMA_IMAGE: chromadb/chroma:${{ matrix.chroma }}
+      CHROMA_TEST_API_VERSION: ${{ matrix.api }}
+      # An environment variable, so that the restore in the Build step reads it too:
+      # pack --no-build takes the package id of the referenced client project from that restore.
+      PackageIdPrefix: ${{ vars.PACKAGE_ID_PREFIX }}
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
 
     - name: CI version suffix
       if: ${{ !startsWith(github.ref, 'refs/tags/v') }}
@@ -31,7 +63,7 @@ jobs:
       run: echo 'VERSION_SUFFIX=' >> $GITHUB_ENV
 
     - name: Setup .NET
-      uses: actions/setup-dotnet@v4
+      uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4
       with:
         dotnet-version: ${{ env.DOTNET_VERSION }}
 
@@ -41,34 +73,166 @@ jobs:
     - name: Test
       run: dotnet test -c ${{ env.CONFIGURATION }} --no-build --verbosity normal --logger 'GitHubActions;summary.includePassedTests=true;summary.includeSkippedTests=true'
 
+    - name: Test in a non-default tenant and database
+      run: dotnet test -c ${{ env.CONFIGURATION }} --no-build --verbosity normal --logger 'GitHubActions;summary.includePassedTests=true;summary.includeSkippedTests=true'
+      env:
+        CHROMA_TEST_TENANT: test_tenant
+        CHROMA_TEST_DATABASE: test_database
+
     - name: Pack
+      if: ${{ matrix.pack }}
       run: dotnet pack -c ${{ env.CONFIGURATION }} --no-build --version-suffix '${{ env.VERSION_SUFFIX }}'
 
+    # The release notes of every package link the GitHub release of its version, so they cannot stay at an older one.
+    - name: Check the release notes of the packages
+      if: ${{ matrix.pack }}
+      run: |
+        status=0
+        for pkg in $(find . -path '*/bin/*' -name '*.nupkg'); do
+          nuspec=$(unzip -p "$pkg" '*.nuspec')
+          version=$(echo "$nuspec" | sed -n 's:.*<version>\([0-9.]*\).*</version>.*:\1:p')
+          if echo "$nuspec" | grep -Eq "<releaseNotes>.*/releases/tag/v$(echo "$version" | sed 's/\./\\./g')([^0-9]|$)"; then
+            echo "$(basename "$pkg"): the release notes link the release v$version"
+          else
+            echo "::error::$(basename "$pkg"): the release notes do not link the release v$version"
+            status=1
+          fi
+        done
+        exit $status
+
     - name: Upload
-      if: ${{ github.event_name != 'schedule' }}
-      uses: actions/upload-artifact@v4
+      if: ${{ matrix.pack && github.event_name != 'schedule' }}
+      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
       with:
         name: packages
         path: |
           **/*.nupkg
           **/*.snupkg
 
+    # An application on .NET 6 or 7 takes the netstandard2.0 build: the packages it brings must not warn that they do
+    # not support it. Built outside the repository, so its props do not apply, with -warnaserror, which turns the
+    # warnings of the targets of a package into errors (TreatWarningsAsErrors only covers the compiler).
+    - name: Build applications on .NET 6 and 7 with the package
+      if: ${{ matrix.pack }}
+      run: |
+        pkgdir="$GITHUB_WORKSPACE/ChromaDB.Client/bin/${{ env.CONFIGURATION }}"
+        file=$(basename "$(ls "$pkgdir"/*.nupkg | head -1)" .nupkg)
+        id=$(echo "$file" | sed -E 's/\.[0-9]+\.[0-9]+\.[0-9]+.*$//')
+        version="${file#$id.}"
+        mkdir -p "$RUNNER_TEMP/consumer" && cd "$RUNNER_TEMP/consumer"
+        cat > Consumer.csproj <<XML
+        <Project Sdk="Microsoft.NET.Sdk">
+          <PropertyGroup>
+            <OutputType>Exe</OutputType>
+            <TargetFrameworks>net6.0;net7.0</TargetFrameworks>
+            <CheckEolTargetFramework>false</CheckEolTargetFramework>
+            <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+          </PropertyGroup>
+          <ItemGroup>
+            <PackageReference Include="$id" Version="[$version]" />
+          </ItemGroup>
+        </Project>
+        XML
+        echo 'System.Console.WriteLine(new ChromaDB.Client.ChromaConfigurationOptions("http://localhost:8000").Uri);' > Program.cs
+        dotnet build -warnaserror -p:RestoreSources="https://api.nuget.org/v3/index.json;$pkgdir"
+
+    # Runs after Pack: it rebuilds the netstandard2.0 client without the version suffix.
+    - name: Test the netstandard2.0 build
+      if: ${{ matrix.pack }}
+      run: dotnet test ChromaDB.Client.Tests -c ${{ env.CONFIGURATION }} -p:ChromaClientTargetFramework=netstandard2.0 --verbosity normal --logger 'GitHubActions;summary.includePassedTests=true;summary.includeSkippedTests=true'
+
+  trimming:
+    # The client published with trimming and with NativeAOT, where reflection-based serialization is off,
+    # running real requests: Samples/ChromaDB.Client.TrimmingTest. Every trimming or AOT warning is an error.
+    # --lists: Chroma 1.5.9 stores lists in metadata, so a rejected list is a failure.
+    runs-on: ubuntu-latest
+    name: Trimming and NativeAOT
+    services:
+      chroma:
+        image: chromadb/chroma:1.5.9
+        ports:
+          - 8000:8000
+
+    steps:
+    - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+    - name: Setup .NET
+      uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4
+      with:
+        dotnet-version: ${{ env.DOTNET_VERSION }}
+
+    - name: NativeAOT prerequisites
+      run: sudo apt-get install -y clang zlib1g-dev
+
+    - name: Wait for Chroma
+      run: for i in $(seq 1 60); do curl -sf http://localhost:8000/api/v2/heartbeat && break; sleep 1; done
+
+    - name: Publish with trimming
+      run: dotnet publish Samples/ChromaDB.Client.TrimmingTest -c ${{ env.CONFIGURATION }} -r linux-x64 -o trimmed -p:TreatWarningsAsErrors=true
+
+    - name: Run with trimming
+      run: ./trimmed/ChromaDB.Client.TrimmingTest http://localhost:8000 --lists
+
+    - name: Publish with NativeAOT
+      run: dotnet publish Samples/ChromaDB.Client.TrimmingTest -c ${{ env.CONFIGURATION }} -r linux-x64 -o aot -p:TrimmingTestAot=true -p:TreatWarningsAsErrors=true
+
+    - name: Run with NativeAOT
+      run: ./aot/ChromaDB.Client.TrimmingTest http://localhost:8000 --lists
+
+  framework:
+    # The tests whose outcome depends on the runtime, on .NET Framework 4.8, where the client runs its net462 build and
+    # the runtime formats and parses numbers in its own way: ChromaDB.Client.FrameworkTests, with no server.
+    runs-on: windows-latest
+    name: .NET Framework
+
+    steps:
+    - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+    - name: Setup .NET
+      uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4
+      with:
+        dotnet-version: ${{ env.DOTNET_VERSION }}
+
+    - name: Test on .NET Framework 4.8
+      run: dotnet test ChromaDB.Client.FrameworkTests -c ${{ env.CONFIGURATION }} --verbosity normal
+
   publish:
-    needs: ci
-    if: ${{ github.repository == 'ssone95/ChromaDB.Client' && (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/v')) && github.event_name != 'schedule' }}
+    needs: [ci, trimming, framework]
+    # Publishes the version tags: with the NUGET_API_KEY secret in the original repository, and with NuGet trusted
+    # publishing where the NUGET_USER variable is set. The original repository publishes the default branch too; elsewhere
+    # its pushes leave the packages as artifacts of the run.
+    if: ${{ github.event_name != 'schedule' && (startsWith(github.ref, 'refs/tags/v') && (github.repository == 'ssone95/ChromaDB.Client' || vars.NUGET_USER != '') || github.repository == 'ssone95/ChromaDB.Client' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)) }}
     runs-on: ubuntu-latest
     name: Publish
+    environment: nuget
+    permissions:
+      attestations: write
+      contents: read
+      id-token: write
 
     steps:
     - name: Setup .NET
-      uses: actions/setup-dotnet@v4
+      uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4
       with:
         dotnet-version: ${{ env.DOTNET_VERSION }}
 
     - name: Download
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
       with:
         name: packages
 
+    - name: Attest build provenance
+      if: ${{ startsWith(github.ref, 'refs/tags/v') }}
+      uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+      with:
+        subject-path: '**/*.nupkg'
+
+    - name: NuGet login
+      if: ${{ vars.NUGET_USER != '' }}
+      id: login
+      uses: NuGet/login@8d196754b4036150537f80ac539e15c2f1028841 # v1
+      with:
+        user: ${{ vars.NUGET_USER }}
+
     - name: Publish to NuGet.org
-      run: dotnet nuget push '**/*.nupkg' --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json
+      run: dotnet nuget push '**/*.nupkg' --api-key ${{ steps.login.outputs.NUGET_API_KEY || secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate

.github/workflows/codeql.yml

@@ -0,0 +1,36 @@
+name: CodeQL
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  schedule:
+    - cron: '17 5 * * 1'
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze C#
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+      with:
+        languages: csharp
+        build-mode: none
+
+    - name: Analyze
+      uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+      with:
+        category: /language:csharp