feat(ifc)!: Display Value proxies for IFC importer (#466)

* First pass

* Add applicationId for proxyInstance

* renamed revit instances

* renamed collection again

* again

* reverted main changes for manual testing

* small refactor of function def

* format matix

.github/workflows/pr.yml

@@ -9,8 +9,55 @@ on:
       - "main"
 
 jobs:
-  test:
-    name: test
+  test-internal: # Run integration tests against the internal server image
+    name: Test (internal)
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install the project
+        run: uv sync --all-extras --dev
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: "ghcr.io"
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Run Speckle Server
+        run: docker compose --file docker-compose-internal.yml up --detach --wait
+
+      - name: Run tests
+        run: uv run pytest --cov --cov-report xml:reports/coverage.xml --junitxml=reports/test-results.xml
+
+      - uses: codecov/codecov-action@v5
+        if: matrix.python-version == 3.12
+        with:
+          fail_ci_if_error: true # optional (default = false)
+          files: ./reports/test-results.xml # optional
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci
+
+  test-public: # Run integration tests against the public server image
+    name: Test (public)
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -42,17 +89,10 @@ jobs:
         run: uv run pre-commit run --all-files
 
       - name: Run Speckle Server
-        run: docker compose up --detach --wait
+        run: docker compose --file docker-compose.yml up --detach --wait
 
       - name: Run tests
         run: uv run pytest --cov --cov-report xml:reports/coverage.xml --junitxml=reports/test-results.xml
 
-      - uses: codecov/codecov-action@v5
-        if: matrix.python-version == 3.12
-        with:
-          fail_ci_if_error: true # optional (default = false)
-          files: ./reports/test-results.xml # optional
-          token: ${{ secrets.CODECOV_TOKEN }}
-
       - name: Minimize uv cache
         run: uv cache prune --ci

docker-compose-internal.yml

@@ -0,0 +1,118 @@
+name: "speckle-server"
+
+services:
+  ####
+  # Speckle Server dependencies
+  #######
+  postgres:
+    image: "postgres:16.4-alpine3.20@sha256:d898b0b78a2627cb4ee63464a14efc9d296884f1b28c841b0ab7d7c42f1fffdf"
+    restart: always
+    environment:
+      POSTGRES_DB: speckle
+      POSTGRES_USER: speckle
+      POSTGRES_PASSWORD: speckle
+    volumes:
+      - ./.volumes/postgres-data:/var/lib/postgresql/data/
+    healthcheck:
+      # the -U user has to match the POSTGRES_USER value
+      test: ["CMD-SHELL", "pg_isready -U speckle"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+
+  redis:
+    image: "valkey/valkey:8.1-alpine@sha256:0d27f0bca0249f61d060029a6aaf2e16b2c417d68d02a508e1dfb763fa2948b4"
+    restart: always
+    volumes:
+      - ./.volumes/redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "--raw", "incr", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+
+  minio:
+    image: "minio/minio:RELEASE.2023-10-25T06-33-25Z"
+    command: server /data --console-address ":9001"
+    restart: always
+    volumes:
+      - ./.volumes/minio-data:/data
+    ports:
+      - '127.0.0.1:9000:9000'
+      - '127.0.0.1:9001:9001'
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "curl -s -o /dev/null http://127.0.0.1:9000/minio/index.html",
+        ]
+      interval: 5s
+      timeout: 30s
+      retries: 30
+      start_period: 10s
+
+  speckle-server:
+    image: ghcr.io/specklesystems/speckle-server:latest
+    restart: always
+    healthcheck:
+      test:
+        - CMD
+        - /nodejs/bin/node
+        - -e
+        - "try { require('node:http').request({headers: {'Content-Type': 'application/json'}, port:3000, hostname:'127.0.0.1', path:'/readiness', method: 'GET', timeout: 2000 }, (res) => { body = ''; res.on('data', (chunk) => {body += chunk;}); res.on('end', () => {process.exit(Number(res.statusCode != 200 || body.toLowerCase().includes('error')));}); }).end(); } catch { process.exit(1); }"
+      interval: 10s
+      timeout: 10s
+      retries: 3
+      start_period: 90s
+    ports:
+      - "0.0.0.0:3000:3000"
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+    environment:
+      # TODO: Change this to the URL of the speckle server, as accessed from the network
+      CANONICAL_URL: "http://127.0.0.1:8080"
+      SPECKLE_AUTOMATE_URL: "http://127.0.0.1:3030"
+      FRONTEND_ORIGIN: "http://127.0.0.1:8081"
+
+      # TODO: Change thvolumes:
+      REDIS_URL: "redis://redis"
+
+      S3_ENDPOINT: "http://minio:9000"
+      S3_PUBLIC_ENDPOINT: "http://127.0.0.1:9000"
+      S3_ACCESS_KEY: "minioadmin"
+      S3_SECRET_KEY: "minioadmin"
+      S3_BUCKET: "speckle-server"
+      S3_CREATE_BUCKET: "true"
+
+      FILE_SIZE_LIMIT_MB: 100
+      MAX_PROJECT_MODELS_PER_PAGE: 500
+
+      # TODO: Change this to a unique secret for this server
+      SESSION_SECRET: "TODO:ReplaceWithLongString"
+
+      STRATEGY_LOCAL: "true"
+
+      POSTGRES_URL: "postgres"
+      POSTGRES_USER: "speckle"
+      POSTGRES_PASSWORD: "speckle"
+      POSTGRES_DB: "speckle"
+      ENABLE_MP: "false"
+
+      LOG_PRETTY: "true"
+
+      FF_NEXT_GEN_FILE_IMPORTER_ENABLED: "true"
+      FF_LARGE_FILE_IMPORTS_ENABLED: "true"
+
+networks:
+  default:
+    name: speckle-server
+
+volumes:
+  postgres-data:
+  redis-data:
+  minio-data:

docker-compose.yml

@@ -1,4 +1,3 @@
-version: "3.9"
 name: "speckle-server"
 
 services:
@@ -22,7 +21,7 @@ services:
       retries: 30
 
   redis:
-    image: "redis:6.0-alpine"
+    image: "valkey/valkey:8.1-alpine@sha256:0d27f0bca0249f61d060029a6aaf2e16b2c417d68d02a508e1dfb763fa2948b4"
     restart: always
     volumes:
       - ./.volumes/redis-data:/data
@@ -38,6 +37,9 @@ services:
     restart: always
     volumes:
       - ./.volumes/minio-data:/data
+    ports:
+      - '127.0.0.1:9000:9000'
+      - '127.0.0.1:9001:9001'
     healthcheck:
       test:
         [
@@ -48,8 +50,6 @@ services:
       timeout: 30s
       retries: 30
       start_period: 10s
-    ports:
-      - "0.0.0.0:9000:9000"
 
   speckle-server:
     image: speckle/speckle-server:latest
@@ -96,7 +96,6 @@ services:
       SESSION_SECRET: "TODO:ReplaceWithLongString"
 
       STRATEGY_LOCAL: "true"
-      DEBUG: "speckle:*"
 
       POSTGRES_URL: "postgres"
       POSTGRES_USER: "speckle"
@@ -104,9 +103,10 @@ services:
       POSTGRES_DB: "speckle"
       ENABLE_MP: "false"
 
+      LOG_PRETTY: "true"
+
       FF_NEXT_GEN_FILE_IMPORTER_ENABLED: "true"
       FF_LARGE_FILE_IMPORTS_ENABLED: "true"
-      FF_BACKGROUND_JOBS_ENABLED: "true"
 
 networks:
   default:

pyproject.toml

@@ -11,7 +11,7 @@ dependencies = [
     "appdirs>=1.4.4",
     "attrs>=24.3.0",
     "deprecated>=1.2.15",
-    "gql[requests,websockets]>=3.5.0",
+    "gql[requests,websockets]>=3.5.0,<4.0.0",
     "httpx>=0.28.1",
     "pydantic>=2.10.5",
     "pydantic-settings>=2.7.1",

src/speckleifc/converter/geometry_converter.py

@@ -4,21 +4,21 @@ from typing import cast
 
 from ifcopenshell.ifcopenshell_wrapper import (
     Triangulation,
-    TriangulationElement,
     colour,
     style,
 )
 
-from speckleifc.render_material_proxy_manager import RenderMaterialProxyManager
+from speckleifc.proxy_managers.render_material_proxy_manager import (
+    RenderMaterialProxyManager,
+)
 from specklepy.objects.base import Base
 from specklepy.objects.geometry import Mesh
 from specklepy.objects.other import RenderMaterial
 
 
 def geometry_to_speckle(
-    shape: TriangulationElement, render_material_manager: RenderMaterialProxyManager
+    geometry: Triangulation, render_material_manager: RenderMaterialProxyManager
 ) -> list[Base]:
-    geometry = cast(Triangulation, shape.geometry)
     materials = cast(Sequence[style], geometry.materials)
     MESH_COUNT = max(len(materials), 1)
 
@@ -33,7 +33,7 @@ def geometry_to_speckle(
         # Not really expected, but occasionally some meshes fail to triangulate
         return []
 
-    mapped_meshes = _pre_alloc_mesh_lists(shape, material_ids, MESH_COUNT)
+    mapped_meshes = _pre_alloc_mesh_lists(geometry, material_ids, MESH_COUNT)
     for i, mesh in enumerate(mapped_meshes):
         material = _material_to_speckle(materials[i])
         render_material_manager.add_mesh_material_mapping(material, mesh)
@@ -103,14 +103,14 @@ def _color_to_argb(colour: colour) -> int:
 
 
 def _pre_alloc_mesh_lists(
-    shape: TriangulationElement, material_ids: Sequence[int], MESH_COUNT: int
+    geometry: Triangulation, material_ids: Sequence[int], MESH_COUNT: int
 ) -> list[Mesh]:
     """
     This is a performance optimisation to pre-size the lists
     since we're expecting potential hundreds of thousands of verts in a single model
     This is very much in the hot path, so worth the extra bit of convoluted logic
     """
-    appId = cast(str, shape.guid)
+    appId = cast(str, geometry.id)
 
     material_face_counts = defaultdict(int)
     for mat_id in material_ids:

src/speckleifc/ifc_geometry_processing.py

@@ -1,6 +1,6 @@
 import multiprocessing
 
-from ifcopenshell import file, ifcopenshell_wrapper, open, sqlite
+from ifcopenshell import SchemaError, file, ifcopenshell_wrapper, open, sqlite
 from ifcopenshell.geom import iterator, settings
 
 from specklepy.logging.exceptions import SpeckleException
@@ -12,8 +12,10 @@ def _create_iterator_settings() -> settings:
     ifc_settings.set("triangulation-type", ifcopenshell_wrapper.TRIANGLE_MESH)
     # no need to weld verts
     ifc_settings.set("weld-vertices", False)
-    # Speckle meshes are all in world coords
-    ifc_settings.set("use-world-coords", True)
+    #
+    ifc_settings.set("use-world-coords", False)
+    ifc_settings.set("permissive-shape-reuse", True)
+
     # Tiny performance improvement,
     ifc_settings.set("no-wire-intersection-check", True)
     # Rendermaterials inherit the material names instead of type + unique id
@@ -33,7 +35,14 @@ def _create_iterator_settings() -> settings:
 
 
 def open_ifc(file_path: str) -> file:
-    ifc_file = open(file_path)
+    try:
+        ifc_file = open(file_path)
+    except SchemaError:
+        raise
+    except FileNotFoundError:
+        raise
+    except Exception as ex:
+        raise SpeckleException("File could not be opened as an IFC file") from ex
 
     if isinstance(ifc_file, file):
         return ifc_file

src/speckleifc/importer.py

@@ -1,10 +1,10 @@
 import time
 from dataclasses import dataclass, field
-from typing import cast
+from typing import List, cast
 
 from ifcopenshell.entity_instance import entity_instance
 from ifcopenshell.geom import file
-from ifcopenshell.ifcopenshell_wrapper import TriangulationElement
+from ifcopenshell.ifcopenshell_wrapper import Triangulation, TriangulationElement
 
 from speckleifc.converter.data_object_converter import data_object_to_speckle
 from speckleifc.converter.geometry_converter import geometry_to_speckle
@@ -12,41 +12,63 @@ from speckleifc.converter.project_converter import project_to_speckle
 from speckleifc.converter.spatial_element_converter import spatial_element_to_speckle
 from speckleifc.ifc_geometry_processing import create_geometry_iterator
 from speckleifc.ifc_openshell_helpers import get_children
-from speckleifc.level_proxy_manager import LevelProxyManager
-from speckleifc.render_material_proxy_manager import RenderMaterialProxyManager
+from speckleifc.proxy_managers.instance_proxy_manager import InstanceProxyManager
+from speckleifc.proxy_managers.level_proxy_manager import LevelProxyManager
+from speckleifc.proxy_managers.render_material_proxy_manager import (
+    RenderMaterialProxyManager,
+)
 from specklepy.logging.exceptions import SpeckleException
 from specklepy.objects import Base
 from specklepy.objects.data_objects import DataObject
+from specklepy.objects.models.collections.collection import Collection
+from specklepy.objects.proxies import InstanceProxy
 
 
 @dataclass
 class ImportJob:
     ifc_file: file
-    cached_display_values: dict[int, list[Base]] = field(default_factory=dict)  # noqa: F821
+
     _render_material_manager: RenderMaterialProxyManager = field(
         default_factory=lambda: RenderMaterialProxyManager()
     )
     _level_proxy_manager: LevelProxyManager = field(
         default_factory=lambda: LevelProxyManager()
     )
+    _instance_proxy_manager: InstanceProxyManager = field(
+        default_factory=lambda: InstanceProxyManager()
+    )
     geometries_count: int = 0
     geometries_used: int = 0
     _current_storey_data_object: DataObject | None = field(default=None, init=False)
 
+    _display_value_cache: dict[int, list[Base]] = field(default_factory=dict)
+    """Maps an instance step ID to a list of instances"""
+
     def convert_element(self, step_element: entity_instance) -> Base:
+        try:
+            return self._convert_element(step_element)
+        except SpeckleException:
+            raise
+        except Exception as ex:
+            raise SpeckleException(
+                f"Failed to convert {step_element.is_a()} #{step_element.id()}"
+            ) from ex
+
+    def _convert_element(self, step_element: entity_instance) -> Base:
         # Track current storey context and store for level proxies
         previous_storey_data_object = self._current_storey_data_object
         if step_element.is_a("IfcBuildingStorey"):
             # Convert the building storey to a DataObject for the level proxy
-            storey_display_value = self.cached_display_values.get(step_element.id(), [])
+            storey_display_value = self._display_value_cache.get(step_element.id(), [])
             self._current_storey_data_object = data_object_to_speckle(
                 storey_display_value, step_element, []
             )
 
         children = self._convert_children(step_element)
-        display_value = self.cached_display_values.get(step_element.id(), [])
+        id = step_element.id()
+        display_value = self._display_value_cache.get(id, [])
 
-        if display_value is not None:
+        if display_value:
             self.geometries_used += 1
 
         # Extract current storey name from DataObject if available
@@ -110,21 +132,53 @@ class ImportJob:
     def pre_process_geometry(self) -> None:
         iterator = create_geometry_iterator(self.ifc_file)
         if not iterator.initialize():
-            raise SpeckleException(
-                "geometry iterator failed to initialize for the given file"
-            )
+            raise SpeckleException("Failed to find any geometry in file")
         self.geometries_count = 0
         while True:
             shape = cast(TriangulationElement, iterator.get())
             self.geometries_count += 1
             id = cast(int, shape.id)
-
-            display_value = geometry_to_speckle(shape, self._render_material_manager)
-            self.cached_display_values[id] = display_value
-
+            try:
+                display_value = self._create_display_value(shape)
+                self._display_value_cache[id] = display_value
+            except Exception as ex:
+                raise SpeckleException(
+                    f"Failed to convert geometry with id: {id}"
+                ) from ex
             if not iterator.next():
                 break
 
+    def _create_display_value(self, shape: TriangulationElement) -> List[Base]:
+        geometry = cast(Triangulation, shape.geometry)
+        display_value_geometry = geometry_to_speckle(
+            geometry, self._render_material_manager
+        )
+
+        definition_ids = self._instance_proxy_manager.add_display_value_definitions(
+            display_value_geometry
+        )
+        matrix = shape.transformation.matrix
+        transposed = [
+            matrix[0], matrix[4], matrix[8], matrix[12],
+            matrix[1], matrix[5], matrix[9], matrix[13],
+            matrix[2], matrix[6], matrix[10], matrix[14],
+            matrix[3], matrix[7], matrix[11], matrix[15],
+        ]  # fmt: skip
+
+        return [
+            cast(
+                Base,
+                InstanceProxy(
+                    units="m",
+                    definitionId=definition_id,
+                    transform=transposed,
+                    maxDepth=0,
+                    applicationId=f"{shape.guid}:{definition_id}",
+                ),
+            )
+            for definition_id in definition_ids
+        ]
+
     def _convert_project_tree(self) -> Base:
         projects = self.ifc_file.by_type("IfcProject", False)
         if len(projects) != 1:
@@ -132,10 +186,22 @@ class ImportJob:
         project = projects[0]
 
         tree = self.convert_element(project)
+        if not isinstance(tree, Collection):
+            raise TypeError("Expected root object to convert to a Collection")
+
         tree["renderMaterialProxies"] = list(
             self._render_material_manager.render_material_proxies.values()
         )
         tree["levelProxies"] = list(self._level_proxy_manager.level_proxies.values())
+        tree["instanceDefinitionProxies"] = list(
+            self._instance_proxy_manager.instance_definition_proxies.values()
+        )
+        tree.elements.append(
+            Collection(
+                name="definitionGeometry",
+                elements=list(self._instance_proxy_manager.instance_geometry.values()),
+            )
+        )
         tree["version"] = 3
 
         return tree

src/speckleifc/main.py

@@ -26,6 +26,7 @@ def open_and_convert_file(
     remote_transport = ServerTransport(project.id, account=account)
 
     ifc_file = open_ifc(file_path)  # pyright: ignore[reportUnknownVariableType]
+
     import_job = ImportJob(ifc_file)  # pyright: ignore[reportUnknownArgumentType]
     data = import_job.convert()
 
@@ -55,6 +56,6 @@ def open_and_convert_file(
     custom_properties = {"ui": "dui3", "actionSource": "import"}
     if project.workspace_id:
         custom_properties["workspace_id"] = project.workspace_id
-    metrics.track(metrics.SEND, account, custom_properties)
+    metrics.track(metrics.SEND, account, custom_properties, send_sync=True)
 
     return version

src/speckleifc/property_extraction.py

@@ -1,3 +1,4 @@
+import math
 from typing import Any, Tuple
 
 from ifcopenshell.entity_instance import entity_instance
@@ -134,6 +135,10 @@ def _get_quantities(
             value = getattr(quantity, quantity.attribute_name(3))
             unit_info = _get_unit_info(element, quantity)
 
+            # Server does not consider `NaN` valid json
+            if math.isnan(value):
+                value = None
+
             if unit_info:
                 # Create structured quantity object with units
                 results[quantity_name] = {

src/speckleifc/proxy_managers/instance_proxy_manager.py

@@ -0,0 +1,43 @@
+from typing import Sequence
+
+from specklepy.objects.base import Base
+from specklepy.objects.proxies import InstanceDefinitionProxy
+
+
+class InstanceProxyManager:
+    def __init__(self):
+        self._instance_definition_proxies: dict[str, InstanceDefinitionProxy] = {}
+        """definition proxies to be added directly to the root"""
+        self._instance_geometry: dict[str, Base] = {}
+        """The geometry that will be added in it's own collection under the root"""
+
+    @property
+    def instance_definition_proxies(self) -> dict[str, InstanceDefinitionProxy]:
+        return self._instance_definition_proxies
+
+    @property
+    def instance_geometry(self) -> dict[str, Base]:
+        return self._instance_geometry
+
+    def add_display_value_definitions(self, geometry: Sequence[Base]) -> list[str]:
+        result: list[str] = []
+        for m in geometry:
+            if not m.applicationId:
+                raise ValueError("geometry with no applicationId cannot be proxied ")
+            definition_id = f"DEFINITION:{m.applicationId}"
+            result.append(definition_id)
+            self._add_definition(definition_id, [m.applicationId], 0)
+            self._instance_geometry[m.applicationId] = m
+
+        return result
+
+    def _add_definition(
+        self, definition_id: str, objects: list[str], max_depth: int
+    ) -> None:
+        proxy = InstanceDefinitionProxy(
+            applicationId=definition_id,
+            name=definition_id,
+            objects=objects,
+            maxDepth=max_depth,
+        )
+        self._instance_definition_proxies[definition_id] = proxy

src/specklepy/core/api/client.py

@@ -131,6 +131,19 @@ class SpeckleClient:
         self.account = Account.from_token(token, self.url)
         self._set_up_client()
 
+        userData = self.active_user.get()
+
+        # None if the token lacked the profile:read scope or if it was None
+        if userData:
+            self.account.userInfo.id = userData.id
+            self.account.userInfo.email = userData.email
+            self.account.userInfo.name = userData.name
+            self.account.userInfo.company = userData.company
+            self.account.userInfo.avatar = userData.avatar
+
+        self.account.serverInfo = self.server.get()
+        self.account.serverInfo.url = self.url
+
     def authenticate_with_account(self, account: Account) -> None:
         """Authenticate the client using an Account object
         The account is saved in the client object and a synchronous GraphQL
@@ -143,6 +156,21 @@ class SpeckleClient:
         self.account = account
         self._set_up_client()
 
+        try:
+            _ = self.active_user.get()
+        except SpeckleException as ex:
+            if isinstance(ex.exception, TransportServerError):
+                if ex.exception.code == 403:
+                    warn(
+                        SpeckleWarning(
+                            "Possibly invalid token - could not authenticate "
+                            f"Speckle Client for server {self.url}"
+                        ),
+                        stacklevel=2,
+                    )
+                else:
+                    raise ex
+
     def _set_up_client(self) -> None:
         headers = {
             "Authorization": f"Bearer {self.account.token}",
@@ -162,21 +190,6 @@ class SpeckleClient:
 
         self._init_resources()
 
-        try:
-            _ = self.active_user.get()
-        except SpeckleException as ex:
-            if isinstance(ex.exception, TransportServerError):
-                if ex.exception.code == 403:
-                    warn(
-                        SpeckleWarning(
-                            "Possibly invalid token - could not authenticate "
-                            f"Speckle Client for server {self.url}"
-                        ),
-                        stacklevel=2,
-                    )
-                else:
-                    raise ex
-
     def execute_query(self, query: str) -> Dict:
         return self.httpclient.execute(query)
 

src/specklepy/core/api/credentials.py

@@ -37,7 +37,7 @@ class Account(BaseModel):
         return self.__repr__()
 
     @classmethod
-    def from_token(cls, token: str, server_url: str = None):
+    def from_token(cls, token: str, server_url: str | None = None):
         acct = cls(token=token)
         acct.serverInfo.url = server_url
         return acct

src/specklepy/core/api/wrapper.py

@@ -1,8 +1,6 @@
 from urllib.parse import quote, unquote, urlparse
 from warnings import warn
 
-from gql import gql
-
 from specklepy.core.api.client import SpeckleClient
 from specklepy.core.api.credentials import (
     Account,
@@ -139,27 +137,11 @@ class StreamWrapper:
 
         if use_fe2 is True and self.branch_name is not None:
             self.model_id = self.branch_name
-            # get branch name
-            query = gql(
-                """
-                query Project($project_id: String!, $model_id: String!) {
-                    project(id: $project_id) {
-                        id
-                        model(id: $model_id) {
-                            name
-                        }
-                    }
-                }
-            """
-            )
-            self._client = self.get_client()
-            params = {"project_id": self.stream_id, "model_id": self.model_id}
-            project = self._client.httpclient.execute(query, params)
 
-            try:
-                self.branch_name = project["project"]["model"]["name"]
-            except KeyError as ke:
-                raise SpeckleException("Project model name is not found", ke) from ke
+            self._client = self.get_client()
+            model = self._client.model.get(self.model_id, self.stream_id)
+
+            self.branch_name = model.name
 
         if not self.stream_id:
             raise SpeckleException(
@@ -175,6 +157,10 @@ class StreamWrapper:
         """
         Gets an account object for this server from the local accounts db
         (added via Speckle Manager or a json file)
+
+        WARNING: this function will return ANY account for the server,
+          just because you pass a token in doesn't guarantee it will be used.
+          This whole class could do with a re-design...
         """
         if self._account and self._account.token:
             return self._account

src/specklepy/core/helpers/speckle_path_provider.py

@@ -88,6 +88,8 @@ def user_application_data_path() -> Path:
                     message="Cannot get appdata path from environment."
                 )
             return Path(app_data_path)
+        if sys.platform.startswith("darwin"):  # macOS
+            return _ensure_folder_exists(Path.home() / "Library", "Application Support")
         else:
             # try getting the standard XDG_DATA_HOME value
             # as that is used as an override
@@ -98,7 +100,7 @@ def user_application_data_path() -> Path:
                 return _ensure_folder_exists(Path.home(), ".config")
     except Exception as ex:
         raise SpeckleException(
-            message="Failed to initialize user application data path.", exception=ex
+            message="Failed to initialize user application data path."
         ) from ex
 
 

src/specklepy/logging/metrics.py

@@ -6,6 +6,7 @@ import platform
 import queue
 import sys
 import threading
+from typing import Any
 
 import requests
 
@@ -29,21 +30,6 @@ CONNECTOR = "Connector Action"
 RECEIVE = "Receive"
 SEND = "Send"
 
-# not in use since 2.15
-ACCOUNTS = "Get Local Accounts"
-BRANCH = "Branch Action"
-CLIENT = "Speckle Client"
-COMMIT = "Commit Action"
-DESERIALIZE = "serialization/deserialize"
-INVITE = "Invite Action"
-OTHER_USER = "Other User Action"
-PERMISSION = "Permission Action"
-SERIALIZE = "serialization/serialize"
-SERVER = "Server Action"
-STREAM = "Stream Action"
-STREAM_WRAPPER = "Stream Wrapper"
-USER = "User Action"
-
 
 def disable():
     global TRACK
@@ -65,43 +51,44 @@ def track(
     action: str,
     account: Account | None = None,
     custom_props: dict | None = None,
+    send_sync: bool = False,
 ):
     if not TRACK:
         return
-    try:
-        initialise_tracker(account)
-        event_params = {
-            "event": action,
-            "properties": {
-                "distinct_id": METRICS_TRACKER.last_user,
-                "server_id": METRICS_TRACKER.last_server,
-                "token": METRICS_TRACKER.analytics_token,
-                "hostApp": HOST_APP,
-                "hostAppVersion": HOST_APP_VERSION,
-                "$os": METRICS_TRACKER.platform,
-                "type": "action",
-            },
-        }
-        if custom_props:
-            event_params["properties"].update(custom_props)
 
-        METRICS_TRACKER.queue.put_nowait(event_params)
-    except Exception as ex:
-        # wrapping this whole thing in a try except as we never want a failure here
-        # to annoy users!
-        LOG.debug(f"Error queueing metrics request: {str(ex)}")
+    tracker = initialise_tracker(account)
+    event_params: dict[str, Any] = {
+        "event": action,
+        "properties": {
+            "distinct_id": tracker.last_user,
+            "server_id": tracker.last_server,
+            "token": tracker.analytics_token,
+            "hostApp": HOST_APP,
+            "hostAppVersion": HOST_APP_VERSION,
+            "$os": tracker.platform,
+            "type": "action",
+        },
+    }
+    if custom_props:
+        event_params["properties"].update(custom_props)
+
+    if send_sync:
+        tracker.send_event(event_params)
+    else:
+        tracker.queue_event(event_params)
 
 
-def initialise_tracker(account: Account | None = None):
+def initialise_tracker(account: Account | None = None) -> "MetricsTracker":
     global METRICS_TRACKER
     if not METRICS_TRACKER:
         METRICS_TRACKER = MetricsTracker()
 
-    if account and account.userInfo.email:
+    if account:
         METRICS_TRACKER.set_last_user(account.userInfo.email)
-    if account and account.serverInfo.url:
         METRICS_TRACKER.set_last_server(account.serverInfo.url)
 
+    return METRICS_TRACKER
+
 
 class Singleton(type):
     _instances = {}
@@ -113,48 +100,62 @@ class Singleton(type):
 
 
 class MetricsTracker(metaclass=Singleton):
-    analytics_url = "https://analytics.speckle.systems/track?ip=1"
-    analytics_token = "acd87c5a50b56df91a795e999812a3a4"
-    last_user = ""
-    last_server = None
-    platform = None
-    sending_thread = None
-    queue = queue.Queue(1000)
+    analytics_url: str = "https://analytics.speckle.systems/track?ip=1"
+    analytics_token: str = "acd87c5a50b56df91a795e999812a3a4"
+    last_user: str = ""
+    last_server: str | None = None
+    platform: str
+
+    _sending_thread: threading.Thread
+    _queue: queue.Queue[dict[str, Any]] = queue.Queue(1000)
+    _session = requests.Session()
 
     def __init__(self) -> None:
-        self.sending_thread = threading.Thread(
+        self._sending_thread = threading.Thread(
             target=self._send_tracking_requests, daemon=True
         )
         self.platform = PLATFORMS.get(sys.platform, "linux")
-        self.sending_thread.start()
+        self._sending_thread.start()
         with contextlib.suppress(Exception):
             node, user = platform.node(), getpass.getuser()
             if node and user:
                 self.last_user = f"@{self.hash(f'{node}-{user}')}"
 
-    def set_last_user(self, email: str):
+    def set_last_user(self, email: str | None) -> None:
         if not email:
             return
         self.last_user = f"@{self.hash(email)}"
 
-    def set_last_server(self, server: str):
+    def set_last_server(self, server: str | None) -> None:
         if not server:
             return
         self.last_server = self.hash(server)
 
-    def hash(self, value: str):
+    def hash(self, value: str) -> str:
         inputList = value.lower().split("://")
         input = inputList[len(inputList) - 1].split("/")[0].split("?")[0]
         return hashlib.md5(input.encode("utf-8")).hexdigest().upper()
 
-    def _send_tracking_requests(self):
-        session = requests.Session()
+    def queue_event(self, event_params: dict[str, Any]) -> None:
+        try:
+            self._queue.put_nowait(event_params)
+        except queue.Full:
+            LOG.warning(
+                "Metrics event was skipped because the metrics queue was was full",
+                exc_info=True,
+            )
+
+    def send_event(self, event_params: dict[str, Any]) -> None:
+        response = self._session.post(self.analytics_url, json=[event_params])
+        response.raise_for_status()
+
+    def _send_tracking_requests(self) -> None:
         while True:
-            event_params = [self.queue.get()]
+            event_params = self._queue.get()
 
             try:
-                session.post(self.analytics_url, json=event_params)
-            except Exception as ex:
-                LOG.debug(f"Error sending metrics request: {str(ex)}")
+                self.send_event(event_params)
+            except Exception:
+                LOG.warning("Error sending metrics request", exc_info=True)
 
-            self.queue.task_done()
+            self._queue.task_done()

src/specklepy/objects/proxies.py

@@ -33,9 +33,9 @@ class InstanceProxy(
     IHasUnits,
     speckle_type="Speckle.Core.Models.Instances.InstanceProxy",
 ):
-    definition_id: str
+    definitionId: str
     transform: List[float]
-    max_depth: int
+    maxDepth: int
 
 
 @dataclass(kw_only=True)
@@ -45,7 +45,7 @@ class InstanceDefinitionProxy(
     detachable={"objects"},
 ):
     objects: List[str]
-    max_depth: int
+    maxDepth: int
     name: str
 
 

src/specklepy/transports/server/batch_sender.py

@@ -7,6 +7,7 @@ import threading
 import requests
 
 from specklepy.logging.exceptions import SpeckleException
+from specklepy.transports.server.retry_policy import setup_session
 
 LOG = logging.getLogger(__name__)
 
@@ -72,10 +73,7 @@ class BatchSender:
 
     def _sending_thread_main(self):
         try:
-            session = requests.Session()
-            session.headers.update(
-                {"Authorization": f"Bearer {self._token}", "Accept": "text/plain"}
-            )
+            session = setup_session(self._token)
 
             while True:
                 batch = self._batches.get()

src/specklepy/transports/server/retry_policy.py

@@ -0,0 +1,46 @@
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3 import Retry
+
+
+def setup_session(auth_token: str | None) -> requests.Session:
+    """
+    Sets up a requests.Session with a basic retry policy
+    to retry on all the usual retryable status codes, with a back off policy:
+        1st: 0ms,
+        2nd: 500ms,
+        3rd: 1500ms.
+
+    Also sets "Accept": "text/plain" header (because this is what ServerTransport needs)
+    and (if a auth_token is provided) the Authorization header
+    """
+
+    session = requests.Session()
+    retry_policy = Retry(
+        total=3,
+        read=3,
+        connect=3,
+        backoff_factor=0.5,
+        status_forcelist=(500, 502, 503, 504, 408, 429),
+        allowed_methods=["HEAD", "GET", "OPTIONS", "POST", "PUT", "DELETE"],
+        raise_on_status=False,
+    )
+
+    adapter = HTTPAdapter(max_retries=retry_policy)
+    session.mount("https://", adapter)
+    session.mount("http://", adapter)
+
+    session.headers.update(
+        {
+            "Accept": "text/plain",
+        }
+    )
+
+    if auth_token is not None:
+        session.headers.update(
+            {
+                "Authorization": f"Bearer {auth_token}",
+            }
+        )
+
+    return session

src/specklepy/transports/server/server.py

@@ -2,12 +2,11 @@ import json
 from typing import Dict, List, Optional
 from warnings import warn
 
-import requests
-
 from specklepy.core.api.client import SpeckleClient
 from specklepy.core.api.credentials import Account, get_account_from_token
 from specklepy.logging.exceptions import SpeckleException, SpeckleWarning
 from specklepy.transports.abstract_transport import AbstractTransport
+from specklepy.transports.server.retry_policy import setup_session
 
 from .batch_sender import BatchSender
 
@@ -92,23 +91,13 @@ class ServerTransport(AbstractTransport):
         self.stream_id = stream_id
         self.url = url
 
-        self.session = requests.Session()
-
-        self.session.headers.update(
-            {
-                "Accept": "text/plain",
-            }
-        )
-
         if self.account is not None:
             self._batch_sender = BatchSender(
                 self.url, self.stream_id, self.account.token, max_batch_size_mb=1
             )
-            self.session.headers.update(
-                {
-                    "Authorization": f"Bearer {self.account.token}",
-                }
-            )
+        self.session = setup_session(
+            self.account.token if self.account is not None else None
+        )
 
     @property
     def name(self) -> str:

tests/integration/client/test_client_and_ops.py

@@ -6,7 +6,7 @@ from specklepy.api import operations
 from specklepy.api.client import SpeckleClient
 from specklepy.api.credentials import Account, get_account_from_token
 from specklepy.core.helpers import speckle_path_provider
-from specklepy.logging.exceptions import SpeckleException, SpeckleWarning
+from specklepy.logging.exceptions import SpeckleException
 from specklepy.objects.base import Base
 from specklepy.transports.server import ServerTransport
 
@@ -17,7 +17,7 @@ def test_invalid_authentication():
     speckle_path_provider.override_application_data_path(gettempdir())
     client = SpeckleClient()
 
-    with pytest.warns(SpeckleWarning):
+    with pytest.raises(SpeckleException):
         client.authenticate_with_token("fake token")
 
     # remove path override

tests/integration/conftest.py

@@ -8,11 +8,12 @@ import requests
 
 from specklepy.api.client import SpeckleClient
 from specklepy.core.api import operations
+from specklepy.core.api.credentials import Account, UserInfo
 from specklepy.core.api.enums import ProjectVisibility
 from specklepy.core.api.inputs.project_inputs import ProjectCreateInput
 from specklepy.core.api.inputs.version_inputs import CreateVersionInput
 from specklepy.core.api.models import Version
-from specklepy.core.api.models.current import Project
+from specklepy.core.api.models.current import Project, ServerInfo
 from specklepy.logging import metrics
 from specklepy.objects.base import Base
 from specklepy.objects.geometry import Point
@@ -89,13 +90,15 @@ def second_user_dict(host: str) -> Dict[str, str]:
 def create_client(host: str, token: str) -> SpeckleClient:
     client = SpeckleClient(host=host, use_ssl=False)
     client.authenticate_with_token(token)
-    user = client.active_user.get()
-    assert user
-    client.account.userInfo.id = user.id
-    client.account.userInfo.email = user.email
-    client.account.userInfo.name = user.name
-    client.account.userInfo.company = user.company
-    client.account.userInfo.avatar = user.avatar
+
+    assert isinstance(client.account, Account)
+    assert isinstance(client.account.userInfo, UserInfo)
+    assert client.account.userInfo.id
+    assert client.account.userInfo.name
+    assert isinstance(client.account.serverInfo, ServerInfo)
+    assert client.account.serverInfo.url
+    assert client.account.serverInfo.name
+
     return client
 
 

tests/unit/test_setup_session.py

@@ -0,0 +1,20 @@
+import requests
+
+from specklepy.transports.server.retry_policy import setup_session
+
+
+def test_session_headers_without_auth():
+    """Check that Accept header is set and Authorization is not."""
+    session = setup_session(None)
+    assert isinstance(session, requests.Session)
+    assert session.headers["Accept"] == "text/plain"
+    assert "Authorization" not in session.headers
+
+
+def test_session_headers_with_auth():
+    """Check that Authorization header is properly added."""
+    token = "abc123"
+    session = setup_session(token)
+    assert isinstance(session, requests.Session)
+    assert session.headers["Authorization"] == f"Bearer {token}"
+    assert session.headers["Accept"] == "text/plain"