test-valkey-glide-rb 0.0.1.pre.rc1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/.rubocop.yml +69 -0
- data/.rubocop_todo.yml +22 -0
- data/AGENTS.md +224 -0
- data/CLAUDE.md +130 -0
- data/CONTRIBUTING.md +115 -0
- data/DEVELOPER.md +390 -0
- data/README.md +268 -0
- data/Rakefile +99 -0
- data/examples/README.md +55 -0
- data/examples/cluster.rb +24 -0
- data/examples/opentelemetry.rb +50 -0
- data/examples/pipelining.rb +29 -0
- data/examples/standalone.rb +22 -0
- data/examples/statistics.rb +24 -0
- data/lib/valkey/bindings.rb +319 -0
- data/lib/valkey/commands/bitmap_commands.rb +86 -0
- data/lib/valkey/commands/cluster_commands.rb +259 -0
- data/lib/valkey/commands/connection_commands.rb +318 -0
- data/lib/valkey/commands/function_commands.rb +255 -0
- data/lib/valkey/commands/generic_commands.rb +525 -0
- data/lib/valkey/commands/geo_commands.rb +87 -0
- data/lib/valkey/commands/hash_commands.rb +592 -0
- data/lib/valkey/commands/hyper_log_log_commands.rb +51 -0
- data/lib/valkey/commands/json_commands.rb +389 -0
- data/lib/valkey/commands/list_commands.rb +348 -0
- data/lib/valkey/commands/module_commands.rb +125 -0
- data/lib/valkey/commands/pubsub_commands.rb +237 -0
- data/lib/valkey/commands/scripting_commands.rb +287 -0
- data/lib/valkey/commands/server_commands.rb +961 -0
- data/lib/valkey/commands/set_commands.rb +220 -0
- data/lib/valkey/commands/sorted_set_commands.rb +971 -0
- data/lib/valkey/commands/stream_commands.rb +636 -0
- data/lib/valkey/commands/string_commands.rb +371 -0
- data/lib/valkey/commands/transaction_commands.rb +175 -0
- data/lib/valkey/commands/vector_search_commands.rb +271 -0
- data/lib/valkey/commands.rb +68 -0
- data/lib/valkey/errors.rb +41 -0
- data/lib/valkey/native/aarch64-unknown-linux-gnu/libglide_ffi.so +0 -0
- data/lib/valkey/native/x86_64-unknown-linux-gnu/libglide_ffi.so +0 -0
- data/lib/valkey/opentelemetry.rb +207 -0
- data/lib/valkey/pipeline.rb +20 -0
- data/lib/valkey/pubsub_callback.rb +10 -0
- data/lib/valkey/request_error_type.rb +10 -0
- data/lib/valkey/request_type.rb +436 -0
- data/lib/valkey/response_type.rb +20 -0
- data/lib/valkey/utils.rb +267 -0
- data/lib/valkey/version.rb +5 -0
- data/lib/valkey.rb +617 -0
- metadata +107 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 6f854a15403e607d0e4690ac22f35ed868684eb71498fc9d99a13410c97f3fec
|
|
4
|
+
data.tar.gz: 5489ff8c34ca1e05770ba2c2c7c96c89cdcd608ea93ad244bbff9bbaf920f238
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 5abb1601c8dc82faaf1a9dd85e4b2619cd2d7ec80d4cef60d26e11801b22c7ff9a2924bf680024f634c3ebfd63163e4e5302190343ff16a1f429d63d3affa19e
|
|
7
|
+
data.tar.gz: c4ac628249e1ffe78e014a6c8b84b05dda88d89671f710dbe8fc7370a233dd3d8627fdd7e1afdc8467f3f87382b0643e9026487ff481bf0af454fd6e9a058f33
|
data/.rubocop.yml
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
inherit_from: .rubocop_todo.yml
|
|
2
|
+
|
|
3
|
+
AllCops:
|
|
4
|
+
TargetRubyVersion: 2.6
|
|
5
|
+
NewCops: enable
|
|
6
|
+
Exclude:
|
|
7
|
+
- 'vendor/**/*'
|
|
8
|
+
- 'lib/valkey/protobuf/**/*.rb'
|
|
9
|
+
|
|
10
|
+
Style/StringLiterals:
|
|
11
|
+
Enabled: false
|
|
12
|
+
|
|
13
|
+
Metrics/ParameterLists:
|
|
14
|
+
Enabled: false
|
|
15
|
+
|
|
16
|
+
Metrics/PerceivedComplexity:
|
|
17
|
+
Enabled: false
|
|
18
|
+
|
|
19
|
+
Style/Documentation:
|
|
20
|
+
Enabled: false
|
|
21
|
+
|
|
22
|
+
Naming/MethodParameterName:
|
|
23
|
+
Enabled: false
|
|
24
|
+
|
|
25
|
+
Naming/AccessorMethodName:
|
|
26
|
+
Enabled: false
|
|
27
|
+
|
|
28
|
+
Lint/DuplicateBranch:
|
|
29
|
+
Enabled: false
|
|
30
|
+
|
|
31
|
+
Metrics/AbcSize:
|
|
32
|
+
Enabled: false
|
|
33
|
+
|
|
34
|
+
Metrics/CyclomaticComplexity:
|
|
35
|
+
Enabled: false
|
|
36
|
+
|
|
37
|
+
Metrics/MethodLength:
|
|
38
|
+
Max: 20
|
|
39
|
+
Exclude:
|
|
40
|
+
- 'lib/valkey.rb'
|
|
41
|
+
- 'lib/valkey/opentelemetry.rb'
|
|
42
|
+
- 'lib/valkey/bindings.rb'
|
|
43
|
+
- 'test/**/*.rb'
|
|
44
|
+
|
|
45
|
+
Metrics/ClassLength:
|
|
46
|
+
Exclude:
|
|
47
|
+
- 'lib/valkey.rb'
|
|
48
|
+
- 'test/**/*.rb'
|
|
49
|
+
|
|
50
|
+
Metrics/BlockLength:
|
|
51
|
+
Exclude:
|
|
52
|
+
- 'Rakefile'
|
|
53
|
+
- 'lib/valkey.rb'
|
|
54
|
+
|
|
55
|
+
Style/IfUnlessModifier:
|
|
56
|
+
Exclude:
|
|
57
|
+
- 'test/test_helper.rb'
|
|
58
|
+
|
|
59
|
+
Metrics/BlockNesting:
|
|
60
|
+
Exclude:
|
|
61
|
+
- 'test_app/**/*.rb'
|
|
62
|
+
|
|
63
|
+
Metrics/ModuleLength:
|
|
64
|
+
Exclude:
|
|
65
|
+
- 'lib/valkey/request_type.rb'
|
|
66
|
+
- 'lib/valkey/utils.rb'
|
|
67
|
+
- 'lib/valkey/commands/*.rb'
|
|
68
|
+
- 'lib/valkey/bindings.rb'
|
|
69
|
+
- 'test/**/*.rb'
|
data/.rubocop_todo.yml
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# This configuration was generated by
|
|
2
|
+
# `rubocop --auto-gen-config`
|
|
3
|
+
# on 2025-07-15 13:27:05 UTC using RuboCop version 1.78.0.
|
|
4
|
+
# The point is for the user to remove these configuration records
|
|
5
|
+
# one by one as the offenses are removed from the code base.
|
|
6
|
+
# Note that changes in the inspected code, or installation of new
|
|
7
|
+
# versions of RuboCop, may require this file to be generated again.
|
|
8
|
+
|
|
9
|
+
# Offense count: 1
|
|
10
|
+
# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
|
|
11
|
+
# AllowedMethods: refine
|
|
12
|
+
Metrics/BlockLength:
|
|
13
|
+
Max: 35
|
|
14
|
+
Exclude:
|
|
15
|
+
- 'lib/valkey.rb'
|
|
16
|
+
|
|
17
|
+
# Offense count: 1
|
|
18
|
+
# Configuration parameters: CountComments, CountAsOne.
|
|
19
|
+
Metrics/ClassLength:
|
|
20
|
+
Max: 111
|
|
21
|
+
Exclude:
|
|
22
|
+
- 'lib/valkey.rb'
|
data/AGENTS.md
ADDED
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
# AGENTS: Ruby Client Context for Agentic Tools
|
|
2
|
+
|
|
3
|
+
This file provides AI agents and developers with the minimum but sufficient context to work productively with the Valkey GLIDE Ruby client (`valkey-rb`). It covers build commands, testing, contribution requirements, and essential guardrails specific to the Ruby implementation.
|
|
4
|
+
|
|
5
|
+
## Repository Overview
|
|
6
|
+
|
|
7
|
+
This is the **Ruby client** for Valkey GLIDE, published as the `valkey-rb` gem. It provides a synchronous, redis-rb-compatible API on top of the Rust GLIDE core via FFI.
|
|
8
|
+
|
|
9
|
+
**Primary Languages:** Ruby, Rust (FFI native library, built separately from [valkey-glide](https://github.com/valkey-io/valkey-glide))
|
|
10
|
+
|
|
11
|
+
**Build System:** Bundler, Rake, RubyGems
|
|
12
|
+
|
|
13
|
+
**Architecture:** Ruby wrapper around `glide-ffi` (`libglide_ffi.so` / `.dylib`) — same FFI path as Go and Python sync clients
|
|
14
|
+
|
|
15
|
+
**Key Components:**
|
|
16
|
+
|
|
17
|
+
- `lib/valkey.rb` — Main client, pipelining, response conversion
|
|
18
|
+
- `lib/valkey/bindings.rb` — FFI bindings
|
|
19
|
+
- `lib/valkey/commands/` — Command modules
|
|
20
|
+
- `lib/valkey/opentelemetry.rb` — Native OTel configuration
|
|
21
|
+
- `test/valkey/` — Standalone integration tests
|
|
22
|
+
- `test/cluster/` — Cluster integration tests
|
|
23
|
+
- `test/lint/` — redis-rb compatibility lint suites
|
|
24
|
+
|
|
25
|
+
## Architecture Quick Facts
|
|
26
|
+
|
|
27
|
+
**Core Implementation:** Ruby wrapper around glide-core via `glide-ffi` cdylib
|
|
28
|
+
|
|
29
|
+
**Client Types:** `Valkey` — standalone or cluster (`cluster_mode: true`)
|
|
30
|
+
|
|
31
|
+
**API Style:** Synchronous, blocking calls (redis-rb style)
|
|
32
|
+
|
|
33
|
+
**Communication:** Direct FFI (`Bindings.command`, `Bindings.batch`)
|
|
34
|
+
|
|
35
|
+
**Supported Platforms:**
|
|
36
|
+
|
|
37
|
+
- Linux: Ubuntu 20+, Amazon Linux 2/2023 (x86_64, aarch64)
|
|
38
|
+
- macOS: 13.7+ (x86_64), 14.7+ (aarch64)
|
|
39
|
+
- **Note:** Alpine Linux / MUSL is **not** supported
|
|
40
|
+
|
|
41
|
+
**Ruby Versions:** 2.6, 2.7, 3.0, 3.1, 3.2, 3.3, 3.4, JRuby (CI matrix)
|
|
42
|
+
|
|
43
|
+
**Gem name:** `valkey-rb` on RubyGems
|
|
44
|
+
|
|
45
|
+
## Build and Test Rules (Agents)
|
|
46
|
+
|
|
47
|
+
### Preferred (Bundler / Rake)
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
# Setup
|
|
51
|
+
bin/setup # bundle install
|
|
52
|
+
|
|
53
|
+
# Linting
|
|
54
|
+
bundle exec rubocop
|
|
55
|
+
|
|
56
|
+
# Testing
|
|
57
|
+
bundle exec rake test # standalone (default)
|
|
58
|
+
bundle exec rake test:valkey # standalone explicitly
|
|
59
|
+
bundle exec rake test:cluster # cluster (needs nodes 7000-7005)
|
|
60
|
+
|
|
61
|
+
# Verbose / CI mode
|
|
62
|
+
CI=1 bundle exec rake test:valkey
|
|
63
|
+
|
|
64
|
+
# Console
|
|
65
|
+
bundle exec bin/console
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Raw Equivalents
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
# Run a single test file
|
|
72
|
+
bundle exec ruby test/valkey/string_commands_test.rb
|
|
73
|
+
|
|
74
|
+
# Run with custom port
|
|
75
|
+
VALKEY_PORT=6379 TIMEOUT=10 bundle exec rake test:valkey
|
|
76
|
+
|
|
77
|
+
# Load gem from lib/ without install
|
|
78
|
+
RUBYOPT="-I$(pwd)/lib" ruby -r valkey -e 'p Valkey.new.ping'
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Test Prerequisites
|
|
82
|
+
|
|
83
|
+
| Suite | Server requirement |
|
|
84
|
+
|-------|-------------------|
|
|
85
|
+
| `test:valkey` | Standalone Valkey/Redis on `localhost:6379` (DB 15) |
|
|
86
|
+
| `test:cluster` | 6-node cluster on `127.0.0.1:7000`–`7005` |
|
|
87
|
+
| SSL tests | TLS Valkey on port `6380` + certs in `test/fixtures/ssl/` |
|
|
88
|
+
| Module tests | JSON, Bloom, Search modules loaded (see CI workflow) |
|
|
89
|
+
|
|
90
|
+
### Rebuild Native FFI (when changing glide-core)
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
cd /path/to/valkey-glide/ffi
|
|
94
|
+
cargo build --release
|
|
95
|
+
cp target/release/libglide_ffi.so /path/to/valkey-glide-ruby/lib/valkey/ # Linux
|
|
96
|
+
# cp target/release/libglide_ffi.dylib ... # macOS
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Contribution Requirements
|
|
100
|
+
|
|
101
|
+
### Developer Certificate of Origin (DCO) Signoff REQUIRED
|
|
102
|
+
|
|
103
|
+
All commits must include a `Signed-off-by` line (per [valkey-glide CONTRIBUTING](https://github.com/valkey-io/valkey-glide/blob/main/CONTRIBUTING.md)):
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
git commit -s -m "feat(ruby): add new command implementation"
|
|
107
|
+
git config --global format.signOff true
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Conventional Commits
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
<type>(<scope>): <description>
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
**Example:** `feat(ruby): implement CLUSTER SCAN with routing options`
|
|
117
|
+
|
|
118
|
+
**Scopes:** `ruby`, or command family name when appropriate.
|
|
119
|
+
|
|
120
|
+
### Code Quality Requirements
|
|
121
|
+
|
|
122
|
+
**RuboCop (required before commit):**
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
bundle exec rubocop
|
|
126
|
+
bundle exec rubocop -A # auto-correct safe offenses
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
**Rust FFI (when updating native library):**
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
cd valkey-glide/ffi
|
|
133
|
+
cargo clippy --all-features --all-targets -- -D warnings
|
|
134
|
+
cargo fmt --manifest-path ./Cargo.toml --all
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## Guardrails & Policies
|
|
138
|
+
|
|
139
|
+
### Generated Outputs (Never Commit)
|
|
140
|
+
|
|
141
|
+
- `*.gem` — built gem packages
|
|
142
|
+
- `coverage/` — coverage reports
|
|
143
|
+
- `tmp/`, `test/tmp/` — temporary test artifacts
|
|
144
|
+
- Regenerated SSL certs unless intentionally updated (`test/fixtures/ssl/*.pem` may be committed for CI)
|
|
145
|
+
- Wrong-platform `libglide_ffi` binaries (build per OS/arch)
|
|
146
|
+
|
|
147
|
+
### Ruby-Specific Rules
|
|
148
|
+
|
|
149
|
+
- **Ruby 2.6+ Required:** Minimum per `valkey.gemspec`
|
|
150
|
+
- **FFI dependency:** `ffi ~> 1.17.0` — do not break ABI without rebuilding native lib
|
|
151
|
+
- **Synchronous only:** No async client in this repo; do not add EventMachine/async patterns without design review
|
|
152
|
+
- **redis-rb compatibility:** Prefer matching redis-rb method signatures and return types when implementing commands
|
|
153
|
+
- **Command args:** All FFI args are strings; convert types in Ruby before `send_command`
|
|
154
|
+
- **Pipeline transactions:** `MULTI`/`EXEC`/`DISCARD` in `pipelined` use sequential fallback — do not remove without fixing FFI batch stability
|
|
155
|
+
- **OpenTelemetry:** Init once per process via `Valkey::OpenTelemetry.init`; spans created in FFI layer
|
|
156
|
+
|
|
157
|
+
### Command Implementation Guidelines
|
|
158
|
+
|
|
159
|
+
1. Check `RequestType` in `lib/valkey/request_type.rb` against glide-core `request_type.rs`
|
|
160
|
+
2. Add method to appropriate `lib/valkey/commands/*.rb` module
|
|
161
|
+
3. Use `send_command(RequestType::..., args)`
|
|
162
|
+
4. Add tests: `test/valkey/` + `test/lint/` when applicable
|
|
163
|
+
5. Document with YARD comments + Valkey command link
|
|
164
|
+
|
|
165
|
+
### Never Commit
|
|
166
|
+
|
|
167
|
+
- Secrets, `.env` credentials, production URLs
|
|
168
|
+
- Debug `puts` in production code paths (PubSub callback is intentional for now)
|
|
169
|
+
|
|
170
|
+
## Project Structure (Essential)
|
|
171
|
+
|
|
172
|
+
```text
|
|
173
|
+
valkey-glide-ruby/
|
|
174
|
+
├── lib/valkey.rb
|
|
175
|
+
├── lib/valkey/
|
|
176
|
+
│ ├── bindings.rb
|
|
177
|
+
│ ├── libglide_ffi.{so,dylib}
|
|
178
|
+
│ ├── commands/*.rb
|
|
179
|
+
│ ├── opentelemetry.rb
|
|
180
|
+
│ ├── pipeline.rb
|
|
181
|
+
│ ├── request_type.rb
|
|
182
|
+
│ └── response_type.rb
|
|
183
|
+
├── test/valkey/ # standalone tests
|
|
184
|
+
├── test/cluster/ # cluster tests
|
|
185
|
+
├── test/lint/ # shared lint
|
|
186
|
+
├── valkey.gemspec
|
|
187
|
+
├── Rakefile
|
|
188
|
+
└── .github/workflows/CI.yml
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
## Quality Gates (Agent Checklist)
|
|
192
|
+
|
|
193
|
+
- [ ] `bundle exec rubocop` passes
|
|
194
|
+
- [ ] `bundle exec rake test:valkey` passes (with Valkey running)
|
|
195
|
+
- [ ] `bundle exec rake test:cluster` passes (if cluster commands touched)
|
|
196
|
+
- [ ] New commands have tests in `test/valkey/` and lint coverage where applicable
|
|
197
|
+
- [ ] `RequestType` matches glide-core enum
|
|
198
|
+
- [ ] No secrets or generated junk committed
|
|
199
|
+
- [ ] DCO signoff: `git log --format="%B" -n 1 | grep "Signed-off-by"`
|
|
200
|
+
- [ ] Conventional commit format used
|
|
201
|
+
- [ ] README / DEVELOPER.md updated if public API or setup changed
|
|
202
|
+
- [ ] Native lib rebuilt and copied if FFI/protobuf changed upstream
|
|
203
|
+
|
|
204
|
+
## Quick Facts for Reasoners
|
|
205
|
+
|
|
206
|
+
**Package:** `valkey-rb` on RubyGems
|
|
207
|
+
**API Style:** Synchronous, redis-rb-compatible
|
|
208
|
+
**Client:** `Valkey.new` — standalone or `cluster_mode: true`
|
|
209
|
+
**Key Features:** Pipelining, OpenTelemetry (native), statistics, TLS, URL parsing, cluster routing
|
|
210
|
+
**Testing:** Minitest + rake tasks; lint suites for redis-rb parity
|
|
211
|
+
**Core repo:** [valkey-glide](https://github.com/valkey-io/valkey-glide) (`ffi/`, `glide-core/`)
|
|
212
|
+
**This repo:** [valkey-glide-ruby](https://github.com/valkey-io/valkey-glide-ruby)
|
|
213
|
+
|
|
214
|
+
## If You Need More
|
|
215
|
+
|
|
216
|
+
- **Getting Started:** [README.md](./README.md)
|
|
217
|
+
- **Contributing:** [CONTRIBUTING.md](./CONTRIBUTING.md)
|
|
218
|
+
- **Examples:** [examples/](./examples/)
|
|
219
|
+
- **Development Setup:** [DEVELOPER.md](./DEVELOPER.md)
|
|
220
|
+
- **Claude-specific rules:** [CLAUDE.md](./CLAUDE.md)
|
|
221
|
+
- **Command coverage:** [Wiki — implementation status](https://github.com/valkey-io/valkey-glide-ruby/wiki/The-implementation-status-of-the-Valkey-commands)
|
|
222
|
+
- **GLIDE docs:** [glide.valkey.io](https://glide.valkey.io/)
|
|
223
|
+
- **Upstream FFI:** [valkey-glide/ffi](https://github.com/valkey-io/valkey-glide/tree/main/ffi)
|
|
224
|
+
- **Other language AGENTS.md:** [valkey-glide/python/AGENTS.md](https://github.com/valkey-io/valkey-glide/blob/main/python/AGENTS.md), [java/AGENTS.md](https://github.com/valkey-io/valkey-glide/blob/main/java/AGENTS.md)
|
data/CLAUDE.md
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
Valkey GLIDE Ruby (`valkey-rb`) is the official Ruby binding for Valkey and Redis OSS. It uses the shared Rust **glide-core** driver via the **glide-ffi** C library, with a redis-rb-compatible Ruby API. This repository is separate from the [valkey-glide](https://github.com/valkey-io/valkey-glide) mono-repo (Python, Java, Node, Go).
|
|
4
|
+
|
|
5
|
+
## Hard Constraints (non-negotiable)
|
|
6
|
+
|
|
7
|
+
- NO task completion without tests covering it and passing (when a Valkey server or cluster is available for integration tests)
|
|
8
|
+
- NO PR creation without addressing review feedback on tests, docs, and RuboCop
|
|
9
|
+
- NEVER assume — verify against `test/valkey/` and `test/lint/` suites
|
|
10
|
+
- NEVER ignore bugs, even out of scope — open a GitHub issue on [valkey-glide-ruby](https://github.com/valkey-io/valkey-glide-ruby/issues)
|
|
11
|
+
|
|
12
|
+
## Rules
|
|
13
|
+
|
|
14
|
+
### Always
|
|
15
|
+
|
|
16
|
+
- Direct and concise; no compliments or apologies
|
|
17
|
+
- Ask if unsure; stop and reassess if looping
|
|
18
|
+
- Match redis-rb conventions when implementing or fixing command APIs
|
|
19
|
+
- If asked to do X a certain way, do it that way; disagree in review, do not change without approval
|
|
20
|
+
|
|
21
|
+
### When Writing
|
|
22
|
+
|
|
23
|
+
- Commit frequently with meaningful messages; git is our diary
|
|
24
|
+
- Focus on **Ruby + FFI** in this repo; core/FFI changes require rebuilding `libglide_ffi` from [valkey-glide/ffi](https://github.com/valkey-io/valkey-glide/tree/main/ffi)
|
|
25
|
+
- Keep PRs small and focused
|
|
26
|
+
- Update README.md / DEVELOPER.md when changing setup, public API, or test requirements
|
|
27
|
+
|
|
28
|
+
### Before Task Completion
|
|
29
|
+
|
|
30
|
+
- Tests cover the change and pass (`bundle exec rake test:valkey` at minimum)
|
|
31
|
+
- `bundle exec rubocop` passes for changed Ruby files
|
|
32
|
+
- If FFI binary updated, smoke-test: `Valkey.new.ping` on target OS
|
|
33
|
+
|
|
34
|
+
### Before Push
|
|
35
|
+
|
|
36
|
+
- `git pull --rebase` on your base branch; resolve conflicts
|
|
37
|
+
- Run tests for relevant scope (`test:valkey` and/or `test:cluster`)
|
|
38
|
+
|
|
39
|
+
### Before PR Creation/Update
|
|
40
|
+
|
|
41
|
+
- RuboCop clean
|
|
42
|
+
- Tests pass for touched areas
|
|
43
|
+
- Docs updated if behavior or setup changed
|
|
44
|
+
- DCO sign-off on commits (`git commit -s`)
|
|
45
|
+
|
|
46
|
+
## What the user cares about (all equally important)
|
|
47
|
+
|
|
48
|
+
- **Performance** — low latency via GLIDE core; avoid unnecessary Ruby allocations in hot paths
|
|
49
|
+
- **Reliability** — correct error types (`CommandError`, `ConnectionError`, `TimeoutError`, `CannotConnectError`)
|
|
50
|
+
- **Usability** — redis-rb familiarity, clear README and connection options
|
|
51
|
+
- **Maintainability** — command modules, lint tests, minimal scope per PR
|
|
52
|
+
- **Correctness** — verify with Minitest, not assumptions; compare with other GLIDE clients for semantics
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Project Structure
|
|
57
|
+
|
|
58
|
+
```text
|
|
59
|
+
valkey-glide-ruby/
|
|
60
|
+
├── lib/valkey.rb # Client entry: connect, pipeline, convert_response
|
|
61
|
+
├── lib/valkey/
|
|
62
|
+
│ ├── bindings.rb # FFI to libglide_ffi
|
|
63
|
+
│ ├── libglide_ffi.so|.dylib # Native library (from valkey-glide/ffi)
|
|
64
|
+
│ ├── commands/ # One module per command family
|
|
65
|
+
│ ├── opentelemetry.rb # Valkey::OpenTelemetry.init
|
|
66
|
+
│ ├── pipeline.rb # Valkey::Pipeline
|
|
67
|
+
│ ├── request_type.rb # Maps to glide-core RequestType
|
|
68
|
+
│ └── response_type.rb # FFI response decoding
|
|
69
|
+
├── test/valkey/ # Standalone integration tests
|
|
70
|
+
├── test/cluster/ # Cluster tests
|
|
71
|
+
└── test/lint/ # redis-rb parity lint
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Architecture: Ruby to Core
|
|
75
|
+
|
|
76
|
+
| Component | Mechanism | Native library | Communication |
|
|
77
|
+
|-----------|-----------|----------------|---------------|
|
|
78
|
+
| Ruby client | FFI gem | `libglide_ffi` (glide-ffi cdylib) | Direct FFI calls |
|
|
79
|
+
| glide-ffi | Rust cdylib | Built from valkey-glide/ffi | glide-core |
|
|
80
|
+
| glide-core | Rust | N/A (in valkey-glide repo) | Valkey/Redis protocol |
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
Ruby (Valkey#send_command)
|
|
84
|
+
→ Bindings.command / Bindings.batch
|
|
85
|
+
→ libglide_ffi (Rust)
|
|
86
|
+
→ glide-core
|
|
87
|
+
→ Valkey / Redis OSS
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Same FFI stack as **Go** and **Python sync**; different from Java (JNI) and Python async (PyO3 + UDS).
|
|
91
|
+
|
|
92
|
+
## Context Retrieval
|
|
93
|
+
|
|
94
|
+
When working on a feature, read these paths first:
|
|
95
|
+
|
|
96
|
+
| Topic | Read first |
|
|
97
|
+
|-------|------------|
|
|
98
|
+
| Connection / options | `lib/valkey.rb` (`#initialize`), `test/lint/connection_options.rb` |
|
|
99
|
+
| New command | `lib/valkey/request_type.rb`, matching `lib/valkey/commands/*.rb`, `test/lint/*` |
|
|
100
|
+
| Pipelining / batch | `lib/valkey.rb` (`pipelined`, `send_batch_commands`), `lib/valkey/pipeline.rb` |
|
|
101
|
+
| OpenTelemetry | `lib/valkey/opentelemetry.rb`, `test/valkey/test_opentelemetry.rb` |
|
|
102
|
+
| FFI / errors | `lib/valkey/bindings.rb`, `lib/valkey/errors.rb` |
|
|
103
|
+
| Cluster | `test/support/helper/cluster.rb`, `test/cluster/` |
|
|
104
|
+
| Upstream semantics | [valkey-glide glide-core](https://github.com/valkey-io/valkey-glide/tree/main/glide-core), peer client in `go/` or `python/glide-sync/` |
|
|
105
|
+
|
|
106
|
+
## Build and Test (quick reference)
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
bin/setup
|
|
110
|
+
bundle exec rubocop
|
|
111
|
+
bundle exec rake test:valkey # needs localhost:6379
|
|
112
|
+
bundle exec rake test:cluster # needs cluster 7000-7005
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Rebuild FFI after core changes:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
cd valkey-glide/ffi && cargo build --release
|
|
119
|
+
cp target/release/libglide_ffi.* /path/to/valkey-glide-ruby/lib/valkey/
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## Agent docs in this repo
|
|
123
|
+
|
|
124
|
+
- [AGENTS.md](./AGENTS.md) — build/test/contribution checklist for agents
|
|
125
|
+
- [CONTRIBUTING.md](./CONTRIBUTING.md) — PR and DCO guidelines
|
|
126
|
+
- [DEVELOPER.md](./DEVELOPER.md) — full developer setup guide
|
|
127
|
+
- [examples/](./examples/) — runnable sample scripts
|
|
128
|
+
- [README.md](./README.md) — user-facing getting started
|
|
129
|
+
|
|
130
|
+
Upstream mono-repo agent context: [valkey-glide/AGENTS.md](https://github.com/valkey-io/valkey-glide/blob/main/AGENTS.md), [valkey-glide/CLAUDE.md](https://github.com/valkey-io/valkey-glide/blob/main/CLAUDE.md).
|
data/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Contributing Guidelines
|
|
2
|
+
|
|
3
|
+
Thank you for your interest in contributing to Valkey GLIDE for Ruby (`valkey-rb`). Whether it's a bug report, new feature, correction, or documentation, we value feedback from the community.
|
|
4
|
+
|
|
5
|
+
Please read this document before submitting issues or pull requests.
|
|
6
|
+
|
|
7
|
+
## Reporting Bugs and Feature Requests
|
|
8
|
+
|
|
9
|
+
Use the [GitHub issue tracker](https://github.com/valkey-io/valkey-glide-ruby/issues) for bugs, feature requests, and questions.
|
|
10
|
+
|
|
11
|
+
Before creating a new issue:
|
|
12
|
+
|
|
13
|
+
1. Search [existing issues](https://github.com/valkey-io/valkey-glide-ruby/issues) to avoid duplicates.
|
|
14
|
+
2. Include Ruby version, OS/architecture, `valkey-rb` version, and Valkey/Redis server version.
|
|
15
|
+
3. For connection problems, note standalone vs cluster and whether TLS is enabled.
|
|
16
|
+
4. Provide a minimal reproduction script when possible.
|
|
17
|
+
|
|
18
|
+
For issues that affect the shared Rust core or other language clients, consider opening an issue in [valkey-glide](https://github.com/valkey-io/valkey-glide/issues) as well.
|
|
19
|
+
|
|
20
|
+
## Contributing via Pull Requests
|
|
21
|
+
|
|
22
|
+
1. Work against the latest `main` branch.
|
|
23
|
+
2. Check [open](https://github.com/valkey-io/valkey-glide-ruby/pulls) and recently merged PRs for duplicates.
|
|
24
|
+
3. For large changes (new command families, FFI updates, API breaks), open an issue first to discuss scope.
|
|
25
|
+
|
|
26
|
+
### Pull request steps
|
|
27
|
+
|
|
28
|
+
1. Fork [valkey-glide-ruby](https://github.com/valkey-io/valkey-glide-ruby).
|
|
29
|
+
2. Make focused changes; avoid unrelated formatting drive-by edits.
|
|
30
|
+
3. Run local checks (see [DEVELOPER.md](./DEVELOPER.md)):
|
|
31
|
+
```bash
|
|
32
|
+
bundle exec rubocop
|
|
33
|
+
bundle exec rake test:valkey # standalone — requires Valkey on :6379
|
|
34
|
+
bundle exec rake test:cluster # if cluster-related — requires nodes :7000–:7005
|
|
35
|
+
```
|
|
36
|
+
4. Commit with **DCO sign-off** and **conventional commits**:
|
|
37
|
+
```bash
|
|
38
|
+
git commit -s -m "feat(ruby): add EXAMPLE command"
|
|
39
|
+
```
|
|
40
|
+
Configure automatic signoff: `git config --global format.signOff true`
|
|
41
|
+
|
|
42
|
+
5. Open a PR and respond to CI feedback (RuboCop + test matrix in `.github/workflows/CI.yml`).
|
|
43
|
+
|
|
44
|
+
GitHub guides: [fork a repo](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo), [create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
|
|
45
|
+
|
|
46
|
+
### Commit message format
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
<type>(<scope>): <description>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
| Type | Use for |
|
|
53
|
+
|------|---------|
|
|
54
|
+
| `feat` | New feature or command |
|
|
55
|
+
| `fix` | Bug fix |
|
|
56
|
+
| `docs` | Documentation only |
|
|
57
|
+
| `test` | Tests only |
|
|
58
|
+
| `refactor` | Code change without behavior change |
|
|
59
|
+
| `chore` | Tooling, CI, deps |
|
|
60
|
+
|
|
61
|
+
**Scope:** `ruby` or a command area (e.g. `ruby-pubsub`).
|
|
62
|
+
|
|
63
|
+
### Developer Certificate of Origin (DCO)
|
|
64
|
+
|
|
65
|
+
All commits must include:
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
Signed-off-by: Your Name <your.email@example.com>
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
By signing off, you agree to the [Developer Certificate of Origin](https://developercertificate.org/).
|
|
72
|
+
|
|
73
|
+
## Adding or Updating Commands
|
|
74
|
+
|
|
75
|
+
1. Confirm the command exists in [glide-core `request_type.rs`](https://github.com/valkey-io/valkey-glide/blob/main/glide-core/src/request_type.rs).
|
|
76
|
+
2. Add or verify `RequestType` in `lib/valkey/request_type.rb`.
|
|
77
|
+
3. Implement in the appropriate `lib/valkey/commands/*.rb` module.
|
|
78
|
+
4. Add tests under `test/valkey/` and lint coverage in `test/lint/` when matching redis-rb behavior.
|
|
79
|
+
5. Update the [command implementation wiki](https://github.com/valkey-io/valkey-glide-ruby/wiki/The-implementation-status-of-the-Valkey-commands).
|
|
80
|
+
|
|
81
|
+
See [DEVELOPER.md](./DEVELOPER.md) for full details.
|
|
82
|
+
|
|
83
|
+
## Updating the Native FFI Library
|
|
84
|
+
|
|
85
|
+
Changes that require a new `libglide_ffi` build:
|
|
86
|
+
|
|
87
|
+
1. Build from [valkey-glide/ffi](https://github.com/valkey-io/valkey-glide/tree/main/ffi) at a compatible release tag.
|
|
88
|
+
2. Copy `libglide_ffi.so` or `libglide_ffi.dylib` into `lib/valkey/`.
|
|
89
|
+
3. Document the valkey-glide version in the PR description.
|
|
90
|
+
4. Test on the target platform (Linux x86_64/aarch64, macOS Intel/Apple Silicon).
|
|
91
|
+
|
|
92
|
+
## AI-Assisted Development
|
|
93
|
+
|
|
94
|
+
If you use Cursor, Claude Code, or similar tools, read:
|
|
95
|
+
|
|
96
|
+
- [AGENTS.md](./AGENTS.md) — build, test, and quality checklist
|
|
97
|
+
- [CLAUDE.md](./CLAUDE.md) — workflow constraints for this repository
|
|
98
|
+
|
|
99
|
+
## Code of Conduct
|
|
100
|
+
|
|
101
|
+
This project follows the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). See the [FAQ](https://aws.github.io/code-of-conduct-faq) or contact opensource-codeofconduct@amazon.com with questions.
|
|
102
|
+
|
|
103
|
+
## Security
|
|
104
|
+
|
|
105
|
+
Report security vulnerabilities via [valkey-glide SECURITY.md](https://github.com/valkey-io/valkey-glide/blob/main/SECURITY.md).
|
|
106
|
+
|
|
107
|
+
## Licensing
|
|
108
|
+
|
|
109
|
+
Contributions are licensed under the same terms as the project. See [LICENSE](./LICENSE). You will be asked to confirm licensing in your PR.
|
|
110
|
+
|
|
111
|
+
## Community
|
|
112
|
+
|
|
113
|
+
Join Valkey Slack: [Join Valkey Slack](https://join.slack.com/t/valkey-oss-developer/shared_invite/zt-2nxs51chx-EB9hu9Qdch3GMfRcztTSkQ).
|
|
114
|
+
|
|
115
|
+
Broader GLIDE contributing process: [valkey-glide CONTRIBUTING.md](https://github.com/valkey-io/valkey-glide/blob/main/CONTRIBUTING.md).
|