Skip to content

Commit 1ee21b7

Browse files
CopilotHJLebbink
Copilot
and
HJLebbink
authored
Add .github/copilot-instructions.md for repository onboarding (#191)
* Initial plan * Add comprehensive copilot-instructions.md file Co-authored-by: HJLebbink <[email protected]> * Add PR label requirement to copilot instructions Co-authored-by: HJLebbink <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: HJLebbink <[email protected]>
1 parent e16d6d4 commit 1ee21b7

File tree

1 file changed

+339
-0
lines changed

1 file changed

+339
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 339 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,339 @@
1+
# Copilot Instructions for minio-rs
2+
3+
## Repository Overview
4+
5+
**minio-rs** is a MinIO Rust SDK for Amazon S3 compatible cloud storage. It provides a strongly-typed, async-first interface to MinIO and S3-compatible object storage APIs using a request builder pattern with full async/await support via tokio.
6+
7+
- **Language**: Rust (edition 2024)
8+
- **Rust Version**: 1.88.0 (specified in `rust-toolchain.toml`)
9+
- **Project Type**: Library crate with examples, integration tests, and benchmarks
10+
- **Repository Size**: ~160 Rust source files, ~273 total files
11+
- **License**: Apache-2.0
12+
13+
## Build Commands and Validation
14+
15+
### Prerequisites
16+
- Rust toolchain 1.88.0 with clippy and rustfmt components (automatically installed via `rust-toolchain.toml`)
17+
- No additional system dependencies required for basic builds
18+
19+
### Essential Commands (in order of typical workflow)
20+
21+
**ALWAYS run these commands in sequence before submitting changes:**
22+
23+
1. **Format Check** (~1 second):
24+
```bash
25+
cargo fmt --all -- --check
26+
```
27+
- Must pass with no output
28+
- Auto-fix: `cargo fmt --all`
29+
30+
2. **Clippy Linting** (~45-70 seconds from clean, instant if cached):
31+
```bash
32+
cargo clippy --all-targets --all-features --workspace -- -D warnings
33+
```
34+
- Fails on any warnings
35+
- This is the primary lint check used in CI
36+
37+
3. **Build** (~90 seconds for full build from clean, ~45 seconds for basic build, ~20 seconds incremental):
38+
```bash
39+
cargo build --bins --examples --tests --benches --verbose
40+
```
41+
- Builds all targets including examples, tests, and benchmarks
42+
- Basic library build: `cargo build` (~20-45 seconds)
43+
- Clean build: `cargo clean` first (removes 6-7 GB in `target/`)
44+
45+
4. **Unit Tests** (<1 second):
46+
```bash
47+
cargo test --lib
48+
```
49+
- Runs only library unit tests (3 tests)
50+
- Does NOT require MinIO server
51+
- Safe to run in any environment
52+
53+
5. **Integration Tests** (require MinIO server setup):
54+
```bash
55+
# IMPORTANT: Integration tests require a running MinIO server
56+
./tests/start-server.sh
57+
export SERVER_ENDPOINT=localhost:9000
58+
export ACCESS_KEY=minioadmin
59+
export SECRET_KEY=minioadmin
60+
export ENABLE_HTTPS=1
61+
export MINIO_SSL_CERT_FILE=./tests/public.crt
62+
63+
# Run with multi-threaded runtime
64+
MINIO_TEST_TOKIO_RUNTIME_FLAVOR="multi_thread" cargo test -- --nocapture
65+
66+
# OR run with current-thread runtime
67+
MINIO_TEST_TOKIO_RUNTIME_FLAVOR="current_thread" cargo test -- --nocapture
68+
```
69+
- WITHOUT these environment variables, integration tests will FAIL
70+
- The server setup script downloads and starts MinIO locally
71+
- Tests are located in `tests/` directory (30+ test files)
72+
- Use `--test <test_name>` to run a specific test file
73+
74+
6. **Documentation** (~8-10 seconds):
75+
```bash
76+
cargo doc --no-deps
77+
```
78+
- Generates documentation in `target/doc/`
79+
- May show ~13 warnings about unresolved links (existing issue)
80+
- Full doc build: `cargo doc --all` (includes dependencies)
81+
82+
7. **Quick Check** (~29 seconds from clean):
83+
```bash
84+
cargo check
85+
```
86+
- Faster than build, useful for quick syntax validation
87+
88+
### Feature Flags
89+
- **Default features**: `default-tls`, `default-crypto`
90+
- **Crypto backends**:
91+
- `default-crypto` (sha2 + hmac) - default
92+
- `ring` - alternative crypto backend
93+
- **TLS backends**:
94+
- `default-tls` - default
95+
- `native-tls`
96+
- `rustls-tls`
97+
- **Special**: `localhost` feature for local testing
98+
99+
⚠️ **IMPORTANT**: Building with `--no-default-features` will FAIL. Always use at least one crypto backend and one TLS backend:
100+
```bash
101+
cargo build --no-default-features --features "ring,default-tls" # Works
102+
cargo build --no-default-features # FAILS
103+
```
104+
105+
### Benchmarks
106+
```bash
107+
cargo bench --bench s3-api --no-run # Build only (~93 seconds)
108+
cargo bench --bench s3-api # Run benchmarks (requires MinIO server)
109+
```
110+
- Results stored in `target/criterion/`
111+
- See `benches/README.md` for details
112+
113+
### Examples
114+
```bash
115+
cargo run --example file_uploader
116+
cargo run --example file_downloader
117+
cargo run --example object_prompt
118+
```
119+
- Examples require network access to MinIO (defaults to play.min.io)
120+
- Will fail if network is unavailable
121+
- Located in `examples/` directory (10 examples)
122+
123+
## Project Architecture
124+
125+
### Directory Structure
126+
```
127+
minio-rs/
128+
├── src/ # Main library source
129+
│ ├── lib.rs # Root library file, exports s3 module
130+
│ └── s3/ # S3 API implementation
131+
│ ├── client.rs # MinioClient implementation (~27K lines)
132+
│ ├── builders.rs # Request builder exports
133+
│ ├── builders/ # Individual request builders (40+ files)
134+
│ ├── response.rs # Response type exports
135+
│ ├── response/ # Response types (40+ files)
136+
│ ├── types.rs # Core types (S3Api trait, etc.)
137+
│ ├── error.rs # Error types
138+
│ ├── utils.rs # Utility functions
139+
│ ├── signer.rs # AWS signature v4
140+
│ ├── creds.rs # Credentials providers
141+
│ ├── http.rs # HTTP utilities
142+
│ └── ... # Other modules
143+
├── tests/ # Integration tests (30+ test files)
144+
│ ├── start-server.sh # MinIO server setup script
145+
│ ├── public.crt # Test SSL certificate
146+
│ ├── private.key # Test SSL key
147+
│ └── test_*.rs # Individual test files
148+
├── examples/ # Usage examples (10 files)
149+
│ ├── common.rs # Shared example utilities
150+
│ └── *.rs # Example programs
151+
├── benches/ # Benchmarks
152+
│ ├── s3/ # S3 API benchmarks
153+
│ └── README.md # Benchmark documentation
154+
├── common/ # Test utilities workspace member
155+
│ ├── src/
156+
│ │ ├── test_context.rs # Test environment setup
157+
│ │ └── ...
158+
│ └── Cargo.toml
159+
├── macros/ # Procedural macros workspace member
160+
│ └── src/test_attr.rs # Test attribute macro
161+
├── Cargo.toml # Main project manifest
162+
├── .rustfmt.toml # Formatting configuration
163+
└── rust-toolchain.toml # Rust version specification
164+
```
165+
166+
### Key Files and Locations
167+
168+
**Configuration Files:**
169+
- `Cargo.toml` - Main project dependencies and metadata (edition 2024)
170+
- `.rustfmt.toml` - Formatting rules (max_width=100, edition=2024)
171+
- `rust-toolchain.toml` - Specifies Rust 1.88.0
172+
- `.gitignore` - Excludes `/target`, `Cargo.lock`, `*.env`, `.idea`, `.cargo`
173+
174+
**CI/CD Workflows** (`.github/workflows/`):
175+
- `rust.yml` - Main CI (format check, clippy, tests with multi/current-thread, build)
176+
- `lint.yml` - Format check for main branch
177+
- `rust-clippy.yml` - Security-focused clippy analysis with SARIF output
178+
179+
### Design Patterns
180+
181+
1. **Builder Pattern**: Each S3 API operation has a builder (e.g., `BucketExists`, `PutObject`)
182+
2. **Traits**:
183+
- `S3Api` - Provides async `send()` method on all builders
184+
- `ToS3Request` - Converts builders to HTTP requests
185+
- `FromS3Response` - Deserializes HTTP responses
186+
3. **Async/Await**: All operations are async, using tokio runtime
187+
4. **Strong Typing**: Responses are strongly typed structures
188+
189+
### Common Code Patterns
190+
191+
**Creating a client:**
192+
```rust
193+
use minio::s3::{MinioClient, MinioClientBuilder};
194+
use minio::s3::creds::StaticProvider;
195+
use minio::s3::http::BaseUrl;
196+
197+
let base_url = "play.min.io".parse::<BaseUrl>()?;
198+
let provider = StaticProvider::new("access_key", "secret_key", None);
199+
let client = MinioClientBuilder::new(base_url)
200+
.provider(Some(provider))
201+
.build()?;
202+
```
203+
204+
**Making API calls:**
205+
```rust
206+
use minio::s3::types::S3Api;
207+
208+
let response = client
209+
.bucket_exists("my-bucket")
210+
.build()
211+
.send()
212+
.await?;
213+
```
214+
215+
**Test context (integration tests):**
216+
```rust
217+
use minio_common::test_context::TestContext;
218+
219+
#[minio_macros::test]
220+
async fn my_test(ctx: TestContext, bucket_name: String) {
221+
// Test automatically creates bucket via bucket_name
222+
// Client available at ctx.client
223+
}
224+
```
225+
226+
## CI/CD Pipeline Details
227+
228+
### GitHub Actions Checks (all must pass)
229+
230+
1. **check-format** job:
231+
- Runs: `cargo fmt --all -- --check`
232+
- Fast: ~1 second
233+
234+
2. **clippy** job:
235+
- Runs: `cargo clippy --all-targets --all-features --workspace -- -D warnings`
236+
- Duration: ~45 seconds
237+
238+
3. **test-multi-thread** job:
239+
- Sets up MinIO server via `./tests/start-server.sh`
240+
- Exports environment variables
241+
- Runs: `MINIO_TEST_TOKIO_RUNTIME_FLAVOR="multi_thread" cargo test -- --nocapture`
242+
243+
4. **test-current-thread** job:
244+
- Same as test-multi-thread but with `current_thread` flavor
245+
- Tests async behavior in single-threaded context
246+
247+
5. **build** job:
248+
- Runs: `cargo build --bins --examples --tests --benches --verbose`
249+
- Timeout: 5 minutes
250+
- Duration: ~90 seconds
251+
252+
6. **label-checker** job:
253+
- **REQUIRED**: All PRs must have at least one label
254+
- Valid labels: `highlight`, `breaking-change`, `security-fix`, `enhancement`, `bug`, `cleanup-rewrite`, `regression-fix`, `codex`
255+
- PRs without a label will fail the check
256+
- The check runs on PR open, synchronize, label, and unlabel events
257+
258+
### Branches
259+
- Main development branch: `master`
260+
- PRs target: `master`
261+
- Some workflows also watch: `main` (legacy)
262+
263+
## Common Issues and Workarounds
264+
265+
### Integration Test Failures
266+
**Symptom**: Tests fail with "NotPresent" error or connection errors
267+
**Cause**: Missing MinIO server or environment variables
268+
**Solution**: Follow the integration test setup in section "Essential Commands" above
269+
270+
### Build Failures with --no-default-features
271+
**Symptom**: Compilation errors about missing crypto functions
272+
**Cause**: No crypto backend enabled
273+
**Solution**: Always enable at least one crypto backend: `--features "ring,default-tls"` or use `default-crypto`
274+
275+
### Documentation Warnings
276+
**Symptom**: 13 warnings about unresolved links when running `cargo doc`
277+
**Cause**: Known issue with documentation links
278+
**Solution**: These warnings are acceptable and don't need to be fixed for PRs
279+
280+
### Test Environment Variables
281+
When running tests locally without CI=true, tests use play.min.io by default. To use local MinIO:
282+
```bash
283+
export CI=true
284+
export SERVER_ENDPOINT=localhost:9000
285+
export ACCESS_KEY=minioadmin
286+
export SECRET_KEY=minioadmin
287+
export ENABLE_HTTPS=1
288+
export MINIO_SSL_CERT_FILE=./tests/public.crt
289+
```
290+
291+
## Coding Guidelines
292+
293+
### Format and Style
294+
- **Always** run `cargo fmt --all` before committing
295+
- Max line width: 100 characters (enforced by .rustfmt.toml)
296+
- Use `reorder_imports = true` (automatic)
297+
- Edition 2024 formatting rules apply
298+
299+
### Linting
300+
- **Zero warnings policy**: `cargo clippy` must pass with -D warnings
301+
- Allow directives in lib.rs: `#![allow(clippy::result_large_err)]`, `#![allow(clippy::too_many_arguments)]`
302+
- These are intentional and should not be removed
303+
304+
### Testing
305+
- Add unit tests in the same file as the code (see `src/s3/utils.rs`, `src/s3/builders/put_object.rs`)
306+
- Add integration tests in `tests/` directory with `#[minio_macros::test]` attribute
307+
- Use `TestContext` for integration tests - it handles server connection and cleanup
308+
- Test both multi-threaded and current-thread async runtimes
309+
310+
### Dependencies
311+
- Prefer workspace dependencies defined in `[workspace.dependencies]` section
312+
- Main async runtime: `tokio` (dev-dependency, version 1.48+)
313+
- HTTP client: `reqwest` (version 0.12, workspace dependency)
314+
- See `Cargo.toml` for full dependency list
315+
316+
## Quick Reference
317+
318+
**Fastest validation sequence:**
319+
```bash
320+
cargo fmt --all && cargo clippy --all-targets --all-features --workspace -- -D warnings && cargo test --lib
321+
```
322+
323+
**Full local validation (without integration tests):**
324+
```bash
325+
cargo fmt --all --check && \
326+
cargo clippy --all-targets --all-features --workspace -- -D warnings && \
327+
cargo build --bins --examples --tests --benches && \
328+
cargo test --lib && \
329+
cargo doc --no-deps
330+
```
331+
332+
**Workspace structure:**
333+
- Main crate: `minio` (library in `src/`)
334+
- Helper crate: `minio-common` (test utilities in `common/`)
335+
- Macro crate: `minio-macros` (proc macros in `macros/`)
336+
337+
---
338+
339+
**Trust these instructions**: This information has been validated against the actual repository. Only search for additional information if these instructions are incomplete or you encounter errors not documented here.

0 commit comments

Comments
 (0)