servicestack 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d4c81df4c0df47d185c8f942f3da2e61983d149eb74ac128e03005eb9af30b3
-  data.tar.gz: 15f64c2c49f10e6803ff8a722edb1faeb20c670d99350103848390ab291239a9
+  metadata.gz: 422e88b02d244852ff3d8941817d5fc6c22c58c2a7698458b4d2d96df75af2bf
+  data.tar.gz: 9b2941734b9154d258de44f156e2e66b600f6042825535b017cf81699bcaf6da
 SHA512:
-  metadata.gz: 204756127fbd7b57d41c521f7f65824ba804c1bbd5c3487fdb9b4561eaba3c91847fe525c96e59092c2058f178948c44e105eb3a2bd21480ce662d719befa220
-  data.tar.gz: 6d29f98815d56c1dd66eb7e8982226b68288d20799569954b83a55c098aa9a2f5e2cdd5629c8d1bf8f6aa09313649b805ef701c20490a0afa270c8221c0889b8
+  metadata.gz: '09d3557ceda3563802cedbdcf7feddcadb4ccf5251994c00ecdadefa5417fab664429502b7a94379c53e4136f76e2337075d76f07a22cb015c990cbffb59ea7d'
+  data.tar.gz: 8abcf83d19d0530c7873a4a6993fc11390305379657f8db395e7a60a07e2faede986dc807e585a68bfd399aeb2b4b6829bbcfa08b42347568ecd304e14a19c43

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.2]
+
+### Added
+
+- `on_authentication_required` callback for re-authenticating a client before
+  automatically retrying a Request that returned 401 Unauthorized
+
+## [0.1.1]
+
+### Added
+
+- `post_file_with_request` and `post_files_with_request` for uploading files with
+  a Request DTO as a `multipart/form-data` Request, incl. an `UploadFile` that
+  accepts file contents as a String or any IO
+- `post_files_with_request_url` for uploading files to a custom URL
+
 ## [0.1.0]
 
 ### Added
@@ -17,4 +33,6 @@ All notable changes to this project will be documented in this file.
 - Built-in ServiceStack DTOs referenced by generated DTOs (`ResponseStatus`,
   `QueryBase`, `QueryResponse`, `Authenticate`, ...)
 
+[0.1.2]: https://github.com/ServiceStack/servicestack-ruby/releases/tag/v0.1.2
+[0.1.1]: https://github.com/ServiceStack/servicestack-ruby/releases/tag/v0.1.1
 [0.1.0]: https://github.com/ServiceStack/servicestack-ruby/releases/tag/v0.1.0

data/README.md

@@ -162,6 +162,25 @@ refreshed and the failed Request retried:
 client.set_refresh_token(refresh_token)
 ```
 
+### Transparently handle 401 Unauthorized Responses
+
+If the Server returns a 401 Unauthorized Response either because the client was
+unauthenticated or its Bearer Token or API Key had expired, use the
+`on_authentication_required` callback to re-configure the client before the
+original Request is automatically retried:
+
+```ruby
+client.on_authentication_required = lambda { |c|
+  c.authenticate(user_name, password)
+}
+
+# Automatically retries Requests returning 401 Responses
+res = client.send(Secured.new)
+```
+
+A configured Refresh Token takes precedence over the callback, which is only
+used when no Refresh Token is set or refreshing it failed.
+
 ### Batched Requests
 
 ```ruby
@@ -174,6 +193,22 @@ Or send a Request to a one-way endpoint that ignores its Response:
 client.publish(Hello.new(name: 'World'))
 ```
 
+### Uploading Files
+
+Use `post_file_with_request` to upload a file with an API Request, whose contents
+can be a String or any IO:
+
+```ruby
+res = File.open('photo.png', 'rb') do |file|
+  client.post_file_with_request(UploadPhoto.new(album: 'Holiday'),
+    ServiceStack::UploadFile.new(field_name: 'file', file_name: 'photo.png',
+                                 content_type: 'image/png', stream: file))
+end
+```
+
+The Request DTO's populated properties are sent as form fields alongside the file.
+To upload multiple files use `post_files_with_request`.
+
 ### Custom URLs
 
 ```ruby

data/lib/servicestack/json_service_client.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'net/http'
+require 'securerandom'
 require 'uri'
 require_relative 'dto'
 require_relative 'types'
@@ -19,6 +20,29 @@ module ServiceStack
     HEAD = 'HEAD'
   end
 
+  # A file uploaded in a multipart/form-data Request.
+  #
+  # Its contents can be supplied as a String or any IO that responds to `read`,
+  # e.g. a File or StringIO.
+  class UploadFile
+    attr_accessor :field_name, :file_name, :content_type, :stream
+
+    def initialize(field_name: 'file', file_name: nil, content_type: nil, stream: nil)
+      @field_name = field_name
+      @file_name = file_name
+      @content_type = content_type
+      @stream = stream
+    end
+
+    # The file contents to upload.
+    def contents
+      return @stream unless @stream.respond_to?(:read)
+
+      @stream.binmode if @stream.respond_to?(:binmode)
+      @stream.read
+    end
+  end
+
   # Either the typed Response of a successful API Request or the structured
   # ResponseStatus error of a failed one, returned by `api`.
   class ApiResult
@@ -47,7 +71,7 @@ module ServiceStack
     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
+                  :timeout, :cookies, :on_authentication_required
 
     class << self
       # Filters applied to every Request and Response of all clients.
@@ -203,6 +227,42 @@ module ServiceStack
       execute(method, to_absolute_url(path), body, args: args)
     end
 
+    # ── File Uploads ──
+
+    # Uploads a file with a Request DTO as a multipart/form-data Request,
+    # returning its typed Response, e.g:
+    #
+    #   File.open('photo.png', 'rb') do |file|
+    #     client.post_file_with_request(UploadPhoto.new(album: 'Holiday'),
+    #       ServiceStack::UploadFile.new(field_name: 'file', file_name: 'photo.png',
+    #                                    content_type: 'image/png', stream: file))
+    #   end
+    def post_file_with_request(request, file, args: nil)
+      post_files_with_request(request, [file], args: args)
+    end
+
+    # Uploads multiple files with a Request DTO as a multipart/form-data Request.
+    def post_files_with_request(request, files, args: nil)
+      url = create_url_from_dto(HttpMethods::POST, request)
+      post_files_with_request_url(url, request, files, response_as: resolve_response_type(request), args: args)
+    end
+
+    # Uploads files with a Request DTO to a custom relative path or absolute URL.
+    def post_files_with_request_url(path, request, files, response_as: nil, args: nil)
+      boundary = "----ServiceStackFormBoundary#{SecureRandom.hex(12)}"
+      body = multipart_body(boundary, request, files)
+
+      json = execute(HttpMethods::POST, to_absolute_url(path), body, args: args,
+                                                                    content_type: "multipart/form-data; boundary=#{boundary}")
+      return nil if response_as.nil?
+      return json if response_as == String
+
+      parsed = json.to_s.strip.empty? ? {} : JSON.parse(json)
+      return parsed unless response_as.respond_to?(:from_hash)
+
+      response_as.from_hash(parsed)
+    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://')
@@ -232,11 +292,11 @@ module ServiceStack
       response_type.from_hash(parsed)
     end
 
-    def execute(method, url, body, args: nil, retry_on_auth_failure: true)
+    def execute(method, url, body, args: nil, retry_on_auth_failure: true, content_type: nil)
       url = append_query_string(url, args) if args && !args.empty?
 
       uri = URI.parse(url)
-      request = new_http_request(method, uri, body)
+      request = new_http_request(method, uri, body, content_type: content_type)
 
       @request_filter&.call(request)
       self.class.global_request_filter&.call(request)
@@ -249,8 +309,8 @@ module ServiceStack
       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)
+      if status_code == 401 && retry_on_auth_failure && handle_authentication_required
+        return execute(method, url, body, retry_on_auth_failure: false, content_type: content_type)
       end
 
       # Redirects aren't followed, e.g. Services that redirect to a HTML sign in
@@ -264,7 +324,7 @@ module ServiceStack
       raise WebServiceException.new(e.message, inner_exception: e)
     end
 
-    def new_http_request(method, uri, body)
+    def new_http_request(method, uri, body, content_type: nil)
       request_class = case method.to_s.upcase
                       when HttpMethods::GET then Net::HTTP::Get
                       when HttpMethods::POST then Net::HTTP::Post
@@ -288,7 +348,7 @@ module ServiceStack
       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['Content-Type'] = content_type || request['Content-Type'] || MIME_TYPE_JSON
         request.body = body.is_a?(String) ? body : JSON.generate(to_hash(body))
       end
 
@@ -315,6 +375,26 @@ module ServiceStack
       end
     end
 
+    # Re-authenticates the client after a Request returned 401 Unauthorized,
+    # returning whether the Request should be retried.
+    #
+    # Uses the Refresh Token when configured, otherwise the
+    # `on_authentication_required` callback.
+    def handle_authentication_required
+      return true if refresh_access_token
+      return false if @on_authentication_required.nil?
+
+      if @on_authentication_required.arity.zero?
+        @on_authentication_required.call
+      else
+        @on_authentication_required.call(self)
+      end
+      true
+    rescue StandardError
+      # Re-authenticating failed, return the original 401 Response
+      false
+    end
+
     def refresh_access_token
       return false if @refresh_token.to_s.empty?
 
@@ -402,6 +482,34 @@ module ServiceStack
       dto
     end
 
+    # Builds the multipart/form-data body of a file upload Request, sending the
+    # populated Request DTO properties as form fields
+    def multipart_body(boundary, request, files)
+      body = +''
+
+      to_hash(request).each do |name, value|
+        next if value.nil?
+
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"#{name}\"\r\n\r\n"
+        body << "#{qs_value(value)}\r\n"
+      end
+
+      files.each do |file|
+        field_name = file.field_name.to_s.empty? ? 'file' : file.field_name
+        file_name = file.file_name.to_s.empty? ? 'file' : file.file_name
+
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"#{field_name}\"; filename=\"#{file_name}\"\r\n"
+        body << "Content-Type: #{file.content_type || 'application/octet-stream'}\r\n\r\n"
+        body << file.contents.to_s.dup.force_encoding(Encoding::BINARY)
+        body << "\r\n"
+      end
+
+      body << "--#{boundary}--\r\n"
+      body.force_encoding(Encoding::BINARY)
+    end
+
     def has_request_body?(method)
       !%w[GET DELETE HEAD OPTIONS].include?(method.to_s.upcase)
     end

data/lib/servicestack/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: servicestack
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - ServiceStack