dire 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e906e8fff287d41ee5dd703c581b631ab621fdff3a7756dcd42cea4b1c533866
+  data.tar.gz: 51e92742b580410563a5860dbcbad8dde8a257a5a5520a88bbdb3cb15b53f48d
+SHA512:
+  metadata.gz: cceb3d5d623e467593dd395b302116d0e95a89ccc69908434c7cd1dc74af57d6eef4de4b34e3a6e44d1a2b1d8170d0a03a657e17b7557b3936fe79951ca6176a
+  data.tar.gz: 568fdf77d605419283ebb50ce7da44e35aa4af773ed01facb02319369e1fb641d54c582497847b23825bb71262f741d648d790fee2fd7f05f7b54bede11650ea

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Filip Pyda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,121 @@
+Dire
+====
+
+Simple `Pathname` wrapper that provides convenient
+and safe interface for filesystem traversal.
+
+Useful in situations where you need to accept parameters
+from external sources (like HTTP request) or read data from
+potentially unsafe directory structure (containing symbolic
+links).
+
+Main Features:
+--------------
+
+* simple interface,
+* easy to test,
+* restrict access to selected directory (paths, links),
+* content type recognition (binary, mime),
+* ignore pattern support.
+
+Sample Usage:
+-------------
+
+Restrict access to directory:
+
+```ruby
+root = Dire.root 'path/to/dir'
+=> #<Dire::Dir>
+```
+
+Basic `Dire::Dir` methods:
+
+```ruby
+dir = root.get 'path/to/subdir'
+=> #<Dire::Dir>
+
+dir.dirs
+=> [#<Dire::Dir>, #<Dire::Dir>, ...]
+
+dir.files
+=> [#<Dire::File>, #<Dire::File>, ...]
+
+root.list
+=> [#<Dire::Dir>, #<Dire::File>, ...]
+```
+
+Basic `Dire::File` methods:
+
+```ruby
+file = dir.get 'path/to/file.txt'
+=> #<Dire::File>
+
+# check data encoding
+file.binary?
+=> false
+
+# get MimeMagic (mimemagic gem)
+file.mime
+=> #<MimeMagic>
+
+# inverse of binary
+file.text?
+=> true
+```
+
+Common `Dire::Node` methods:
+
+```ruby
+# associated Pathname (for IO use)
+file.path
+=> #<Pathname>
+
+# alias of path
+file.absolute_path
+=> #<Pathname>
+
+# relative as string
+file.param
+=> #<String>
+
+# relative to root
+file.relative_path
+=> #<Pathname>
+```
+
+Ignore patterns:
+
+```ruby
+Dire::IGNORE << 'globbing/pattern'
+
+# raises Dire::Error::InvalidPath
+dir.get 'path/matching/pattern'
+```
+
+For more information check [lib](https://github.com/f6p/dire/tree/master/lib)
+and [test](https://github.com/f6p/dire/tree/master/test).
+
+Rails Usage:
+------------
+
+Add `dire` gem.
+
+Add route:
+
+```ruby
+get 'controller_path(/:path_parameter)',
+  as: 'route_name',
+  to: 'controller_name#action_name',
+  constraints: { path: /.+/ },
+  format: false
+```
+
+Force HTML:
+
+```ruby
+before_action :force_html, only: 'action_name'
+
+def force_html
+ request.format = :html
+end
+```

data/lib/dire/dir.rb

@@ -0,0 +1,56 @@
+module Dire
+  class Dir < Node
+    @@invalid_link_handler = -> (path) {}
+
+    def self.invalid_link_handler= lambda
+      @@invalid_link_handler = lambda
+    end
+
+    @@invalid_path_handler = -> (path) {}
+
+    def self.invalid_path_handler= lambda
+      @@invalid_path_handler = lambda
+    end
+
+    def dirs
+      nodes.select { |i| i.absolute_path.directory? }
+    end
+
+    def files
+      nodes.select { |i| not i.absolute_path.directory? }
+    end
+
+    def list
+      dirs + files
+    end
+
+    def root?
+      not parent
+    end
+
+    def validate!
+      super && validate_type!('directory')
+    end
+
+    private
+
+    def nodes
+      return @nodes if @nodes
+
+      @nodes = absolute_path.glob '*', ::File::FNM_DOTMATCH
+      @nodes = @nodes.filter_map do |node|
+        next if ignore? node
+
+        if absolute_path.to_s < node.to_s
+          begin
+            get node
+          rescue Dire::Error::InvalidLink
+            @@invalid_link_handler.(node)
+          rescue Dire::Error::InvalidPath
+            @@invalid_path_handler.(node)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dire/error/base.rb

@@ -0,0 +1,5 @@
+module Dire
+  module Error
+    class Base < StandardError ; end
+  end
+end

data/lib/dire/error/invalid_link.rb

@@ -0,0 +1,5 @@
+module Dire
+  module Error
+    class InvalidLink < Base ; end
+  end
+end

data/lib/dire/error/invalid_path.rb

@@ -0,0 +1,5 @@
+module Dire
+  module Error
+    class InvalidPath < Base ; end
+  end
+end

data/lib/dire/error/invalid_root.rb

@@ -0,0 +1,5 @@
+module Dire
+  module Error
+    class InvalidRoot < Base ; end
+  end
+end

data/lib/dire/file.rb

@@ -0,0 +1,27 @@
+require 'mimemagic'
+
+module Dire
+  class File < Node
+    def binary?
+      return @binary if @binary
+
+      unless %w(application text).include? mime.mediatype
+        return @binary = true
+      end
+
+      @binary = !absolute_path.read.valid_encoding? rescue true
+    end
+
+    def mime
+      @mime ||= MimeMagic.by_magic absolute_path.open
+    end
+
+    def text?
+      !binary?
+    end
+
+    def validate!
+      super && validate_type!('file')
+    end
+  end
+end

data/lib/dire/link.rb

@@ -0,0 +1,27 @@
+module Dire
+  class Link < Node
+    def broken?
+      !link.exist? || !inside?(link)
+    end
+
+    def param
+      chop(link).to_s
+    end
+
+    def validate!
+      super && validate_type!('link')
+
+      if broken?
+        raise Dire::Error::InvalidLink, 'Dead link'
+      end
+
+      true
+    end
+
+    private
+
+    def link
+      path.readlink.expand_path path.dirname
+    end
+  end
+end

data/lib/dire/mixin/check.rb

@@ -0,0 +1,57 @@
+module Dire::Mixin::Check
+  def == other
+    path.to_s == other.path.to_s
+  end
+
+  def broken?
+    false
+  end
+
+  def known?
+    true
+  end
+
+  def parent? node
+    parent == node
+  end
+
+  def root?
+    false
+  end
+
+  def validate!
+    begin
+      raise Errno::ENOENT if ignore? path
+
+      path.lstat
+    rescue Errno::ENOENT
+      raise Dire::Error::InvalidPath, 'Not found'
+    end
+
+    unless inside? path
+      raise Dire::Error::InvalidPath, 'Outside root'
+    end
+
+    true
+  end
+
+  private
+
+  def ignore? path
+    Dire::IGNORE.any? do |ignore|
+      File.fnmatch? ignore, path, File::FNM_PATHNAME
+    end
+  end
+
+  def inside? path
+    expand(path).to_s.index(root.to_s) == 0
+  end
+
+  def validate_type! name
+    unless type == name
+      raise Dire::Error::InvalidPath, 'Node missmatch'
+    end
+
+    true
+  end
+end

data/lib/dire/mixin/path.rb

@@ -0,0 +1,23 @@
+module Dire::Mixin::Path
+  def absolute_path
+    path
+  end
+
+  def param
+    relative_path.to_s
+  end
+
+  def relative_path
+    chop path
+  end
+
+  private
+
+  def chop pth
+    expand(pth).relative_path_from(root)
+  end
+
+  def expand pth
+    path.join(pth).expand_path
+  end
+end

data/lib/dire/node.rb

@@ -0,0 +1,60 @@
+module Dire
+  class Node
+    include Mixin::Check
+    include Mixin::Path
+
+    attr_reader :path, :root
+
+    def initialize node, root, validate = true
+      @path = str2abs node
+      @root = plant root
+
+      validate! if validate
+    end
+
+    def get path, validate = true
+      path = expand path
+      type = path.ftype rescue nil
+
+      const = case type
+        when 'directory' then Dir
+        when 'file'      then File
+        when 'link'      then Link
+
+        else Other
+      end
+
+      const.new path, root, validate
+    end
+
+    def parent
+      Dire::Dir.new absolute_path.join('..'), root
+    rescue Error::InvalidPath
+      nil
+    end
+
+    def to_s
+      relative_path.to_s
+    end
+
+    def type
+      path.ftype rescue 'other'
+    end
+
+    private
+
+    def plant root
+      root = str2abs root
+
+      unless root.directory?
+        raise Dire::Error::InvalidRoot, 'Not a dir'
+      end
+
+      root
+    end
+
+    def str2abs path
+      Pathname.new(path).expand_path
+    end
+  end
+end

data/lib/dire/other.rb

@@ -0,0 +1,15 @@
+module Dire
+  class Other < Node
+    def known?
+      false
+    end
+
+    def type
+      'other'
+    end
+
+    def validate!
+      super && validate_type!('other')
+    end
+  end
+end

data/lib/dire/version.rb

@@ -0,0 +1,3 @@
+module Dire
+  VERSION = "0.1.0"
+end

data/lib/dire.rb

@@ -0,0 +1,12 @@
+require 'zeitwerk'
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+module Dire
+  IGNORE=%w()
+
+  def self.root path
+    Dire::Dir.new path, path
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: dire
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Filip Pyda
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-11-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mimemagic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.3
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.4.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.4.2
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.14.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.14.4
+description: Personal
+email:
+- filip.pyda@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE.txt
+files:
+- LICENSE.txt
+- README.md
+- lib/dire.rb
+- lib/dire/dir.rb
+- lib/dire/error/base.rb
+- lib/dire/error/invalid_link.rb
+- lib/dire/error/invalid_path.rb
+- lib/dire/error/invalid_root.rb
+- lib/dire/file.rb
+- lib/dire/link.rb
+- lib/dire/mixin/check.rb
+- lib/dire/mixin/path.rb
+- lib/dire/node.rb
+- lib/dire/other.rb
+- lib/dire/version.rb
+homepage: https://github.com/f6p/dire
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.22
+signing_key:
+specification_version: 4
+summary: Filesystem Browser
+test_files: []