Skip to content

Ruby SDK methods and error classes generated from the op registry - #1127

Merged
zlareb1 merged 5 commits into
ClickHouse:mainfrom
rahulsjha:feat/ruby-sdk-generated
Nov 22, 2026
Merged

zlareb1 merged 5 commits into
ClickHouse:mainfrom
rahulsjha:feat/ruby-sdk-generated

Conversation

@rahulsjha

Copy link
Copy Markdown
Contributor

Part of #55.

Ruby SDK: generated methods, tests and the live run

This builds on the minimal Ruby client from #1027 (sdk/ruby/). Every op the server serves is now a Ruby method generated from the op registry. The PR also adds Loom.configure, the retry and idempotency rules the TypeScript SDK follows, and one error class per server code. The existing Client#set/get/search/delete methods and their tests stay as they were.

What changed

  • scripts/codegen/sdk_rb_gen.py (new). It writes two files under sdk/ruby/lib/clickhouse/loom/generated/. It has --check, like the other SDK generators.
    • ops.rb: OPS holds one OpSpec per op (idempotent, read-only, role, maturity, the input's field names and the required ones). It also has one class per op group with one method per op, and the client's group accessors. 376 ops in 43 groups.
    • errors.rb: one Error subclass per server code, plus ERROR_CLASSES (code → class). The codes come from the same functions that build docs/reference/errors.md in docs_reference.py, so the classes match the errors reference: 193 codes.
  • Wiring. make lint runs sdk_rb_gen.py --check. tests/unit/test_sdk_rb_generated.py fails when a generated file is stale, as test_sdk_ts_generated.py does for TypeScript, so the unit suite catches drift. code-generation.md, adding-an-operation.md, CONTRIBUTING.md and .claude/rules/wire-ops.md name the new generator next to the TS and Python ones.
  • Ruby runtime (hand-written):
    • operations.rb: OpSpec, and OpGroup, the base class of the generated groups.
    • configuration.rb: Loom.configure.
    • retry_policy.rb: RetryPolicy and RetryAfter.
    • client.rb: identity binding, the generated group accessors, the generic call, and the retry loop.
    • errors.rb: maps each code to its class, and keeps detail.
  • Loom is set as a short name for ClickHouse::Loom (Loom.configure, Loom::PinnedConflict, as the issue writes them). It is skipped when the app already defines a Loom.

How generation works

client.<group>.<method>(**fields) posts /v1/<group>.<rest>. The method name follows the Python SDK: tracker.source.add is client.tracker.source_add.

  • Name clashes. A method that would shadow a method every Ruby object has takes a trailing _. The only case today is memory.inspect → memory.inspect_; without it, printing a group in irb would make an HTTP call. The generator refuses to write if two ops map to the same method, if a group name would hide a client method, or if an error class name would take a constant the gem defines by hand.
  • Fields. Fields are keyword arguments, merged over the bound org / namespace / agent, so a keyword of the same name overrides one for a single call.
    • A keyword the op does not take raises ArgumentError before sending, with the nearest field name: memory.set has no field valeu (did you mean value?).
    • A nil keyword is left out. A Hash passed first is sent as it is, so it can carry an explicit null.
  • Transport options go under request_options: { idempotency_key:, retry_policy: }, a single reserved keyword. A plain idempotency_key: keyword would not work: task.create has a body field named idempotency_key, and some ops have fields named body, options and max_attempts. The generator fails if an op ever adds a field named request_options.
  • client.call("some.op", {...}) calls an op this gem version does not know yet.
  • client.search with no argument is the search.* group. With a query it is still the existing typed search(query, ...).

Retries, matching the TypeScript SDK (gaps listed under What's left)

  • Idempotency-Key. An op the server deduplicates (idempotent and not read-only) gets one Idempotency-Key, unless the caller passes one. Every resend in the call repeats it, along with X-Request-Id. X-Loom-Retry-Count counts the resends.
  • Connection failures. A connection refused or unreachable before the request went out is resent.
  • 408 and 5xx. These are resent for an op the registry marks idempotent. Any other op is resent only on a 408 or AUTH_UNAVAILABLE. Not resent: an error the server classes configuration, and the codes in the TypeScript NEVER_RETRIED list.
    • A 5xx on an op that is not idempotent, whose body names no retryable, is marked not retryable, as markMaybeApplied does in TypeScript.
  • Timeouts. A timeout, or an answer cut off after sending, is resent only for an op the server deduplicates. retry_timeouts takes :never, :idempotent (the default) or :always.
  • Retry-After. The header (seconds or an HTTP-date), or else detail.retry_after_s, replaces the backoff when it is at most 60 s.
  • Backoff. Defaults are 3 attempts, 0.25 s doubling up to 5 s, and jitter 0.5. Every field can be set in Loom.configure, Client.new(retry_policy:) or per call, and each is checked by name.
  • 429. A 429 is pacing, not a retry. The call waits out Retry-After (1 s when it is missing or longer than 60 s) for up to rate_limit_max_wait (15 s), then raises Loom::RateLimited.
  • Request ID on errors. An error answer that does not echo X-Request-Id keeps the ID the call sent, as TypeScript does. The server does not echo it on a 422, for example.

One change to the #1027 client: calls are now retried by default, where before the client sent each request once. The README's "never retries" sentence is replaced. The existing error tests now build their client with retry_policy: { max_attempts: 1 }, rate_limit_max_wait: 0 in test_helper.rb, so each still reads the first answer it got. Their assertions are unchanged. A network error stays retryable? == false, as before. TypeScript marks a failed connect as retryable; I kept the Ruby client's existing flag.

Tests

The tests run in WSL Ubuntu 22.04, on Ruby 3.1.6 and 3.3.6, with ruby -w and no warnings. No server is needed.

  • rake test: 68 runs, 1382 assertions, 0 failures. That is 11 existing ClientTest, 20 ErrorsTest (15 existing + 5 new), 13 GeneratedTest, 18 RetryTest and 6 ConfigurationTest.
    • Generated methods: the request body, identity overrides, nil keywords, an unknown field refused before sending, request_options, multi-segment and shadowing names, and an unknown op. Every op in OPS has its method, the client reaches every group, and no generated name shadows an Object method.
    • Retry and idempotency: exponential backoff, Retry-After from the header and from the body, a too-long Retry-After falling back to the backoff, and the same Idempotency-Key and X-Request-Id on every resend. Also: attempts running out, non-idempotent ops, AUTH_UNAVAILABLE, configuration and never-retried codes, 429 pacing and its budget, a refused connection, a timeout resent only for a deduplicated op, a per-call policy, policy validation, and HTTP-date parsing.
    • Error mapping: PinnedConflict with its detail, RateLimited, an unknown code raising Error, and every generated class naming its code.
  • FakeServer can now delay an answer and serves each connection on its own thread, which the timeout test needs.
  • pytest tests/unit/test_sdk_rb_generated.py: 7 passed. These check that both generated files are current, that --check reports a stale file, that every registry op appears in ops.rb, the method naming, that no error class hides a constant the gem uses, and that the error classes equal the codes in errors.md. test_codegen_common.py and test_codegen_checkout_guard.py still pass.
  • python scripts/codegen/sdk_rb_gen.py --check: both files current. ruff check and ruff format --check (0.16.9) are clean, scripts/gates/check_no_secrets.py finds nothing, and prettier (3.9.9) leaves the touched Markdown unchanged.
  • gem build clickhouse-loom.gemspec packages the generated files.

Live check

I ran this checkout's server (uvicorn server.main:app, auth off, fake-ngram-1024 embedder, native ClickHouse, migrations applied) and then a short script that uses only the generated methods:

  • memory.set returned active. Sent again with the same Idempotency-Key, it returned the same version, which is the server's replay.
  • memory.get returned the value and tags.
  • memory.search ranked the memory first. With a per-call agent: override it returned 0 hits.
  • The legacy client.get(key) still returns its typed Memory.
  • An unpinned memory.set over a pinned key raised Loom::PinnedConflict (PINNED_CONFLICT, 409, request ID kept).
  • An unknown keyword raised ArgumentError before sending, and a bad input raised Loom::ValidationFailed (422).
  • memory.delete tombstoned the key, and a later get returned found=false.
  • agents.connected and blacklist.list, whose inputs have no agent field, accept the bound agent the client sends with every call, as the Python SDK sends it.

What's left

  • CI job for Ruby. No workflow runs the Ruby tests today, and that was already true before this PR. The sdk/rust job in ci.yml (around line 1280) is the pattern: ruby/setup-ruby with 3.1 and 3.3, then bundle exec rake test in sdk/ruby. The lint job's "generated loom/ops.py and loom/client.py are current" step could also run sdk_rb_gen.py --check. For now, the drift check runs through make lint and the unit suite. I left workflow files alone so a maintainer can choose the job layout.
  • Retry parity gaps. These are not ported yet: the TypeScript SDK's pacing on X-RateLimit-* headers before a 429 arrives, a per-call timeout option, and resending a 401 once with a fresh token (the gem takes a fixed api_key).
  • Typed answers. The generated methods return the decoded JSON Hash. The four typed memory shorthands are kept, but there are no generated result classes yet.
  • The Rails example (per-user memory written from a Sidekiq job) is not in this PR, to keep it reviewable; the issue says you plan to ship one. It would use a Loom.configure initializer and the per-call namespace: override. I can add it here or in a follow-up.
  • The gem is not published to RubyGems, and its version stays 0.1.0.

An AI agent helped with this; I reviewed the change and ran the tests and the live check myself.

scripts/codegen/sdk_rb_gen.py writes sdk/ruby/lib/clickhouse/loom/generated/:
ops.rb holds OPS (one OpSpec per served op: idempotency, read-only, role,
maturity, field names) and one class per op group with one method per op,
named as the Python SDK names them; errors.rb holds one Error subclass per
server code, from the same sources as docs/reference/errors.md. --check
runs in make lint, and tests/unit/test_sdk_rb_generated.py fails on drift.

Signed-off-by: rahulsjha <132360698+rahulsjha@users.noreply.github.com>
client.<group>.<method>(**fields) calls every served op with the bound org,
namespace and agent, a keyword of the same name overriding one per call,
and an unknown field refused before sending. Loom.configure and
LOOM_BASE_URL / LOOM_API_KEY set the defaults. Calls follow the
TypeScript SDK's retry rules: one Idempotency-Key per deduplicated op,
repeated on every resend; 408/5xx resent for idempotent ops; Retry-After
(seconds or HTTP-date) honoured; a 429 waited out within
rate_limit_max_wait. A server code raises its own Error subclass
(Loom::PinnedConflict, Loom::RateLimited, ...). The existing
set/get/search/delete methods keep their typed answers.

Signed-off-by: rahulsjha <132360698+rahulsjha@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 21, 2026 20:55
@vercel

vercel Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
loom-docs Ready Ready Preview Nov 22, 2026 5:20am UTC

Request Review

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@zlareb1 zlareb1 self-assigned this Nov 21, 2026

@zlareb1 zlareb1 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One retry-bound defect remains. The submitted Ruby suite passes (68 tests), and the generator and checkout checks pass (23 tests). No live-server run was performed.

Comment thread sdk/ruby/lib/clickhouse/loom/client.rb Resolved
A 429 whose Retry-After is 0 or a past date gave a zero wait, so the rate_limit_max_wait check always passed and the call resent forever. Such a wait is now 1 s (as an absent one is) and any positive wait is at least 0.1 s, so every paced resend spends part of rate_limit_max_wait and the call ends in Loom::RateLimited.

Signed-off-by: rahulsjha <132360698+rahulsjha@users.noreply.github.com>
@rahulsjha

Copy link
Copy Markdown
Contributor Author

Thanks, you're right: a Retry-After: 0 (or a past date) gave a zero wait, so the budget check always passed. Fixed in 9fd878c.

  • RetryAfter.for_rate_limit now treats a zero, past, unreadable or over-60 s wait as 1 s, as it already did for a missing one, and floors any positive wait at 0.1 s. Every paced resend spends part of rate_limit_max_wait, so a call resends at most rate_limit_max_wait / 0.1 times and then raises Loom::RateLimited.
  • Your probe (max_attempts: 1, rate_limit_max_wait: 0.001, Retry-After: 0) now sends one request and raises RateLimited. That case and a past HTTP-date are regression tests, plus a zero wait under a 3 s budget (three 1 s sleeps, then the raise). The new tests fail on the previous head.
  • The README's 429 line says how a zero or short wait is counted.

#1127 fix: tests

@zlareb1 zlareb1 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No findings. The zero-delay rate-limit loop is bounded, including a zero or past Retry-After and a wait budget below the minimum delay. On this head, all 70 Ruby tests pass with 1,394 assertions, and all 23 generator and checkout checks pass.

@zlareb1 zlareb1 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The retry fix passes on this head. Validation with the current base found a separate generated-table defect: test_sdk_rb_generated.py fails because the Ruby operation table no longer matches two served code operations. The other 22 generator and checkout checks pass.

@rahulsjha

Copy link
Copy Markdown
Contributor Author

Thanks, fixed. I merged current main into the branch (no conflicts) and ran python scripts/codegen/sdk_rb_gen.py against its schemas. The only change to generated/ops.rb is include_lessons and lesson_namespaces on code.grep (from #1128) and code.enclosing (from #1139), so call_op now accepts both keywords.

  • sdk_rb_gen.py --check: current.
  • pytest tests/unit/test_sdk_rb_generated.py tests/unit/test_codegen_common.py tests/unit/test_codegen_checkout_guard.py: 23 passed.
  • Ruby SDK tests: 70 runs, 0 failures on 3.1.6 and 3.3.6.

Ruby op table regenerated against current main, and the checks

@zlareb1 zlareb1 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No findings. The generated operation table includes the lesson fields on code.grep and code.enclosing. On this head, all 70 Ruby tests pass with 1,394 assertions, and all 23 generator and checkout checks pass. Live-server tests were not run.

@zlareb1
zlareb1 merged commit 84c00d4 into ClickHouse:main Nov 22, 2026
54 checks passed
@rahulsjha rahulsjha mentioned this pull request Nov 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants