Skip to content

Commit 6f00d22

Browse files
Copilotmasilver99
Copilot
and
masilver99
committed
Add comprehensive GitHub Copilot instructions
Co-authored-by: masilver99 <14352629+masilver99@users.noreply.github.com>
1 parent 1bf3274 commit 6f00d22

5 files changed

Lines changed: 163 additions & 1056 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# GitHub Copilot Instructions for AgQueue
2+
3+
## Project Overview
4+
5+
AgQueue is a simple, opinionated, transactional work queue system built in C# with .NET 5. It transforms any supported database (currently SQLite and PostgreSQL) into a full-fledged work queue with advanced messaging capabilities.
6+
7+
### Key Features
8+
- **Transactional**: Transactions are mandatory with expiry timespans and can be extended
9+
- **Priority Support**: Messages returned by priority, then FIFO
10+
- **Durable Storage**: Messages reliably stored to disk using SQLite/PostgreSQL
11+
- **Multiple Queues**: Support for multiple named queues
12+
- **Built-in Retry**: Automatic message retry with configurable delays
13+
- **gRPC Communication**: Primary communication via gRPC server
14+
- **Message Metadata**: Custom data storage for messages with tags and correlation IDs
15+
16+
## Architecture
17+
18+
### Project Structure
19+
- **AgQueue.Server.Common**: Core internal API and storage interfaces
20+
- **AgQueue.Common**: Client interfaces and common models
21+
- **AgQueue.GrpcServer**: gRPC server implementation
22+
- **AgQueue.Sqlite**: SQLite storage implementation
23+
- **AgQueue.Postgres**: PostgreSQL storage implementation
24+
- **AgQueue.Models**: Shared data models and protobuf definitions
25+
- **Benchmarks**: Performance benchmarking project
26+
- **tests/**: Integration and unit tests
27+
28+
### Key Components
29+
1. **InternalApi**: Core business logic for queue operations
30+
2. **IStorage/IStorageTransaction**: Storage abstraction layer
31+
3. **AgQueueService**: gRPC service implementation
32+
4. **Transaction Management**: Two-level transaction system (queue + database)
33+
5. **protobuf/gRPC**: Protocol definitions in `AgQueue.Models/AgQueue.proto`
34+
35+
### gRPC API Structure
36+
The main service `QueueApi` provides these operations:
37+
- **Queue Management**: CreateQueue, DeleteQueue, GetQueueInfo
38+
- **Transaction Control**: StartTransaction, CommitTransaction, RollbackTransaction
39+
- **Message Operations**: QueueMessage, DequeueMessage, PeekMessage
40+
- **Storage Management**: InitializeStorage
41+
42+
## Development Guidelines
43+
44+
### Code Standards
45+
- Follow StyleCop Analyzers recommendations (configured in stylecop.json)
46+
- **Zero warnings policy**: Pull requests must have no compiler warnings
47+
- Use XML documentation (`///`) for all public methods and properties
48+
- Company name: "Michael Silver" (configured in stylecop.json)
49+
- Copyright: "Copyright (c) Michael Silver. All rights reserved."
50+
51+
### Coding Conventions
52+
- Use int64 for primary keys (application-generated, not database-generated)
53+
- Queue names are case sensitive
54+
- Prefer explicit error handling over exceptions where appropriate
55+
- Use `ResultCode` enum for internal API responses (maps to gRPC status codes)
56+
57+
### Key Patterns
58+
59+
#### Transaction Handling
60+
```csharp
61+
// Two types of transactions to be aware of:
62+
// 1. Database transactions (IStorageTransaction) - for SQL atomicity
63+
// 2. Queue transactions (stored in Transaction table) - for message handling
64+
```
65+
66+
#### Storage Implementation
67+
- Implement `IStorage` interface for new database providers
68+
- Reference `StorageSqlite` class as the primary example
69+
- Handle connection management and transaction lifecycle properly
70+
71+
#### Error Handling
72+
- Use `ApiResult<T>` for internal API returns
73+
- Map `ResultCode` to appropriate gRPC status codes
74+
- Implement proper exception interceptors for gRPC calls
75+
76+
### Build and Testing
77+
- Target Framework: .NET 5.0 (note: end-of-life, may require upgrade to newer .NET version)
78+
- Build with: `dotnet build --configuration Release`
79+
- Run tests: `dotnet test` (requires .NET 5.0 runtime)
80+
- No warnings should be present in successful builds
81+
- Integration tests use in-process gRPC server on port 10043
82+
- Current build shows package vulnerabilities (MessagePack, Newtonsoft.Json, Npgsql)
83+
- **Note**: Tests may fail on systems without .NET 5.0 runtime installed
84+
85+
### Dependencies and Packages
86+
- **gRPC**: Primary communication protocol (.proto files in AgQueue.Models)
87+
- **SQLite/PostgreSQL**: Supported database backends
88+
- **StyleCop.Analyzers**: Code analysis and formatting
89+
- **MSTest**: Testing framework for integration tests
90+
- **BenchmarkDotNet**: Performance benchmarking
91+
- **MessagePack**: Serialization (note: has known vulnerability in current version)
92+
- **Newtonsoft.Json**: JSON handling (note: has known vulnerability in current version)
93+
94+
## Common Development Tasks
95+
96+
### Adding New Queue Operations
97+
1. Add method to `InternalApi` class
98+
2. Implement corresponding gRPC service method in `AgQueueService`
99+
3. Update storage interface (`IStorage`) if needed
100+
4. Implement in storage providers (SQLite/Postgres)
101+
5. Add integration tests
102+
6. Update documentation
103+
104+
### Adding New Storage Provider
105+
1. Create new project (e.g., `AgQueue.Redis`)
106+
2. Implement `IStorage` and `IStorageTransaction` interfaces
107+
3. Follow patterns from `StorageSqlite` implementation
108+
4. Handle primary key generation consistently
109+
5. Add appropriate error handling and resource disposal
110+
111+
### Message Workflows
112+
1. **Add Message**: CreateQueue → StartTransaction → QueueMessage → CommitTransaction
113+
2. **Pull Message**: StartTransaction → DequeueMessage → (Process) → CommitTransaction/RollbackTransaction
114+
3. **Peek Message**: PeekMessageByQueue/PeekMessageById (no transaction required)
115+
116+
### Message Properties
117+
- **Payload**: Binary message data (bytes)
118+
- **Priority**: Lower number = higher priority (int32)
119+
- **MaxAttempts**: Retry limit before message expiration
120+
- **ExpiryInMinutes**: Message lifetime (0 = no expiration)
121+
- **CorrelationId**: Optional application-defined correlation (int32)
122+
- **GroupName**: Optional grouping string
123+
- **MetaData**: Optional descriptive string data
124+
125+
### Message States
126+
- **Active**: Available for processing
127+
- **InTransaction**: Currently being processed
128+
- **Processed**: Successfully completed
129+
- **Expired**: Exceeded expiry time
130+
- **AttemptsExceeded**: Exceeded max retry attempts
131+
132+
### Testing Guidelines
133+
- Use `[DoNotParallelize]` attribute for integration tests
134+
- Initialize storage with `DeleteExistingData = true` for clean tests
135+
- Clean up resources in `TestCleanup` methods
136+
- Test both success and error scenarios
137+
138+
## Important Notes
139+
140+
### Transaction Complexity
141+
The codebase has two transaction concepts that can be confusing:
142+
- **Database transactions**: SQL-level atomicity (IStorageTransaction)
143+
- **Queue transactions**: Business-level message handling (stored in Transaction table)
144+
145+
### Performance Considerations
146+
- Int64 primary keys chosen over GUIDs for better database performance
147+
- Single-process limitation due to application-generated primary keys
148+
- SQLite chosen for durability over raw speed
149+
150+
### Migration Notes
151+
- Project originally planned TCP and REST servers
152+
- Consolidated to gRPC-only for better performance and feature completeness
153+
- Some legacy documentation may reference old architecture
154+
155+
## StyleCop Configuration
156+
157+
The project uses StyleCop Analyzers with custom rules:
158+
- SA1200 (using directives placement) is disabled
159+
- SA1413 (trailing commas) is disabled
160+
- Company name and copyright are automatically applied
161+
- License type: MIT
162+
163+
Always ensure your changes conform to the configured StyleCop rules and maintain zero warnings.

0 commit comments

Comments
 (0)