Skip to content

MiniS3 M2 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add durable multipart uploads, S3-shaped conditional requests, deterministic lifecycle expiration, two public-API labs, and synchronized bilingual teaching documentation.

Architecture: MiniS3 remains the serialized service facade. multipart.py, conditional.py, and lifecycle.py own pure values and rules; DiskStorage owns invisible upload staging and keeps the existing bucket-manifest rename as the only object visibility point. Object timestamps and multipart provenance are immutable version metadata so restart recovery and lifecycle evaluation remain deterministic.

Tech Stack: Python 3.12+, standard library only at runtime, uv, hatchling, pytest.

File map

  • src/minis3/multipart.py: upload/part values, composite ETag, and complete-list validation.
  • src/minis3/conditional.py: pure If-Match and If-None-Match evaluation.
  • src/minis3/lifecycle.py: immutable expiration rules/actions and pure evaluation.
  • src/minis3/model.py, bucket.py: timestamps, explicit ETag publication, lifecycle mutations.
  • src/minis3/storage/disk.py: durable invisible upload staging, reload, cleanup, and manifest integration.
  • src/minis3/store.py: locked public API and manual lifecycle tick.
  • src/minis3/errors.py, __init__.py: S3-shaped errors and public values.
  • tests/test_multipart.py, test_conditional.py, test_lifecycle.py: M2 behavioral contracts.
  • tests/test_storage.py: complete-before/after-publication crash contracts.
  • labs/lab_multipart_etag.py, lab_conditional_cas.py: public-API teaching demonstrations.
  • README, mapping, differences, labs guide, and MkDocs navigation: bilingual M2 teaching surface.

Task 1: Multipart contracts and pure validation

  • [x] Add failing tests for deterministic initiation, replaceable parts, invisible incomplete uploads, ordered checklist validation, minimum size for every listed part except the last, exact binary-MD5 composite ETag, abort, and restart.
  • [x] Run uv run pytest -q tests/test_multipart.py and confirm failures are missing M2 API/types.
  • [x] Implement immutable multipart values, S3-shaped validation errors, durable upload directories, and public init/upload/complete/abort methods.
  • [x] Run the focused test file and retain green behavior before continuing.

Task 2: Multipart publication crash boundary

  • [x] Add failing storage tests that inject a crash before and after complete's bucket manifest publication.
  • [x] Confirm pre-publication restart exposes no object while preserving the upload; confirm post-publication restart exposes the complete object and removes completed staging.
  • [x] Add multipart provenance to immutable version metadata and recovery cleanup without adding a second visibility point.
  • [x] Run multipart plus storage tests to green.

Task 3: Conditional requests

  • [x] Add failing tests for GET If-None-Match NotModified, GET If-Match failure, PUT/DELETE If-Match compare-and-swap, wildcard matching, and two concurrent writers with exactly one winner.
  • [x] Run uv run pytest -q tests/test_conditional.py and confirm missing API/error failures.
  • [x] Implement pure match functions and evaluate conditions under the same store lock as each mutation.
  • [x] Run conditional and existing versioning tests to green.

Task 4: Lifecycle

  • [x] Add failing tests for pure rule evaluation, prefix filtering, current expiration to delete marker, noncurrent physical deletion, injected-clock boundary behavior, and restart persistence.
  • [x] Run uv run pytest -q tests/test_lifecycle.py and confirm missing API/type failures.
  • [x] Add immutable creation timestamps, rules/actions, a side-effect-free evaluator, and a locked manual tick that persists one candidate bucket state.
  • [x] Run lifecycle, versioning, storage, and listing tests to green.

Task 5: Labs and bilingual documentation

  • [x] Add the multipart ETag mystery lab and conditional CAS race lab using only the minis3 public API.
  • [x] Run both labs and record their deterministic output.
  • [x] Update English/Chinese READMEs, mapping matrices, differences, and lab guides; add direct MkDocs navigation entries for both new labs.
  • [x] Check that all M2 rows separately state semantic tier and availability, and remove obsolete “planned M2” claims.

Task 6: Final verification

  • [x] Review the diff for public API consistency, why-comments, stale M1-only wording, and accidental generated data.
  • [x] Run uv run pytest -q, both new labs, git diff --check, and an import/compile check.
  • [x] Count source lines in the three implemented M2 modules, report the exact pytest total and lab output summaries, and confirm no commit was created.