webclient 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19d01c484b19fd633a6e73b3710d38dad056bd066e7c2dc9c613ddd1eae4c28f
-  data.tar.gz: 7140effe816c143e7ff9e336dadd9b1bd7b424ee6ca0c1b4ff75a12021fe0979
+  metadata.gz: 177c9b330862eac8b588d0bffe1d4819ffe20b5f03f13e8617291e1c890bc979
+  data.tar.gz: c0819b68fa611fa4aa38f088816984ae6f1d444f710a425135ead32d60f71f9f
 SHA512:
-  metadata.gz: aa8feda707d1e1c79bcaf9205e768465e21d2c39b8cba9143387816bd17d5df34f7e871d43ece9a3780a1a3577b701017633823e5e695635eb73d4f8ec954f0d
-  data.tar.gz: af08cb829652c2ba30600dd7163bba31dd9bc1e5bdbfc8d5f9d289ac285fcde5f878de541f4523e07906cdbb41bb25ebca632bae28df4113e741aa4b9e160512
+  metadata.gz: 7b3fdc8068632f7184fd77f6f7a34e2126ca54d7b7a09d4d1d5f92686dcfb16dc6af0c0a6470f188af82f9274388cc6aad0774c97a4e1aa312508976a328d24e
+  data.tar.gz: 74ea0e68e127db132d859f32806dc1f07fa86aa1b08beeeb949fc37aa53a405473825481dbe9bc2ffea1b5ea0d9d16555022f4ab956a9fc9df457d9d35da3401

data/CHANGELOG.md

@@ -1,4 +1,4 @@
-### 0.0.1 / 2020-10-03
-
-* Everything is new. First release.
-
+### 0.3.1
+### 0.0.1 / 2020-10-03
+
+* Everything is new. First release.

data/Manifest.txt

@@ -4,4 +4,8 @@ README.md
 Rakefile
 lib/webclient.rb
 lib/webclient/version.rb
-lib/webclient/webclient.rb
+lib/webclient/webclient-get.rb
+lib/webclient/webclient-post.rb
+lib/webclient/webclient_response-status.rb
+lib/webclient/webclient_response-text.rb
+lib/webclient/webclient_response.rb

data/README.md

@@ -1,22 +1,23 @@
-# webclient
-
-webclient gem - yet (another) universal network client interface for world wide web (www) requests via HTTP
-
-
-* home  :: [github.com/rubycoco/webclient](https://github.com/rubycoco/webclient)
-* bugs  :: [github.com/rubycoco/webclient/issues](https://github.com/rubycoco/webclient/issues)
-* gem   :: [rubygems.org/gems/webclient](https://rubygems.org/gems/webclient)
-* rdoc  :: [rubydoc.info/gems/webclient](http://rubydoc.info/gems/webclient)
-* forum :: [groups.google.com/group/wwwmake](https://groups.google.com/group/wwwmake)
-
-
-
-## Usage
-
-TBD
-
-
-## License
-
-The `webclient` scripts are dedicated to the public domain.
-Use it as you please with no restrictions whatsoever.
+# webclient
+
+webclient gem - yet (another)  universal network client interface for world wide web (www) requests via HTTP
+
+
+* home  :: [github.com/rubycocos/webclient](https://github.com/rubycocos/webclient)
+* bugs  :: [github.com/rubycocos/webclient/issues](https://github.com/rubycocos/webclient/issues)
+* gem   :: [rubygems.org/gems/webclient](https://rubygems.org/gems/webclient)
+* rdoc  :: [rubydoc.info/gems/webclient](http://rubydoc.info/gems/webclient)
+
+
+
+## Usage
+
+TBD
+
+
+
+
+## License
+
+The `webclient` scripts are dedicated to the public domain.
+Use  as you please with no restrictions whatsoever.

data/Rakefile

@@ -1,28 +1,28 @@
-require 'hoe'
-require './lib/webclient/version.rb'
-
-Hoe.spec 'webclient' do
-
-  self.version = Webclient::VERSION
-
-  self.summary = 'webclient gem - yet (another) universal network client interface for world wide web (www) requests via HTTP'
-  self.description = summary
-
-  self.urls    = { home: 'https://github.com/rubycoco/webclient' }
-
-  self.author  = 'Gerald Bauer'
-  self.email   = 'ruby-talk@ruby-lang.org'
-
-  # switch extension to .markdown for gihub formatting
-  self.readme_file  = 'README.md'
-  self.history_file = 'CHANGELOG.md'
-
-  self.extra_deps = []
-
-  self.licenses = ['Public Domain']
-
-  self.spec_extras = {
-   required_ruby_version: '>= 2.2.2'
-  }
-
-end
+require 'hoe'
+require './lib/webclient/version.rb'
+
+Hoe.spec 'webclient' do
+
+  self.version = Webclient::VERSION
+
+  self.summary = 'webclient gem - yet (another) universal network client interface for world wide web (www) requests via HTTP'
+  self.description = summary
+
+  self.urls    = { home: 'https://github.com/rubycocos/webclient' }
+
+  self.author  = 'Gerald Bauer'
+  self.email   = 'gerald.bauer@gmail.com'
+
+  # switch extension to .markdown for gihub formatting
+  self.readme_file  = 'README.md'
+  self.history_file = 'CHANGELOG.md'
+
+  self.extra_deps = []
+
+  self.licenses = ['Public Domain']
+
+  self.spec_extras = {
+   required_ruby_version: '>= 2.2.2'
+  }
+
+end

data/lib/webclient/version.rb

@@ -1,20 +1,19 @@
-
-class Webclient
-  MAJOR = 0    ## todo: namespace inside version or something - why? why not??
-  MINOR = 2
-  PATCH = 1
-  VERSION = [MAJOR,MINOR,PATCH].join('.')
-
-  def self.version
-    VERSION
-  end
-
-  def self.banner
-    "webclient/#{VERSION} on Ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) [#{RUBY_PLATFORM}] in (#{root})"
-  end
-
-  def self.root
-    File.expand_path( File.dirname(File.dirname(File.dirname(__FILE__))) )
-  end
-end # module Webclient
-
+
+class Webclient
+  MAJOR = 0    ## todo: namespace inside version or something - why? why not??
+  MINOR = 3
+  PATCH = 1
+  VERSION = [MAJOR,MINOR,PATCH].join('.')
+
+  def self.version
+    VERSION
+  end
+
+  def self.banner
+    "webclient/#{VERSION} on Ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) [#{RUBY_PLATFORM}] in (#{root})"
+  end
+
+  def self.root
+    File.expand_path( File.dirname(File.dirname(File.dirname(__FILE__))) )
+  end
+end # module Webclient

data/lib/webclient/webclient-get.rb

@@ -0,0 +1,51 @@
+
+class Webclient
+
+
+def self.get( url, headers: {}, auth: [] )
+
+  uri = URI.parse( url )
+  http = Net::HTTP.new( uri.host, uri.port )
+
+  if uri.instance_of? URI::HTTPS
+    http.use_ssl     = true
+    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+  end
+
+  request = Net::HTTP::Get.new( uri.request_uri )
+
+  ### add (custom) headers if any
+  ##  check/todo: is there are more idiomatic way for Net::HTTP ???
+  ##   use
+  ##     request = Net::HTTP::Get.new( uri.request_uri, headers )
+  ##    why? why not?
+  ##  instead of e.g.
+  ##   request['X-Auth-Token'] = 'xxxxxxx'
+  ##   request['User-Agent']   = 'ruby'
+  ##   request['Accept']       = '*/*'
+  if headers && headers.size > 0
+    headers.each do |key,value|
+      request[ key ] = value
+    end
+  end
+
+
+  if auth.size == 2   ## e.g. ['user', 'password']
+    ## always assume basic auth for now
+    ##  auth[0]  => user
+    ##  auth[1]  => password
+    request.basic_auth( auth[0], auth[1] )
+    puts "  using basic auth - user: #{auth[0]}, password: ***"
+  end
+
+
+  puts "GET #{uri}..."
+
+  response = http.request( request )
+
+  ## note: return "unified" wrapped response
+  Response.new( response )
+end  # method self.get
+
+
+end  # class Webclient

data/lib/webclient/webclient-post.rb

@@ -0,0 +1,93 @@
+
+class Webclient
+
+
+
+##
+## todo/check
+##   maybe add a
+###    self.post_form( url, form/params, **kwargs) - why? why not?
+###
+
+def self.post( url, headers: {},
+                    auth: [],
+                    body: nil,
+                    form: nil,
+                    json: nil   ## json - convenience shortcut (for body & encoding)
+              )
+
+  uri = URI.parse( url )
+  http = Net::HTTP.new( uri.host, uri.port )
+
+  if uri.instance_of? URI::HTTPS
+    http.use_ssl     = true
+    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+  end
+
+  request = Net::HTTP::Post.new( uri.request_uri )
+
+  ### add (custom) headers if any
+  ##  check/todo: is there are more idiomatic way for Net::HTTP ???
+  ##   use
+  ##     request = Net::HTTP::Get.new( uri.request_uri, headers )
+  ##    why? why not?
+  ##  instead of e.g.
+  ##   request['X-Auth-Token'] = 'xxxxxxx'
+  ##   request['User-Agent']   = 'ruby'
+  ##   request['Accept']       = '*/*'
+  if headers && headers.size > 0
+    headers.each do |key,value|
+      request[ key ] = value
+    end
+  end
+
+  if auth.size == 2   ## e.g. ['user', 'password']
+    ## always assume basic auth for now
+    ##  auth[0]  => user
+    ##  auth[1]  => password
+    request.basic_auth( auth[0], auth[1] )
+    puts "  using basic auth - user: #{auth[0]}, password: ***"
+  end
+
+
+  if body
+     request.body = body.to_s
+  end
+
+  if form
+     ## fix-fix-fix: urlencode key/values!!!!!
+
+     ###
+     ## maybe use ??
+     ##  uri = URI "http://localhost:4567/greet"
+     ##    params = { :name => 'Peter' }
+     ##    uri.query = URI.encode_www_form params
+
+     form_urlencoded = form.map do |k,v|
+                                     "#{k}=#{v}"
+                                 end.join( '&' )
+
+     request.body = form_urlencoded
+
+    request['Content-Type'] = 'application/x-www-form-urlencoded'
+  end
+
+  if json
+     # note: the body needs to be a JSON string - use pretty generate and NOT "compact" style - why? why not?
+     request.body = JSON.pretty_generate( json )
+
+     ## move (auto-set) header content-type up (before custom headers) - why? why not?
+     request['Content-Type'] = 'application/json'
+  end
+
+
+  puts "POST #{uri}..."
+
+  response = http.request( request )
+
+  ## note: return "unified" wrapped response
+  Response.new( response )
+end  # method self.post
+
+
+end # class Webclient

data/lib/webclient/webclient_response-status.rb

@@ -0,0 +1,50 @@
+class Webclient
+  class Response
+
+    #####################
+    # nested class  Response::Status
+    class Status
+      ### fix-fix-fix
+      ##  maybe fold back
+      ##      into response.status | status_code
+      ##           response.status_message | status_msg
+      ##         keep it simple?
+      ##
+      ##   keep status.ok?    =>  response.ok?
+      ##   keep status.nok?   =>  response.nok?
+
+      attr_reader :code
+
+      def initialize( code, message: nil )
+        ## note - upstream Net::HTTP::Response::code is a string e.g. "200"!!!
+        ##             convert to integer number
+        @code    = code.to_i(10)
+        @message = message
+      end
+
+
+      def to_i()   @code; end    ## use alias_method :to_id, :code - why? why not?
+      def to_int() @code; end
+
+      ##  note - allow compare with integer e.g.
+      ##          response.status == 200
+      def ==(other)
+        other.is_a?(Status) ? code == other.code : code == other.to_i
+      end
+
+
+      def ok?()  code == 200; end
+      def nok?() code != 200; end
+
+      def success?()   (200..299).include?(code); end
+      def redirect?()  (300..399).include?(code); end
+      def error?()     code >= 400; end
+
+
+      def message() @message; end
+      alias_method :msg, :message   ## add/keep shorter alias too - why? why not?
+    end  # (nested) class Status
+
+
+end  # class Response
+end  # class Webclient

data/lib/webclient/webclient_response-text.rb

@@ -0,0 +1,306 @@
+
+class Webclient
+  class Response
+
+
+
+   # regex to capture the charset from both HTML5 and HTML4 meta tags
+   # --  the modern HTML5 <meta charset="..."> tag, or
+   # --  the older HTML4 <meta http-equiv="Content-Type" ...> tag
+   ##   <meta http-equiv="Content-Type" content="text/html;
+   ##          charset=windows-1252"
+   ##     support multi-line (m) - why? why not???
+   ##
+   ## note - add the n (NOENCODING) flag
+   ##  The n flag forces Ruby to compile and process the regex as a raw sequence of bytes
+   ##    (ASCII-8BIT). This allows it to safely match against US-ASCII, ASCII-8BIT,
+   ##   or UTF-8 strings without throwing compatibility errors
+   ##  charset
+   ###   note - charset class was [^"' >]+ changed to more strict/simple [a-z0-9-_]+
+   ##   check if other "weirdo" encoding name exist?
+     HTML_CHARSET_RE = %r{ <meta [^>]+
+                            charset [ ]* = [ ]*
+                                    ["']? (?<charset> [a-z0-9_-]+)
+                        }ixn
+
+     HTML_CHARSET_ALIASES = {
+       'utf8'          => 'UTF-8',
+       'utfs-8'        => 'UTF-8',     ## typo in rsssf (fix otherwise or here??)
+       'cp1252'        => 'Windows-1252',
+       'latin1'        => 'ISO-8859-1',
+       'ascii'         => 'US-ASCII',
+       'binary'        => 'ASCII-8BIT'
+     }
+
+
+
+    ### internal helper
+    ###    to get "upstream" encoding
+    ###         note - unicode bom will override user encoding !!!
+    ##  -- use _text_encoding_upstream or such - why? why not?
+    ##   change/rename _8bit to chars_8bit - why? why not?
+
+    def _text_encoding()        defined?( @_text_encoding )        ?  @_text_encoding : nil;  end
+    def _text_encoding_source() defined?( @_text_encoding_source ) ?  @_text_encoding_source : nil; end
+
+    def _text_encoding_valid()  defined?( @_text_encoding_valid)   ?  @_text_encoding_valid : nil;  end
+    def _text_ascii_only()      defined?( @_text_ascii_only )      ?  @_text_ascii_only   : nil;  end
+    def _text_8bit()            defined?( @_text_8bit )            ?  @_text_8bit         : nil;  end
+    def _text_utf8_replace()    defined?( @_text_utf8_replace )    ?  @_text_utf8_replace : nil; end
+
+
+
+    ##   use encoding: nil   (with fallback 'UTF-8')
+    ##      lets us check if user encoding passed in or
+    ##                    if default fallback used !!!!
+    ##   use for encoding_source (hierarchy) !!
+    ##       e.g.   bom|html|http| user or fallback
+    ##
+    ##    or use a new force_encoding property/option for user
+    ##          e.g.  bom|  force| html|http|...
+
+    ## todo/check: rename encoding to html/http-like charset - why? why not?
+    ##    or keep encoding as used for ruby's strings
+    def _decode_text( encoding: _encoding_user )
+
+      if encoding.nil?
+        encoding = 'UTF-8'     ### use UTF-8 as fallback (default encoding)
+        encoding_source = 'fallback'
+      else
+        encoding_source = 'user'
+      end
+
+
+      # note: Net::HTTP will NOT set encoding UTF-8 etc.
+      # will be set to ASCII-8BIT == BINARY == Encoding Unknown; Raw Bytes Here
+      ##
+      ## todo/assert
+      ##   make sure encoding is  ASCII-8BIT == BINARY !!!
+      ##
+      ## note !!!! - make sure text is always a copy (thus, use dup(licate)!!)
+      ##              NOT a reference to @response.body.to_s
+      ##                otherwise force_encoding
+      ##                    will change the encoding "upstream"
+      text = @response.body.b.dup
+
+
+
+      ##    note  - record 7bit ascii code range (ENC_CODERANGE_7BIT) check (on "raw" blob before changing encoding)
+      ##     see https://shopify.engineering/code-ranges-ruby-strings
+      ##
+      ##  String#ascii_only?
+      ##    returns true if every character in the string has a byte value between 0 and 127.
+      ##
+      ### ENC_CODERANGE_7BIT:
+      ##   Every single byte in the string is between 0 and 127.
+      ##  If this flag is already set, ascii_only?
+      ##  immediately returns true.
+      ##
+      ##  ENC_CODERANGE_VALID:
+      ##    The string contains valid characters for its encoding (like UTF-8),
+      ##   but at least one character is outside the 0–127 range
+      ##   (e.g., it contains a 128+ byte).
+      ## If this flag is set, it immediately returns false.
+      ##
+      ##
+      ##              check before optional bom-removal
+      @_text_ascii_only    = text.ascii_only?
+
+
+      ###
+      ##  note
+      ## auto-check for unicode byte-order marks (BOM)s!!
+      ##   and auto-strip bom!!
+      ##
+      ##  common BOMs to check
+      ##   UTF-8: EF BB BF
+      ##   UTF-16 BE: FE FF
+      ##   UTF-16 LE: FF FE
+      ##   UTF-32 BE: 00 00 FE FF
+      ##   UTF-32 LE: FF FE 00 00
+
+      encoding_bom =
+      if text.start_with?("\x00\x00\xFE\xFF".b)
+         text = text.byteslice(4..)
+         'UTF-32BE'
+      elsif text.start_with?("\xFF\xFE\x00\x00".b)
+         text = text.byteslice(4..)
+         'UTF-32LE'
+      elsif text.start_with?("\xFE\xFF".b)
+         text = text.byteslice(2..)
+         'UTF-16BE'
+      elsif text.start_with?("\xFF\xFE".b)
+         text = text.byteslice(2..)
+         'UTF-16LE'
+      elsif text.start_with?("\xEF\xBB\xBF".b)
+         text = text.byteslice(3..)
+         'UTF-8'
+      else
+         nil   # no bom found
+      end
+
+
+
+
+      if encoding_bom
+        puts "  [debug] auto-removing unicode >#{encoding_bom}< encoding bom (magic bytes) in response.text"
+
+        if encoding_bom.downcase != encoding.downcase
+          puts "  [debug] !!! WARN - auto-fixing response.text encoding; >#{encoding}< overridden by >#{encoding_bom}< unicode encoding bom"
+          encoding = encoding_bom
+        end
+
+        encoding_source = 'bom'
+      else
+         ##   fix-fix-fix   check/add http content type check with charset!!
+         ##
+         ##  check if html content type
+         ##     text/html
+         ##     application/xhtml+xml
+         ##          && check html meta charset in page in first 1028 bytes
+         ##
+         ##  note - content_type might return nil (guard with to_s!!)
+         ##   maybe use/make into  html? helper like gif? pdf? or such
+
+          if content_type.to_s.match?( %r{text/html}i ) ||
+             content_type.to_s.match?( %r{application/xhtml}i )
+
+             if (m = HTML_CHARSET_RE.match( text[0, 1028] ))
+                 encoding_html =  m[:charset]
+                 ## note - normalize encoding_html
+                 ##    plus fix known type errors!!!
+                 encoding_html = HTML_CHARSET_ALIASES[ encoding_html.downcase ] || encoding_html
+
+                 ## fix-fix-fix
+                 ##  validate with ruby's builtin in encoding registry!!!
+                 # 3. Validate against Ruby's internal encoding registry
+                 ## begin
+                 ##   Encoding.find(standard_name).name
+                 ## rescue ArgumentError
+                 ##     unknown encoding!!!
+                 ## end
+
+                 if encoding_html.downcase != encoding.downcase
+                    ## note  - change WARN to INFO
+                    puts "  [debug] !!! WARN - overwrite response.text encoding; >#{encoding}< overridden by >#{encoding_html}< html meta charset"
+                    encoding = encoding_html
+                 end
+
+                 encoding_source = 'html'
+            end
+          end
+      end
+
+
+##
+##    note - allow "hack-y" access to "upstream" encoding used before conversion to utf-8
+##             e.g. use   response._text_encoding or
+##                        response._text_encoding_source  (e.g. bom|html|http|user)
+          @_text_encoding        = encoding
+          @_text_encoding_source = encoding_source
+
+###
+###    if encoding.start_with? utf
+##           or has encoding_bom
+###       do nothing
+##      otherwise
+##           tally all 8-bit ascii chars (above > 127)
+
+      if encoding_bom || encoding.downcase.start_with?( 'utf' )
+           @_text_8bit = nil
+      else
+         ## get/track 8-bit bytes (1xxxxxxx), that is, > 127 (128-255)
+         bytes  = text.bytes.select { |byte| byte > 127 }
+
+         if bytes.empty?
+           @_text_8bit = nil
+         else
+           @_text_8bit = "#{bytes.count} - "
+           ##  bytes.tally
+           ## e.g.  {195=>1, 169=>1, 240=>1, 159=>1, 152=>1, 138=>1}
+           ##    note - use sort (turns in array e.g. [[138,1],...])
+           @_text_8bit += bytes.tally.sort.map {|ord,count| "#{ord}=>#{count}"}.join(', ')
+         end
+      end
+
+
+
+
+
+
+      if encoding.downcase == 'utf-8'
+         text = text.force_encoding( Encoding::UTF_8 )
+
+         ## track/check code range if valid/broken
+         @_text_encoding_valid = text.valid_encoding?
+      else
+        ## [debug] GET=http://www.football-data.co.uk/mmz4281/0405/SC0.csv
+        ##    Encoding::UndefinedConversionError: "\xA0" from ASCII-8BIT to UTF-8
+        ##     note:  0xA0 (160) is NBSP (non-breaking space) in Windows-1252
+
+       ## note: assume windows encoding (for football-data.uk)
+       ##   use "Windows-1252" for input and convert to utf-8
+       ##
+       ##    see https://www.justinweiss.com/articles/3-steps-to-fix-encoding-problems-in-ruby/
+       ##    see https://en.wikipedia.org/wiki/Windows-1252
+       ## txt = txt.force_encoding( 'Windows-1252' )
+       ## txt = txt.encode( 'UTF-8' )
+       ##   Encoding::UTF_8 => 'UTF-8'
+          puts "  [debug] try converting response.text encoding from >#{encoding}< to >UTF-8<"
+          text = text.force_encoding( encoding )
+
+          ## track/check code range if valid/broken
+          ##   note - check BEFORE conversion to utf-8 - why? why not?
+          @_text_encoding_valid = text.valid_encoding?
+
+          ## note be more tolerant when converting - use replace for now - why? why not?
+          ##   maybe add a strict (no replace) version later
+             text = text.encode(
+                      Encoding::UTF_8,
+                         invalid: :replace,
+                         undef:   :replace,
+                         replace: "�"
+                      )
+
+               errors = text.scan( "�" )
+               if errors.size > 0
+                  puts "  [debug] !!! WARN - #{errors.size} invalid/undef character encoding error(s) replaced w/ �"
+                  @_text_utf8_replace = errors.size
+              end
+      end
+
+
+     # Normalize unicode (utf-8) string to Composed (NFC)
+     #    NFC (Normalization Form Canonical Composition)
+
+=begin
+  use nfkc ??
+  or delegate to userland??
+
+Pro-Tip: Watch out for Ligatures and Compatibility Issues
+While NFC handles standard accents beautifully,
+you might occasionally want NFKC (Normalization Form Compatibility Composition)
+instead.
+ pages sometimes contain legacy typographical quirks like:
+ Ligatures: The characters fi or fl typed as a single glyph.
+ Roman Numerals / Fractions: Characters like Ⅳ or ½.
+
+ If you use standard NFC, those symbols remain as complex single characters.
+ If you use NFKC, Ruby will break them down into standard,
+ easily searchable text (fi becomes fi, Ⅳ becomes IV, and ½ becomes 1/2).
+=end
+
+     ###
+     ##  todo/check -  add nfc: true|false
+     ##                   to text() as option (if unicode - utf8)  - why? why not?
+     ##                or text_unicode( nfc: true|false )
+
+     ##  comment out for now - get
+     ##    unicode_normalize/normalize.rb:126:in `gsub': invalid byte sequence in UTF-8
+      text = text.unicode_normalize(:nfc)
+
+      text
+    end
+
+end # class Response
+end  # class Webclient

data/lib/webclient/webclient_response.rb

@@ -0,0 +1,112 @@
+
+class Webclient
+  # wrap Net::HTTP::Response  or
+  #    maybe HTTPX or such in the future
+
+  ## check - rename to HttpResponse?
+  ##      and use  HttpErrorResponse or such - why? why not?
+  class Response
+    def initialize( response )
+      @response = response
+    end
+
+    ## todo - find a better name for underlying object - instead of raw use ??
+    ##   note - raw used by python requests too
+    ##            use for streaming and such - why? why not?
+    def raw() @response; end
+
+
+    ###############
+    ##  response status methods
+
+    def status
+      @status ||= Status.new( @response.code, message: @response.message )
+    end
+
+    ## add  "flat" shortcuts - keep - why? why not?
+    def status_code()  status.to_i; end
+    def ok?()          status.ok?; end
+    def nok?()         status.nok?; end
+
+
+
+    ###
+    ## keep http_version on Response - why? why not?
+    ##    only really 1.0 and 1.1
+    ##      check if value is a string?
+    def version() @response.http_version; end
+    alias_method :http_version, :version   ## add/keep longer alias too - why? why not?
+
+
+
+
+
+    ###
+    #  note - add a writeable  encoding_user attribute
+    ##            on default (if not set by user) returns nil
+    def _encoding_user=( value ) @_encoding_user = value; end
+    def _encoding_user()  defined?( @_encoding_user )  ?  @_encoding_user : nil;  end
+
+    ## cache (returned) decoded text - why? why not?
+    def text( encoding: _encoding_user )
+        @text ||= _decode_text( encoding: encoding )
+    end
+
+    ## convenience helper; returns parsed json data; note: always assume utf-8 (text) encoding
+    ##   cache returned (parsed) json value - why? why not?
+    ##   add :symbolize_keys option - why? why not?
+    def json
+        @json ||= JSON.parse( text )
+    end
+
+
+
+    ##  always use t raw binary data
+    ##  and always use  @response.body.b
+    ##         or body.b  (binary ascii-7bit) string/buffer here !!!!
+    ##
+
+    def body() @response.body.b; end
+    alias_method :blob, :body
+
+
+
+    ################
+    # nested class Response::Headers
+    class Headers
+      def initialize( response )
+        @response = response
+      end
+      def each( &blk )
+        @response.each_header do |key, value|  # iterate all response headers
+          blk.call( key, value )
+        end
+      end
+    end    # nested class Response::Headers
+
+    def headers
+       @headers ||= Headers.new( @response )
+    end
+
+
+
+
+    ## add some predefined/built-in header(s) convenience shortcuts
+    ## check: change to headers['content-type'] or such - why? why not?
+    def content_type()    @response.content_type; end
+    def content_length()  @response.content_length; end
+
+    ###
+    ##  note - content_type might return nil, thus, use to_s (gets converted to "")
+    def image_jpg?()   content_type.to_s.match?( %r{image/jpeg}i );   end
+    def image_png?()   content_type.to_s.match?( %r{image/png}i );    end
+    def image_gif?()   content_type.to_s.match?( %r{image/gif}i );    end
+
+    alias_method :image_jpeg?, :image_jpg?
+    alias_method :jpeg?, :image_jpg?
+    alias_method :jpg?, :image_jpg?
+    alias_method :png?, :image_png?
+    alias_method :gif?, :image_gif?
+
+end ##  class Response
+end  # class Webclient

data/lib/webclient.rb

@@ -1,25 +1,38 @@
-require 'pp'
-require 'time'
-require 'date'
-require 'fileutils'
-
-require 'uri'
-require 'net/http'
-require 'net/https'
-
-require 'json'
-require 'yaml'
-
-
-# our own code
-require 'webclient/version'   # note: let version always go first
-require 'webclient/webclient'
-
-
-############
-## add convenience alias for camel case / alternate different spelling
-WebClient = Webclient
-
-
-# say hello
-puts Webclient.banner     ## if defined?( $RUBYLIBS_DEBUG )
+###
+## note - requires basicially a mirror/clone of cococs "prelude/prolog"
+##           see <https://github.com/rubycocos/cocos/blob/master/lib/cocos.rb>
+
+require 'pp'
+require 'time'
+require 'date'
+require 'fileutils'
+require 'pathname'   ### auto-add for use of relative_path construction
+require 'base64'     ### ## e.g. Base64.decode64,Base64.encode64,...
+
+require 'uri'
+require 'net/http'
+require 'net/https'
+require 'cgi'        ## auto-add  for use of params encoding
+
+require 'json'
+require 'yaml'
+
+
+
+# our own code
+require_relative 'webclient/version'   # note: let version always go first
+
+require_relative 'webclient/webclient-get'
+require_relative 'webclient/webclient-post'
+require_relative 'webclient/webclient_response'
+require_relative 'webclient/webclient_response-status'
+require_relative 'webclient/webclient_response-text'
+
+
+############
+## add convenience alias for camel case / alternate different spelling
+WebClient = Webclient
+
+
+# say hello
+puts Webclient.banner     ## if defined?( $RUBYLIBS_DEBUG )

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: webclient
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-05 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
@@ -36,17 +36,17 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.22'
+        version: '4.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.22'
+        version: '4.2'
 description: webclient gem - yet (another) universal network client interface for
   world wide web (www) requests via HTTP
-email: ruby-talk@ruby-lang.org
+email: gerald.bauer@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files:
@@ -60,8 +60,12 @@ files:
 - Rakefile
 - lib/webclient.rb
 - lib/webclient/version.rb
-- lib/webclient/webclient.rb
-homepage: https://github.com/rubycoco/webclient
+- lib/webclient/webclient-get.rb
+- lib/webclient/webclient-post.rb
+- lib/webclient/webclient_response-status.rb
+- lib/webclient/webclient_response-text.rb
+- lib/webclient/webclient_response.rb
+homepage: https://github.com/rubycocos/webclient
 licenses:
 - Public Domain
 metadata: {}
@@ -82,7 +86,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: webclient gem - yet (another) universal network client interface for world

data/lib/webclient/webclient.rb

@@ -1,170 +0,0 @@
-
-class Webclient
-
-  class Response   # nested class - wrap Net::HTTP::Response
-    def initialize( response )
-      @response = response
-    end
-    def raw() @response; end
-
-
-    ## todo/check: rename encoding to html/http-like charset - why? why not?
-    def text( encoding: 'UTF-8' )
-      # note: Net::HTTP will NOT set encoding UTF-8 etc.
-      # will be set to ASCII-8BIT == BINARY == Encoding Unknown; Raw Bytes Here
-      # thus, set/force encoding to utf-8
-      text = @response.body.to_s
-      if encoding.downcase == 'utf-8'
-         text = text.force_encoding( Encoding::UTF_8 )
-      else
-    ## [debug] GET=http://www.football-data.co.uk/mmz4281/0405/SC0.csv
-    ##    Encoding::UndefinedConversionError: "\xA0" from ASCII-8BIT to UTF-8
-    ##     note:  0xA0 (160) is NBSP (non-breaking space) in Windows-1252
-
-    ## note: assume windows encoding (for football-data.uk)
-    ##   use "Windows-1252" for input and convert to utf-8
-    ##
-    ##    see https://www.justinweiss.com/articles/3-steps-to-fix-encoding-problems-in-ruby/
-    ##    see https://en.wikipedia.org/wiki/Windows-1252
-    ## txt = txt.force_encoding( 'Windows-1252' )
-    ## txt = txt.encode( 'UTF-8' )
-    ##   Encoding::UTF_8 => 'UTF-8'
-        puts " [debug] converting response.text encoding from >#{encoding}< to >UTF-8<"
-
-        text = text.force_encoding( encoding )
-        text = text.encode( Encoding::UTF_8 )
-      end
-
-      text
-    end
-
-    ## convenience helper; returns parsed json data; note: always assume utf-8 (text) encoding
-    def json() JSON.parse( text ); end
-
-
-
-    class Headers # nested (nested) class
-      def initialize( response )
-        @response = response
-      end
-      def each( &blk )
-        @response.each_header do |key, value|  # Iterate all response headers
-          blk.call( key, value )
-        end
-      end
-    end
-    def headers() @headers ||= Headers.new( @response ); end
-
-    class Status  # nested (nested) class
-      def initialize( response )
-        @response = response
-      end
-      def code() @response.code.to_i; end
-      def ok?()  code == 200; end
-      def nok?() code != 200; end
-      def message() @response.message; end
-    end
-    def status() @status ||= Status.new( @response ); end
-  end # (nested) class Response
-
-
-def self.get( url, headers: {}, auth: [] )
-
-  uri = URI.parse( url )
-  http = Net::HTTP.new( uri.host, uri.port )
-
-  if uri.instance_of? URI::HTTPS
-    http.use_ssl     = true
-    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
-  end
-
-  request = Net::HTTP::Get.new( uri.request_uri )
-
-  ### add (custom) headers if any
-  ##  check/todo: is there are more idiomatic way for Net::HTTP ???
-  ##   use
-  ##     request = Net::HTTP::Get.new( uri.request_uri, headers )
-  ##    why? why not?
-  ##  instead of e.g.
-  ##   request['X-Auth-Token'] = 'xxxxxxx'
-  ##   request['User-Agent']   = 'ruby'
-  ##   request['Accept']       = '*/*'
-  if headers && headers.size > 0
-    headers.each do |key,value|
-      request[ key ] = value
-    end
-  end
-
-
-  if auth.size == 2   ## e.g. ['user', 'password']
-    ## always assume basic auth for now
-    ##  auth[0]  => user
-    ##  auth[1]  => password
-    request.basic_auth( auth[0], auth[1] )
-    puts "  using basic auth - user: #{auth[0]}, password: ***"
-  end
-
-
-  puts "GET #{uri}..."
-
-  response = http.request( request )
-
-  ## note: return "unified" wrapped response
-  Response.new( response )
-end  # method self.get
-
-
-def self.post( url, headers: {},
-                    body: nil,
-                    json: nil   ## json - convenience shortcut (for body & encoding)
-              )
-
-  uri = URI.parse( url )
-  http = Net::HTTP.new( uri.host, uri.port )
-
-  if uri.instance_of? URI::HTTPS
-    http.use_ssl     = true
-    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
-  end
-
-  request = Net::HTTP::Post.new( uri.request_uri )
-
-  ### add (custom) headers if any
-  ##  check/todo: is there are more idiomatic way for Net::HTTP ???
-  ##   use
-  ##     request = Net::HTTP::Get.new( uri.request_uri, headers )
-  ##    why? why not?
-  ##  instead of e.g.
-  ##   request['X-Auth-Token'] = 'xxxxxxx'
-  ##   request['User-Agent']   = 'ruby'
-  ##   request['Accept']       = '*/*'
-  if headers && headers.size > 0
-    headers.each do |key,value|
-      request[ key ] = value
-    end
-  end
-
-  if body
-     request.body = body.to_s
-  end
-
-  if json
-     # note: the body needs to be a JSON string - use pretty generate and NOT "compact" style - why? why not?
-     request.body = JSON.pretty_generate( json )
-
-     ## move (auto-set) header content-type up (before custom headers) - why? why not?
-     request['Content-Type'] = 'application/json'
-  end
-
-
-  puts "POST #{uri}..."
-
-  response = http.request( request )
-
-  ## note: return "unified" wrapped response
-  Response.new( response )
-end  # method self.post
-
-
-end  # class Webclient
-