servicestack 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5d4c81df4c0df47d185c8f942f3da2e61983d149eb74ac128e03005eb9af30b3
+  data.tar.gz: 15f64c2c49f10e6803ff8a722edb1faeb20c670d99350103848390ab291239a9
+SHA512:
+  metadata.gz: 204756127fbd7b57d41c521f7f65824ba804c1bbd5c3487fdb9b4561eaba3c91847fe525c96e59092c2058f178948c44e105eb3a2bd21480ce662d719befa220
+  data.tar.gz: 6d29f98815d56c1dd66eb7e8982226b68288d20799569954b83a55c098aa9a2f5e2cdd5629c8d1bf8f6aa09313649b805ef701c20490a0afa270c8221c0889b8

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0]
+
+### Added
+
+- `ServiceStack::JsonServiceClient` for consuming ServiceStack APIs with
+  generated typed DTOs
+- `ServiceStack::DTO` conversions driven by the wire name and Type metadata
+  generated DTOs declare, so nested DTOs, Dates and collections round-trip
+- Structured `ResponseStatus` errors in `WebServiceException`, incl. field errors
+- `api` results that return errors instead of raising
+- Auth with Basic Auth, API Keys, Bearer Tokens, Refresh Tokens and Session Cookies
+- Batched (`send_all`), one-way (`publish`) and custom URL Requests
+- Built-in ServiceStack DTOs referenced by generated DTOs (`ResponseStatus`,
+  `QueryBase`, `QueryResponse`, `Authenticate`, ...)
+
+[0.1.0]: https://github.com/ServiceStack/servicestack-ruby/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) ServiceStack
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,206 @@
+# servicestack-ruby
+
+Typed Ruby Client Library for consuming [ServiceStack](https://servicestack.net) APIs.
+
+- Typed Request/Response DTOs, generated from any ServiceStack API
+- Response Type, route and HTTP Method resolved from the Request DTO
+- Structured `ResponseStatus` errors with field validation errors
+- Auth with Basic Auth, API Keys, JWT Bearer Tokens, Refresh Tokens and Session Cookies
+- Batched Requests, one-way Requests and custom URLs
+- Zero dependencies, only the Ruby standard library
+
+Requires Ruby 3.0+.
+
+## Install
+
+```bash
+gem install servicestack
+```
+
+Or in your `Gemfile`:
+
+```ruby
+gem 'servicestack'
+```
+
+## Generate Typed DTOs
+
+Generate the Ruby DTOs of any ServiceStack API with the [get-dtos](https://www.npmjs.com/package/get-dtos) tool:
+
+```bash
+npx get-dtos ruby https://blazor-vue.web-templates.io
+```
+
+Which downloads a `dtos.rb` containing the typed DTOs of the remote API:
+
+```ruby
+require 'json'
+require 'servicestack'
+
+# @Route("/hello/{Name}")
+class Hello
+    include ServiceStack::DTO
+
+    # @return [String]
+    attr_accessor :name
+
+    def self.properties
+        {
+            name: { name: 'name' },
+        }
+    end
+
+    def response_type() = HelloResponse
+    def get_type_name() = 'Hello'
+    def get_method() = 'GET'
+end
+```
+
+The generated `response_type`, `get_type_name` and `get_method` are what let the
+client resolve each API's Response Type, route and HTTP Method, whilst
+`self.properties` declares the wire name and Type of each property so nested
+DTOs, Dates and collections round-trip correctly.
+
+## Usage
+
+```ruby
+require 'servicestack'
+require_relative 'dtos'
+
+client = ServiceStack::JsonServiceClient.new('https://blazor-vue.web-templates.io')
+
+res = client.send(Hello.new(name: 'World')) # res is a HelloResponse
+puts res.result
+```
+
+`send` uses the HTTP Method the API is annotated with, use `get`, `post`, `put`,
+`patch` or `delete` to send a Request DTO with a specific HTTP Method:
+
+```ruby
+res = client.post(Hello.new(name: 'World'))
+```
+
+APIs that don't return a Response Body are sent with `send_void`:
+
+```ruby
+client.send_void(DeleteBooking.new(id: 1))
+```
+
+> `JsonServiceClient#send` overrides `Object#send`. Use `__send__` for Ruby's
+> dynamic dispatch, or `send_dto` if you prefer an unambiguous name.
+
+### AutoQuery
+
+AutoQuery APIs return a typed `QueryResponse`, with the query params of their
+base type inherited by the Request DTO:
+
+```ruby
+res = client.send(QueryBookings.new(take: 5, order_by_desc: 'id'))
+
+res.results.each do |booking| # booking is a Booking
+  puts "#{booking.id} #{booking.name}"
+end
+```
+
+### Error Handling
+
+Failed API Requests raise a `WebServiceException` containing the HTTP Status
+Code and the API's structured `ResponseStatus`:
+
+```ruby
+begin
+  client.send(CreateBooking.new)
+rescue ServiceStack::WebServiceException => e
+  puts e.status_code            # 400
+  puts e.error_code             # "NotEmpty"
+  puts e.error_message          # "'Name' must not be empty."
+  puts e.field_error('Name')    # "'Name' must not be empty."
+  puts e.unauthorized?          # false
+end
+```
+
+Alternatively `api` returns errors in its result instead of raising:
+
+```ruby
+api = client.api(CreateBooking.new)
+if api.failed?
+  puts api.error_code, api.field_error('Name')
+else
+  puts api.response.id
+end
+```
+
+Redirects aren't followed, so Services that redirect to a HTML sign in page
+raise a `WebServiceException` with a `Redirect` ErrorCode instead of returning
+an empty Response.
+
+### Authentication
+
+API Keys and JWTs are sent in the Bearer Token Authorization header:
+
+```ruby
+client.set_bearer_token('ak-87949de37e894627a9f6173154e7cafa')
+```
+
+HTTP Basic Auth credentials:
+
+```ruby
+client.set_credentials('username', 'password')
+```
+
+Sign in with ServiceStack's Authenticate API, which retains the Session Cookies
+the Server returns and uses any Bearer Token it issues:
+
+```ruby
+auth = client.authenticate('username', 'password')
+```
+
+When a Refresh Token is configured, expired Bearer Tokens are transparently
+refreshed and the failed Request retried:
+
+```ruby
+client.set_refresh_token(refresh_token)
+```
+
+### Batched Requests
+
+```ruby
+responses = client.send_all([Hello.new(name: 'A'), Hello.new(name: 'B')])
+```
+
+Or send a Request to a one-way endpoint that ignores its Response:
+
+```ruby
+client.publish(Hello.new(name: 'World'))
+```
+
+### Custom URLs
+
+```ruby
+res = client.get_url('/hello/World', response_as: HelloResponse)
+res = client.post_url('/hello', body: Hello.new(name: 'World'), response_as: HelloResponse)
+csv = client.send_url_string('/api/QueryBookings.csv')
+```
+
+### Client Configuration
+
+```ruby
+client.set_header('X-Custom', 'Value')
+client.timeout = 30
+client.set_base_path('')  # use the /json/reply pre-defined routes
+
+# Inspect or modify each Request and Response
+client.request_filter = ->(req) { puts req.path }
+client.response_filter = ->(res) { puts res.code }
+```
+
+## Tests
+
+```bash
+rake test              # unit tests
+rake test:integration  # integration tests against test.servicestack.net
+```
+
+## License
+
+BSD-3-Clause. See [LICENSE](LICENSE).

data/lib/servicestack/dto.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module ServiceStack
+  # Included by generated DTOs to convert them to and from the JSON their APIs
+  # are serialized with.
+  #
+  # Generated DTOs declare the wire name and Type of each property, which is
+  # what lets nested DTOs, Dates and collections round-trip correctly:
+  #
+  #   class Booking
+  #     include ServiceStack::DTO
+  #     attr_accessor :id, :booking_start_date, :discount
+  #
+  #     def self.properties
+  #       {
+  #         id: { name: 'id' },
+  #         booking_start_date: { name: 'bookingStartDate', type: DateTime },
+  #         discount: { name: 'discount', type: Coupon },
+  #       }
+  #     end
+  #   end
+  module DTO
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Creates a DTO, populating any properties passed as keyword args, e.g:
+    #
+    #   Hello.new(name: 'World')
+    def initialize(**kwargs)
+      kwargs.each do |key, value|
+        setter = "#{key}="
+        unless respond_to?(setter)
+          raise ArgumentError, "unknown property '#{key}' for #{self.class}"
+        end
+
+        public_send(setter, value)
+      end
+    end
+
+    # The DTO as the Hash it's serialized to, using its wire property names and
+    # omitting any properties that aren't populated.
+    def to_hash
+      to = {}
+      self.class.all_properties.each do |attr, meta|
+        value = instance_variable_get("@#{attr}")
+        next if value.nil?
+
+        to[meta[:name] || attr.to_s] = Serializer.to_json_value(value)
+      end
+      to
+    end
+    alias to_h to_hash
+
+    # The DTO as its JSON representation.
+    def to_json(*args)
+      require 'json'
+      to_hash.to_json(*args)
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && to_hash == other.to_hash
+    end
+
+    def inspect
+      "#<#{self.class} #{to_hash.map { |k, v| "#{k}=#{v.inspect}" }.join(', ')}>"
+    end
+
+    module ClassMethods
+      # The wire name and Type of each property, overridden by generated DTOs.
+      def properties
+        {}
+      end
+
+      # This DTO's properties, including the properties it inherits.
+      def all_properties
+        to = {}
+        ancestors.reverse.each do |klass|
+          next unless klass.respond_to?(:properties)
+
+          to.merge!(klass.properties)
+        end
+        to
+      end
+
+      # Creates a populated DTO from the Hash of a JSON API Response.
+      def from_hash(hash)
+        return nil if hash.nil?
+
+        instance = new
+        props = all_properties
+        hash.each do |key, value|
+          attr, meta = find_property(props, key.to_s)
+          next if attr.nil?
+
+          instance.instance_variable_set("@#{attr}", Serializer.from_json_value(meta[:type], value))
+        end
+        instance
+      end
+
+      # Creates a populated DTO from a JSON string.
+      def from_json(json)
+        require 'json'
+        from_hash(::JSON.parse(json))
+      end
+
+      private
+
+      # Resolves a JSON property to the DTO property it populates, matching on
+      # the wire name first, then the DTO's own snake_case name.
+      def find_property(props, json_name)
+        props.each do |attr, meta|
+          return [attr, meta] if meta[:name] == json_name
+        end
+
+        snake_name = Serializer.snake_case(json_name).to_sym
+        meta = props[snake_name]
+        return [snake_name, meta] if meta
+
+        [nil, nil]
+      end
+    end
+
+    # Converts values to and from their JSON representation.
+    module Serializer
+      module_function
+
+      def to_json_value(value)
+        case value
+        when nil then nil
+        when ::DateTime, ::Time then value.iso8601
+        when ::Date then value.iso8601
+        when ::Symbol then value.to_s
+        when ::Array then value.map { |x| to_json_value(x) }
+        when ::Hash then value.each_with_object({}) { |(k, v), to| to[k.to_s] = to_json_value(v) }
+        else
+          value.respond_to?(:to_hash) && value.class.include?(DTO) ? value.to_hash : value
+        end
+      end
+
+      def from_json_value(type, value)
+        return nil if value.nil?
+
+        # Arrays declare their element Type, e.g. type: [Booking]
+        if type.is_a?(::Array)
+          element_type = type.first
+          return value.map { |x| from_json_value(element_type, x) } if value.is_a?(::Array)
+
+          return value
+        end
+
+        # Hashes declare their key and value Types, e.g. type: { String => Booking }
+        if type.is_a?(::Hash)
+          value_type = type.values.first
+          return value.each_with_object({}) { |(k, v), to| to[k] = from_json_value(value_type, v) } if value.is_a?(::Hash)
+
+          return value
+        end
+
+        return value if type.nil?
+        return parse_date(value) if type == ::DateTime || type == ::Time || type == ::Date
+        return value.to_s if type == ::String
+        return value.to_i if type == ::Integer && !value.is_a?(::Integer)
+        return value.to_f if type == ::Float && !value.is_a?(::Float)
+
+        if type.is_a?(::Class) && type.include?(DTO) && value.is_a?(::Hash)
+          return type.from_hash(value)
+        end
+
+        value
+      end
+
+      def parse_date(value)
+        return value unless value.is_a?(::String)
+
+        # ServiceStack also serializes dates in WCF's /Date(1670000000000)/ format
+        if (match = value.match(%r{^/Date\((-?\d+)([+-]\d{4})?\)/$}))
+          return ::Time.at(match[1].to_i / 1000.0).to_datetime
+        end
+
+        ::DateTime.parse(value)
+      rescue ::ArgumentError, ::TypeError
+        value
+      end
+
+      def snake_case(name)
+        name.to_s
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .tr('-', '_')
+            .downcase
+      end
+
+      def camel_case(name)
+        parts = name.to_s.split('_')
+        ([parts.first] + parts[1..].map(&:capitalize)).join
+      end
+    end
+  end
+end

data/lib/servicestack/json_service_client.rb

@@ -0,0 +1,442 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+require_relative 'dto'
+require_relative 'types'
+require_relative 'web_service_exception'
+
+module ServiceStack
+  # HTTP Methods used by ServiceStack APIs.
+  module HttpMethods
+    GET = 'GET'
+    POST = 'POST'
+    PUT = 'PUT'
+    PATCH = 'PATCH'
+    DELETE = 'DELETE'
+    OPTIONS = 'OPTIONS'
+    HEAD = 'HEAD'
+  end
+
+  # Either the typed Response of a successful API Request or the structured
+  # ResponseStatus error of a failed one, returned by `api`.
+  class ApiResult
+    attr_reader :response, :error
+
+    def initialize(response: nil, error: nil)
+      @response = response
+      @error = error
+    end
+
+    def succeeded? = @error.nil?
+    def failed? = !@error.nil?
+    def error_code = @error&.error_code
+    def error_message = @error&.message
+    def field_error(field_name) = @error&.field_error(field_name)
+  end
+
+  # Client for consuming ServiceStack APIs with generated typed DTOs.
+  #
+  #   client = ServiceStack::JsonServiceClient.new('https://example.org')
+  #   res = client.send(Hello.new(name: 'World'))
+  #   puts res.result
+  class JsonServiceClient
+    MIME_TYPE_JSON = 'application/json'
+
+    attr_accessor :base_url, :reply_base_url, :oneway_base_url, :headers,
+                  :bearer_token, :refresh_token, :refresh_token_uri,
+                  :user_name, :password, :request_filter, :response_filter,
+                  :timeout, :cookies
+
+    class << self
+      # Filters applied to every Request and Response of all clients.
+      attr_accessor :global_request_filter, :global_response_filter
+    end
+
+    def initialize(base_url)
+      raise ArgumentError, 'base_url is required' if base_url.nil? || base_url.to_s.empty?
+
+      @base_url = base_url.to_s.sub(%r{/+$}, '')
+      @headers = { 'Accept' => MIME_TYPE_JSON }
+      @cookies = {}
+      @timeout = 60
+      set_base_path('api')
+    end
+
+    # Changes the base path Request DTOs are sent to, e.g. 'api'.
+    # Use an empty base_path for the /json/reply pre-defined routes.
+    def set_base_path(base_path = '')
+      if base_path.nil? || base_path.to_s.empty?
+        @reply_base_url = combine_with(@base_url, 'json/reply')
+        @oneway_base_url = combine_with(@base_url, 'json/oneway')
+      else
+        @reply_base_url = combine_with(@base_url, base_path)
+        @oneway_base_url = combine_with(@base_url, base_path)
+      end
+      self
+    end
+
+    # Sets the JWT or API Key sent in the Bearer Authorization header.
+    def set_bearer_token(token)
+      @bearer_token = token
+      self
+    end
+
+    # Sets the Refresh Token used to fetch a new Bearer Token when a Request
+    # returns 401 Unauthorized.
+    def set_refresh_token(token)
+      @refresh_token = token
+      self
+    end
+
+    # Sets the UserName and Password sent in the HTTP Basic Auth header.
+    def set_credentials(user_name, password)
+      @user_name = user_name
+      @password = password
+      self
+    end
+
+    # Sets a HTTP Header sent with each Request.
+    def set_header(name, value)
+      @headers[name] = value
+      self
+    end
+
+    # ── Typed API ──
+
+    # Sends a Request DTO with the HTTP Method it's annotated with, returning
+    # its typed Response.
+    #
+    # Note this overrides Object#send, use __send__ or send_dto for Ruby's
+    # dynamic dispatch.
+    def send(request, method: nil, body: nil, args: nil)
+      method ||= resolve_http_method(request)
+      execute_typed(method, create_url_from_dto(method, request), body || request,
+                    resolve_response_type(request), args: args)
+    end
+    alias send_dto send
+
+    def get(request, args: nil) = send(request, method: HttpMethods::GET, args: args)
+    def post(request, body: nil, args: nil) = send(request, method: HttpMethods::POST, body: body, args: args)
+    def put(request, body: nil, args: nil) = send(request, method: HttpMethods::PUT, body: body, args: args)
+    def patch(request, body: nil, args: nil) = send(request, method: HttpMethods::PATCH, body: body, args: args)
+    def delete(request, args: nil) = send(request, method: HttpMethods::DELETE, args: args)
+
+    # Sends a Request DTO that doesn't return a Response Body.
+    def send_void(request, args: nil)
+      method = resolve_http_method(request)
+      execute(method, create_url_from_dto(method, request), request, args: args)
+      nil
+    end
+
+    # Sends a Request DTO, returning an ApiResult containing either its typed
+    # Response or the structured ResponseStatus error.
+    def api(request, method: nil, args: nil)
+      ApiResult.new(response: send(request, method: method, args: args))
+    rescue WebServiceException => e
+      ApiResult.new(error: e.response_status || ResponseStatus.new(
+        error_code: e.status_description, message: e.message
+      ))
+    end
+
+    # Sends multiple Request DTOs of the same Type in a single Request.
+    def send_all(requests)
+      return [] if requests.nil? || requests.empty?
+
+      # Brackets are encoded so the batch URL is a valid URI
+      url = combine_with(@reply_base_url, "#{type_name_of(requests.first)}%5B%5D")
+      response_type = resolve_response_type(requests.first)
+      json = execute(HttpMethods::POST, url, requests)
+      parsed = json.to_s.empty? ? [] : JSON.parse(json)
+      return parsed unless response_type
+
+      parsed.map { |x| response_type.from_hash(x) }
+    end
+
+    # Sends a Request DTO to a one-way endpoint, ignoring any Response.
+    def publish(request)
+      url = combine_with(@oneway_base_url, type_name_of(request))
+      execute(HttpMethods::POST, url, request)
+      nil
+    end
+
+    # Signs in with UserName and Password credentials, using the Bearer Token
+    # and Session Cookies the Server returns for subsequent Requests.
+    def authenticate(user_name, password)
+      res = send(Authenticate.new(provider: 'credentials', user_name: user_name, password: password))
+      @bearer_token = res.bearer_token unless res.bearer_token.to_s.empty?
+      @refresh_token = res.refresh_token unless res.refresh_token.to_s.empty?
+      res
+    end
+
+    # ── URL API ──
+
+    # Sends a GET Request to a custom relative path or absolute URL.
+    def get_url(path, response_as: nil, args: nil)
+      send_url(path, method: HttpMethods::GET, response_as: response_as, args: args)
+    end
+
+    def post_url(path, body: nil, response_as: nil, args: nil)
+      send_url(path, method: HttpMethods::POST, body: body, response_as: response_as, args: args)
+    end
+
+    def put_url(path, body: nil, response_as: nil, args: nil)
+      send_url(path, method: HttpMethods::PUT, body: body, response_as: response_as, args: args)
+    end
+
+    def patch_url(path, body: nil, response_as: nil, args: nil)
+      send_url(path, method: HttpMethods::PATCH, body: body, response_as: response_as, args: args)
+    end
+
+    def delete_url(path, response_as: nil, args: nil)
+      send_url(path, method: HttpMethods::DELETE, response_as: response_as, args: args)
+    end
+
+    # Sends a Request to a custom relative path or absolute URL.
+    def send_url(path, method: HttpMethods::GET, body: nil, response_as: nil, args: nil)
+      execute_typed(method, to_absolute_url(path), body, response_as, args: args)
+    end
+
+    # Sends a Request to a custom URL, returning its raw Response Body.
+    def send_url_string(path, method: HttpMethods::GET, body: nil, args: nil)
+      execute(method, to_absolute_url(path), body, args: args)
+    end
+
+    # Converts a relative path into an absolute URL of this client.
+    def to_absolute_url(path_or_url)
+      return path_or_url if path_or_url.to_s.start_with?('http://', 'https://')
+
+      combine_with(@base_url, path_or_url)
+    end
+
+    # The URL a Request DTO is sent to, appending the populated DTO properties
+    # to the QueryString for Requests without a Body.
+    def create_url_from_dto(method, request)
+      url = combine_with(@reply_base_url, type_name_of(request))
+      return url if has_request_body?(method)
+
+      append_query_string(url, to_hash(request))
+    end
+
+    private
+
+    def execute_typed(method, url, body, response_type, args: nil)
+      json = execute(method, url, body, args: args)
+      return nil if response_type.nil?
+      return json if response_type == String
+
+      parsed = json.to_s.strip.empty? ? {} : JSON.parse(json)
+      return parsed unless response_type.respond_to?(:from_hash)
+
+      response_type.from_hash(parsed)
+    end
+
+    def execute(method, url, body, args: nil, retry_on_auth_failure: true)
+      url = append_query_string(url, args) if args && !args.empty?
+
+      uri = URI.parse(url)
+      request = new_http_request(method, uri, body)
+
+      @request_filter&.call(request)
+      self.class.global_request_filter&.call(request)
+
+      response = http_client(uri).request(request)
+
+      @response_filter&.call(response)
+      self.class.global_response_filter&.call(response)
+
+      capture_cookies(response)
+
+      status_code = response.code.to_i
+      if status_code == 401 && retry_on_auth_failure && refresh_access_token
+        return execute(method, url, body, retry_on_auth_failure: false)
+      end
+
+      # Redirects aren't followed, e.g. Services that redirect to a HTML sign in
+      # page would otherwise return an empty Response
+      raise to_web_service_exception(response) if status_code >= 300
+
+      response.body
+    rescue WebServiceException
+      raise
+    rescue StandardError => e
+      raise WebServiceException.new(e.message, inner_exception: e)
+    end
+
+    def new_http_request(method, uri, body)
+      request_class = case method.to_s.upcase
+                      when HttpMethods::GET then Net::HTTP::Get
+                      when HttpMethods::POST then Net::HTTP::Post
+                      when HttpMethods::PUT then Net::HTTP::Put
+                      when HttpMethods::PATCH then Net::HTTP::Patch
+                      when HttpMethods::DELETE then Net::HTTP::Delete
+                      when HttpMethods::OPTIONS then Net::HTTP::Options
+                      when HttpMethods::HEAD then Net::HTTP::Head
+                      else Net::HTTP::Post
+                      end
+
+      request = request_class.new(uri.request_uri)
+      @headers.each { |name, value| request[name] = value }
+
+      if @bearer_token
+        request['Authorization'] = "Bearer #{@bearer_token}"
+      elsif @user_name || @password
+        request.basic_auth(@user_name.to_s, @password.to_s)
+      end
+
+      request['Cookie'] = @cookies.map { |k, v| "#{k}=#{v}" }.join('; ') unless @cookies.empty?
+
+      if body && has_request_body?(method)
+        request['Content-Type'] ||= MIME_TYPE_JSON
+        request.body = body.is_a?(String) ? body : JSON.generate(to_hash(body))
+      end
+
+      request
+    end
+
+    def http_client(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.read_timeout = @timeout if @timeout
+      http.open_timeout = @timeout if @timeout
+      http
+    end
+
+    # Retains the Session Cookies returned by the Server, e.g. ss-id/ss-pid
+    def capture_cookies(response)
+      cookies = response.get_fields('set-cookie')
+      return if cookies.nil?
+
+      cookies.each do |set_cookie|
+        pair = set_cookie.split(';').first.to_s
+        name, _, value = pair.partition('=')
+        @cookies[name.strip] = value.strip unless name.strip.empty?
+      end
+    end
+
+    def refresh_access_token
+      return false if @refresh_token.to_s.empty?
+
+      url = @refresh_token_uri || combine_with(@reply_base_url, 'GetAccessToken')
+      json = execute(HttpMethods::POST, to_absolute_url(url),
+                     GetAccessToken.new(refresh_token: @refresh_token),
+                     retry_on_auth_failure: false)
+      res = GetAccessTokenResponse.from_hash(JSON.parse(json.to_s.empty? ? '{}' : json))
+      return false if res.access_token.to_s.empty?
+
+      @bearer_token = res.access_token
+      true
+    rescue StandardError
+      false
+    end
+
+    def to_web_service_exception(response)
+      status_code = response.code.to_i
+      response_status = nil
+
+      body = response.body.to_s
+      unless body.empty?
+        begin
+          hash = JSON.parse(body)
+          if hash.is_a?(Hash)
+            status_hash = hash['responseStatus'] || hash['ResponseStatus']
+            status_hash = hash if status_hash.nil? && (hash['errorCode'] || hash['message'])
+            response_status = ResponseStatus.from_hash(status_hash) if status_hash
+          end
+        rescue JSON::ParserError
+          # Services can return non JSON errors, e.g. a HTML error page
+        end
+      end
+
+      if response_status.nil? && status_code >= 300 && status_code < 400
+        location = response['location']
+        response_status = ResponseStatus.new(
+          error_code: 'Redirect',
+          message: "Request was redirected#{location ? " to #{location}" : ''}"
+        )
+      end
+
+      response_status ||= ResponseStatus.new(error_code: response.message, message: response.message)
+
+      WebServiceException.new(
+        response_status.message || response.message,
+        status_code: status_code,
+        status_description: response.message,
+        response_status: response_status,
+        response_body: body
+      )
+    end
+
+    def resolve_response_type(request)
+      return nil unless request.respond_to?(:response_type)
+
+      request.response_type
+    end
+
+    def resolve_http_method(request)
+      return request.get_method if request.respond_to?(:get_method) && !request.get_method.to_s.empty?
+
+      name = type_name_of(request)
+      case name
+      when /\A(Get|Query|Find|Search)/ then HttpMethods::GET
+      when /\A(Create)/ then HttpMethods::POST
+      when /\A(Update|Replace)/ then HttpMethods::PUT
+      when /\A(Patch)/ then HttpMethods::PATCH
+      when /\A(Delete|Remove)/ then HttpMethods::DELETE
+      else HttpMethods::POST
+      end
+    end
+
+    def type_name_of(request)
+      return request.get_type_name if request.respond_to?(:get_type_name)
+
+      request.class.name.to_s.split('::').last
+    end
+
+    def to_hash(dto)
+      return dto if dto.is_a?(String)
+      return dto.map { |x| to_hash(x) } if dto.is_a?(Array)
+      return dto.to_hash if dto.respond_to?(:to_hash)
+
+      dto
+    end
+
+    def has_request_body?(method)
+      !%w[GET DELETE HEAD OPTIONS].include?(method.to_s.upcase)
+    end
+
+    def combine_with(base_url, path)
+      base = base_url.to_s.sub(%r{/+$}, '')
+      rel = path.to_s.sub(%r{\A/+}, '').sub(%r{/+$}, '')
+      return base if rel.empty?
+      return rel if base.empty?
+
+      "#{base}/#{rel}"
+    end
+
+    def append_query_string(url, args)
+      return url if args.nil? || args.empty?
+
+      params = args.filter_map do |key, value|
+        next if value.nil?
+
+        "#{URI.encode_www_form_component(key.to_s)}=#{URI.encode_www_form_component(qs_value(value))}"
+      end
+      return url if params.empty?
+
+      "#{url}#{url.include?('?') ? '&' : '?'}#{params.join('&')}"
+    end
+
+    def qs_value(value)
+      case value
+      when nil then ''
+      when true, false then value.to_s
+      when Array then "[#{value.map { |x| qs_value(x) }.join(',')}]"
+      when Hash then "{#{value.map { |k, v| "#{k}:#{qs_value(v)}" }.join(',')}}"
+      when DateTime, Time, Date then value.iso8601
+      else value.to_s
+      end
+    end
+  end
+end

data/lib/servicestack/types.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+require_relative 'dto'
+
+module ServiceStack
+  # A field validation error within a ResponseStatus.
+  class ResponseError
+    include DTO
+    attr_accessor :error_code, :field_name, :message, :meta
+
+    def self.properties
+      {
+        error_code: { name: 'errorCode' },
+        field_name: { name: 'fieldName' },
+        message: { name: 'message' },
+        meta: { name: 'meta' },
+      }
+    end
+  end
+
+  # ServiceStack's structured error, returned in the `responseStatus` property
+  # of failed API Responses.
+  class ResponseStatus
+    include DTO
+    attr_accessor :error_code, :message, :stack_trace, :errors, :meta
+
+    def self.properties
+      {
+        error_code: { name: 'errorCode' },
+        message: { name: 'message' },
+        stack_trace: { name: 'stackTrace' },
+        errors: { name: 'errors', type: [ResponseError] },
+        meta: { name: 'meta' },
+      }
+    end
+
+    # The validation error message for the field, matched case-insensitively.
+    def field_error(field_name)
+      error = get_field_error(field_name)
+      error&.message
+    end
+
+    # The ResponseError for the field, matched case-insensitively.
+    def get_field_error(field_name)
+      (errors || []).find { |x| x.field_name.to_s.casecmp?(field_name.to_s) }
+    end
+  end
+
+  # Returned by APIs with no Response Body.
+  class EmptyResponse
+    include DTO
+    attr_accessor :response_status
+
+    def self.properties
+      { response_status: { name: 'responseStatus', type: ResponseStatus } }
+    end
+  end
+
+  # Returned by APIs that return the Id of the created or updated entity.
+  class IdResponse
+    include DTO
+    attr_accessor :id, :response_status
+
+    def self.properties
+      {
+        id: { name: 'id' },
+        response_status: { name: 'responseStatus', type: ResponseStatus },
+      }
+    end
+  end
+
+  # Returned by APIs that return a single string result.
+  class StringResponse
+    include DTO
+    attr_accessor :result, :meta, :response_status
+
+    def self.properties
+      {
+        result: { name: 'result' },
+        meta: { name: 'meta' },
+        response_status: { name: 'responseStatus', type: ResponseStatus },
+      }
+    end
+  end
+
+  # Returned by APIs that return a list of string results.
+  class StringsResponse
+    include DTO
+    attr_accessor :results, :meta, :response_status
+
+    def self.properties
+      {
+        results: { name: 'results' },
+        meta: { name: 'meta' },
+        response_status: { name: 'responseStatus', type: ResponseStatus },
+      }
+    end
+  end
+
+  # The audit fields of AutoQuery CRUD data models.
+  class AuditBase
+    include DTO
+    attr_accessor :created_date, :created_by, :modified_date, :modified_by, :deleted_date, :deleted_by
+
+    def self.properties
+      {
+        created_date: { name: 'createdDate', type: DateTime },
+        created_by: { name: 'createdBy' },
+        modified_date: { name: 'modifiedDate', type: DateTime },
+        modified_by: { name: 'modifiedBy' },
+        deleted_date: { name: 'deletedDate', type: DateTime },
+        deleted_by: { name: 'deletedBy' },
+      }
+    end
+  end
+
+  # The query params supported by all AutoQuery Requests.
+  class QueryBase
+    include DTO
+    attr_accessor :skip, :take, :order_by, :order_by_desc, :include, :fields, :meta
+
+    def self.properties
+      {
+        skip: { name: 'skip' },
+        take: { name: 'take' },
+        order_by: { name: 'orderBy' },
+        order_by_desc: { name: 'orderByDesc' },
+        include: { name: 'include' },
+        fields: { name: 'fields' },
+        meta: { name: 'meta' },
+      }
+    end
+  end
+
+  # The base of AutoQuery RDBMS Requests.
+  class QueryDb < QueryBase; end
+
+  # The base of AutoQuery Data Requests.
+  class QueryData < QueryBase; end
+
+  # The typed Response of AutoQuery Requests.
+  #
+  # Use `QueryResponse.of(Booking)` for a Response that converts its `results`
+  # into the specified Type, which is what generated AutoQuery DTOs return.
+  class QueryResponse
+    include DTO
+    attr_accessor :offset, :total, :results, :meta, :response_status
+
+    class << self
+      attr_accessor :results_type
+
+      # A QueryResponse that converts its results into the specified Type.
+      def of(type)
+        @of_types ||= {}
+        @of_types[type] ||= Class.new(self) do
+          self.results_type = type
+        end
+      end
+
+      def properties
+        {
+          offset: { name: 'offset' },
+          total: { name: 'total' },
+          results: { name: 'results', type: [results_type].compact },
+          meta: { name: 'meta' },
+          response_status: { name: 'responseStatus', type: ResponseStatus },
+        }
+      end
+    end
+  end
+
+  # Authenticate with a ServiceStack Service.
+  class Authenticate
+    include DTO
+    attr_accessor :provider, :user_name, :password, :remember_me, :access_token,
+                  :access_token_secret, :return_url, :error_view, :meta
+
+    def self.properties
+      {
+        provider: { name: 'provider' },
+        user_name: { name: 'userName' },
+        password: { name: 'password' },
+        remember_me: { name: 'rememberMe' },
+        access_token: { name: 'accessToken' },
+        access_token_secret: { name: 'accessTokenSecret' },
+        return_url: { name: 'returnUrl' },
+        error_view: { name: 'errorView' },
+        meta: { name: 'meta' },
+      }
+    end
+
+    def response_type = AuthenticateResponse
+    def get_type_name = 'Authenticate'
+    def get_method = 'POST'
+  end
+
+  # The Response of a successful Authenticate Request.
+  class AuthenticateResponse
+    include DTO
+    attr_accessor :user_id, :session_id, :user_name, :display_name, :referrer_url,
+                  :bearer_token, :refresh_token, :refresh_token_expiry, :profile_url,
+                  :roles, :permissions, :auth_provider, :response_status, :meta
+
+    def self.properties
+      {
+        user_id: { name: 'userId' },
+        session_id: { name: 'sessionId' },
+        user_name: { name: 'userName' },
+        display_name: { name: 'displayName' },
+        referrer_url: { name: 'referrerUrl' },
+        bearer_token: { name: 'bearerToken' },
+        refresh_token: { name: 'refreshToken' },
+        refresh_token_expiry: { name: 'refreshTokenExpiry', type: DateTime },
+        profile_url: { name: 'profileUrl' },
+        roles: { name: 'roles' },
+        permissions: { name: 'permissions' },
+        auth_provider: { name: 'authProvider' },
+        response_status: { name: 'responseStatus', type: ResponseStatus },
+        meta: { name: 'meta' },
+      }
+    end
+  end
+
+  # Register a new User.
+  class Register
+    include DTO
+    attr_accessor :user_name, :first_name, :last_name, :display_name, :email,
+                  :password, :confirm_password, :auto_login, :error_view, :meta
+
+    def self.properties
+      {
+        user_name: { name: 'userName' },
+        first_name: { name: 'firstName' },
+        last_name: { name: 'lastName' },
+        display_name: { name: 'displayName' },
+        email: { name: 'email' },
+        password: { name: 'password' },
+        confirm_password: { name: 'confirmPassword' },
+        auto_login: { name: 'autoLogin' },
+        error_view: { name: 'errorView' },
+        meta: { name: 'meta' },
+      }
+    end
+
+    def response_type = RegisterResponse
+    def get_type_name = 'Register'
+    def get_method = 'POST'
+  end
+
+  # The Response of a successful Register Request.
+  class RegisterResponse
+    include DTO
+    attr_accessor :user_id, :session_id, :user_name, :referrer_url, :bearer_token,
+                  :refresh_token, :refresh_token_expiry, :roles, :permissions,
+                  :redirect_url, :response_status, :meta
+
+    def self.properties
+      {
+        user_id: { name: 'userId' },
+        session_id: { name: 'sessionId' },
+        user_name: { name: 'userName' },
+        referrer_url: { name: 'referrerUrl' },
+        bearer_token: { name: 'bearerToken' },
+        refresh_token: { name: 'refreshToken' },
+        refresh_token_expiry: { name: 'refreshTokenExpiry', type: DateTime },
+        roles: { name: 'roles' },
+        permissions: { name: 'permissions' },
+        redirect_url: { name: 'redirectUrl' },
+        response_status: { name: 'responseStatus', type: ResponseStatus },
+        meta: { name: 'meta' },
+      }
+    end
+  end
+
+  # Exchange a Refresh Token for a new JWT Bearer Token.
+  class GetAccessToken
+    include DTO
+    attr_accessor :refresh_token, :meta
+
+    def self.properties
+      {
+        refresh_token: { name: 'refreshToken' },
+        meta: { name: 'meta' },
+      }
+    end
+
+    def response_type = GetAccessTokenResponse
+    def get_type_name = 'GetAccessToken'
+    def get_method = 'POST'
+  end
+
+  # The Response of GetAccessToken.
+  class GetAccessTokenResponse
+    include DTO
+    attr_accessor :access_token, :response_status, :meta
+
+    def self.properties
+      {
+        access_token: { name: 'accessToken' },
+        response_status: { name: 'responseStatus', type: ResponseStatus },
+        meta: { name: 'meta' },
+      }
+    end
+  end
+
+  # Convert an authenticated Session into a JWT Bearer Token.
+  class ConvertSessionToToken
+    include DTO
+    attr_accessor :preserve_session, :meta
+
+    def self.properties
+      {
+        preserve_session: { name: 'preserveSession' },
+        meta: { name: 'meta' },
+      }
+    end
+
+    def response_type = ConvertSessionToTokenResponse
+    def get_type_name = 'ConvertSessionToToken'
+    def get_method = 'POST'
+  end
+
+  # The Response of ConvertSessionToToken.
+  class ConvertSessionToTokenResponse
+    include DTO
+    attr_accessor :access_token, :refresh_token, :response_status, :meta
+
+    def self.properties
+      {
+        access_token: { name: 'accessToken' },
+        refresh_token: { name: 'refreshToken' },
+        response_status: { name: 'responseStatus', type: ResponseStatus },
+        meta: { name: 'meta' },
+      }
+    end
+  end
+end

data/lib/servicestack/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ServiceStack
+  VERSION = '0.1.0'
+end

data/lib/servicestack/web_service_exception.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ServiceStack
+  # Raised for failed API Requests, containing the HTTP Status Code and the
+  # structured ResponseStatus error when the Server returned one.
+  #
+  #   begin
+  #     client.send(CreateBooking.new)
+  #   rescue ServiceStack::WebServiceException => e
+  #     puts e.status_code           # 400
+  #     puts e.error_code            # "NotEmpty"
+  #     puts e.field_error('Name')   # "'Name' must not be empty."
+  #   end
+  class WebServiceException < StandardError
+    attr_reader :status_code, :status_description, :response_status, :response_body, :inner_exception
+
+    def initialize(message = nil, status_code: 0, status_description: nil, response_status: nil,
+                   response_body: nil, inner_exception: nil)
+      super(message || status_description || "HTTP Error #{status_code}")
+      @status_code = status_code
+      @status_description = status_description
+      @response_status = response_status
+      @response_body = response_body
+      @inner_exception = inner_exception
+    end
+
+    # The ErrorCode of the error, e.g. "NotFound".
+    def error_code = @response_status&.error_code
+
+    # The error message.
+    def error_message = @response_status&.message || message
+
+    # Any field validation errors.
+    def field_errors = @response_status&.errors || []
+
+    # The validation error message for the field, if it has one.
+    def field_error(field_name) = @response_status&.field_error(field_name)
+
+    def unauthorized? = @status_code == 401
+    def forbidden? = @status_code == 403
+    def not_found? = @status_code == 404
+    def validation_error? = !field_errors.empty?
+  end
+end

data/lib/servicestack.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Typed Ruby Client Library for consuming ServiceStack APIs.
+#
+# Generate typed DTOs for a remote ServiceStack API with get-dtos:
+#
+#   npx get-dtos ruby https://blazor-vue.web-templates.io
+#
+# Then send them with the client, which resolves each API's route, HTTP Method
+# and Response Type from its Request DTO:
+#
+#   require 'servicestack'
+#   require_relative 'dtos'
+#
+#   client = ServiceStack::JsonServiceClient.new('https://blazor-vue.web-templates.io')
+#   res = client.send(Hello.new(name: 'World'))
+#   puts res.result
+require_relative 'servicestack/version'
+require_relative 'servicestack/dto'
+require_relative 'servicestack/types'
+require_relative 'servicestack/web_service_exception'
+require_relative 'servicestack/json_service_client'
+
+module ServiceStack
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: servicestack
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ServiceStack
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Send generated typed Request DTOs to any ServiceStack API, with structured
+  ResponseStatus errors, AutoQuery, batched Requests and Bearer Token, API Key, Basic
+  Auth and Session Cookie authentication.
+email:
+- team@servicestack.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/servicestack.rb
+- lib/servicestack/dto.rb
+- lib/servicestack/json_service_client.rb
+- lib/servicestack/types.rb
+- lib/servicestack/version.rb
+- lib/servicestack/web_service_exception.rb
+homepage: https://github.com/ServiceStack/servicestack-ruby
+licenses:
+- BSD-3-Clause
+metadata:
+  homepage_uri: https://github.com/ServiceStack/servicestack-ruby
+  source_code_uri: https://github.com/ServiceStack/servicestack-ruby
+  changelog_uri: https://github.com/ServiceStack/servicestack-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'false'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Typed Ruby Client Library for consuming ServiceStack APIs
+test_files: []