# code:
# * George Moschovitis  <gm@navel.gr>
# * Anastasios Koutoumanos  <ak@navel.gr>
#
# (c) 2004 Navel, all rights reserved.
# $Id: page-handler.rb 99 2004-10-22 09:50:28Z 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