haveapi-rust-client 0.30.0

data/lib/haveapi/rust_client/snapshot.rb

@@ -0,0 +1,207 @@
+require 'json'
+require 'digest'
+require 'uri'
+
+module HaveAPI::RustClient
+  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
+    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')
+
+      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'
+      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
+    end
+  end
+end

data/lib/haveapi/rust_client/version.rb

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

data/lib/haveapi/rust_client.rb

@@ -0,0 +1,12 @@
+require_relative 'rust_client/version'
+
+module HaveAPI
+  module RustClient
+    class Error < StandardError; end
+  end
+end
+
+require_relative 'rust_client/snapshot'
+require_relative 'rust_client/naming'
+require_relative 'rust_client/ir'
+require_relative 'rust_client/generator'

data/runtime/src/runtime/auth.rs

@@ -0,0 +1,97 @@
+use std::fmt;
+
+use crate::runtime::Error;
+
+/// A credential requiring explicit access. Cloning does not zeroize its storage.
+#[derive(Clone, PartialEq, Eq)]
+pub struct SecretString(String);
+
+impl SecretString {
+    pub fn expose_secret(&self) -> &str {
+        &self.0
+    }
+}
+
+impl From<String> for SecretString {
+    fn from(value: String) -> Self {
+        Self(value)
+    }
+}
+
+impl From<&str> for SecretString {
+    fn from(value: &str) -> Self {
+        Self(value.to_owned())
+    }
+}
+
+impl fmt::Debug for SecretString {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("[REDACTED]")
+    }
+}
+
+impl fmt::Display for SecretString {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("[REDACTED]")
+    }
+}
+
+#[non_exhaustive]
+pub enum TokenStep {
+    Complete {
+        token: SecretString,
+    },
+    Challenge {
+        token: SecretString,
+        next_action: String,
+    },
+}
+
+impl TokenStep {
+    pub fn from_parts(
+        complete: bool,
+        token: Option<String>,
+        next_action: Option<String>,
+        known_steps: &[&str],
+    ) -> Result<Self, Error> {
+        let token = token
+            .filter(|token| !token.trim().is_empty())
+            .ok_or_else(|| Error::protocol(None, "authentication response is missing its token"))?;
+        if complete {
+            if next_action
+                .as_ref()
+                .is_some_and(|action| !action.is_empty())
+            {
+                return Err(Error::protocol(
+                    None,
+                    "completed authentication contains a continuation",
+                ));
+            }
+            Ok(Self::Complete {
+                token: token.into(),
+            })
+        } else {
+            let next_action = next_action
+                .filter(|action| !action.is_empty())
+                .ok_or_else(|| {
+                    Error::protocol(None, "authentication response is missing its continuation")
+                })?;
+            if !known_steps.contains(&next_action.as_str()) {
+                return Err(Error::UnsupportedAuthStep { next_action });
+            }
+            Ok(Self::Challenge {
+                token: token.into(),
+                next_action,
+            })
+        }
+    }
+}
+
+impl fmt::Debug for TokenStep {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(match self {
+            Self::Complete { .. } => "TokenStep::Complete { [REDACTED] }",
+            Self::Challenge { .. } => "TokenStep::Challenge { [REDACTED] }",
+        })
+    }
+}

data/runtime/src/runtime/client.rs

@@ -0,0 +1,380 @@
+use std::{collections::BTreeMap, fmt, marker::PhantomData, sync::Arc, time::Duration};
+
+use reqwest::header::{ACCEPT, AUTHORIZATION, HeaderMap, HeaderName, HeaderValue, USER_AGENT};
+use serde::{Serialize, de::DeserializeOwned};
+
+#[cfg(feature = "blocking")]
+use crate::runtime::BlockingTransport;
+use crate::runtime::{
+    ActionSpec, ApiSpec, AsyncTransport, Error, JsonMap, Mode, PreparedRequest, RequestAuth,
+    RequestParts, Response, Validate, decode, prepare,
+};
+
+pub struct ClientConfig {
+    pub(crate) base: url::Url,
+    pub(crate) headers: HeaderMap,
+    pub(crate) auth: Option<(HeaderName, HeaderValue)>,
+    pub(crate) timeout: Duration,
+    pub(crate) connect_timeout: Duration,
+    pub(crate) max_response_bytes: usize,
+}
+
+#[derive(Clone)]
+pub struct Client<C: Mode> {
+    config: Arc<ClientConfig>,
+    transport: C,
+}
+
+impl<C: Mode> Client<C> {
+    pub fn config(&self) -> &ClientConfig {
+        &self.config
+    }
+}
+
+enum Credentials {
+    Basic(String, String),
+    Token(String),
+    OAuth2(String),
+}
+
+pub struct ClientBuilder<C: Mode> {
+    base: String,
+    api: &'static ApiSpec,
+    credentials: Option<Credentials>,
+    auth_selections: usize,
+    timeout: Duration,
+    connect_timeout: Duration,
+    max_response_bytes: usize,
+    user_agent: String,
+    mode: PhantomData<C>,
+}
+
+impl<C: Mode> ClientBuilder<C> {
+    pub fn new(base: impl AsRef<str>, api: &'static ApiSpec) -> Self {
+        Self {
+            base: base.as_ref().to_owned(),
+            api,
+            credentials: None,
+            auth_selections: 0,
+            timeout: Duration::from_secs(30),
+            connect_timeout: Duration::from_secs(10),
+            max_response_bytes: 16 * 1024 * 1024,
+            user_agent: "haveapi-rust-client".into(),
+            mode: PhantomData,
+        }
+    }
+
+    pub fn basic_auth(mut self, username: impl Into<String>, password: impl Into<String>) -> Self {
+        self.credentials = Some(Credentials::Basic(username.into(), password.into()));
+        self.auth_selections += 1;
+        self
+    }
+
+    pub fn token(mut self, token: impl Into<String>) -> Self {
+        self.credentials = Some(Credentials::Token(token.into()));
+        self.auth_selections += 1;
+        self
+    }
+
+    pub fn oauth2_token(mut self, token: impl Into<String>) -> Self {
+        self.credentials = Some(Credentials::OAuth2(token.into()));
+        self.auth_selections += 1;
+        self
+    }
+
+    pub fn timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = timeout;
+        self
+    }
+    pub fn connect_timeout(mut self, timeout: Duration) -> Self {
+        self.connect_timeout = timeout;
+        self
+    }
+    pub fn max_response_bytes(mut self, bytes: usize) -> Self {
+        self.max_response_bytes = bytes;
+        self
+    }
+    pub fn user_agent(mut self, value: impl Into<String>) -> Self {
+        self.user_agent = value.into();
+        self
+    }
+
+    fn finish(self) -> Result<ClientConfig, Error> {
+        if self.api.protocol_major != 2 {
+            return Err(Error::configuration("unsupported HaveAPI protocol major"));
+        }
+        if self.api.api_version.is_empty() {
+            return Err(Error::configuration("API version is required"));
+        }
+        if self.auth_selections > 1 {
+            return Err(Error::configuration(
+                "select only one authentication method",
+            ));
+        }
+        if self.timeout.is_zero() || self.connect_timeout.is_zero() {
+            return Err(Error::configuration("HTTP timeouts must be positive"));
+        }
+        if self.max_response_bytes == 0 {
+            return Err(Error::configuration("response size limit must be positive"));
+        }
+        let base = crate::runtime::protocol::parse_base(&self.base)?;
+        let mut headers = HeaderMap::new();
+        headers.insert(ACCEPT, HeaderValue::from_static("application/json"));
+        headers.insert(
+            USER_AGENT,
+            HeaderValue::from_str(&self.user_agent)
+                .map_err(|_| Error::configuration("invalid user agent"))?,
+        );
+        let auth = match self.credentials {
+            None => None,
+            Some(Credentials::Basic(username, password)) => {
+                if !self.api.basic_auth {
+                    return Err(Error::configuration(
+                        "Basic authentication is not described",
+                    ));
+                }
+                if username.contains(':') {
+                    return Err(Error::configuration(
+                        "Basic username cannot contain a colon",
+                    ));
+                }
+                let encoded = base64(format!("{username}:{password}").as_bytes());
+                let mut value = HeaderValue::from_str(&format!("Basic {encoded}"))
+                    .map_err(|_| Error::configuration("invalid Basic authentication"))?;
+                value.set_sensitive(true);
+                Some((AUTHORIZATION, value))
+            }
+            Some(Credentials::Token(token)) => Some(token_header(self.api.token_header, token)?),
+            Some(Credentials::OAuth2(token)) => Some(token_header(self.api.oauth2_header, token)?),
+        };
+        Ok(ClientConfig {
+            base,
+            headers,
+            auth,
+            timeout: self.timeout,
+            connect_timeout: self.connect_timeout,
+            max_response_bytes: self.max_response_bytes,
+        })
+    }
+}
+
+impl ClientBuilder<AsyncTransport> {
+    pub fn build(self) -> Result<Client<AsyncTransport>, Error> {
+        let config = self.finish()?;
+        let transport = AsyncTransport::new(&config)?;
+        Ok(Client {
+            config: Arc::new(config),
+            transport,
+        })
+    }
+}
+
+#[cfg(feature = "blocking")]
+impl ClientBuilder<BlockingTransport> {
+    /// Build, use, and drop this client outside async runtime threads.
+    pub fn build(self) -> Result<Client<BlockingTransport>, Error> {
+        let config = self.finish()?;
+        let transport = BlockingTransport::new(&config)?;
+        Ok(Client {
+            config: Arc::new(config),
+            transport,
+        })
+    }
+}
+
+pub struct Request<'a, C: Mode, I, O, M> {
+    client: &'a Client<C>,
+    spec: &'static ActionSpec,
+    path_params: BTreeMap<String, String>,
+    input: I,
+    global_meta: Option<JsonMap>,
+    object_meta: Option<JsonMap>,
+    output: PhantomData<(O, M)>,
+}
+
+impl<'a, C: Mode, I, O, M> Request<'a, C, I, O, M> {
+    pub fn new(
+        client: &'a Client<C>,
+        spec: &'static ActionSpec,
+        path_params: BTreeMap<String, String>,
+        input: I,
+    ) -> Self {
+        Self {
+            client,
+            spec,
+            path_params,
+            input,
+            global_meta: None,
+            object_meta: None,
+            output: PhantomData,
+        }
+    }
+    pub fn input(mut self, input: I) -> Self {
+        *self.input_mut() = input;
+        self
+    }
+    pub fn global_meta(mut self, meta: JsonMap) -> Self {
+        self.global_meta = Some(meta);
+        self
+    }
+    pub fn object_meta(mut self, meta: JsonMap) -> Self {
+        self.object_meta = Some(meta);
+        self
+    }
+    pub(crate) fn input_mut(&mut self) -> &mut I {
+        &mut self.input
+    }
+}
+
+impl<C: Mode, I: Serialize + Validate, O, M> Request<'_, C, I, O, M> {
+    fn prepared(self) -> Result<PreparedRequest, Error> {
+        self.input.validate()?;
+        let input = if self.spec.input.is_some() {
+            Some(serde_json::to_value(self.input).map_err(|_| Error::Encode)?)
+        } else {
+            None
+        };
+        prepare(
+            &self.client.config,
+            self.spec,
+            RequestParts {
+                path_params: self.path_params,
+                input,
+                global_meta: self.global_meta,
+                object_meta: self.object_meta,
+            },
+        )
+    }
+}
+
+impl<I: Serialize + Validate, O: DeserializeOwned, M: DeserializeOwned>
+    Request<'_, AsyncTransport, I, O, M>
+{
+    pub async fn send(self) -> Result<Response<O, M>, Error> {
+        let client = self.client;
+        let spec = self.spec;
+        let request = self.prepared()?;
+        decode(spec, client.transport.execute(request).await?)
+    }
+}
+
+#[cfg(feature = "blocking")]
+impl<I: Serialize + Validate, O: DeserializeOwned, M: DeserializeOwned>
+    Request<'_, BlockingTransport, I, O, M>
+{
+    pub fn send(self) -> Result<Response<O, M>, Error> {
+        let client = self.client;
+        let spec = self.spec;
+        let request = self.prepared()?;
+        decode(spec, client.transport.execute(request)?)
+    }
+}
+
+fn token_header(header: Option<&str>, token: String) -> Result<(HeaderName, HeaderValue), Error> {
+    let name = HeaderName::from_bytes(
+        header
+            .ok_or_else(|| Error::configuration("requested token provider is not described"))?
+            .as_bytes(),
+    )
+    .map_err(|_| Error::configuration("invalid authentication header name"))?;
+    if matches!(
+        name.as_str(),
+        "host"
+            | "content-length"
+            | "content-type"
+            | "accept"
+            | "user-agent"
+            | "connection"
+            | "transfer-encoding"
+            | "proxy-authorization"
+            | "proxy-authenticate"
+            | "te"
+            | "trailer"
+            | "upgrade"
+            | "cookie"
+            | "referer"
+            | "location"
+    ) {
+        return Err(Error::configuration("reserved authentication header name"));
+    }
+    if token.trim().is_empty() {
+        return Err(Error::configuration("token cannot be empty"));
+    }
+    let mut value = HeaderValue::from_str(&token)
+        .map_err(|_| Error::configuration("invalid token header value"))?;
+    value.set_sensitive(true);
+    Ok((name, value))
+}
+
+fn base64(bytes: &[u8]) -> String {
+    const TABLE: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    let mut result = String::with_capacity(bytes.len().div_ceil(3) * 4);
+    for chunk in bytes.chunks(3) {
+        let first = chunk[0];
+        let second = chunk.get(1).copied().unwrap_or(0);
+        let third = chunk.get(2).copied().unwrap_or(0);
+        result.push(TABLE[usize::from(first >> 2)] as char);
+        result.push(TABLE[usize::from((first & 3) << 4 | second >> 4)] as char);
+        result.push(if chunk.len() > 1 {
+            TABLE[usize::from((second & 15) << 2 | third >> 6)] as char
+        } else {
+            '='
+        });
+        result.push(if chunk.len() > 2 {
+            TABLE[usize::from(third & 63)] as char
+        } else {
+            '='
+        });
+    }
+    result
+}
+
+impl fmt::Debug for ClientConfig {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("ClientConfig { [REDACTED] }")
+    }
+}
+impl<C: Mode> fmt::Debug for Client<C> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("Client { [REDACTED] }")
+    }
+}
+impl<C: Mode> fmt::Debug for ClientBuilder<C> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("ClientBuilder { [REDACTED] }")
+    }
+}
+impl<C: Mode, I, O, M> fmt::Debug for Request<'_, C, I, O, M> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("Request { [REDACTED] }")
+    }
+}
+
+impl ClientConfig {
+    pub(crate) fn request_headers(&self, auth: RequestAuth) -> HeaderMap {
+        let mut headers = self.headers.clone();
+        if auth == RequestAuth::Configured
+            && let Some((name, value)) = &self.auth
+        {
+            headers.insert(name.clone(), value.clone());
+        }
+        headers
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn basic_encoding_matches_rfc7617() {
+        assert_eq!(
+            base64(b"Aladdin:open sesame"),
+            "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
+        );
+        assert_eq!(base64(b""), "");
+        assert_eq!(base64(b"a"), "YQ==");
+        assert_eq!(base64(b"ab"), "YWI=");
+        assert_eq!(base64(b"abc"), "YWJj");
+    }
+}