How valkey-io/valkey-glide works
Purpose and Entry Points
Valkey GLIDE is a multi-language client for Valkey and Redis OSS. A shared Rust core owns connection behavior, protocol execution, cluster routing, resilience, and observability; language SDKs expose idiomatic APIs over native bindings. Primary consumer entry points are:
• rust/src/lib.rs
• go/glide_client.go
• java/client/src/main/java/glide/api/GlideClient.java
• node/src/index.ts
• python/glide-async/python/glide/glide_client.py
Rust Core Execution Engine
glide-core is the principal native runtime. It accepts protobuf-shaped connection and command requests, creates standalone or cluster clients, converts responses, and manages asynchronous request lifecycles.
• glide-core/src/lib.rs
• glide-core/src/client/mod.rs
• glide-core/src/protobuf/command_request.proto
Control flow is generally: SDK command API → language binding serialization → Rust core request dispatch → Redis-compatible transport → typed response/error returned through the binding.
Transport, Routing, and Resilience
The core wraps a vendored/customized Rust Redis client implementation and adds GLIDE-specific connection orchestration. Cluster support maintains slot/topology knowledge and routes requests, including multi-slot behavior; standalone support reconnects and applies circuit-breaker/timeout policies.
• glide-core/src/client/standalone_client.rs
• glide-core/src/client/reconnecting_connection.rs
• glide-core/redis-rs/redis/src/cluster_async/connections_logic.rs
Important external boundary: network connections terminate at Valkey or Redis OSS servers, including standalone, cluster, and Sentinel-related modes. TLS, DNS/address resolution, IAM authentication, dynamic credentials, and certificate reload are core-adjacent concerns.
• glide-core/src/address_resolver_registry.rs
• glide-core/src/iam/mod.rs
• glide-core/src/tls_reload/mod.rs
Stateful Client Features
Several core-owned facilities coordinate state beyond one command: client pools/scopes, cluster scan cursors, scripts, Pub/Sub subscriptions and reconnection, client-side cache behavior, and experimental compression.
• glide-core/src/pool.rs
• glide-core/src/pubsub/synchronizer.rs
• glide-core/src/cluster_scan_container.rs
These are shared semantics surfaced by SDK wrappers rather than independently implemented per language. Compression transforms supported string command payloads before transport and decodes responses afterward.
• glide-core/src/compression.rs
• glide-core/src/scripts_container.rs
Native Binding Boundary
A Rust FFI layer exposes core client and pool operations to language-specific adapters. Protobuf contracts and native response layouts are compatibility-critical boundaries: changes here affect Java JNI, Node N-API, Python native extensions, and Go bindings.
• ffi/src/lib.rs
• ffi/src/pool_ffi.rs
• glide-core/src/protobuf/response.proto
Java has a JNI bridge in Rust plus Java-side request/response managers; Node and Python build Rust native modules; Go appears to consume the shared FFI-facing implementation through its client layer.
• java/src/jni_client.rs
• node/rust-client/src/lib.rs
• python/glide-shared/src/lib.rs
Language SDK Layers
Each SDK provides public clients, command families, configuration models, batching, and conversion between native values and language types. Java additionally ships Jedis compatibility modules.
• Go: go/base_client.go, go/glide_cluster_client.go
• Java: java/client/src/main/java/glide/internal/GlideNativeBridge.java, java/client/src/main/java/glide/managers/CommandManager.java
• Node: node/src/BaseClient.ts, node/src/GlideClusterClient.ts
• Python: python/glide-shared/glide_shared/_glide_ffi.py, python/glide-sync/glide_sync/glide_client.py
• Rust SDK: rust/src/client/mod.rs, rust/src/commands/mod.rs
Observability, Delivery, and Runtime Matrix
OpenTelemetry spans/metrics are configured in SDK APIs and exported from the Rust telemetry crate; logging has a separate Rust core. CI builds and tests language packages against supported engine/version matrices and provisions Valkey containers for integration tests.
• glide-core/telemetry/src/open_telemetry.rs
• logger_core/src/lib.rs
• .github/workflows/full-matrix-tests.yml
Material runtimes are Rust/Tokio, JVM/JNI, Node.js/N-API, Python native extensions (sync and async), and Go. Infrastructure dependencies include Valkey/Redis OSS servers, Docker-based test services, DNS test setup, and optional AWS IAM/OpenTelemetry ecosystems.
Main entry points: mod.rs Core dispatch · GlideNativeBridge.java SDK adapters · address_resolver_registry.rs Network security · lib.rs Native FFI
Components 18
Language SDKs
Public idiomatic clients and command APIs.
- Rust SDK
rust/src/lib.rs - Go SDK
go/glide_client.go - Java SDK
java/client/src/main/java/glide/api/GlideClient.java - Node SDK
node/src/index.ts - Python SDK
python/glide-async/python/glide/glide_client.py - SDK adapters · Language layers batch commands and convert native values.
java/client/src/main/java/glide/internal/GlideNativeBridge.java
Native Runtime
Shared Rust execution and binding boundary.
- Native FFI · Compatibility boundary for core clients, pools, and response layouts.
ffi/src/lib.rs - Protocol contracts · Connection, command, and response wire contracts.
glide-core/src/protobuf/command_request.proto - Core dispatch · Creates clients, dispatches requests, and returns typed results.
glide-core/src/client/mod.rs - Routing & transport · Maintains cluster topology and routes Redis-compatible commands.
glide-core/redis-rs/redis/src/cluster_async/connections_logic.rs - Standalone resilience · Reconnects and applies circuit-breaker and timeout policies.
glide-core/src/client/reconnecting_connection.rs
Core Facilities
Stateful and cross-cutting client behavior.
- Stateful facilities · Pools, scans, scripts, Pub/Sub synchronization, cache, and compression.
glide-core/src/pool.rs - Network security · DNS resolution, IAM credentials, TLS reload, and dynamic authentication.
glide-core/src/address_resolver_registry.rs - Telemetry
glide-core/telemetry/src/open_telemetry.rs - Logging core
logger_core/src/lib.rs
External Boundaries
Network services and optional integrations.
- Valkey / Redis OSS · Standalone, cluster, and Sentinel-related server modes.
- AWS IAM & OpenTelemetry
- CI runtime matrix · Builds and tests language packages against supported server versions.
.github/workflows/full-matrix-tests.yml
Connections 23
- Rust SDK → Core dispatch: native API
- Go SDK → SDK adapters: commands
- Java SDK → SDK adapters: commands
- Node SDK → SDK adapters: commands
- Python SDK → SDK adapters: commands
- SDK adapters → Native FFI: native calls
- Native FFI → Protocol contracts: serializes
- Native FFI → Core dispatch: client and pool operations
- Protocol contracts → Core dispatch: request/response types
- Core dispatch → Routing & transport: cluster commands
- Core dispatch → Standalone resilience: standalone commands
- Core dispatch → Stateful facilities: shared semantics
- Routing & transport → Network security: connects through
- Standalone resilience → Network security: connects through
- Network security → Valkey / Redis OSS: network connections
- Routing & transport → Valkey / Redis OSS: cluster transport
- Standalone resilience → Valkey / Redis OSS: standalone transport
- Core dispatch → Telemetry: spans and metrics
- Core dispatch → Logging core: logs
- Network security → AWS IAM & OpenTelemetry: IAM integration
- Telemetry → AWS IAM & OpenTelemetry: exports telemetry
- CI runtime matrix → Rust SDK: builds and tests
- CI runtime matrix → Valkey / Redis OSS: provisions test services