smb-client 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 74e4c55cf1373694b5add4df963fdd2724e4530f
-  data.tar.gz: 261879d622d0e1f3e07d7e61f010dcf21d22e81e
+  metadata.gz: 3f651dd31ee5d350f7e0b360cf174e194ae9bfab
+  data.tar.gz: b45cb7eb1f73c605139795bc71355ed75d04f8c1
 SHA512:
-  metadata.gz: 237d79a37f9ec4ae6ea87a7bd4c35c2928937139b8543695e1e22373819df74e10c019415bf5ea03ae5bda77aaf05bc886e44b267b484df57dd627e57136554c
-  data.tar.gz: 242f5cfffd62044a694f516e17c1aa72bf2fbd6ef5a95f28a414e0d5f31fbbc42123fb1f38f76be2317ecb25d399c55576cb018fefad4205f3d697b0b6a18b74
+  metadata.gz: 9777debb5d8176ab01f543f8c37c8ffde3c9a6c5418745690ff927a1d2254ef826474c396144fe0ac2840958912a4cf00b7b6be54ea305d343bcdc2cc7c20b6e
+  data.tar.gz: 913a1a40edd78e053effd7cff12fe46a92b6ab7b061bbbc9dba19623bf158efde5bfe170a3b7fe9b9756cb39786fb2d801eaaf68f4e99e232461d376de066429

data/CODE_OF_CONDUCT.md

@@ -55,7 +55,7 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at ralf@rherzog.de. All
+reported by contacting the project team at ralf.herzog@netcom-kassel.de. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.

data/Gemfile.lock

@@ -1,13 +1,20 @@
 PATH
   remote: .
   specs:
-    smb-client (0.1.0)
+    smb-client (0.1.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    docile (1.1.5)
+    json (2.1.0)
     minitest (5.10.3)
     rake (10.5.0)
+    simplecov (0.15.1)
+      docile (~> 1.1.0)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
 
 PLATFORMS
   ruby
@@ -16,6 +23,7 @@ DEPENDENCIES
   bundler (~> 1.16)
   minitest (~> 5.0)
   rake (~> 10.0)
+  simplecov
   smb-client!
 
 BUNDLED WITH

data/README.md

@@ -16,16 +16,18 @@ gem 'smb/client'
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundler install
+```
 
 Or install it yourself as:
 
-    $ gem install smb-client
+```bash
+$ gem install smb-client
+```
 
 ## Usage
 
-### Setup
-
 ```ruby
 require 'smb/client'
 
@@ -42,7 +44,7 @@ options = {
 
 ### List directories
 
-Always returns an array with `LsItem` elements.
+Always returns an array containing `LsItem` elements.
 
 ```ruby
 @smb_client.ls
@@ -75,6 +77,24 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+### Setup a SMB server for tests
+
+For example with docker:
+```bash
+$ docker run -d -t --name samba -v /mount -d dperson/samba -u "guest1;pass1" -s "guest1_private;/mount;no;no;no;guest1" -w WORKGROUP
+$ docker exec samba chmod 777 /mount
+```
+
+To get the container ip address run:
+
+```bash
+$ docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' samba
+```
+
+This returns for example: `172.17.0.2`
+
+Now set the IP in the [test_helper.rb](https://github.com/NetcomKassel/smb-client/blob/master/test/test_helper.rb)'s `SMB_CLIENT_OPTIONS` hash.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/NetcomKassel/smb-client. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
@@ -85,4 +105,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the SMB::Client project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/RalfHerzog/smb-client/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the SMB::Client project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/NetcomKassel/smb-client/blob/master/CODE_OF_CONDUCT.md).

data/lib/smb/client/client.rb

@@ -8,11 +8,14 @@ require_relative 'client_helper'
 require_relative 'runtime_error'
 
 module SMB
+  # Low-level interface to smbclient executable
   class Client
     include ClientHelper
 
     attr_accessor :executable, :pid
 
+    # Creates a new instance and connects to server
+    # @param [Hash] options Hash with connection options
     def initialize(options = {})
       @executable = ENV.fetch('SMBCLIENT_EXECUTABLE') { 'smbclient' }
       @options = {
@@ -40,11 +43,14 @@ module SMB
       @shutdown_in_progress = false
     end
 
+    # Closes the connection to the server end terminates all running threads
     def close
       @shutdown_in_progress = true
       Process.kill('QUIT', @pid) == 1
     end
 
+    # Execute a smbclient command
+    # @param [String] cmd The command to be executed
     def exec(cmd)
       # Send command
       @write1.puts cmd
@@ -66,8 +72,9 @@ module SMB
 
     private
 
+    # Connect to the server using separate threads and pipe for communications
     def connect
-      # Run +@executable+ in a separate thread to talk to hin asynchronosly
+      # Run +@executable+ in a separate thread to talk to hin asynchronously
       Thread.start do
         # Spawn the actual +@executable+ pty with +input+ and +output+ handle
         begin
@@ -83,8 +90,6 @@ module SMB
               end
             end
 
-            @connection_established = true
-
             # Wait for responses ending with input prompt
             loop do
               output.expect(/smb: \\>$/) { |text| handle_response text }
@@ -102,6 +107,8 @@ module SMB
       end
     end
 
+    # Returns the parameters for the +smbclient+ command
+    # @return [String] The parameters
     def params
       @options.map do |k, v|
         v.nil? && raise(Client::RuntimeError, "Missing option [:#{k}]")
@@ -110,17 +117,21 @@ module SMB
 -U #{@options[:user]} #{@options[:workgroup]} -m SMB#{@options[:version]}"
     end
 
+    # Handles a response from smbclient
     def handle_response(text)
       # Write to second pipe so the origin command invocation thread can
       # receive this
       if @first_message
         @first_message = false
+        # TODO: Filter for server information? => Domain, OS and Server
+
+        @connection_established = true
         return
       end
 
       # Format responses
       # Ignore command sent (the first returned line) and the last returned
-      # which is the smb prompt
+      # which is the smb prompt ("smb: \>")
       @write2.write text[0].lines[1..-2].join
       @write2.close
     end

data/lib/smb/client/client_helper.rb

@@ -1,38 +1,16 @@
 require 'time'
 require 'tempfile'
 
+require_relative 'ls_item'
+
 module SMB
+  # Helper methods to get simpler access to smbclient's capabilities
   module ClientHelper
-    class LsItem
-      REGEX = /(?<name>[\.|\w]+)\s+(?<type>.)\s+(?<size>\d+)\s+(?<change_time>.+)/
-
-      attr_accessor :name, :type, :size, :change_time
-
-      def file?
-        @type.include? 'N'
-      end
-
-      def directory?
-        @type.include? 'D'
-      end
-
-      def hidden?
-        @type.include? 'H'
-      end
-
-      def self.from_line(line)
-        match_data = REGEX.match line
-        return nil unless match_data
-
-        item = LsItem.new
-        item.name = match_data['name']
-        item.type = match_data['type']
-        item.size = match_data['size'].to_i
-        item.change_time = Time.parse match_data['change_time']
-        item
-      end
-    end
-
+    # List contents of a remote directory
+    # @param [String] mask The matching mask
+    # @param [Boolean] raise If set, an error will be raised. If set to
+    # +false+, an empty array will be returned
+    # @return [Array] List of +mask+ matching LsItems
     def ls(mask = '', raise = true)
       ls_items = []
       output = exec 'ls ' + mask
@@ -46,8 +24,13 @@ module SMB
       []
     end
 
+    # +dir+ is an alias for +ls+
     alias dir ls
 
+    # Creates a new directory on the server
+    # @param [String] path The path to be created
+    # @param [Boolean] raise raise Error or just return +false+
+    # @return [Boolean] true on success
     def mkdir(path, raise = true)
       exec 'mkdir ' + path
       true
@@ -56,6 +39,10 @@ module SMB
       false
     end
 
+    # Removes a directory on the server
+    # @param [String] path The path to be removed
+    # @param [TrueClass/FalseClass] raise raise Error or just return +false+
+    # @return [Boolean] true on success
     def rmdir(path, raise = true)
       exec 'rmdir ' + path
       true
@@ -64,6 +51,12 @@ module SMB
       false
     end
 
+    # Upload a local file
+    # @param [String] from The source file path (on local machine)
+    # @param [String] to The destination file path
+    # @param [Boolean] overwrite Overwrite if exist on server?
+    # @param [Boolean] raise raise Error or just return +false+
+    # @return [Boolean] true on success
     def put(from, to, overwrite = false, raise = true)
       ls_items = ls to, false
       if !overwrite && !ls_items.empty?
@@ -76,7 +69,14 @@ module SMB
       false
     end
 
+    # Writes content to remote file
+    # @param [String] content The content to be written
+    # @param [String] to The destination file path
+    # @param [Boolean] overwrite Overwrite if exist on server?
+    # @param [Boolean] raise raise Error or just return +false+
+    # @return [Boolean] true on success
     def write(content, to, overwrite = false, raise = true)
+      # This is just a hack around +put+
       tempfile = Tempfile.new
       tempfile.write content
       tempfile.close
@@ -84,6 +84,10 @@ module SMB
       put tempfile.path, to, overwrite, raise
     end
 
+    # Delete a remote file
+    # @param [String] path The remote file to be deleted
+    # @param [Boolean] raise raise raise Error or just return +false+
+    # @return [Boolean] true on success
     def del(path, raise = true)
       exec 'del ' + path
       true
@@ -92,12 +96,22 @@ module SMB
       false
     end
 
+    # +rm+ is an alias for +del+
     alias rm del
 
+    # Receive a file from the smb server to local.
+    # If +to+ was not passed, a tempfile will be generated.
+    # @param [String] from The remote file to be read
+    # @param [String] to local file path to be created
+    # @param [Boolean] overwrite Overwrite if exist locally?
+    # @param [Boolean] raise raise Error or just return +false+
     def get(from, to = nil, overwrite = false, raise = true)
+      # Create a new tempfile but delete it
+      # The tempfile.path should be free to use now
       tempfile = Tempfile.new
       to ||= tempfile.path
       tempfile.unlink
+
       if !overwrite && File.exist?(to)
         raise Client::RuntimeError, "File [#{to}] already exist locally"
       end
@@ -108,6 +122,11 @@ module SMB
       false
     end
 
+    # Reads a remote file and return its content
+    # @param [String] from The file to be read from server
+    # @param [Boolean] overwrite Overwrite if exist locally?
+    # @param [Boolean] raise raise Error or just return +false+
+    # @return [String] The content of the remote file
     def read(from, overwrite = false, raise = true)
       tempfile = Tempfile.new
       to = tempfile.path

data/lib/smb/client/ls_item.rb

@@ -0,0 +1,35 @@
+require 'time'
+
+module SMB
+  module ClientHelper
+    class LsItem
+      REGEX = /(?<name>[\.|\w]+)\s+(?<type>.)\s+(?<size>\d+)\s+(?<change_time>.+)/
+
+      attr_accessor :name, :type, :size, :change_time
+
+      def file?
+        @type.include? 'N'
+      end
+
+      def directory?
+        @type.include? 'D'
+      end
+
+      def hidden?
+        @type.include? 'H'
+      end
+
+      def self.from_line(line)
+        match_data = REGEX.match line
+        return nil unless match_data
+
+        item = LsItem.new
+        item.name = match_data['name']
+        item.type = match_data['type']
+        item.size = match_data['size'].to_i
+        item.change_time = Time.parse match_data['change_time']
+        item
+      end
+    end
+  end
+end

data/lib/smb/client/version.rb

@@ -1,5 +1,5 @@
 module SMB
   class Client
-    VERSION = '0.1.1'.freeze
+    VERSION = '0.1.2'.freeze
   end
 end

data/smb-client.gemspec

@@ -33,4 +33,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '~> 1.16'
   spec.add_development_dependency 'minitest', '~> 5.0'
   spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'simplecov'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: smb-client
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Ralf Herzog
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-11-19 00:00:00.000000000 Z
+date: 2017-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: SMB Client wrapper for smbclient executable
 email:
 - ralf@rherzog.de
@@ -73,6 +87,7 @@ files:
 - lib/smb/client/client.rb
 - lib/smb/client/client_helper.rb
 - lib/smb/client/connection_error.rb
+- lib/smb/client/ls_item.rb
 - lib/smb/client/runtime_error.rb
 - lib/smb/client/version.rb
 - smb-client.gemspec