nitro 0.1.2 → 0.2.0

data/lib/n/app/fragment.rb

@@ -1,3 +1,14 @@
+# code:
+# * George Moschovitis  <gm@navel.gr>
+#
+# (c) 2004 Navel, all rights reserved.
+# $Id: fragment.rb 99 2004-10-22 09:50:28Z gmosx $
+
+require "n/utils/cache"
+require "n/mixins"
+
+module N; module App
+
 # = Fragment
 #
 # A Fragment is the output of a rendered script. Additional metadata 
@@ -16,16 +27,6 @@
 # - less memory per server
 # - can run background cron scripts over the fragments (compression)
 #
-# code:: gmosx
-#
-# (c) 2004 Navel, all rights reserved.
-# $Id: fragment.rb 71 2004-10-18 10:50:22Z gmosx $
-
-require "n/utils/cache"
-require "n/mixins"
-
-module N; module App
-
 class Fragment
 	include N::Expirable
 	include N::LRUCache::Item
@@ -55,6 +56,8 @@ class Fragment
 		@expires = @lm + ea
 	end
 
+	# Is the fragment expired?
+	#
 	def expired?
 		return true if @expires.nil? || (Time.now > @expires)
 	end

data/lib/n/app/handlers.rb

@@ -1,24 +1,31 @@
-# = Handlers
+# code: 
+# * George Moschovitis  <gm@navel.gr>
 #
-# code: gmosx
-#
-# (c) 2002-2003 Navel, all rights reserved.
-# $Id: handlers.rb 71 2004-10-18 10:50:22Z gmosx $
+# (c) 2004 Navel, all rights reserved.
+# $Id: handlers.rb 99 2004-10-22 09:50:28Z gmosx $
 
 require "n/utils/cache"
 require "n/server/filter"
 
 module N; module App
 
-# = App server handlers handle requests to specific resources.
+# = Handler
+# 
+# App server handlers handle requests to specific resources.
+# Handlers are a special kinf of filters so the can be chained
+# in the rendering pipeline.
 #
 # === Design:
 #
-# Handlers are NOT singleton classes. This way we can assign one handler
-# class to multiple resources, and keep statistics and metrics for
-# each resource.
+# Handlers are NOT singleton classes. This way we can assign one 
+# handler class to multiple resources, and keep statistics and 
+# metrics for each resource.
 #
 class Handler < N::ServerFilter
+
+	# Perform the actual work of the handler
+	# Typically calls the next filter in the pipeline afterwards.
+	#
 	def process(request)
 		# nop
 		
@@ -26,21 +33,19 @@ class Handler < N::ServerFilter
 		@next_filter.process(request) if @next_filter
 	end
 
-	#---------------------------------------------------------------------
-	# Testing/Metrics support methods
-
-
 end # class
 
-# Handler Error.
-# raise this if an error happens when handling a request
-
+# = Handler Error
+#
+# Raise this if an error happens when handling a request
+#
 class HandlerError < StandardError; end
 
 # = Script Handler
 #
-# Base handler for scripts.
-
+# Base handler for scripts. All othere script handlers are extensions
+# from this class.
+#
 class ScriptHandler < Handler
 
 	# cache the compiled page scripts to optimize future references.
@@ -93,7 +98,8 @@ class ScriptHandler < Handler
 		return @@compiled_script_cache
 	end
 
-	# Log a rendering error
+	# Log a rendering error. The accumulated log is available
+	# for rendering in the offending page when in Debug mode.
 	#
 	def log_error(request, ex)
 		request.log_error "--------"
@@ -105,9 +111,10 @@ class ScriptHandler < Handler
 
 end
 
-# Handler Error.
-# raise this if an error happens when handling a request
-
+# =ScriptHandlerError
+#
+# Raise this if an error happens when handling a script.
+#
 class ScriptHandlerError < HandlerError
 	attr_reader :error_line
 

data/lib/n/app/handlers/code-handler.rb

@@ -1,10 +1,8 @@
-# = Code handler (.sx scripts)
-#
 # code: 
-# George Moschovitis  <gm@navel.gr>
+# * George Moschovitis  <gm@navel.gr>
 #
 # (c) 2004 Navel, all rights reserved.
-# $Id: code-handler.rb 71 2004-10-18 10:50:22Z gmosx $
+# $Id: code-handler.rb 99 2004-10-22 09:50:28Z gmosx $
 
 require "cgi"
 require "singleton"

data/lib/n/app/handlers/page-handler.rb

@@ -1,11 +1,9 @@
-# = XML Page handler (.sx scripts)
-#
 # code:
-# George Moschovitis  <gm@navel.gr>
-# Anastasios Koutoumanos  <ak@navel.gr>
+# * George Moschovitis  <gm@navel.gr>
+# * Anastasios Koutoumanos  <ak@navel.gr>
 #
 # (c) 2004 Navel, all rights reserved.
-# $Id: page-handler.rb 89 2004-10-20 12:55:58Z gmosx $
+# $Id: page-handler.rb 99 2004-10-22 09:50:28Z gmosx $
 
 require "cgi"
 require "singleton"

data/lib/n/app/request-part.rb

@@ -1,12 +1,8 @@
-# = RequestPart
-#
-# Encapsulates a multipart part.
-#
 # code:
-# George Moschovitis  <gm@navel.gr>
+# * George Moschovitis  <gm@navel.gr>
 #
 # (c) 2004 Navel, all rights reserved.
-# $Id: request-part.rb 71 2004-10-18 10:50:22Z gmosx $
+# $Id: request-part.rb 99 2004-10-22 09:50:28Z gmosx $
 
 require "cgi"
 require "ftools"
@@ -48,7 +44,6 @@ class RequestPart
 	# Hack fixed save for webrick!
 	#
 	def save(prefix, forced_filename = nil, forced_extension = nil)
-		# ARGH!! local path is used for something else, FIXME!!
 		::FileUtils.mkdir_p(prefix)
 		save_path = "#{prefix}/#{@filename}"
 		::File.open(save_path, "wb") {|f| f.write @body }

data/lib/n/app/request.rb

@@ -1,15 +1,8 @@
-# = Request
-#
-# Will use params with symbols for args. use uppercase for system 
-# 'args'.
-#
-# === INVESTIGATE:
-# extend request from hash? to make more compatible with irb?
-#
-# code: gmosx, drak
+# code:
+# * George Moschovitis  <gm@navel.gr>
 #
 # (c) 2004 Navel, all rights reserved.
-# $Id: request.rb 71 2004-10-18 10:50:22Z gmosx $
+# $Id: request.rb 101 2004-10-22 12:35:39Z gmosx $
 
 require "cgi"
 require "ftools"
@@ -108,16 +101,17 @@ end
 
 # = Request
 #
-# Encapsulates an http protocol request. Generally clones
-# the Apache Request passed by mod_ruby.
-#
-# === Todo:
+# The context of an http protocol request. Encapsulates both
+# the request and the response context.
+# 
+# === Future:
 #
 # - USE libapreq!
 # - Dont use env_table (arghhhh!)
 # - dont use a separate path and real path
 # - MEGA: unify request and request (like a socket, io
 #   stream,etc). Evan subclass IO!
+# - extend request from hash? to make more compatible with irb?
 #
 # === Design:
 #
@@ -142,7 +136,8 @@ end
 #		com/caucho/server/http/HttpRequest.java
 # - use as much of ruby's default cgi/http code as
 #   possible (why reinvent the wheel?)
-#
+# Will use params with symbols for args. use uppercase for system 
+# 'args'.
 #
 class Request 
 	# include usefull query parsing code from the standard
@@ -184,9 +179,12 @@ class Request
 	# The query string is parsed to the parameters
 	# hash.
 	attr_accessor :parameters
+	# alias for the parameters hash
 	alias_method :query, :parameters
+	# alias for the parameters hash	
+	alias_method :params, :parameters
 
-	# the session this request is part-of
+	# the session this request is part-of.
 	attr_accessor :session
 
 	# The parts attached to this request.
@@ -195,7 +193,9 @@ class Request
 	# can easily enumerate parts.
 	attr_accessor :parts
 
-	# the level of the request (0 = toplevel) 
+	# The level of the request (0 = toplevel). When the evaluating
+	# the sub-scripts that the top level script includes, the 
+	# request level is incremented.  
 	attr_accessor :level
 
 	# the remote address for this request
@@ -238,7 +238,7 @@ class Request
 	# the incoming cookies
 	attr_accessor :in_cookies
 
-	# request: 
+	# response: 
 	
 	# the outgoing headers
 	attr_accessor :out
@@ -302,6 +302,7 @@ class Request
 	alias_method :parse_cookie_string, :parse_cookies
 
 	# === Input:
+	#
 	# the cookie name
 	#
 	# === Output:
@@ -331,12 +332,14 @@ class Request
 #-------------------------------------------------------------------------------
 # Query
 
+	# Parse the query string and populate the parameters hash.
+	#
 	def parse_query_string
 		return N::UriUtils.query_string_to_hash(@query_string)
 	end
 
 	# Return the value of a query parameter
-
+	#
 	def [](name)
 		return @parameters[name]
 	end
@@ -362,8 +365,9 @@ class Request
 	# Set the value of a query parameter
 	#
 	# === FIXME:
+	#
 	# - handle multivalued parameters!
-
+	# 
 	def []=(name, value)
 		@parameters[name] = value
 	end
@@ -537,7 +541,8 @@ class Request
 	# --------------------------------------------------------------------
 	# Debugging helper 
 	
-	#
+	# Accumulate errors in a request log. This log can be presented
+	# in the offending page when running in debug mode.
 	#
 	def log_error(str)
 		@error_log = [] unless @error_log
@@ -546,7 +551,7 @@ class Request
 	end
 
 	# ====================================================================
-	# Request
+	# Response
 	
 	# TODO: add status codes, messages
 

data/lib/n/app/script.rb

@@ -1,19 +1,8 @@
-# = Base class for scripts.
+# code:
+# * George Moschovitis  <gm@navel.gr>
 #
-# Typically a handler evaluates a script. The base class describing 
-# a script is defined here.
-# A generalized fragment caching system is also defined.
-#
-# see handlers/page-handler::PageScript for more information.
-#
-# TODO:
-# - convert all methods to __ to avoid collisions.
-#
-# code: 
-# George Moschovitis  <gm@navel.gr>
-#
-# (c) 2003 Navel, all rights reserved.
-# $Id: script.rb 71 2004-10-18 10:50:22Z gmosx $
+# (c) 2004 Navel, all rights reserved.
+# $Id: script.rb 99 2004-10-22 09:50:28Z gmosx $
 
 require "fileutils"
 

data/lib/n/app/server.rb

@@ -1,9 +1,8 @@
-# = AppServer
-#
-# code:: gmosx
+# code:
+# * George Moschovitis  <gm@navel.gr>
 #
 # (c) 2004 Navel, all rights reserved.
-# $Id: server.rb 89 2004-10-20 12:55:58Z gmosx $
+# $Id: server.rb 106 2004-10-25 11:31:11Z gmosx $
 
 require "drb"
 
@@ -13,16 +12,19 @@ require "n/app/session"
 
 module N; module App
 
-# = AppServerMixin
+# = ServerMixin
+#
+# Usefull application server related methods.
 #
 module ServerMixin
 
 	def initialize_app
 		if $drb_state
-			# Cluster
+			# Cluster mode: use distributed Ruby objects.
 			$lm = N::Cluster::Slm.new($drb_lm_server, "druby://:8000")
 			$sessions = DRbObject.new(nil, $drb_sessions_cluster)
 		else
+			# NoCluster mode: use standard Ruby onjects.
 			$lm = N::SafeHash.new
 			$sessions = N::App::SessionManager.new
 		end
@@ -35,7 +37,7 @@ module ServerMixin
 	
 end
 
-# = AppServer
+# = Server
 #
 # The Application Server. Handles dynamic requests in a web application.
 # Dont keepalive (or use a VERY SMALL keepalive). Typically this server
@@ -47,6 +49,8 @@ class Server < N::Server
 	def initialize(name = "AppServer")
 		super
 		initialize_app()
+		
+		$log.info "Server listening at #$srv_url"
 	end
 end
 

data/lib/n/app/session.rb

@@ -1,12 +1,8 @@
-# = Session
-#
-#--
 # code:
-# George Moschovitis  <gm@navel.gr>
+# * George Moschovitis  <gm@navel.gr>
 #
 # (c) 2002-2003 Navel, all rights reserved.
-# $Id: session.rb 84 2004-10-19 13:57:01Z gmosx $
-#++
+# $Id: session.rb 99 2004-10-22 09:50:28Z gmosx $
 
 require "md5"
 
@@ -17,7 +13,7 @@ module N; module App
 
 # = SessionManager
 #
-# This object manages Session Objects. Several utility methods
+# This object manages session objects. Several utility methods
 # are also provided.
 #
 # === WARNING:
@@ -97,7 +93,7 @@ end
 
 # = Session
 #
-# This object encapsulates a WebApplication session.
+# This object encapsulates a session.
 #
 # === Design:
 #
@@ -124,7 +120,7 @@ class Session < Hash
 	# the last touch time
 	attr_accessor :touch_time
 	
-	#
+	# Initializs the session.
 	#
 	def initialize(sid, request = nil)
 		super()
@@ -156,7 +152,7 @@ class Session < Hash
 		@user = N::AnonymousUser.instance
 	end
 	
-	#
+	# 
 	#
 	def touch
 		@touch_time = Time.now
@@ -207,7 +203,7 @@ class Session < Hash
 	
 	# Initialize sessions garbage collection.
 	#
-	# === Warning: this is not used yet!
+	# WARNING: this is not used yet!
 	#
 	def self.initialize_gc(session_manager, interval)
 		# gmosx, FIXME: store this in a variable.