Skip to content

feat(rc-ops)!: add health, readiness, and usage commands - #294

Merged
cxymds merged 7 commits into
mainfrom
cxymds/issue-1377-ops-utilities
Jul 22, 2026
Merged

feat(rc-ops)!: add health, readiness, and usage commands#294
cxymds merged 7 commits into
mainfrom
cxymds/issue-1377-ops-utilities

Conversation

@cxymds

@cxymds cxymds commented Jul 22, 2026

Copy link
Copy Markdown
Member

Closes rustfs/backlog#1377

Background and user impact

The CLI did not expose RustFS liveness/readiness probes or the server's background-scanner data-usage snapshot. Operators had to combine curl, admin credentials, and custom S3 listing scripts, and a client-side usage scan could become unexpectedly expensive if started implicitly.

What changed

  • Adds rc ping for bounded unsigned GET /health liveness checks.
  • Adds rc ready for bounded unsigned GET /health/ready dependency-readiness checks.
  • Adds rc du ALIAS[/BUCKET[/PREFIX]].
  • Uses the signed RustFS GET /rustfs/admin/v3/datausageinfo snapshot when supported.
  • Requires explicit --fallback before any slower client-side S3 scan.
  • Supports paginated current objects, versions/delete markers, incomplete multipart uploads, and uploaded parts.
  • Reports sanitized human output and schema-v3 JSON with partial-result semantics.

Review resolution

  • Guards current-object pagination against missing, empty, or non-advancing continuation tokens, returning a bounded network error instead of looping.
  • Adds regression coverage for each invalid-token case.
  • Adds an end-to-end du test asserting unsupported-feature exit code 7 and verifying that fallback scanning is not started.
  • Keeps readiness failure and transport failure intentionally retryable as exit code 3; their messages retain the operational distinction.
  • Does not independently change the workspace package version: the repository's release/tag stream is already ahead of 0.1.24, while this PR preserves output v1/v2 and adds only the explicitly versioned v3 families. The protected-file gate is satisfied through the BREAKING marker and migration guidance below.

RustFS compatibility and safety

  • /health and /health/ready are public operational endpoints; credentials are never attached.
  • The data-usage route is signed and capability-gated.
  • Prefix and incomplete-upload dimensions absent from the snapshot require explicit S3 fallback.
  • Health timeouts are bounded to 1–300 seconds.
  • Authentication failures remain exit code 4 and never trigger a scan unless --fallback was explicit.
  • Alias-wide scan failures preserve successful buckets, mark output partial, and exit 3.
  • Totals use saturating arithmetic and server-controlled text is sanitized before human output.

BREAKING contract note

This PR adds command contracts under the protected docs/reference/rc/ path and is therefore marked BREAKING per repository policy. Existing commands, exit codes, config schema, and output v1/v2 remain unchanged. Consumers of the new commands should select the output-v3 health or usage family.

Validation

  • cargo fmt --all --check: passed.
  • cargo clippy --workspace -- -D warnings: passed with zero warnings.
  • cargo test --workspace: passed.
  • Compatibility script unit tests and repository consistency check: passed.
  • Focused object pagination, du exit-code, output-schema, replication, and launcher tests: passed after integration with latest main.

@cxymds

cxymds commented Jul 22, 2026

Copy link
Copy Markdown
Member Author

This PR supersedes #275 after its base branch was deleted. It carries the prior review fixes: bounded current-object pagination for missing, empty, and repeated tokens; regression tests for those cases; and an end-to-end unsupported-feature exit-code 7 test that verifies no fallback scan occurs. The branch has been integrated with latest main and the full mandatory validation suite passes. Please re-review the migrated changes.

@cxymds
cxymds requested a review from overtrue July 22, 2026 14:07
@cxymds
cxymds marked this pull request as ready for review July 22, 2026 14:07
@cxymds
cxymds merged commit e212950 into main Jul 22, 2026
17 checks passed
@cxymds
cxymds deleted the cxymds/issue-1377-ops-utilities branch July 22, 2026 14:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant