⬆️(backend) upgrade docspec to v3.0.0 and adapt converter API

Summary

- Bump docspec Docker image from `2.6.3` to `3.0.0` and adapt
`DocSpecConverter` to the new API (raw body upload with explicit
`Content-Type`/`Accept` headers instead of multipart form)

Important

**The Docker image (`ghcr.io/docspecio/api:3.0.0`) must be updated
alongside the code changes.** The new request format is incompatible
with v2.x — deploying only the code without updating the image (or vice
versa) will break document conversion.

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to
 - 🚸(frontend) show Crisp from the help menu #2222
 - ♿️(frontend) structure correctly 5xx error alerts #2128
 - ♿️(frontend) make doc search result labels uniquely identifiable #2212
+- ⬆️(backend) upgrade docspec to v3.0.x and adapt converter API #2220
 
 ### Fixed
 

compose.yml

@@ -29,8 +29,8 @@ services:
       - MINIO_ROOT_USER=impress
       - MINIO_ROOT_PASSWORD=password
     ports:
-      - '9000:9000'
-      - '9001:9001'
+      - "9000:9000"
+      - "9001:9001"
     healthcheck:
       test: ["CMD", "mc", "ready", "local"]
       interval: 1s
@@ -81,16 +81,16 @@ services:
       - ./src/backend:/app
       - ./data/static:/data/static
     depends_on:
-        postgresql:
-            condition: service_healthy
-            restart: true
-        mailcatcher:
-          condition: service_started
-        redis:
-          condition: service_started
-        createbuckets:
-          condition: service_started
-  
+      postgresql:
+        condition: service_healthy
+        restart: true
+      mailcatcher:
+        condition: service_started
+      redis:
+        condition: service_started
+      createbuckets:
+        condition: service_started
+
   celery-dev:
     user: ${DOCKER_USER:-1000}
     image: impress:backend-development
@@ -143,7 +143,7 @@ services:
 
   frontend-development:
     user: "${DOCKER_USER:-1000}"
-    build: 
+    build:
       context: .
       dockerfile: ./src/frontend/Dockerfile
       target: impress-dev
@@ -173,13 +173,13 @@ services:
     image: node:22
     user: "${DOCKER_USER:-1000}"
     environment:
-      HOME: /tmp 
+      HOME: /tmp
     volumes:
       - ".:/app"
 
   y-provider-development:
     user: ${DOCKER_USER:-1000}
-    build: 
+    build:
       context: .
       dockerfile: ./src/frontend/servers/y-provider/Dockerfile
       target: y-provider-development
@@ -221,7 +221,11 @@ services:
       - --health-enabled=true
       - --metrics-enabled=true
     healthcheck:
-      test: ['CMD-SHELL', 'exec 3<>/dev/tcp/localhost/9000; echo -e "GET /health/live HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n" >&3; grep "HTTP/1.1 200 OK" <&3']
+      test:
+        [
+          "CMD-SHELL",
+          'exec 3<>/dev/tcp/localhost/9000; echo -e "GET /health/live HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n" >&3; grep "HTTP/1.1 200 OK" <&3',
+        ]
       start_period: 5s
       interval: 1s
       timeout: 2s
@@ -235,7 +239,7 @@ services:
       KC_DB_PASSWORD: pass
       KC_DB_USERNAME: impress
       KC_DB_SCHEMA: public
-      PROXY_ADDRESS_FORWARDING: 'true'
+      PROXY_ADDRESS_FORWARDING: "true"
     ports:
       - "8080:8080"
     depends_on:
@@ -244,7 +248,7 @@ services:
         restart: true
 
   docspec:
-    image: ghcr.io/docspecio/api:2.6.3
+    image: ghcr.io/docspecio/api:3.0.1
     ports:
       - "4000:4000"
 

src/backend/core/services/converter_services.py

@@ -49,7 +49,7 @@ class Converter:
 
         if content_type == mime_types.DOCX and accept == mime_types.YJS:
             blocknote_data = self.docspec.convert(
-                data, mime_types.DOCX, mime_types.BLOCKNOTE
+                data, content_type, mime_types.BLOCKNOTE
             )
             return self.ydoc.convert(
                 blocknote_data, mime_types.BLOCKNOTE, mime_types.YJS
@@ -66,8 +66,11 @@ class DocSpecConverter:
 
         response = requests.post(
             url,
-            headers={"Accept": mime_types.BLOCKNOTE},
-            files={"file": ("document.docx", data, content_type)},
+            headers={
+                "Content-Type": content_type,
+                "Accept": mime_types.BLOCKNOTE,
+            },
+            data=data,
             timeout=settings.CONVERSION_API_TIMEOUT,
             verify=settings.CONVERSION_API_SECURE,
         )

src/backend/core/tests/test_services_docspec_converter.py

@@ -110,8 +110,11 @@ def test_docspec_convert_success(mock_post, settings):
     # Verify the request was made correctly
     mock_post.assert_called_once_with(
         "http://docspec.test/convert",
-        headers={"Accept": mime_types.BLOCKNOTE},
-        files={"file": ("document.docx", docx_data, mime_types.DOCX)},
+        headers={
+            "Content-Type": mime_types.DOCX,
+            "Accept": mime_types.BLOCKNOTE,
+        },
+        data=docx_data,
         timeout=5,
         verify=False,
     )

src/helm/env.d/dev/values.impress.yaml.gotmpl

@@ -178,7 +178,7 @@ docSpec:
   image:
     repository: ghcr.io/docspecio/api
     pullPolicy: IfNotPresent
-    tag: "2.6.3"
+    tag: "3.0.1"
 
   probes:
     liveness:

src/helm/env.d/feature/values.impress.yaml.gotmpl

@@ -154,7 +154,7 @@ docSpec:
   image:
     repository: ghcr.io/docspecio/api
     pullPolicy: IfNotPresent
-    tag: "2.6.3"
+    tag: "3.0.1"
 
   probes:
     liveness:

src/helm/impress/values.yaml

@@ -768,7 +768,7 @@ docSpec:
   image:
     repository: ghcr.io/docspecio/api
     pullPolicy: IfNotPresent
-    tag: "2.6.3"
+    tag: "3.0.1"
 
   ## @param docSpec.command Override the docSpec container command
   command: []