haveapi-rust-client 0.30.2 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96e9f24f598297eaaea7bce5ae34feaad34b8bb8db00af2c854602d686e5c267
-  data.tar.gz: 2671a364e42f99c7b44e704820c05653f999fb57844f289e09d7991ccfeb946e
+  metadata.gz: bbefec00a6d665ac94f470cffd1e57ee56d29b8d999fad1e285e3ed9372bea83
+  data.tar.gz: c6f8b97f567dc89e702c527584410e1de27301a0b212f22e08e3f4d6d8b6aedd
 SHA512:
-  metadata.gz: 821fb5d7d22dd75afe6b5dedbeff675ad7141873fda8af9c7da55b24cc394e2a26bbc96af10d0d1a425249e41d3b12218384d8cfe5f7cf4884826f12129caa73
-  data.tar.gz: 450823127999c9458b96607d7f25fae0ec4d49d38857f9d1d157f51aae4dee00ec900a940e2bf74e834a27e78d29b115435a988d80a0a5760bd1e76a35971a98
+  metadata.gz: 6773bee64ceb3f14225915b063e481904acc116e030f408c6212d4ad5ab622293dab564685d517aaf337ebd2d926d1e43472c58ed18586038da24fae7b3c94ec
+  data.tar.gz: fcc4a3fcc8fb177f1a8e01634b42fd6baf6b24a4f531f212084a6297cb077552ca7967bbabea52af5dcbd4fa4c6f84f44710693e4dfa9414f7c1119712fe29fd

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../ruby
   specs:
-    haveapi-client (0.30.2)
+    haveapi-client (0.31.0)
       activesupport (>= 7.0)
       highline (~> 3.1)
       json
@@ -12,9 +12,9 @@ PATH
 PATH
   remote: .
   specs:
-    haveapi-rust-client (0.30.2)
+    haveapi-rust-client (0.31.0)
       fiddle (~> 1.1, >= 1.1.8)
-      haveapi-client (~> 0.30.2)
+      haveapi-client (~> 0.31.0)
       tomlrb (~> 2.0)
 
 GEM
@@ -156,8 +156,8 @@ CHECKSUMS
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
   fiddle (1.1.8) sha256=7fa8ee3627271497f3add5503acdbc3f40b32f610fc1cf49634f083ef3f32eee
   hana (1.3.7) sha256=5425db42d651fea08859811c29d20446f16af196308162894db208cac5ce9b0d
-  haveapi-client (0.30.2)
-  haveapi-rust-client (0.30.2)
+  haveapi-client (0.31.0)
+  haveapi-rust-client (0.31.0)
   highline (3.1.2) sha256=67cbd34d19f6ef11a7ee1d82ffab5d36dfd5b3be861f450fc1716c7125f4bb4a
   http-accept (1.7.0) sha256=c626860682bfbb3b46462f8c39cd470fd7b0584f61b3cc9df5b2e9eb9972a126
   http-cookie (1.1.6) sha256=ba4b82be64de61dc281243dac70e3c382c45142f20268ed9276a3670c93feaa9

data/README.md

@@ -1,85 +1,174 @@
 # Rust client generator
 
-This Ruby generator turns a saved HaveAPI protocol 2 description into a typed,
-self-contained Rust client for one explicit API version. The generated client
-uses async reqwest by default and offers the same actions through the optional
-`blocking` feature. Ruby and HaveAPI are generation tools, not dependencies of
-the resulting Rust crate.
+Generate a typed Rust client for one explicit API version from a saved
+[HaveAPI](https://github.com/vpsfreecz/haveapi) protocol 2 description. Generated
+clients support async calls and an optional `blocking` feature. Their resource
+names and routes are fixed; applications do not need Ruby or runtime discovery.
 
-The client contract uses edition 2024, Rust 1.95 or newer, Serde, url 2.5,
-and reqwest 0.13.5 with verified rustls TLS. Generation requires the exact
-formatter version recorded in the client configuration. New test fixtures use
-the formatter from the HaveAPI Nix shell; existing clients retain their own
-recorded formatter. A separate acceptance check verifies Rust 1.95 because the
-development compiler is newer.
+## Prepare the source tools and crate
 
-## Development
-
-From the HaveAPI root:
+From the HaveAPI checkout root:
 
 ```sh
 nix develop .#client-rust
-cd clients/rust
-bundle exec rspec spec/unit
-bundle exec rubocop lib bin spec/unit spec/spec_helper.rb haveapi-rust-client.gemspec
+BUNDLE_GEMFILE="$PWD/clients/rust/Gemfile" bundle install
+mkdir -p /path/to/widget-client/schema /path/to/widget-client/src
 ```
 
-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.
+The component shell supplies Ruby 3.2 or newer, Rust and `rustfmt`, and prepares
+an isolated Ruby bundle using the Ruby client from the same checkout. Retain the
+checkout revision and resolved component lock with your generation inputs.
 
-`make test-rust-unit` runs the generator specs. `make test-rust` additionally
-runs both runtime feature configurations and the generated-client protocol
-harness. Compilation, linting Rust, server integration, MSRV and packaging can
-take longer; use the development workspace's verification procedure when
-working there. Unit specs never start a server or invoke Cargo.
+Create `/path/to/widget-client/Cargo.toml`:
 
-## Generate a client
+```toml
+[package]
+name = "widget-client"
+version = "0.1.0"
+license = "MIT"
+edition = "2024"
+rust-version = "1.95"
 
-Keep acquisition separate from generation:
+[features]
+default = []
+blocking = ["reqwest/blocking"]
 
-```sh
-bundle exec haveapi-rust-client fetch https://api.example.test/v1.0/ \
-  --api-version 1.0 --profile public --output schema/api-1.0.json
-bundle exec haveapi-rust-client generate --schema schema/api-1.0.json \
-  --api-version 1.0 --config generator.toml --output src/generated
-bundle exec haveapi-rust-client generate --schema schema/api-1.0.json \
-  --api-version 1.0 --config generator.toml --output src/generated --check
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+url = "2.5"
+reqwest = { version = "0.13.5", default-features = false, features = ["json", "rustls"] }
+
+[dev-dependencies]
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
 ```
 
-Run these commands from the consuming project with this generator available in
-its Bundler environment. The explicit URL includes the selected version.
-Neither command selects the server's default API version. Offline generation
-uses only the saved schema, generator configuration, locked Ruby dependencies,
-maintained runtime source and pinned formatter.
+Record the selected formatter in `/path/to/widget-client/generator.toml`:
 
-The handwritten crate entry point is:
+```sh
+cat > /path/to/widget-client/generator.toml <<EOF
+crate_name = "widget-client"
+crate_version = "0.1.0"
+license = "MIT"
+edition = "2024"
+rust_version = "1.95"
+rustfmt_version = "$(rustfmt --version)"
+EOF
+```
+
+Add the handwritten entry point `/path/to/widget-client/src/lib.rs`:
 
 ```rust
 mod generated;
 pub use generated::*;
 ```
 
-A generated action looks like
-`api.vps().update(123).hostname("example").send().await?`. The blocking client
-uses `blocking::Client` and ends the same chain in `.send()?`. Construct, use and
-drop a blocking client outside an async runtime, or put its entire lifecycle
-inside `tokio::task::spawn_blocking`. See the [runtime contract](runtime/README.md)
-for authentication, errors, deadlines and blocking restrictions.
+The generator checks the existing crate manifest; it does not create or replace
+it. See [crate configuration](docs/generation.md#configuration-and-crate-scaffold)
+for formatter selection and dependencies. Building the TLS dependencies can
+require a C toolchain.
+
+## Fetch, save and generate
+
+The example API at `https://example.test/v1.0/` has `Widget#Update` with path
+`/v1.0/widgets/{widget_id}`, a nullable string `name` input, and `id` and `name`
+outputs. Replace the example URL, version and resource names with those of your
+API.
+
+From the HaveAPI root in the prepared component environment:
+
+```sh
+BUNDLE_GEMFILE="$PWD/clients/rust/Gemfile" bundle exec ruby \
+  clients/rust/bin/haveapi-rust-client fetch https://example.test/v1.0/ \
+  --api-version 1.0 --profile public \
+  --output /path/to/widget-client/schema/api.json
+BUNDLE_GEMFILE="$PWD/clients/rust/Gemfile" bundle exec ruby \
+  clients/rust/bin/haveapi-rust-client generate \
+  --schema /path/to/widget-client/schema/api.json --api-version 1.0 \
+  --config /path/to/widget-client/generator.toml \
+  --output /path/to/widget-client/src/generated
+BUNDLE_GEMFILE="$PWD/clients/rust/Gemfile" bundle exec ruby \
+  clients/rust/bin/haveapi-rust-client generate \
+  --schema /path/to/widget-client/schema/api.json --api-version 1.0 \
+  --config /path/to/widget-client/generator.toml \
+  --output /path/to/widget-client/src/generated --check
+```
+
+The schema's parent directory must exist. Fetch uses the exact mounted version
+endpoint; it does not choose a server default. Generation uses local schema,
+configuration, prepared dependencies, embedded runtime and the recorded formatter.
+It makes no network request or dependency installation. `--check` reports stale
+output without changing it. Keep handwritten files outside `src/generated`.
 
-Read the [integration harness guide](spec/integration/README.md) for fixture
-setup and acceptance commands.
+For Basic capture, set `WIDGET_PASSWORD` in your environment, then run:
 
-Read [generation and snapshots](docs/generation.md) for configuration, naming,
-metadata fidelity and ownership rules, and [packaging](docs/releasing.md) before
-preparing a generator or generated-client release.
+```sh
+BUNDLE_GEMFILE="$PWD/clients/rust/Gemfile" bundle exec ruby \
+  clients/rust/bin/haveapi-rust-client fetch https://example.test/v1.0/ \
+  --api-version 1.0 --profile basic-user --basic-user demo \
+  --basic-password-env WIDGET_PASSWORD \
+  --output /path/to/widget-client/schema/api.json
+```
+
+For an existing HaveAPI token, set `WIDGET_TOKEN` and run:
+
+```sh
+BUNDLE_GEMFILE="$PWD/clients/rust/Gemfile" bundle exec ruby \
+  clients/rust/bin/haveapi-rust-client fetch https://example.test/v1.0/ \
+  --api-version 1.0 --profile token-user --token-env WIDGET_TOKEN \
+  --output /path/to/widget-client/schema/api.json
+```
+
+These authentication choices are mutually exclusive. Token capture uses anonymous
+discovery at the same endpoint to select the advertised token header. Supply a
+token you have already acquired. `--profile` labels the capture; it does not
+change authentication. Permissions and enabled plugins determine which resources
+the snapshot contains. Review saved defaults and
+data before sharing it. Never retain credentials or tokens. Failed capture leaves
+an existing output file intact.
+
+## Use the generated client locally
+
+In an application, refer to the crate you generated:
+
+```toml
+[dependencies]
+widget-client = { path = "/path/to/widget-client" }
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+```
+
+```rust
+use widget_client::Client;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let api = Client::builder("https://example.test").build()?;
+    let result = api.widget().update(1).name("new name".to_owned()).send().await?;
+    println!("Name: {:?}", result.output.name);
+    Ok(())
+}
+```
 
-The [server documentation adapter](docs/documentation.md) provides optional
-async and blocking examples for a configured published SDK profile.
+Give the builder the API root and mount prefix without `/v1.0`; generated routes
+already contain the version. Protected actions can use `.basic_auth(user,
+password)` or `.token(std::env::var("WIDGET_TOKEN")?)` before `.build()`, when
+advertised by the API. Server permissions still apply.
+
+For synchronous use, enable `features = ["blocking"]` on the same local crate,
+import `widget_client::blocking::Client` and call `.send()?`. Construct, use and
+drop a blocking client outside an async runtime; see the
+[runtime contract](runtime/README.md#authentication-and-transport-policy).
+
+Only fields you set are sent. Results contain typed `output`, metadata in `meta`
+and `http_status`; optional outputs reflect fields hidden or omitted by the
+server. Transport, HTTP/API and decoding failures return errors. See
+[snapshots and generation](docs/generation.md) for ownership, recovery, naming,
+null handling and source digests, and the [runtime reference](runtime/README.md)
+for authentication and timeouts.
+
+## Development and reference
+
+- [Generator development](docs/development.md)
+- [Integration harness](spec/integration/README.md)
+- [Packaging and releases](docs/releasing.md)
+- [Server documentation profiles](docs/documentation.md)

data/docs/development.md

@@ -0,0 +1,38 @@
+# Rust generator development
+
+From the HaveAPI root:
+
+```sh
+nix develop .#client-rust
+cd clients/rust
+bundle exec rspec spec/unit
+bundle exec rubocop lib bin spec/unit spec/spec_helper.rb haveapi-rust-client.gemspec
+```
+
+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.
+
+From the HaveAPI root, `make test-rust-unit` runs the generator specs.
+`make test-rust` additionally runs both runtime feature configurations and the
+generated-client protocol harness. Unit specs never start a server or invoke
+Cargo. Compilation, Rust linting, server integration, MSRV and packaging checks
+can take longer; follow the development workspace's verification procedure when
+working there.
+
+The Nix shell supplies the development compiler and formatter. New test
+fixtures record that formatter; existing clients retain their own exact
+configured formatter. A separate acceptance check verifies Rust 1.95 because
+the development compiler is newer. See
+[generation configuration](generation.md#configuration-and-crate-scaffold), the
+[runtime checks](../runtime/README.md#development-checks), the
+[integration harness](../spec/integration/README.md) and
+[packaging](releasing.md) for the corresponding commands and input requirements.

data/lib/haveapi/rust_client/cli.rb

@@ -5,12 +5,17 @@ require 'haveapi/rust_client'
 module HaveAPI::RustClient
   class Cli
     def self.run(argv = ARGV, out: $stdout, err: $stderr)
+      argv = argv.dup
       command = argv.shift
+      if command == 'fetch'
+        return HaveAPI::Schema::FetchCommand.run(argv, out:, err:, command_name: 'haveapi-rust-client')
+      end
+
+      argv.unshift(command) if %w[-h --help].include?(command)
       options = {}
       parser = OptionParser.new do |opts|
         opts.banner = 'Usage: haveapi-rust-client fetch URL | generate [options]'
         opts.on('--api-version VERSION') { |value| options[:version] = value }
-        opts.on('--profile PROFILE') { |value| options[:profile] = value }
         opts.on('--schema FILE') { |value| options[:schema] = value }
         opts.on('--config FILE') { |value| options[:config] = value }
         opts.on('--output PATH') { |value| options[:output] = value }
@@ -25,14 +30,6 @@ module HaveAPI::RustClient
       raise Error, '--output is required' unless options[:output]
 
       case command
-      when 'fetch'
-        raise Error, 'fetch requires one explicit version URL and --profile' unless argv.length == 1 && options[:profile]
-        raise Error, '--check is supported only for generation' if options[:check]
-
-        diagnostics = []
-        snapshot = Snapshot.fetch(url: argv.first, api_version: options[:version], profile: options[:profile], diagnostics:)
-        diagnostics.each { |message| err.puts(message) }
-        File.write(options[:output], Snapshot.canonical(snapshot))
       when 'generate'
         unless argv.empty? && options[:schema] && options[:config]
           raise Error, 'generate requires --schema and --config'

data/lib/haveapi/rust_client/generator.rb

@@ -158,7 +158,7 @@ module HaveAPI::RustClient
 
     def generator_digest
       paths = Dir.chdir(ROOT) { Dir['lib/**/*.rb', 'template/**/*'].select { |path| File.file?(path) }.sort }
-      digest_files(paths, ROOT)
+      Digest::SHA256.hexdigest("#{digest_files(paths, ROOT)}\0#{Snapshot.canonical(HaveAPI::Schema.source_identity)}")
     end
 
     def digest_files(paths, root)

data/lib/haveapi/rust_client/snapshot.rb

@@ -1,207 +1,32 @@
-require 'json'
-require 'digest'
-require 'uri'
+begin
+  require 'haveapi/schema'
+rescue LoadError
+  raise HaveAPI::RustClient::Error,
+        'shared haveapi-client schema API is unavailable; prepare the component bundle from this source release'
+end
 
 module HaveAPI::RustClient
+  # Keep the generator API/error boundary while sharing one portable format.
   module Snapshot
-    KEYS = %w[schema_format api_version protocol_version source_url profile mount_path description].freeze
-    PROSE = %w[description label examples message comment title].freeze
-
-    def self.canonical(value)
-      normalized = case value
-                   when Hash
-                     value.keys.map(&:to_s).sort.to_h do |key|
-                       [key, canonical_value(value.fetch(key))]
-                     end
-                   else
-                     canonical_value(value)
-                   end
-      "#{JSON.pretty_generate(normalized)}\n"
-    end
-
-    def self.canonical_value(value)
-      case value
-      when Hash
-        value.keys.sort.to_h { |key| [key, canonical_value(value.fetch(key))] }
-      when Array
-        value.map { |item| canonical_value(item) }
-      else
-        value
-      end
-    end
-
-    def self.sha256(snapshot)
-      Digest::SHA256.hexdigest(canonical(snapshot))
-    end
-
-    def self.load(path)
-      validate(JSON.parse(File.read(path)))
-    rescue JSON::ParserError
-      raise Error, 'snapshot is not valid JSON'
-    end
-
-    def self.fetch(url:, api_version:, profile:, diagnostics: [])
-      require 'haveapi/client'
-      version!(api_version)
-      endpoint = endpoint!(url)
-      suffix = "/v#{api_version}/"
-      raise Error, 'fetch URL must select the exact requested version' unless endpoint.path.end_with?(suffix)
-
-      mount = endpoint.path.delete_suffix("v#{api_version}/")
-      # The shared metadata client owns parsing/protocol compatibility. Keep the
-      # explicit version request at the supplied mount and disable redirects.
-      root = endpoint.dup
-      root.path = mount
-      communicator = HaveAPI::Client::Communicator.new(root.to_s)
-      communicator.instance_variable_set(
-        :@rest,
-        RestClient::Resource.new(root.to_s, max_redirects: 0, open_timeout: 10, read_timeout: 30)
-      )
-      description = communicator.describe_api(api_version)
-      from_description(
-        description: JSON.parse(JSON.generate(description)),
-        api_version:, protocol_version: communicator.instance_variable_get(:@proto_version),
-        source_url: url, profile:, mount_path: mount, diagnostics:
-      )
-    rescue HaveAPI::Client::ProtocolError
-      raise Error, 'incompatible HaveAPI protocol version'
-    rescue RestClient::Exception, URI::InvalidURIError
-      raise Error, 'metadata acquisition failed (HTTP, redirect or URL error)'
-    end
-
-    def self.from_envelope(envelope, api_version:, source_url:, profile:, mount_path: '/', diagnostics: [])
-      raise Error, 'metadata envelope is not successful' unless envelope['status'] == true
-
-      from_description(
-        description: envelope.fetch('response'), protocol_version: envelope.fetch('version'),
-        api_version:, source_url:, profile:, mount_path:, diagnostics:
-      )
-    rescue KeyError
-      raise Error, 'metadata envelope is incomplete'
-    end
-
-    def self.from_description(description:, api_version:, protocol_version:, source_url:, profile:, mount_path: '/', diagnostics: [])
-      snapshot = {
-        'schema_format' => 1, 'api_version' => api_version, 'protocol_version' => protocol_version,
-        'source_url' => source_url, 'profile' => profile, 'mount_path' => mount_path,
-        'description' => sanitize(description, diagnostics:)
-      }
-      validate(snapshot)
-    end
-
-    # Prose is removed only from structural description objects. Parameter names,
-    # validator choice keys and Custom/default JSON are data, never filter keys.
-    def self.sanitize(value, context = :description, diagnostics: [], path: [])
-      return value.map { |item| sanitize(item, context, diagnostics:, path:) } if value.is_a?(Array)
-      return value unless value.is_a?(Hash)
-
-      value.each_with_object({}) do |(key, item), result|
-        next if PROSE.include?(key) && !%i[map data choices].include?(context)
-
-        if context == :description && key == 'default' && value['protected'] == true && !item.nil?
-          diagnostics << "removed protected default: #{path.join('/')}"
-          next
-        end
-
-        validate_machine_endpoint(key, item) if context == :description
-        child_context = sanitization_context(context, key, item)
-        result[key] = if context == :validators && key == 'custom'
-                        true
-                      elsif context == :choices
-                        nil
-                      else
-                        sanitize(item, child_context, diagnostics:, path: path + [key])
-                      end
-      end
+    unless defined?(HaveAPI::Schema::Snapshot) && HaveAPI::Schema.respond_to?(:source_identity)
+      raise Error, 'loaded haveapi-client does not provide the required shared schema API'
     end
 
-    def self.validate_machine_endpoint(key, value)
-      return if value.nil?
-      return endpoint!(value) if key.end_with?('_url')
-      return unless %w[path help].include?(key) || key.end_with?('_path')
+    KEYS = HaveAPI::Schema::Snapshot::KEYS
+    PROSE = HaveAPI::Schema::Snapshot::PROSE
 
-      path, query = value.is_a?(String) ? value.split('?', 2) : [nil, nil]
-      unless path && path.start_with?('/') && !path.include?('#') && safe_segments?(path) &&
-             (query.nil? || (key == 'help' && query.match?(/\Amethod=(?:GET|POST|PUT|PATCH|DELETE|OPTIONS)\z/)))
-        raise Error, 'unsafe machine endpoint in API description'
+    %i[canonical canonical_value sha256 load validate sanitize from_description from_envelope version! endpoint! safe_path? safe_segments? child_context sanitization_context machine_endpoint! validate_machine_endpoint validate_machine_endpoints].each do |name|
+      define_singleton_method(name) do |*args, **kwargs, &block|
+        HaveAPI::Schema::Snapshot.public_send(name, *args, **kwargs, &block)
+      rescue HaveAPI::Schema::Error => e
+        raise Error, e.message
       end
     end
 
-    def self.sanitization_context(context, key, item)
-      return :data if %i[data choices].include?(context)
-      return :description if context == :map
-      return :map if %w[resources actions parameters authentication].include?(key)
-      return :data if %w[default format].include?(key) && context != :validator
-      return item.is_a?(Hash) ? :choices : :data if key == 'values'
-      return :validators if key == 'validators'
-      return :validator if context == :validators
-
-      :description
-    end
-
-    def self.validate(snapshot)
-      raise Error, 'snapshot must be an object' unless snapshot.is_a?(Hash)
-      raise Error, 'unsupported snapshot envelope keys' unless snapshot.keys.sort == KEYS.sort
-      raise Error, 'unsupported snapshot format' unless snapshot['schema_format'] == 1
-
-      version!(snapshot['api_version'])
-      protocol = snapshot['protocol_version']
-      raise Error, 'unsupported HaveAPI protocol major' unless protocol.is_a?(String) && protocol.match?(/\A2\.\d+\z/)
-      raise Error, 'profile must be a nonempty label' unless snapshot['profile'].is_a?(String) && !snapshot['profile'].empty?
-
-      endpoint = endpoint!(snapshot['source_url'])
-      mount = snapshot['mount_path']
-      unless mount.is_a?(String) && mount.start_with?('/') && mount.end_with?('/') && safe_segments?(mount)
-        raise Error, 'invalid capture mount path'
-      end
-
-      expected = "#{mount}v#{snapshot['api_version']}/"
-      raise Error, 'snapshot source URL/version mismatch' unless endpoint.path == expected
-
-      description = snapshot['description']
-      unless description.is_a?(Hash) && description['resources'].is_a?(Hash) &&
-             description['authentication'].is_a?(Hash) && description['meta'].is_a?(Hash)
-        raise Error, 'invalid API description structure'
-      end
-      raise Error, 'snapshot description/version mismatch' unless description['help'] == expected
-
-      description.fetch('authentication').each do |provider, config|
-        raise Error, "invalid authentication description for #{provider}" unless config.is_a?(Hash)
-
-        config.each do |key, value|
-          endpoint!(value) if key.end_with?('_url') && value
-          next unless key.end_with?('_path') && value
-          next if value.is_a?(String) && value.start_with?('/') && !value.match?(/[?#]/) && safe_segments?(value)
-
-          raise Error, "unsafe authentication path for #{provider}"
-        end
-      end
-      snapshot
-    end
-
-    def self.version!(version)
-      return if version.is_a?(String) && version.match?(/\A\d+(?:\.\d+)*\z/)
-
-      raise Error, 'an explicit numeric API version is required'
-    end
-
-    def self.endpoint!(url)
-      endpoint = URI.parse(url)
-      unless %w[http https].include?(endpoint.scheme) && endpoint.host &&
-             endpoint.userinfo.nil? && endpoint.query.nil? && endpoint.fragment.nil? && safe_segments?(endpoint.path)
-        raise Error, 'endpoint must be an HTTP URL without credentials, query or fragment'
-      end
-
-      endpoint
-    rescue URI::InvalidURIError, TypeError
-      raise Error, 'invalid endpoint URL'
-    end
-
-    def self.safe_segments?(path)
-      !path.include?('\\') && !path.start_with?('//') && path.split('/').none? do |segment|
-        decoded = URI::DEFAULT_PARSER.unescape(segment)
-        %w[. ..].include?(decoded) || decoded.match?(%r{[/\\\x00-\x1f\x7f]})
-      end
+    def self.fetch(**)
+      HaveAPI::Schema::Capture.fetch(**)
+    rescue HaveAPI::Schema::Error => e
+      raise Error, e.message
     end
   end
 end

data/lib/haveapi/rust_client/version.rb

@@ -1,5 +1,5 @@
 module HaveAPI
   module RustClient
-    VERSION = '0.30.2'.freeze
+    VERSION = '0.31.0'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: haveapi-rust-client
 version: !ruby/object:Gem::Version
-  version: 0.30.2
+  version: 0.31.0
 platform: ruby
 authors:
 - Jakub Skokan
@@ -35,14 +35,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.30.2
+        version: 0.31.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.30.2
+        version: 0.31.0
 - !ruby/object:Gem::Dependency
   name: tomlrb
   requirement: !ruby/object:Gem::Requirement
@@ -70,6 +70,7 @@ files:
 - LICENSE.txt
 - README.md
 - bin/haveapi-rust-client
+- docs/development.md
 - docs/documentation.md
 - docs/generation.md
 - docs/releasing.md