joggle 0.1.0

data/COPYING

@@ -0,0 +1,20 @@
+Copyright (C) 2009 Paul Duncan <pabs@pablotron.org>
+ 
+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 of the Software, its documentation and marketing & publicity 
+materials, and acknowledgment shall be given in the documentation, materials
+and software packages that this Software was used.
+   
+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 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

@@ -0,0 +1,212 @@
+Joggle 0.1.0 README
+===================
+
+Please see the file COPYING for licensing and warranty information.  The
+latest version of this software is available at the following URL:
+
+    http://pablotron.org/software/joggle/
+
+Table of Contents
+=================
+  1.  Overview
+  2.  System Requirements
+  3.  Installation
+  4.  Configuration
+  5.  Using Joggle
+  6.  Advanced Configuration
+  7.  Security Considerations
+  8.  Reporting Bugs
+  9.  About the Author
+    
+1. Overview
+===========
+Joggle is an Twitter to XMPP relay.  Jabber messages are sent as tweets,
+and tweets are sent as instant messages.  
+
+Installation and configuration is easy and, if you'd like, you can share
+your Joggle installation with more than one person.
+
+2. System Requirements
+======================
+Here's what you'll need to get started using Joggle:
+
+  * Ruby 1.8 (a recent version, preferrably including RubyGems)
+  * JSON (gem install json)
+  * XMPP4r (gem install xmpp4r)
+
+You'll also need a spare Jabber account to relay messages.  If you don't
+have your own Jabber server, you can create a free one through
+jabber.org or gmail.com.
+
+3. Installation
+===============
+The easiest way to install Joggle is via RubyGems:
+
+    sudo gem install joggle
+
+If you don't use RubyGems, you can also install Joggle using setup.rb,
+like this:
+
+    sudo ruby ./setup.rb
+
+Note: If you're using Debian or a Debian-based distribution (e.g.
+Ubuntu), then you'll want to use the RubyGems version of XMPP4r -- the
+Debian version is horribly out of date, and may not work with Joggle.
+
+4. Configuration
+================
+The simplest way to get Joggle up and running is like so:
+
+    # create ~/.joggle and make sure it's only readable by you
+    mkdir ~/.joggle && chmod 700 ~/.joggle
+
+    # add username and password to config
+    cp doc/joggle.cfg.sample ~/.joggle/joggle.cfg
+
+    # edit ~/.joggle/joggle.cfg and add your jabber username and
+    # password!
+    vim ~/.joggle/joggle.cfg
+
+    # run joggle
+    joggle --config ~/.joggle/joggle.cfg
+
+Want to run Joggle via Cron?  Here's how:
+
+    # run joggle every time the system is restarted
+    @reboot joggle --daemon --config  ~/.joggle/joggle.cfg
+
+Note: Although you can specify the JID and password via the command-line
+or the environment, doing so is not recommended on a shared system; see
+the "Security Considerations" section below for additional information.
+
+5. Using Joggle
+===============
+In order to use Joggle you'll need to bind your Jabber account to your
+twitter account.  Here's how:
+
+ 1. Add the Joggle Jabber ID to your IM client.  Joggle will
+    automatically accept any subscription.
+
+ 2. Register your Twitter account with Joggle by sending a 
+    message to Joggle in the following form:
+
+    ".register TWITTER_USER TWITTER_PASS"
+
+    (replace TWITTER_USER and TWITTER_PASS with your Twitter username
+    and password, respectively)
+
+Note that more than one person can use the Joggle Jabber relay.  Each
+person just needs to follow the steps above to bind their Jabber and
+Twitter accounts (this feature can be disabled; see the "Advanced
+Configuration" section below).  At the moment you can only register one
+Twitter account per person, although this may change in the future.
+
+If you change your mind and decide not to use Joggle any more, you can
+tell it to forget your Twitter account information by sending a message
+like this:
+
+    ".unregister"
+
+There are several other commands available via message as well; use the
+".help" command for a complete list.
+
+6. Advanced Configuration
+=========================
+By default, Joggle will automatically approve any Jabber subscription
+request it receives.  This means that if Joggle is relaying via an
+account on a public Jabber server, then anyone can use your Joggle
+installation to relay to Twitter.
+
+To limit your Joggle installation to a specific set of Jabber IDs,
+use the --allow command-line option, like so:
+
+    # limit joggle access to specific users
+    joggle --allow alice@example.com --allow bob@example.com
+
+Or you can use the 'engine.allow' directive in the configuration file:
+
+    # limit access to alice@example.com and bob@example.com
+    engine.allow alice@example.com
+    engine.allow bob@example.com
+
+You can also configure the Joggle update frequency.  Here's what the
+configuration looks like by default:
+
+    # from 8am until 3pm, update every 10 minutes
+    engine.update.range    8-15       10
+
+    # from 3pm until 10pm, update every 5 minutes
+    engine.update.range    15-22      10
+
+    # from 10pm until midnight, update every 10 minutes
+    engine.update.range    22-24      10 
+
+    # from midnight until 2am, update every 20 minutes
+    engine.update.range    0-2        20 
+
+    # for unspecified times (e.g. 2am - 8am), update every 60 minutes
+    engine.update.default             60
+
+Note that the _minimum_ update frequency is 5 minutes; Joggle will
+ignore anything less than that.  Also note that HTTP caching and a
+number of other checks are performed prior to contacting Twitter, so
+the specified update frequency will probably not translate precisely
+into the actual update frequency.
+
+There are several other command-line options, environment varialbes, and
+configuration file directives.  These will be documented on the Joggle
+web site (http://pablotron.org/software/joggle/) when time permits.
+
+7. Security Considerations
+==========================
+Since Joggle is saves your Twitter username and password, an unsavory
+system administrator or malicious user could obtain both by sifting
+through the Joggle storage or log files.
+
+By default, Joggle does its best to protect against malicious users by
+creating the storage and log files in a directory that only accessible
+by the owner (chmod 700).  
+
+The implications here are as follows:
+
+  * Don't use a Joggle relay run by someone you don't trust.
+
+  * Don't run a Joggle relay on a system that isn't secure.
+
+  * Don't change the path for the configuration, storage, or log files, 
+    without properly securing the new location (e.g. chmod 700).
+
+  * Don't specify the username and password via the command-line on a
+    shared system, since the command-line arguments can be viewed by
+    other users (e.g. "ps axu")
+
+You should also be wary of your Jabber providers; many Jabber servers of
+them do not configure Jabber with TLS or SASL enabled, which means that
+both your Jabber and Twitter credentials are sent over the wire as plain
+text.
+
+Joggle connects to Twitter via SSL.  If you're having problems with SSL,
+you can disable this feature by adding the following directives to your
+config file:
+
+  # use http instead of https for Twitter updates
+  # (do not do this unless you have to)
+  twitter.fetcher.url.timeline  http://twitter.com/statuses/friends_timeline.json
+  twitter.fetcher.url.tweet     http://twitter.com/statuses/update.json
+
+Note that doing this is NOT RECOMMENDED; your Twitter username and
+password will be sent over the wire as plain text.
+
+8. Reporting Bugs
+=================
+To report a bug or request a feature, visit the Joggle Redmine
+repository at the following URL:
+
+    http://redmine.pablotron.org/projects/show/joggle
+
+You can also contact me directly via email using the address below.
+
+9. About the Author
+===================
+Paul Duncan <pabs@pablotron.org>
+http://pablotron.org/

data/Rakefile

@@ -0,0 +1,120 @@
+
+# load libraries
+
+require 'rake/rdoctask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'lib/joggle/version.rb' 
+
+def package_info
+  require 'ostruct'
+  require 'rubygems'
+
+  # create package
+  ret = OpenStruct.new
+
+  # set package information
+  ret.name          = 'Joggle'
+  ret.blurb         = 'Jabber/Twitter relay, written in Ruby.'
+  ret.version       = Joggle::VERSION
+  ret.platform      = Gem::Platform::RUBY
+  ret.url           = 'http://pablotron.org/software/joggle/'
+
+  # author information
+  ret.author_name   = 'Paul Duncan'
+  ret.author_email  = 'pabs@pablotron.org'
+
+  # requirements and files
+  ret.reqs          = ['none']
+  ret.include_files = Dir['**/*'].delete_if { |path| 
+    %w{CVS .svn .hg}.any? { |chunk| path.include?(chunk) }
+  }
+      
+  # rdoc info
+  ret.rdoc_title    = "#{ret.name} #{ret.version} API Documentation"
+  ret.rdoc_options  = %w{--webcvs http://hg.pablotron.org/joggle}
+  ret.rdoc_dir      = 'doc'
+  ret.rdoc_files    = %w{bin/joggle lib/**/*.rb README examples/**/*}
+
+  # runtime info
+  ret.auto_require  = 'joggle'
+  ret.executables   = %w{joggle}
+  ret.require_path  = 'lib'
+  ret.package_name  = 'joggle'
+  ret.dependencies  = %w{xmpp4r json}
+
+  # package signing
+  if false && ENV['GEM_SIGNING_KEY'] && ENV['GEM_SIGNING_CHAIN']
+    ret.signing_key = File.expand_path(ENV['GEM_SIGNING_KEY'])
+    ret.signing_chain = ENV['GEM_SIGNING_CHAIN'].split(',').map { |path|
+      File.expand_path(path)
+    }
+  end
+
+  # package release dir
+  if path = ENV['RAKE_PACKAGE_DIR']
+    ret.pkg_dir = File.join(File.expand_path(path), ret.package_name)
+  end
+
+  if files = ret.rdoc_files
+    ret.rdoc_files = files.map { |e| Dir.glob(e) }.flatten.compact
+  end
+
+  # return package
+  ret
+end
+
+pkg = package_info
+
+gem_spec = Gem::Specification.new do |s|
+  # package information
+  s.name      = pkg.name.downcase
+  s.platform  = pkg.platform
+  s.version   = pkg.version
+  s.summary   = s.description = pkg.blurb
+  s.rubyforge_project = 'pablotron'
+
+  # files
+  pkg.reqs.each { |req| s.requirements << req }
+  s.files = pkg.include_files
+
+  # runtime info
+  s.executables   = pkg.executables
+  s.require_path  = pkg.require_path
+  s.autorequire   = pkg.auto_require
+
+  # dependencies
+  pkg.dependencies.each { |dep| s.add_dependency(dep) }
+
+  # rdoc info
+  s.has_rdoc = true
+  s.rdoc_options = ['--title', pkg.rdoc_title] + pkg.rdoc_options + pkg.rdoc_files
+
+  # author and project details
+  s.author    = pkg.author_name
+  s.email     = pkg.author_email
+  s.homepage  = pkg.url
+
+  # gem crypto stuff
+  if pkg.signing_key && pkg.signing_chain
+    s.signing_key   = pkg.signing_key
+    s.signing_chain = pkg.signing_chain
+  end
+end
+
+Rake::GemPackageTask.new(gem_spec) do |p|
+  p.need_tar_gz = true
+  # p.need_pgp_signature = true
+  p.package_dir = pkg.pkg_dir if pkg.pkg_dir
+end
+
+
+Rake::RDocTask.new do |rd|
+  rd.title = pkg.rdoc_title
+  rd.rdoc_dir = pkg.rdoc_dir
+  rd.rdoc_files.include(*pkg.rdoc_files)
+  rd.options.concat(pkg.rdoc_options)
+end
+
+task :clean => [:clobber]
+task :release => [:clean, :package]

data/TODO

@@ -0,0 +1,36 @@
+Release 
+-------
+  [x] new name, jitter is used too much (-> joggle)
+  [x] remove lib/joggle/monitor/{socket,jabber}.rb (unused)
+  [x] remove /tmp/foo debugging
+  [x] help text
+  [x] add new tweets to message store (so they don't show up on updates)
+  [x] cli tool and option parsing (bin/joggle)
+  [x] rdoc documentation
+  [x] add client-side support for restricted user list
+  [x] remove /resource bit from jid
+  [x] gem
+  [x] finish README
+  [x] check length of message before trying to submit it
+
+Next
+----
+  [ ] in_response_to (check time of last response for @messages?)
+  [ ] .reply option
+  [-] better error handling for 404s
+  [ ] handle rate limiting (add Throttle and message queue?)
+  [ ] .set option (to configure sleep, etc)
+
+Maybe 
+-----
+  [ ] handle client disconnects
+  [ ] fix http caching (give count to twitter)
+  [ ] redirect jabber client output to log file
+
+Future
+------
+  [ ] http proxy for post
+  [ ] add additional backends (sqlite3, at least)
+  [ ] make config directives relative to config path
+  [ ] add support for jabber auto-registration?
+  [ ] ignoring specifc jabber users

data/bin/joggle

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require 'joggle/cli/runner'
+
+# create and run joggle cli interface
+Joggle::CLI::Runner.run($0, ARGV)