utopia 1.7.1 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3390ed8d54ee8c008436db759edf55d1ed597125
-  data.tar.gz: 400382f8bd1cf1cc415f1807b41b131a66b93cc1
+  metadata.gz: 0b9d8f6593ca274e5489f7d07153aa9756ac83d6
+  data.tar.gz: a26c9e0b6c439311684563a66af2b0c8cd36e0df
 SHA512:
-  metadata.gz: 1c1c7ece8a229674da398b5e51603b9dbcde275519d7b279f442e35bc07ef40101c1b80ff75d8527f089fa7f970144c6257d177262372a9d024bcdc25902b406
-  data.tar.gz: 8095d7678c15039a31c8f2a5b04850dc32bfb45c4f96141ce85869ee80bec1283a9609f14a71f9aba6830ca3a70ac7f2e1f8daafdce933cbcec67e4fcb4870c4
+  metadata.gz: 5369e9923cbd895aeda163bb87234a3ef596afe999283e44c8520197f2043921d2cfd1450bd6fe3237ba6d92867932182079e20cd7efdb921bd2a9bc651cd0d7
+  data.tar.gz: 01b933e7c4c1d83e400ee809d474b4962739737d88908eaf67c388a7d1dc05ba6f062a5d3f40fc4076968ea30b9fee419539e63f90cc422fee79dba55aa44db8

data/.travis.yml

@@ -5,13 +5,12 @@ before_install:
   - git config --global user.email "samuel@oriontransfer.net"
   - git config --global user.name "Samuel Williams"
 rvm:
-  - 2.1.8
   - 2.2.4
   - 2.3.0
   - ruby-head
-  - rbx-2
+  - rbx
 env: COVERAGE=true BENCHMARK=true
 matrix:
   allow_failures:
-    - rvm: rbx-2
+    - rvm: rbx
     - rvm: ruby-head

data/README.md

@@ -1,14 +1,21 @@
 # ![Utopia](materials/utopia.png?raw=true)
 
-Utopia is a website generation framework which provides a robust set of tools
-to build highly complex dynamic websites. It uses the filesystem heavily for
-content and provides functions for interacting with files and directories as
-structure representing the website.
+Utopia is a website generation framework which provides a robust set of tools to build highly complex dynamic websites. It uses the filesystem heavily for content and provides functions for interacting with files and directories as structure representing the website.
 
 [![Build Status](https://secure.travis-ci.org/ioquatix/utopia.svg)](http://travis-ci.org/ioquatix/utopia)
 [![Code Climate](https://codeclimate.com/github/ioquatix/utopia.svg)](https://codeclimate.com/github/ioquatix/utopia)
 [![Coverage Status](https://coveralls.io/repos/ioquatix/utopia/badge.svg)](https://coveralls.io/r/ioquatix/utopia)
 
+## Motivation
+
+The [original Utopia project](https://github.com/ioquatix/utopia-php) was written in PHP in the early 2000s. It consisted of an XML parser, a database layer and some code to assist with business logic. It was initially designed to reduce the amount of HTML required to build both content-centric websites and business apps. At the time, CSS was very poorly supported and thus a lot of the time, you'd be using quite complex `<table>`s with embedded `<img>`s to generate simple things like boxes with drop shadows, etc. Utopia provided a core concept - a node - which was essentially a small snippet of HTML, which could be composed into other nodes simply by using a named tag (similar to ColdFusion). Attributes and content were passed in, and thus you could easily build complex pages with simple semantic markup.
+
+At the time, the available frameworks were pretty basic. Utopia was a working, albeit poor, implementation of MVC and supported several commercial websites I developed at the time. I made it, partly just because I could, but also because it served a commercial purpose.
+
+Eventually one day I started using Ruby on Rails. There are aspects of the Rails framework which I like. However, at the time I was using it (starting with version 0.8), I found that it's flat organisation of controllers and views very limiting. Nested controllers and views make it easier to manage complexity in a web application. Utopia embraces this principle, and applies it to both the controller and view layers. I also developed a [model layer with similar principles](https://github.com/ioquatix/relaxo-model).
+
+So, Utopia exists because it suits my way of thinking about web applications, and it's conceptual core has been refined for over a decade. It provides a considered amount of both flexibility, and opinionated behavior.
+
 ## Installation
 
 ### Local Setup
@@ -19,9 +26,10 @@ Install utopia:
 
 Create a new site:
 
-	$ utopia create www.example.com
+	$ mkdir www.example.com
 	$ cd www.example.com
-	$ rake server
+	$ utopia site create
+	$ rake
 
 #### Bower Integration
 
@@ -44,13 +52,17 @@ Firstly log into your remote site using `ssh` and install utopia:
 
 Then use the utopia command to generate a new remote site:
 
-	$ sudo -u http utopia server:create /srv/http/www.example.com
+	$ mkdir /srv/http/www.example.com
+	$ cd /srv/http/www.example.com
+	$ sudo -u http utopia server create
 
 On the local site, you can set up a git remote:
 
 	$ git remote add production ssh://remote/srv/http/www.example.com
 	$ git push --set-upstream production master
 
+When you push to the remote site, `rake deploy` will be run after the code is updated, finally, `rake restart` will be run which ideally should restart the application server.
+
 ### Passenger+Nginx Setup
 
 Utopia works well with Passenger+Nginx. Installing Passenger+Nginx is easy:
@@ -101,31 +113,150 @@ Utopia builds on top of Rack with the following middleware:
 - `Utopia::Localization`: Non-intrusive localization of resources.
 - `Utopia::Controller`: Dynamic behaviour with recursive execution.
 - `Utopia::Content`: XML-style template engine with powerful tag behaviours.
-- `Utopia::Session::EncryptedCookie`: Session storage using an encrypted cookie.
+- `Utopia::Session`: Session storage using an encrypted cookie.
+
+The implementation of Utopia is considered thread-safe and reentrant. However, this does not guarantee that the code YOU write will be so.
 
 ### Static
 
-This middleware serves static files using the `mime-types` library. By default, it works with `Rack::Sendfile` and `Rack::Cache` and supports `ETag` based caching.
+This middleware serves static files using the `mime-types` library. By default, it works with `Rack::Sendfile` and supports `ETag` based caching. Normally, you'd prefer to put static files into `public/_static` but it's also acceptable to put static content into `pages/` if it makes sense.
+
+	use Utopia::Static,
+		# The root path to serve files from:
+		root: "path/to/root",
+		# The mime-types to recognize/serve:
+		types: [:default, :xiph],
+		# Cache-Control header for files:
+		cache_control: 'public, max-age=7200'
 
 ### Redirection
 
 A set of flexible URI rewriting middleware which includes support for string mappings, regular expressions and status codes (e.g. 404 errors).
 
+	# String (fast hash lookup) rewriting:
+	use Utopia::Redirection::Rewrite,
+		'/' => '/welcome/index'
+
+	# Redirect directories (e.g. /) to an index file (e.g. /index):
+	use Utopia::Redirection::DirectoryIndex,
+		index: 'index.html'
+	
+	# Redirect (error) status codes to actual pages:
+	use Utopia::Redirection::Errors,
+		404 => '/errors/file-not-found'
+
 ### Localization
 
 The localization middleware uses the `Accept-Language` header to guess the preferred locale out of the given options. If a request path maps to a resource, that resource is returned. Otherwise, a localized request is made.
 
+	use Utopia::Localization,
+		:default_locale => 'en',
+		:locales => ['en', 'de', 'ja', 'zh'],
+		:nonlocalized => ['/_static/', '/_cache/']
+
+Somewhere further down the chain, you can localize a resource:
+
+	localization = Utopia::Localization[request]
+	show_welcome(localization.current_locale)
+
 ### Controller
 
-A simple recursive controller layer which works in isolation from the view rendering middleware. A controller consists of a set of actions which match against incoming paths and execute code accordingly.
+A simple recursive controller layer which works in isolation from the view rendering middleware.
+
+	use Utopia::Controller,
+		# The root directory where `controller.rb` files can be found.
+		root: 'path/to/root',
+		# The base class to use for all controllers:
+		base: Utopia::Controller::Base
+		# Whether or not to cache controller classes:
+		cache_controllers: (RACK_ENV == :production),
+
+A controller is a file within the root directory (or subdirectory) with the name `controller.rb`. This code is dynamically loaded into an anonymous class and executed. The default controller has only a single function:
+
+	def passthrough(request, path)
+		# Call one of:
+		
+		# This will cause the middleware to generate a response.
+		# def respond!(response)
+
+		# This will cause the controller to skip the request.
+		# def ignore!
+
+		# Request relative redirect. Respond with a redirect to the given target.
+		# def redirect! (target, status = 302)
+		
+		# Controller relative redirect.
+		# def goto!(target, status = 302)
+		
+		# Respond with an error which indiciates some kind of failure.
+		# def fail!(error = 400, message = nil)
+		
+		# Succeed the request and immediately respond.
+		# def succeed!(status: 200, headers: {}, **options)
+		# options may include content: string or body: Enumerable (as per Rack specifications
+	end
+
+The controller layer can do more complex operations by prepending modules into it.
+
+	prepend Rewrite, Actions
+
+	# Extracts an Integer
+	rewrite.extract_prefix id: Integer do
+		@user = User.find_by_id(@id)
+	end
+
+	before do |request, path|
+		# Always executed, before any controller specific actions are performed.
+	end
+
+	on 'edit' do |request, path|
+		if request.post?
+			@user.update_attributes(request[:user])
+		end
+	end
+	
+	otherwise do |request, path|
+		# Executed if no specific named actions were executed.
+	end
+	
+	after do |request, path|
+		# Always executed, after all other controller actions are performed.
+	end
 
 ### Content
 
 A tag based content generation system which integrates nicely with HTML5. Supports structures which separate generic page templates from dynamically generated content in an easy and consistent way.
 
+	use Utopia::Content,
+		cache_templates: (RACK_ENV == :production),
+		tags: {
+			'deferred' => Utopia::Tags::Deferred,
+			'override' => Utopia::Tags::Override,
+			'node' => Utopia::Tags::Node,
+			'environment' => Utopia::Tags::Environment.for(RACK_ENV)
+		}
+
+A basic template `create.xnode` looks something like:
+
+	<page>
+		<heading>Create User</heading>
+		<form action="#">
+			<input name="name" />
+			<input type="submit" />
+		</form>
+	</page>
+
+This template would typically be designed with supporting `_page.xnode` and `_heading.xnode` in the same directory or, more typically, somewhere further up the directory hierarchy.
+
 ### Session
 
-The encrypted cookie session management uses symmetric private key encryption to store data on the client and avoid tampering.
+The session management uses symmetric private key encryption to store data on the client and avoid tampering.
+
+	use Utopia::Session,
+		:expire_after => 3600,
+		:secret => '40 or more random characters for your secret key'
+
+All session data is stored on the client, but it's encrypted with a salt and the secret key. It would be hard for the client to decrypt the data without the secret.
 
 ## Contributing
 

data/benchmarks/string_vs_symbol.rb

@@ -0,0 +1,12 @@
+require 'benchmark/ips'
+
+STRING_HASH = { "foo" => "bar" }
+SYMBOL_HASH = { :foo => "bar"  }
+
+Benchmark.ips do |x|
+	x.report("string") { STRING_HASH["foo"] }
+	x.report("symbol") { SYMBOL_HASH[:foo]  }
+	x.report("symbol-from-string") { SYMBOL_HASH["foo".to_sym]  }
+	
+	x.compare!
+end

data/lib/utopia/command.rb

@@ -34,11 +34,10 @@ module Utopia
 			module Site
 				CONFIGURATION_FILES = ['config.ru', 'config/environment.rb', 'Gemfile', 'Rakefile', 'tasks/utopia.rake']
 				
-				DIRECTORIES = ["config", "lib", "pages", "public", "tasks", "tmp"]
-				SYMLINKS = {"public/_static" => "../pages/_static"}
+				DIRECTORIES = ["config", "lib", "pages", "public", "tasks"]
 				
 				# Removed during upgrade process
-				OLD_DIRECTORIES = ["access_log", "cache"]
+				OLD_DIRECTORIES = ["access_log", "cache", "tmp"]
 				
 				ROOT = File.join(BASE, 'site')
 			end
@@ -56,7 +55,6 @@ module Utopia
 					destination_root = parent.root
 					
 					FileUtils.mkdir_p File.join(destination_root, "public")
-					FileUtils.mkdir_p File.join(destination_root, "tmp")
 					
 					Dir.chdir(destination_root) do
 						# Shared allows multiple users to access the site with the same group:
@@ -65,6 +63,7 @@ module Utopia
 						system("git", "config", "core.worktree", destination_root)
 						
 						system("cp", "-r", File.join(Setup::Server::ROOT, 'git', 'hooks'), File.join(destination_root, '.git'))
+						system("cp", "-r", File.join(Setup::Server::ROOT, 'config'), File.join(destination_root))
 					end
 					
 					hostname = `hostname`.chomp
@@ -110,10 +109,6 @@ module Utopia
 						end
 					end
 					
-					Setup::Site::SYMLINKS.each do |path, target|
-						FileUtils.ln_s(target, File.join(destination_root, path), force: true)
-					end
-					
 					Setup::Site::CONFIGURATION_FILES.each do |configuration_file|
 						destination_path = File.join(destination_root, configuration_file)
 						
@@ -160,6 +155,16 @@ module Utopia
 			class Update < Samovar::Command
 				self.description = "Upgrade an existing site to use the latest configuration files from the template."
 				
+				def move_static!
+					if File.lstat("public/_static").symlink?
+						FileUtils.rm_f "public/_static"
+					end
+					
+					if File.directory?("pages/_static") and !File.exist?("public/_static")
+						system("git", "mv", "pages/_static", "public/_static")
+					end
+				end
+				
 				def invoke(parent)
 					destination_root = parent.root
 					branch_name = "utopia-upgrade-#{Utopia::VERSION}"
@@ -180,10 +185,6 @@ module Utopia
 						FileUtils.rm_rf(path)
 					end
 					
-					Setup::Site::SYMLINKS.each do |path, target|
-						FileUtils.ln_s(target, File.join(destination_root, path), force: true)
-					end
-					
 					Setup::Site::CONFIGURATION_FILES.each do |configuration_file|
 						source_path = File.join(Setup::Site::ROOT, configuration_file)
 						destination_path = File.join(destination_root, configuration_file)
@@ -201,7 +202,9 @@ module Utopia
 							system("git", "add", "-u")
 							
 							# Stage any new files that we have explicitly added:
-							system("git", "add", *Setup::Site::CONFIGURATION_FILES, *Setup::Site::SYMLINKS.keys)
+							system("git", "add", *Setup::Site::CONFIGURATION_FILES)
+							
+							move_static!
 							
 							# Commit all changes:
 							system("git", "commit", "-m", "Upgrade to utopia #{Utopia::VERSION}.")

data/lib/utopia/content.rb

@@ -145,13 +145,9 @@ module Utopia
 			locale = env[Localization::CURRENT_LOCALE_KEY]
 			if link = Links.for(@root, path, locale)
 				if link.path and node = lookup_node(link.path)
-					response = Rack::Response.new
-					
 					attributes = request.env.fetch(VARIABLES_KEY, {}).to_hash
 					
-					node.process!(request, response, attributes)
-					
-					return response.finish
+					return node.process!(request, attributes)
 				elsif redirect_uri = link[:uri]
 					return [307, {HTTP::LOCATION => redirect_uri}, []]
 				end

data/lib/utopia/content/node.rb

@@ -107,18 +107,23 @@ module Utopia
 			end
 
 			def call(transaction, state)
+				# Load the template:
 				template = @controller.fetch_template(@file_path)
 				
+				# Evaluate the template/code:
 				context = Context.new(transaction, state)
 				markup = template.to_buffer(context)
 				
+				# Render the resulting markup into the transaction:
 				transaction.parse_markup(markup)
 			end
 
-			def process!(request, response, attributes = {})
-				transaction = Transaction.new(request, response)
+			def process!(request, attributes = {})
+				transaction = Transaction.new(request)
+				
 				output = transaction.render_node(self, attributes)
-				response.write(output)
+				
+				return [200, transaction.headers, [output]]
 			end
 		end
 		
@@ -149,7 +154,7 @@ module Utopia
 			end
 			
 			def response
-				transaction.response
+				transaction
 			end
 			
 			def attributes

data/lib/utopia/{extensions/rack.rb → content/response.rb}

@@ -18,39 +18,42 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-require 'rack'
-
-module Rack
-	# Compatibility with older versions of rack:
-	EXPIRES = 'Expires'.freeze unless defined? EXPIRES
-	HTTP_HOST = 'HTTP_HOST'.freeze unless defined? HTTP_HOST
-	
-	class Response
-		# Specifies that the content shouldn't be cached. Overrides `cache!` if already called.
-		def do_not_cache!
-			headers[CACHE_CONTROL] = "no-cache, must-revalidate"
-			headers[EXPIRES] = Time.now.httpdate
-		end
+module Utopia
+	class Content
+		# Compatibility with older versions of rack:
+		EXPIRES = 'Expires'.freeze
+		CACHE_CONTROL = 'Cache-Control'.freeze
+		CONTENT_TYPE = 'Content-Type'.freeze
+		
+		class Response
+			def initialize
+				@status = 200
+				@headers = {}
+			end
+			
+			attr :status
+			attr :headers
+			
+			# Specifies that the content shouldn't be cached. Overrides `cache!` if already called.
+			def do_not_cache!
+				@headers[CACHE_CONTROL] = "no-cache, must-revalidate"
+				@headers[EXPIRES] = Time.now.httpdate
+			end
 
-		# Specify that the content should be cached.
-		def cache!(duration = 3600, access = "public")
-			unless headers[CACHE_CONTROL] =~ /no-cache/
-				headers[CACHE_CONTROL] = "#{access}, max-age=#{duration}"
-				headers[EXPIRES] = (Time.now + duration).httpdate
+			# Specify that the content should be cached.
+			def cache!(duration = 3600, access: "public")
+				unless @headers[CACHE_CONTROL] =~ /no-cache/
+					@headers[CACHE_CONTROL] = "#{access}, max-age=#{duration}"
+					@headers[EXPIRES] = (Time.now + duration).httpdate
+				end
 			end
-		end
 
-		# Specify the content type of the response data.
-		def content_type!(value)
-			self.content_type = value
-		end
-		
-		def content_type= value
-			headers[CONTENT_TYPE] = value
-		end
-		
-		def content_type
-			headers[CONTENT_TYPE]
+			# Specify the content type of the response data.
+			def content_type= value
+				@headers[CONTENT_TYPE] = value
+			end
+			
+			alias content_type! content_type=
 		end
 	end
 end