epic: redisctl 1.0 Redis Cloud client readiness audit

[joshrotenberg]

Goal

Establish enough evidence and API stability in redis-cloud-rs for redisctl 1.0 to depend on it as the supported Redis Cloud client.

This is not a requirement to implement every API operation. It is a requirement to make the supported surface explicit, current against the published specification, and validated against a dedicated non-production Redis Cloud account.

Existing audit backlog

• docs: README installation snippet pins redis-cloud = "0.10", current release is 0.11.0 #144 — correct the published-version documentation and prevent recurrence
• test: error.rs is ~11% line coverage — error Display/From/source paths largely untested #145 — test the public error contract
• test: connectivity PSC and Transit Gateway modules lag far behind sibling connectivity coverage #146 — close PSC and Transit Gateway request/response test gaps
• test(compliance): implement the deferred T4 destructive/mutating write pass #147 — add guarded destructive/mutating lifecycle validation
• fix(spec): normalize /v1 paths and refresh the bundled OpenAPI surface #148 — normalize /v1, refresh the bundled OpenAPI document, and reconcile coverage
• ci(spec): run Redis Cloud OpenAPI drift detection on a schedule #149 — schedule specification-drift detection
• ci(test): establish a ratcheting code-coverage floor #150 — establish a ratcheting coverage floor
• ci(live): schedule safe Redis Cloud contract and compliance validation #151 — schedule safe live contract/compliance validation

Readiness review

• Compare the complete typed route inventory with the current published Redis Cloud OpenAPI document.
• Classify every published operation as supported, deliberately unsupported, or raw-only, with rationale.
• Run the safe compliance matrix against a dedicated test account and review every known difference and skipped category.
• Exercise representative reversible and destructive lifecycles with explicit cost, cleanup, and safety controls.
• Review public model behavior for unknown fields, optionality, numeric/string drift, pagination, async tasks, and error classification.
• Review the consumer-facing API for changes that should happen before the next stable client release.
• Publish an audited crate release with migration notes suitable for redisctl consumption.

Exit criteria

• The bundled specification and route inventory match the current upstream source of truth.
• Live validation covers the critical read and lifecycle journeys used by redisctl.
• Unsupported or unverified areas are explicit and are not described as full coverage.
• CI detects future specification drift and material coverage regression.
• A released crate version is available for redisctl integration; redisctl does not consume an unreleased branch for 1.0.

Downstream

redis/redisctl#1090 will remain blocked until this audit is complete. Downstream integration is tracked by redis/redisctl#1086 and requires the audited crate release plus passing Cloud CLI/MCP contract tests.

[joshrotenberg]

Full live-validation plan (2026-08-11)

This plan is based on a clean run of the prepared account and the refreshed 169-operation specification in #155. Current evidence:

• Live integration: 23/23 pass.
• Compliance: PASS=66, DRIFT=0, FAIL=0, KNOWN-DIFF=6, SKIP=97, UNCOVERED=0.
• The 97 skips comprise 44 general writes, 50 connectivity/Active-Active operations, one binary download covered elsewhere, one Data Integration proxy read, and one endpoint-redirection status read.

Validation ladder

Tier	Scope	Trigger	Account impact	Target cadence
T0	fmt, clippy, unit/wiremock, fixtures, route inventory, bundled spec validation	every PR	none	every PR
T1	safe live reads plus raw → typed → reserialized drift detection	schedule + manual	none	daily
T2	reversible writes on pinned resources: tags, names, ACL rules, then CIDR, maintenance windows, resource tags, database updates, ACL roles/users	schedule + manual	temporary, restored	weekly
T3	disruptive operations on disposable databases: backup, import, traffic state, upgrade, flush	manual approval	data/state changes	pre-release
T4	complete Pro and Essentials create → verify → update → delete lifecycles; endpoint redirection and Data Integration lifecycles	manual approval	billable resource creation/deletion	pre-release
T5	VPC peering, PrivateLink, PSC, TGW, and Active-Active region lifecycles	manual approval + provider setup	cloud/network changes and cost	milestone/manual

Safety gates

1. Keep every live test #[ignore]; normal cargo test remains offline.
2. Verify an expected account ID before the first write, not merely valid credentials.
3. Require progressively stronger flags: REDIS_CLOUD_ALLOW_REVERSIBLE=1, REDIS_CLOUD_ALLOW_DESTRUCTIVE=1, REDIS_CLOUD_ALLOW_BILLABLE=1, and REDIS_CLOUD_ALLOW_CONNECTIVITY=1.
4. Require test-owned resource names carrying a unique run ID. Never mutate a discovered arbitrary resource.
5. Serialize live jobs with a GitHub Actions concurrency group and environment approval for T3-T5.
6. Enforce hard caps: maximum resources per run, bounded polling, overall timeout, and a documented spend ceiling.
7. Write a cleanup journal as resources are created. Unwind it in reverse order on success, failure, cancellation, and timeout.
8. Finish with a residue audit that fails if test-prefixed resources remain. Preserve IDs/statuses in the job summary, but never archive raw account payloads or credentials.
9. Do not bless compliance changes automatically. Upload a sanitized diff summary and require review before updating the committed baseline.

Resource matrix

The existing pinned Pro and Essentials subscription/database pair is sufficient for T1 and most T2 work. Additional resources are needed only as their tier is implemented:

• T3: an empty disposable Pro DB and Essentials DB, a non-sensitive import fixture URL, and an explicit Redis-version upgrade target.
• T4: payment method/billing permission, a tested minimum-cost Pro configuration, an Essentials plan, two disposable databases for endpoint redirection, and a provisioned Data Integration workspace.
• T5: dedicated AWS/GCP/Azure test projects/accounts, VPCs and CIDRs, IAM roles, PrivateLink/PSC/TGW prerequisites, plus an Active-Active subscription with region IDs.

Implementation sequence

1. ci(live): schedule safe Redis Cloud contract and compliance validation #151: add the scheduled/manual T1 workflow, secret isolation, concurrency, sanitized summary, and reproducible local command.
2. test(compliance): implement the deferred T4 destructive/mutating write pass #147 foundation: add the shared preflight, account-ID assertion, tier flags, run naming, cleanup journal, pollers, and residue audit before adding destructive cases.
3. Expand T2 one reversible family at a time; each lifecycle must snapshot and restore state and have an interrupted-run cleanup test.
4. Add T4 Essentials lifecycle first, then Pro lifecycle with explicit cost approval. Keep subscription and database creation/deletion in separate tests so cleanup failures are diagnosable.
5. Add endpoint redirection using two disposable DBs and always exercise revert before deletion. Add Data Integration root/proxy lifecycle once a test workspace can be provisioned.
6. Split T5 by provider and topology; do not make connectivity prerequisites part of the ordinary T1/T2 account.
7. After the matrix is stable, use ci(test): establish a ratcheting code-coverage floor #150 to ratchet offline coverage and add a separate live-operation coverage metric.

Exit criteria

• Every one of the 169 operations is PASS, KNOWN-DIFF with reviewed evidence, or SKIP with a specific unavailable prerequisite; no generic deferred-write reason remains.
• T1 and T2 run routinely with zero residual resources.
• T3-T5 are reproducible through manual workflows with approvals, cost bounds, and cleanup reports.
• A failed or cancelled run cannot silently leave test-owned resources behind.
• The release audit records the exact spec revision, compliance summary, known differences, and lifecycle runs used as evidence.

This plan leaves #147, #151, and #152 open for implementation and audit completion.