Skip to content

AGENTS.md

Latest commit

 

History

History
86 lines (63 loc) · 3.33 KB

AGENTS.md

File metadata and controls

86 lines (63 loc) · 3.33 KB
Raw

CLAUDE.md

Project Overview

Apache Reqsign — a Rust library for signing HTTP API requests across cloud providers (AWS, Azure, Google, Aliyun, Huawei, Tencent, Oracle, Volcengine).

Architecture

The codebase is a Cargo workspace with three layers:

  • core (reqsign-core): traits (ProvideCredential, SignRequest, SigningCredential) and the runtime-agnostic Context / Signer types.
  • context/*: pluggable runtime adapters (file-read-tokio, http-send-reqwest, command-execute-tokio).
  • services/*: per-cloud signing implementations, each its own crate. AWS support is split into shared credentials/canonicalization (aws-core), SigV4 (aws-v4), and SigV4a (aws-v4a).
  • reqsign: facade crate re-exporting everything behind feature flags; provides default_context() and per-service default_signer().

Key Design Decisions

  • No default implementations in Context: Context::new() wires up no-op stubs. Users (or default_context()) must explicitly plug in FileRead, HttpSend, Env, CommandExecute.
  • MaybeSend futures: core traits use MaybeSend instead of async_trait so that the crate compiles for wasm32-unknown-unknown.
  • Dyn-trait pairs: every async trait Foo has a FooDyn counterpart and a blanket impl FooDyn for T: Foo, enabling Arc<dyn FooDyn> inside Signer.

API Design References

When working on an API area with an explicit design document, follow that document as the source of truth instead of inferring policy from the current implementation.

For security-sensitive changes, follow SECURITY.md and THREAT_MODEL.md as the source of truth for Reqsign's security boundary and its relationship to OpenDAL and other host applications.

Default Credential Provider

All future refactors and API reviews around DefaultCredentialProvider must follow the authoritative design in docs/default-credential-provider-api.md.

Treat any future API change that reintroduces the following as a design regression unless explicitly approved: configure_*, disable_*(bool), fallback-based re-enabling of removed slots during build().

Build & Test

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --no-fail-fast            # unit tests
cargo test --doc --all-features --workspace  # doc tests

Integration Tests

Integration tests live per-service under services/<name>/tests/ and are gated by REQSIGN_<SERVICE>_TEST* env vars. Secrets are loaded via 1Password Connect in CI. Some providers (IMDS, ECS, SSO, Process, Cognito) use Python mock servers checked into services/aws-v4/tests/mocks/.

WASM Compatibility

reqsign-core and a subset of services (aws-v4, aws-v4a, azure, aliyun, tencent) must compile for wasm32-unknown-unknown. CI verifies this supported subset.

Versioning

  • Service crates and core share a lockstep major version (3.0.0).
  • reqsign-http-send-reqwest has its own major (4.0.0).
  • The facade reqsign crate follows an independent scheme (0.20.0).
  • Release is triggered by pushing a v*.*.* tag; cargo publish --workspace publishes everything.

License

Apache-2.0 (ASF). All source files must carry the Apache header, enforced by hawkeye via licenserc.toml.