nitro 0.1.2

data/lib/n/app/filters/autologin.rb

@@ -0,0 +1,50 @@
+# = AutoLogin filter
+#
+# code:: gmosx
+#
+# (c) 2004 Navel, all rights reserved.
+# $Id: autologin.rb 79 2004-10-18 16:38:19Z gmosx $
+
+require "n/utils/string"
+require "n/server/filter"
+
+require_part "users"
+
+module N; module App
+
+# = AutoLoginFilter
+#
+# Automatically login a user with valid authentication cookie.
+# Uses some n1 code at the moment.
+#
+class AutoLoginFilter < N::ServerFilter
+
+	def process(request)
+		if request.is_top?
+			# only try to autologin for top level requests
+			# there is NO need for the older SKIP_AUTOLOGIN session flag.
+			if (request.session.user.anonymous?) and 
+					cookie = request.get_cookie($users_auth_cookie)
+					
+				username, password_crypted = cookie.split(",")
+				
+				if user = $db.get_by_name(username, N::User) and 
+						password_crypted == user.password
+					if request.session.login(request, user)
+						# user logged in
+					else
+						# stale cookie, remove it
+						request.del_cookie($users_auth_cookie)
+					end
+				else
+					$log.warn "Unknown user or wrong password in auth-cookie: #{cookie} from IP: #{request.remote_addr}"
+				end
+			end
+		end
+	
+		return @next_filter.process(request) if @next_filter
+	end
+
+end
+
+end; end # module

data/lib/n/app/fragment.rb

@@ -0,0 +1,67 @@
+# = Fragment
+#
+# A Fragment is the output of a rendered script. Additional metadata 
+# such as lastmodified and expire times are stored to facilitate 
+# fragment processing (for example caching).
+#
+# === Design:
+#
+# Fragments are cached in the filesystem to allow for a cluster of
+# server to access them. Benefits over the older memory cache scheme:
+#
+# - each fragment is processed once by one server
+# - easier visualisation of the fragments.
+# - can clear the cache for all server
+# - can selectively invalidate one fragment!
+# - 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
+
+	# precompiled flags for fragment key "customization"
+
+	ADMIN_FLAG = "-a"
+	OWNER_FLAG = "-o"
+	EDITOR_FLAG = "-e"
+	VIEWER_FLAG = "-f"
+	MY_FLAG = "-m"
+	ANONYMOUS_FLAG = "-n"
+
+	attr_accessor :body, :lm
+	
+	# another method for invalidation, allows for more flexible
+	# invalidation strategies. also used by the legacy autoinvalidate
+	# code.
+	attr_accessor :expires
+
+	def initialize(body = "", lm = Time.now)
+		@body = body
+		@lm = lm
+	end
+
+	def expires_after!(ea = (60*60*24))
+		@expires = @lm + ea
+	end
+
+	def expired?
+		return true if @expires.nil? || (Time.now > @expires)
+	end
+
+	def to_str
+		return @body
+	end	
+end
+
+end; end # module

data/lib/n/app/handlers.rb

@@ -0,0 +1,120 @@
+# = Handlers
+#
+# code: gmosx
+#
+# (c) 2002-2003 Navel, all rights reserved.
+# $Id: handlers.rb 71 2004-10-18 10:50:22Z gmosx $
+
+require "n/utils/cache"
+require "n/server/filter"
+
+module N; module App
+
+# = App server handlers handle requests to specific resources.
+#
+# === 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.
+#
+class Handler < N::ServerFilter
+	def process(request)
+		# nop
+		
+		# walk the filter pipeline		
+		@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
+
+class HandlerError < StandardError; end
+
+# = Script Handler
+#
+# Base handler for scripts.
+
+class ScriptHandler < Handler
+
+	# cache the compiled page scripts to optimize future references.
+	# use a thread safe cache.
+	@@compiled_script_cache = N::SafeHash.new()
+
+	# dont allow 2 threads to compile the same script. In fact dont allow
+	# two threads to compile in parallel.
+	@@compile_sync = Sync.new
+
+	# Overload the path.
+	# FIXME: better name and much better documentation.
+	#
+	def	overload_path(path)
+		path.gsub!(/\/\//, '/')
+		
+		if ::File.exists?("#$root_dir/#{path}")
+			return path
+		else
+			$log.debug "OVERLOAD: '#{path}' -> 'p/#{path}'" if $DBG
+			return "p/#{path}"
+		end		
+	end
+	
+	# the compiler returns a singleton class customized for rendering the
+	# input script. The original idea was to define render() as a static 
+	# method and return the class, but we will use a singleton object to 
+	# keep custom data structures (sub-page-graph, metrics, etc)
+	#
+	# script_path is used as key in the Dynamic class creation and for 
+	# caching
+	#
+	# === Design:
+	# we use __ for out too to avoid nasty collisions.
+	#
+	def compile_script(script)
+		compiled_script = nil
+		
+		# dont allow 2 threads to compile the same script. In fact dont 
+		# allow two threads to compile in parallel.
+		# gmosx: SOS this eval assigns the variable compiled_script!
+		@@compile_sync.synchronize {
+			eval(script)
+		}
+			
+		return compiled_script		
+	end
+	
+	def compiled_script_cache
+		return @@compiled_script_cache
+	end
+
+	# Log a rendering error
+	#
+	def log_error(request, ex)
+		request.log_error "--------"
+		request.log_error "#{request.path}:"
+		request.log_error "#{ex.class}: #{ex}"
+		request.log_error ex.backtrace()
+		raise ScriptHandlerError.new(0, "error")
+	end
+
+end
+
+# Handler Error.
+# raise this if an error happens when handling a request
+
+class ScriptHandlerError < HandlerError
+	attr_reader :error_line
+
+	def initialize(error_line, message = nil)
+		@error_line, @message = error_line, message
+	end
+	
+end
+
+end; end # module

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

@@ -0,0 +1,184 @@
+# = Code handler (.sx scripts)
+#
+# code: 
+# George Moschovitis  <gm@navel.gr>
+#
+# (c) 2004 Navel, all rights reserved.
+# $Id: code-handler.rb 71 2004-10-18 10:50:22Z gmosx $
+
+require "cgi"
+require "singleton"
+require "sync"
+
+require "n/utils/cache"
+require "n/utils/uri"
+require "n/app/script"
+require "n/app/fragment"
+require "n/app/handlers"
+
+module N; module App
+
+# = CodeHandler
+#
+# web server handler that executes ruby code (logic)
+# Caching is NOT SUPPORTED (and not needed anyway)
+#
+# TODO:
+#
+# probably extend PageHandler from CodeHandler and not vice versa.
+#
+class CodeHandler < ScriptHandler
+
+	# process is called ONLY for top level scripts.
+	# 
+	# no need for synchronization, the page-script is thread safe.
+	# if you use thread-unsafe code in your script you are responsible
+	# for synchronization.
+	#
+	# TODO:
+	# add timing code here
+	#
+	def process(request)	
+		# gmosx, FIXME: temporarily here, move somewhere ELSE!
+
+		request.locale = $lc_map[request.user.locale] || $lc_en
+		script = get_compiled_script(request.path)		
+		fragment = eval_script(script, request)
+		
+		# walk the filter pipeline
+		super
+
+		return fragment, script
+	end
+
+	# evaluate the request script in the context of the current request.
+	# returns the output of the script, ie the fragment body.
+	#
+	# === Design:
+	#
+	# I think that the script caching logic should be here, because it nicelly
+	# encapsulates transform and compile.
+	#
+	def eval_script(script, request)
+	
+		$log.debug "Evaluating, #{request.path}" if $DBG
+
+		fragment = Fragment.new(:key)
+		
+		# try to render the script, report errors.
+		begin
+			fragment.body = script.__render(request)
+		rescue N::ScriptExitException => see
+			# the script raised a ScripteExitException to force a premature
+			# end. Surpress this error!
+		rescue => ex
+			log_error(request, ex)
+		end
+
+		return fragment
+	end
+
+	# === Output:
+	# defcode: the code that customizes the base script class.
+	# pagecode: the code that renders the fragment.
+	#
+	# === REMARKS:
+	# - this method is evaluated in compile time, so we cannot pass
+	#   or use the request/request pair. gmosx: NO, we do pass request, 
+	#   some data can and SHOULD be used to prepare the transform.
+	#
+	def transform_script(path, hash, shader = nil)
+
+		path = overload_path(path)
+
+		# load the page text from the script
+		pagecode = ""
+
+		pagecode = File.read("#$root_dir/#{path}")
+
+		# convert to ruby code
+		pagecode.gsub!(/<<</, "__out << %{")
+		pagecode.gsub!(/>>>/, "}")
+
+		script = %{
+			class CodeScript_#{hash} < CodeScript
+				def initialize(path)
+					super
+@pagecode = <<-'PAGECODE'
+#{pagecode}
+PAGECODE
+@defcode = nil
+				end
+				def __render(request)
+					__out = ""
+					lc = request.locale
+					#{pagecode}
+					return __out
+				end
+			end
+			return CodeScript_#{hash}.new("#{path}")
+		}
+
+		return script
+	end
+
+	# try to get the script from the cache. invalidates the compiled version and return nil
+	# if the script is modified since compile time. Also takes active shader and localization
+	# into account. If script is not compiled, transform and compile it.
+	#
+	# Output:
+	# the compiled script. Throws exception if the script does not exist.
+	#
+	def get_compiled_script(path, hash = nil)
+		compiled_script = nil
+		key = calc_script_key(path, hash)
+	
+		# gmosx: $reload_scripts is typically set to true when debugging
+		# statically included files (.ss)
+		unless $reload_scripts
+		
+			compiled_script = @@compiled_script_cache[key]
+	
+			# gmosx: monitor scripts should be explicit!
+			if $srv_monitor_scripts and compiled_script and (File.mtime(compiled_script.path) > compiled_script.__create_time)
+				$log.debug "Script '#{path}' externaly modified, recompiling" if $DBG
+				compiled_script = nil
+			end
+			
+		end
+
+		unless compiled_script
+			# the script is not cached, so load, transform and compile it!
+			$log.debug "Compiling script '#{key}'" if $DBG
+
+			script = transform_script(path, key)
+			compiled_script = compile_script(script)
+			
+			@@compiled_script_cache[key] = compiled_script
+		end
+		
+		return compiled_script
+	end
+	
+	def calc_script_key(path, hash)
+		return "#{path}#{hash}".gsub(/[^\w]/, "")
+	end
+
+end # CodeHandler
+
+# = Codescript
+#
+# encapsulates the script defining Ruby Code to execute.
+# effectively acts as a Generator.
+#
+# === Requirements:
+#
+# - the generated class should be a singleton, no need to stress
+#	the garbage collector.
+# - the render method should be thread safe.
+#
+class CodeScript < Script
+		
+end # CodeScript
+
+end; end # module

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

@@ -0,0 +1,612 @@
+# = XML Page handler (.sx scripts)
+#
+# code:
+# 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 $
+
+require "cgi"
+require "singleton"
+require "sync"
+
+require "n/utils/cache"
+require "n/utils/uri"
+require "n/app/script"
+require "n/app/fragment"
+require "n/app/handlers"
+
+module N; module App
+
+# = PageHandler
+#
+# web server handler that render xml pages (.sx scripts).
+# This is the main handler of the Nitro Application Server.
+#
+# The handler evaluates the given script. The result of
+# this evaluation is called a Fragment. The result of a top
+# level script, ie a top level fragments is called a page.
+#
+# == Advantages over the original .rx format:
+#
+# - xml based
+# - strips <!-- comments
+# - allows multiline comments
+# - allows pre-transformation with xlst (free transformation)
+# - allows validation of xhtml
+# - allows syntax highlighting
+#
+# == TODO:
+#
+# - move shader selection in a script method, that can
+#   be overriden (user specific shaders).
+# - compress the output some more, every byte
+#		counts (bandwidth == money)
+# - use something like FormValidator to validate parameters
+#		for sub-fragments.
+#
+# === FIXME:
+# - correct encoding of fragment hash
+# (query string, shader, user etc)
+#
+# === Design:
+#
+# break the rendering process in sub methods to make testable
+# and verifiable (and easier to read).
+#
+# Statically included scripts (.ss) SHOULD be valid xml files (even 
+# though they are not required) to be automatically verifiable and 
+# compatible with editors. The xml prologue (<?xml / <root>) is removed.
+#
+# Be carefull about statically included files scope issues. This is the
+# reason why we do not use statically included files everywhere.
+#
+# === WARNING:
+#
+# no need to lock cache io, we use a safe cache!
+#
+class PageHandler < ScriptHandler
+
+	# process is called ONLY for top level scripts.
+	# 
+	# no need for synchronization, the page-script is thread safe.
+	# if you use thread-unsafe code in your script you are responsible
+	# for synchronization.
+	#
+	# TODO:
+	# add timing code here
+	#
+	def process(request)	
+		# gmosx, FIXME: temporarily here, move somewhere ELSE!
+
+		request.locale = $lc_map[request.user.locale] || $lc_en
+		request.shader = calc_shader(request)
+		request.tag = calc_tag(request)
+		request.top_script = script = get_compiled_script(request.path, request.tag, request.shader)
+		
+		# Action requests should be uncacheable, to be safe.
+		# No need for a check here! all actions should use consume which
+		# sets the uncacheable flag.
+		#
+		# request.uncacheable = true if request.delete("*act*")
+		# request.uncacheable = true if request.query_string =~ /\$.*\$/
+		
+		script.__init_render(request)
+		
+		# dont cache admin pages, FIXME: use less checks here!! 
+		
+		if script.__cache?(request) and (not request.uncacheable) and 
+				(not request.session["ADMIN_MODE"]) and (not $reload_scripts)
+			if etag = script.__etag(request)
+				request.headers["cache-control"] = "pubic, must-revalidate"
+				request.headers["etag"] = etag
+			end
+		else
+			# gmosx, FIXME: add the correct cache control header here!!
+			etag = nil
+		end
+
+		if etag && etag == request.headers["IF-NONE-MATCH"]
+			request.set_not_modified!
+		else
+			fragment = eval_script(script, request)
+		end
+
+		# walk the filter pipeline
+		super
+		
+		return fragment, script
+	end
+
+	# Process sub level scripts.
+	#	
+	def sub_process(request)
+		script = get_compiled_script(request.path, request.tag, request.shader)
+		script.__init_render(request)
+		fragment = eval_script(script, request)
+		
+		return fragment, script
+	end
+
+	# evaluate the request script in the context of the current request.
+	# returns the output of the script, ie the fragment body.
+	#
+	# === Design:
+	#
+	# I think that the script caching logic should be here, because it nicelly
+	# encapsulates transform and compile.
+	#
+	def eval_script(script, request)
+	
+		etag = script.__etag(request)
+
+		unless fragment = script.__cache_get(etag)
+
+			# no suitable fragment exists in the cache, so render the script.
+			$log.debug "Rendering, #{request.path}" if $DBG
+
+			fragment = Fragment.new
+			
+			# try to render the script, report errors.
+			begin
+				fragment.body = script.__render(request)
+
+				if script.__cache?(request)
+					script.__cache_put(etag, fragment) unless request.uncacheable
+				end
+			rescue N::ScriptExitException => see
+				# the script raised a ScripteExitException to force a premature
+				# end. Surpress this error!
+			rescue => ex
+				log_error(request, ex)
+			end
+
+		end
+		
+		return fragment
+	end
+
+	# === Output:
+	# defcode: the code that customizes the base script class.
+	# pagecode: the code that renders the fragment.
+	#
+	# === TODO:
+	# - we have to keep the original script code to apply multiple shaders
+	#
+	# === REMARKS:
+	# - this method is evaluated in compile time, so we cannot pass
+	#   or use the request/request pair. gmosx: NO, we do pass request, 
+	#   some data can and SHOULD be used to prepare the transform.
+	#
+	def transform_script(path, hash, shader = nil)
+	
+		path = overload_path(path)
+		
+		initcode = ""
+		defcode = ""
+		sub_scripts = []
+		filename = "#$root_dir/#{path}"
+		cached_filename = ".cache/#{shader}#{path}.rb"
+
+		# load the page text from the script.
+		# check if a cached transformed script exists.
+		# also staticaly includes all <?include xxx ?> files.
+		# this also validates the xhtml (cool side-effect).
+		begin
+			document = ::File.read(filename)
+
+			# calculate mtime
+			mtime = ::File.stat(filename).mtime		
+			document.scan(/<\?include xl:href="(.*?)"(.*)\?>/) { |match|
+				match = overload_path(match[0])
+				imtime = ::File.stat("#$root_dir/#{match}").mtime
+				mtime = imtime if imtime > mtime
+			}
+			# also check the shader mtime
+			# FIXME: even better should check mtime now!
+			mtime = shader.mtime if shader.mtime > mtime
+		
+			# calculate subscripts
+			document.scan(/<x:include xl:href="(.*?)"(.*)>/) { |match|
+				match = overload_path(match[0])				
+				sub_path = "#{match.split("?")[0]}"
+				sub_scripts << get_compiled_script(sub_path, hash, shader)
+			}
+
+			# check if a cached transformed script exists
+			# FIXME: encode shader and shader mtime.
+			if false # ::File.exists?(cached_filename) and ::File.stat(cached_filename).mtime > mtime
+				return ::File.read(cached_filename), sub_scripts
+			end
+
+			$log.debug "Transforming '#{path}'" if $DBG
+			
+			# static includes
+			# the target file is included at compile time.
+			#
+			# gmosx: must be xformed before the <?r pi.
+			# ex:		
+			# <?include xl:href="root/myfile.sx" ?>
+			#
+			document.gsub!(/<\?include xl:href="(.*?)"(.*)\?>/) { |match|
+				# gmosx: xmm match matches the whole string.
+				match = overload_path($1)				
+				load_statically_included("#$root_dir/#{match}")
+			}
+
+			# dynamic includes
+			# the target file is included at run time
+			#
+			document.gsub!(/<x:include xl:href="(.*?)"(.*)(.?)\/>/) { |match|
+				"<?r __out << __include('#$1', request) ?>"
+			}
+			
+			# expand method macro 
+			#
+			document.gsub!(/\@\?(.*?)(['|"|\s])/, '#{_a(request, %^\1^)}\2')
+
+			# localisation 
+			# gmosx, OPTIMIZE in the future i could pre translate the strings!
+			document.gsub!(/\|:(.*?)\|/, '#{lc[:\1]}')
+			document.gsub!(/\!:(.*?)\|(.*?)\!/, '#{lc[:\1].call(\2)}')
+
+			# extract the definition code. The <?def .. ?> will
+			# be ignored afterwards.
+			#
+			document.scan(/<\?def(.*?)\?>/m) { |match|
+				defcode << $1 << "\n"
+			}
+			
+			# extract the initialization phase code. The <?i .. ?> will
+			# be ignored afterwards.
+			#
+			document.scan(/<\?i(.*?)\?>/m) { |match|
+				initcode << $1 << "\n"
+			}
+			
+		rescue Exception, StandardError => e
+			$log.error pp_exception(e)
+			raise RuntimeError.new
+		end
+
+		# pre-transform the script.
+		pagecode = shader.transform(document)
+
+		# preprocess the script to convert to valid ruby code.
+
+		# strip the xml header! (interracts with the following gsub!)
+		# FIXME: perhaps the xslt could strip this?
+		pagecode.gsub!(/<\?xml.*\?>/, "")
+
+		# xform the processing instructions
+		pagecode.gsub!(/\?>/, "\n__out << %{")
+		pagecode.gsub!(/<\?ruby /, "}\n")
+		pagecode.gsub!(/<\?r /, "}\n")
+		
+		# tml, TODO: resolve static injects! scan injects and update the metadata
+		# in the page-graph.
+
+		pagecode = %@__out << %{#{pagecode}}@
+
+		# gmosx: unescape quotes etc, that are escaped by the xslt processor.
+		# can we avoid this ???
+		# yes: the xslt processors escapes code in #{ } brackets, we should
+		# use <?= ?> brackets.
+		#
+		# The new version of render supports output buffering ala php.
+		# __out_buffers keeps a stack of buffers.
+		
+		pagecode = CGI.unescapeHTML(pagecode)
+		key = calc_script_key(path, hash)
+		
+		script = %{
+			class PageScript#{key} < PageScript
+				def initialize(path)
+					super
+					@key = "#{key}"
+				end
+				#{defcode}
+				def __init_render(request)
+				#{initcode}
+				end
+				def __render(request)
+					lc = request.locale
+					
+					__out_buffers = nil
+					
+					__out = ""					
+					if request.is_top?
+						__out = %|<?xml version="1.0"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">|
+					end
+					
+					#{pagecode}
+					return __out
+				end
+			end			
+			compiled_script = PageScript#{key}.new("#{path}")
+		}
+		
+		# remove excessive white space
+		# gmosx: FIXME: i can do better here: remove leading space per
+		# line for example.
+		script.squeeze!(" \t")
+
+		# cache the transformed script.
+		#
+		dir = N::StringUtils.directory_from_path(cached_filename)
+		FileUtils.mkdir_p(dir)		
+		File.open(cached_filename, "w") { |f|
+			f << script	
+		}	
+
+		return script, sub_scripts		
+	end
+
+	# try to get the script from the cache. invalidates the compiled version and return nil
+	# if the script is modified since compile time. Also takes active shader and localization
+	# into account. If script is not compiled, transform and compile it.
+	#
+	# Output:
+	# the compiled script. Throws exception if the script does not exist.
+	#
+	def get_compiled_script(path, hash, shader)
+		compiled_script = nil
+		key = calc_script_key(path, hash)
+	
+		# gmosx: $reload_scripts is typically set to true when debugging
+		# statically included files (.ss)
+		unless $reload_scripts
+		
+			compiled_script = @@compiled_script_cache[key]
+	
+			# gmosx: monitor scripts should be explicit!
+			if $srv_monitor_scripts and compiled_script and (File.mtime(compiled_script.path) > compiled_script.__create_time)
+				$log.debug "Script '#{path}' externaly modified, recompiling" if $DBG
+				compiled_script = nil
+			end
+			
+		end
+
+		unless compiled_script
+			# the script is not cached, so load, transform and compile it!
+			$log.debug "Compiling script '#{key}'" if $DBG
+
+			script, sub_scripts = transform_script(path, hash, shader)
+			compiled_script = compile_script(script)
+			compiled_script.sub_scripts = sub_scripts unless sub_scripts.empty?
+			
+			@@compiled_script_cache[key] = compiled_script
+		end
+		
+		return compiled_script
+	end
+
+	#-----------------------------------------------------------------------------
+	# Hooks
+
+	# Calculate shader for this request.
+	#
+	# TODO: allow per include shader!
+	#
+	def calc_shader(request)
+		return $default_shader		
+		# return $shaders[request.user.shader]
+	end
+
+	# Standard encoding/modification/customization of the fragment_hash.
+	# Override this in your application to provide customized encoding.
+	# For example encode the shader id.
+	#
+	def calc_tag(request)
+		return "#{request.locale[:locale]}#{request.shader.name}"
+	end
+
+	def calc_script_key(path, hash)
+		return "#{path}#{hash}".gsub(/[^\w]/, "")
+	end
+	
+	#-----------------------------------------------------------------------------
+	# Utils
+	
+	# loads a script and prepares it for statically inclusion by removing
+	# the optional xml prologue/epilogue. 
+	#
+	def load_statically_included(filename)
+		$log.debug "Statically including '#{filename}'" if $DBG
+		
+		code = File.read(filename)
+		code.gsub!(/<\?xml.*\?>/, "")
+		code.gsub!(/<\/?root(.*?)>/m, " ");
+		
+		return code
+	end
+
+end # PageHandler
+
+# = Pagescript
+#
+# encapsulates the script defining a specific xml page.
+# effectively acts as a Generator.
+#
+# === Requirements:
+#
+# - the generated class should be a singleton, no need to stress
+#	the garbage collector.
+# - the render method should be thread safe.
+#
+# == Design:
+#
+# - only pass request and request for simplicity
+#   __session can be deducted from request, and __user/__errors from
+#	__session.
+#
+# === Injection:
+#
+# Injection is the inclusion of subscripts in a super (parent) script.
+# There are two types of inclusion, dynamic and static. In contrary to what
+# you may believe, dynamix inclusion IS needed in cases where you decide
+# what tou include at runtime. A synthesized "my" page is a good example.
+# However, n1 overused dynamic inclusion. In most cases static inclusion
+# works just fine. Another interesting optimization is when you dynamically
+# include but not recursivelly. The full, recursive and dynamic include is
+# really seldomly needed. However in our implementation there is no difference
+# between inject_once / inject_recursive.
+#
+# === Class generation example:
+#
+# WARNING: the example may be deprecated!
+#
+# source script:
+#
+# <?xml version='1.0'?>
+# <?ruby
+#	a = 5
+# 	b = request["bval"]
+# ?>
+# <html>
+#	<body>
+#		this is it a = #{a}, b = #{b} and c = #{request["cval"]}<br/>
+#		cool huh?
+#	</body>
+# </html>
+#
+# generated class:
+#
+# class PageScript__index
+# 	def render(request)
+#		out = ""
+#		a = 5
+#		b = request["bval"]
+#		__out << %{
+# 		<html>
+#			<body>
+#				this is it a = #{a}, b = #{b} and c = #{request["cval"]}<br/>
+#				cool huh?
+#			</body>
+# 		</html>
+#		}
+#		return __out
+#	end
+# end
+#
+# === Future:
+#
+# - use catbuffer for optimized appends.
+#
+class PageScript < Script
+	# <x:include xl:href='...'/> implementation
+	# Dynamically include ("inject") a subpage (fragment) in this page.
+	#
+	# gmosx, SOS: This is a new version for dynamic inclusion that doesnt
+	# generate subrequest objects. For use with new (v3) code.
+	#
+	# === Design:
+	#
+	# To keep this method simple (and as a small optimization) we used
+	# to not allow a query string when including. Pass the parameters
+	# as request arguments or parameters. Here is an example:
+	#
+	# <?r request_set_arg("max_message", 5); request["admin"] = true ?>
+	# <x:include xl:href='*parts/messages/view-messages.xi'/>
+	#
+	# However to support legacy code, to follow the REST design guidelines,
+	# and because it turned out to be easy thanks to the refactoring, the
+	# query string is supported. Passing params through the request object
+	# is suggested though (and essential to pass ruby objects). The query
+	# string of the included string is converted to arguments to avoid
+	# poluting the parent request query string.
+	#
+	# Still, the preferred way is to use the args hash to pass special 
+	# arguments to included scripts.
+	# <?r request.set_arg("maxitems", 5) ?>
+	# <x:include xl:href="p/list.si" />
+	#
+	# If you want to include the parents query string for caching purposes
+	# call with parent = true!
+	#
+	# TODO: add unit test for this.
+	#
+	def __include(uri, request, parent = false)
+		begin
+			$log.devel "Including #{uri}"
+
+			# get script real path and type
+			script_path, type, args, qs = N::UriUtils.decode(uri)
+
+			# update the dependencies set, we only need the key as flag,
+			# so just insert true. Calculating the dependencies this
+			# way is simple and not too inefficient.
+			#
+			# @dependencies[script_path] = true
+
+			request.level += 1
+			request.path = script_path
+			
+			# Build the cache key for this request.
+			# attach the query string of the parent. Needed for
+			# example in fragments with pagers. Do NOT do this
+			# by default, or excessive numbers of fragments will
+			# be generated. 
+			if parent
+				request.fragment_hash = "#{qs}#{request.query_string}"
+			else
+				request.fragment_hash = qs
+			end			
+			
+			# add arguments passes through the query string.
+			request.parameters.update(args)
+
+			# TODO: select by regexp
+			# FIXME: hacky implementation, NO Need for this test, always
+			# PageHandler.
+			if handler = $srv_extension_map[type]
+				handler = handler[1]
+			else
+				$log.error "No handler for extension '#{type}'"
+				unless N::StringUtils.valid?(type)
+					$log.error "Perhaps you have a syntax error in your include statement or you didnt pass the uri"
+				end
+			end
+
+			fragment, script = handler.sub_process(request)
+
+			# restore parent request
+			request.level -= 1
+			
+			# gmosx: one idea was to clear the args here to avoid a class of bugs.
+			# But i think it is better to trust the developer to do this, thus
+			# giving him greater flexibility.
+			# gmosx: NO !!! practice shows that it is NOT GOOD to trust the
+			# developer :)
+			# Hmm clearing the args also poses problems though :(
+			#
+			# request.args.clear()
+
+			return fragment.body			
+			
+		rescue ScriptHandlerError => e
+			# allready handled!
+		rescue Exception, StandardError => e
+			# gmosx: this block is used to catch possible errors in the inject
+			# implementation if we do not catch these errors here, they
+			# propagate to the caller that prints a NON usefull message, that
+			# can waste a developers time.
+			#
+			$log.error "error in INCLUDE IMPLEMENTATION while including: #{uri}"
+			# gmosx: too noisy, only uncomment if you get the above error!!
+			$log.error pp_exception(e)
+
+			# Following our design goal of chaos reduction (ie small changes
+			# should result in small results) we drink the exception and
+			# output an error flag. So the rest of the page is rendered and
+			# the server error handler is NOT triggered.
+		end
+
+		return "(error)"
+	end
+	
+end # PageScript
+
+end; end # module