{"owner":"apache","repo":"opendal","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nGuidance for AI coding agents working in this repository.\n\n## General Rules\n\n- Use English in repository files: code, comments, commit messages, PR titles, PR bodies, and technical docs.\n- Add comments only when they explain non-obvious intent or constraints.\n- Add tests when they verify real behavior or guard a regression; do not add placeholder tests.\n- Do not change public APIs or behavior tests unless the task explicitly requires it.\n\n## Documentation Style\n\n- Prefer active voice. Name the type or component that performs an action, for example, “`RetryLayer` retries failed operations.”\n- Use direct, present-tense sentences.\n- Lead with what a public type or method does, then explain important constraints, defaults, and behavior.\n- Describe API semantics precisely. Verify option types, capability requirements, error behavior, and overwrite or versioning semantics against the implementation.\n- Keep terminology consistent with the codebase, especially `service`, `layer`, `operator`, `storage` and `operation`.\n- Use parallel structure in lists and punctuate complete sentences consistently.\n\n## Rust Workspace Commands\n\nThe Rust workspace for OpenDAL core lives under `core/`. There is no root `Cargo.toml`; run core cargo commands from `core/`.\n\n```bash\ncd core\n\n# Check and build\ncargo check\ncargo build --locked\ncargo build --all-features --locked\n\n# Lint, matching Core CI\ncargo clippy --workspace --all-targets --all-features -- -D warnings\n\n# Lint a focused service/layer feature set\ncargo clippy --all-targets --features=services-s3 -- -D warnings\n\n# Unit tests, matching Core CI\ncargo nextest run --workspace --no-fail-fast --all-features\n\n# Doc tests and docs\ncargo test --workspace --doc --all-features\ncargo doc --lib --no-deps --all-features\n\n# Behavior tests\nOPENDAL_TEST=s3 cargo test behavior --features tests,services-s3\n\n# Format core workspace\ncargo fmt --all\ncargo fmt --all -- --check\n```\n\nRepository-wide format checks run from the repository root:\n\n```bash\n./scripts/workspace.py cargo fmt -- --check\ntaplo format --check\n```\n\nCode generation and release helpers also run from the repository root:\n\n```bash\njust generate python\njust generate java\njust update-version\njust release\n```\n\n## Current Architecture\n\nOpenDAL's Rust core has been split into a facade crate plus smaller core, service, and layer crates.\n\n- `core/Cargo.toml`: Rust workspace root and `opendal` facade package.\n- `core/src/lib.rs`: facade crate that re-exports `opendal-core`, wires optional service/layer crates, and registers enabled services for `Operator::from_uri` / `Operator::via_iter`.\n- `core/core/`: `opendal-core`, containing public core types, raw traits, shared layers, HTTP utilities, docs, RFCs, and the always-available memory service.\n- `core/services/<service>/`: standalone service crates named `opendal-service-*`.\n- `core/layers/<layer>/`: standalone layer crates named `opendal-layer-*`.\n- `core/testkit/`: behavior-test support.\n- `core/tests/behavior/`: core behavior test entrypoint.\n- `integrations/`: ecosystem integrations such as `object_store`, `parquet`, `dav-server`, `unftp-sbe`, and Spring.\n- `bindings/`: language bindings; each binding has its own build/test conventions.\n- `website/`: documentation website.\n- `dev/`: repository maintenance, code generation, and release tooling used by `just`.\n\nImportant consequences of the split:\n\n- Service and layer code no longer lives under `core/src/services` or `core/src/layers`.\n- Public API changes usually touch `core/core/src/...` and the facade exports in `core/src/lib.rs`.\n- Optional user-facing features are declared in `core/Cargo.toml` as `services-*` and `layers-*`, and usually map to optional `opendal-service-*` / `opendal-layer-*` dependencies.\n- The memory service is in `core/core/src/services/memory`; `services-memory` is a deprecated compatibility feature because memory is always enabled.\n\n## Service Implementation Pattern\n\nMost services follow this shape under `core/services/<name>/`:\n\n- `src/lib.rs`: crate docs, module declarations, public builder/config exports, and service registration function.\n- `src/backend.rs`: builder and `opendal_core::raw::Access` implementation.\n- `src/config.rs`: serializable config and builder conversion.\n- `src/core.rs`: shared service client, request construction, and service-specific helpers.\n- `src/error.rs`: service-specific error parsing.\n- `src/reader.rs`, `src/writer.rs`, `src/lister.rs`, `src/deleter.rs`, `src/copier.rs`: operation implementations when the service needs them.\n- `src/docs.md`: service docs included into rustdoc.\n\nWhen adding or changing a service:\n\n1. Put implementation in `core/services/<service>/`.\n2. Implement `Builder` and `Access` using `opendal_core`.\n3. Add or update the facade feature and optional dependency in `core/Cargo.toml`.\n4. Register the service in `core/src/lib.rs` when it should support URI/iterator construction.\n5. Add or update behavior-test setup under `.github/services/<service>/` when real backend testing is needed.\n6. Run focused clippy/tests first, then broaden validation based on the blast radius.\n\n## Layer Implementation Pattern\n\nReusable layers live under `core/layers/<layer>/` as `opendal-layer-*` crates. Core layers that are required by `opendal-core` itself live under `core/core/src/layers/`.\n\nWhen adding or changing a public optional layer:\n\n1. Put reusable optional code in `core/layers/<layer>/`.\n2. Depend on `opendal-core` and implement `Layer` / `LayeredAccess` against `opendal_core::raw`.\n3. Add or update the corresponding `layers-*` feature and optional dependency in `core/Cargo.toml`.\n4. Re-export it from the facade when users should access it through `opendal::layers`.\n\n## Testing Expectations\n\n- Use `cargo fmt --all -- --check` for Rust formatting inside `core/`; use `./scripts/workspace.py cargo fmt -- --check` for the repository-wide format check.\n- For core changes, `cargo clippy --workspace --all-targets --all-features -- -D warnings` is the CI-level lint gate.\n- For behavior changes, run the narrow behavior test, for example `OPENDAL_TEST=s3 cargo test behavior --features tests,services-s3`.\n- Behavior tests require backend credentials or fixture setup. Use `.env.example`, `fixtures/`, and `.github/services/<service>/` as the source of truth for service-specific setup.\n- Integration crates under `integrations/` have their own CI workflows and should be validated in their own directories when touched.\n- Binding changes should follow the binding's local README/build files and the matching `.github/workflows/ci_bindings_*.yml`.\n\n## Pull Requests\n\n- Before opening a PR, search for similar open PRs, issues, and in-progress branches that already address the same problem. Prefer contributing to or coordinating with existing work over opening a duplicate.\n- Always use `.github/pull_request_template.md` when creating a PR.\n- Keep PR titles and descriptions factual and concise.\n- Do not add AI-tool branding or co-author trailers.\n- If public APIs or user-facing behavior change, update docs and call out the user-facing impact in the PR template.\n\n## Important Notes\n\n- Minimum Rust version is 1.91, configured in `core/Cargo.toml` and checked by CI.\n- Use `opendal_core::raw::Access`, `Layer`, and `LayeredAccess` for internal implementations.\n- Use `opendal_core::raw::oio::{ReadStream, Write, List, Delete}` for operation bodies.\n- Use `Operator` and `blocking::Operator` as the public API entry points.\n- Prefer existing helpers in `opendal-core` before adding service-local utilities.\n\n## Security\n\nSecurity model: [SECURITY.md](./SECURITY.md)\n\nAgents that scan this repository should consult `SECURITY.md` and the threat\nmodel it links (`SECURITY-THREAT-MODEL.md`) for the project's in-scope /\nout-of-scope declarations, adversary model, and known non-findings before\nreporting issues.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nGuidance for AI coding agents working in this repository.\n\n## General Rules\n\n- Use English in repository files: code, comments, commit messages, PR titles, PR bodies, and technical docs.\n- Add comments only when they explain non-obvious intent or constraints.\n- Add tests when they verify real behavior or guard a regression; do not add placeholder tests.\n- Do not change public APIs or behavior tests unless the task explicitly requires it.\n\n## Documentation Style\n\n- Prefer active voice. Name the type or component that performs an action, for example, “`RetryLayer` retries failed operations.”\n- Use direct, present-tense sentences.\n- Lead with what a public type or method does, then explain important constraints, defaults, and behavior.\n- Describe API semantics precisely. Verify option types, capability requirements, error behavior, and overwrite or versioning semantics against the implementation.\n- Keep terminology consistent with the codebase, especially `service`, `layer`, `operator`, `storage` and `operation`.\n- Use parallel structure in lists and punctuate complete sentences consistently.\n\n## Rust Workspace Commands\n\nThe Rust workspace for OpenDAL core lives under `core/`. There is no root `Cargo.toml`; run core cargo commands from `core/`.\n\n```bash\ncd core\n\n# Check and build\ncargo check\ncargo build --locked\ncargo build --all-features --locked\n\n# Lint, matching Core CI\ncargo clippy --workspace --all-targets --all-features -- -D warnings\n\n# Lint a focused service/layer feature set\ncargo clippy --all-targets --features=services-s3 -- -D warnings\n\n# Unit tests, matching Core CI\ncargo nextest run --workspace --no-fail-fast --all-features\n\n# Doc tests and docs\ncargo test --workspace --doc --all-features\ncargo doc --lib --no-deps --all-features\n\n# Behavior tests\nOPENDAL_TEST=s3 cargo test behavior --features tests,services-s3\n\n# Format core workspace\ncargo fmt --all\ncargo fmt --all -- --check\n```\n\nRepository-wide format checks run from the repository root:\n\n```bash\n./scripts/workspace.py cargo fmt -- --check\ntaplo format --check\n```\n\nCode generation and release helpers also run from the repository root:\n\n```bash\njust generate python\njust generate java\njust update-version\njust release\n```\n\n## Current Architecture\n\nOpenDAL's Rust core has been split into a facade crate plus smaller core, service, and layer crates.\n\n- `core/Cargo.toml`: Rust workspace root and `opendal` facade package.\n- `core/src/lib.rs`: facade crate that re-exports `opendal-core`, wires optional service/layer crates, and registers enabled services for `Operator::from_uri` / `Operator::via_iter`.\n- `core/core/`: `opendal-core`, containing public core types, raw traits, shared layers, HTTP utilities, docs, RFCs, and the always-available memory service.\n- `core/services/<service>/`: standalone service crates named `opendal-service-*`.\n- `core/layers/<layer>/`: standalone layer crates named `opendal-layer-*`.\n- `core/testkit/`: behavior-test support.\n- `core/tests/behavior/`: core behavior test entrypoint.\n- `integrations/`: ecosystem integrations such as `object_store`, `parquet`, `dav-server`, `unftp-sbe`, and Spring.\n- `bindings/`: language bindings; each binding has its own build/test conventions.\n- `website/`: documentation website.\n- `dev/`: repository maintenance, code generation, and release tooling used by `just`.\n\nImportant consequences of the split:\n\n- Service and layer code no longer lives under `core/src/services` or `core/src/layers`.\n- Public API changes usually touch `core/core/src/...` and the facade exports in `core/src/lib.rs`.\n- Optional user-facing features are declared in `core/Cargo.toml` as `services-*` and `layers-*`, and usually map to optional `opendal-service-*` / `opendal-layer-*` dependencies.\n- The memory service is in `core/core/src/services/memory`; `services-memory` is a deprecated compatibility feature because memory is always enabled.\n\n## Service Implementation Pattern\n\nMost services follow this shape under `core/services/<name>/`:\n\n- `src/lib.rs`: crate docs, module declarations, public builder/config exports, and service registration function.\n- `src/backend.rs`: builder and `opendal_core::raw::Access` implementation.\n- `src/config.rs`: serializable config and builder conversion.\n- `src/core.rs`: shared service client, request construction, and service-specific helpers.\n- `src/error.rs`: service-specific error parsing.\n- `src/reader.rs`, `src/writer.rs`, `src/lister.rs`, `src/deleter.rs`, `src/copier.rs`: operation implementations when the service needs them.\n- `src/docs.md`: service docs included into rustdoc.\n\nWhen adding or changing a service:\n\n1. Put implementation in `core/services/<service>/`.\n2. Implement `Builder` and `Access` using `opendal_core`.\n3. Add or update the facade feature and optional dependency in `core/Cargo.toml`.\n4. Register the service in `core/src/lib.rs` when it should support URI/iterator construction.\n5. Add or update behavior-test setup under `.github/services/<service>/` when real backend testing is needed.\n6. Run focused clippy/tests first, then broaden validation based on the blast radius.\n\n## Layer Implementation Pattern\n\nReusable layers live under `core/layers/<layer>/` as `opendal-layer-*` crates. Core layers that are required by `opendal-core` itself live under `core/core/src/layers/`.\n\nWhen adding or changing a public optional layer:\n\n1. Put reusable optional code in `core/layers/<layer>/`.\n2. Depend on `opendal-core` and implement `Layer` / `LayeredAccess` against `opendal_core::raw`.\n3. Add or update the corresponding `layers-*` feature and optional dependency in `core/Cargo.toml`.\n4. Re-export it from the facade when users should access it through `opendal::layers`.\n\n## Testing Expectations\n\n- Use `cargo fmt --all -- --check` for Rust formatting inside `core/`; use `./scripts/workspace.py cargo fmt -- --check` for the repository-wide format check.\n- For core changes, `cargo clippy --workspace --all-targets --all-features -- -D warnings` is the CI-level lint gate.\n- For behavior changes, run the narrow behavior test, for example `OPENDAL_TEST=s3 cargo test behavior --features tests,services-s3`.\n- Behavior tests require backend credentials or fixture setup. Use `.env.example`, `fixtures/`, and `.github/services/<service>/` as the source of truth for service-specific setup.\n- Integration crates under `integrations/` have their own CI workflows and should be validated in their own directories when touched.\n- Binding changes should follow the binding's local README/build files and the matching `.github/workflows/ci_bindings_*.yml`.\n\n## Pull Requests\n\n- Before opening a PR, search for similar open PRs, issues, and in-progress branches that already address the same problem. Prefer contributing to or coordinating with existing work over opening a duplicate.\n- Always use `.github/pull_request_template.md` when creating a PR.\n- Keep PR titles and descriptions factual and concise.\n- Do not add AI-tool branding or co-author trailers.\n- If public APIs or user-facing behavior change, update docs and call out the user-facing impact in the PR template.\n\n## Important Notes\n\n- Minimum Rust version is 1.91, configured in `core/Cargo.toml` and checked by CI.\n- Use `opendal_core::raw::Access`, `Layer`, and `LayeredAccess` for internal implementations.\n- Use `opendal_core::raw::oio::{ReadStream, Write, List, Delete}` for operation bodies.\n- Use `Operator` and `blocking::Operator` as the public API entry points.\n- Prefer existing helpers in `opendal-core` before adding service-local utilities.\n\n## Security\n\nSecurity model: [SECURITY.md](./SECURITY.md)\n\nAgents that scan this repository should consult `SECURITY.md` and the threat\nmodel it links (`SECURITY-THREAT-MODEL.md`) for the project's in-scope /\nout-of-scope declarations, adversary model, and known non-findings before\nreporting issues.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nGuidance for AI coding agents working in this repository.\n\n## General Rules\n\n- Use English in repository files: code, comments, commit messages, PR titles, PR bodies, and technical docs.\n- Add comments only when they explain non-obvious intent or constraints.\n- Add tests when they verify real behavior or guard a regression; do not add placeholder tests.\n- Do not change public APIs or behavior tests unless the task explicitly requires it.\n\n## Documentation Style\n\n- Prefer active voice. Name the type or component that performs an action, for example, “`RetryLayer` retries failed operations.”\n- Use direct, present-tense sentences.\n- Lead with what a public type or method does, then explain important constraints, defaults, and behavior.\n- Describe API semantics precisely. Verify option types, capability requirements, error behavior, and overwrite or versioning semantics against the implementation.\n- Keep terminology consistent with the codebase, especially `service`, `layer`, `operator`, `storage` and `operation`.\n- Use parallel structure in lists and punctuate complete sentences consistently.\n\n## Rust Workspace Commands\n\nThe Rust workspace for OpenDAL core lives under `core/`. There is no root `Cargo.toml`; run core cargo commands from `core/`.\n\n```bash\ncd core\n\n# Check and build\ncargo check\ncargo build --locked\ncargo build --all-features --locked\n\n# Lint, matching Core CI\ncargo clippy --workspace --all-targets --all-features -- -D warnings\n\n# Lint a focused service/layer feature set\ncargo clippy --all-targets --features=services-s3 -- -D warnings\n\n# Unit tests, matching Core CI\ncargo nextest run --workspace --no-fail-fast --all-features\n\n# Doc tests and docs\ncargo test --workspace --doc --all-features\ncargo doc --lib --no-deps --all-features\n\n# Behavior tests\nOPENDAL_TEST=s3 cargo test behavior --features tests,services-s3\n\n# Format core workspace\ncargo fmt --all\ncargo fmt --all -- --check\n```\n\nRepository-wide format checks run from the repository root:\n\n```bash\n./scripts/workspace.py cargo fmt -- --check\ntaplo format --check\n```\n\nCode generation and release helpers also run from the repository root:\n\n```bash\njust generate python\njust generate java\njust update-version\njust release\n```\n\n## Current Architecture\n\nOpenDAL's Rust core has been split into a facade crate plus smaller core, service, and layer crates.\n\n- `core/Cargo.toml`: Rust workspace root and `opendal` facade package.\n- `core/src/lib.rs`: facade crate that re-exports `opendal-core`, wires optional service/layer crates, and registers enabled services for `Operator::from_uri` / `Operator::via_iter`.\n- `core/core/`: `opendal-core`, containing public core types, raw traits, shared layers, HTTP utilities, docs, RFCs, and the always-available memory service.\n- `core/services/<service>/`: standalone service crates named `opendal-service-*`.\n- `core/layers/<layer>/`: standalone layer crates named `opendal-layer-*`.\n- `core/testkit/`: behavior-test support.\n- `core/tests/behavior/`: core behavior test entrypoint.\n- `integrations/`: ecosystem integrations such as `object_store`, `parquet`, `dav-server`, `unftp-sbe`, and Spring.\n- `bindings/`: language bindings; each binding has its own build/test conventions.\n- `website/`: documentation website.\n- `dev/`: repository maintenance, code generation, and release tooling used by `just`.\n\nImportant consequences of the split:\n\n- Service and layer code no longer lives under `core/src/services` or `core/src/layers`.\n- Public API changes usually touch `core/core/src/...` and the facade exports in `core/src/lib.rs`.\n- Optional user-facing features are declared in `core/Cargo.toml` as `services-*` and `layers-*`, and usually map to optional `opendal-service-*` / `opendal-layer-*` dependencies.\n- The memory service is in `core/core/src/services/memory`; `services-memory` is a deprecated compatibility feature because memory is always enabled.\n\n## Service Implementation Pattern\n\nMost services follow this shape under `core/services/<name>/`:\n\n- `src/lib.rs`: crate docs, module declarations, public builder/config exports, and service registration function.\n- `src/backend.rs`: builder and `opendal_core::raw::Access` implementation.\n- `src/config.rs`: serializable config and builder conversion.\n- `src/core.rs`: shared service client, request construction, and service-specific helpers.\n- `src/error.rs`: service-specific error parsing.\n- `src/reader.rs`, `src/writer.rs`, `src/lister.rs`, `src/deleter.rs`, `src/copier.rs`: operation implementations when the service needs them.\n- `src/docs.md`: service docs included into rustdoc.\n\nWhen adding or changing a service:\n\n1. Put implementation in `core/services/<service>/`.\n2. Implement `Builder` and `Access` using `opendal_core`.\n3. Add or update the facade feature and optional dependency in `core/Cargo.toml`.\n4. Register the service in `core/src/lib.rs` when it should support URI/iterator construction.\n5. Add or update behavior-test setup under `.github/services/<service>/` when real backend testing is needed.\n6. Run focused clippy/tests first, then broaden validation based on the blast radius.\n\n## Layer Implementation Pattern\n\nReusable layers live under `core/layers/<layer>/` as `opendal-layer-*` crates. Core layers that are required by `opendal-core` itself live under `core/core/src/layers/`.\n\nWhen adding or changing a public optional layer:\n\n1. Put reusable optional code in `core/layers/<layer>/`.\n2. Depend on `opendal-core` and implement `Layer` / `LayeredAccess` against `opendal_core::raw`.\n3. Add or update the corresponding `layers-*` feature and optional dependency in `core/Cargo.toml`.\n4. Re-export it from the facade when users should access it through `opendal::layers`.\n\n## Testing Expectations\n\n- Use `cargo fmt --all -- --check` for Rust formatting inside `core/`; use `./scripts/workspace.py cargo fmt -- --check` for the repository-wide format check.\n- For core changes, `cargo clippy --workspace --all-targets --all-features -- -D warnings` is the CI-level lint gate.\n- For behavior changes, run the narrow behavior test, for example `OPENDAL_TEST=s3 cargo test behavior --features tests,services-s3`.\n- Behavior tests require backend credentials or fixture setup. Use `.env.example`, `fixtures/`, and `.github/services/<service>/` as the source of truth for service-specific setup.\n- Integration crates under `integrations/` have their own CI workflows and should be validated in their own directories when touched.\n- Binding changes should follow the binding's local README/build files and the matching `.github/workflows/ci_bindings_*.yml`.\n\n## Pull Requests\n\n- Before opening a PR, search for similar open PRs, issues, and in-progress branches that already address the same problem. Prefer contributing to or coordinating with existing work over opening a duplicate.\n- Always use `.github/pull_request_template.md` when creating a PR.\n- Keep PR titles and descriptions factual and concise.\n- Do not add AI-tool branding or co-author trailers.\n- If public APIs or user-facing behavior change, update docs and call out the user-facing impact in the PR template.\n\n## Important Notes\n\n- Minimum Rust version is 1.91, configured in `core/Cargo.toml` and checked by CI.\n- Use `opendal_core::raw::Access`, `Layer`, and `LayeredAccess` for internal implementations.\n- Use `opendal_core::raw::oio::{ReadStream, Write, List, Delete}` for operation bodies.\n- Use `Operator` and `blocking::Operator` as the public API entry points.\n- Prefer existing helpers in `opendal-core` before adding service-local utilities.\n\n## Security\n\nSecurity model: [SECURITY.md](./SECURITY.md)\n\nAgents that scan this repository should consult `SECURITY.md` and the threat\nmodel it links (`SECURITY-THREAT-MODEL.md`) for the project's in-scope /\nout-of-scope declarations, adversary model, and known non-findings before\nreporting issues.\n","category":"root","tokens":1967}]}