fairagro-middleware-api-client 10.0.3.dev26__tar.gz → 11.0.1.dev27__tar.gz

{fairagro_middleware_api_client-10.0.3.dev26 → fairagro_middleware_api_client-11.0.1.dev27}/.gitignore

@@ -228,6 +228,3 @@ helmchart/**/client_ext.conf
 .cache_ggshield
 
 docker/Dockerfile.api.bak
-# Docker DinD: ignore runtime state in docker-config, keep minimal config.json tracked
-.devcontainer/docker-config/*
-!.devcontainer/docker-config/config.json

{fairagro_middleware_api_client-10.0.3.dev26 → fairagro_middleware_api_client-11.0.1.dev27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fairagro-middleware-api-client
-Version: 10.0.3.dev26
+Version: 11.0.1.dev27
 Summary: The FAIRagro advanced middleware API client
 Requires-Python: >=3.12
 Requires-Dist: httpx>=0.28.1

fairagro_middleware_api_client-10.0.3.dev26/spec/harvest-client/design.md

@@ -1,72 +0,0 @@
-# Harvest Client — Design
-
-## Module Overview
-
-`ApiClient` (`api_client.py`) orchestrates the harvest lifecycle.
-`HarvestResult`, `HarvestStatistics`, `HarvestError`, and `HarvestErrorType`
-(`models.py`) are the stable public types exposed to harvesters.
-
-```text
-harvester
-    └─→ ApiClient.harvest_arcs(rdi, arcs)
-            ├─→ create_harvest          → HarvestResult (RUNNING)
-            ├─→ _submit_arcs_parallel
-            │       ├─→ duplicate check (client-side)  → HarvestError(DUPLICATE)
-            │       └─→ POST v3/harvests/{id}/arcs      → HarvestError(SUBMISSION_FAILED) on error
-            └─→ complete_harvest        → HarvestResult (COMPLETED)
-                    └─→ inject client_errors via model_copy  → HarvestResult.errors
-```
-
-## Key Decisions
-
-1. **`HarvestStatistics` is a typed Pydantic model, not `dict`**
-   — The server serializes its internal `HarvestStatistics` via `model_dump()`
-   before sending it over the wire. The field names and types are stable and
-   known. A typed model gives consumers validated, IDE-navigable fields rather
-   than requiring dict key lookups with no type safety.
-
-2. **`HarvestError` is a client-facing type in `models.py`, independent of any server model**
-   — Per-item errors are currently generated client-side. When the server
-   persists them natively (issue #240), `_parse_harvest_response` will
-   populate `HarvestResult.errors` from the server response automatically —
-   the type and consumer interface remain unchanged.
-
-3. **`arc_id: str | None` in `HarvestError`**
-   — The `DUPLICATE` and `SUBMISSION_FAILED` categories always have a
-   known ARC identifier (when one is extractable from the RO-Crate). Future
-   error categories — such as harvest-level timeouts or config failures —
-   may not be associated with any specific ARC. `None` is the semantically
-   correct representation; an empty string would be an invisible sentinel
-   value that callers would need to treat specially.
-
-4. **Client-side error collection as compatibility shim until issue #240**
-   — `harvest_arcs()` collects errors from `_submit_arcs_parallel()` and
-   merges them into the server response via `model_copy(update=...)`.
-   This shim is removed once the server persists and returns per-item errors
-   natively. The `model_copy` merge is additive: if the server already
-   returns errors in its response (post-#240), client-side errors are
-   appended rather than overwriting.
-
-5. **Duplicate detection is performed client-side before the HTTP request**
-   — Within one harvest batch, two different ARC payloads that share an
-   identifier are a harvester bug. Detecting them client-side yields an
-   explicit `DUPLICATE` error and avoids the round-trip. The server still
-   enforces harvest-local identity: identical re-submits (e.g. transport
-   retries) return `200`; conflicting content for the same identifier returns
-   `409` (see `harvest-arc-upload/`). Client-side detection therefore covers
-   *intra-batch* duplicates; server idempotency covers *retry* duplicates.
-
-6. **Item-level failures are non-fatal; harvest-level failures are fatal**
-   — A submission failure for one ARC (e.g. server 422 on bad content) must
-   not abort the entire harvest because the remaining ARCs may be valid. A
-   catastrophic failure (e.g. 401 Unauthorized, harvest already closed) means
-   no further submissions will succeed, so the harvest is aborted, marked
-   `FAILED`, and the exception propagates to the caller.
-
-7. **POST ARC endpoints retry transport failures**
-   — `POST /v3/arcs` and `POST /v3/harvests/{id}/arcs` are server-idempotent for
-   identical bodies, so the client retries `ConnectError` and transient gateway
-   statuses (`502`/`503`/`504`) on those paths without risking a second object.
-   Other POSTs (create/complete harvest) are not retried. Conflicting `409`
-   (same identifier, different content in one harvest) remains a real conflict
-   and is not treated as success.

fairagro_middleware_api_client-10.0.3.dev26/spec/harvest-client/spec.md

@@ -1,50 +0,0 @@
-# Harvest Client
-
-Manage the full lifecycle of a harvest run — creation, parallel ARC
-submission, error collection, and finalization — on behalf of a harvester
-process.  The client returns a typed result that captures both statistics
-and per-item errors so harvesters can produce complete reports.
-
-## Requirements
-
-- [ ] Create a harvest run for a given RDI, submit all ARCs from an async
-      source in bounded parallelism, and return the completed harvest result
-      as a single operation.
-- [ ] Accept an optional expected-dataset count at the start of a harvest to
-      enable progress tracking on the server side.
-- [ ] Return typed harvest statistics (submitted, new, updated, unchanged,
-      missing counts, and optional expected-dataset count) as structured
-      fields rather than an opaque mapping.
-- [ ] Record per-item errors encountered during submission and include them
-      in the returned harvest result.
-- [ ] Classify each per-item error into one of the following categories:
-      `duplicate` (two ARCs share the same identifier) or `submission_failed`
-      (the server rejected or could not process the ARC).
-- [ ] Each per-item error carries: the error category, a human-readable
-      message, and an ISO 8601 timestamp of when the error occurred.
-- [ ] Optionally associate a per-item error with an ARC identifier; errors
-      that do not relate to a specific ARC (e.g. harvest-level failures) may
-      omit the identifier.
-- [ ] Detect duplicate ARC identifiers before submission and record them as
-      `duplicate` errors; do not submit the duplicate.
-- [ ] Skip individual ARC submission failures and continue the harvest with
-      remaining items; record each failure as a `submission_failed` error.
-- [ ] Abort the entire harvest on catastrophic errors (e.g. authentication
-      failure, invalid harvest state) and mark the harvest as failed before
-      propagating the exception to the caller.
-
-## Edge Cases
-
-ARC with no extractable RO-Crate identifier → submitted normally; any
-resulting error records no ARC identifier (`null`).
-
-Two ARCs share the same identifier → the second is skipped; a `duplicate`
-error is recorded for it; the first continues to be submitted normally.
-
-Catastrophic error during submission → remaining tasks are cancelled; the
-harvest is transitioned to `FAILED`; the exception propagates to the caller.
-
-No per-item errors → the returned result contains an empty errors list.
-
-`expected_datasets` not provided → harvest is created without a progress
-denominator; statistics show raw counts only.