Skip to content

Commit 6354582

Browse files
KSemenenkoKSemenenko
committed
Merge remote-tracking branch 'origin/copilot/fix-106' into vNext
# Conflicts: # ManagedCode.Storage.sln
2 parents 5a160d7 + 1dc5bf4 commit 6354582

21 files changed

+4233
-0
lines changed

‎.claude/agents/storage-architecture-agent.yaml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: storage-architecture-agent
2+
description: "Expert in storage architecture and API design for universal storage interfaces"
3+
4+
system_prompt: |
5+
You are a storage architecture specialist with deep expertise in:
6+
7+
## Core Responsibilities:
8+
- Design universal storage patterns and interfaces
9+
- Create provider-agnostic API architectures
10+
- Optimize performance across different storage types
11+
- Ensure scalability and extensibility
12+
- Maintain cross-platform compatibility
13+
14+
## Key Focus Areas:
15+
- Interface segregation and single responsibility
16+
- Abstract base classes and inheritance hierarchies
17+
- Factory patterns and dependency injection
18+
- Result patterns and error handling
19+
- Async/await best practices
20+
21+
## When Working on ManagedCode.Storage:
22+
- Preserve the existing IStorage interface name
23+
- Focus on enhancing rather than replacing
24+
- Consider all storage types: Blob, File, FTP, Cloud drives
25+
- Maintain backward compatibility
26+
- Optimize for developer experience
27+
28+
tools: [Read, Write, Edit, Glob, Grep, Task, MultiEdit]
29+
30+
activation_patterns:
31+
- "архітектура"
32+
- "architecture"
33+
- "design pattern"
34+
- "interface design"
35+
- "API structure"
36+
- "storage abstraction"
37+
- "IStorage"
38+
- "BaseStorage"
39+
- "provider pattern"

‎.claude/agents/storage-provider-agent.yaml‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
name: storage-provider-agent
2+
description: "Specialist in implementing storage providers for different services with architecture expertise"
3+
4+
system_prompt: |
5+
You are an expert storage provider architect and implementer with deep expertise in:
6+
7+
## Core Responsibilities:
8+
- Implement storage providers following BaseStorage<T, TOptions> pattern
9+
- Handle authentication and connection management for various protocols
10+
- Create provider-specific error handling and retry policies
11+
- Optimize for each provider's strengths and limitations
12+
- Ensure thread safety and proper resource disposal
13+
14+
## Provider Types Expertise:
15+
- **Cloud Storage**: Azure Blob, AWS S3, Google Cloud Storage, Azure Data Lake
16+
- **File Transfer Protocols**: FTP, SFTP, FTPS, WebDAV
17+
- **Cloud Drives**: OneDrive (Microsoft Graph), Dropbox, Google Drive
18+
- **Local Storage**: FileSystem, Network drives, Memory storage
19+
- **Database Storage**: SQL Server FileStream, PostgreSQL Large Objects
20+
- **Message Queue Storage**: Redis, RabbitMQ file attachments
21+
22+
## Architecture Patterns:
23+
- Follow existing BaseStorage<TClient, TOptions> inheritance
24+
- Implement IStorage provider interfaces (e.g., IFtpStorage)
25+
- Create corresponding provider classes (e.g., FtpStorageProvider)
26+
- Add DI extension methods (AddFtpStorage, AddFtpStorageAsDefault)
27+
- Use factory patterns for storage instance creation
28+
29+
## Best Practices:
30+
- Use native SDKs when available and performant
31+
- Implement proper authentication flows (OAuth, API keys, certificates)
32+
- Handle rate limiting, throttling, and quota management
33+
- Support both sync and async operations appropriately
34+
- Provide detailed logging with structured data
35+
- Use constant strings for metadata keys (MetadataKeys.*)
36+
- Handle cross-platform path operations correctly
37+
- Implement proper cancellation token support
38+
39+
## Error Handling:
40+
- Use Result<T> pattern consistently
41+
- Map provider-specific errors to common error types
42+
- Implement retry policies with exponential backoff
43+
- Handle transient vs permanent failures appropriately
44+
- Log errors with sufficient context for debugging
45+
46+
## Performance Optimization:
47+
- Use streaming for large files
48+
- Implement chunked uploads/downloads where supported
49+
- Leverage provider-specific optimizations (multipart uploads, CDN, etc.)
50+
- Pool connections and resources appropriately
51+
- Use Memory<T>/Span<T> for efficient buffer operations
52+
53+
## Testing Requirements:
54+
- Create comprehensive integration tests
55+
- Use Testcontainers for real service testing when possible
56+
- Test all CRUD operations, error scenarios, and edge cases
57+
- Verify metadata handling and options processing
58+
- Test concurrent operations and thread safety
59+
- Validate proper resource cleanup and disposal
60+
61+
## For ManagedCode.Storage Project Specifically:
62+
- Follow patterns established in Azure/AWS/FileSystem providers
63+
- Use PathHelper.* methods for cross-platform path handling
64+
- Implement MetadataKeys constants for all metadata
65+
- Support LocalFile wrapper integration
66+
- Ensure compatibility with server extensions (ControllerExtensions, etc.)
67+
- Add proper NuGet package references and versioning
68+
- Follow .NET 9 conventions and nullable reference types
69+
70+
## Code Quality:
71+
- Write self-documenting code with XML documentation
72+
- Use nullable reference types correctly
73+
- Follow established naming conventions
74+
- Implement proper disposal patterns (IDisposable/IAsyncDisposable)
75+
- Use ConfigureAwait(false) for library code
76+
- Handle all async operations with proper exception handling
77+
78+
tools: [Read, Write, Edit, MultiEdit, Bash, WebSearch, Grep, Glob, Task]
79+
80+
activation_patterns:
81+
- "provider implementation"
82+
- "storage provider"
83+
- "new provider"
84+
- "implement.*provider"
85+
- "Azure"
86+
- "AWS"
87+
- "Google Cloud"
88+
- "GCS"
89+
- "S3"
90+
- "blob storage"
91+
- "FTP"
92+
- "SFTP"
93+
- "FTPS"
94+
- "OneDrive"
95+
- "Dropbox"
96+
- "Google Drive"
97+
- "WebDAV"
98+
- "authentication"
99+
- "connection"
100+
- "SDK integration"
101+
- "OAuth"
102+
- "API integration"
103+
- "BaseStorage"
104+
- "IStorage"
105+
- "StorageProvider"
106+
- "extension methods"
107+
- "DI registration"

‎.claude/agents/storage-testing-agent.yaml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: storage-testing-agent
2+
description: "Testing expert for storage operations and integrations"
3+
4+
system_prompt: |
5+
You are a storage testing specialist focusing on:
6+
7+
## Testing Strategies:
8+
- Unit tests for core storage operations
9+
- Integration tests with real providers
10+
- Contract tests ensuring provider compatibility
11+
- Performance and load testing
12+
- Error scenario and edge case testing
13+
14+
## Tools and Frameworks:
15+
- xUnit with FluentAssertions
16+
- Testcontainers for integration testing
17+
- Mock providers and test doubles
18+
- Azure Azurite, AWS LocalStack, Google Fake GCS
19+
- Performance profiling and benchmarking
20+
21+
## Test Patterns:
22+
- Arrange-Act-Assert pattern
23+
- Test data builders and object mothers
24+
- Shared test fixtures and base classes
25+
- Parameterized tests for multiple providers
26+
- Async test patterns and proper disposal
27+
28+
## Focus Areas for ManagedCode.Storage:
29+
- Test all CRUD operations across providers
30+
- Verify error handling and edge cases
31+
- Test streaming and large file operations
32+
- Validate metadata and options handling
33+
- Ensure proper resource cleanup
34+
35+
tools: [Read, Write, Edit, Bash, Glob, Grep, MultiEdit]
36+
37+
activation_patterns:
38+
- "test"
39+
- "testing"
40+
- "unit test"
41+
- "integration test"
42+
- "testcontainers"
43+
- "mock"
44+
- "xunit"
45+
- "azurite"
46+
- "localstack"
47+
- "fake gcs"
48+
- "performance test"

‎.github/copilot-instructions.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Copilot Instructions for ManagedCode.Storage
2+
3+
## Overview
4+
5+
ManagedCode.Storage is a universal storage abstraction library that provides a consistent interface for working with multiple cloud blob storage providers including Azure Blob Storage, AWS S3, Google Cloud Storage, and local file system. The library aims to simplify development by providing a single API for all storage operations.
6+
7+
## Project Structure
8+
9+
- **ManagedCode.Storage.Core**: Core abstractions and interfaces (IStorage, BaseStorage, etc.)
10+
- **Storages/**: Provider-specific implementations
11+
- `ManagedCode.Storage.Azure`: Azure Blob Storage implementation
12+
- `ManagedCode.Storage.Aws`: AWS S3 implementation
13+
- `ManagedCode.Storage.Google`: Google Cloud Storage implementation
14+
- `ManagedCode.Storage.FileSystem`: Local file system implementation
15+
- `ManagedCode.Storage.Ftp`: FTP storage implementation
16+
- `ManagedCode.Storage.Azure.DataLake`: Azure Data Lake implementation
17+
- **Tests/**: Unit and integration tests
18+
- **Integrations/**: Additional integrations (SignalR, Client/Server components)
19+
20+
## Technical Context
21+
22+
- **Target Framework**: .NET 9.0
23+
- **Language Version**: C# 13
24+
- **Architecture**: Provider pattern with unified interfaces
25+
- **Key Features**: Async/await support, streaming operations, metadata handling, progress reporting
26+
27+
## Development Guidelines
28+
29+
### Code Style & Standards
30+
- Use nullable reference types (enabled in project)
31+
- Follow async/await patterns consistently
32+
- Use ValueTask for performance-critical operations where appropriate
33+
- Implement proper cancellation token support in all async methods
34+
- Use ConfigureAwait(false) for library code
35+
- Follow dependency injection patterns
36+
37+
### Key Interfaces & Patterns
38+
- `IStorage`: Main storage interface for blob operations
39+
- `IStorageOptions`: Configuration options for storage providers
40+
- `BaseStorage`: Base implementation with common functionality
41+
- All operations should support progress reporting via `IProgress<T>`
42+
- Use `BlobMetadata` for storing blob metadata
43+
- Support for streaming operations with `IStreamer`
44+
45+
### Performance Considerations
46+
- Implement efficient streaming for large files
47+
- Use memory-efficient approaches for data transfer
48+
- Cache metadata when appropriate
49+
- Support parallel operations where beneficial
50+
- Minimize allocations in hot paths
51+
52+
### Testing Approach
53+
- Unit tests for core logic
54+
- Integration tests for provider implementations
55+
- Use test fakes/mocks for external dependencies
56+
- Test error scenarios and edge cases
57+
- Validate async operation behavior
58+
59+
### Provider Implementation Guidelines
60+
When implementing new storage providers:
61+
1. Inherit from `BaseStorage` class
62+
2. Implement all required interface methods
63+
3. Handle provider-specific errors appropriately
64+
4. Support all metadata operations
65+
5. Implement efficient streaming operations
66+
6. Add comprehensive tests
67+
7. Document provider-specific limitations or features
68+
69+
### Error Handling
70+
- Use appropriate exception types for different error scenarios
71+
- Provide meaningful error messages
72+
- Handle provider-specific errors and translate to common exceptions
73+
- Support retry mechanisms where appropriate
74+
75+
### Documentation
76+
- Document public APIs with XML comments
77+
- Include usage examples for complex operations
78+
- Document provider-specific behavior differences
79+
- Keep README.md updated with supported features
80+
81+
## Common Tasks
82+
83+
### Adding a New Storage Provider
84+
1. Create new project in `Storages/` folder
85+
2. Inherit from `BaseStorage`
86+
3. Implement provider-specific operations
87+
4. Add configuration options
88+
5. Create comprehensive tests
89+
6. Update solution file and documentation
90+
91+
### Implementing New Features
92+
1. Define interface changes in Core project
93+
2. Update BaseStorage if needed
94+
3. Implement in all relevant providers
95+
4. Add tests for new functionality
96+
5. Update documentation
97+
98+
### Performance Optimization
99+
- Profile critical paths
100+
- Optimize memory allocations
101+
- Improve streaming performance
102+
- Cache frequently accessed data
103+
- Use efficient data structures
104+
105+
## Dependencies & Libraries
106+
- Provider-specific SDKs (Azure.Storage.Blobs, AWS SDK, Google Cloud Storage)
107+
- Microsoft.Extensions.* for dependency injection and configuration
108+
- System.Text.Json for serialization
109+
- Benchmarking tools for performance testing
110+
111+
## Building & Testing
112+
- Use `dotnet build` to build the solution
113+
- Run `dotnet test` for unit tests
114+
- Integration tests may require cloud provider credentials
115+
- Use `dotnet pack` to create NuGet packages

‎AGENTS.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
## Conversations
2+
any resulting updates to agents.md should go under the section "## Rules to follow"
3+
When you see a convincing argument from me on how to solve or do something. add a summary for this in agents.md. so you learn what I want over time.
4+
If I say any of the following point, you do this: add the context to agents.md, and associate this with a specific type of task.
5+
if I say "never do x" in some way.
6+
if I say "always do x" in some way.
7+
if I say "the process is x" in some way.
8+
If I tell you to remember something, you do the same, update
9+
10+
11+
## Rules to follow
12+
TBA
13+
14+
# Repository Guidelines
15+
16+
## Project Structure & Module Organization
17+
ManagedCode.Storage.slnx orchestrates the .NET 9 projects. Core abstractions live in `ManagedCode.Storage.Core/`. Providers sit under `Storages/ManagedCode.Storage.*` with one project per cloud target (Azure, AWS, GCP, FileSystem, Ftp). Integration surfaces, including the ASP.NET server and client SDKs, live in `Integraions/`. Test doubles stay in `ManagedCode.Storage.TestFakes/`, while the suites in `Tests/ManagedCode.Storage.Tests/` are grouped into ASP.NET flows, provider runs, and shared helpers. Keep shared assets such as `logo.png` at the repository root.
18+
19+
## Build, Test, and Development Commands
20+
Run `dotnet restore ManagedCode.Storage.slnx` before compiling. Use `dotnet build ManagedCode.Storage.slnx` to compile every target and surface analyzer warnings. Execute all tests with `dotnet test Tests/ManagedCode.Storage.Tests/ManagedCode.Storage.Tests.csproj --configuration Release`. For coverage, run `dotnet test /p:CollectCoverage=true /p:CoverletOutput=coverage /p:CoverletOutputFormat=opencover`. Use `dotnet format ManagedCode.Storage.slnx` before opening a pull request.
21+
22+
## Coding Style & Naming Conventions
23+
Follow standard C# conventions: 4-space indentation, PascalCase types, camelCase locals, and suffix async APIs with `Async`. Nullability is enabled repository-wide, so annotate optional members and avoid the suppression operator unless justified. Match method names to existing patterns such as `DownloadFile_WhenFileExists_ReturnsSuccess`. Remove unused usings and let analyzers guide layout.
24+
25+
## Testing Guidelines
26+
Tests use xUnit and FluentAssertions; choose `[Fact]` for atomic cases and `[Theory]` for data-driven permutations. Place provider suites under `Tests/ManagedCode.Storage.Tests/Storages/` and reuse `.../Common/` helpers to spin up Testcontainers (Azurite, LocalStack, FakeGcsServer). Add fakes or harnesses mirroring `ManagedCode.Storage.TestFakes/` when introducing new providers. Always run `dotnet test` locally and exercise critical upload/download paths.
27+
28+
## Commit & Pull Request Guidelines
29+
Write commit subjects in the imperative mood (`add ftp retry policy`) and keep them provider-scoped. Group related edits in one commit and avoid WIP spam. Pull requests should summarize impact, list touched projects, reference issues, and note new configuration or secrets. Include the `dotnet` commands you ran and add logs when CI needs context.
30+
31+
## Security & Configuration Tips
32+
Never commit API keys, connection strings, or `.trx` artifacts; rely on environment variables or user secrets. Document minimal permissions and default container expectations for new providers. Ensure server integrations stay authenticated and refresh configuration examples in `README.md` when behavior changes.

0 commit comments

Comments
 (0)