use crate TypedBuilder for builders

bugfixes

WIP

doc updated

Author: HJLebbink

.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep:*)"
+    ],
+    "deny": []
+  },
+  "$schema": "https://json.schemastore.org/claude-code-settings.json"
+}

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -0,0 +1,245 @@
+# Claude Code Style Guide for MinIO Rust SDK
+
+- Only provide actionable feedback.
+- Exclude code style comments on generated files. These will have a header signifying that.
+- Use github markdown folded sections for all items.
+- Do not use emojis.
+- Do not add a "feel good" section.
+
+## Copyright Header
+
+All source files that haven't been generated MUST include the following copyright header:
+
+```go
+// MinIO Rust Library for Amazon S3 Compatible Cloud Storage
+// Copyright 20?? MinIO, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+```
+
+## Code Style Guidelines
+
+### Ignore files
+- Ignore files from processing mentioned under '.gitignore'
+
+### Comments
+- **NO redundant comments** - Code should be self-documenting
+- Avoid obvious comments like `// Set x to 5` for `x := 5`
+- Only add comments when they explain WHY, not WHAT
+- Document complex algorithms or non-obvious business logic
+
+## Critical Code Patterns
+
+### Builder Pattern
+All S3 API requests MUST use the builder pattern, with the following documentation but then for the appropriate API
+
+```rust
+/// Argument builder for the [`AppendObject`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-buckets-objects-append.html) S3 API operation.
+///
+/// This struct constructs the parameters required for the [`Client::append_object`](crate::s3::client::Client::append_object) method.
+```
+
+**Key Requirements:**
+1. The aws docs url must exist. 
+
+### Admin API Handler Pattern
+Handler methods for `adminAPIHandlers` do not follow the previous pattern as it is handled in a middleware function.
+Instead, they should follow this pattern:
+
+```go
+func (a adminAPIHandlers) HandlerName(w http.ResponseWriter, r *http.Request) {
+    ctx := r.Context()
+    
+    // Option 1 for objectAPI fetch
+    objectAPI := newObjectLayerFn()
+    if objectAPI == nil || globalNotificationSys == nil {
+        writeErrorResponseJSON(ctx, w, errorCodes.ToAPIErr(ErrServerNotInitialized), r.URL)
+        return
+    }
+    
+    // Option 2 for objectAPI fetch
+    objectAPI, _ := validateAdminReq(ctx, w, r, policy.DeletePolicyAdminAction)
+    if objectAPI == nil {
+        return
+    }
+    
+    // Implementation here
+    
+    // Error handling pattern:
+    if err != nil {
+        writeErrorResponseJSON(ctx, w, toAdminAPIErr(ctx, err), r.URL)
+        return
+    }
+}
+```
+
+## Code Quality Principles
+
+### Why Code Quality Standards Are Mandatory
+
+Code quality standards are **critical business requirements** for MinIO Rust SDK:
+
+1. **Enterprise Data Safety**: A single bug can corrupt terabytes of customer data across distributed systems
+2. **Code Efficientcy**: MinIO Rust SDK code must be efficient and performant
+3. **Scalability**: MinIO Rust SDK must be able to handle thousands of concurrent requests
+4. **High Availability**: Systems must handle failures gracefully - unpredictable code creates cascading failures
+5**Developer Velocity**: New team members must understand complex distributed systems quickly and safely
+
+### Predictable Code Requirements
+
+Code must exhibit **deterministic behavior** to ensure system reliability:
+
+1. **Managed Global State**: Global variables are acceptable for system-wide shared state (e.g., `globalObjectLayer`, `globalNotificationSys`, `globalSiteReplicationSys`) that all layers need consistent access to
+2. **Explicit Dependencies**: Business logic dependencies should be passed as parameters or dependency injection
+3. **Deterministic Operations**: Avoid time-dependent logic, random values, or platform-specific behavior in core paths
+4. **Consistent Error Handling**: Same error conditions must always produce identical error responses
+5. **Idempotent Operations**: Operations should be safely repeatable without unintended side effects
+
+### Readability Standards
+
+Complex distributed systems code must remain **human-readable**:
+
+1. **Self-Documenting Code**: Function and variable names should clearly express business intent
+2. **Consistent Patterns**: Follow established patterns (HTTP handlers, error handling, logging)
+3. **Logical Flow**: Code should read as a clear narrative from top to bottom
+4. **Minimal Cognitive Load**: Each function should have a single, well-defined responsibility
+5. **Clear Abstractions**: Break complex operations into well-named, focused helper functions
+
+### Separation of Concerns
+
+**Architectural layers must maintain clear boundaries**:
+
+1. **Handler Layer**: HTTP request/response processing, input validation, context creation
+2. **Service Layer**: Business logic orchestration, data transformation
+3. **Storage Layer**: Data persistence, replication, consistency management
+4. **Utility Layer**: Reusable helpers with no business logic dependencies
+5. **Global Coordination**: Shared state management via global variables where all components need consistent views
+
+### Functions and Methods
+- Keep functions focused on a single responsibility
+- Use descriptive names that clearly indicate purpose and business intent
+- Prefer early returns to reduce nesting complexity
+- Error handling should be immediate and explicit
+- **Function length guideline**: Most functions should be under 100 lines; handlers may be longer due to validation logic
+- **Parameter limits**: Prefer structs over long parameter lists for better maintainability
+
+### Variables
+- Use meaningful variable names that reflect business concepts
+- Variable names should reflect usage frequency: frequent variables can be shorter
+- Constants should follow Rust patterns
+- Global variables should be clearly identified and documented for their system-wide purpose
+
+### Developer Documentation
+
+**All significant features must include developer documentation** in the `docs/` directory:
+
+1. **API Documentation**: New endpoints must have usage examples in `docs/`
+2. **Architecture Decisions**: Complex algorithms or design patterns should be documented
+3. **Configuration Changes**: New config options must be documented with examples
+4. **Integration Guides**: External system integrations need clear setup instructions
+5. **Future Developer Context**: Document WHY decisions were made, not just WHAT was implemented
+
+## Testing Requirements
+
+### Why Unit Tests Are Mandatory
+
+Unit tests are **non-negotiable** in this project for critical business reasons:
+
+1. **Data Integrity**: MinIO EOS handles enterprise-critical data. A single bug can cause data loss affecting thousands of users
+2. **Security Compliance**: Financial and healthcare customers require verifiable code quality. Tests provide audit trails  
+3. **Multi-tenant Reliability**: One customer's workload cannot impact another's. Tests ensure proper isolation
+4. **Performance SLAs**: Enterprise customers have strict performance requirements. Tests validate behavior under load
+5. **API Stability**: Breaking changes can affect thousands of applications. Tests prevent regressions
+6. **Distributed System Complexity**: Complex interactions between storage nodes require comprehensive testing
+
+### Mandatory Unit Tests
+**EVERY implementation MUST include unit tests** without being explicitly asked. Follow these patterns:
+
+1. Test files must be named `*_test.go`
+2. Test functions must start with `Test`
+3. Use table-driven tests for multiple scenarios
+4. Cover both success and error cases, including edge conditions
+5. Mock external dependencies appropriately
+6. **Test coverage guideline**: Aim for comprehensive coverage of new code paths
+7. Include negative tests for error conditions and boundary cases
+8. Add benchmarks for performance-critical code paths
+
+
+## Testing Commands
+
+## Pre-commit Checklist
+
+Before any code changes:
+1. ✅ Run `make lint` to check code style
+2. ✅ Run `make test` to ensure all tests pass
+3. ✅ Run `make lint-fix` to auto-fix linting issues
+4. ✅ Ensure new code has appropriate test coverage
+5. ✅ Verify no redundant comments are added
+
+## Generated Code Management
+
+**CRITICAL**: This codebase has 54+ auto-generated files ending in `_gen.go`.
+
+### When to Regenerate:
+- After modifying generator templates
+- When adding new API endpoints
+- When changing data structures used by generators
+
+### Required Steps:
+```bash
+# 1. Generate code
+go generate ./...
+
+# 2. MUST commit generated files (they are NOT in .gitignore)
+git add *_gen.go
+
+# 3. Verify no uncommitted generated files remain
+git diff --name-only | grep '_gen.go$' || echo "All generated files committed"
+```
+
+### Generated File Pattern:
+- Files ending in `_gen.go` are auto-generated
+- **DO NOT edit these files manually**
+- Always commit generated changes with your PR
+- CI will fail if generated files are out of sync
+
+## Directory Structure Conventions
+
+- `/cmd` - Main application code and server components
+- `/internal` - Internal packages not meant for external use
+- `/pkg` - Public packages that can be imported by external projects
+- `/docs` - Documentation and scripts
+- `/buildscripts` - Build and CI/CD scripts
+
+## Common Patterns to Follow
+
+### Logging
+Use the log package
+
+```go
+log::info!("life cycle settings before setting: resp={resp:?}");
+```
+
+## Improvement Suggestions
+
+Claude will periodically analyze the codebase and suggest:
+- Missing test coverage areas
+- Performance optimizations
+- Code refactoring opportunities
+- Security improvements
+- Documentation gaps
+
+## Quick Reference
+
+- **Fix linting**: `cargo fmt --all`
+- **Run specific test**: `cargo test --test TestName`

Cargo.toml

@@ -33,41 +33,42 @@ bytes = { workspace = true }
 async-std = { workspace = true, features = ["attributes"] }
 reqwest = { workspace = true, features = ["stream"] }
 
-async-recursion = "1.1.1"
-async-stream = "0.3.6"
-async-trait = "0.1.88"
-base64 = "0.22.1"
-chrono = "0.4.41"
-crc = "3.3.0"
+async-recursion = "1.1"
+async-stream = "0.3"
+async-trait = "0.1"
+base64 = "0.22"
+chrono = "0.4"
+crc = "3.3"
 dashmap = "6.1.0"
-env_logger = "0.11.8"
-hmac = { version = "0.12.1", optional = true }
-hyper = { version = "1.6.0", features = ["full"] }
-lazy_static = "1.5.0"
-log = "0.4.27"
-md5 = "0.8.0"
-multimap = "0.10.1"
-percent-encoding = "2.3.1"
-url = "2.5.4"
-regex = "1.11.1"
-ring = { version = "0.17.14", optional = true, default-features = false, features = ["alloc"] }
-serde = { version = "1.0.219", features = ["derive"] }
-serde_json = "1.0.142"
-sha2 = { version = "0.10.9", optional = true }
-urlencoding = "2.1.3"
-xmltree = "0.11.0"
-http = "1.3.1"
-thiserror = "2.0.14"
+env_logger = "0.11"
+hmac = { version = "0.12", optional = true }
+hyper = { version = "1.7", features = ["full"] }
+lazy_static = "1.5"
+log = "0.4"
+md5 = "0.8"
+multimap = "0.10"
+percent-encoding = "2.3"
+url = "2.5"
+regex = "1.11"
+ring = { version = "0.17", optional = true, default-features = false, features = ["alloc"] }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+sha2 = { version = "0.10", optional = true }
+urlencoding = "2.1"
+xmltree = "0.11"
+http = "1.3"
+thiserror = "2.0"
+typed-builder = "0.21"
 
 [dev-dependencies]
 minio-common = { path = "./common" }
 minio-macros = { path = "./macros" }
-tokio = { version = "1.47.1", features = ["full"] }
-async-std = { version = "1.13.1", features = ["attributes", "tokio1"] }
-clap = { version = "4.5.44", features = ["derive"] }
-rand = { version = "0.9.2", features = ["small_rng"] }
-quickcheck = "1.0.3"
-criterion = "0.7.0"
+tokio = { version = "1.47", features = ["full"] }
+async-std = { version = "1.13", features = ["attributes", "tokio1"] }
+clap = { version = "4.5", features = ["derive"] }
+rand = { version = "0.9", features = ["small_rng"] }
+quickcheck = "1.0"
+criterion = "0.7"
 
 [lib]
 name = "minio"

README.md

@@ -24,8 +24,8 @@ use minio::s3::response::BucketExistsResponse;
 
 #[tokio::main]
 async fn main() {
-    let client: Client = Default::default(); // configure your client
-
+    let client = Client::create_client_on_localhost().unwrap(); // configure your client here
+    
     let exists: BucketExistsResponse = client
         .bucket_exists("my-bucket")
         .send()

benches/s3/bench_bucket_exists.rs

@@ -23,6 +23,11 @@ pub(crate) fn bench_bucket_exists(criterion: &mut Criterion) {
         "bucket_exists",
         criterion,
         || async { Ctx2::new().await },
-        |ctx| BucketExists::new(ctx.client.clone(), ctx.bucket.clone()),
+        |ctx| {
+            BucketExists::builder()
+                .client(ctx.client.clone())
+                .bucket(ctx.bucket.clone())
+                .build()
+        },
     );
 }