Valkey GLIDE AI Coding Assistant Instructions - Comprehensive guide for AI agents working on the multi-language Valkey/Redis client library

copilot-instructions.md

Valkey GLIDE AI Coding Assistant Instructions

Project Overview

Multi-language Valkey/Redis client with Rust core (glide-core) and language wrappers. Uses protobuf for cross-language communication and FFI/UDS for performance.

Architecture

Core Components

• glide-core/: Rust core (protocol, connections, business logic)
• ffi/: C FFI layer for direct language bindings
• socket_listener.rs: UDS server for process-isolated communication
• Language wrappers: java/, python/, node/, csharp/, cpp/, go/
• Protobuf: Commands in glide-core/src/protobuf/*.proto

Communication Patterns

1. FFI (Go, C/C++): Direct memory-shared, static linking libglide_ffi.a
2. UDS (Java, Python, Node.js): Process-isolated via Unix sockets /tmp/glide-socket-*

Development Workflows

Build Commands

• Root: make all or make <lang>
• Java: ./gradlew :client:buildAll
• Python: python3 dev.py build --mode release
• Node: npm run build:release
• Go: make build

Adding New Commands

1. Check glide-core/src/request_type.rs and command_request.proto
2. Add to Rust core RequestType enum
3. Update ffi/src/lib.rs (FFI) or socket_listener.rs (UDS)
4. Add to each language wrapper
5. Update protobuf if needed

Testing

• Integration tests: Use utils/cluster_manager.py for test servers
• FFI tests: ./gradlew testFfi (Java)
• Flags: -Dtls=true for TLS testing

Language-Specific Patterns

Java

• Gradle: :client (main), :integTest (tests)
• JNI via glide.ffi package
• Async: CompletableFuture<T>
• Format: ./gradlew spotlessApply

Python

• Build: dev.py with maturin/PyO3
• Unified async/sync API

Node.js

• napi-rs bindings in rust-client/
• TypeScript: src/ → build-ts/

Go

• CGO with libglide_ffi.a
• Direct FFI calls: C.create_client()

C#/C++

• FFI with static libglide_ffi.a
• Manual memory management at C boundary

Key Conventions

Error Handling

• Rust core: Result<T, RedisError>
• Languages: Idiomatic error types (exceptions, promises, etc.)

Routing & Clustering

• Auto-route by key slots or explicit RequestRouting
• Multi-slot operations need special handling (MGET, MSET)
• AZ Affinity for read-from-replica

File Organization

• Shared protobuf: glide-core/src/protobuf/
• Generated code: build/ directories (git-ignored)
• Language docs: DEVELOPER.md in each language
• Examples: examples/<lang>/

Development Methodology

5-Stage Implementation Process

1. Deep Design & Planning: Create thorough, complete plans with comprehensive design. Research extensively, validate assumptions, and ensure all edge cases are considered
2. Core Implementation: Implement in Rust core (glide-core/) ensuring it works for all language wrappers. Focus on performance, maintainability, and cross-language compatibility
3. Core Testing: Add comprehensive tests in the core to validate implementation works correctly across all scenarios
4. Wrapper Implementation: Choose one wrapper, implement fully, merge completely before moving to other wrappers. One wrapper at a time to completion
5. Wrapper Testing: After each wrapper implementation, create thorough testing for the new feature ensuring it works as designed

Collaboration Standards

• Critical Design Review: Challenge every design decision. Research web for best practices, validate approaches, question assumptions
• Implementation Excellence: Always seek better implementation methods. Optimize for performance, check every line of code for quality
• Meaningful Testing: Write tests that actually validate implementation, not tests designed to pass. Test edge cases and failure scenarios
• Code Quality: Clean up debugging code, remove unnecessary try/catch blocks, ensure readable code and well-organized commits
• Open Source Standards: Follow best practices for large-scale open source development

Project Management & Workflow

Focus Strategy for Large Projects

• Single Language Focus: When working on this extremely large multi-language project, concentrate on ONE language at a time along with the shared Rust components to preserve context window
• Context Boundaries: Avoid loading unnecessary language implementations when working on a specific wrapper
• Rust Core Integration: Always include glide-core/ and ffi/ context when working on any language wrapper

Branch Context Tracking

• Branch Goals: Create and maintain a BRANCH_CONTEXT.md file in the project root to track:
  • Current branch objective and key goals
  • Implementation strategy and approach
  • Key decisions and rationale
  • Progress tracking and next steps
• Context Updates: Regularly update this file as work progresses
• Review Process: Always check existing BRANCH_CONTEXT.md before starting new work

Repository Information

• Repository URL: https://github.com/valkey-io/valkey-glide
• Issue Tracking: Use GitHub issues for feature requests, bugs, and discussions
• Pull Requests: Follow contribution guidelines in CONTRIBUTING.md

AI Assistant Guidelines

Stage-Based Behavior

• Design Phase: Research extensively using web search, challenge all decisions, validate with best practices, ensure completeness before proceeding
• Implementation Phase: Always seek optimal solutions, question performance implications, review every line for quality
• Testing Phase: Create meaningful tests that validate real behavior, not just passing tests. Focus on edge cases and failure scenarios
• Code Review: Ensure clean commits, readable code, removal of debug artifacts, adherence to open source standards

Information Validation

• Web Search First: When encountering unclear concepts or needing up-to-date information, perform web searches to validate understanding
• Documentation Sources: Cross-reference with official Valkey, Redis, and language-specific documentation
• Community Resources: Check GitHub discussions, Stack Overflow, and relevant community forums
• Best Practices Research: Always research industry standards and best practices before implementing

Implementation Standards

• Performance First: Consider impact on both FFI and UDS communication patterns
• Cross-Language Consistency: Ensure changes maintain consistency across language implementations
• Clean Code: Remove debugging code, organize commits logically, ensure code readability
• Thorough Testing: Test both standalone and cluster configurations for new features

Focus on understanding the protobuf interface and FFI boundaries when working across languages, and follow the 5-stage methodology rigorously.