haveapi-rust-client 0.30.0 → 0.30.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21033d06951c8de41c052be7cf6d615912ba7fb83e450ed07d360d46691fc880
-  data.tar.gz: ace71e7005ca64d911730b47a67795ec64338097bcc3f4116976460c70d5de6b
+  metadata.gz: d48abd48b55a176accb7ff4492b9de2e68b6ee4b324d7edb406261387b467c4e
+  data.tar.gz: 2eb8481e97155eef2b0ad829b135ad504f880a29afea0a5b9e0c157229bb4ea5
 SHA512:
-  metadata.gz: a0de1d3a4d6c2d282e4b68012a43147e3ca865251fe03f179853db9d9b6fe3963fc9950b1a7585457c274a08bb351cc4d073f33385e764649ce4d81e15b96743
-  data.tar.gz: 55cebb5a66f6592549da6ccfdb9384d83812373485656e2c2f907da4c3e33618686e5f0fec2b36c2b29af79d1b6fefa7d6d3e126fea6827b719e5d3abbf98226
+  metadata.gz: 738bbd676ea82ff0a2eb25898c16a7038c5e8b25b54abaec838a8e1a25de08b248e92af70c355a886439f31572460eece27f8f96aed8630f945b95d554cba500
+  data.tar.gz: d0aa4952b7baf709927e4f95257ec8a42d72b672ca3f60fb048fcf8ca84f856fd0836a164101be162f69e12a4abaff2d6a4d2234f76e3d8e3d69c8e54d0ce837

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../ruby
   specs:
-    haveapi-client (0.30.0)
+    haveapi-client (0.30.1)
       activesupport (>= 7.0)
       highline (~> 3.1)
       json
@@ -12,8 +12,9 @@ PATH
 PATH
   remote: .
   specs:
-    haveapi-rust-client (0.30.0)
-      haveapi-client (~> 0.30.0)
+    haveapi-rust-client (0.30.1)
+      fiddle (~> 1.1, >= 1.1.8)
+      haveapi-client (~> 0.30.1)
       tomlrb (~> 2.0)
 
 GEM
@@ -40,6 +41,7 @@ GEM
     diff-lcs (1.6.2)
     domain_name (0.7.20261007)
     drb (2.2.3)
+    fiddle (1.1.8)
     hana (1.3.7)
     highline (3.1.2)
       reline
@@ -63,13 +65,13 @@ GEM
     mime-types (3.7.0)
       logger
       mime-types-data (~> 3.2025, >= 3.2025.0507)
-    mime-types-data (3.2026.1013)
+    mime-types-data (3.2026.1020)
     minitest (6.0.6)
       drb (~> 2.0)
       prism (~> 1.5)
     netrc (0.11.0)
     parallel (1.28.0)
-    parser (3.3.12.0)
+    parser (3.3.13.0)
       ast (~> 2.4.1)
       racc
     prism (1.9.0)
@@ -151,9 +153,10 @@ CHECKSUMS
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   domain_name (0.7.20261007) sha256=0976c6ab837dbde991b433d03acc38fdb91fa8839df31a1ed75ce0318dc0441c
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
+  fiddle (1.1.8) sha256=7fa8ee3627271497f3add5503acdbc3f40b32f610fc1cf49634f083ef3f32eee
   hana (1.3.7) sha256=5425db42d651fea08859811c29d20446f16af196308162894db208cac5ce9b0d
-  haveapi-client (0.30.0)
-  haveapi-rust-client (0.30.0)
+  haveapi-client (0.30.1)
+  haveapi-rust-client (0.30.1)
   highline (3.1.2) sha256=67cbd34d19f6ef11a7ee1d82ffab5d36dfd5b3be861f450fc1716c7125f4bb4a
   http-accept (1.7.0) sha256=c626860682bfbb3b46462f8c39cd470fd7b0584f61b3cc9df5b2e9eb9972a126
   http-cookie (1.1.6) sha256=ba4b82be64de61dc281243dac70e3c382c45142f20268ed9276a3670c93feaa9
@@ -166,11 +169,11 @@ CHECKSUMS
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   mcp (0.25.0) sha256=8acf3a5f3b60b6fd6e5d9b8ac5eb85ac504766976cbadaca182d2ffe7d795d98
   mime-types (3.7.0) sha256=dcebf61c246f08e15a4de34e386ebe8233791e868564a470c3fe77c00eed5e56
-  mime-types-data (3.2026.1013) sha256=370f152f2a47e54e58829766492ea2cbe130a45358374b8788a6a8ad4e961c96
+  mime-types-data (3.2026.1020) sha256=6b3bcc776c1e3591267727700467e02fb9c12b503fcce4e0e964516d7c1e0d06
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
   netrc (0.11.0) sha256=de1ce33da8c99ab1d97871726cba75151113f117146becbe45aa85cb3dabee3f
   parallel (1.28.0) sha256=33e6de1484baf2524792d178b0913fc8eb94c628d6cfe45599ad4458c638c970
-  parser (3.3.12.0) sha256=21a6d7f755d5a24dfbdc6e6b772e4e879a52e7631a88bc5a3a134606052c9828
+  parser (3.3.13.0) sha256=e02f9b63c2fe05b0c68f692ba4df89b3cb113b663964f75d988fbebfd6c3deca
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
   racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
   rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a

data/README.md

@@ -24,9 +24,13 @@ bundle exec rspec spec/unit
 bundle exec rubocop lib bin spec/unit spec/spec_helper.rb haveapi-rust-client.gemspec
 ```
 
-The component shell installs the dependencies frozen in the tracked
-`clients/rust/Gemfile.lock`. Use its Ruby interpreter with those gems; native
-gems installed by this shell cannot be loaded by a different ambient Ruby.
+The component shell runs `bundle install` for this library's dependency ranges
+and creates an ignored local `clients/rust/Gemfile.lock`. Keep that prepared
+resolution unchanged while building and checking a candidate, and retain the
+lock with its build evidence. Fresh resolutions can select different compatible
+dependencies; the source commit alone does not fix the Ruby dependency graph.
+Use the shell's Ruby interpreter with those gems; native gems installed by this
+shell cannot be loaded by a different ambient Ruby.
 The root Git hooks also need the root shell's dependencies: prepare them with
 `nix develop --command true` before committing, then commit with the declared
 Overcommit hooks enabled. Do not install gems concurrently in the same gem home.

data/docs/documentation.md

@@ -1,41 +1,100 @@
 # Rust examples in server documentation
 
-The optional `HaveAPI::RustClient::Documentation` adapter maps a published Rust
-SDK's saved snapshot and TOML configuration to server documentation. It uses the same
-Snapshot validation, complete IR, naming scopes and types as the generator.
-Construction and rendering make no network requests and run no generator, compiler
-or formatter. The server loads its trusted local files at startup.
+The optional `HaveAPI::RustClient::Documentation` adapter uses the generator's
+Snapshot validation, IR and naming rules to map a configured SDK to server
+examples. It makes no network requests and runs no generator, compiler or
+formatter during construction or rendering. Install `haveapi-rust-client`
+alongside the server, then register a profile before mounting:
 
-An API operator installs the matching `haveapi-rust-client` gem and configures a
-profile before mounting the server:
+```ruby
+api.documentation_clients('1.0', rust: { crate_name: 'widget-client' })
+api.mount('/api/')
+```
+
+`generator_version` defaults to the server's `HaveAPI::VERSION` and must match
+the installed generator gem. An explicit value requires the installed generator
+to report that version; it never downloads one. The SDK's version and API version
+are independent of that generator version. Imports replace crate-name hyphens
+with underscores and use the generator's reserved-name rules.
+
+`crate_version` is optional. When omitted or nil, registry examples show
+`cargo add widget-client` (or `cargo add widget-client --features blocking`).
+Cargo chooses a compatible release according to its resolver, manifest,
+toolchain and existing lockfile. The server does not resolve it and never emits
+`version = "latest"`. To control version selection, supply a version such as
+`crate_version: '1.2.3'`. Its Cargo version-requirement semantics remain intact;
+it does not silently become an exact `=` constraint. Separate Tokio/serde_json
+requirements are still shown.
+
+Unpublished SDKs can use an explicit Git source instead of a registry release:
 
 ```ruby
-api.documentation_clients(
-  '1.0',
+api.documentation_clients('7.0',
   rust: {
-    snapshot_path: '/srv/api/sdk/schema/api-1.0.json',
-    generator_config_path: '/srv/api/sdk/generator.toml',
-    generator_version: HaveAPI::RustClient::VERSION
+    crate_name: 'vpsadmin-client',
+    source: {
+      git: 'https://github.com/vpsfreecz/vpsadmin-rust-client',
+      rev: 'ff876abe17e3301da62c1b6afbda055ec89db9d2'
+    }
   }
 )
 ```
 
-Use the exact generator version that produced the published SDK. The profile's
-package name and package version come from `crate_name` and `crate_version` in
-that SDK's existing [generator config](generation.md). They are independent of
-the API and HaveAPI package versions. Rust imports normalize crate-name hyphens
-to underscores. Configure a profile only for an SDK that users can install; the
-examples do not publish or generate that package.
-
-The server hides both Rust variants when that API version has no Rust profile.
-Invalid configured profiles fail at startup. A configured profile can still serve examples after unrelated additions to the
-live API. Each rendered sample must match the saved route,
-HTTP method, input and output layouts, and the contracts of the parameters it
-uses. The adapter
-checks the full SDK map against the current user's filtered help and sample;
-it never recomputes names from a reduced schema or prints hidden saved defaults.
-An unavailable action, changed parameter or unsupported value produces a short
-limitation in place of code. Filesystem paths remain outside rendered output.
+The emitted Cargo dependency contains that `git` and full `rev`; an explicitly
+supplied crate version additionally constrains the source package. Blocking
+examples add `features = ["blocking"]`. Only absolute HTTPS URLs without
+credentials/query/fragment/control characters and 40-hex revisions are accepted.
+Branches, tags, paths and custom registries are rejected. The server never
+fetches this repository or publishes the crate. Configuring its name or source
+does not establish that the SDK matches an API surface.
+
+At the end of mount, the server builds the adapter from the complete selected
+API version, including authentication routes and changes from post-mount hooks.
+The private structural copy excludes examples, prose and parameter defaults,
+while retaining canonical sibling names, ancestor paths and types. Requests use
+their own authorized help. Automatic mode assumes that the SDK matches the
+current generation contract; its package name or version alone cannot prove
+that. An older SDK can lack actions or use different names after additions or
+route changes.
+
+For an older or subset SDK, use the optional
+`snapshot_path: '/srv/api/sdk/schema/api-1.0.json'` with inline crate identity.
+The legacy `generator_config_path: '/srv/api/sdk/generator.toml'` is also retained
+as an alternative to inline `crate_name`/`crate_version`. It validates the full
+existing [generator configuration](generation.md) and may use either automatic
+schema or a saved snapshot. Do not mix the two identity forms. Saved file paths
+must be trusted absolute local paths; files are loaded during registration.
+Inline documentation does not need license, formatter or compiler packaging
+settings. An older pinned generator can use a suitable legacy file profile;
+automatic/inline mode requires the new factory interface and rejects missing
+support at startup.
+
+The server hides both Rust variants when no profile exists for that API version.
+Invalid profiles and actual generator-version mismatches fail startup. Adapter
+initialization occurs only once per mount and publishes no partial profiles on
+failure. Request-local authorized descriptions still control visible actions,
+fields and samples, including across users and locales. For saved models, each
+sample must match its route, method, layouts and supplied parameter contracts.
+Unavailable or stale samples produce a limitation. Private schema, hidden
+defaults, local paths and initialization diagnostics never enter rendered output.
+See the [server profile guide](../../../doc/client-examples.md) for compatibility
+and rollback requirements.
+
+The pure in-memory factories use the same resolve/render interface as legacy
+`Documentation.new(snapshot:, config:)`:
+
+```ruby
+adapter = HaveAPI::RustClient::Documentation.from_description(
+  description: full_description, api_version: '1.0',
+  protocol_version: HaveAPI::PROTOCOL_VERSION, mount_path: '/api/',
+  crate_name: 'widget-client', crate_version: nil, source: nil
+)
+# Or use Documentation.from_snapshot(snapshot:, crate_name:, crate_version: nil, source: nil).
+```
+
+Their internal structural URL is not an SDK provenance source or emitted request
+URL. Requests use the real server context. Actual SDK generation still requires
+its full versioned packaging configuration; these factories do not relax it.
 
 Both variants show a complete program and Cargo dependency comments. Async
 programs use Tokio and `.send().await?`. Blocking programs enable the SDK's
@@ -46,12 +105,11 @@ mounted root. Authenticated actions use advertised existing credentials from
 invent an OAuth acquisition flow or automatically follow token challenges.
 
 Object setters preserve null, zero, false and empty strings, and leave omitted
-fields unset.
-Lists use generated `Input` structs with `InputValue` fields and
+fields unset. Lists use generated `Input` structs with `InputValue` fields and
 `..Default::default()` for omitted values. GET lists and nested Custom query
-values produce limitations. The example DSL has no metadata input channel, so actions requiring metadata
-show a limitation. Responses expose
-`output`, typed `meta` and `http_status`. Fields accessed in examples must occur
+values produce limitations. The example DSL has no metadata input channel, so
+actions requiring metadata show a limitation. Responses expose `output`, typed
+`meta` and `http_status`. Fields accessed in examples must occur
 in the authorized sample. Rust provides explicit action-state calls rather
 than an automatic operation-wait helper. Request success and timeouts do not
 establish whether a server-side operation finished or was rolled back.

data/docs/generation.md

@@ -54,6 +54,10 @@ Acquisition timestamps, raw capture hashes, the source revision, resolved
 Ruby/Cargo locks and exact Rust toolchain belong in separate provenance.
 The generated ownership manifest records schema, runtime and generator-source
 digests, Ruby lock digest, configuration and the owned file inventory.
+The Ruby lock digest identifies the prepared lock shipped with the generator
+gem, or its local source-tree lock. It does not describe every dependency in a
+consumer's executing bundle. Prepare the source-tree lock with `bundle install`
+before generation and keep its bytes with the generation evidence.
 
 ## Configuration and crate scaffold
 
@@ -78,7 +82,9 @@ that differs from the configuration.
 It declares serde 1 with derive, serde_json 1, url 2.5, and reqwest 0.13.5 with
 `default-features = false` and `features = ["json", "rustls"]`. Features are
 `default = []` and `blocking = ["reqwest/blocking"]`. Tokio 1 with macros and
-rt-multi-thread supports tests/examples. Commit the consuming crate's Cargo.lock.
+rt-multi-thread supports tests/examples. Do not track Cargo.lock for a generated
+library. Applications and private test harnesses may track their lockfiles;
+retain their resolved inputs as verification evidence.
 Regeneration checks these requirements when the output is `src/generated`
 inside an existing crate. It reports mismatches and never replaces Cargo.toml
 or other handwritten package files.

data/docs/releasing.md

@@ -1,7 +1,7 @@
 # Packaging the Rust generator and generated clients
 
 The Ruby gem is `haveapi-rust-client` and follows HaveAPI's shared VERSION.
-`make version` updates its version, client dependency and tracked generator lock
+`make version` updates its version, client dependency and prepared local Ruby lock
 alongside existing components. The top-level release build includes this gem,
 and the protected publishing job uploads it after `haveapi-client`. Configure
 its RubyGems publisher before release; a new gem can use a pending publisher
@@ -12,9 +12,18 @@ registry setup, approval, retained artifacts and recovery.
 Prepare its package from `clients/rust` in the component Nix shell:
 
 ```sh
+bundle install
 bundle exec rake build
 ```
 
+The Ruby generator is a library: its Gemfile.lock is ignored by Git and records
+the dependencies resolved by ordinary Bundler preparation. Keep that lock fixed
+through the build and checks. Packaging requires it and includes its exact bytes
+in the gem for generation provenance; RubyGems dependency ranges remain the
+consumer installation contract. A fresh resolution may differ, so retain the
+actual lock and original artifacts rather than claiming commit-only
+reproducibility.
+
 The gem includes Ruby/ERB sources, the executable, documentation, Ruby dependency
 lock and maintained runtime source. It excludes the private Cargo harness and
 integration fixtures. The top-level `make release` builds and inspects this gem,
@@ -27,6 +36,11 @@ ruby utils/release/rust_smoke.rb dist
 ```
 
 The check loads the generator from the package and verifies its copied runtime.
+Fiddle is a runtime gem dependency that provides atomic directory exchange when
+replacing a generated tree. Prepare the component bundle before
+checking the package. The check must load `fiddle/import` from the installed,
+nondefault gem that satisfies the package's dependency requirement. Loading the
+generator requires Fiddle even when generating a new directory.
 Run the broader generator, runtime and generated-client checks as well.
 `make test-rust-unit` runs the quick generator specs; `make test-rust` covers
 those specs, both runtime feature configurations
@@ -35,7 +49,8 @@ Rust target. Publishing a new gem version requires separate authorization and
 approval in the protected release environment; `make publish` exits without
 publishing.
 
-Generated Rust crates have their own SemVer and Cargo.lock. Their API-version
+Generated Rust crates have their own SemVer. Do not track Cargo.lock for a
+generated library; applications may track it. Their API-version
 constant and schema digest identify the target independently of the crate
 version. Adding required input, changing public types or removing actions can
 require a breaking crate release; increasing the MSRV is a deliberate release
@@ -44,7 +59,8 @@ through optional fields and open string values.
 
 The embedded runtime has no separate registry release. Its `haveapi-runtime-tests`
 Cargo package is a private development harness with `publish = false`, not an
-artifact of HaveAPI's shared version. No crates.io token is needed to release
+artifact of HaveAPI's shared version. Its tracked Cargo.lock is retained.
+No crates.io token is needed to release
 the generator gem. Publish a generated crate through its consuming project's
 own release procedure and registry identity.
 
@@ -54,6 +70,30 @@ fixtures, the declared minimum Rust version and `cargo package`. Inspect the
 archive for copied runtime source and ordinary registry dependencies. No Ruby,
 HaveAPI checkout or private runtime crate should be needed to build it.
 
+Nested resource components retain their public double-underscore names, such as
+`project__task` and `authentication__token__token`. Generated module declarations
+and client accessor methods carrying that separator have a scoped
+`#[allow(non_snake_case)]`; ordinary generated identifiers and handwritten code
+keep their usual lint checks. The attributes change generated bytes and
+provenance while preserving public names and routes. Existing generated clients
+do not need regeneration.
+
+The focused naming check uses the real server fixture and treats that lint as
+an error for the generated crate under both the development toolchain and
+independently selected Rust 1.95. Prepare the environments from
+the [integration guide](../spec/integration/README.md), then run:
+
+```sh
+HAVEAPI_RUST_INTEGRATION=1 HAVEAPI_RUST_NAME_LINT=1 \
+HAVEAPI_RUST_MSRV_CARGO=/path/to/rust-1.95/bin/cargo \
+HAVEAPI_RUST_MSRV_RUSTC=/path/to/rust-1.95/bin/rustc \
+nix develop .#client-rust --command ruby clients/rust/spec/integration/run.rb
+```
+
+This mode compiles the fixture library with both transport features and
+`-D non_snake_case` at root and mounted API paths. The ordinary integration mode
+continues to execute the full protocol tests.
+
 A runtime source fix reaches consumers only after regeneration and release of
 each affected generated crate. Keep the prior schema, generator revision,
 lockfiles and generated revision available for recovery. Pinning a previous

data/lib/haveapi/rust_client/documentation.rb

@@ -2,24 +2,72 @@ require 'haveapi/rust_client'
 require 'date'
 
 module HaveAPI::RustClient
-  # Resolves the complete saved SDK before checking a request's authorized help.
-  # Construction is deliberately limited to the generator's pure validation/IR.
+  # Resolves the complete SDK model before checking a request's authorized help.
   class Documentation
+    include Model
+
     class Unsupported < StandardError; end
 
-    def initialize(snapshot:, config:)
-      @generator = Generator.new(schema: JSON.parse(Snapshot.canonical(snapshot)), config: JSON.parse(Snapshot.canonical(config)))
-      @snapshot = @generator.schema
-      @import = @generator.config.fetch('crate_name').tr('-', '_')
+    def self.from_description(description:, api_version:, protocol_version:, mount_path:,
+                              crate_name:, crate_version: nil, source: nil)
+      # Snapshot validation needs a structural origin; requests use context URLs.
+      snapshot = Snapshot.from_description(
+        description: JSON.parse(JSON.generate(description)), api_version:, protocol_version:, mount_path:,
+        source_url: "https://haveapi.invalid#{mount_path}v#{api_version}/", profile: 'server-documentation'
+      )
+      from_snapshot(snapshot:, crate_name:, crate_version:, source:)
+    end
+
+    def self.from_snapshot(snapshot:, crate_name:, crate_version: nil, source: nil)
+      new(snapshot:, crate_name:, crate_version:, source:)
+    end
+
+    def self.validate_source(source)
+      return nil if source.nil?
+      raise Error, 'invalid Rust SDK source' unless source.is_a?(Hash) && source.length == 2
+
+      values = source.to_h { |key, value| [key.to_s, value] }
+      url, revision = values.values_at('git', 'rev')
+      unless values.keys.sort == %w[git rev] && url.is_a?(String) && !url.match?(/[\x00-\x20\x7f]/) &&
+             revision.is_a?(String) && revision.match?(/\A[0-9a-fA-F]{40}\z/)
+        raise Error, 'invalid Rust SDK source'
+      end
+
+      uri = URI.parse(url)
+      unless uri.is_a?(URI::HTTPS) && uri.host && !uri.host.empty? &&
+             uri.userinfo.nil? && uri.query.nil? && uri.fragment.nil?
+        raise Error, 'invalid Rust SDK source'
+      end
+
+      values.transform_values { |value| value.dup.freeze }.freeze
+    rescue URI::InvalidURIError
+      raise Error, 'invalid Rust SDK source'
+    end
+
+    def initialize(snapshot:, config: nil, crate_name: nil, crate_version: nil, source: nil)
+      if config
+        raise Error, 'conflicting Rust SDK package settings' unless crate_name.nil? && crate_version.nil?
+
+        config = JSON.parse(Snapshot.canonical(config))
+        Generator.validate_config(config)
+        crate_name, crate_version = config.values_at('crate_name', 'crate_version')
+      end
+      Model.validate_package(crate_name:, crate_version:)
+      @crate_name = crate_name.dup
+      @crate_version = crate_version&.dup
+      @source = self.class.validate_source(source)
+      @snapshot = Snapshot.validate(JSON.parse(Snapshot.canonical(snapshot)))
+      @ir = IR.new(@snapshot)
+      @import = @crate_name.tr('-', '_')
       raise Error, 'crate name cannot be imported in Rust' if %w[crate self super].include?(@import)
 
       @import = "r##{@import}" if Naming::RESERVED.include?(@import)
-      @generator.ir.actions.each { |action| @generator.meta_parameters(action) }
-      freeze_data([@snapshot, @generator.config, @generator.ir.resources, @generator.ir.actions])
+      @ir.actions.each { |action| meta_parameters(action) }
+      freeze_data([@snapshot, @crate_name, @crate_version, @source, @import, @ir.resources, @ir.actions])
     end
 
     def resolve(resource_path:, action_name:)
-      @generator.ir.actions.find do |action|
+      @ir.actions.find do |action|
         action[:resource][:path] == resource_path.map(&:to_s) && action[:name] == action_name.to_s
       end
     end
@@ -69,11 +117,9 @@ module HaveAPI::RustClient
     end
 
     def program(context, mode, body, credentials: [])
-      config = @generator.config
-      dependencies = ["// Cargo.toml: #{config.fetch('crate_name')} = { version = #{literal(config.fetch('crate_version'))}" +
-        (mode == :blocking ? ', features = ["blocking"] }' : ' }')]
-      dependencies << '// Cargo.toml: tokio = { version = "1", features = ["macros", "rt-multi-thread"] }' if mode == :async
-      dependencies << '// Cargo.toml: serde_json = "1"'
+      dependencies = dependency_lines(mode)
+      dependencies << '// cargo add tokio --features macros,rt-multi-thread' if mode == :async
+      dependencies << '// cargo add serde_json'
       dependencies << '// Construct, use and drop this blocking client outside async runtime threads.' if mode == :blocking
       client = mode == :blocking ? "#{@import}::blocking::Client" : "#{@import}::Client"
       lines = dependencies + ["use #{client};", '']
@@ -87,6 +133,17 @@ module HaveAPI::RustClient
       lines.push('    Ok(())', '}', '').join("\n")
     end
 
+    def dependency_lines(mode)
+      unless @source || @crate_version
+        return ["// cargo add #{@crate_name}#{' --features blocking' if mode == :blocking}"]
+      end
+
+      fields = @source ? %w[git rev].map { |key| "#{key} = #{JSON.generate(@source.fetch(key))}" } : []
+      fields << "version = #{JSON.generate(@crate_version)}" if @crate_version
+      fields << 'features = ["blocking"]' if mode == :blocking
+      ["// Cargo.toml: #{@crate_name} = { #{fields.join(', ')} }"]
+    end
+
     def authentication(context, mode, method, description)
       provider = method.to_s
       live = normalize(context.description).fetch('authentication', {})[provider]
@@ -313,8 +370,7 @@ module HaveAPI::RustClient
     end
 
     def typed_literal(parameter, value)
-      # Ask the generator for the real type instead of duplicating name/type rules.
-      case @generator.rust_type(parameter)
+      case rust_type(parameter)
       when 'String' then "#{literal(value.respond_to?(:iso8601) ? value.iso8601 : value)}.to_owned()"
       when 'i64' then value == -(2**63) ? 'i64::MIN' : "#{value}_i64"
       when 'f64' then "#{value.to_f}_f64"

data/lib/haveapi/rust_client/generator.rb

@@ -7,11 +7,27 @@ require 'tomlrb'
 
 module HaveAPI::RustClient
   class Generator
+    include Model
+
     ROOT = File.expand_path('../../..', __dir__)
     CONFIG_KEYS = %w[crate_name crate_version license edition rust_version rustfmt_version].freeze
     OWNER_FILE = '.haveapi-generated.json'.freeze
     attr_reader :schema, :config, :ir
 
+    def self.validate_config(config)
+      unless config.is_a?(Hash) && config.keys.sort == CONFIG_KEYS.sort
+        raise Error, 'generator config keys do not match supported contract'
+      end
+
+      Model.validate_package(crate_name: config['crate_name'], crate_version: config['crate_version'], required_version: true)
+      unless config['license'] == 'MIT' && config['edition'] == '2024' && config['rust_version'] == '1.95' &&
+             config['rustfmt_version'].is_a?(String) && !config['rustfmt_version'].empty?
+        raise Error, 'unsupported license, Rust edition/MSRV or formatter configuration'
+      end
+
+      nil
+    end
+
     def initialize(schema:, config:)
       @schema = Snapshot.validate(schema)
       @config = config
@@ -69,15 +85,7 @@ module HaveAPI::RustClient
     private
 
     def validate_config
-      raise Error, 'generator config keys do not match supported contract' unless config.keys.sort == CONFIG_KEYS.sort
-      unless config['crate_name'].is_a?(String) && config['crate_name'].match?(/\A[a-z][a-z0-9_-]*\z/) &&
-             config['crate_version'].is_a?(String) && config['crate_version'].match?(/\A\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?\z/)
-        raise Error, 'invalid crate name/version'
-      end
-      unless config['license'] == 'MIT' && config['edition'] == '2024' && config['rust_version'] == '1.95' &&
-             config['rustfmt_version'].is_a?(String) && !config['rustfmt_version'].empty?
-        raise Error, 'unsupported license, Rust edition/MSRV or formatter configuration'
-      end
+      self.class.validate_config(config)
     end
 
     def validate_manifest(output)
@@ -260,16 +268,6 @@ module HaveAPI::RustClient
       value.split('_').map(&:capitalize).join
     end
 
-    def rust_type(parameter, output: false)
-      case parameter[:desc].fetch('type')
-      when 'String', 'Text', 'Datetime' then 'String'
-      when 'Integer', 'Resource' then output && parameter[:desc]['type'] == 'Resource' ? 'runtime::Association' : 'i64'
-      when 'Float' then 'f64'
-      when 'Boolean' then 'bool'
-      when 'Custom' then 'serde_json::Value'
-      end
-    end
-
     def input_type(action)
       return '()' unless action[:input]
 
@@ -282,17 +280,6 @@ module HaveAPI::RustClient
       action[:output][:layout].end_with?('_list') ? 'Vec<Output>' : 'Output'
     end
 
-    def meta_parameters(action)
-      values = [action[:global_output]]
-      values << action[:object_output] if action[:output] && !action[:output][:layout].end_with?('_list')
-      fields = values.compact.flat_map { |io| io[:parameters] }
-      fields.group_by { |field| field[:name] }.map do |name, matches|
-        raise Error, "inconsistent metadata field #{name}" if matches.map { |field| field[:desc] }.uniq.length > 1
-
-        matches.first
-      end.sort_by { |field| field[:name] }
-    end
-
     def parameter_specs(io)
       return '&[]' unless io
 

data/lib/haveapi/rust_client/model.rb

@@ -0,0 +1,35 @@
+module HaveAPI::RustClient
+  # Pure rules shared by generated SDKs and their documentation examples.
+  module Model
+    def self.validate_package(crate_name:, crate_version: nil, required_version: false)
+      unless crate_name.is_a?(String) && crate_name.match?(/\A[a-z][a-z0-9_-]*\z/) &&
+             ((crate_version.nil? && !required_version) ||
+              (crate_version.is_a?(String) && crate_version.match?(/\A\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?\z/)))
+        raise Error, 'invalid crate name/version'
+      end
+
+      nil
+    end
+
+    def rust_type(parameter, output: false)
+      case parameter[:desc].fetch('type')
+      when 'String', 'Text', 'Datetime' then 'String'
+      when 'Integer', 'Resource' then output && parameter[:desc]['type'] == 'Resource' ? 'runtime::Association' : 'i64'
+      when 'Float' then 'f64'
+      when 'Boolean' then 'bool'
+      when 'Custom' then 'serde_json::Value'
+      end
+    end
+
+    def meta_parameters(action)
+      values = [action[:global_output]]
+      values << action[:object_output] if action[:output] && !action[:output][:layout].end_with?('_list')
+      fields = values.compact.flat_map { |io| io[:parameters] }
+      fields.group_by { |field| field[:name] }.map do |name, matches|
+        raise Error, "inconsistent metadata field #{name}" if matches.map { |field| field[:desc] }.uniq.length > 1
+
+        matches.first
+      end.sort_by { |field| field[:name] }
+    end
+  end
+end

data/lib/haveapi/rust_client/version.rb

@@ -1,5 +1,5 @@
 module HaveAPI
   module RustClient
-    VERSION = '0.30.0'.freeze
+    VERSION = '0.30.1'.freeze
   end
 end

data/lib/haveapi/rust_client.rb

@@ -9,4 +9,5 @@ end
 require_relative 'rust_client/snapshot'
 require_relative 'rust_client/naming'
 require_relative 'rust_client/ir'
+require_relative 'rust_client/model'
 require_relative 'rust_client/generator'

data/template/resource.rs.erb

@@ -9,6 +9,10 @@ pub struct Handle<'a, C: runtime::Mode> {
     path_params: BTreeMap<String, String>,
 }
 impl<C: runtime::Mode> runtime::Client<C> {
+<% if resource[:module].include?('__') -%>
+    // Double underscores preserve resource component boundaries in the public API.
+    #[allow(non_snake_case)]
+<% end -%>
     pub fn <%= resource[:module] %>(&self<%= resource[:bound].map { |name| ", #{HaveAPI::RustClient::Naming.snake(name)}: impl ToString" }.join %>) -> Handle<'_, C> {
         let path_params = BTreeMap::from([<%= resource[:bound].map { |name| "(#{generator.literal(name)}.to_owned(), #{HaveAPI::RustClient::Naming.snake(name)}.to_string())" }.join(',') %>]);
         Handle { client: self, path_params }

data/template/resources.rs.erb

@@ -1,4 +1,8 @@
 // Generated resource modules. Component boundaries use double underscores.
 <% ir.resources.each do |resource| -%>
+<% if resource[:module].include?('__') -%>
+// Double underscores preserve resource component boundaries in the public API.
+#[allow(non_snake_case)]
+<% end -%>
 pub mod <%= resource[:module] %>;
 <% end -%>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: haveapi-rust-client
 version: !ruby/object:Gem::Version
-  version: 0.30.0
+  version: 0.30.1
 platform: ruby
 authors:
 - Jakub Skokan
@@ -9,20 +9,40 @@ bindir: bin
 cert_chain: []
 date: 1980-01-01 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.8
 - !ruby/object:Gem::Dependency
   name: haveapi-client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.30.0
+        version: 0.30.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.30.0
+        version: 0.30.1
 - !ruby/object:Gem::Dependency
   name: tomlrb
   requirement: !ruby/object:Gem::Requirement
@@ -58,6 +78,7 @@ files:
 - lib/haveapi/rust_client/documentation.rb
 - lib/haveapi/rust_client/generator.rb
 - lib/haveapi/rust_client/ir.rb
+- lib/haveapi/rust_client/model.rb
 - lib/haveapi/rust_client/naming.rb
 - lib/haveapi/rust_client/snapshot.rb
 - lib/haveapi/rust_client/version.rb