Build MinIO S3 SDK with custom Signature V4 signing

### Type Feature ### Lineage `plan-pal-e-platform` → Phase 24 (MinIO SDK) ### Repo `forgejo_admin/minio-sdk` ### User Story As a platform developer I want a pure Python SDK that wraps the raw S3 REST API So that I can interact with MinIO without depending on boto3 or any third-party S3 SDK ### Context MinIO is deployed on the pal-e platform (Helm chart v5.4.0, namespace `minio`). The stock MinIO Console UI is unusable on mobile. We're building a custom mobile-first interface. This SDK is the foundation — it wraps every S3 endpoint with custom Signature V4 signing. No boto3, no minio-py, no aws-sdk. Just `requests` + Python stdlib. The S3 API is just HTTP with XML responses. The only complex part is AWS Signature V4 signing (4 chained HMAC-SHA256 operations). MinIO's S3 implementation is identical to AWS with minor gotchas (API port 9000, no regional routing, `AbortIncompleteMultipartUpload` lifecycle not supported). Key decisions: - **No third-party S3 SDKs** — own the stack, full control over HTTP, no hidden failures - **`requests` is the only external dep** — stdlib `hmac` + `hashlib` for signing, `xml.etree` for parsing - **Published to Forgejo PyPI** — same pattern as `pal-e-docs-sdk` ### File Targets Files to create: - `src/minio_sdk/__init__.py` — package init, exports client class - `src/minio_sdk/client.py` — main `MinioClient` class with all S3 operations - `src/minio_sdk/signer.py` — AWS Signature V4 signing module - `src/minio_sdk/models.py` — dataclasses for Bucket, Object, Part, etc. - `src/minio_sdk/xml_parser.py` — S3 XML response parsing to Python objects - `src/minio_sdk/exceptions.py` — typed exceptions for S3 errors - `tests/test_signer.py` — unit tests for Signature V4 with known test vectors - `tests/test_client.py` — integration tests against live MinIO - `pyproject.toml` — project config, dependencies, build config - `CLAUDE.md` — agent conventions for this repo ### Acceptance Criteria - [ ] Signature V4 signing works against live MinIO (not mocked) - [ ] All bucket operations: list, create, delete, head, versioning, policy, tagging, lifecycle - [ ] All object operations: put, get, head, delete, batch delete, copy, list (v2), ACL, tagging - [ ] All multipart operations: initiate, upload part, complete, abort, list parts - [ ] Presigned URL generation: GET (download) and PUT (upload) with configurable expiration - [ ] XML responses parsed to typed Python objects (dataclasses) - [ ] Integration tests pass against MinIO at `minio-api.tail5b443a.ts.net` - [ ] Package installable via `pip install` from Forgejo PyPI - [ ] Zero boto3 / minio-py / aws-sdk dependencies ### Test Expectations - [ ] Unit tests: Signature V4 signing with known AWS test vectors (canonical request, string-to-sign, signature) - [ ] Integration tests: every endpoint tested against live MinIO with real buckets/objects - [ ] Test cleanup: tests create and delete their own test buckets/objects - Run command: `pytest tests/ -v` ### Constraints - Only external dependency: `requests`. Everything else is stdlib. - XML parsing with `xml.etree.ElementTree` (stdlib), not lxml - MinIO API endpoint: `minio-api.tail5b443a.ts.net` (port 443 via Tailscale, routes to 9000) - Credentials: MinIO access key + secret key (get from env vars `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY`) - Region: `us-east-1` (MinIO default) - Follow existing SDK conventions from `pal-e-docs-sdk` for project structure and PyPI publishing ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `project-pal-e-platform` — project this affects - `phase-pal-e-platform-24-minio-sdk` — phase note with full scope

forgejo_admin commented

2026-03-21 16:06:44 +00:00

Owner

Type

Feature

Lineage

plan-pal-e-platform → Phase 24 (MinIO SDK)

Repo

forgejo_admin/minio-sdk

User Story

As a platform developer
I want a pure Python SDK that wraps the raw S3 REST API
So that I can interact with MinIO without depending on boto3 or any third-party S3 SDK

Context

MinIO is deployed on the pal-e platform (Helm chart v5.4.0, namespace minio). The stock MinIO Console UI is unusable on mobile. We're building a custom mobile-first interface. This SDK is the foundation — it wraps every S3 endpoint with custom Signature V4 signing. No boto3, no minio-py, no aws-sdk. Just requests + Python stdlib.

The S3 API is just HTTP with XML responses. The only complex part is AWS Signature V4 signing (4 chained HMAC-SHA256 operations). MinIO's S3 implementation is identical to AWS with minor gotchas (API port 9000, no regional routing, AbortIncompleteMultipartUpload lifecycle not supported).

Key decisions:

No third-party S3 SDKs — own the stack, full control over HTTP, no hidden failures
requests is the only external dep — stdlib hmac + hashlib for signing, xml.etree for parsing
Published to Forgejo PyPI — same pattern as pal-e-docs-sdk

File Targets

Files to create:

src/minio_sdk/__init__.py — package init, exports client class
src/minio_sdk/client.py — main MinioClient class with all S3 operations
src/minio_sdk/signer.py — AWS Signature V4 signing module
src/minio_sdk/models.py — dataclasses for Bucket, Object, Part, etc.
src/minio_sdk/xml_parser.py — S3 XML response parsing to Python objects
src/minio_sdk/exceptions.py — typed exceptions for S3 errors
tests/test_signer.py — unit tests for Signature V4 with known test vectors
tests/test_client.py — integration tests against live MinIO
pyproject.toml — project config, dependencies, build config
CLAUDE.md — agent conventions for this repo

Acceptance Criteria

Signature V4 signing works against live MinIO (not mocked)
All bucket operations: list, create, delete, head, versioning, policy, tagging, lifecycle
All object operations: put, get, head, delete, batch delete, copy, list (v2), ACL, tagging
All multipart operations: initiate, upload part, complete, abort, list parts
Presigned URL generation: GET (download) and PUT (upload) with configurable expiration
XML responses parsed to typed Python objects (dataclasses)
Integration tests pass against MinIO at minio-api.tail5b443a.ts.net
Package installable via pip install from Forgejo PyPI
Zero boto3 / minio-py / aws-sdk dependencies

Test Expectations

Unit tests: Signature V4 signing with known AWS test vectors (canonical request, string-to-sign, signature)
Integration tests: every endpoint tested against live MinIO with real buckets/objects
Test cleanup: tests create and delete their own test buckets/objects
Run command: pytest tests/ -v

Constraints

Only external dependency: requests. Everything else is stdlib.
XML parsing with xml.etree.ElementTree (stdlib), not lxml
MinIO API endpoint: minio-api.tail5b443a.ts.net (port 443 via Tailscale, routes to 9000)
Credentials: MinIO access key + secret key (get from env vars MINIO_ACCESS_KEY / MINIO_SECRET_KEY)
Region: us-east-1 (MinIO default)
Follow existing SDK conventions from pal-e-docs-sdk for project structure and PyPI publishing