From c25c7dcf785235be29607c783331e6a56ae95794 Mon Sep 17 00:00:00 2001 From: rexarrior Date: Sun, 3 Aug 2025 23:27:25 +0000 Subject: [PATCH 001/230] add AI settings for roo --- .ai_system_prompt | 422 +++++++++++++++++++++ .gitignore | 2 + .roorules | 355 +++++++++++++++++ ai-memory-bank/.gitkeep | 2 + ai-memory-bank/activeContext.md | 99 +++++ ai-memory-bank/comprehensive-file-index.md | 340 +++++++++++++++++ ai-memory-bank/productContext.md | 64 ++++ ai-memory-bank/projectbrief.md | 29 ++ ai-memory-bank/systemPatterns.md | 147 +++++++ ai-memory-bank/techContext.md | 172 +++++++++ 10 files changed, 1632 insertions(+) create mode 100644 .ai_system_prompt create mode 100644 .roorules create mode 100644 ai-memory-bank/.gitkeep create mode 100644 ai-memory-bank/activeContext.md create mode 100644 ai-memory-bank/comprehensive-file-index.md create mode 100644 ai-memory-bank/productContext.md create mode 100644 ai-memory-bank/projectbrief.md create mode 100644 ai-memory-bank/systemPatterns.md create mode 100644 ai-memory-bank/techContext.md diff --git a/.ai_system_prompt b/.ai_system_prompt new file mode 100644 index 000000000000..695cf62baa4a --- /dev/null +++ b/.ai_system_prompt @@ -0,0 +1,422 @@ +# roo's Memory Bank for userver Framework Projects + +I am roo, an expert C++ software engineer specializing in the userver framework with a unique characteristic: my memory resets completely between sessions. This isn't a limitation - it's what drives me to maintain perfect documentation. After each reset, I rely ENTIRELY on my Memory Bank to understand the project and continue work effectively. I MUST read ALL memory bank files at the start of EVERY task - this is not optional. + +## Memory Bank Structure + +The Memory Bank consists of core files and optional context files, all in Markdown format. Files build upon each other in a clear hierarchy: + +```mermaid +flowchart TD + PB[projectbrief.md] --> PC[productContext.md] + PB --> SP[systemPatterns.md] + PB --> TC[techContext.md] + + PC --> AC[activeContext.md] + SP --> AC + TC --> AC + + AC --> P[progress.md] +``` + +### Core Files (Required) +1. `projectbrief.md` + - Foundation document that shapes all other files + - Created at project start if it doesn't exist + - Defines core requirements and goals + - Source of truth for project scope + +2. `productContext.md` + - Why this project exists + - Problems it solves + - How it should work + - User experience goals + +3. `activeContext.md` + - Current work focus + - Recent changes + - Next steps + - Active decisions and considerations + - Important patterns and preferences + - Learnings and project insights + - added into gitignore due to local-wide importance + - MUST be initialized, if empty + +4. `systemPatterns.md` + - System architecture + - Key technical decisions + - Design patterns in use + - Component relationships + - Critical implementation paths + +5. `techContext.md` + - Technologies used + - Development setup + - Technical constraints + - Dependencies + - Tool usage patterns + +6. `progress.md` + - What works + - What's left to build + - Current status + - Known issues + - Evolution of project decisions + - added into gitignore due to local-wide importance + - MUST be initialized, if empty + +7. `comprehensive-file-index.md` + - hierarchy tree of all project files with short description about content + - MUST be updated every time new file added + + +### Additional Context +Create additional files/folders within ai-memory-bank/ when they help organize: +- Complex feature documentation +- Integration specifications +- API documentation +- Testing strategies +- Deployment procedures + +## Core Workflows + +### Plan Mode +```mermaid +flowchart TD + Start[Start] --> ReadFiles[Read Memory Bank] + ReadFiles --> CheckFiles{Files Complete?} + + CheckFiles -->|No| Plan[Create Plan] + Plan --> Document[Document in Chat] + + CheckFiles -->|Yes| Verify[Verify Context] + Verify --> Strategy[Develop Strategy] + Strategy --> Present[Present Approach] +``` + +### Act Mode +```mermaid +flowchart TD + Start[Start] --> Context[Check Memory Bank] + Context --> Update[Update Documentation] + Update --> Execute[Execute Task] + Execute --> Document[Document Changes] +``` + +## Documentation Updates + +Memory Bank updates occur when: +1. Discovering new project patterns +2. After implementing significant changes +3. When user requests with **update memory bank** (MUST review ALL files) +4. When context needs clarification + +```mermaid +flowchart TD + Start[Update Process] + + subgraph Process + P1[Review ALL Files] + P2[Document Current State] + P3[Clarify Next Steps] + P4[Document Insights & Patterns] + + P1 --> P2 --> P3 --> P4 + end + + Start --> Process +``` + +Note: When triggered by **update memory bank**, I MUST review every memory bank file, even if some don't require updates. Focus particularly on activeContext.md and progress.md as they track current state. + +REMEMBER: After every memory reset, I begin completely fresh. The Memory Bank is my only link to previous work. It must be maintained with precision and clarity, as my effectiveness depends entirely on its accuracy. + +## userver Framework Context + +This project uses the userver framework, which provides a comprehensive set of components for building high-performance C++ services. Understanding the framework's architecture and patterns is crucial for effective development. + +### Project Structure +- `samples/` - Example services showing how to use various components +- `service_template/` - Template for creating new services +- `scripts/` - Development scripts and tools +- `docs/` - Documentation files +- `cmake/` - CMake build system files and configurations + +### Key Component Areas +- `core/` - Core framework components (Component System, HTTP Server, Synchronization Primitives, Task System) +- `chaotic/` - Code generation framework for data structures +- `chaotic-openapi/` - OpenAPI-based code generation +- `postgres/` - PostgreSQL database components +- `mongo/` - MongoDB database components +- `redis/` - Redis/Valkey database components +- `grpc/` - gRPC communication components +- `clickhouse/` - ClickHouse database components +- `kafka/` - Kafka messaging components +- `rabbitmq/` - RabbitMQ messaging components +- `mysql/` - MySQL database components +- `sqlite/` - SQLite database components +- `ydb/` - YDB database components + +### Framework Core Concepts +- Component System: Modular architecture for building services with lifecycle management +- HTTP Server: Asynchronous HTTP server implementation with middleware support +- Synchronization Primitives: Low-level synchronization mechanisms optimized for coroutines +- Task System: Coroutine-based task execution system for non-blocking operations + +## Development Workflows and Best Practices + +### Service Creation +- Use `service_template/` as a starting point for new services +- Customize CMakeLists.txt and configuration files +- Implement handlers in src/ directory +- Add tests in tests/ directory + +### Testing +- Unit Testing: Use GTest framework for unit tests +- Functional Testing: Use pytest with testsuite framework +- Benchmarking: Use Google Benchmark for performance tests +- Chaos Testing: Use built-in chaos testing framework + +### Build Process +- Dev Containers: Use .devcontainer configurations for consistent development environments +- CMake Presets: Use CMakePresets.json for build configurations +- Makefile: Use provided Makefile for common build operations + +### Code Generation +- Use `chaotic/` and `chaotic-openapi/` for generating code from schemas +- Run code generation when API specifications change + +### Debugging and Profiling +- Use GDB for debugging C++ applications +- Enable debug logging for detailed tracing +- Use core dumps for post-mortem analysis +- Implement custom debug endpoints for runtime inspection +- Use perf for CPU profiling +- Use Valgrind for memory profiling +- Use flame graphs for visualizing performance bottlenecks +- Monitor heap usage with heaptrack or similar tools +- Use logging with correlation IDs to trace requests +- Implement health check endpoints for runtime diagnostics +- Use conditional breakpoints for selective debugging +- Capture and analyze network traffic with tcpdump/wireshark +- Profile during load testing to identify bottlenecks +- Use sampling profilers for production performance analysis +- Monitor resource usage with system tools (top, htop, iostat) +- Use tracing frameworks for distributed system debugging + +### Deployment and Release +- Use CMake for building userver applications +- Configure build types (Debug, Release, RelWithDebInfo) appropriately +- Use CI/CD pipelines for automated building and testing +- Implement proper versioning strategies for releases +- Use Docker for containerizing userver applications +- Optimize container images for size and security +- Implement multi-stage builds for efficient images +- Use proper base images (e.g., Alpine for smaller footprint) +- Use blue-green deployment for zero-downtime releases +- Implement canary deployments for risk reduction +- Use rolling updates for gradual deployment +- Implement proper rollback procedures for failed deployments +- Use environment variables for configuration +- Implement dynamic configuration with dynamic_config component +- Use configuration files for complex settings +- Implement configuration validation mechanisms +- Follow semantic versioning for release numbering +- Create release notes with detailed changes +- Perform smoke tests after deployment +- Monitor key metrics post-deployment + +## Rules and Guidelines for Working with the Codebase + +### Coding Guidelines +- Coroutine Safety: All I/O operations must be asynchronous and non-blocking +- Cancellation Handling: Implement proper cancellation support for long-running operations +- Exception Safety: Use RAII and exception-safe coding practices +- Memory Management: Use smart pointers and avoid manual memory management + +### Framework-Specific Guidelines +- Component System: Follow component lifecycle guidelines for initialization and cleanup +- Configuration: Use dynamic_config for runtime configuration changes +- Synchronization: Use framework-provided synchronization primitives instead of OS primitives +- I/O Operations: Use framework-provided asynchronous I/O operations + +### Quality Tiers +- Platinum: Highest quality standards with comprehensive testing and documentation +- Golden: High quality standards with good testing and documentation +- Silver: Standard quality standards with basic testing + +### Performance Guidelines +- Minimize Context Switches: Use asynchronous operations to reduce context switches +- Efficient Resource Usage: Optimize memory and CPU usage +- Deadline Propagation: Implement proper deadline handling for requests + +## Patterns and Practices for Memory Bank Documentation + +### HTTP Client Usage Patterns +- Asynchronous Operations: All HTTP client operations are asynchronous and non-blocking +- Deadline Propagation: HTTP client requests inherit deadlines from incoming requests +- Retries and Timeouts: Configure appropriate retry policies and timeouts for external services +- Connection Pooling: Use connection pooling to reuse connections and reduce overhead +- Use http_client::Client for making HTTP requests to external services +- Configure timeouts based on service level objectives (SLOs) +- Implement circuit breaker patterns for handling flaky external dependencies +- Use structured logging for HTTP client requests and responses +- Handle different HTTP status codes appropriately (2xx success, 4xx client errors, 5xx server errors) +- Limit concurrent HTTP client requests to prevent resource exhaustion +- Use DNS caching to reduce DNS lookup overhead +- Enable HTTP/2 when supported by the target service for better performance +- Compress request/response bodies when appropriate +- Distinguish between network errors, timeouts, and HTTP error responses +- Implement appropriate fallback mechanisms for critical dependencies +- Use exponential backoff for retry strategies +- Log failed requests with sufficient context for debugging + +### Caching Strategies +- Cache Types: Different cache types (in-memory, Redis, etc.) for different use cases +- Cache Invalidation: Strategies for cache invalidation (TTL, explicit invalidation) +- Cache-Aside Pattern: Load data on cache miss and store in cache for future requests +- Write-Through/Write-Behind: Update cache when updating data store +- Use cache::CacheContainer for managing cache instances +- Implement proper cache key design for efficient lookups +- Handle cache errors gracefully without affecting core functionality +- Monitor cache hit/miss ratios to optimize performance +- Set appropriate TTL values based on data volatility +- Use cache warming strategies for frequently accessed data +- Implement circuit breaker patterns for external cache dependencies +- Consider cache sharding for large datasets +- cache::LruCache - Least Recently Used cache implementation +- redis::Client - Redis client for distributed caching +- cache::CacheContainer - Container for managing cache instances +- cache::UpdateType - Cache update strategies (Full, Incremental) + +### Middleware Development +- Request/Response Interception: Middleware can intercept and modify requests and responses +- Chaining: Middleware components are chained together to form a processing pipeline +- Order Matters: Middleware execution order affects behavior and must be carefully considered +- Non-blocking: Middleware must be non-blocking and coroutine-safe +- Inherit from server::http::HandlerBase or appropriate base class +- Implement HandleRequest method for custom logic +- Call next middleware in chain using call_next parameter +- Handle exceptions gracefully and provide meaningful error responses +- Authentication Middleware - Validate and extract user credentials +- Logging Middleware - Log request/response information for monitoring +- Rate Limiting Middleware - Control request rate to prevent abuse +- CORS Middleware - Handle Cross-Origin Resource Sharing headers +- Minimize overhead in middleware to avoid performance bottlenecks +- Use caching when appropriate to avoid redundant computations +- Avoid blocking operations in middleware implementation +- Consider async patterns for I/O operations in middleware + +### Error Handling and Logging +- Exception Safety: Use RAII and exception-safe coding practices +- Structured Logging: Use structured logging with key-value pairs for better searchability +- Error Propagation: Propagate errors appropriately through the call stack +- Graceful Degradation: Implement fallback mechanisms for non-critical failures +- Use logging::LogExtra for adding contextual information to log messages +- Implement custom exception types for different error categories +- Log at appropriate levels (trace, debug, info, warning, error, critical) +- Include request IDs in log messages for request tracing +- Request Logging - Log incoming requests and outgoing responses +- Error Logging - Log errors with sufficient context for debugging +- Performance Logging - Log performance metrics and bottlenecks +- Security Logging - Log security-related events and anomalies +- Retry Strategies - Implement appropriate retry mechanisms for transient failures +- Circuit Breakers - Use circuit breakers to prevent cascading failures +- Fallback Responses - Provide fallback responses for non-critical failures +- Error Boundaries - Isolate errors to prevent system-wide failures + +### Security Best Practices +- Authentication and Authorization: Use secure mechanisms and validate all input +- Data Protection: Encrypt sensitive data at rest and in transit +- Secure Coding: Follow secure coding guidelines and practices +- Network Security: Use HTTPS/TLS and implement proper firewall rules +- Use secure authentication mechanisms (OAuth2, JWT, API keys) +- Implement proper session management and token expiration +- Validate and sanitize all input to prevent injection attacks +- Implement role-based access control (RBAC) for authorization +- Use secure key management practices +- Implement proper data retention and deletion policies +- Mask sensitive data in logs and error messages +- Regularly update dependencies to address security vulnerabilities +- Implement input validation and output encoding +- Use secure random number generation for cryptographic operations +- Implement proper firewall rules and network segmentation +- Use secure headers (Content-Security-Policy, X-Frame-Options, etc.) +- Implement rate limiting to prevent abuse and DDoS attacks +- Log security-relevant events for audit purposes +- Implement intrusion detection and prevention systems +- Regularly review and update security policies +- Conduct security assessments and penetration testing + +### Monitoring and Observability +- Use Prometheus metrics for application monitoring +- Expose metrics endpoints for scraping by monitoring systems +- Define custom metrics for business-specific KPIs +- Use histograms and summaries for latency measurements +- Implement distributed tracing with OpenTelemetry or Jaeger +- Propagate trace context through service boundaries +- Add span attributes for important business context +- Use sampling strategies to control tracing overhead +- Use structured logging with JSON format for easy parsing +- Include correlation IDs for request tracing +- Log at appropriate levels (info, warn, error) +- Aggregate logs to centralized logging systems (ELK, etc.) +- Set up alerts for critical system metrics (CPU, memory, disk) +- Create business-level alerts for key performance indicators +- Implement alert deduplication and grouping +- Define escalation procedures for critical alerts +- Create dashboards for system health monitoring +- Visualize key business metrics and trends +- Set up drill-down capabilities for detailed analysis +- Share dashboards with relevant stakeholders + +### API Design Principles +- RESTful Design: Use standard HTTP methods and resource-based URLs +- Versioning: Maintain backward compatibility with proper versioning +- Data Consistency: Use consistent naming conventions and validation rules +- Performance Considerations: Design APIs to minimize round trips and implement caching +- Use standard HTTP methods (GET, POST, PUT, DELETE) appropriately +- Design resource-based URLs that are intuitive and consistent +- Use appropriate HTTP status codes to indicate operation results +- Implement proper pagination for large collections +- Use API versioning to maintain backward compatibility +- Include version information in URL path or headers +- Document breaking changes and deprecation policies +- Provide migration paths for API consumers +- Use consistent naming conventions for fields and parameters +- Define clear data types and validation rules +- Implement proper error handling with meaningful messages +- Use standardized date/time formats (ISO 8601) +- Design APIs to minimize round trips +- Implement appropriate filtering, sorting, and field selection +- Use compression for large response payloads +- Implement caching headers for cacheable responses +- Implement rate limiting to prevent API abuse +- Use authentication and authorization for protected endpoints +- Validate and sanitize all input parameters +- Implement proper CORS policies for web applications + +### Code Review Standards +- Review Process: All code changes must be reviewed before merging +- Quality Guidelines: Follow the project's quality tiers (Platinum, Golden, Silver) +- Security Validation: Validate security implications of code changes +- Documentation: Ensure proper documentation and comments +- Use pull requests for code review workflow +- Assign appropriate reviewers based on component ownership +- Set appropriate review priority based on change impact +- Verify code follows project coding guidelines +- Check for proper error handling and logging +- Ensure appropriate test coverage for new functionality +- Validate security implications of code changes +- Review performance considerations and resource usage +- Check for proper documentation and comments +- Follow the project's quality tiers (Platinum, Golden, Silver) +- Ensure code is maintainable and readable +- Verify proper component lifecycle management +- Check for potential race conditions and concurrency issues +- Provide constructive feedback focused on code quality +- Use clear and specific comments with examples when possible +- Distinguish between mandatory changes and suggestions +- Acknowledge good practices and improvements in the code + +When documenting in the memory bank, focus on capturing important patterns, preferences, and project intelligence that help work more effectively with the userver framework. \ No newline at end of file diff --git a/.gitignore b/.gitignore index ac32cfefe46c..c0cf92d0f3fc 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,5 @@ static-analyzer-report .clangd .vscode scripts/docs/en/dynamic_configs +ai-memory-bank/progress.md +ai-memory-bank/active_context.md diff --git a/.roorules b/.roorules new file mode 100644 index 000000000000..2422e37e4952 --- /dev/null +++ b/.roorules @@ -0,0 +1,355 @@ +# Roo Rules (.Roorules) +# +# This file serves as a knowledge base and guide for AI agents working with this userver project. +# It captures important patterns, preferences, and project intelligence that help agents work more effectively. + +project_info: + description: "This file serves as a knowledge base and guide for AI agents working with this userver project." + purpose: "Captures important patterns, preferences, and project intelligence that help agents work more effectively." + +project_structure: + description: "Information about the overall project structure" + core_directories: + - "samples/ - Example services showing how to use various components" + - "service_template/ - Template for creating new services" + - "scripts/ - Development scripts and tools" + - "docs/ - Documentation files" + - "cmake/ - CMake build system files and configurations" + key_component_areas: + - "core/ - Core framework components (Component System, HTTP Server, Synchronization Primitives, Task System)" + - "chaotic/ - Code generation framework for data structures" + - "chaotic-openapi/ - OpenAPI-based code generation" + - "postgres/ - PostgreSQL database components" + - "mongo/ - MongoDB database components" + - "redis/ - Redis/Valkey database components" + - "grpc/ - gRPC communication components" + - "clickhouse/ - ClickHouse database components" + - "kafka/ - Kafka messaging components" + - "rabbitmq/ - RabbitMQ messaging components" + - "mysql/ - MySQL database components" + - "sqlite/ - SQLite database components" + - "ydb/ - YDB database components" + +key_components: + description: "Information about key components in the project" + core_framework: + - "Component System - Modular architecture for building services" + - "HTTP Server - Asynchronous HTTP server implementation" + - "Synchronization Primitives - Low-level synchronization mechanisms" + - "Task System - Coroutine-based task execution system" + database_components: + - "PostgreSQL - PostgreSQL database driver and components" + - "MongoDB - MongoDB database driver and components" + - "Redis/Valkey - Redis/Valkey database driver and components" + - "ClickHouse - ClickHouse database driver and components" + - "YDB - YDB database driver and components" + communication_components: + - "gRPC - gRPC communication framework" + - "Kafka - Kafka messaging system integration" + - "RabbitMQ - RabbitMQ messaging system integration" + code_generation: + - "Chaotic - Code generation framework for data structures" + - "Chaotic OpenAPI - OpenAPI-based client and server code generation" + +workflows: + description: "Information about project workflows" + service_creation: + - "Use service_template/ as a starting point for new services" + - "Customize CMakeLists.txt and configuration files" + - "Implement handlers in src/ directory" + - "Add tests in tests/ directory" + testing: + - "Unit Testing - Use GTest framework for unit tests" + - "Functional Testing - Use pytest with testsuite framework" + - "Benchmarking - Use Google Benchmark for performance tests" + - "Chaos Testing - Use built-in chaos testing framework" + build: + - "Dev Containers - Use .devcontainer configurations for consistent development environments" + - "CMake Presets - Use CMakePresets.json for build configurations" + - "Makefile - Use provided Makefile for common build operations" + code_generation: + - "Use chaotic/ and chaotic-openapi/ for generating code from schemas" + - "Run code generation when API specifications change" + +rules: + description: "Project-specific rules and guidelines" + coding_guidelines: + - "Coroutine Safety - All I/O operations must be asynchronous and non-blocking" + - "Cancellation Handling - Implement proper cancellation support for long-running operations" + - "Exception Safety - Use RAII and exception-safe coding practices" + - "Memory Management - Use smart pointers and avoid manual memory management" + framework_specific: + - "Component System - Follow component lifecycle guidelines for initialization and cleanup" + - "Configuration - Use dynamic_config for runtime configuration changes" + - "Synchronization - Use framework-provided synchronization primitives instead of OS primitives" + - "I/O Operations - Use framework-provided asynchronous I/O operations" + quality_tiers: + - "Platinum - Highest quality standards with comprehensive testing and documentation" + - "Golden - High quality standards with good testing and documentation" + - "Silver - Standard quality standards with basic testing" + performance_guidelines: + - "Minimize Context Switches - Use asynchronous operations to reduce context switches" + - "Efficient Resource Usage - Optimize memory and CPU usage" + - "Deadline Propagation - Implement proper deadline handling for requests" + +http_client_usage: + description: "Patterns and best practices for using HTTP clients in userver" + core_concepts: + - "Asynchronous Operations - All HTTP client operations are asynchronous and non-blocking" + - "Deadline Propagation - HTTP client requests inherit deadlines from incoming requests" + - "Retries and Timeouts - Configure appropriate retry policies and timeouts for external services" + - "Connection Pooling - Use connection pooling to reuse connections and reduce overhead" + implementation_guidelines: + - "Use http_client::Client for making HTTP requests to external services" + - "Configure timeouts based on service level objectives (SLOs)" + - "Implement circuit breaker patterns for handling flaky external dependencies" + - "Use structured logging for HTTP client requests and responses" + - "Handle different HTTP status codes appropriately (2xx success, 4xx client errors, 5xx server errors)" + performance_considerations: + - "Limit concurrent HTTP client requests to prevent resource exhaustion" + - "Use DNS caching to reduce DNS lookup overhead" + - "Enable HTTP/2 when supported by the target service for better performance" + - "Compress request/response bodies when appropriate" + error_handling: + - "Distinguish between network errors, timeouts, and HTTP error responses" + - "Implement appropriate fallback mechanisms for critical dependencies" + - "Use exponential backoff for retry strategies" + - "Log failed requests with sufficient context for debugging" + + +caching_strategies: + description: "Caching strategies and implementation patterns in userver" + core_concepts: + - "Cache Types - Different cache types (in-memory, Redis, etc.) for different use cases" + - "Cache Invalidation - Strategies for cache invalidation (TTL, explicit invalidation)" + - "Cache-Aside Pattern - Load data on cache miss and store in cache for future requests" + - "Write-Through/Write-Behind - Update cache when updating data store" + implementation_guidelines: + - "Use cache::CacheContainer for managing cache instances" + - "Implement proper cache key design for efficient lookups" + - "Handle cache errors gracefully without affecting core functionality" + - "Monitor cache hit/miss ratios to optimize performance" + performance_considerations: + - "Set appropriate TTL values based on data volatility" + - "Use cache warming strategies for frequently accessed data" + - "Implement circuit breaker patterns for external cache dependencies" + - "Consider cache sharding for large datasets" + cache_components: + - "cache::LruCache - Least Recently Used cache implementation" + - "redis::Client - Redis client for distributed caching" + - "cache::CacheContainer - Container for managing cache instances" + - "cache::UpdateType - Cache update strategies (Full, Incremental)" + + +middleware_development: + description: "Guidelines for developing middleware components in userver" + core_concepts: + - "Request/Response Interception - Middleware can intercept and modify requests and responses" + - "Chaining - Middleware components are chained together to form a processing pipeline" + - "Order Matters - Middleware execution order affects behavior and must be carefully considered" + - "Non-blocking - Middleware must be non-blocking and coroutine-safe" + implementation_guidelines: + - "Inherit from server::http::HandlerBase or appropriate base class" + - "Implement HandleRequest method for custom logic" + - "Call next middleware in chain using call_next parameter" + - "Handle exceptions gracefully and provide meaningful error responses" + common_patterns: + - "Authentication Middleware - Validate and extract user credentials" + - "Logging Middleware - Log request/response information for monitoring" + - "Rate Limiting Middleware - Control request rate to prevent abuse" + - "CORS Middleware - Handle Cross-Origin Resource Sharing headers" + performance_considerations: + - "Minimize overhead in middleware to avoid performance bottlenecks" + - "Use caching when appropriate to avoid redundant computations" + - "Avoid blocking operations in middleware implementation" + - "Consider async patterns for I/O operations in middleware" + + +error_handling_logging: + description: "Error handling and logging patterns in userver" + core_concepts: + - "Exception Safety - Use RAII and exception-safe coding practices" + - "Structured Logging - Use structured logging with key-value pairs for better searchability" + - "Error Propagation - Propagate errors appropriately through the call stack" + - "Graceful Degradation - Implement fallback mechanisms for non-critical failures" + implementation_guidelines: + - "Use logging::LogExtra for adding contextual information to log messages" + - "Implement custom exception types for different error categories" + - "Log at appropriate levels (trace, debug, info, warning, error, critical)" + - "Include request IDs in log messages for request tracing" + logging_patterns: + - "Request Logging - Log incoming requests and outgoing responses" + - "Error Logging - Log errors with sufficient context for debugging" + - "Performance Logging - Log performance metrics and bottlenecks" + - "Security Logging - Log security-related events and anomalies" + error_handling_patterns: + - "Retry Strategies - Implement appropriate retry mechanisms for transient failures" + - "Circuit Breakers - Use circuit breakers to prevent cascading failures" + - "Fallback Responses - Provide fallback responses for non-critical failures" + - "Error Boundaries - Isolate errors to prevent system-wide failures" + + +security_best_practices: + description: "Security best practices for userver applications" + authentication_authorization: + - "Use secure authentication mechanisms (OAuth2, JWT, API keys)" + - "Implement proper session management and token expiration" + - "Validate and sanitize all input to prevent injection attacks" + - "Implement role-based access control (RBAC) for authorization" + data_protection: + - "Encrypt sensitive data at rest and in transit" + - "Use secure key management practices" + - "Implement proper data retention and deletion policies" + - "Mask sensitive data in logs and error messages" + secure_coding: + - "Follow secure coding guidelines and practices" + - "Regularly update dependencies to address security vulnerabilities" + - "Implement input validation and output encoding" + - "Use secure random number generation for cryptographic operations" + network_security: + - "Use HTTPS/TLS for all external communications" + - "Implement proper firewall rules and network segmentation" + - "Use secure headers (Content-Security-Policy, X-Frame-Options, etc.)" + - "Implement rate limiting to prevent abuse and DDoS attacks" + monitoring_auditing: + - "Log security-relevant events for audit purposes" + - "Implement intrusion detection and prevention systems" + - "Regularly review and update security policies" + - "Conduct security assessments and penetration testing" + + +debugging_profiling: + description: "Debugging and profiling workflows for userver applications" + debugging_tools: + - "Use GDB for debugging C++ applications" + - "Enable debug logging for detailed tracing" + - "Use core dumps for post-mortem analysis" + - "Implement custom debug endpoints for runtime inspection" + profiling_tools: + - "Use perf for CPU profiling" + - "Use Valgrind for memory profiling" + - "Use flame graphs for visualizing performance bottlenecks" + - "Monitor heap usage with heaptrack or similar tools" + debugging_techniques: + - "Use logging with correlation IDs to trace requests" + - "Implement health check endpoints for runtime diagnostics" + - "Use conditional breakpoints for selective debugging" + - "Capture and analyze network traffic with tcpdump/wireshark" + profiling_workflows: + - "Profile during load testing to identify bottlenecks" + - "Use sampling profilers for production performance analysis" + - "Monitor resource usage with system tools (top, htop, iostat)" + - "Use tracing frameworks for distributed system debugging" + + +deployment_release: + description: "Deployment and release processes for userver applications" + build_process: + - "Use CMake for building userver applications" + - "Configure build types (Debug, Release, RelWithDebInfo) appropriately" + - "Use CI/CD pipelines for automated building and testing" + - "Implement proper versioning strategies for releases" + containerization: + - "Use Docker for containerizing userver applications" + - "Optimize container images for size and security" + - "Implement multi-stage builds for efficient images" + - "Use proper base images (e.g., Alpine for smaller footprint)" + deployment_strategies: + - "Use blue-green deployment for zero-downtime releases" + - "Implement canary deployments for risk reduction" + - "Use rolling updates for gradual deployment" + - "Implement proper rollback procedures for failed deployments" + configuration_management: + - "Use environment variables for configuration" + - "Implement dynamic configuration with dynamic_config component" + - "Use configuration files for complex settings" + - "Implement configuration validation mechanisms" + release_process: + - "Follow semantic versioning for release numbering" + - "Create release notes with detailed changes" + - "Perform smoke tests after deployment" + - "Monitor key metrics post-deployment" + + +monitoring_observability: + description: "Monitoring and observability setup for userver applications" + metrics_collection: + - "Use Prometheus metrics for application monitoring" + - "Expose metrics endpoints for scraping by monitoring systems" + - "Define custom metrics for business-specific KPIs" + - "Use histograms and summaries for latency measurements" + tracing: + - "Implement distributed tracing with OpenTelemetry or Jaeger" + - "Propagate trace context through service boundaries" + - "Add span attributes for important business context" + - "Use sampling strategies to control tracing overhead" + logging: + - "Use structured logging with JSON format for easy parsing" + - "Include correlation IDs for request tracing" + - "Log at appropriate levels (info, warn, error)" + - "Aggregate logs to centralized logging systems (ELK, etc.)" + alerting: + - "Set up alerts for critical system metrics (CPU, memory, disk)" + - "Create business-level alerts for key performance indicators" + - "Implement alert deduplication and grouping" + - "Define escalation procedures for critical alerts" + dashboards: + - "Create dashboards for system health monitoring" + - "Visualize key business metrics and trends" + - "Set up drill-down capabilities for detailed analysis" + - "Share dashboards with relevant stakeholders" + + +api_design_principles: + description: "API design principles for userver applications" + restful_design: + - "Use standard HTTP methods (GET, POST, PUT, DELETE) appropriately" + - "Design resource-based URLs that are intuitive and consistent" + - "Use appropriate HTTP status codes to indicate operation results" + - "Implement proper pagination for large collections" + versioning: + - "Use API versioning to maintain backward compatibility" + - "Include version information in URL path or headers" + - "Document breaking changes and deprecation policies" + - "Provide migration paths for API consumers" + data_consistency: + - "Use consistent naming conventions for fields and parameters" + - "Define clear data types and validation rules" + - "Implement proper error handling with meaningful messages" + - "Use standardized date/time formats (ISO 8601)" + performance_considerations: + - "Design APIs to minimize round trips" + - "Implement appropriate filtering, sorting, and field selection" + - "Use compression for large response payloads" + - "Implement caching headers for cacheable responses" + security_considerations: + - "Implement rate limiting to prevent API abuse" + - "Use authentication and authorization for protected endpoints" + - "Validate and sanitize all input parameters" + - "Implement proper CORS policies for web applications" + + +code_review_standards: + description: "Code review standards and best practices for userver applications" + review_process: + - "All code changes must be reviewed before merging" + - "Use pull requests for code review workflow" + - "Assign appropriate reviewers based on component ownership" + - "Set appropriate review priority based on change impact" + review_checklist: + - "Verify code follows project coding guidelines" + - "Check for proper error handling and logging" + - "Ensure appropriate test coverage for new functionality" + - "Validate security implications of code changes" + - "Review performance considerations and resource usage" + - "Check for proper documentation and comments" + quality_guidelines: + - "Follow the project's quality tiers (Platinum, Golden, Silver)" + - "Ensure code is maintainable and readable" + - "Verify proper component lifecycle management" + - "Check for potential race conditions and concurrency issues" + feedback_guidelines: + - "Provide constructive feedback focused on code quality" + - "Use clear and specific comments with examples when possible" + - "Distinguish between mandatory changes and suggestions" + - "Acknowledge good practices and improvements in the code" \ No newline at end of file diff --git a/ai-memory-bank/.gitkeep b/ai-memory-bank/.gitkeep new file mode 100644 index 000000000000..689752efa566 --- /dev/null +++ b/ai-memory-bank/.gitkeep @@ -0,0 +1,2 @@ +# This file is used to keep the memory-bank directory in the repository. +# It can be safely deleted if the directory contains other files. \ No newline at end of file diff --git a/ai-memory-bank/activeContext.md b/ai-memory-bank/activeContext.md new file mode 100644 index 000000000000..fae5e6e7d248 --- /dev/null +++ b/ai-memory-bank/activeContext.md @@ -0,0 +1,99 @@ +# Active Context + +## Current Work Focus + +This document tracks the current focus areas, recent changes, and active decisions for the userver framework project analysis. + +### Current Analysis Focus +- Understanding the userver framework architecture and components +- Analyzing sample services to understand implementation patterns +- Documenting key framework features and capabilities +- Creating comprehensive memory bank for future reference + +## Recent Changes + +### Framework Analysis +- Completed analysis of README.md and .roorules documentation +- Reviewed service_template structure and implementation patterns +- Examined hello_service sample for basic handler implementation +- Analyzed component-based architecture patterns + +### Memory Bank Creation +- Created projectbrief.md with framework overview +- Created productContext.md with user needs and problems solved +- Created systemPatterns.md with architecture and technical patterns +- Created techContext.md with technologies and development setup + +## Next Steps + +### Documentation Completion +1. Create progress.md to track project status +2. Create fileindex with project file hierarchy +3. Review additional sample services for implementation patterns +4. Document HTTP client usage patterns +5. Document caching strategies and implementation patterns +6. Document middleware development guidelines +7. Document error handling and logging patterns +8. Document security best practices +9. Document debugging and profiling workflows +10. Document deployment and release processes +11. Document monitoring and observability setup +12. Document API design principles +13. Document code review standards + +## Active Decisions and Considerations + +### Framework Adoption +- Userver framework provides comprehensive solution for high-performance C++ microservices +- Component-based architecture simplifies service composition +- Coroutine-based async model provides excellent performance characteristics +- Rich ecosystem of database and protocol integrations reduces development time + +### Implementation Considerations +- Learning curve for coroutine-based programming model +- Need to understand component lifecycle and configuration +- Importance of following framework patterns for optimal performance +- Integration requirements with existing systems and databases + +## Important Patterns and Preferences + +### Code Organization +- Component-based architecture with clear separation of concerns +- Configuration-driven behavior through YAML files +- Handler-based request processing with middleware support +- Modular design with dependency injection + +### Performance Optimization +- Minimize context switches through async operations +- Use connection pooling for database and HTTP clients +- Implement proper deadline propagation +- Leverage caching for frequently accessed data + +### Development Practices +- Follow component lifecycle guidelines +- Use framework-provided synchronization primitives +- Implement structured logging with contextual information +- Provide comprehensive metrics and tracing +- Write tests at multiple levels (unit, functional, integration) + +## Learnings and Project Insights + +### Key Insights +1. Userver framework abstracts away complexity of asynchronous programming +2. Component system provides modular and configurable service architecture +3. Built-in observability reduces operational overhead +4. Rich ecosystem of integrations accelerates development + +### Framework Strengths +- High performance with minimal resource usage +- Comprehensive set of database and protocol integrations +- Built-in observability and monitoring capabilities +- Flexible configuration and dynamic updates +- Strong focus on developer productivity + +### Areas for Further Exploration +- Advanced caching strategies and implementations +- Complex middleware development patterns +- Performance optimization techniques +- Integration with specific databases and protocols +- Deployment and scaling strategies \ No newline at end of file diff --git a/ai-memory-bank/comprehensive-file-index.md b/ai-memory-bank/comprehensive-file-index.md new file mode 100644 index 000000000000..3b83e989379b --- /dev/null +++ b/ai-memory-bank/comprehensive-file-index.md @@ -0,0 +1,340 @@ +# Comprehensive File Index + +## Root Directory +- .ai_system_prompt - AI system prompt configuration file +- .clang-format - Code formatting configuration for C++ code +- .clang-tidy - Static analysis configuration for C++ code +- .cmake-format.py - Configuration for formatting CMake files +- .editorconfig - Editor configuration for consistent coding styles across editors +- .gitattributes - Git attributes configuration for file handling +- .gitignore - Git ignore patterns for excluding files from version control +- .mapping.json - JSON mapping configuration file +- .piglet-meta.json - Metadata configuration for Piglet tooling +- 🛡️ .roorules - Project-specific rules and guidelines for AI agents +- AUTHORS - List of contributors and authors of the project +- CMakeLists.txt - Root CMake build configuration file +- CODE_OF_CONDUCT.md - Guidelines for community conduct and interactions +- CODEOWNERS - File defining code ownership for different parts of the project +- conanfile.py - Conan package manager configuration file +- CONTRIBUTING.md - Guidelines for contributing to the project +- LICENSE - License information for the project +- Makefile - Make build system configuration +- pyproject.toml - Python project configuration file +- pytest.ini - Configuration file for pytest testing framework +- README.md - Main project documentation and introduction +- SECURITY.md - Security policies and reporting procedures +- THIRD_PARTY.md - Information about third-party dependencies and licenses + +### GitHub Configuration (.github/) +- dependabot.yml - Configuration for automated dependency updates +- docker-compose.yml - Docker Compose configuration for development environment +- pull_request_template.md - Template for pull request descriptions +- ISSUE_TEMPLATE/ - Templates for different types of issues +- workflows/ - GitHub Actions workflow definitions + +## Core Framework (core/) +The core framework provides the foundation components for building high-performance C++ services with asynchronous I/O and coroutine support. + +### Core Components +- benchmarks/ - Performance benchmarking tools and tests +- build_config.hpp.in - Build configuration template file +- CMakeLists.txt - CMake build configuration for core framework +- dynamic_configs/ - Dynamic configuration management system +- functional_tests/ - Functional tests for core framework components +- include/ - Public header files for core framework components +- internal/ - Internal implementation details not exposed in public API +- library.yaml - Library configuration file +- libc_include_fixes/ - Fixes for standard library includes +- README.md - Core framework documentation +- src/ - Source code implementation of core framework components +- static_configs/ - Static configuration files +- sys_coro/ - System coroutine implementation +- uboost_coro/ - Boost coroutine integration +- utest/ - Unit testing framework and utilities + +### Core Subdirectories +#### alerts/ +Framework for handling alert notifications and monitoring +- source.hpp - Alert source interface + +#### baggage/ +Distributed tracing baggage propagation implementation +- baggage_manager.hpp - Baggage manager implementation +- baggage.hpp - Baggage data structure +- fwd.hpp - Forward declarations for baggage components + +#### cache/ +Caching framework for in-memory and external cache solutions +- cache_config.hpp - Cache configuration structures +- cache_statistics.hpp - Cache statistics tracking +- caching_component_base.hpp - Base class for caching components +- expirable_lru_cache.hpp - LRU cache with expiration support +- lru_cache_component_base.hpp - Base class for LRU cache components +- lru_cache_config.hpp - LRU cache configuration +- lru_cache_statistics.hpp - LRU cache statistics +- nway_lru_cache.hpp - N-way LRU cache implementation +- update_type.hpp - Cache update type definitions + +#### clients/ +HTTP and other client implementations for external service communication + +##### clients/dns/ +DNS client implementation +- component.hpp - DNS client component +- resolver.hpp - DNS resolver implementation + +##### clients/http/ +HTTP client implementation +- client.hpp - HTTP client interface +- component.hpp - HTTP client component +- request.hpp - HTTP request representation +- response.hpp - HTTP response representation +- plugins/ - HTTP client plugins for additional functionality + +#### components/ +Component system for modular service architecture with lifecycle management +- component_base.hpp - Base class for all components +- component_list.hpp - Component list management +- run.hpp - Service startup and shutdown functions + +#### concurrent/ +Concurrency primitives and utilities for thread-safe operations + +#### congestion_control/ +Network congestion control mechanisms +- component.hpp - Congestion control component +- controller.hpp - Congestion controller interface +- limiter.hpp - Request rate limiter +- sensor.hpp - Congestion monitoring sensor + +#### dist_lock/ +Distributed locking implementation for coordination between services + +#### dump/ +Data dump and restore functionality for caching components +- config.hpp - Dump configuration structures +- dumper.hpp - Data dumper interface +- operations.hpp - Dump operations + +#### dynamic_config/ +Dynamic configuration system for runtime configuration changes +- snapshot.hpp - Configuration snapshot +- source.hpp - Configuration source +- value.hpp - Typed configuration value wrapper + +#### engine/ +Coroutine-based engine for asynchronous I/O operations +- async.hpp - Asynchronous task execution +- task.hpp - Task management +- mutex.hpp - Coroutine-aware mutex +- condition_variable.hpp - Coroutine-aware condition variable + +#### fs/ +File system operations and utilities + +#### logging/ +Structured logging framework with multiple output options + +#### middlewares/ +Middleware components for request/response processing +- pipeline.hpp - Middleware pipeline implementation +- runner.hpp - Middleware execution runner + +#### net/ +Networking utilities and implementations + +#### os_signals/ +Operating system signal handling +- component.hpp - OS signals handling component +- processor.hpp - Signal processor implementation + +#### rcu/ +Read-Copy-Update (RCU) synchronization mechanism +- rcu.hpp - RCU implementation +- rcu_map.hpp - RCU-protected map data structure + +#### server/ +HTTP server implementation and related components + +#### storages/ +Storage abstractions for various database systems + +#### tracing/ +Distributed tracing implementation + +#### utils/ +General utility functions and classes + +## Code Generation Components + +### Chaotic (chaotic/) +Code generation framework for data structures and serialization + +#### Chaotic Directories +- bin/ - Executable scripts for code generation +- bin-dynamic-configs/ - Dynamic configuration generation scripts +- chaotic/ - Core chaotic implementation +- golden_tests/ - Reference tests for generated code +- include/ - Public header files for chaotic components +- integration_tests/ - Integration tests for chaotic components +- mypy/ - Python type checking configuration +- src/ - Source code implementation +- tests/ - Unit tests for chaotic components + +### Chaotic OpenAPI (chaotic-openapi/) +OpenAPI-based code generation for client and server implementations + +#### Chaotic OpenAPI Directories +- bin/ - Executable scripts for OpenAPI code generation +- chaotic_openapi/ - Core OpenAPI implementation +- golden_tests/ - Reference tests for generated OpenAPI code +- include/ - Public header files for OpenAPI components +- integration_tests/ - Integration tests for OpenAPI components +- mypy/ - Python type checking configuration +- src/ - Source code implementation +- tests/ - Unit tests for OpenAPI components + +## Database Components + +### ClickHouse (clickhouse/) +ClickHouse database driver and components for analytics workloads + +### MongoDB (mongo/) +MongoDB database driver and components for document-based storage + +### MySQL (mysql/) +MySQL database driver and components for relational data storage + +### PostgreSQL (postgresql/) +PostgreSQL database driver and components for relational data storage + +### Redis/Valkey (redis/) +Redis/Valkey database driver and components for in-memory data storage + +### RocksDB (rocks/) +RocksDB key-value storage driver and components +- CMakeLists.txt - CMake build configuration for RocksDB component +- library.yaml - Library configuration file +- include/ - Public header files for RocksDB components +- src/ - Source code implementation for RocksDB components + +### SQLite (sqlite/) +SQLite database driver and components for embedded relational storage + +### YDB (ydb/) +YDB (Yandex Database) driver and components for distributed storage + +## Communication Components + +### gRPC (grpc/) +gRPC communication framework for high-performance RPC calls + +### Kafka (kafka/) +Kafka messaging system integration for event streaming + +### RabbitMQ (rabbitmq/) +RabbitMQ messaging system integration for message queuing + +## Other Components + +### ODBC (odbc/) +ODBC database connectivity layer + +### OpenTelemetry (otlp/) +OpenTelemetry protocol implementation for distributed tracing and metrics + +## Development Support + +### CMake (cmake/) +CMake build system files and configurations for building userver applications + +### Libraries (libraries/) +Additional libraries and dependencies + +### Scripts (scripts/) +Development scripts and tools for various tasks + +### Testsuite (testsuite/) +Testing framework and utilities for functional and integration testing + +### Third Party (third_party/) +Third-party dependencies and libraries + +### Universal (universal/) +Universal components that work across different systems + +## Sample Services (samples/) +Example services demonstrating how to use various components of the userver framework + +### Sample Services List +- chaotic_openapi_service/ - Service using OpenAPI code generation +- chaotic_service/ - Service using chaotic code generation +- clickhouse_service/ - Service using ClickHouse database +- config_service/ - Service demonstrating configuration management +- digest_auth_service/ - Service with digest authentication +- dns-resolver/ - Service demonstrating DNS resolution +- embedded_files/ - Service with embedded files +- flatbuf_service/ - Service using FlatBuffers serialization +- grpc_middleware_service/ - Service with gRPC middleware +- grpc_service/ - Service using gRPC communication +- grpc-generic-proxy/ - Generic gRPC proxy service +- hello_service/ - Basic hello world service example +- http_caching/ - Service demonstrating HTTP caching +- http_middleware_service/ - Service with HTTP middleware +- http-client-perf/ - HTTP client performance testing service +- https_service/ - Service with HTTPS support +- json2yaml/ - Service for converting JSON to YAML +- kafka_service/ - Service using Kafka messaging +- mongo_service/ - Service using MongoDB database +- mongo-support/ - MongoDB support utilities +- multipart_service/ - Service handling multipart requests +- mysql_service/ - Service using MySQL database +- netcat/ - Network utility service +- otlp_service/ - Service using OpenTelemetry protocol +- postgres_auth/ - Service with PostgreSQL authentication +- postgres_cache_order_by/ - Service with PostgreSQL caching +- postgres_service/ - Service using PostgreSQL database +- postgres-support/ - PostgreSQL support utilities +- production_service/ - Example production-ready service +- rabbitmq_service/ - Service using RabbitMQ messaging +- redis_service/ - Service using Redis database +- s3api/ - Service with S3 API integration +- static_service/ - Service serving static files +- tcp_full_duplex_service/ - Full-duplex TCP service +- tcp_service/ - TCP-based service +- testsuite-support/ - Testsuite support utilities +- websocket_service/ - Service with WebSocket support +- ydb_service/ - Service using YDB database + +## Service Template (service_template/) +Template for creating new services with standard structure and configuration + +### Service Template Components +- .clang-format - Code formatting configuration +- .gitignore - Git ignore patterns +- CMakeLists.txt - CMake build configuration +- CMakePresets.json - CMake presets configuration +- Makefile - Make build system configuration +- README.md - Service documentation +- requirements.txt - Python requirements +- run_as_user.sh - Script for running service as specific user +- .devcontainer/ - Development container configuration +- .github/ - GitHub workflow configurations +- cmake/ - CMake modules and configurations +- configs/ - Configuration files +- postgresql/ - PostgreSQL schema files +- proto/ - Protocol buffer definitions +- src/ - Source code implementation +- tests/ - Test files + +## Memory Bank (memory-bank/) +Project-specific documentation and context files for AI agents + +### Memory Bank Files +- projectbrief.md - Foundation document defining core requirements and goals +- productContext.md - Product context including problems solved and user experience goals +- systemPatterns.md - System architecture and technical decisions +- techContext.md - Technology context including development setup and dependencies +- activeContext.md - Current work focus, recent changes, and next steps +- progress.md - Current status, completed work, and known issues +- comprehensive-file-index.md - Detailed file index with descriptions (this document) \ No newline at end of file diff --git a/ai-memory-bank/productContext.md b/ai-memory-bank/productContext.md new file mode 100644 index 000000000000..33c0064af5d3 --- /dev/null +++ b/ai-memory-bank/productContext.md @@ -0,0 +1,64 @@ +# Product Context + +## Problem Statement + +Traditional C++ server development faces several challenges: + +1. **Complexity of Asynchronous Programming**: Writing efficient asynchronous code requires deep understanding of threading, synchronization, and non-blocking I/O patterns. + +2. **Context Switching Overhead**: Traditional threaded approaches suffer from significant overhead due to OS context switches, especially under high load. + +3. **Resource Utilization**: Inefficient use of CPU and memory resources due to blocking operations and thread management overhead. + +4. **Integration Complexity**: Integrating with multiple databases, messaging systems, and external services requires significant boilerplate code. + +5. **Configuration Management**: Dynamically changing service configurations without restarts is challenging in traditional C++ applications. + +6. **Monitoring and Observability**: Implementing comprehensive logging, tracing, and metrics collection is time-consuming. + +## User Needs + +The userver framework addresses these problems by providing: + +### Performance Needs +- **High Throughput**: Handle thousands of concurrent requests with minimal resource usage +- **Low Latency**: Minimize response times through efficient I/O handling +- **Resource Efficiency**: Optimize CPU and memory usage with small thread pools + +### Development Needs +- **Simplified Asynchronous Programming**: Abstract away complexity of coroutine-based asynchronous operations +- **Component-Based Architecture**: Modular design for easy service composition +- **Database Integration**: Native drivers for popular databases with async support +- **Protocol Support**: Built-in support for HTTP, gRPC, Kafka, Redis, and other protocols +- **Configuration Management**: Dynamic configuration updates without service restarts + +### Operational Needs +- **Observability**: Built-in metrics, logging, and tracing capabilities +- **Health Monitoring**: Service health checks and diagnostics +- **Deployment Flexibility**: Support for containerized deployments and cloud environments +- **Scalability**: Horizontal and vertical scaling capabilities + +## Solution Approach + +The userver framework provides a comprehensive solution through: + +1. **Coroutine-Based Architecture**: Uses coroutines to handle asynchronous operations without blocking threads +2. **Component System**: Modular architecture with lifecycle management for service components +3. **Rich Ecosystem**: Native integrations with databases, messaging systems, and protocols +4. **Built-in Observability**: Automatic metrics collection, structured logging, and distributed tracing +5. **Dynamic Configuration**: Runtime configuration updates without service restarts +6. **Developer Productivity**: Code generation tools and templates for rapid service development + +## Target Users + +1. **C++ Developers** building high-performance microservices +2. **System Architects** designing scalable distributed systems +3. **DevOps Engineers** managing containerized applications +4. **Performance Engineers** optimizing service throughput and latency + +## Success Metrics + +- Reduced development time for new services +- Improved resource utilization compared to traditional approaches +- Lower operational overhead through built-in observability +- Higher developer satisfaction through simplified async programming \ No newline at end of file diff --git a/ai-memory-bank/projectbrief.md b/ai-memory-bank/projectbrief.md new file mode 100644 index 000000000000..b388fd1085ae --- /dev/null +++ b/ai-memory-bank/projectbrief.md @@ -0,0 +1,29 @@ +# userver Framework Project Brief + +## Project Overview + +**userver** is an open source asynchronous framework with a rich set of abstractions for fast and comfortable creation of C++ microservices, services and utilities. + +The framework solves the problem of efficient I/O interactions transparently for developers. Operations that would typically suspend the thread of execution do not suspend it. Instead, the thread processes other requests and tasks and returns to the handling of the operation only when it is guaranteed to execute immediately. + +This approach results in straightforward source code, avoids CPU-consuming context switches from OS, and efficiently utilizes the CPU with a small amount of execution threads. + +## Key Features + +- Efficient asynchronous drivers for databases (MongoDB, PostgreSQL, Redis/Valkey, ClickHouse, MySQL/MariaDB, YDB, SQLite) and data transfer protocols (HTTP/{1.1, 2.0}, gRPC, AMQP 0-9-1, Kafka, TCP, TLS, WebSocket) +- Rich set of high-level components for caches, tasks, distributed locking, logging, tracing, statistics, metrics, JSON/YAML/BSON +- Functionality to change the service configuration on-the-fly +- On-the-fly configurable drivers, options of the deadline propagation, timeouts, congestion-control +- Comprehensive set of asynchronous low-level synchronization primitives and OS abstractions + +## Purpose + +The userver framework is designed to help developers create high-performance C++ microservices and applications with minimal effort. It abstracts away the complexity of asynchronous programming while providing excellent performance characteristics. + +## Target Use Cases + +- High-performance microservices +- Real-time data processing systems +- API gateways and service meshes +- Distributed systems requiring efficient I/O handling +- Applications requiring integration with multiple databases and messaging systems \ No newline at end of file diff --git a/ai-memory-bank/systemPatterns.md b/ai-memory-bank/systemPatterns.md new file mode 100644 index 000000000000..f7f987d940c3 --- /dev/null +++ b/ai-memory-bank/systemPatterns.md @@ -0,0 +1,147 @@ +# System Patterns + +## Architecture Overview + +The userver framework follows a component-based architecture with coroutine-driven asynchronous processing. The core concepts include: + +### Component System +- **Modular Design**: Services are composed of components that can be assembled as needed +- **Lifecycle Management**: Components have well-defined initialization and cleanup phases +- **Dependency Injection**: Components can depend on other components through configuration +- **Configuration-Driven**: Component behavior is controlled through configuration files + +### Asynchronous Processing Model +- **Coroutine-Based**: Uses coroutines for non-blocking operations +- **Deadline Propagation**: Request deadlines are automatically propagated through the system +- **Cancellation Support**: Long-running operations can be cancelled when deadlines are exceeded +- **Thread Pool Optimization**: Small number of threads handle many concurrent operations + +### HTTP Server Architecture +- **Request Handling Pipeline**: Middleware and handlers process requests in a chain +- **Non-Blocking I/O**: All HTTP operations are asynchronous +- **Connection Management**: Efficient connection pooling for both server and client operations +- **Protocol Support**: HTTP/1.1, HTTP/2, and WebSocket support + +## Key Technical Patterns + +### 1. Component Pattern +```cpp +class MyHandler : public server::handlers::HttpHandlerBase { +public: + static constexpr std::string_view kName = "handler-my-service"; + using HttpHandlerBase::HttpHandlerBase; + + std::string HandleRequest(server::http::HttpRequest& request, + server::request::RequestContext&) const override; +}; +``` + +Components are the building blocks of userver services: +- Each component has a unique name used in configuration +- Components inherit from base classes that provide common functionality +- Components are registered in the component list at startup + +### 2. Configuration Pattern +- **Static Configuration**: YAML files defining component configurations +- **Dynamic Configuration**: Runtime-configurable parameters that can be updated without restart +- **Environment Integration**: Configuration values can come from files, environment variables, or remote sources + +### 3. Database Integration Patterns +- **Connection Pooling**: Database connections are pooled for efficiency +- **Prepared Statements**: SQL queries are prepared for performance +- **Transaction Management**: Automatic transaction handling with rollback support +- **Async Operations**: All database operations are non-blocking + +### 4. Caching Patterns +- **Multiple Cache Types**: In-memory, Redis, and other cache implementations +- **Cache-Aside Pattern**: Load data on cache miss and store for future requests +- **TTL Management**: Automatic cache expiration based on time-to-live settings +- **Cache Warming**: Pre-populate caches with frequently accessed data + +### 5. Middleware Pattern +- **Request/Response Interception**: Middleware can modify requests and responses +- **Chaining**: Multiple middleware components can be chained together +- **Order Matters**: Middleware execution order affects behavior +- **Non-blocking**: All middleware must be coroutine-safe + +### 6. Error Handling Pattern +- **Structured Exceptions**: Custom exception types for different error categories +- **Graceful Degradation**: Services continue operating when non-critical components fail +- **Circuit Breakers**: Prevent cascading failures in distributed systems +- **Retry Logic**: Automatic retry with exponential backoff for transient failures + +## Core Framework Components + +### HTTP Server Components +- `server::handlers::HttpHandlerBase`: Base class for HTTP handlers +- `server::http::HttpRequest`: HTTP request object +- `server::http::HttpResponse`: HTTP response object + +### Database Components +- `storages::postgres::Cluster`: PostgreSQL cluster management +- `storages::redis::Client`: Redis client implementation +- `storages::mongo::Pool`: MongoDB connection pool + +### Utility Components +- `logging::Log`: Structured logging system +- `metrics::Metric`: Metrics collection and reporting +- `tracing::Span`: Distributed tracing implementation +- `cache::CacheContainer`: Cache management + +## Design Principles + +### 1. Coroutine Safety +All I/O operations must be asynchronous and non-blocking: +```cpp +// Correct - async database operation +auto result = db.Execute("SELECT * FROM users WHERE id=$1", user_id); + +// Incorrect - blocking operation that would suspend thread +std::this_thread::sleep_for(1s); +``` + +### 2. Exception Safety +Use RAII and exception-safe coding practices: +```cpp +// Correct - automatic resource management +auto connection = db.Acquire(); +auto result = connection.Execute("SELECT * FROM users"); + +// Resources automatically released when connection goes out of scope +``` + +### 3. Configuration-Driven Design +Behavior should be configurable without code changes: +```yaml +# Configuration in YAML +components: + handler-my-service: + type: handler-my-service + task_processor: main-task-processor + listen_path: /api/v1/users +``` + +### 4. Observability-First Approach +All components should provide metrics and logging: +```cpp +// Built-in metrics collection +statistics_->GetCounter("requests")->Increment(); +statistics_->GetHistogram("request-time")->Record(request_time); +``` + +## Performance Patterns + +### 1. Minimize Context Switches +- Use asynchronous operations to reduce OS context switches +- Optimize memory and CPU usage +- Implement proper deadline handling for requests + +### 2. Efficient Resource Usage +- Connection pooling for database and HTTP clients +- Memory pooling for frequently allocated objects +- Lazy initialization of expensive resources + +### 3. Deadline Propagation +- HTTP client requests inherit deadlines from incoming requests +- Configure appropriate timeouts based on service level objectives +- Implement circuit breaker patterns for handling flaky external dependencies \ No newline at end of file diff --git a/ai-memory-bank/techContext.md b/ai-memory-bank/techContext.md new file mode 100644 index 000000000000..1c0ad4be33b4 --- /dev/null +++ b/ai-memory-bank/techContext.md @@ -0,0 +1,172 @@ +# Technology Context + +## Core Technologies + +### Programming Language +- **C++17/20**: Primary language for framework and service implementation +- **Coroutines**: Leveraged for asynchronous programming model +- **STL**: Standard Template Library for common data structures and algorithms + +### Build System +- **CMake**: Primary build system with comprehensive configuration +- **Makefile**: Simplified build interface for common operations +- **Conan**: Package manager for dependency management +- **CMakePresets.json**: Standardized build configurations + +### Dependencies +- **Boost**: Utility libraries for system operations +- **fmt**: Modern formatting library +- **spdlog**: Fast logging library +- **OpenSSL**: Cryptographic operations and TLS support +- **libcurl**: HTTP client operations +- **Protocol Buffers**: Serialization for gRPC and other protocols +- **RapidJSON**: JSON parsing and generation +- **yaml-cpp**: YAML parsing and generation +- **Prometheus Client**: Metrics collection and exposition + +## Database Technologies + +### Supported Databases +- **PostgreSQL**: Primary relational database with async driver +- **MongoDB**: Document database with async driver +- **Redis/Valkey**: In-memory data structure store +- **ClickHouse**: Column-oriented database for analytics +- **MySQL/MariaDB**: Alternative relational database +- **YDB**: Distributed database system +- **SQLite**: Embedded database for local storage + +### Database Patterns +- **Connection Pooling**: Efficient reuse of database connections +- **Prepared Statements**: Optimized query execution +- **Transaction Management**: ACID-compliant transaction support +- **Async Operations**: Non-blocking database interactions + +## Communication Technologies + +### HTTP Stack +- **HTTP/1.1**: Standard web protocol support +- **HTTP/2**: Modern protocol with multiplexing support +- **WebSocket**: Bidirectional communication protocol +- **HTTPS/TLS**: Secure communication support + +### RPC Frameworks +- **gRPC**: High-performance RPC framework with protobuf +- **Generic HTTP Clients**: RESTful API integration + +### Messaging Systems +- **Kafka**: Distributed streaming platform +- **RabbitMQ**: Message broker with AMQP support +- **TCP/UDP**: Low-level network communication + +## Development Tools + +### Testing Frameworks +- **GTest**: Unit testing framework +- **pytest**: Python-based functional testing +- **Google Benchmark**: Performance benchmarking +- **Chaos Testing**: Built-in fault injection framework + +### Code Generation +- **Chaotic**: Data structure code generation from schemas +- **Chaotic OpenAPI**: Client and server code generation from OpenAPI specifications +- **Protocol Buffers**: Code generation for gRPC services + +### Development Environment +- **Dev Containers**: Standardized development environments +- **Docker**: Containerization for consistent deployments +- **CI/CD**: Automated testing and deployment pipelines + +## Observability Stack + +### Logging +- **Structured Logging**: JSON-formatted log entries +- **Log Levels**: Trace, debug, info, warning, error, critical +- **Contextual Information**: Correlation IDs and request context + +### Metrics +- **Prometheus**: Metrics collection and storage +- **Custom Metrics**: Business-specific KPI tracking +- **Histograms/Summaries**: Latency and distribution metrics + +### Tracing +- **OpenTelemetry/Jaeger**: Distributed tracing implementation +- **Span Context**: Request flow tracking across services +- **Trace Attributes**: Business context in traces + +## Development Setup + +### Prerequisites +1. **C++ Compiler**: GCC 9+ or Clang 10+ +2. **CMake**: 3.15+ +3. **Python**: 3.8+ for build scripts and testing +4. **Conan**: For dependency management +5. **Docker**: For containerized development (optional) + +### Build Process +```bash +# Clone repository +git clone https://github.com/userver-framework/userver.git + +# Create build directory +mkdir build +cd build + +# Configure with CMake +cmake .. -DCMAKE_BUILD_TYPE=Release + +# Build +make -j$(nproc) + +# Run tests +ctest +``` + +### Service Template +The `service_template/` directory provides a starting point for new services: +- Pre-configured CMakeLists.txt +- Sample configuration files +- Basic handler implementation +- Testing setup with pytest and GTest + +### Development Workflow +1. **Create Service**: Copy and customize service_template +2. **Implement Handlers**: Add business logic to handler components +3. **Configure Components**: Update YAML configuration files +4. **Add Tests**: Implement unit and functional tests +5. **Build and Deploy**: Compile and deploy service + +## Quality Assurance + +### Code Review Process +- **Pull Requests**: All changes require review +- **Component Ownership**: Assign reviewers based on component expertise +- **Quality Tiers**: Platinum, Golden, and Silver quality standards + +### Testing Strategies +- **Unit Tests**: Component-level testing with GTest +- **Functional Tests**: Service-level testing with pytest +- **Integration Tests**: Multi-component testing scenarios +- **Performance Tests**: Load and stress testing with benchmarks +- **Chaos Tests**: Fault injection and resilience testing + +### Static Analysis +- **Clang-Tidy**: Static code analysis +- **Clang-Format**: Code formatting enforcement +- **Compiler Warnings**: Strict warning levels for code quality + +## Deployment Options + +### Containerization +- **Docker Images**: Pre-built images for all components +- **Multi-stage Builds**: Efficient image construction +- **Base Images**: Alpine Linux for minimal footprint + +### Orchestration +- **Kubernetes**: Container orchestration support +- **Service Discovery**: Automatic service registration +- **Load Balancing**: Traffic distribution across instances + +### Configuration Management +- **Environment Variables**: Runtime configuration +- **Configuration Files**: YAML-based configuration +- **Dynamic Configuration**: Runtime updates without restarts \ No newline at end of file From 28cd65262de2acfb1bcf01377b0ea4d44ca16aab Mon Sep 17 00:00:00 2001 From: rexarrior Date: Mon, 4 Aug 2025 13:54:27 +0000 Subject: [PATCH 002/230] update development settings --- ai-development-settings/extreme/.gitkeep | 0 .../minimalistic/.ai_system_prompt | 125 ++++++++++++ .../minimalistic/.ai_system_prompt_new.md | 125 ++++++++++++ ai-development-settings/minimalistic/.gitkeep | 0 .../minimalistic/.roorules | 186 ++++++++++++++++++ 5 files changed, 436 insertions(+) create mode 100644 ai-development-settings/extreme/.gitkeep create mode 100644 ai-development-settings/minimalistic/.ai_system_prompt create mode 100644 ai-development-settings/minimalistic/.ai_system_prompt_new.md create mode 100644 ai-development-settings/minimalistic/.gitkeep create mode 100644 ai-development-settings/minimalistic/.roorules diff --git a/ai-development-settings/extreme/.gitkeep b/ai-development-settings/extreme/.gitkeep new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/ai-development-settings/minimalistic/.ai_system_prompt b/ai-development-settings/minimalistic/.ai_system_prompt new file mode 100644 index 000000000000..690fb85c181a --- /dev/null +++ b/ai-development-settings/minimalistic/.ai_system_prompt @@ -0,0 +1,125 @@ +# AI Agent System Prompt for userver Service Development + +I am an expert C++ software engineer specializing in developing services using the userver framework. My purpose is to help create high-performance, scalable services that leverage the full power of the userver framework's component-based architecture and asynchronous capabilities. + +## Core Principles + +### Service Development Focus +- I develop services that use the userver framework, not the framework itself +- I focus on implementing business logic in handlers and components +- I use existing framework components rather than creating new ones +- I follow service development patterns and best practices + +### Component-Based Architecture +- Services are composed of components registered in main.cpp +- Components have well-defined lifecycles (Constructor → Start → Stop → Destructor) +- Components are configured through static_config.yaml +- Dependencies between components are declared explicitly + +### Asynchronous Programming Model +- All I/O operations use userver's asynchronous drivers +- Operations are non-blocking and coroutine-safe +- Deadline propagation ensures responsive service behavior +- Cancellation support handles long-running operations gracefully + +## Service Development Workflow + +### 1. Service Creation +- Start with the service_template/ as a base +- Customize CMakeLists.txt for project-specific dependencies +- Implement handlers in src/ directory following established patterns +- Configure components in configs/static_config.yaml + +### 2. Handler Implementation +- Inherit from userver::server::handlers::HttpHandlerBase +- Use kName constant for component registration +- Implement HandleRequestThrow for exception-based error handling +- Extract request parameters with request.GetArg("name") +- Set response headers and content type appropriately + +### 3. Component Registration +- Register components in main.cpp using MinimalServerComponentList() +- Append standard components like Ping, HttpClient, DnsClient +- Add custom handlers and components as needed +- Use component names that match static_config.yaml + +### 4. Configuration Management +- Configure task processors for CPU-bound and filesystem-bound operations +- Map handlers to URLs in static_config.yaml +- Set up database connections and other external dependencies +- Use environment variables for deployment-specific settings + +## Key Implementation Patterns + +### HTTP Handler Pattern +Refer to .roorules for detailed implementation patterns. + +### Request Processing +Refer to .roorules for detailed request processing techniques. + +### Error Handling +Refer to .roorules for detailed error handling approaches. + +## Service-Specific Components + +### Core Components +Refer to .roorules for a complete list of available components. + +### Database Components +Refer to .roorules for database component options. + +### Optional Components +Refer to .roorules for optional component options. + +## Best Practices + +### Performance Optimization +- Use asynchronous operations to minimize context switches +- Implement connection pooling for database and HTTP clients +- Apply deadline propagation to all downstream requests +- Use caching for frequently accessed data + +### Reliability Patterns +- Implement circuit breaker patterns for external dependencies +- Use proper retry strategies with exponential backoff +- Handle different HTTP status codes appropriately +- Implement graceful degradation for non-critical failures + +### Development Practices +- Follow component lifecycle guidelines for initialization and cleanup +- Use framework-provided synchronization primitives +- Implement structured logging with contextual information +- Write tests at multiple levels (unit, functional, integration) + +## Available Resources + +### Userver framework documentation +- Repository https://github.com/userver-framework/userver +- Site with documentation: https://userver.tech/de/d6a/md_en_2index.html + +### Documentation +- userver/samples: Example services demonstrating various features +- userver/service_template: Template for creating new services +- userver/ai-memory-bank: Memory bank with framework patterns and context + +### Development Environment +- CMake for build configuration +- GTest for unit testing +- pytest with testsuite for functional testing +- Google Benchmark for performance testing + +## Quality Standards + +### Code Quality +- Follow userver coding guidelines and patterns +- Use RAII and exception-safe coding practices +- Implement proper memory management with smart pointers +- Maintain consistent code formatting + +### Testing Requirements +- Unit tests for core business logic +- Functional tests for service endpoints +- Integration tests for database and external service interactions +- Performance benchmarks for critical operations + +This system prompt provides the foundation for developing high-quality services on the userver framework while maintaining consistency with established patterns and best practices. For detailed implementation instructions, refer to the .roorules file. \ No newline at end of file diff --git a/ai-development-settings/minimalistic/.ai_system_prompt_new.md b/ai-development-settings/minimalistic/.ai_system_prompt_new.md new file mode 100644 index 000000000000..690fb85c181a --- /dev/null +++ b/ai-development-settings/minimalistic/.ai_system_prompt_new.md @@ -0,0 +1,125 @@ +# AI Agent System Prompt for userver Service Development + +I am an expert C++ software engineer specializing in developing services using the userver framework. My purpose is to help create high-performance, scalable services that leverage the full power of the userver framework's component-based architecture and asynchronous capabilities. + +## Core Principles + +### Service Development Focus +- I develop services that use the userver framework, not the framework itself +- I focus on implementing business logic in handlers and components +- I use existing framework components rather than creating new ones +- I follow service development patterns and best practices + +### Component-Based Architecture +- Services are composed of components registered in main.cpp +- Components have well-defined lifecycles (Constructor → Start → Stop → Destructor) +- Components are configured through static_config.yaml +- Dependencies between components are declared explicitly + +### Asynchronous Programming Model +- All I/O operations use userver's asynchronous drivers +- Operations are non-blocking and coroutine-safe +- Deadline propagation ensures responsive service behavior +- Cancellation support handles long-running operations gracefully + +## Service Development Workflow + +### 1. Service Creation +- Start with the service_template/ as a base +- Customize CMakeLists.txt for project-specific dependencies +- Implement handlers in src/ directory following established patterns +- Configure components in configs/static_config.yaml + +### 2. Handler Implementation +- Inherit from userver::server::handlers::HttpHandlerBase +- Use kName constant for component registration +- Implement HandleRequestThrow for exception-based error handling +- Extract request parameters with request.GetArg("name") +- Set response headers and content type appropriately + +### 3. Component Registration +- Register components in main.cpp using MinimalServerComponentList() +- Append standard components like Ping, HttpClient, DnsClient +- Add custom handlers and components as needed +- Use component names that match static_config.yaml + +### 4. Configuration Management +- Configure task processors for CPU-bound and filesystem-bound operations +- Map handlers to URLs in static_config.yaml +- Set up database connections and other external dependencies +- Use environment variables for deployment-specific settings + +## Key Implementation Patterns + +### HTTP Handler Pattern +Refer to .roorules for detailed implementation patterns. + +### Request Processing +Refer to .roorules for detailed request processing techniques. + +### Error Handling +Refer to .roorules for detailed error handling approaches. + +## Service-Specific Components + +### Core Components +Refer to .roorules for a complete list of available components. + +### Database Components +Refer to .roorules for database component options. + +### Optional Components +Refer to .roorules for optional component options. + +## Best Practices + +### Performance Optimization +- Use asynchronous operations to minimize context switches +- Implement connection pooling for database and HTTP clients +- Apply deadline propagation to all downstream requests +- Use caching for frequently accessed data + +### Reliability Patterns +- Implement circuit breaker patterns for external dependencies +- Use proper retry strategies with exponential backoff +- Handle different HTTP status codes appropriately +- Implement graceful degradation for non-critical failures + +### Development Practices +- Follow component lifecycle guidelines for initialization and cleanup +- Use framework-provided synchronization primitives +- Implement structured logging with contextual information +- Write tests at multiple levels (unit, functional, integration) + +## Available Resources + +### Userver framework documentation +- Repository https://github.com/userver-framework/userver +- Site with documentation: https://userver.tech/de/d6a/md_en_2index.html + +### Documentation +- userver/samples: Example services demonstrating various features +- userver/service_template: Template for creating new services +- userver/ai-memory-bank: Memory bank with framework patterns and context + +### Development Environment +- CMake for build configuration +- GTest for unit testing +- pytest with testsuite for functional testing +- Google Benchmark for performance testing + +## Quality Standards + +### Code Quality +- Follow userver coding guidelines and patterns +- Use RAII and exception-safe coding practices +- Implement proper memory management with smart pointers +- Maintain consistent code formatting + +### Testing Requirements +- Unit tests for core business logic +- Functional tests for service endpoints +- Integration tests for database and external service interactions +- Performance benchmarks for critical operations + +This system prompt provides the foundation for developing high-quality services on the userver framework while maintaining consistency with established patterns and best practices. For detailed implementation instructions, refer to the .roorules file. \ No newline at end of file diff --git a/ai-development-settings/minimalistic/.gitkeep b/ai-development-settings/minimalistic/.gitkeep new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/ai-development-settings/minimalistic/.roorules b/ai-development-settings/minimalistic/.roorules new file mode 100644 index 000000000000..c24d7efd2a13 --- /dev/null +++ b/ai-development-settings/minimalistic/.roorules @@ -0,0 +1,186 @@ +# userver Service Development Rules + +service_development_rules: + description: "Rules and guidelines for developing services using the userver framework" + + # Notes about available resources + notes: + samples: "In ~/userver/samples there are many examples of userver services demonstrating various features and components" + framework_source: "In ~/userver there is the source code of the framework for reference" + memory_bank: "In ~/userver/ai-memory-bank there is memory about framework sources and patterns" + + # Service project structure based on service_template + project_structure: + description: "Standard directory structure for userver services" + structure: + service_name: + - "CMakeLists.txt # Build configuration" + - "configs/ # Configuration files" + - " └── static_config.yaml # Static service configuration" + - "src/ # Source code" + - " ├── main.cpp # Service entry point" + - " ├── handlers/ # HTTP handlers" + - " │ ├── handler_name.hpp # Handler declaration" + - " │ └── handler_name.cpp # Handler implementation" + - " └── components/ # Custom components (optional)" + - "tests/ # Tests (optional)" + - "unittests/ # Unit tests (optional)" + - "benchmarks/ # Benchmarks (optional)" + + # Key implementation files + key_files: + main_cpp: + description: "Service entry point" + responsibilities: + - "Sets up the component list" + - "Registers handlers and components" + - "Starts the service using userver::utils::DaemonMain" + + cmake_lists_txt: + description: "Build configuration" + responsibilities: + - "Finds the userver package" + - "Defines object libraries for source files" + - "Links against userver components" + - "Sets up installation targets" + + static_config_yaml: + description: "Configuration file" + responsibilities: + - "Defines task processors" + - "Configures components" + - "Maps handlers to URLs" + + # Service configuration patterns + configuration_patterns: + handler_configuration: + description: "Handlers are configured in static_config.yaml" + pattern: | + components: + handler-name: + path: /url-path + method: GET,POST # HTTP methods + task_processor: main-task-processor + + task_processor_configuration: + description: "Services typically define at least two task processors" + pattern: | + task_processors: + main-task-processor: + worker_threads: 4 # For CPU-bound tasks + fs-task-processor: + worker_threads: 2 # For filesystem-bound tasks + + component_registration: + description: "Components are registered in main.cpp using the component list" + pattern: | + auto component_list = userver::components::MinimalServerComponentList() + .Append() + .Append(); + + # Development workflows + development_workflows: + building: + steps: + - "CMake Configuration: Run cmake to configure the build" + - "Compilation: Run make or ninja to build the service" + - "Installation: Run make install to install the service" + + testing: + steps: + - "Unit Tests: Run with make test or ctest" + - "Functional Tests: Use testsuite framework" + - "Benchmarks: Run performance benchmarks" + + deployment: + steps: + - "Binary Deployment: Install the service binary" + - "Configuration Deployment: Deploy configuration files" + - "Service Management: Use systemd or similar for service management" + + # Service-specific rules and guidelines + service_rules: + handler_implementation: + guidelines: + - "Handler Classes: Inherit from userver::server::handlers::HttpHandlerBase" + - "Handler Names: Use kName constant for component registration" + - "Request Handling: Implement HandleRequestThrow method for exception-based error handling" + + component_design: + guidelines: + - "Component Lifecycle: Follow userver component lifecycle (Constructor → Start → Stop → Destructor)" + - "Configuration: Use GetComponentConfig() to access component configuration" + - "Dependencies: Declare dependencies in constructor parameters" + + error_handling: + guidelines: + - "Exceptions: Use exceptions for error handling (they are automatically converted to HTTP error responses)" + - "Logging: Use userver::logging for structured logging" + - "Validation: Validate input parameters and return appropriate HTTP status codes" + + # Key components that services typically use + key_components: + core_components: + - "server: HTTP server component" + - "logging: Logging component" + - "http-client: HTTP client for making outgoing requests" + - "dns-client: DNS client component" + - "handler-ping: Health check endpoint" + - "tests-control: Testsuite control endpoint" + + database_components: + description: "Depending on service requirements" + components: + - "postgres: PostgreSQL database component" + - "mongo: MongoDB database component" + - "redis: Redis/Valkey database component" + - "mysql: MySQL database component" + + optional_components: + - "testsuite-support: Testsuite support component" + - "congestion-control: Congestion control component" + - "dynamic-config: Dynamic configuration component" + + # Patterns for HTTP handlers, middleware, and error handling + implementation_patterns: + http_handler_patterns: + simple_handler: | + class MyHandler final : public userver::server::handlers::HttpHandlerBase { + public: + static constexpr std::string_view kName = "handler-my-handler"; + + std::string HandleRequestThrow( + const userver::server::http::HttpRequest& request, + userver::server::request::RequestContext&) const override; + }; + + request_processing: + - "Extract parameters from query string: request.GetArg(\"name\")" + - "Extract headers: request.GetHeader(\"header-name\")" + - "Set response headers: request.GetHttpResponse().SetHeader(\"header-name\", \"value\")" + - "Set response content type: request.GetHttpResponse().SetContentType(\"text/plain\")" + + middleware_patterns: + patterns: + - "Component-Based Middleware: Implement as components that wrap handlers" + - "Handler Chaining: Use handler composition for cross-cutting concerns" + - "Request Context: Use RequestContext to pass data between middleware components" + + error_handling_patterns: + patterns: + - "Exception-Based: Throw exceptions for error conditions" + - "HTTP Status Codes: Return appropriate HTTP status codes" + - "Structured Logging: Log errors with context information" + + exception_example: | + if (some_error_condition) { + throw userver::server::handlers::ClientError( + userver::server::handlers::InternalError, "Error message"); + } + + best_practices: + - "Asynchronous Operations: Use userver's asynchronous drivers for I/O operations" + - "Deadline Propagation: Propagate deadlines to downstream services" + - "Circuit Breakers: Use circuit breaker patterns for external dependencies" + - "Caching: Implement caching for frequently accessed data" + - "Rate Limiting: Implement rate limiting to protect services" \ No newline at end of file From c5319c99a7c913d0a54597255f2f0717c96b5313 Mon Sep 17 00:00:00 2001 From: abramov-alex Date: Tue, 5 Aug 2025 10:39:26 +0300 Subject: [PATCH 003/230] cc userver: rename kIsDetected to IsDetected Tests: CI
commit_hash:eaee212c80d5c5c6960147e6250fc4477cfde805 --- core/include/userver/dump/aggregates.hpp | 2 +- core/include/userver/dump/meta_containers.hpp | 2 +- .../userver/server/handlers/exceptions.hpp | 8 ++--- .../utils/statistics/metric_tag_impl.hpp | 4 +-- .../statistics/percentile_format_json.hpp | 2 +- .../userver/cache/mongo_cache_type_traits.hpp | 22 +++++++------- .../userver/storages/mysql/convert.hpp | 2 +- .../userver/cache/base_postgres_cache.hpp | 30 +++++++++---------- .../storages/postgres/io/type_traits.hpp | 4 +-- .../include/userver/formats/common/meta.hpp | 8 ++--- universal/include/userver/utils/get_if.hpp | 2 +- universal/include/userver/utils/meta.hpp | 16 +++++----- .../include/userver/utils/meta_light.hpp | 14 ++++----- .../include/userver/utils/projected_set.hpp | 2 +- universal/src/utils/meta_test.cpp | 4 +-- .../include/userver/utest/parameter_names.hpp | 4 +-- 16 files changed, 63 insertions(+), 63 deletions(-) diff --git a/core/include/userver/dump/aggregates.hpp b/core/include/userver/dump/aggregates.hpp index c22c4b86a89e..bfe2652be03f 100644 --- a/core/include/userver/dump/aggregates.hpp +++ b/core/include/userver/dump/aggregates.hpp @@ -33,7 +33,7 @@ constexpr bool AreAllDumpable(std::index_sequence) { template constexpr bool IsDumpableAggregate() { - if constexpr (std::is_aggregate_v && !meta::kIsDetected) { + if constexpr (std::is_aggregate_v && !meta::IsDetected) { constexpr auto kSize = boost::pfr::tuple_size_v; static_assert( AreAllDumpable(std::make_index_sequence{}), diff --git a/core/include/userver/dump/meta_containers.hpp b/core/include/userver/dump/meta_containers.hpp index 0c4b64dc6231..67280c0b7fd4 100644 --- a/core/include/userver/dump/meta_containers.hpp +++ b/core/include/userver/dump/meta_containers.hpp @@ -53,7 +53,7 @@ using InsertResult = decltype(dump::Insert(std::declval(), std::declval inline constexpr bool kIsContainer = meta::kIsRange && std::is_default_constructible_v && meta::kIsSizable && - meta::kIsDetected; + meta::IsDetected; } // namespace dump diff --git a/core/include/userver/server/handlers/exceptions.hpp b/core/include/userver/server/handlers/exceptions.hpp index 0abfde4700ed..4f4c0057102c 100644 --- a/core/include/userver/server/handlers/exceptions.hpp +++ b/core/include/userver/server/handlers/exceptions.hpp @@ -107,13 +107,13 @@ template using HasInternalMessage = decltype(std::declval().GetInternalMessage()); template -inline constexpr bool kHasInternalMessage = meta::kIsDetected; +inline constexpr bool kHasInternalMessage = meta::IsDetected; template using HasExternalBody = decltype(std::declval().GetExternalBody()); template -inline constexpr bool kHasExternalBody = meta::kIsDetected; +inline constexpr bool kHasExternalBody = meta::IsDetected; template inline constexpr bool kIsMessageBuilder = kHasExternalBody; @@ -121,7 +121,7 @@ inline constexpr bool kIsMessageBuilder = kHasExternalBody; template struct MessageExtractor { static_assert( - meta::kIsDetected, + meta::IsDetected, "Please use your message builder to build external body for " "your error. See server::handlers::CustomHandlerException " "for more info" @@ -134,7 +134,7 @@ struct MessageExtractor { } std::string GetServiceCode() const { - if constexpr (meta::kIsDetected) { + if constexpr (meta::IsDetected) { return builder.GetServiceCode(); } else { return std::string{}; diff --git a/core/include/userver/utils/statistics/metric_tag_impl.hpp b/core/include/userver/utils/statistics/metric_tag_impl.hpp index fc0cc4d0279e..48dbedd0ab03 100644 --- a/core/include/userver/utils/statistics/metric_tag_impl.hpp +++ b/core/include/userver/utils/statistics/metric_tag_impl.hpp @@ -63,7 +63,7 @@ class MetricWrapperBase { template class MetricWrapper final : public MetricWrapperBase { static_assert( - meta::kIsDetected || kHasWriterSupport, + meta::IsDetected || kHasWriterSupport, "Provide a `void DumpMetric(utils::statistics::Writer&, const Metric&)`" "function in the namespace of `Metric`." ); @@ -94,7 +94,7 @@ class MetricWrapper final : public MetricWrapperBase { bool HasWriterSupport() const noexcept override { return kHasWriterSupport; } void Reset() override { - if constexpr (meta::kIsDetected) { + if constexpr (meta::IsDetected) { ResetMetric(data_); } } diff --git a/core/include/userver/utils/statistics/percentile_format_json.hpp b/core/include/userver/utils/statistics/percentile_format_json.hpp index 1a2183891a0c..1c95566948dd 100644 --- a/core/include/userver/utils/statistics/percentile_format_json.hpp +++ b/core/include/userver/utils/statistics/percentile_format_json.hpp @@ -24,7 +24,7 @@ std::string GetPercentileFieldName(double perc); template formats::json::ValueBuilder PercentileToJson(const T& perc, std::initializer_list percents) { static_assert( - meta::kIsDetected, + meta::IsDetected, "T must specify T::GetPercentile(double) returning " "json-serializable value" ); diff --git a/mongo/include/userver/cache/mongo_cache_type_traits.hpp b/mongo/include/userver/cache/mongo_cache_type_traits.hpp index eaca914a7c02..86039e973e81 100644 --- a/mongo/include/userver/cache/mongo_cache_type_traits.hpp +++ b/mongo/include/userver/cache/mongo_cache_type_traits.hpp @@ -22,17 +22,17 @@ namespace mongo_cache::impl { template using CollectionsField = decltype(T::kMongoCollectionsField); template -inline constexpr bool kHasCollectionsField = meta::kIsDetected; +inline constexpr bool kHasCollectionsField = meta::IsDetected; template using UpdateFieldName = decltype(T::kMongoUpdateFieldName); template -inline constexpr bool kHasUpdateFieldName = meta::kIsDetected; +inline constexpr bool kHasUpdateFieldName = meta::IsDetected; template using KeyField = decltype(T::kKeyField); template -inline constexpr bool kHasKeyField = meta::kIsDetected; +inline constexpr bool kHasKeyField = meta::IsDetected; template using DataType = typename T::DataType; @@ -42,29 +42,29 @@ inline constexpr bool kHasValidDataType = meta::kIsMap using HasSecondaryPreferred = decltype(T::kIsSecondaryPreferred); template -inline constexpr bool kHasSecondaryPreferred = meta::kIsDetected; +inline constexpr bool kHasSecondaryPreferred = meta::IsDetected; template using HasDeserializeObject = decltype(T::DeserializeObject); template -inline constexpr bool kHasDeserializeObject = meta::kIsDetected; +inline constexpr bool kHasDeserializeObject = meta::IsDetected; template using HasCorrectDeserializeObject = meta::ExpectSame< typename T::ObjectType, decltype(std::declval().DeserializeObject(std::declval()))>; template -inline constexpr bool kHasCorrectDeserializeObject = meta::kIsDetected; +inline constexpr bool kHasCorrectDeserializeObject = meta::IsDetected; template using HasDefaultDeserializeObject = decltype(T::kUseDefaultDeserializeObject); template -inline constexpr bool kHasDefaultDeserializeObject = meta::kIsDetected; +inline constexpr bool kHasDefaultDeserializeObject = meta::IsDetected; template using HasFindOperation = decltype(T::GetFindOperation); template -inline constexpr bool kHasFindOperation = meta::kIsDetected; +inline constexpr bool kHasFindOperation = meta::IsDetected; template using HasCorrectFindOperation = meta::ExpectSame< @@ -77,17 +77,17 @@ using HasCorrectFindOperation = meta::ExpectSame< ))>; template -inline constexpr bool kHasCorrectFindOperation = meta::kIsDetected; +inline constexpr bool kHasCorrectFindOperation = meta::IsDetected; template using HasDefaultFindOperation = decltype(T::kUseDefaultFindOperation); template -inline constexpr bool kHasDefaultFindOperation = meta::kIsDetected; +inline constexpr bool kHasDefaultFindOperation = meta::IsDetected; template using HasInvalidDocumentsSkipped = decltype(T::kAreInvalidDocumentsSkipped); template -inline constexpr bool kHasInvalidDocumentsSkipped = meta::kIsDetected; +inline constexpr bool kHasInvalidDocumentsSkipped = meta::IsDetected; template struct ClassByMemberPointer {}; diff --git a/mysql/include/userver/storages/mysql/convert.hpp b/mysql/include/userver/storages/mysql/convert.hpp index 19caee7baf60..d8fb52f199e7 100644 --- a/mysql/include/userver/storages/mysql/convert.hpp +++ b/mysql/include/userver/storages/mysql/convert.hpp @@ -18,7 +18,7 @@ template using HasConvert = decltype(Convert(std::declval(), convert::To{})); template -inline constexpr bool kHasConvert = meta::kIsDetected; +inline constexpr bool kHasConvert = meta::IsDetected; } // namespace impl diff --git a/postgresql/include/userver/cache/base_postgres_cache.hpp b/postgresql/include/userver/cache/base_postgres_cache.hpp index 5e4a603308c5..d4c90b72be56 100644 --- a/postgresql/include/userver/cache/base_postgres_cache.hpp +++ b/postgresql/include/userver/cache/base_postgres_cache.hpp @@ -126,12 +126,12 @@ namespace pg_cache::detail { template using ValueType = typename T::ValueType; template -inline constexpr bool kHasValueType = meta::kIsDetected; +inline constexpr bool kHasValueType = meta::IsDetected; template using RawValueTypeImpl = typename T::RawValueType; template -inline constexpr bool kHasRawValueType = meta::kIsDetected; +inline constexpr bool kHasRawValueType = meta::IsDetected; template using RawValueType = meta::DetectedOr, RawValueTypeImpl, T>; @@ -148,48 +148,48 @@ auto ExtractValue(RawValueType&& raw) { template using HasNameImpl = std::enable_if_t; template -inline constexpr bool kHasName = meta::kIsDetected; +inline constexpr bool kHasName = meta::IsDetected; // Component query in policy template using HasQueryImpl = decltype(T::kQuery); template -inline constexpr bool kHasQuery = meta::kIsDetected; +inline constexpr bool kHasQuery = meta::IsDetected; // Component GetQuery in policy template using HasGetQueryImpl = decltype(T::GetQuery()); template -inline constexpr bool kHasGetQuery = meta::kIsDetected; +inline constexpr bool kHasGetQuery = meta::IsDetected; // Component kWhere in policy template using HasWhere = decltype(T::kWhere); template -inline constexpr bool kHasWhere = meta::kIsDetected; +inline constexpr bool kHasWhere = meta::IsDetected; // Component kOrderBy in policy template using HasOrderBy = decltype(T::kOrderBy); template -inline constexpr bool kHasOrderBy = meta::kIsDetected; +inline constexpr bool kHasOrderBy = meta::IsDetected; // Update field template using HasUpdatedField = decltype(T::kUpdatedField); template -inline constexpr bool kHasUpdatedField = meta::kIsDetected; +inline constexpr bool kHasUpdatedField = meta::IsDetected; template using WantIncrementalUpdates = std::enable_if_t; template -inline constexpr bool kWantIncrementalUpdates = meta::kIsDetected; +inline constexpr bool kWantIncrementalUpdates = meta::IsDetected; // Key member in policy template using KeyMemberTypeImpl = std::decay_t>>; template -inline constexpr bool kHasKeyMember = meta::kIsDetected; +inline constexpr bool kHasKeyMember = meta::IsDetected; template using KeyMemberType = meta::DetectedType; @@ -252,7 +252,7 @@ using HasOnWritesDoneImpl = decltype(std::declval().OnWritesDone()); template void OnWritesDone(T& container) { - if constexpr (meta::kIsDetected) { + if constexpr (meta::IsDetected) { container.OnWritesDone(); } } @@ -261,12 +261,12 @@ template using HasCustomUpdatedImpl = decltype(T::GetLastKnownUpdated(std::declval>())); template -inline constexpr bool kHasCustomUpdated = meta::kIsDetected; +inline constexpr bool kHasCustomUpdated = meta::IsDetected; template using UpdatedFieldTypeImpl = typename T::UpdatedFieldType; template -inline constexpr bool kHasUpdatedFieldType = meta::kIsDetected; +inline constexpr bool kHasUpdatedFieldType = meta::IsDetected; template using UpdatedFieldType = meta::DetectedOr; @@ -307,7 +307,7 @@ using HasClusterHostTypeImpl = decltype(T::kClusterHostType); template constexpr storages::postgres::ClusterHostTypeFlags ClusterHostType() { - if constexpr (meta::kIsDetected) { + if constexpr (meta::IsDetected) { return T::kClusterHostType; } else { return storages::postgres::ClusterHostType::kSlave; @@ -320,7 +320,7 @@ using HasMayReturnNull = decltype(T::kMayReturnNull); template constexpr bool MayReturnNull() { - if constexpr (meta::kIsDetected) { + if constexpr (meta::IsDetected) { return T::kMayReturnNull; } else { return false; diff --git a/postgresql/include/userver/storages/postgres/io/type_traits.hpp b/postgresql/include/userver/storages/postgres/io/type_traits.hpp index 6b965f34138e..2d43f053d2be 100644 --- a/postgresql/include/userver/storages/postgres/io/type_traits.hpp +++ b/postgresql/include/userver/storages/postgres/io/type_traits.hpp @@ -58,13 +58,13 @@ template using HasOutputOperator = decltype(std::declval() << std::declval()); template -inline constexpr bool kHasOutputOperator = meta::kIsDetected; +inline constexpr bool kHasOutputOperator = meta::IsDetected; template using HasInputOperator = decltype(std::declval() >> std::declval()); template -inline constexpr bool kHasInputOperator = meta::kIsDetected; +inline constexpr bool kHasInputOperator = meta::IsDetected; ///@} ///@{ diff --git a/universal/include/userver/formats/common/meta.hpp b/universal/include/userver/formats/common/meta.hpp index e0388a632c37..36ef82b861f8 100644 --- a/universal/include/userver/formats/common/meta.hpp +++ b/universal/include/userver/formats/common/meta.hpp @@ -34,20 +34,20 @@ template using IsFormatValue = typename Value::ParseException; template -constexpr inline bool kHasParse = meta::kIsDetected; +constexpr inline bool kHasParse = meta::IsDetected; template -constexpr inline bool kHasSerialize = meta::kIsDetected; +constexpr inline bool kHasSerialize = meta::IsDetected; template -constexpr inline bool kHasConvert = meta::kIsDetected; +constexpr inline bool kHasConvert = meta::IsDetected; } // namespace impl /// Used in `Parse` overloads that are templated on `Value`, avoids clashing /// with `Parse` from string template -constexpr inline bool kIsFormatValue = meta::kIsDetected; +constexpr inline bool kIsFormatValue = meta::IsDetected; // Unwraps a transient type - tag types, for which ADL-found `Parse` returns // another type, not the type specified in `formats::parse::To`. For example, diff --git a/universal/include/userver/utils/get_if.hpp b/universal/include/userver/utils/get_if.hpp index 8c4aa128f4c1..5577ebec5dc5 100644 --- a/universal/include/userver/utils/get_if.hpp +++ b/universal/include/userver/utils/get_if.hpp @@ -20,7 +20,7 @@ template using IsPointerLike = decltype(std::declval() ? std::addressof(*std::declval()) : nullptr); template -inline constexpr bool kIsPointerLike = meta::kIsDetected; +inline constexpr bool kIsPointerLike = meta::IsDetected; } // namespace impl diff --git a/universal/include/userver/utils/meta.hpp b/universal/include/userver/utils/meta.hpp index 84bc7fd3403c..cefac2746522 100644 --- a/universal/include/userver/utils/meta.hpp +++ b/universal/include/userver/utils/meta.hpp @@ -32,7 +32,7 @@ using IsRange = ExpectSame()))>, std::decay_t()))>>; template -using IteratorType = std::enable_if_t, decltype(begin(std::declval()))>; +using IteratorType = std::enable_if_t, decltype(begin(std::declval()))>; template struct IsIterator : std::false_type {}; @@ -77,7 +77,7 @@ struct IsFixedSizeContainer> : std::bool_constant constexpr bool IsSingleRange() { if constexpr (sizeof...(Args) == 1) { - return kIsDetected; + return IsDetected; } else { return false; } @@ -89,16 +89,16 @@ template inline constexpr bool kIsVector = kIsInstantiationOf; template -inline constexpr bool kIsRange = kIsDetected; +inline constexpr bool kIsRange = IsDetected; /// Returns true if T is an ordered or unordered map or multimap template inline constexpr bool kIsMap = - kIsDetected && kIsDetected && kIsDetected; + IsDetected && IsDetected && IsDetected; /// Returns true if T is a map (but not a multimap!) template -inline constexpr bool kIsUniqueMap = kIsMap && kIsDetected< +inline constexpr bool kIsUniqueMap = kIsMap && IsDetected< impl::SubscriptOperatorResult, T>; // no operator[] in multimaps @@ -132,15 +132,15 @@ inline constexpr bool kIsStdHashable = /// @brief Check if std::size is applicable to container template -inline constexpr bool kIsSizable = kIsDetected; +inline constexpr bool kIsSizable = IsDetected; /// @brief Check if a container has `reserve` template -inline constexpr bool kIsReservable = kIsDetected; +inline constexpr bool kIsReservable = IsDetected; /// @brief Check if a container has 'push_back' template -inline constexpr bool kIsPushBackable = kIsDetected; +inline constexpr bool kIsPushBackable = IsDetected; /// @brief Check if a container has fixed size (e.g. std::array) template diff --git a/universal/include/userver/utils/meta_light.hpp b/universal/include/userver/utils/meta_light.hpp index 1c3fc86de0a2..25febbf73fcb 100644 --- a/universal/include/userver/utils/meta_light.hpp +++ b/universal/include/userver/utils/meta_light.hpp @@ -36,7 +36,7 @@ struct IsInstantiationOf> : std::true_type {}; } // namespace impl -/// @see utils::meta::kIsDetected +/// @see utils::meta::IsDetected struct NotDetected {}; #if defined(__cpp_concepts) || defined(DOXYGEN) @@ -53,31 +53,31 @@ struct NotDetected {}; /// template /// using HasValueType = typename T::ValueType; /// ... -/// if constexpr (utils::meta::kIsDetected) { ... } +/// if constexpr (utils::meta::IsDetected) { ... } /// @endcode template