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.
Files changed (50) hide show
  1. checksums.yaml +7 -0
  2. data/.rubocop.yml +69 -0
  3. data/.rubocop_todo.yml +22 -0
  4. data/AGENTS.md +224 -0
  5. data/CLAUDE.md +130 -0
  6. data/CONTRIBUTING.md +115 -0
  7. data/DEVELOPER.md +390 -0
  8. data/README.md +268 -0
  9. data/Rakefile +99 -0
  10. data/examples/README.md +55 -0
  11. data/examples/cluster.rb +24 -0
  12. data/examples/opentelemetry.rb +50 -0
  13. data/examples/pipelining.rb +29 -0
  14. data/examples/standalone.rb +22 -0
  15. data/examples/statistics.rb +24 -0
  16. data/lib/valkey/bindings.rb +319 -0
  17. data/lib/valkey/commands/bitmap_commands.rb +86 -0
  18. data/lib/valkey/commands/cluster_commands.rb +259 -0
  19. data/lib/valkey/commands/connection_commands.rb +318 -0
  20. data/lib/valkey/commands/function_commands.rb +255 -0
  21. data/lib/valkey/commands/generic_commands.rb +525 -0
  22. data/lib/valkey/commands/geo_commands.rb +87 -0
  23. data/lib/valkey/commands/hash_commands.rb +592 -0
  24. data/lib/valkey/commands/hyper_log_log_commands.rb +51 -0
  25. data/lib/valkey/commands/json_commands.rb +389 -0
  26. data/lib/valkey/commands/list_commands.rb +348 -0
  27. data/lib/valkey/commands/module_commands.rb +125 -0
  28. data/lib/valkey/commands/pubsub_commands.rb +237 -0
  29. data/lib/valkey/commands/scripting_commands.rb +287 -0
  30. data/lib/valkey/commands/server_commands.rb +961 -0
  31. data/lib/valkey/commands/set_commands.rb +220 -0
  32. data/lib/valkey/commands/sorted_set_commands.rb +971 -0
  33. data/lib/valkey/commands/stream_commands.rb +636 -0
  34. data/lib/valkey/commands/string_commands.rb +371 -0
  35. data/lib/valkey/commands/transaction_commands.rb +175 -0
  36. data/lib/valkey/commands/vector_search_commands.rb +271 -0
  37. data/lib/valkey/commands.rb +68 -0
  38. data/lib/valkey/errors.rb +41 -0
  39. data/lib/valkey/native/aarch64-unknown-linux-gnu/libglide_ffi.so +0 -0
  40. data/lib/valkey/native/x86_64-unknown-linux-gnu/libglide_ffi.so +0 -0
  41. data/lib/valkey/opentelemetry.rb +207 -0
  42. data/lib/valkey/pipeline.rb +20 -0
  43. data/lib/valkey/pubsub_callback.rb +10 -0
  44. data/lib/valkey/request_error_type.rb +10 -0
  45. data/lib/valkey/request_type.rb +436 -0
  46. data/lib/valkey/response_type.rb +20 -0
  47. data/lib/valkey/utils.rb +267 -0
  48. data/lib/valkey/version.rb +5 -0
  49. data/lib/valkey.rb +617 -0
  50. 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).