feat: add cancellation support for file and source uploads (#252)

This pull request introduces several improvements and new features to
the admin API library, focusing on enhanced document upload management,
especially regarding cancellation and cleanup of in-progress uploads.
The changes also include OpenAPI spec refinements, new abstract methods
for upload cancellation, and corresponding implementation in the file
uploader logic.

**Key changes include:**

### API and OpenAPI Specification Enhancements

- Updated `openapi.yaml` to OpenAPI 3.0.2, added detailed endpoint
descriptions, improved schema examples, clarified required fields, and
refined the structure for better documentation and validation.
[[1]](diffhunk://#diff-249c3dcd61b95d16c609c93086e8bb278356d195418bde6eb5ceece91c0c376cL1-L355)
[[2]](diffhunk://#diff-249c3dcd61b95d16c609c93086e8bb278356d195418bde6eb5ceece91c0c376cL365-R366)
- Added `.openapi-generator-ignore` entries to prevent overwriting
hand-maintained source files during code generation.

### Upload Cancellation Support

- Added `cancel_upload` abstract methods to both `FileUploader` and
`SourceUploader` base classes, enabling a standard interface for upload
cancellation by document identification.
[[1]](diffhunk://#diff-7dddc401b91c2ff4593c718a6211b203b1f5e15eb78cb33ec9e6da5756a0d173R13-R23)
[[2]](diffhunk://#diff-07e3a38bb2ae6f51f1ce64c6e8e1898be13dc441c1c43071c8c2ecc5f352531eR15-R25)
- Updated the `delete_document` endpoint logic to request cancellation
of any in-progress file or source uploads before deleting the document,
ensuring best-effort cleanup and preventing inconsistent states.
[[1]](diffhunk://#diff-8065840d5a5800fba5b7e366084521208dd6acdb106779806da0a04443d18667R61-R66)
[[2]](diffhunk://#diff-62762d1049cc95244c98453fbb91010628f7509b8b97f8e875ca1b9b2b3fe4b9R49-R50)
[[3]](diffhunk://#diff-62762d1049cc95244c98453fbb91010628f7509b8b97f8e875ca1b9b2b3fe4b9R67-R68)

### File Uploader Implementation Updates

- Implemented `cancel_upload` in `DefaultFileUploader` to mark uploads
as cancelled in the key-value store and log the action, supporting both
namespaced and non-namespaced document IDs.
- Introduced `UploadCancelledError` exception to signal when a running
upload is cancelled.
- Improved upload task management: now tracks run IDs, ensures proper
cleanup in case of errors or failed task starts, and integrates
cancellation logic into the upload lifecycle.

These changes collectively make document deletion safer and more robust,
improve API clarity, and lay the groundwork for better handling of
concurrent or cancelled uploads.

Author: a-klos

libs/admin-api-lib/.openapi-generator-ignore

@@ -32,3 +32,9 @@ setup.cfg
 .gitignore
 docker-compose.yaml
 .openapi-generator/FILES
+
+# These files are hand-maintained in this repo (DI wiring and impl loading)
+src/admin_api_lib/main.py
+src/admin_api_lib/apis/admin_api.py
+src/admin_api_lib/apis/admin_api_base.py
+src/admin_api_lib/security_api.py