# valkey-io/valkey-glide architecture

> Architecture diagram of the GitHub repository valkey-io/valkey-glide, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/valkey-io/valkey-glide
- Repository: https://github.com/valkey-io/valkey-glide

## Overview

#### 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: [`glide-core/src/client/mod.rs`](https://github.com/valkey-io/valkey-glide/blob/main/glide-core/src/client/mod.rs) (Core dispatch), [`java/client/src/main/java/glide/internal/GlideNativeBridge.java`](https://github.com/valkey-io/valkey-glide/blob/main/java/client/src/main/java/glide/internal/GlideNativeBridge.java) (SDK adapters), [`glide-core/src/address_resolver_registry.rs`](https://github.com/valkey-io/valkey-glide/blob/main/glide-core/src/address_resolver_registry.rs) (Network security), [`ffi/src/lib.rs`](https://github.com/valkey-io/valkey-glide/blob/main/ffi/src/lib.rs) (Native FFI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdks["Language SDKs"]
  node_rust_sdk["Rust SDK<br/>Rust client API<br/>[lib.rs]"]
  node_go_sdk["Go SDK<br/>Go client API<br/>[glide_client.go]"]
  node_java_sdk["Java SDK<br/>JVM client API<br/>[GlideClient.java]"]
  node_node_sdk["Node SDK<br/>TypeScript client API<br/>[index.ts]"]
  node_python_sdk["Python SDK<br/>Python client API<br/>[glide_client.py]"]
  node_sdk_adapters["SDK adapters<br/>request conversion"]
end

subgraph group_native["Native Runtime"]
  node_ffi{{"Native FFI<br/>Rust FFI boundary<br/>[lib.rs]"}}
  node_protobuf_contracts["Protocol contracts<br/>protobuf schemas"]
  node_core_dispatch["Core dispatch<br/>async request engine<br/>[mod.rs]"]
  node_routing_transport["Routing &amp; transport<br/>Redis client transport"]
  node_standalone_resilience["Standalone resilience<br/>reconnection policy"]
end

subgraph group_core_features["Core Facilities"]
  node_stateful_features["Stateful facilities<br/>shared client state<br/>[pool.rs]"]
  node_network_security["Network security<br/>connection adjuncts"]
  node_telemetry["Telemetry<br/>[open_telemetry.rs]"]
  node_logging["Logging core<br/>Rust logging<br/>[lib.rs]"]
end

subgraph group_external["External Boundaries"]
  node_valkey_servers[("Valkey / Redis OSS<br/>database servers")]
  node_optional_ecosystem(("AWS IAM &amp; OpenTelemetry<br/>optional services"))
  node_ci_matrix["CI runtime matrix<br/>delivery pipeline"]
end

node_rust_sdk -->|"native API"| node_core_dispatch
node_go_sdk -->|"commands"| node_sdk_adapters
node_java_sdk -->|"commands"| node_sdk_adapters
node_node_sdk -->|"commands"| node_sdk_adapters
node_python_sdk -->|"commands"| node_sdk_adapters
node_sdk_adapters -->|"native calls"| node_ffi
node_ffi -->|"serializes"| node_protobuf_contracts
node_ffi -->|"client and pool operations"| node_core_dispatch
node_protobuf_contracts -->|"request/response types"| node_core_dispatch
node_core_dispatch -->|"cluster commands"| node_routing_transport
node_core_dispatch -->|"standalone commands"| node_standalone_resilience
node_core_dispatch -->|"shared semantics"| node_stateful_features
node_routing_transport -->|"connects through"| node_network_security
node_standalone_resilience -->|"connects through"| node_network_security
node_network_security -->|"network connections"| node_valkey_servers
node_routing_transport -->|"cluster transport"| node_valkey_servers
node_standalone_resilience -->|"standalone transport"| node_valkey_servers
node_core_dispatch -.->|"spans and metrics"| node_telemetry
node_core_dispatch -.->|"logs"| node_logging
node_network_security -.->|"IAM integration"| node_optional_ecosystem
node_telemetry -.->|"exports telemetry"| node_optional_ecosystem
node_ci_matrix -.->|"builds and tests"| node_rust_sdk
node_ci_matrix -.->|"provisions test services"| node_valkey_servers

click node_rust_sdk "https://github.com/valkey-io/valkey-glide/blob/main/rust/src/lib.rs"
click node_go_sdk "https://github.com/valkey-io/valkey-glide/blob/main/go/glide_client.go"
click node_java_sdk "https://github.com/valkey-io/valkey-glide/blob/main/java/client/src/main/java/glide/api/GlideClient.java"
click node_node_sdk "https://github.com/valkey-io/valkey-glide/blob/main/node/src/index.ts"
click node_python_sdk "https://github.com/valkey-io/valkey-glide/blob/main/python/glide-async/python/glide/glide_client.py"
click node_sdk_adapters "https://github.com/valkey-io/valkey-glide/blob/main/java/client/src/main/java/glide/internal/GlideNativeBridge.java"
click node_ffi "https://github.com/valkey-io/valkey-glide/blob/main/ffi/src/lib.rs"
click node_protobuf_contracts "https://github.com/valkey-io/valkey-glide/blob/main/glide-core/src/protobuf/command_request.proto"
click node_core_dispatch "https://github.com/valkey-io/valkey-glide/blob/main/glide-core/src/client/mod.rs"
click node_routing_transport "https://github.com/valkey-io/valkey-glide/blob/main/glide-core/redis-rs/redis/src/cluster_async/connections_logic.rs"
click node_standalone_resilience "https://github.com/valkey-io/valkey-glide/blob/main/glide-core/src/client/reconnecting_connection.rs"
click node_stateful_features "https://github.com/valkey-io/valkey-glide/blob/main/glide-core/src/pool.rs"
click node_network_security "https://github.com/valkey-io/valkey-glide/blob/main/glide-core/src/address_resolver_registry.rs"
click node_telemetry "https://github.com/valkey-io/valkey-glide/blob/main/glide-core/telemetry/src/open_telemetry.rs"
click node_logging "https://github.com/valkey-io/valkey-glide/blob/main/logger_core/src/lib.rs"
click node_ci_matrix "https://github.com/valkey-io/valkey-glide/blob/main/.github/workflows/full-matrix-tests.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rust_sdk,node_go_sdk,node_java_sdk,node_node_sdk,node_python_sdk,node_sdk_adapters toneBlue
class node_ffi,node_protobuf_contracts,node_core_dispatch,node_routing_transport,node_standalone_resilience toneAmber
class node_stateful_features,node_network_security,node_telemetry,node_logging toneMint
class node_valkey_servers,node_optional_ecosystem,node_ci_matrix toneRose
```

## Components

### Language SDKs

Public idiomatic clients and command APIs.

- [Rust SDK](https://github.com/valkey-io/valkey-glide/blob/main/rust/src/lib.rs): Rust client API · `rust/src/lib.rs`
- [Go SDK](https://github.com/valkey-io/valkey-glide/blob/main/go/glide_client.go): Go client API · `go/glide_client.go`
- [Java SDK](https://github.com/valkey-io/valkey-glide/blob/main/java/client/src/main/java/glide/api/GlideClient.java): JVM client API · `java/client/src/main/java/glide/api/GlideClient.java`
- [Node SDK](https://github.com/valkey-io/valkey-glide/blob/main/node/src/index.ts): TypeScript client API · `node/src/index.ts`
- [Python SDK](https://github.com/valkey-io/valkey-glide/blob/main/python/glide-async/python/glide/glide_client.py): Python client API · `python/glide-async/python/glide/glide_client.py`
- [SDK adapters](https://github.com/valkey-io/valkey-glide/blob/main/java/client/src/main/java/glide/internal/GlideNativeBridge.java): request conversion · 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](https://github.com/valkey-io/valkey-glide/blob/main/ffi/src/lib.rs): Rust FFI boundary · Compatibility boundary for core clients, pools, and response layouts. · `ffi/src/lib.rs`
- [Protocol contracts](https://github.com/valkey-io/valkey-glide/blob/main/glide-core/src/protobuf/command_request.proto): protobuf schemas · Connection, command, and response wire contracts. · `glide-core/src/protobuf/command_request.proto`
- [Core dispatch](https://github.com/valkey-io/valkey-glide/blob/main/glide-core/src/client/mod.rs): async request engine · Creates clients, dispatches requests, and returns typed results. · `glide-core/src/client/mod.rs`
- [Routing & transport](https://github.com/valkey-io/valkey-glide/blob/main/glide-core/redis-rs/redis/src/cluster_async/connections_logic.rs): Redis client transport · Maintains cluster topology and routes Redis-compatible commands. · `glide-core/redis-rs/redis/src/cluster_async/connections_logic.rs`
- [Standalone resilience](https://github.com/valkey-io/valkey-glide/blob/main/glide-core/src/client/reconnecting_connection.rs): reconnection policy · 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](https://github.com/valkey-io/valkey-glide/blob/main/glide-core/src/pool.rs): shared client state · Pools, scans, scripts, Pub/Sub synchronization, cache, and compression. · `glide-core/src/pool.rs`
- [Network security](https://github.com/valkey-io/valkey-glide/blob/main/glide-core/src/address_resolver_registry.rs): connection adjuncts · DNS resolution, IAM credentials, TLS reload, and dynamic authentication. · `glide-core/src/address_resolver_registry.rs`
- [Telemetry](https://github.com/valkey-io/valkey-glide/blob/main/glide-core/telemetry/src/open_telemetry.rs): OpenTelemetry export · `glide-core/telemetry/src/open_telemetry.rs`
- [Logging core](https://github.com/valkey-io/valkey-glide/blob/main/logger_core/src/lib.rs): Rust logging · `logger_core/src/lib.rs`

### External Boundaries

Network services and optional integrations.

- **Valkey / Redis OSS**: database servers · Standalone, cluster, and Sentinel-related server modes.
- **AWS IAM & OpenTelemetry**: optional services
- [CI runtime matrix](https://github.com/valkey-io/valkey-glide/blob/main/.github/workflows/full-matrix-tests.yml): delivery pipeline · Builds and tests language packages against supported server versions. · `.github/workflows/full-matrix-tests.yml`

## Connections

- 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
