localwiki_client 0.1.0 → 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 57676e3cee0822abe0c07ab173531579f1cccb21
+  data.tar.gz: c7b7b0370f9372cca7b2149e0374737a04fca115
+SHA512:
+  metadata.gz: 9a420a1750d4d72858603feff2eeb7656e27649526b5138eeffb8d933fc685e5de239515df86f2cbaed82e46c1b760c0d28b18122d1816f27d34f1218fcc0a9c
+  data.tar.gz: 254a56caf270b691b689ea326f8d3000ebe211aedfece5b411646f9609997ccc06c9caefe0b03d1ecbe80c322cdac7a17b1f189c16288c918138fadc4d407bd9

data/.gitignore

@@ -1,2 +1,4 @@
+.yardoc
+doc/
 .idea
 Gemfile.lock

data/.travis.yml

@@ -1,5 +1,6 @@
 language: ruby
 rvm:
   - 1.9.3
+  - 2.0.0
   - jruby-19mode # JRuby in 1.9 mode
-  - rbx-19mode
+  - rbx-19mode

data/History.txt

@@ -1,3 +1,14 @@
+=== 0.2.0 / 2013-03-16
+
+* Implemented CRUD methods
+* Implemented #fetch_version
+* Switched to VCR test library
+
+=== 0.1.0 / 2013-02-23
+
+* Switched to Faraday
+* Reorganized code
+
 === 0.0.4 / 2013-01-05
 
 * Fixed gem homepage

data/README.md

@@ -20,14 +20,34 @@ Usage
 ## Example
 
     require 'localwiki_client'
+
+    # read access
     wiki = LocalwikiClient.new 'seattlewiki.net'
     wiki.site_name
     => SeattleWiki
     wiki.count('user')
     => 47
 
+    # write access
+    wiki = LocalwikiClient.new 'seattlewiki.net', 'myusername', 'myapikey'
+    page_json = {name: 'Current Events', content: 'Coming Soon!'}.to_json
+    response = wiki.create('page', page_json)
+    response.status
+    => 201
+
+Features / Problems
+-------------------
+
+* #create, #read (#fetch), #update, #delete provide basic CRUD functionality
+* #list fetches all (or with a limit) of a specific type of resource
+* #fetch_version retrieves version history for a resource
+* a few helper methods exist, more to come
+    * #count, #page_by_name, #unique_authors
+
+
 Compatibility
 -------------
+ * 2.0.0
  * 1.9.3
  * jruby-19mode
  * rbx-19mode
@@ -36,8 +56,21 @@ Contributing
 ------------
 
 To get your improvements included, please fork and submit a pull request.
+
 Bugs and/or failing tests are very appreciated.
 
+Contributors
+------------
+Seth Vincent
+
+Brandon Faloona
+
+Helen Canzler
+
+Jerry Frost
+
+Matt Adkins
+
 LICENSE
 -------
 

data/Rakefile

@@ -1,6 +1,7 @@
 require 'rake'
 require 'rspec/core'
 require 'rspec/core/rake_task'
+require 'yard'
 
 desc 'Default: run unit test specs'
 task :default => :spec
@@ -19,7 +20,7 @@ task :test => [:spec]
 
 desc "Run integration tests"
 RSpec::Core::RakeTask.new(:integration) do |t|
-  t.pattern = "spec/integration/*_spec.rb"
+  t.pattern = "integration/*_spec.rb"
   t.rspec_opts = ['-f d']
 end
 
@@ -31,4 +32,20 @@ end
 desc "Detailed Flog report! (*nix only)"
 task :flog_detail do
   system('find lib -name \*.rb | xargs flog -d')
-end
+end
+
+desc "Generate YARD documentation for files in ['lib/**/*.rb']"
+YARD::Rake::YardocTask.new(:yard)
+
+desc "Delete VCR fixtures and logs"
+task :vcr_purge do
+  files = Dir[File.expand_path("../spec/fixtures/cassettes/*", __FILE__)].map do |file|
+    file if File.file?(file)
+  end
+  files.each { |file| File.delete(file) }
+end
+
+desc "Sanitize VCR fixtures (remove Apikey values)"
+task :vcr_sanitize do
+  system(%{ruby -pi -e "gsub(/- ApiKey .+:.+/, '- ApiKey testuser:key')" spec/fixtures/cassettes/*.yml})
+end

data/integration/helper.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+require 'localwiki_client'
+
+def test_env_vars_set?
+  return true if ENV['localwiki_client_user'] && ENV['localwiki_client_apikey']
+  puts "\nTo add or modify tests in the spec folder you need to do two things:"
+  puts "\tContact sethvincent@gmail.com to request a username and apikey on the test server."
+  puts "\tSet these two environment variables:\n\t\texport localwiki_client_user=USERNAME\n\t\texport localwiki_client_apikey=APIKEY"
+end

data/{spec/integration → integration}/live_saltlake_wiki_spec.rb

@@ -1,5 +1,4 @@
-$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
-require 'localwiki_client'
+require File.expand_path("../helper", __FILE__)
 
 describe 'LIVE saltlakewiki.org' do
 
@@ -18,3 +17,4 @@ describe 'LIVE saltlakewiki.org' do
   end
 
 end
+

data/integration/live_test_wiki_spec.rb

@@ -0,0 +1,47 @@
+require File.expand_path("../helper", __FILE__)
+
+if test_env_vars_set?
+
+  describe 'LIVE testwiki instance' do
+
+    before(:all) {
+      @wiki = Localwiki::Client.new 'ec2-54-234-151-52.compute-1.amazonaws.com',
+                                    ENV['localwiki_client_user'],
+                                    ENV['localwiki_client_apikey']
+      }
+
+    context "CRUD methods" do
+
+      before(:all) do
+        require 'securerandom'
+        @pagename = "TestPage#{SecureRandom.uuid}"
+      end
+
+      it "#create('page', json) response.status is 201" do
+        json = {name: @pagename, content: '<p>Created!</p>'}.to_json
+        response = @wiki.create('page', json)
+        response.status.should eq 201
+      end
+
+      it "#read('page', 'TestPage<uuid>') response.status is 200" do
+        response = @wiki.read('page', @pagename)
+        response["content"].should match(/Created!/)
+      end
+
+      it "#update('page', 'TestPage<uuid>', json) response.status is 204" do
+        json = {content: '<p>Updated!</p>'}.to_json
+        response = @wiki.update('page', @pagename, json)
+        response.status.should eq 204
+        @wiki.read('page', @pagename)["content"].should match(/Updated!/)
+      end
+
+      it "#delete('page', 'TestPage<uuid>') response.status is 204" do
+        response = @wiki.delete('page', @pagename)
+        response.status.should eq 204
+        @wiki.read('page', @pagename).status.should eq 404
+      end
+
+    end
+
+  end
+end

data/lib/localwiki/client.rb

@@ -1,5 +1,5 @@
 require 'faraday'
-require 'json/pure'
+require 'json'
 
 module Localwiki
 
@@ -8,41 +8,54 @@ module Localwiki
   #
   class Client
 
-    attr_accessor :hostname       # hostname of the server we'd like to point at
-    attr_reader   :site_name      # site resource - display name of wiki
-    attr_reader   :time_zone      # site resource - time zone of server, e.g. 'America/Chicago'
-    attr_reader   :language_code  # site resource - language code of the server, e.g. 'en-us'
+    # hostname of the server we'd like to point at
+    attr_accessor :hostname
+    
+    # site resource - display name of wiki
+    attr_reader   :site_name
+    
+    # site resource - time zone of server, example: 'America/Chicago'
+    attr_reader   :time_zone      
+    
+    # site resource - language code of the server, example: 'en-us'
+    attr_reader   :language_code  
 
     ##
     # Create a LocalWikiClient instance
     #
-    #   LocalwikiClient.new 'seattlewiki.net'
+    # @example LocalwikiClient.new 'seattlewiki.net'
     #
-    def initialize hostname
+    def initialize hostname, user=nil, apikey=nil
       @hostname = hostname
+      @user = user
+      @apikey = apikey
       create_connection
       collect_site_details
     end
 
     ##
     # Request total count of given resource
-    #
+    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
+    # @return [Fixnum] resource count
+    # @example wiki.count('user')
     def count(resource)
       list(resource.to_s,1)["meta"]["total_count"]
     end
 
     ##
     # fetch a page by name ("The Page Name" or "The_Page_Name" or "the page name")
-    #
+    # @param name "The Page Name" or "The_Page_Name" or "the page name"
+    # @return [Hash] the parsed JSON object from the response body, otherwise the whole http response object
     def page_by_name(name)
       fetch(:page,"#{name.gsub!(/\s/, '_')}")
     end
 
     ##
     # list of a specific type of resource
-    # resource are "site", "page", "user", "file", "map", "tag", "page_tag"
-    # limit is an integer
-    # params is a hash of query string params
+    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
+    # @param limit is an integer
+    # @param params is a hash of query string params
+    # @return [Hash] the parsed JSON object from the response body, otherwise the whole http response object
     def list(resource,limit=0,params={})
       uri = '/api/' + resource.to_s
       params.merge!({limit: limit.to_s})
@@ -51,42 +64,79 @@ module Localwiki
 
     ##
     # fetch a specific resource
-    # resources are "site", "page", "user", "file", "map", "tag", "page_tag"
-    # identifier is id, pagename, slug, etc.
-    # params is a hash of query string params
+    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
+    # @param identifier is id, pagename, slug, etc.
+    # @param params is a hash of query string params
+    # @example wiki.update('page', '<page tag>')
+    # @return [Hash] the parsed JSON object from the response body, otherwise the whole http response object
     def fetch(resource,identifier,params={})
-      uri = '/api/' + resource.to_s + '/' + identifier
+      uri = '/api/' + resource.to_s + '/' + slugify(identifier)
+      http_get(uri,params)
+    end
+    alias_method :read, :fetch
+
+    ##
+    # fetch version information for a resource
+    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
+    # @param identifier is id, pagename, slug, etc.
+    # @param params is a hash of query string params
+    # @example wiki.fetch_version('page', 'First Page')
+    # @return [Hash] the parsed JSON object from the response body, otherwise the whole http response object
+    def fetch_version(resource,identifier,params={})
+      uri = '/api/' + resource.to_s + '_version?name=' + identifier
       http_get(uri,params)
     end
 
+    ##
+    # number of unique authors that have modified a resource
+    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
+    # @param identifier is id, pagename, slug, etc.
+    # @param params is a hash of query string params
+    # @example wiki.unique_authors('page', 'First Page')
+    # @return [Fixnum]
+    def unique_authors(resource,identifier,params={})
+      json = fetch_version(resource,identifier,params)
+      json['objects'].map {|entry| entry['history_user']}.uniq.length
+    end
+
     ##
     # create a specific resource
-    # resources are "site", "page", "user", "file", "map", "tag", "page_tag"
-    def create(resource,identifier,json)
-      raise 'Not Yet Implemented'
+    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
+    # @param json is a json object
+    # @example wiki.create('page', <json object containing the page tag>)
+    # @return [HTTPResponse] the http response object
+    def create(resource, json)
+      uri = '/api/' + resource.to_s + '/'
+      http_post(uri, json)
     end
 
     ##
     # update a specific resource
-    # resources are "site", "page", "user", "file", "map", "tag", "page_tag"
-    # identifier is id, pagename, slug, etc.
+    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
+    # @param identifier is id, pagename, slug, etc.
+    # @param json is a json object
+    # @example wiki.update('page', '<page tag>', <json object>)
+    # @return [HTTPResponse] the http response object
     def update(resource,identifier,json)
-      raise 'Not Yet Implemented'
+      uri = '/api/' + resource.to_s + '/' + slugify(identifier)
+      http_put(uri, json)  
     end
 
     ##
     # delete a specific resource
-    # resources are "site", "page", "user", "file", "map", "tag", "page_tag"
-    # identifier is id, pagename, slug, etc.
+    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
+    # @param identifier is id, pagename, slug, etc.
+    # @example wiki.delete('page', '<page tag>')
+    # @return [HTTPResponse] the http response object
     def delete(resource,identifier)
-      raise 'Not Yet Implemented'
+      uri = '/api/' + resource.to_s + '/' + slugify(identifier)
+      http_delete(uri)
     end
 
     private
 
     ##
     # Get site resource and set instance variables
-    #
     def collect_site_details
       site = fetch('site','1')
       @site_name = site['name']
@@ -96,32 +146,75 @@ module Localwiki
 
     ##
     # create Faraday::Connection instance and set @site
-    #
     def create_connection
       @site = Faraday.new :url => @hostname
     end
-
+  
     ##
     # http get request
-    # url is formatted as http://[@hostname]/[thing(s)-you-want]?[params]
-    #
+    # @param uri /api/<resource>/<resource identifier>
+    # @param params is a hash of query string params
+    # @return [Hash] the parsed JSON object, otherwise the  http response object
     def http_get(uri,params={})
       params.merge!({format: 'json'})
       full_url = 'http://' + @hostname + uri.to_s
       response = @site.get full_url, params
-      JSON.parse(response.body)
+      JSON.parse(response.body) rescue response
     end
-
-    def http_post()
-      raise 'Not Yet Implemented'
+    
+    ##
+    # http post request
+    # @param uri /api/<resource>/
+    # @param json is a json object
+    # @return [HTTPResponse] the http response object
+    def http_post(uri, json)
+      full_url = 'http://' + @hostname + uri.to_s
+      
+      @site.post do |req|
+        req.url full_url
+        req.headers['Content-Type'] = 'application/json'
+        req.headers['Authorization'] = "ApiKey #{@user}:#{@apikey}"
+        req.body = json
+      end
+    end
+    
+    ##
+    # http put request
+    # @param uri /api/<resource>/<resource identifier>
+    # @param json is a json object
+    # @return [HTTPResponse] the http response object
+    def http_put(uri, json)
+      full_url = 'http://' + @hostname + uri.to_s
+      
+      @site.put do |req|
+        req.url full_url
+        req.headers['Content-Type'] = 'application/json'
+        req.headers['Authorization'] = "ApiKey #{@user}:#{@apikey}"
+        req.body = json
+      end
     end
 
-    def http_put()
-      raise 'Not Yet Implemented'
+    ##
+    # http delete request
+    # @param uri /api/<resource>/<resource identifier>
+    # @return [HTTPResponse] the http response object
+    def http_delete(uri)
+      full_url = 'http://' + @hostname + uri.to_s
+
+      @site.delete do |req|
+        req.url full_url
+        req.headers['Content-Type'] = 'application/json'
+        req.headers['Authorization'] = "ApiKey #{@user}:#{@apikey}"
+      end
     end
 
-    def http_delete()
-      raise 'Not Yet Implemented'
+    ##
+    # create human readable identifier that is used to create clean urls
+    # @param string
+    # @example slugify('My Page') == 'My_Page'
+    # @return [String]
+    def slugify(string)
+      string.to_s.strip.gsub(' ', "_")
     end
 
   end

data/lib/localwiki/version.rb

@@ -1,5 +1,5 @@
 module Localwiki
 
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 
 end

data/localwiki_client.gemspec

@@ -14,11 +14,15 @@ Gem::Specification.new do |s|
   s.required_ruby_version = '>= 1.9.2'
 
   s.add_dependency('faraday')
-  s.add_dependency('json')
+  s.add_dependency('json_pure')
 
   s.add_development_dependency('rake')
   s.add_development_dependency('rspec', '>= 2.9.0')
-  s.add_development_dependency('rspec-mocks', '>= 2.9.0')
+  s.add_development_dependency('vcr')
+  s.add_development_dependency('webmock', '>= 1.8.0', '< 1.10')
+  s.add_development_dependency('yard')
+  s.add_development_dependency('kramdown')
+
   s.add_development_dependency('rb-fsevent')
 
   unless ENV['TRAVIS'] == 'true'

data/spec/basic_crud_spec.rb

@@ -0,0 +1,67 @@
+require File.expand_path("../helper", __FILE__)
+
+describe 'LocalwikiClient' do
+
+  before(:all) do
+    VCR.insert_cassette 'basic_crud', :record => :new_episodes
+    @wiki = Localwiki::Client.new 'ec2-54-234-151-52.compute-1.amazonaws.com',
+                                  ENV['localwiki_client_user'],
+                                  ENV['localwiki_client_apikey']
+    require 'securerandom'
+    @pagename = "TestPage#{SecureRandom.uuid}"
+    @path_matcher = lambda do |request_1, request_2|
+      URI(request_1.uri).path.match(/TestPage/) && URI(request_2.uri).path.match(/TestPage/)
+    end
+  end
+
+  after(:all) do
+    VCR.eject_cassette
+  end
+
+  context "CRUD method" do
+
+    it "#create('page', json) response.status is 201" do
+      response = @wiki.create('page', {name: @pagename, content: '<p>Created!</p>'}.to_json)
+      response.status.should eq 201
+    end
+
+    it "#read('page', pagename) response.status should match(/Created!/)" do
+      VCR.use_cassette 'basic_crud_read_success', :match_requests_on => [:method, @path_matcher] do
+        response = @wiki.read('page', @pagename)
+        response["content"].should match(/Created!/)
+      end
+    end
+
+    it "#update('page', pagename, json) response.status is 204" do
+      VCR.use_cassette 'basic_crud_update_success', :match_requests_on => [:method, @path_matcher] do
+        response = @wiki.update('page', @pagename, {content: '<foo>'}.to_json)
+        response.status.should eq 204
+      end
+    end
+
+    it "#delete('page', pagename) response.status is 204" do
+      VCR.use_cassette 'basic_crud_delete_success', :match_requests_on => [:method, @path_matcher] do
+        response = @wiki.delete('page', @pagename)
+        response.status.should eq 204
+      end
+    end
+
+    context "when page does not exist" do
+
+      it "#read returns response.status of 404" do
+        VCR.use_cassette 'basic_crud_read_fail', :match_requests_on => [:method, @path_matcher] do
+          response = @wiki.read('page', @pagename)
+          response.status.should eq 404
+        end
+      end
+
+      it "#delete returns response.status of 404" do
+        VCR.use_cassette 'basic_crud_delete_fail', :match_requests_on => [:method, @path_matcher] do
+          response = @wiki.delete('page', @pagename)
+          response.status.should eq 404
+        end
+      end
+
+    end
+  end
+end

data/spec/basic_spec.rb

@@ -0,0 +1,34 @@
+require File.expand_path("../helper", __FILE__)
+
+describe 'LocalwikiClient' do
+
+  context "#create and #page_by_name" do
+
+    before(:all) do
+      VCR.insert_cassette 'basic', :record => :new_episodes
+      @wiki = Localwiki::Client.new 'ec2-54-234-151-52.compute-1.amazonaws.com',
+                                    ENV['localwiki_client_user'],
+                                    ENV['localwiki_client_apikey']
+    end
+
+    after(:all) do
+      VCR.eject_cassette
+    end
+
+    it "handle spaces" do
+      require 'securerandom'
+      base_name = "Test Page"
+      page_name = "#{base_name}#{SecureRandom.uuid}"
+      path_matcher = lambda do |request_1, request_2|
+        URI(request_1.uri).path.match(/Test/) && URI(request_2.uri).path.match(/Test/)
+      end
+      @wiki.create('page', {name: page_name, content: '<p>Created page with spaces!</p>'}.to_json)
+      VCR.use_cassette 'basic_page_by_name_spaces', :match_requests_on => [:method, path_matcher] do
+        response = @wiki.page_by_name(page_name)
+        response["content"].should match(/Created page with spaces!/)
+      end
+    end
+
+  end
+
+end

data/spec/fetch_version_spec.rb

@@ -0,0 +1,43 @@
+require File.expand_path("../helper", __FILE__)
+
+describe 'LocalwikiClient' do
+
+  before(:all) do
+    VCR.insert_cassette 'fetch', :record => :new_episodes
+    @wiki = Localwiki::Client.new 'ec2-54-234-151-52.compute-1.amazonaws.com',
+                                  ENV['localwiki_client_user'],
+                                  ENV['localwiki_client_apikey']
+    require 'securerandom'
+  end
+
+  after(:all) do
+    VCR.eject_cassette
+  end
+
+  context "#fetch_version" do
+
+    it "returns json that includes all edits" do
+      pagename = "TestPage#{SecureRandom.uuid}"
+      VCR.use_cassette 'basic_fetch_version_success', :match_requests_on => [:method] do
+        @wiki.create('page', {name: pagename, content: '<p>Created!</p>'}.to_json)
+        @wiki.update('page', pagename, {content: '<p>foo</p>'}.to_json)
+        response = @wiki.fetch_version('page', pagename)
+        response['meta']['total_count'].should eq 2
+      end
+    end
+  end
+
+  context "#unique_authors" do
+
+    it "returns the number of authors" do
+      pagename = "TestPage#{SecureRandom.uuid}"
+      VCR.use_cassette 'basic_unique_authors_success', :match_requests_on => [:method] do
+        @wiki.create('page', {name: pagename, content: '<p>Created!</p>'}.to_json)
+        @wiki.update('page', pagename, {content: '<p>foo</p>'}.to_json)
+        @wiki.unique_authors('page', pagename).should eq 1
+      end
+    end
+
+  end
+end
+