couch-quilt 0.2.1

data/.gitignore

@@ -0,0 +1,3 @@
+coverage
+pkg
+rdoc

data/INSTALL

@@ -0,0 +1,32 @@
+Installing Quilt
+================
+
+Dependencies
+------------
+
+Quilt is written in Ruby using the Ruby FuseFS library.
+So all you need is Ruby itself, the Rubygems package manager and the ruby fusefs library.
+On Debian derivates you can achieve that using the following command:
+
+  apt-get install ruby rubygems libfusefs-ruby
+
+
+Installation
+------------
+
+As soon I released this as a gem, you will be able to install via Rubygems:
+
+  gem install quilt
+
+
+Problems
+--------
+
+On Ubuntu the fuse install lack adequate permission settings:
+
+  fusermount: failed to open /etc/fuse.conf: Permission denied
+
+
+The following line can be used to fix this:
+
+  chmod a+rwx /etc/fuse.conf

data/README.md

@@ -0,0 +1,33 @@
+Quilt
+=====
+
+Read and write CouchDB documents via FUSE userspace filesystem
+
+
+Install dependencies
+--------------------
+
+    apt-get install ruby rubygems libfusefs-ruby
+
+
+Install Quilt
+-------------
+
+    gem install couch-quilt
+
+
+Getting started
+---------------
+
+start quilt by typing
+
+    couchquilt mountpoint [server] [--debug]
+
+
+Your mapped CouchDB will now be available at *mountpoint*.
+
+You can create databases and documents with mkdir, add properties via echo >> and so on.
+Databases and documents can be deleted via a touch /database_id/_delete or /database_id/document_id/_delete.
+
+
+Read more on the [projectpage](http://jo.github.com/quilt/).

data/Rakefile

@@ -0,0 +1,39 @@
+require 'rake'
+require 'spec/rake/spectask'
+require 'rake/rdoctask'
+require File.join(File.dirname(__FILE__), 'lib', 'couchquilt', 'version')
+
+desc 'Default: run specs.'
+task :default => :spec
+
+desc "Run all examples"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_files = FileList['spec/*_spec.rb']
+  t.spec_opts = ["--color"]
+end
+
+desc "Run all examples with RCov"
+Spec::Rake::SpecTask.new(:coverage) do |t|
+  t.spec_files = FileList['spec/*_spec.rb']
+  t.rcov = true
+  t.rcov_opts = ['--exclude', '/var/lib/gems', '--exclude', "spec"]
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "couch-quilt"
+    s.version = Couchquilt::VERSION
+    s.summary = "Access CouchDB from filesystem."
+    s.email = "schmidt@netzmerk.com"
+    s.homepage = "http://jo.github.com/quilt"
+    s.description = "Access CouchDB JSON documents from filesystem."
+    s.authors = ['Johannes Jörg Schmidt']
+    s.rubyforge_project = "couch-quilt"
+    #s.files =  FileList["[A-Z]*(.rdoc)", "{bin,lib,spec}/**/*", "README.md", "INSTALL", "Rakefile"]
+  end
+
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install jeweler"
+end

data/bin/couchquilt

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+# Copyright 2010 Johannes J. Schmidt, TF
+# 
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+# 
+#        http://www.apache.org/licenses/LICENSE-2.0
+# 
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+#
+# usage:
+#  couchquilt ~/quilt http://localhost:5984
+
+QUILT_ROOT = File.expand_path(File.join(File.dirname(__FILE__), ".."))
+require File.join(QUILT_ROOT, "lib/couchquilt")
+
+DEBUG = ARGV.delete("--debug")
+require File.join(File.dirname(__FILE__), '../lib/couchquilt/debugged_fs') if DEBUG
+
+if ARGV[0].nil?
+  puts "usage:"
+  puts "couchquilt mountpoint [server] [--debug]"
+  exit
+end
+
+# database server url defaults to http://127.0.0.1:5984
+# couch fs will be mounted on ./app/127.0.0.1:5984 per default
+mountpoint = ARGV[0]
+server     = ARGV[1] || "http://127.0.0.1:5984"
+
+# create mount point if needed
+Dir.mkdir(mountpoint) unless File.directory?(mountpoint)
+
+# init quilt fs
+quilt_fs_class = DEBUG ? Couchquilt::DebuggedFS : Couchquilt::FS
+FuseFS.set_root quilt_fs_class.new(server)
+FuseFS.mount_under mountpoint
+
+# listen for exit signals and unmount fuse
+trap("INT") do
+  puts "ancelling..."
+  FuseFS.unmount
+  FuseFS.exit
+  puts "Bye."
+end
+
+# actually do the Fuse mount
+puts "Quilt maps #{server} to #{mountpoint}"
+puts "Debug mode" if DEBUG
+FuseFS.run

data/couch-quilt.gemspec

@@ -0,0 +1,56 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{couch-quilt}
+  s.version = "0.2.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Johannes J\303\266rg Schmidt"]
+  s.date = %q{2010-02-25}
+  s.default_executable = %q{couchquilt}
+  s.description = %q{Access CouchDB JSON documents from filesystem.}
+  s.email = %q{schmidt@netzmerk.com}
+  s.executables = ["couchquilt"]
+  s.extra_rdoc_files = [
+    "README.md"
+  ]
+  s.files = [
+    ".gitignore",
+     "INSTALL",
+     "README.md",
+     "Rakefile",
+     "bin/couchquilt",
+     "couch-quilt.gemspec",
+     "lib/couchquilt.rb",
+     "lib/couchquilt/couch_client.rb",
+     "lib/couchquilt/debugged_fs.rb",
+     "lib/couchquilt/fs.rb",
+     "lib/couchquilt/version.rb",
+     "spec/couchquilt_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://jo.github.com/quilt}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{couch-quilt}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Access CouchDB from filesystem.}
+  s.test_files = [
+    "spec/couchquilt_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/lib/couchquilt.rb

@@ -0,0 +1,37 @@
+# Copyright 2010 Johannes J. Schmidt, TF
+# 
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+# 
+#        http://www.apache.org/licenses/LICENSE-2.0
+# 
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+#
+# Quilt mixes CouchDB Design Documents into FUSE
+
+
+require "rubygems"
+begin
+    require 'json'
+rescue LoadError
+    raise "You need install and require your own json compatible library since Quilt couldn't load the json/json_pure gem" unless Kernel.const_defined?("JSON")
+end
+require "rest_client"
+require 'fusefs'
+
+$:.unshift File.dirname(__FILE__) unless
+  $:.include?(File.dirname(__FILE__)) ||
+    $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'couchquilt/couch_client'
+require 'couchquilt/fs'
+
+
+# Set out your Quilt
+module Couchquilt
+end

data/lib/couchquilt/couch_client.rb

@@ -0,0 +1,44 @@
+# speaking to CouchDB server
+module Couchquilt
+  class CouchClient
+    def initialize(server_name)
+      @server_name = server_name
+    end
+
+    # initiates a GET request and returns the JSON parsed response
+    def get(path)
+      response = RestClient.get(url_for(path))
+      JSON.parse(response) rescue response
+    rescue RestClient::ResourceNotFound
+      nil
+    end
+
+    # initiates a PUT request and returns true if it was successful
+    def put(path, payload = {})
+      RestClient.put url_for(path), payload.to_json
+      true
+    end
+
+    # initiates a DELETE request and returns true if it was successful
+    def delete(path)
+      RestClient.delete url_for(path)
+      true
+    rescue
+      false
+    end
+
+    # initiates a HEAD request to +url+ and returns true if the resource exists
+    def head(path)
+      RestClient.head url_for(path)
+      true
+    rescue RestClient::ResourceNotFound
+      false
+    end
+
+    private
+
+    def url_for(path)
+      File.join(@server_name, path)
+    end
+  end
+end

data/lib/couchquilt/debugged_fs.rb

@@ -0,0 +1,21 @@
+module Couchquilt
+  # proxy sends all requests to QuiltFS
+  # used for printing debug information
+  class DebuggedFS
+    def initialize(server_name)
+      @quilt = FS.new(server_name)
+    rescue => e
+      STDERR.puts e.message, e.backtrace
+    end
+
+    (FS.public_instance_methods - public_instance_methods).each do |method|
+      class_eval <<-STR
+        def #{method}(*args)
+          @quilt.#{method}(*args)
+        rescue => e
+          STDOUT.puts "#{method}", args.inspect, e.class, e.message, e.backtrace
+        end
+      STR
+    end
+  end
+end

data/lib/couchquilt/fs.rb

@@ -0,0 +1,414 @@
+require 'cgi'
+require 'uri'
+
+module Couchquilt
+  class FS
+    # initializes Quilt FS with the database server name
+    def initialize(server_name)
+      @couch = CouchClient.new(server_name)
+    end
+
+    # list contents of path
+    def contents(path)
+      database, id, *parts = extract_parts(path)
+  
+      list case named_path(path)
+           when :root
+             @couch.get("_all_dbs")
+           when :database
+             ["_design"] +
+               # database meta data
+               map_json(@couch.get(database)) +
+               # all documents but design documents
+               # Note: we can not use ?startkey="_design/"&endkey="_design0" here,
+               # because that would return no results for databases without design documents
+               @couch.get("#{database}/_all_docs")["rows"].map { |r| r["id"] }.select { |id| id !~ /^_design\// }
+           when :_design
+             query = URI.encode('startkey="_design"&endkey="_design0"')
+             # all design documents
+             @couch.get("#{database}/_all_docs?#{query}")["rows"].map { |r| r["id"].sub("_design/", "") }
+           when :_show
+             (@couch.get("#{database}/#{id}")["shows"] || {}).keys
+           when :_list
+             (@couch.get("#{database}/#{id}")["lists"] || {}).keys
+           when :_view
+             (@couch.get("#{database}/#{id}")["views"] || {}).keys
+           when :list_function
+             (@couch.get("#{database}/#{id}")["views"] || {}).keys.map { |name| "#{name}.html" }
+           when :show_function
+             query = URI.encode('startkey="_design0"')
+             @couch.get("#{database}/_all_docs?#{query}")["rows"].map { |r| "#{r["id"]}.html" }
+           when :view_function, :view_function_result
+             map_json(get_view_result_part(database, id, parts))
+           when :design_document
+             ["_list", "_show", "_view"] +
+               map_json(get_document_part(database, id))
+           else
+             map_json(get_document_part(database, id, parts))
+           end
+    end
+  
+    # is path a directory?
+    def directory?(path)
+      database, id, *parts = extract_parts(path)
+  
+      case named_path(path)
+      when :database, :document, :design_document
+        @couch.head(path)
+      when :view_function_result
+        doc = get_view_result_part(database, id, parts)
+        # arrays and hashes are mapped into directories
+        doc.is_a?(Hash) || doc.is_a?(Array)
+      when :database_info, :show_function_result, :list_function_result
+        false
+      when nil
+        # look into document
+        doc = get_document_part(database, id, parts)
+        # arrays and hashes are mapped into directories
+        doc.is_a?(Hash) || doc.is_a?(Array)
+      else
+        # all other special paths are directories by now
+        # TODO: thats not so good.
+        true
+      end
+    end
+  
+    # is path a file?
+    def file?(path)
+      database, id, *parts = extract_parts(path)
+  
+      case named_path(path)
+      when :database_info, :show_function_result, :list_function_result
+        true
+      when :view_function_result
+        # Every javascript or HTML is file, based on extension
+        [".js", ".html"].include?(File.extname(path))
+      when nil
+        # look into document
+        doc = get_document_part(database, id, parts)
+        # only arrays and hashes are mapped into directories
+        !doc.nil? && !(doc.is_a?(Hash) || doc.is_a?(Array))
+      else
+        false
+      end
+    end
+  
+    # reading file contents of path
+    def read_file(path)
+      database, id, *parts = extract_parts(path)
+  
+      content case named_path(path)
+              when :database_info
+                @couch.get(database)[remove_extname(id)]
+              when :show_function_result
+                parts.shift
+                @couch.get(remove_extname(File.join(database, id, "_show", *parts)))
+              when :list_function_result
+                parts.shift
+                @couch.get(remove_extname(File.join(database, id, "_list", *parts)))
+              when :view_function_result
+                get_view_result_part(database, id, parts)
+              else
+                get_document_part(database, id, parts)
+              end
+    end
+  
+    # is path writable?
+    # every javascript file is writable, except ones starting with an underscore
+    def can_write?(path)
+      database, id, *parts = extract_parts(path)
+  
+      case named_path(path)
+      when :switch_delete_database, :switch_delete_document
+        true
+      when :database_info, :show_function_result, :list_function_result, :view_function_result
+        false
+      else
+        File.basename(path) !~ /\A_/ && File.extname(path) == ".js"
+      end
+    end
+  
+    # writes content str to path
+    def write_to(path, str)
+      database, id, *parts = extract_parts(path)
+      # fetch document
+      doc = @couch.get("#{database}/#{id}")
+      # update the value that the file at path holds
+      update_value(doc, parts, str)
+      # save document
+      @couch.put("#{database}/#{id}", doc)
+    end
+  
+    # can I delete path?
+    def can_delete?(path)
+      return false if File.basename(path) =~ /\A_/
+  
+      case named_path(path)
+      when :database_info, :show_function_result, :list_function_result, :view_function_result
+        false
+      else
+        true
+      end
+    end
+  
+    # deletes path
+    # either deletes a database, document or removes a part of a document
+    def delete(path)
+      database, id, *parts = extract_parts(path)
+  
+      # fetch document
+      doc = @couch.get("#{database}/#{id}")
+      # remove object
+      remove_object(doc, parts)
+      # save document
+      @couch.put("#{database}/#{id}", doc)
+    end
+  
+    # can I make a directory at path?
+    def can_mkdir?(path)
+      database, id, *parts = extract_parts(path)
+  
+      case named_path(path)
+      when :root, :_design, :_list, :list_function, :_show, :show_function, :_view, :view_function, :view_function_result
+        false
+      when :database, :document, :design_document
+        # can create database or document unless exists
+        !@couch.head(path)
+      else
+        !get_document_part(database, id, parts)
+      end
+    end
+  
+    # makes a directory
+    # this creates either a database, a document or inserts an object into a document
+    def mkdir(path)
+      database, id, *parts = extract_parts(path)
+  
+      case named_path(path)
+      when :database
+        @couch.put(database)
+      when :document, :design_document
+        @couch.put("#{database}/#{id}")
+      else
+        # fetch document
+        doc = @couch.get("#{database}/#{id}")
+        # insert empty object
+        update_value(doc, parts, {})
+        # save document
+        @couch.put("#{database}/#{id}", doc)
+      end
+    end
+  
+    # can I remove a directory at path?
+    def can_rmdir?(path)
+      database, id, *parts = extract_parts(path)
+  
+      case named_path(path)
+      when :root, :_design, :_list, :list_function, :_show, :show_function, :_view, :view_function, :view_function_result, :database, :document, :design_document
+        false
+      else
+        get_document_part(database, id, parts).empty? rescue nil
+      end
+    end
+  
+    # deletes a directory
+    # that is a part of a document
+    def rmdir(path)
+      database, id, *parts = extract_parts(path)
+  
+      # fetch document
+      doc = @couch.get("#{database}/#{id}")
+      # remove object
+      update_value(doc, parts, nil)
+      # save document
+      @couch.put("#{database}/#{id}", doc)
+    end
+  
+    # switch to delete a database or document
+    def touch(path)
+      database, id, *parts = extract_parts(path)
+  
+      case named_path(path)
+      when :switch_delete_database
+        @couch.delete(database)
+      when :switch_delete_document
+        doc = @couch.get("#{database}/#{id}")
+        @couch.delete("#{database}/#{id}?rev=#{doc["_rev"]}")
+      end
+    end
+  
+    private
+  
+    # gets the database, id and parts from path
+    def extract_parts(path)
+      database, id, *parts = path.scan(/[^\/]+/)
+      if id == "_design" && !parts.empty?
+        id << "/#{parts.shift}"
+      end
+      [database, id] + parts
+    end
+  
+    # returns a path identifier for special paths
+    def named_path(path)
+      database, id, *parts = extract_parts(path)
+  
+      if database.nil?
+        # /
+        :root
+      elsif id == "_delete"
+        :switch_delete_database
+      elsif parts.size == 1 && parts.first == "_delete"
+        :switch_delete_document
+      elsif id.nil?
+        # /database_id
+        :database
+      elsif ["compact_running.b.js", "db_name.js", "disk_format_version.i.js", "disk_size.i.js", "doc_count.i.js", "doc_del_count.i.js", "instance_start_time.js", "purge_seq.i.js", "update_seq.i.js"].include?(id) && parts.empty?
+        :database_info
+      elsif id == "_design" && parts.empty?
+        # /database_id/_design
+        :_design
+      elsif id =~ /_design\// && parts.empty?
+        # /database_id/_design/design_document_id
+        :design_document
+      elsif id =~ /_design\// && parts == ["_show"]
+        # /database_id/_design/design_document_id/_show
+        :_show
+      elsif id =~ /_design\// && parts == ["_list"]
+        # /database_id/_design/design_document_id/_list
+        :_list
+      elsif id =~ /_design\// && parts == ["_view"]
+        # /database_id/_design/design_document_id/_view
+        :_view
+      elsif id =~ /_design\// && parts.size == 2 && parts.first == "_list"
+        # /database_id/_design/design_document_id/_list/list_function_name
+        :list_function
+      elsif id =~ /_design\// && parts.size == 3 && parts.first == "_list"
+        # /database_id/_design/design_document_id/_list/list_function_name/view_function_name
+        :list_function_result
+      elsif id =~ /_design\// && parts.size == 2 && parts.first == "_show"
+        # /database_id/_design/design_document_id/_show/show_function_name
+        :show_function
+      elsif id =~ /_design\// && parts.size == 3 && parts.first == "_show"
+        # /database_id/_design/design_document_id/_show/show_function_name/document_id
+        :show_function_result
+      elsif id =~ /_design\// && parts.size == 2 && parts.first == "_view"
+        # /database_id/_design/design_document_id/_view/view_function_name
+        :view_function
+      elsif id =~ /_design\// && parts.size >= 3 && parts.first == "_view"
+        # /database_id/_design/design_document_id/_view/view_function_name/document_id
+        :view_function_result
+      elsif parts.empty?
+        # /database_id/document_id
+        :document
+      else
+        # /database_id/document_id/object
+        # /database_id/_design/design_document_id
+        # /database_id/_design/design_document_id/object
+        nil
+      end
+    end
+  
+    # maps json contents into contents array
+    def map_json(doc)
+      case doc
+      when Hash
+        # Hash is mapped to directory
+        doc.keys.sort.map { |k| append_extname(k, doc[k]) }
+      when Array
+        # Array is mapped to directory
+        doc.map { |k| append_extname(doc.index(k), k) }
+      end
+    end
+  
+    # fetch part of document
+    def get_document_part(database, id, parts = [])
+      doc = @couch.get("#{database}/#{id}")
+      get_part(doc, parts)
+    end
+  
+    # get view result, or a part of that document.
+    def get_view_result_part(database, id, parts = [])
+      a, view_function_name, *rest = parts
+      view = [id.sub("_design/", ""), "_view", view_function_name].join("/")
+      doc = @couch.get("#{database}/_design/#{view}")
+      get_part(doc, rest)
+    end
+  
+    # get a part of the document
+    # eg: get_part({ :a => { :b => :c}}, [:a, :b]) #=> :c
+    # also removes the file extension and gets index of arrays
+    def get_part(doc, parts)
+      return if doc.nil?
+      doc = doc.dup
+      parts.each do |part|
+        case doc
+        when Hash
+          doc = doc[remove_extname(part)]
+        when Array
+          doc = doc[part.to_i]
+        end
+      end
+      doc
+    end
+  
+    # updates a part of a hash
+    # Example:
+    #  update_value({:a => { :b => 'c'}}, [:a, :b], 'cis') #=> {:a => { :b => 'cis'}}
+    def update_value(hash, keys, value)
+      key = remove_extname(keys.shift)
+      if keys.empty?
+        hash[key] = value
+      else
+        hash[key] = update_value(hash[key], keys, value)
+      end
+      hash
+    end
+  
+    # removes an object from a hash
+    # Example:
+    #  remove_object({:a => { :b => 'c'}}, [:a, :b]) #=> {:a => { }}
+    def remove_object(hash, keys)
+      key = remove_extname(keys.shift)
+      if keys.empty?
+        hash.delete(key)
+      else
+        hash[key] = remove_object(hash[key], keys)
+      end
+      hash
+    end
+  
+    # remove extname to get the id
+    def remove_extname(filename)
+      filename.sub(/((\.(f|i|b))?\.js|\.html)\z/, "")
+    end
+  
+    # Appends extname, that is: builds a filename from key and value.
+    # Note: values are casted by extension.
+    def append_extname(key, value)
+      basename = key.is_a?(Integer) ? "%.3d" % key : key
+  
+      case value
+      when Float
+        "#{basename}.f.js"
+      when Integer
+        "#{basename}.i.js"
+      when nil, String
+        "#{basename}.js"
+      when true, false
+        "#{basename}.b.js"
+      else
+        basename
+      end
+    end
+
+    # escapes the value for using as filename
+    def list(array)
+      return [] if array.nil?
+      array.compact.map { |v| CGI.escape(v) }.sort
+    end
+
+    def content(value)
+      value.to_s
+    end
+  end
+end