howlr 0.1.0

data/CHANGELOG.txt

@@ -0,0 +1,3 @@
+=== 0.1.0 :: 2008-03-10
+
+* First public release.

data/Manifest.txt

@@ -0,0 +1,20 @@
+CHANGELOG.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/howlr
+bin/howlr-ctl
+config.example.yml
+examples/active_resource_client_example.rb
+examples/php_client_example.php
+lib/howlr.rb
+lib/howlr/controllers.rb
+lib/howlr/deliverers.rb
+lib/howlr/deliverers/email/mailer/message.rhtml
+lib/howlr/environment.rb
+lib/howlr/message.rb
+lib/howlr/version.rb
+lib/howlr/views.rb
+setup.rb
+test/howlr_test.rb
+test/test_helper.rb

data/README.txt

@@ -0,0 +1,11 @@
+= Howlr
+
+The Howlr daemon provides RESTful interface for sending outgoing messages. 
+Messages are submitted via HTTP and dispatched to other protocols. Currently
+ only email (SMTP and Sendmail) is supported, but other delivery methods 
+(SMS, IM, etc.) are possible.
+
+
+Please see Howlr's Google Code site for further information:
+
+http://code.google.com/p/howlr/

data/Rakefile

@@ -0,0 +1,62 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+require 'hoe'
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'howlr', 'version')
+
+AUTHOR = "Matt Zukowski"
+EMAIL = "matt@roughest.net"
+DESCRIPTION = "Sends out emails/messages using a REST API."
+GEM_NAME = "howlr"
+RUBYFORGE_PROJECT = "howlr"
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+
+ENV['nodot'] = '1'
+
+NAME = "howlr"
+REV = nil
+#REV = `svn info`[/Revision: (\d+)/, 1] rescue nil
+VERS = ENV['VERSION'] || (Howlr::VERSION::STRING + (REV ? ".#{REV}" : ""))
+                          CLEAN.include ['**/.*.sw?', '*.gem', '.config']
+RDOC_OPTS = ['--quiet', '--title', "howlr #{VERS} documentation",
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject { |x| Array(x).first == 'hoe' } 
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/*_test.rb"]
+  p.clean_globs = CLEAN  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  #p.changes        - A description of the release's latest changes.
+  #p.extra_deps     - An array of rubygem dependencies.
+  #p.spec_extras    - A hash of extra values to set in the gemspec.
+  
+  p.extra_deps = [
+    ['picnic', '~>0.6.2'], 
+    ['reststop', '~>0.2.0']
+  ]
+  p.spec_extras = {:executables => ['howlr', 'howlr-ctl']}
+end

data/bin/howlr

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+# ---------------------------------------------------------------------
+# This file is part of Howlr (http://howlr.googlecode.com/).
+#
+# Howlr is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Howlr is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Howlr.  If not, see <http://www.gnu.org/licenses/>.
+# ---------------------------------------------------------------------
+
+if File.exists?(picnic = File.expand_path(File.dirname(File.expand_path(__FILE__))+'/../vendor/picnic/lib'))
+  $: << picnic
+elsif File.exists?(picnic = File.expand_path(File.dirname(File.expand_path(__FILE__))+'/../../picnic/lib'))
+  $: << picnic
+else
+  require 'rubygems'
+end
+
+require 'picnic/cli'
+
+cli = Picnic::Cli.new(
+  'howlr',
+  :app_path => File.expand_path(File.dirname(File.expand_path(__FILE__)))
+)
+
+cli.handle_cli_input

data/bin/howlr-ctl

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+
+# ---------------------------------------------------------------------
+# This file is part of Howlr (http://howlr.googlecode.com/).
+#
+# Howlr is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Howlr is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Howlr.  If not, see <http://www.gnu.org/licenses/>.
+# ---------------------------------------------------------------------
+
+if File.exists?(picnic = File.expand_path(File.dirname(File.expand_path(__FILE__))+'/../vendor/picnic/lib'))
+  $: << picnic
+elsif File.exists?(picnic = File.expand_path(File.dirname(File.expand_path(__FILE__))+'/../../picnic/lib'))
+  $: << picnic
+else
+  require 'rubygems'
+end
+
+require 'picnic/service_control'
+
+ctl = Picnic::ServiceControl.new('howlr')
+
+ctl.handle_cli_input

data/config.example.yml

@@ -0,0 +1,99 @@
+# This is a configuration file for the Howlr RESTful messaging daemon.
+
+# AN IMPORTANT NOTE ABOUT YAML CONFIGURATION FILES:
+# !!! Be sure to use spaces instead of tabs for indentation, as YAML is very
+# !!! sensitive to white-space inconsistencies!
+
+##### HTTP SERVER ###################################################################
+
+# Under what HTTP environment are you running the Fluxr server? The following methods
+# are currently supported:
+#
+# webrick -- simple stand-alone HTTP server; this is the default method
+# mongrel -- fast stand-alone HTTP server; much faster than webrick, but 
+#            you'll have to first install the mongrel gem
+# 
+
+### webrick example
+
+server: webrick
+port: 7008
+
+### webrick SSL example
+
+#server: webrick
+#port: 443
+#ssl_cert: /path/to/your/ssl.pem
+
+# if the private key is separate from cert:
+#ssl_key: /path/to/your/private_key.pem
+
+
+### mongrel example
+
+#server: mongrel
+#port: 7008
+
+# It is possible to run mongrel over SSL, but you will need to use a reverse proxy
+# (try Pound or Apache).
+
+##### MAILER ##########################################################################
+
+# By default, howlr will try to use the local sendmail server. This might work as-is, 
+# but chances are you'll probably have to use SMTP. Below is an example of an SMTP 
+# configuration.
+#
+# See http://api.rubyonrails.com/classes/ActionMailer/Base.html for detailed
+# mailer configuration documentation.
+
+#mailer:
+#  delivery_method: smtp
+#  smtp_settings:
+#    address: smtp.example.com
+#    user_name: foo
+#    password: bar
+#    authentication: :plain
+
+
+##### AUTHENTICATION ##################################################################
+
+# Howlr supports two methods for authentication: Basic HTTP and CAS. 
+
+### Basic HTTP Example
+# Uset the following if you want Howlr to demand a username and password from the user
+# using basic HTTP authentication clients. Note that this isn't very secure unless
+# you run Taskr over HTTPS (see the webrick SSL example above).
+
+#authentication:
+#  method: basic
+#  username: howlr
+#  password: howl!
+
+### CAS Example
+# Uset the following if you want Howlr to demand a username and password using
+# Single Sign-On CAS (Central Authentication System). For more information on CAS see
+# http://code.google.com/p/rubycas-server/.
+# The cas_base_url setting should be the URL of your CAS server.
+
+#authenticatoin:
+#  method: cas
+#  cas_base_url: https://login.example.foo/cas
+
+
+##### LOGGING #########################################################################
+
+# This log is where you'll want to look in case of problems. 
+# 
+# By default, we will try to create a log file named 'howlr.log' in the current 
+# directory (the directory where you're running howlr from). A better place to put 
+# the log is in /var/log, but you will have to run howlr as root or otherwise give 
+# it permissions.
+# 
+# Set the level to DEBUG if you want more detailed logging. Other options are
+# INFO, WARN, and ERROR.
+
+log:
+  file: howlr.log
+  level: INFO
+#  file: /var/log/howlr.log
+#  level: DEBUG

data/examples/active_resource_client_example.rb

@@ -0,0 +1,21 @@
+require 'active_resource'
+
+# Define the proxy class
+class Message < ActiveResource::Base
+  self.site = 'http://localhost:7008'
+end
+
+message = Message.new
+message.subject = "Howlr Test"
+message.body = "This is just a test!"
+message.from = "Test McTestski <test@example.foo>"
+message.recipients = "John Doe <jdoe@example.foo>; Sally Smith <ssmith@example.foo>"
+  
+# Saving the message commits it to the server, causing the message to 
+# be sent out.
+message.save
+
+# The server temporarily stores copies of all sent messages. Saving a  
+# message (i.e. sending it) assigns to it a unique ID. We can use this 
+# ID to later retrieve a copy of this message.
+message2 = Message.find(message.id) 

data/examples/php_client_example.php

@@ -0,0 +1,65 @@
+<?php
+
+/**
+  To use this exmple, you will need the Zend Framework from:
+
+      http://framework.zend.com/download
+
+  For more information on using the Zendr_Rest_Client, see:
+
+      - http://framework.zend.com/manual/en/zend.rest.client.html
+      - http://www.pixelated-dreams.com/archives/243-Next-Generation-REST-Web-Services-Client.html
+**/
+
+require 'Zend/Rest/Client.php';
+
+$howlr_site_url = "http://localhost:7008";
+
+/**
+  If you have your Howlr server configured to require authentication, uncomment the next block
+  and change the username ans password to whatever you have in your config.yml file.
+**/
+//$username = 'howlr';
+//$password = 'howl!';
+//Zend_Rest_Client::getHttpClient()->setAuth($username, $password);
+
+$rest = new Zend_Rest_Client($howlr_site_url);
+
+$data = array(
+	'from' => "Test McTestski <tmctestski@example.foo>",
+	'recipients' => "John Doe <jdoe@example.foo>; Sally Smith <ssmith@example.foo>",
+	'subject' => "Testing Howlr",
+	'body' => "Did it work?"
+);
+
+$r = $rest->post('/messages.xml', $data);
+
+/**
+  You can also send out HTML emails.
+**/
+
+$rest = new Zend_Rest_Client($howlr_site_url);
+
+$html = "
+<html>
+<head>
+	<title>Test</title>
+</head>
+<body>
+	<h1>This is a test!</h1>
+	<p>Did it work?</p>
+</body>
+</html>
+";
+
+$data = array(
+	'from' => "Test McTestski <tmctestski@example.foo>",
+	'recipients' => "John Doe <jdoe@example.foo>",
+	'subject' => "Testing Howlr HTML",
+	'body' => $html,
+	'content_type' => 'text/html'
+);
+
+$r = $rest->post('/messages.xml', $data);
+ 
+?>

data/lib/howlr.rb

@@ -0,0 +1,46 @@
+# This file is part of Howlr.
+#
+# Howlr is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Howlr is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Howlr.  If not, see <http://www.gnu.org/licenses/>.
+
+$: << File.dirname(File.expand_path(__FILE__))
+require 'howlr/environment'
+
+Camping.goes :Howlr
+
+Howlr.picnic!
+
+require 'howlr/views'
+require 'howlr/controllers'
+
+# defaults, overridden by your conf file
+$CONF[:authentication] ||= {:username => 'howlr', :password => 'howl!'}
+$CONF[:mailer] ||= {:delivery_method => 'sendmail'}
+
+if Howlr::Conf[:authentication]
+  Howlr.authenticate_using(Howlr::Conf[:authentication][:method] || :basic)
+end
+
+module Howlr
+  def self.authenticate(credentials)
+    credentials[:username] == Howlr::Conf[:authentication][:username] &&
+      credentials[:password] == Howlr::Conf[:authentication][:password]
+  end
+end
+
+def Howlr.create
+  Howlr::Deliverers::Email::Mailer.delivery_method = Howlr::Conf[:mailer][:delivery_method]
+  Howlr::Deliverers::Email::Mailer.smtp_settings = Howlr::Conf[:mailer][:smtp_settings]
+end
+
+Howlr.start_picnic

data/lib/howlr/controllers.rb

@@ -0,0 +1,129 @@
+# This file is part of Howlr.
+#
+# Howlr is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Howlr is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Howlr.  If not, see <http://www.gnu.org/licenses/>.
+
+require 'howlr/message'
+require 'restr'
+
+module Howlr::Controllers
+  # Messages are created and delivered via this resource.
+  class Messages < REST 'messages'
+    # Contains a list of messages that were created.
+    # Note that this is not persistent! This value is wiped when the server
+    # is shut down.
+    @@messages = []
+    
+    # Render a form for manually inputing a new message.
+    def new
+      render :new_message
+    end
+    
+    # Show the message with the given id created by this server.
+    def read(id)
+      puts "Looking for #{id}"
+      @message = @@messages.find{|m| m.id == id}
+      puts @format
+      if @message
+        render :message
+      else
+        _error("There is no recently sent message with id #{id}.", 404)
+      end
+    end
+    
+    # Create and send a new message.
+    def create
+      if @input['rest'] == '1' && @input['0']
+        # for PHP Zend_Rest_Client compatibility
+        data = @input['0']
+      else
+        data = @input
+      end
+      
+      data[:author] ||= @env['REMOTE_HOST']
+      
+      $LOG.debug "Creating new message from: #{data.inspect}"
+      
+      
+      @message = Howlr::Message.new(data)
+      $LOG.debug "Sending message: #{@message.inspect}"
+      
+      @@messages << @message
+      
+      begin
+        @message.send
+      rescue Howlr::Message::CallbackError => e
+        return _error("Error while executing callback: #{e.underlying_error}", 500, e.underlying_error)
+      rescue => e
+        return _error("Error while sending message: #{e.message}", 500, e)
+      end
+      
+      @headers['Location'] = "/messages/#{@message.id}?format=#{@format}"
+      
+      render :message
+    end
+  end
+  
+  # Can be used as a callback target for messages. This makes it possible
+  # to receive a notification when a message is sent out.
+  #
+  # For example, set up your outgoing message's callback values as follows:
+  #
+  #   callback_url: http://howlr.example.com/delivery_notifications
+  #   callback_method: post
+  #
+  # Now when the message is sent, a delivery notice will be sent back to
+  # the sender, informing them of whether the message was successfully
+  # sent out, or if some sort of delivery error occurred.
+  #
+  # The real-world usefulness of this is probably questionable. It's just
+  # meant to illustrate how a message callback receiver can be implemented.
+  class DeliveryNotifications < REST 'delivery_notifications'
+    def create
+      $LOG.debug "Creating delivery notification from: #{@input.inspect}"
+      
+      auth = {
+        :username => Conf[:auth_username], 
+        :password => Conf[:auth_password]
+      }
+      
+      begin
+        m = Restr.get("http://localhost:#{Conf[:port]}#{Conf[:uri_path]}messages", 
+          {:id => @input[:message_id], :format => 'XML'}, 
+          auth)
+        
+        to = m['from']
+        subject = "Howlr Message Delivery Notification"
+        
+        body = "Your message regarding #{m['subject'].inspect} was " +
+          (@input[:send_success] == 'true' ? '' : 'NOT') +
+          " sent successfully to #{@input[:recipient_address]}."
+        
+        data = {
+          :recipients => to, 
+          :body => body, 
+          :subject => subject,
+          :from => @input[:recipient_address]
+        }
+        puts data.inspect
+        Restr.post("http://localhost:#{Conf.port}#{Conf.uri_path}messages",
+          data, auth)
+          
+      rescue Net::HTTPServerException, Net::HTTPError => e
+        return _error($LAST_ERROR_BODY, e.response.code, e)
+      rescue => e
+        return _error(e.inspect, 500, e)
+      end
+    end
+  end
+end