prep release 1.23.0

.github/workflows/publish-pypi.yml

@@ -50,6 +50,9 @@ jobs:
         uses: "actions/checkout@v7"
         with:
           submodules: true
+          # Full history + tags so hatch-vcs stamps the real tag version at build time, not the fallback
+          fetch-depth: 0
+          fetch-tags: true
 
       - name: Cache UV dependencies
         uses: "actions/cache@v6"

.github/workflows/release.yml

@@ -24,6 +24,9 @@ jobs:
         uses: "actions/checkout@v7"
         with:
           submodules: true
+          # Full history + tags so hatch-vcs resolves the exact tag version from installed metadata
+          fetch-depth: 0
+          fetch-tags: true
 
       - name: "Set up Python"
         uses: "actions/setup-python@v7"
@@ -41,10 +44,13 @@ jobs:
       - name: Check prerelease type
         id: release
         run: |
-          VERSION=$(uv version --short)
+          VERSION=$(uv run python -c "import importlib.metadata; print(importlib.metadata.version('infrahub-sdk'))")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
           echo is_prerelease=$(uv run python -c "from packaging.version import Version; print(int(Version('$VERSION').is_prerelease))") >> "$GITHUB_OUTPUT"
           echo is_devrelease=$(uv run python -c "from packaging.version import Version; print(int(Version('$VERSION').is_devrelease))") >> "$GITHUB_OUTPUT"
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo is_local=$(uv run python -c "from packaging.version import Version; print(int(Version('$VERSION').local is not None))") >> "$GITHUB_OUTPUT"
+          echo base_version=$(uv run python -c "from packaging.version import Version; print(Version('$VERSION').base_version)") >> "$GITHUB_OUTPUT"
+          echo fallback_base=$(uv run python -c "import tomllib; from packaging.version import Version; print(Version(tomllib.load(open('pyproject.toml', 'rb'))['tool']['hatch']['version']['fallback-version']).base_version)") >> "$GITHUB_OUTPUT"
           echo major_minor_version=$(uv run python -c "from packaging.version import Version; v = Version('$VERSION'); print(f'{v.major}.{v.minor}')") >> "$GITHUB_OUTPUT"
           echo latest_tag=$(curl -L \
               -H "Accept: application/vnd.github+json" \
@@ -53,16 +59,23 @@ jobs:
               https://api.github.com/repos/${{ github.repository }}/releases/latest \
               | jq -r '.tag_name') >> "$GITHUB_OUTPUT"
 
-      - name: Check tag version
+      - name: "Publish guard: resolved version must match the release tag"
         run: |
           EXPECTED_TAG="v${{ steps.release.outputs.version }}"
           if [ "${{ github.event.release.tag_name }}" != "$EXPECTED_TAG" ]; then
-            echo "Tag version does not match python project version"
+            echo "Resolved version (${{ steps.release.outputs.version }}) does not match release tag ${{ github.event.release.tag_name }}"
             echo "Expected: $EXPECTED_TAG"
             echo "Got: ${{ github.event.release.tag_name }}"
             exit 1
           fi
 
+      - name: "Publish guard: reject unreleased fallback version"
+        # fallback_base is read from pyproject.toml at run time; the fallback is a static sentinel (0.0.0.dev0)
+        if: steps.release.outputs.base_version == steps.release.outputs.fallback_base && (steps.release.outputs.is_devrelease == 1 || steps.release.outputs.is_local == 1)
+        run: |
+          echo "Resolved version (${{ steps.release.outputs.version }}) is an unreleased fallback (base ${{ steps.release.outputs.fallback_base }}, dev/local build): no v* tag is reachable. Refusing to publish."
+          exit 1
+
       - name: Check prerelease and project version
         if: github.event.release.prerelease == true && steps.release.outputs.is_prerelease == 0 && steps.release.outputs.is_devrelease == 0
         run: |

.github/workflows/repository-dispatch.yml

@@ -37,6 +37,7 @@ jobs:
         repo:
           - "opsmill/emma"
           - "opsmill/infrahub-demo-dc"
+          - "opsmill/infrahub-sync"
           - "INFRAHUB_CUSTOMER1_REPOSITORY"
 
     steps:

.github/workflows/schema-drift.yml

@@ -0,0 +1,32 @@
+---
+# yamllint disable rule:truthy rule:line-length
+name: Schema Drift Check
+
+# Warn-only: surfaces when the published Infrahub JSON schema has drifted from
+# the formatter's committed baseline (infrahub_sdk/ctl/schema_properties.json).
+# This never fails the run — it emits ::warning:: annotations and a job summary
+# so a maintainer can account for the change in schema_format.py.
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+jobs:
+  schema-drift:
+    runs-on: "ubuntu-22.04"
+    timeout-minutes: 5
+    steps:
+      - name: "Check out repository code"
+        uses: "actions/checkout@v6"
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install UV
+        uses: astral-sh/setup-uv@v7
+      - name: Install dependencies
+        run: uv sync --all-groups --all-extras
+      - name: "Check for Infrahub schema drift (warn only)"
+        run: uv run invoke schema-drift-check

.gitignore

@@ -30,8 +30,14 @@ dist/*
 
 # Generated files
 generated/
+# Committed, generated schema models (write/read variants) must be version-controlled.
+!infrahub_sdk/schema/generated/
+!infrahub_sdk/schema/generated/*.py
 sandbox/
 
+# hatch-vcs version file (written at build time; must not be tracked)
+infrahub_sdk/_version.py
+
 # SpecKit internal cache
 .specify/**/.cache/
 .specify/feature.json

.vale/styles/Infrahub/sentence-case.yml

@@ -45,6 +45,7 @@ exceptions:
   - IP
   - IP Fabric
   - IPAM
+  - IPAddress
   - IPHost
   - IPNetwork
   - JavaScript

.vale/styles/spelling-exceptions.txt

@@ -8,6 +8,7 @@ artifact_definitions
 artifact_name
 async
 Authentik
+backoff
 boolean
 check_definitions
 class_name

CHANGELOG.md

@@ -11,6 +11,37 @@ This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the chang
 
 <!-- towncrier release notes start -->
 
+## [1.23.0](https://github.com/opsmill/infrahub-sdk-python/tree/v1.23.0) - 2026-08-19
+
+### Removed
+
+- Removed `client.branch.diff_data()` from both the async and sync clients. The method relied on a `GET /api/diff/data` REST endpoint that does not exist in Infrahub, so every call returned a 404. Use `client.get_diff_tree()` to retrieve the full diff of a branch against its base branch, or `client.get_diff_summary()` for the list of changed nodes; both use the `DiffTree` GraphQL query. ([#325](https://github.com/opsmill/infrahub-sdk-python/issues/325))
+
+### Added
+
+- Added the Infrahub deployment ID to the `infrahubctl info` command output and a `get_server_information()` method (returning the server version and deployment ID) on the async and sync clients. ([#1017](https://github.com/opsmill/infrahub-sdk-python/issues/1017))
+- Added transparent retry of HTTP 429 (rate-limited) responses on both `InfrahubClient` and `InfrahubClientSync`. Retries use jittered exponential backoff and honour a server-provided `Retry-After` header (delta-seconds or HTTP-date). The behaviour is tunable through four new `Config` fields (`rate_limit_retry_enabled`, `rate_limit_max_retries`, `rate_limit_backoff_base`, `rate_limit_backoff_max`), and a new `RateLimitError` exception is raised when retries are exhausted. ([#1124](https://github.com/opsmill/infrahub-sdk-python/issues/1124))
+- Added support for tagging SDK requests with a priority via a new `X-Priority` header. A `Priority` enum (`high`, `medium`, `low`) is available from `infrahub_sdk.constants`; set `Config.priority` (env var `INFRAHUB_PRIORITY`) for a client-wide default emitted on every request, or pass `priority=` to individual operations to override it per request. When unset, no header is sent. Works identically on `InfrahubClient` and `InfrahubClientSync`. ([#1151](https://github.com/opsmill/infrahub-sdk-python/issues/1151))
+- Add `infrahubctl schema format` command, an opinionated offline formatter that normalises the key ordering of schema files. Optional flags can also strip redundant default values (`--strip-defaults`), sort attributes/relationships by `order_weight` (`--sort-by-order-weight`), and backfill a missing `order_weight` (`--backfill-order-weight`).
+- Added `retry()` and `cancel()` methods to the task manager. The `Task` model now exposes `available_actions` along with `can_retry` / `can_cancel` helpers.
+- Added an opt-in `include_diagnostics` flag to the task manager's `all()`, `filter()`, and `get()` methods. When enabled, tasks expose an `error` field, and `webhook-send` tasks are returned as `WebhookDeliveryTask` instances carrying `http_request` / `http_response` delivery details.
+- Added support for the new `IPAddress` attribute kind. Values are exposed as bare `ipaddress.IPv4Address`/`IPv6Address` objects (no prefix) and serialized to a bare-address string when writing, alongside the existing `IPHost` and `IPNetwork` kinds.
+- The JSON schema generated for `.infrahub.yml` now warns when a definition has not said what it depends on, so YAML language servers flag it while the file is being edited. A Python transform or generator definition with no `watch` block is flagged, and so is a `watch` value that is not a mapping, including the bare `watch:` that parses as null and records nothing. Both warnings are advisory only: the models still accept every one of those forms. An empty `watch: {}` or `files: []` stays clean, since either one records that the author checked and nothing beyond what Infrahub detects needs watching. The generated schema also picks up the `watch` block on generator definitions, which it was previously rejecting as an unknown property.
+- The request priority (`X-Priority` header) can now be carried on the client's `RequestContext` via a new `priority` field, alongside the existing client-wide `Config.priority` default and per-call `priority=` override. Resolution precedence is per-call `priority=` > `request_context.priority` > `Config.priority` > no header. The priority is emitted as a header only and is never included in the mutation body. Works identically on `InfrahubClient` and `InfrahubClientSync`.
+- Import `pyarrow` lazily in the line-delimited JSON importer so that `infrahubctl` commands other than `object load` no longer require the `ctl` extra (and its heavy `pyarrow` dependency) to be installed.
+
+### Changed
+
+- Paginated queries generated by `all()`, `filters()`, `get()` and resource pool allocation lookups now pass `offset` and `limit` as GraphQL variables instead of inlining them in the query text. The query document stays identical across pages, allowing the Infrahub server to reuse its cached query analysis, and the query is now rendered once per call instead of once per page. `generate_query_data` also accepts variable placeholder strings (for example `"$offset"`) for its `offset` and `limit` arguments.
+- Raised the default `Config.rate_limit_max_retries` from 5 to 10, so a request shed with HTTP 429 keeps retrying (honouring `Retry-After`) for longer before raising `RateLimitError`. This lets background work ride out a longer burst of server-side backpressure. Callers that prefer to give up sooner can lower the value.
+- The hand-maintained schema models in `infrahub_sdk.schema` are now backed by the generated write/read contract (`infrahub_sdk.schema.generated`). Public names, import paths, and behavior methods are unchanged, but a few defaults and constraints now match the server contract:
+
+  - `AttributeKind.STRING` has been removed. It was deprecated and `kind="String"` was already rejected server-side; use `AttributeKind.TEXT` instead.
+  - Write and read models drop unknown fields silently (`extra="ignore"`). A submitted field that is not part of the write contract — read-level, internal, or a typo — is dropped rather than rejected, and a read model tolerates additional fields returned by a newer server.
+  - Write-model defaults now match the server contract: relationship `min_count`/`max_count` default to `0` (was `None`), node `branch` defaults to `"aware"`, `generate_profile` defaults to `True`, and `generate_template` defaults to `False`. This changes the round-trip output of programmatically-built schemas.
+
+  Constructing `AttributeSchema(name=..., kind=AttributeKind.TEXT, ...)`, `NodeSchema`, `GenericSchema`, `RelationshipSchema`, `SchemaRoot`, and the read-side `*API` models continues to work unchanged.
+
 ## [1.22.3](https://github.com/opsmill/infrahub-sdk-python/tree/v1.22.3) - 2026-08-19
 
 ### Fixed

dev/specs/ihs-249-sdk-429-retry/alignment-check.md

@@ -0,0 +1,43 @@
+# Spec/Ask Alignment Check: SDK retry with backoff on HTTP 429 responses
+
+**Date**: 2026-07-07
+**Feature**: [spec.md](./spec.md)
+
+## 1. Source
+
+**Source PRD**: Jira IHS-249 — "SDK retry with backoff on HTTP 429 responses"
+(`https://opsmill.atlassian.net/browse/IHS-249`), fetched via the Atlassian MCP tool.
+The issue body is itself a full, structured PRD (Problem Statement, Solution Overview, 9 User
+Stories, 3 prioritised User Journeys with acceptance criteria, FR-001…009, Key Entities, Edge
+Cases, SC-001…005, Implementation/Testing Decisions, Out of Scope, one Open Question). Related
+GitHub issue: opsmill/infrahub-sdk-python#1124. No secondary URLs to fetch.
+
+## 2. Verdict
+
+Result: ✅ ALIGNED
+
+`spec.md` faithfully carries every PRD requirement, acceptance criterion, and scope boundary.
+The only additions are an expansion of an existing requirement and the authorized resolution of
+the PRD's explicit open question — neither is drift under the check's definition.
+
+## 3. Findings
+
+| Severity | Category | PRD reference | Spec reference | Description |
+| ---------- | ---------- | --------------- | ---------------- | ------------- |
+| ✅ none | missing | FR-001…009 | FR-001…009 | All nine functional requirements present, none dropped or softened (attempt cap, jittered+clamped backoff, Retry-After both forms, malformed fallback, RateLimitError with url/attempts/last-Retry-After, all request paths, per-retry logging, async/sync parity, tune+disable). |
+| ✅ none | missing | Journeys P1–P3, User Stories 1–9 | US1–US4, Edge Cases | P1/P2/P3 journeys map to US1/US2/US3; PRD user story 8 (tune/disable) surfaced as US4. All acceptance scenarios preserved. |
+| ✅ none | missing | SC-001…005 | SC-001…005 | Success criteria carried over with equivalent semantics. |
+| ✅ none | contradicted | Out of Scope (503, server-side INFP-636/635, `retry_on_failure`) | Out of Scope | Scope boundaries reproduced verbatim; nothing contradicted. |
+| ℹ️ info | added (authorized) | Open Question (chain httpx.HTTPStatusError as `__cause__`?) | FR-005, Assumptions | The PRD's single open question was resolved affirmatively (chain the transport error as `__cause__`). The parent prep flow explicitly authorizes autonomous clarification resolution; recorded as an assumption. Not drift. |
+| ℹ️ info | added (derived) | FR-009 (disable via Config) | SC-006 | Spec adds SC-006 (disabled path raises immediately). This is a measurable expansion of FR-009, not new scope. |
+| ℹ️ info | added (design) | Assumption: single `_request` chokepoint | plan.md R1 / data-model | Plan (not spec) records that multipart/streaming bypass `_request`, so retry is applied at three sites. This corrects a PRD *assumption* at the implementation layer while still satisfying FR-006; spec requirements unchanged. Not spec drift. |
+
+No requirements are missing, no acceptance criteria dropped or softened, no requirement semantics
+changed, and no off-scope scope items were introduced. The Config field defaults (enabled, 5, 0.5,
+60), the new `RateLimitError`, and the additive-only API surface all match the PRD exactly.
+
+## 4. Action
+
+**Proceed.** No remediation passes required (remediation counter: 0). `tasks.md` is safe to hand to
+the implementation phase. The affirmative resolution of the open question and the SC-006 derivation
+are documented above for traceability.

dev/specs/ihs-249-sdk-429-retry/checklists/requirements.md

@@ -0,0 +1,39 @@
+# Specification Quality Checklist: SDK retry with backoff on HTTP 429 responses
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-07-07
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- The PRD's single open question (whether the exhaustion error should chain the
+  underlying transport error as its cause) was resolved affirmatively and encoded
+  into FR-005 and the Assumptions section, so no [NEEDS CLARIFICATION] markers remain.
+- Entity names in the spec are described in capability terms (e.g. "rate-limit retry
+  decision logic") rather than concrete class names to keep the spec implementation-agnostic;
+  concrete names (`RateLimitRetryHandler`, `RateLimitError`, `Config` fields) are deferred to plan.md.

dev/specs/ihs-249-sdk-429-retry/contracts/config.md

@@ -0,0 +1,37 @@
+# Contract: `Config` rate-limit fields (additive, public)
+
+Added to `infrahub_sdk/config.py::ConfigBase`. All additive; no existing field changes.
+
+```python
+rate_limit_retry_enabled: bool = Field(
+    default=True,
+    description="Retry requests that receive HTTP 429 using backoff. Set False to disable.",
+)
+rate_limit_max_retries: int = Field(
+    default=5,
+    ge=0,
+    description="Maximum number of retries after the initial attempt when receiving HTTP 429.",
+)
+rate_limit_backoff_base: float = Field(
+    default=0.5,
+    gt=0,
+    description="Base interval in seconds for exponential backoff between 429 retries.",
+)
+rate_limit_backoff_max: float = Field(
+    default=60.0,
+    gt=0,
+    description="Maximum wait in seconds for any single 429 retry (also clamps Retry-After).",
+)
+```
+
+## Backward compatibility
+
+- Purely additive; existing code constructing `Config(...)` / `InfrahubClient(...)` is unaffected.
+- Environment-variable overrides follow the existing `BaseSettings` mechanism (e.g.
+  `INFRAHUB_RATE_LIMIT_MAX_RETRIES`), consistent with current fields.
+
+## Guarantees
+
+- `rate_limit_retry_enabled=False` ⇒ a 429 is returned/raised exactly as before this feature
+  (no wait, no extra attempt). (FR-009, SC-006)
+- Defaults produce transparent retry for typical background workloads. (FR-001)