rsence-pre 2.1.0.1.pre

data/lib/plugins/plugins.rb

@@ -0,0 +1,169 @@
+##   RSence
+ #   Copyright 2009 Riassence Inc.
+ #   http://riassence.com/
+ #
+ #   You should have received a copy of the GNU General Public License along
+ #   with this software package. If not, contact licensing@riassence.com
+ ##
+
+
+module RSence
+  
+  # Namespace for plugin classes and modules
+  module Plugins
+  end
+end
+
+# Contains the PluginBase module which has common methods for the bundle classes
+require 'plugins/plugin_base'
+
+# guiparser.rb contains the Yaml serializer for gui trees.
+# It uses JSONRenderer on the client to build user interfaces.
+require 'plugins/guiparser'
+
+# plugin_sqlite_db.rb contains automatic local sqlite database
+# creation for a plugin that includes it.
+require 'plugins/plugin_sqlite_db'
+
+# Interface for plugins in a plugin bundle
+require 'plugins/plugin_plugins'
+
+
+# Templates for the main plugin classes.
+require 'plugins/plugin'
+require 'plugins/gui_plugin'
+require 'plugins/servlet'
+
+
+module RSence
+  
+  module Plugins
+    
+    # Creates the runtime Plugin class from Plugin__
+    # @return [Plugin__]
+    def self.Plugin
+      lambda do |ns|
+        klass = Class.new( Plugin__ ) do
+          def self.ns=(ns)
+            define_method( :bundle_info ) do
+              ns.bundle_info
+            end
+          end
+        end
+        klass.ns = ns if ns
+        klass
+      end
+    end
+    
+    
+    # Creates the runtime GUIPlugin class from GUIPlugin__
+    # @return [GUIPlugin__]
+    def self.GUIPlugin
+      lambda do |ns|
+        klass = Class.new( GUIPlugin__ ) do
+          def self.ns=(ns)
+            define_method( :bundle_info ) do
+              ns.bundle_info
+            end
+          end
+        end
+        klass.ns = ns if ns
+        klass
+      end
+    end
+    
+    
+    # Creates the runtime Servlet class from Servlet__
+    # @return [Servlet__]
+    def self.Servlet
+      lambda do |ns|
+        klass = Class.new( Servlet__ ) do
+          def self.ns=(ns)
+            define_method( :bundle_info ) do
+              ns.bundle_info
+            end
+          end
+        end
+        klass.ns = ns if ns
+        klass
+      end
+    end
+    
+    # Loads bundle in an anonymous module with special environment options.
+    # @param [Hash] params
+    # @option params [String] :src_path ('/path/of/the_plugin/the_plugin.rb') The ruby source file to read.
+    # @option params [String] :bundle_path ('/path/of/the_plugin') The plugin bundle directory path.
+    # @option params [String] :bundle_name (:the_plugin) The name of the plugin as it will be registered.
+    # @return [Module] Isolated, anonymous module containing the evaluated source code of +src_path+
+    def self.bundle_loader( params )
+      begin
+        mod = Module.new do |m|
+          if RUBY_VERSION.to_f >= 1.9
+            m.define_singleton_method( :_bundle_path ) do
+              params[ :bundle_path ]
+            end
+          else
+            m.module_eval( <<-END
+            def self._bundle_path; #{params[:bundle_path].inspect}; end
+            END
+            )
+          end
+          
+          # Makes a full path using the plugin bundle as the 'local path'.
+          # The (optional) +prefix+ is a subdirectory in the bundle,
+          # the +suffix+ is the file extension.
+          def self.bundle_path( path=false, prefix=false, suffix=false )
+            return _bundle_path if not path
+            if suffix
+              path = "#{path}#{suffix}" unless path.end_with?(suffix)
+            end
+            if prefix
+              path = File.join( prefix, path )
+            end
+            path = File.expand_path( path, _bundle_path )
+            return path
+          end
+          def self.inspect; "#<module BundleWrapper of #{@@bundle_name}}>"; end
+          def self.const_missing( name )
+            if name == :Servlet
+              return Plugins.Servlet.call( self )
+            elsif name == :Plugin
+              return Plugins.Plugin.call( self )
+            elsif name == :GUIPlugin
+              return Plugins.GUIPlugin.call( self )
+            else
+              warn "Known const missing: #{name.inspect}"
+              super
+            end
+          end
+          begin
+            plugin_src = params[:src]
+            unless RUBY_VERSION.to_f >= 1.9
+              plugin_src = "_bundle_path = #{params[:bundle_path].inspect};" + plugin_src
+            end
+            m.module_eval( plugin_src )
+          rescue => e
+            src_path = params[:src_path]
+            src_path = "<undefined src_path>" if src_path == nil
+            params[:plugin_manager].plugin_error(
+              e,
+              'BundleLoaderEvalError',
+              "An error occurred while evaluating the plugin bundle #{params[:bundle_name]}.",
+              src_path
+            )
+          end
+        end
+        return mod
+      rescue => e
+        src_path = params[:src_path]
+        src_path = "<undefined src_path>" if src_path == nil
+        params[:plugin_manager].plugin_error(
+          e,
+          'BundleLoaderError',
+          "An error occurred while loading the plugin bundle #{params[:bundle_name]}.",
+          src_path
+        )
+      end
+    end
+  end
+end

data/lib/plugins/servlet.rb

@@ -0,0 +1,108 @@
+##   RSence
+ #   Copyright 2009 Riassence Inc.
+ #   http://riassence.com/
+ #
+ #   You should have received a copy of the GNU General Public License along
+ #   with this software package. If not, contact licensing@riassence.com
+ ##
+
+
+module RSence
+  module Plugins
+    
+    # Use the Servlet class to create responders for GET / POST urls.
+    # 
+    # A Servlet's public API is accessible like the other plugins directly.
+    # 
+    # == Responding to a URL consists of four phases:
+    # 1. PluginManager calls every {Servlet__#match #match} method
+    # 2. The plugins that return true to the {Servlet__#match #match} method are queried by their score -method
+    # 3. The matched plugins are sorted by score, lowest score wins. If it's a draw between equal scores, the choice is randomized.
+    # 4. The {Servlet__#post #post} or {Servlet__#get #get} method is called, depending on the type of HTTP request.
+    #
+    # = Extension hooks for server events
+    # These methods are provided as the basic server event hooks:
+    # * {#init +#init+} -- Use instead of +initialize+
+    # * {#open +#open+} -- Extend to open objects
+    # * {#flush +#flush+} -- Extend to write the state and to flush buffers
+    # * {#close +#close+} -- Extend to close objects
+    #
+    # = Extension hooks for REST events
+    # * {#match +#match+} -- Extend to return true for certain url and request_type conditions.
+    # * {#score +#score+} -- Extend to return a numeric score. Lower scores are "better" than higher ones. 
+    # * {#get   +#get+} -- Extend to handle a HTTP GET request and response.
+    # * {#post  +#post+} -- Extend to handle a HTTP POST request and response.
+    class Servlet__
+      
+      include PluginBase
+      
+      # @private Class type identifier for the PluginManager.
+      # @return [:Servlet]
+      def self.bundle_type; :Servlet; end
+      
+      # @private The constructor should not be accessed from anywhere else than the PluginManager, which does it automatically.
+      def initialize( bundle_name, bundle_info, bundle_path, plugin_manager )
+        @info    = bundle_info
+        @name    = bundle_name
+        @path    = bundle_path
+        @plugins = plugin_manager
+        register
+        @inited = false
+      end
+
+      # @return [Symbol] The name of the plugin bundle
+      attr_reader :name
+      
+      # @return [String] The absolute path of the plugin bundle.
+      attr_reader :path
+      
+      # @return [Hash] The {file:PluginBundleInfo meta-information} of the plugin bundle.
+      attr_reader :info
+      
+      # @private State of the plugin.
+      attr_reader :inited
+
+      
+      # @private Used by PluginManager to register the plugin
+      def register
+        @plugins.register_bundle( self, @name )
+        @inited = true
+      end
+      
+      # Extend to return true for the certain uri and request_type conditions your servlet code handles.
+      #
+      # @example Handles :get requests that begin with /foo
+      #   def match( uri, request_type )
+      #     request_type == :get and uri.start_with?( '/foo' )
+      #   end
+      #
+      # @param [String] uri The request uri (full "path" of the request url).
+      # @param [:get, :post] request_type The type of request. Only :get and :post are handled yet.
+      #
+      # @return [true] to match
+      # @return [false] to not match. Returns false to everything, if not extended.
+      def match( uri, request_type=:get ); false; end
+      alias match? match
+      
+      # If matched, returns score where lower is better. Score is needed for priority sorting, when several Servlet's {#match} are returning true for the same request.
+      #
+      # @return [Number]
+      def score; 100; end
+      
+      # Extend to do any GET request processing. Not doing anything by default.
+      #
+      # @param [Request] req The HTTP Request object.
+      # @param [Response] res The HTTP Response object.
+      # @param [Hash] ses The session object, not implemented yet.
+      def get( req, res, ses ); end
+      
+      # Extend to do any POST request processing. Not doing anything by default.
+      #
+      # @param [Request] req The HTTP Request object.
+      # @param [Response] res The HTTP Response object.
+      # @param [Hash] ses The session object, not implemented yet.
+      def post( req, res, ses ); end
+      
+    end
+  end
+end

data/lib/rsence.rb

@@ -0,0 +1,32 @@
+##   RSence
+ #   Copyright 2010 Riassence Inc.
+ #   http://riassence.com/
+ #
+ #   You should have received a copy of the GNU General Public License along
+ #   with this software package. If not, contact licensing@riassence.com
+ ##
+
+# The RSence module contains the server interfaces of RSence.
+# == The classes that matter from a Plugin developer's point of view are:
+# - {RSence::Plugins::GUIPlugin__ GUIPlugin}
+#   - Use for user interface plugins. Supports {RSence::Plugins::GUIParser GUITree} handling; the user interface starts automatically.
+#   - No server programming except defining GUITree YAML structures is required to define a user interface when using this class.
+# - {RSence::Plugins::Plugin__ Plugin}
+#   - Use for supporting plugins and advanced client-server development.
+#   - Great for providing backend functionality and miscellaneous API's for other Plugins.
+# - {RSence::Plugins::Servlet__ Servlet}
+#   - Use for raw POST / GET handlers to provide external API's, search engine indexes, plain html fallback etc.
+# - {RSence::HValue HValue}
+#   - Use for syncing data objects between client and server automatically.
+#   - Bind any plugin methods as responders / validators; they will be called whenever a client-server change triggers an data change event.
+# - {RSence::Message Message (msg)}
+#   - Used extensively to pass around session, data and request/response bindings.
+#   - The standard convention is usage as the first parameter, named +msg+, of any method that includes handling session-related data.
+# 
+# Most other classes are inner workings of RSence itself and are subject to change without further notice.
+module RSence
+end
+
+# Requires the ARGVParser that functions as the command-line user interface.
+require 'conf/argv'
+

data/lib/session/msg.rb

@@ -0,0 +1,327 @@
+##   RSence
+ #   Copyright 2006 Riassence Inc.
+ #   http://riassence.com/
+ #
+ #   You should have received a copy of the GNU General Public License along
+ #   with this software package. If not, contact licensing@riassence.com
+ ##
+
+
+require 'util/gzstring'
+
+
+module RSence
+
+  # A Message instance is used as a `messenger class` while processing client-server requests. It's initialized by the system and the convention guideline for its instance is +msg+, pass it on wherever msg might be needed.
+  # In most cases, the use of +msg+ is to just pass the same +msg+ onward from a method to another.
+  # 
+  # @example Logs a message in the client javascript console.
+  #  msg.console "#{Time.new.to_s} -- Testing.."
+  #
+  # @example Executes a custom Javascript command in the client.
+  #  msg.reply "alert('Hello!');"
+  #
+  # @example Invalidates the session.
+  #  msg.expire_session
+  #
+  # @example Creating a new {HValue}. Usage like this in any extended {Plugins::Plugin__ Plugin} or {Plugins::GUIPlugin__ GUIPlugin} class. It's recommended to use the +values.yaml+ file to create any initial values.
+  #  def create_example_value( msg )
+  #    ses = get_ses(msg)
+  #    default_data = "Some text"
+  #    if ses.has_key?( :example_value )
+  #      # Resets the default data, causes it to update in the client too on the next sync.
+  #      ses[:example_value].set( msg, default_data )
+  #    else
+  #      # Creates a new value with default data
+  #      ses[:example_value] = HValue.new( msg, default_data )
+  #    end
+  #  end
+  # 
+  class Message
+    
+    # @private Session data placeholder, assigned by SessionManager.
+    attr_accessor :session 
+    
+    # Flag for a new session's first request.
+    # Check it in your code to decide what to do, when a new session is encountered.
+    # In systems that require authentication, this may be used as a trigger to display a login/register dialog.
+    # @return [Boolean] This flag is true on the first request of a newly created session.
+    attr_accessor :new_session
+    
+    # Flag for a restored session's first request.
+    # Check it in your code to decide what to do, when a restored session is encountered.
+    # @return [Boolean] This flag is true on the first request of a newly restored session.
+    attr_accessor :restored_session
+    
+    # Contains the source ses on the first request after the active session was cloned from another session.
+    # @return [false, Hash]
+    attr_accessor :cloned_source 
+    
+    # Contains the target sessions packed in an Array on the first request after another session was cloned from the active session.
+    # @return [false, Array<Hash>]
+    attr_accessor :cloned_targets
+    
+    # @private The session is not valid by default, it's set by SessionManager, if everything seems ok.
+    attr_accessor :ses_valid 
+    
+    # The HTTP Request object of the active request.
+    # @return [Request]
+    attr_accessor :request 
+    
+    # The HTTP Response object of the active request.
+    # @return [Response]
+    attr_accessor :response
+    
+    # @private Response output buffer, Array of Strings; sent to client using to_json
+    attr_accessor :buffer
+    
+    # @private Value response output buffer, Array value setters; sent to client using to_json before {:buffer} is sent
+    attr_accessor :value_buffer
+    
+    # @private The request success flag; Boolean.
+    attr_accessor :response_success
+    
+    # Reference to {Transporter}
+    # @return [Transporter]
+    attr_accessor :transporter
+    
+    # Reference to {ValueManager}
+    # @return [ValueManager]
+    attr_accessor :valuemanager
+    
+    # Reference to {SessionManager}
+    # @return [SessionManager]
+    attr_accessor :sessions
+    
+    # Reference to the main {PluginManager}
+    # @return [PluginManager]
+    attr_accessor :plugins
+    
+    # @private Message is initialized with a valid {Transporter}, {Request} and {Response} objects along with options. 
+    def initialize( transporter, request, response, options )
+    
+      @config = RSence.config
+    
+      @request  = request
+      @response_success = false
+      @response = response
+      @session  = nil
+      @buffer = []
+    
+      @options = options
+    
+      # Value response output.
+      @value_buffer = []
+    
+      # The session key placeholder.
+      @ses_key = false
+      @new_session      = false
+      @restored_session = false
+      @cloned_source = false
+      @cloned_targets = false
+      @ses_valid = false
+      @error_js = ''
+    
+      # global instances
+      @transporter    = transporter
+      @valuemanager   = @transporter.valuemanager
+      @sessions = @transporter.sessions
+      @plugins  = @transporter.plugins
+    
+      if options[:servlet]
+        @do_gzip = false
+      else
+        @response.content_type = 'text/javascript; charset=utf-8'
+        @response['Cache-Control'] = 'no-cache'
+      
+        # gnu-zipped responses:
+        if @request.header['accept-encoding'] and @request.header['accept-encoding'].include?('gzip') and not @config[:no_gzip]
+          @response['Content-Encoding'] = 'gzip'
+          @do_gzip = true
+        else
+          @do_gzip = false
+        end
+      end
+    
+      @response_sent = false
+    end
+  
+    # @private Returns true for Internet Explorer 6.0
+    # @return [Boolean]
+    def ie6;
+      (request.header.has_key?('user-agent') and request.header['user-agent'].include?('MSIE 6.0'))
+    end
+  
+    # Invalidates the active session.
+    # @return [nil]
+    def expire_session
+      @sessions.expire_session( @session[:ses_id] ) if @session
+    end
+  
+    # @private Define the session key.
+    def ses_key=(ses_key)
+      @ses_key = ses_key
+    end
+    
+    # @private Getter for session key.
+    # @return [String] The active session key.
+    def ses_key
+      @ses_key
+    end
+  
+    # Getter for the user id
+    # @return [Number, String] The current user id. Returns 0 by default.
+    def user_id
+      @session[:user_id]
+    end
+  
+    # Setter for the user id
+    # @param [Number, String] user_id The user id to set. Use in login situations to store the user id.
+    # @return [nil]
+    def user_id=(user_id)
+      @session[:user_id] = user_id
+    end
+    
+    # Returns the session id
+    # @return [Number]
+    def ses_id
+      @session[:ses_id]
+    end
+    alias session_id ses_id
+    
+    # @private Sets the session id
+    # @param [Number] ses_id The session id to set.
+    # @return [nil]
+    def ses_id=(ses_id)
+      @session[:ses_id] = ses_id
+    end
+    
+    # @private Sets the error message
+    # @param [String] error_js The error script to send instead of the regular buffers.
+    def error_msg( error_js )
+      @error_js = error_js
+      # response_done
+    end
+    
+    # @private Converts the buffer to JSON
+    def buf_json(buffer)
+      buffer.to_json
+    end
+  
+    # @private Called to flush buffer.
+    def response_done
+      return if @response_sent
+      if not @response_success
+        @response.status = 200
+        #@response.status = 503
+      
+        buffer = [
+          "" # empty session key will stop the syncing
+        ] + @error_js
+      else
+        ## The response status should always be 200 (OK)
+        @response.status = 200
+      
+        buffer = @value_buffer + @buffer
+        if @ses_key
+          buffer.unshift( @ses_key )
+        end
+      
+      end
+    
+      # flush the output
+      if @do_gzip
+        outp = GZString.new('')
+        gzwriter = Zlib::GzipWriter.new(outp,Zlib::BEST_SPEED)
+        gzwriter.write( buf_json(buffer) )
+        gzwriter.close
+      else
+        outp = buf_json(buffer)
+      end
+    
+      @response['content-length'] = outp.size
+      @response.body = outp
+    
+      @response_sent = true
+    end
+  
+    # Sends data to the client, usually javascript, but is valid for any data that responds to #to_json
+    # @param [String<js>, #to_json] data Javascript source or object that responds to #to_json
+    # @param [Boolean] dont_squeeze When true, doesn't `squeeze` the contents (jsmin + jscompress)
+    def reply(data,dont_squeeze=false)
+      data.strip!
+      data = @plugins[:client_pkg].squeeze( data ) unless dont_squeeze
+      puts data if @config[:trace]
+      @buffer.push( data )
+    end
+  
+    # @private For value manager; insert changed values BEFORE other js.
+    def reply_value(data)
+      puts data if @config[:trace]
+      @value_buffer.push( data )
+    end
+  
+    # Sends data to the client's javascript console.
+    # @param [#to_json] data Any data that can be presented in the Javascript console.
+    def console(data)
+      reply( "console.log(#{data.to_json});" )
+    end
+    
+    # Serves an image object and returns its disposable URL.
+    # Calls the default `ticket` plugin.
+    # @param [#to_blob] img_obj RMagick image object.
+    # @param [String] img_format The format img_obj#to_blob is encoded as.
+    # @return [String] The URL where the image can be accessed from using a GET request.
+    # @deprecated
+    # Use {TicketPlugin#serve_img ticket.serve_img} directly instead.
+    def serve_img( img_obj, img_format='PNG' )
+      call( :ticket, :serve_img, self, img_obj, img_format )
+    end
+    
+    # Binary data to be served once as a downloadable file attachment, returns a disposable URL.
+    # Calls the default `ticket` plugin.
+    # @param [String] file_data The binary data to serve
+    # @param [String] content_type The MIME type to serve the data as
+    # @param [String] filename The name of the downloadable file.
+    # @return [String] The URL where the downloadable file can be accessed from using a GET request.
+    # @deprecated
+    # Use {TicketPlugin#serve_file ticket.serve_file} directly instead.
+    def serve_file( file_data, content_type='text/plain', filename='untitled.txt' )
+      call( :ticket, :serve_file, self, file_data, content_type, filename )
+    end
+    
+    # Sends any binary to be served indefinitely, returns a unique, random, static URL.
+    # Calls the default `ticket` plugin.
+    # IMPORTANT: PLEASE call {#release_rsrc} manually, when the resource is no longer needed to free the memory occupied!
+    # HINT: In most cases, it's a better idea to use serve_img or serve_file to expire the resource automatically.
+    # @see {#release_rsrc}
+    # @param [String] rsrc_data The binary data of the resource to serve.
+    # @param [String] content_type The MIME type to serve the data as
+    # @return [String] The URL where the resource can be accessed from using a GET request.
+    # @deprecated
+    # Use {TicketPlugin#serve_rsrc ticket.serve_rsrc} directly instead.
+    def serve_rsrc( rsrc_data, content_type='text/plain' )
+      call(:ticket,:serve_rsrc,self, rsrc_data, content_type )
+    end
+  
+    # Removes the URL served, you *must* call this manually when after a served resource is no longer needed!
+    # Calls the default `ticket` plugin.
+    # @see {#serve_rsrc}
+    # @param [String] uri The URL to delete; the return value of {#serve_rsrc}
+    # @deprecated
+    # Use {TicketPlugin#serve_rsrc ticket.serve_rsrc} directly instead.
+    def release_rsrc( uri )
+      call(:ticket,:del_rsrc, uri[3..-1] )
+    end
+    alias unserve_rsrc release_rsrc
+  
+    # Calls a method of a registered plugin with optional arguments.
+    # @param [Symbol] plugin_name The plugin to call
+    # @param [Symbol] plugin_method The method of the plugin to call
+    # @param *args Any arguments to pass to the `plugin_method`
+    def call( plugin_name, plugin_method, *args )
+      @plugins.call( plugin_name, plugin_method, *args)
+    end
+    alias run call
+  end
+end