feat: add Copilot best practices with instructions and setup configuration (#307)

# Copilot Instructions for s3s

<!-- This file is generated by Copilot -->

## Project Overview

s3s is an experimental Rust project that provides an ergonomic adapter for building S3-compatible services. It implements the Amazon S3 REST API as a generic hyper service, allowing S3-compatible services to focus on the S3 API itself without worrying about the HTTP layer.

## Key Architecture

- **s3s**: Core crate implementing S3 REST API as a hyper service

- **s3s-aws**: Provides integration with aws-sdk-s3 and useful types

- **s3s-fs**: Sample implementation using file system (for testing and debugging)

- **s3s-model**: Generated data types from AWS Smithy models

- **s3s-policy**: S3 policy handling

- **s3s-test**: Testing utilities

- **s3s-proxy**: Proxy implementation for E2E testing

- **s3s-e2e**: End-to-end testing framework

The project converts HTTP requests to operation inputs, calls user-defined services, and converts outputs back to HTTP responses.

## Development Workflow

### Required Tools

- **Rust**: ^1.85.0 (MSRV - minimum supported version)

- **just**: ^1.36.0 (task runner, like make)

- **uv**: ^0.5.0 (Python package manager)

- **Docker**: For E2E testing

### Main Commands

Use `just` for all development tasks:

- `just dev` - Run complete development cycle (fetch, fmt, codegen, lint, test)

- `just fetch` - Fetch dependencies (uv sync + cargo fetch)

- `just fmt` - Format code (ruff format + cargo fmt)

- `just lint` - Lint code (ruff check + cargo clippy)

- `just test` - Run tests (cargo test)

- `just codegen` - Run code generation from Smithy models

- `just doc` - Generate and open documentation

### Code Generation

The project uses code generation from AWS Smithy models:

- `just crawl` - Update data from AWS

- `just codegen` - Generate Rust code from models

**Important**: Always run `just codegen` after making changes to generation code.

### Project Structure

```

├── crates/          # Main Rust crates

│   ├── s3s/         # Core S3 service implementation

│   ├── s3s-aws/     # AWS integration

│   ├── s3s-fs/      # File system implementation

│   └── ...

├── codegen/         # Code generation utilities

├── data/            # Smithy model data and crawling scripts

├── scripts/         # Development and testing scripts

└── docs/            # Documentation

```

### Testing Strategy

1. **Unit tests**: `cargo test` - Test individual components

2. **Integration tests**: Test crate interactions

3. **E2E tests**: Full system testing with Docker

   - `s3s-proxy` + MinIO integration

   - `s3s-fs` standalone testing

   - MinT test suite compatibility

### Code Style & Linting

- **Rust**: Uses clippy with strict lints (all, pedantic, cargo = deny)

- **Python**: Uses ruff for formatting and linting

- **Safety**: `unsafe` code is forbidden

- **Commit Messages**: Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification

### Important Files

- `justfile` - Task definitions and development commands

- `Cargo.toml` - Workspace configuration and lint settings

- `pyproject.toml` - Python project configuration

- `CONTRIBUTING.md` - Detailed development guide

- `.github/actions/setup/action.yml` - CI setup steps

### Working with the Codebase

#### When modifying S3 operations:

1. Check if code generation is needed (`just codegen`)

2. Update tests in relevant crates

3. Run full test suite (`just test`)

4. Consider E2E impact

#### When adding new features:

1. Follow the existing crate structure

2. Add appropriate unit and integration tests

3. Update documentation if public APIs change

4. Run `just dev` to ensure quality

#### When fixing bugs:

1. Add a test that reproduces the issue

2. Fix the issue with minimal changes

3. Ensure the test passes

4. Run full test suite to prevent regressions

### CI/CD

- GitHub Actions run on push/PR to main

- Tests run on multiple Rust versions (MSRV, stable, nightly)

- Cross-platform testing (Linux, Windows, macOS)

- E2E tests with MinIO and custom implementations

### Common Pitfalls

- Don't forget to run `just codegen` after modifying generation code

- Always format code before committing (`just fmt`)

- Test changes against both unit tests and E2E tests

- Be aware that this is a security-sensitive project (HTTP body limits, rate limiting needed)

### Security Considerations

The S3Service and adapters have no built-in security protection. When working on this project:

- Consider HTTP body length limits

- Think about rate limiting and back pressure

- Remember that services may be exposed to the Internet

- Test security implications of any changes

### Getting Help

- Check `CONTRIBUTING.md` for detailed development setup

- Review existing tests for implementation patterns

- Use `just doc` to explore API documentation

- Look at `s3s-fs` as a reference implementation

# Pre-installation steps for Copilot agents working on s3s

# These steps mirror the existing CI setup to ensure agents have all required dependencies

# This file is generated by Copilot

- name: Install just

  uses: taiki-e/install-action@just

- name: Setup uv

  uses: astral-sh/setup-uv@v3

  with:

    enable-cache: true

- name: Setup Rust toolchain

  uses: dtolnay/rust-toolchain@stable

  with:

    components: rustfmt, clippy

- name: Setup Rust cache

  uses: Swatinem/rust-cache@v2

- name: Fetch dependencies

  run: |

    uv sync

    cargo fetch

  shell: bash

- name: Verify setup

  run: |

    echo "Rust version: $(rustc --version)"

    echo "Cargo version: $(cargo --version)"

    echo "Just version: $(just --version)"

    echo "UV version: $(uv --version)"

    echo "Setup complete!"

  shell: bash