wee 0.1.0 → 0.3.1

data/INSTALL

@@ -0,0 +1,7 @@
+= Installation
+
+1. Download and Install RubyGems: http://rubygems.rubyforge.org
+
+2. Install Wee: <tt>gem install wee</tt>
+
+3. Set environment variable (required to load RubyGems): <tt>export RUBYOPT=-rubygems</tt>

data/README

@@ -0,0 +1,268 @@
+= Wee Web Framework
+
+== Copyright and License
+
+Copyright (c) 2004, 2005 by Michael Neumann (mneumann@ntecs.de).
+
+Released under the same terms of license as Ruby. Some files under directory
+<tt>examples/</tt> might be copyrighted by third parties and licensed under
+different terms.
+
+== Status and Bugs
+
+Wee is not considered production ready! It should only be used for small
+things. 
+
+Known Bugs:
+
+* Continuations leak memory!
+* Sessions get never reclaimed (easy to fix). 
+
+== Introduction
+
+Wee is a light-weight, very high-level and modern web-framework that makes
+<b>W</b>eb <b>e</b>ngineering <b>e</b>asy. It mainly inherits many ideas and
+features from Seaside2[http://beta4.com/seaside2], but was written from scratch
+without ever looking at the Seaside (or any other) sources. All code was
+developed from ideas and lots of discussions with Avi Bryant. 
+
+== Features
+
+=== Reusable components
+
+Wee has _real_ components, which are like widgets in a GUI. Once written, you
+can use them everywhere. They are completely independent and do not interfere
+with other components. Components encapsulate state, a view and actions. Of
+course you can use an external model or use templates for rendering.
+
+=== Backtracking
+
+See the <i>What is backtracking?</i> section below. In short, backtracking lets
+the browser's back and forward-button play well together with your application.
+
+=== Clean and concise
+
+Wee is well thought out, is written in *and* supports clean and concise code.
+Furthermore I think most parts are now very well documented.
+
+=== Abstract core
+
+The core of Wee is completely independent of both HTTP and HTML. That means,
+with little effort, you should be able to render other formats than HTML and
+use other communication protocols like SOAP, XML-RPC, Email, GUI or Console.
+
+=== Templating-independent 
+
+Wee does not depend on a special templating-engine. You can use a different
+templating engine for each component if you want. 
+
+=== Powerful programmatic HTML generation 
+
+Wee ships with an easy to use and very powerful programmatic html-generation
+library. For example you can create a select list easily with this piece of
+code:
+
+   # select an object from these items
+   items = [1, 2, 3, 4]
+
+   # the labels shown to the user
+   labels = items.map {|i| i.to_s}
+
+   # render it
+   r.select_list(items).labels(labels).callback {|choosen| p choosen}
+
+   # render a multi-select list, with objects 2 and 4 selected
+   r.select_list(items).multi.labels(labels).selected([2,4])
+
+The callback is called with the selected objects from the _items_ array.  Items
+can be any object, e.g. whole components:
+
+   labels = ["msg1", "msg2"]
+   items = labels.collect {|m| MessageBox.new(m)}
+   r.select_list(items).labels(labels).callback {|choosen| call choosen.first} 
+
+=== Continuation based (Optional)
+
+<b>IMPORTANT:</b> <i>The current implementation of continuations in Ruby might lead
+to memory leaks, if you use continuations. Furthermore, if you use
+continuations, it's no longer possible to store the session state to disk.</i>
+
+Continuation-based frameworks are also known as _modal_ frameworks. You can
+write code like the one shown below (taken from one of Avi's emails) where each
+method displays a new page:
+
+  def checkout
+    billing = getAddress("Billing Address")
+    if useSeparateShippingAddress()
+      shipping = getAddress("Shipping Address")
+    else
+      shipping = billing
+    end
+    payment = getPaymentInfo()
+    showConfirmation(billing, shipping, payment)
+  end 
+
+Try to implement the same in a non-continuation based framework and show me
+your code... ;-)
+
+=== Fully Marshallable (drops Continuation support)
+
+If you don't need continuations, Wee can be made fully marshallable. It is not
+yet fully marshallable (it was in the past), but it can be made, if required. 
+
+== Observations and Limitations
+
+* Using continuations (might) lead to memory leaks! 
+
+* When using continuations for cross-component calls, it's impossible to
+  store a session to disk (at least in Ruby). This problem is partly addressed
+  by checkpointing provided by operating systems like
+  DragonFly[www.dragonflybsd.org]. But with this approach it's still impossible
+  to store sessions _selectively_ to disk. 
+
+* Each session runs in it's own (light-weigth) thread (this is a neccessity
+  when using continuations).
+
+* Only one action callback can be invoked per request (a former version of Wee
+  was able to invoke multiple callback, and answer even from multiple
+  components at the same time, but this was removed, due to the unreliability of
+  continuations in Ruby).  
+
+* Components are thread-safe, as a fresh components-tree is created for each
+  session and requests inside a session are serialized.
+
+== What is backtracking?
+
+If you want, you can make the back-button of your browser work correctly
+together with your web-application. Imagine you have a simple counter
+application, which shows the current count and two links _inc_ and _dec_ with
+which you can increase or decrease the current count. Starting with an inital
+count of 0, you increase the counter up to 8, then click three times the back
+button of your browser (now displays 5) and finally decrease by one, then the
+counter really shows the expected 4, instead of 7 (as clicking the back button
+does usually not send a HTTP request, and the last state of your application
+was 8).
+
+Only individual objects are backtracked, those of which you explicitly take a
+snapshot, not the whole component. That's the easiest (from an application
+programmers perspective) and most flexible way. And its fast and uses less
+memory.
+
+You can decide yourself whether you want infinite backtracking or only
+backtracking up to n pages, with whatever replacement strategy you want, least
+recently used (LRU), least frequently used (LFU) etc. 
+
+== Decorations
+
+Decorations are used to modify the look and behaviour of a component, without
+modifying the components tree. A component can have more than one decoration.
+This is implemented as a linked list of decorations (Wee::Decoration#owner
+points to the next decoration). Wee::Component#decoration points to the first
+decoration in the chain or to the component itself, if no decorations were
+specified. We actually use a Wee::ValueHolder for the <tt>@decoration</tt>
+instance variable of class Wee::Component to be able to easily backtrack it
+(required if you want to "undo" component calls).
+
+== The anatomy of a request/response cycle
+
+The request/response cycle in Wee is actually split into two separate phases
+or steps. Depending on the point-of-view (given that a page is rendered and
+the user clicks on a link or button), the first phase is to invoke an action
+(a "callback"). Then in the second phase, a new page is rendered and sent
+back to the user. So the two steps are:
+
+1. invoke callbacks (action phase)
+
+2. render new page and display (render phase)
+
+These two phases repeat permanently. Which tasks are performed in each of them, is briefly listed below:
+
+<b>Action:</b>
+
+1. restore snapshot (if not up-to-date)
+
+2. invoke actions   
+
+3. backtrack state
+
+4. update url -> redirect to render phase (not yet)
+
+<b>Render:</b>
+
+1. restore snapshot (if not up-to-date)
+
+2. render
+
+For each session there is at most one request handled at the same time. That
+means, that there is either one action request or one render request handled.
+Why? Because we have only one components tree, which we update on action
+requests. As Wee allows to go back in time, we have to restore this components
+tree to a certain point in time before we can handle an action or render
+request. This disallows to handle e.g. two render requests simultaneous.
+
+=== Action Phase (Invoking Callbacks)
+
+Possible sources for callbacks are links (anchors) and all kinds of
+form-elements like submit buttons, input-fields etc. There are two different
+kinds of callbacks:
+
+* Input callbacks (input-fields)
+
+* Action callbacks (anchor, submit-button)
+
+The distinction between input and action callbacks is important, as action
+callbacks might depend on values of input-fields being assigned to instance
+variables of the controlling component. Hence, Wee first invokes all input
+callbacks before any action callback is triggered.
+
+There are two methods related to callback processing:
+
+* Wee::Component#process_callbacks_chain
+
+* Wee::Presenter#process_callbacks
+
+Note that each Wee::Component is also a Wee::Presenter, whereas a
+Wee::Decoration is not a Component (but a Presenter)! 
+
+Method <i>process_callbacks_chain</i> invokes <i>process_callbacks</i> for
+it's first decoration, or if the component has no decorations, the method is
+called for the component itself.  As such, <i>process_callbacks_chain</i>
+is important to avoid entering an infinite loop (a method calling itself). What
+decorations are, is discussed elsewhere.
+
+Method <i>process_callbacks</i> of class Component first invokes all input
+callbacks specified for this component, then calls
+<i>process_callbacks_chain</i> for all of it's child components. This ensures,
+that all input callbacks are triggered before the first action callback is
+run. Finally, it invokes all of it's action callbacks.
+
+=== Rendering Phase
+
+The rendering phase is assumed to be side-effect free! So, you as a
+programmer should take care to meet this assumption.
+
+Similar as in the callback-step, there are two methods related to rendering a
+page:
+
+* Wee::Component#do_render_chain
+
+* Wee::Presenter#do_render
+
+Method <i>Component#do_render_chain</i> starts rendering the decoration chain by
+calling <i>Presenter#do_render</i> for the first decoration of the component or
+for the component itself if no decorations were specified.  Method
+<i>Presenter#do_render</i> then generates the desired output which gets sent to
+the user. Note that method <i>do_render</i> might call other components'
+<i>do_render_chain</i> methods to display those components "inside" itself
+(usually a component does this for it's child components, but this has to be
+implemented by the programmer). 
+
+=== Further Reads
+
+In this order:
+
+* Wee::Presenter
+* Wee::Component
+* Wee::Decoration
+* Wee::Delegate
+* Wee::AnswerDecoration

data/Rakefile

@@ -0,0 +1,26 @@
+require 'rake/rdoctask'
+require 'rake/testtask'
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README"
+  rd.rdoc_dir = 'doc/tmp'
+  rd.rdoc_files.include('lib/**/*.rb', 'README', 'INSTALL')
+  rd.options << '--all --inline-source' 
+end
+
+task :rdoc do
+  sh 'cpdup -o doc/tmp doc/rdoc' 
+end
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+end
+
+task :package do
+  sh 'gem build wee.gemspec' 
+end
+
+task :clean => [:clobber_rdoc]
+
+task :default => [:test, :rdoc, :clean]

data/TODO

@@ -0,0 +1,116 @@
+* call method #backtrack from backtrack_state. you don't need to call super for #backtrack (at least for direct subclasses of Component).
+* call method #setup from initialize. same reason as for #backtrack.  
+
+* initialize the component inside the handler thread, not from within Session#initialize
+ 
+* renamexxx_chain methods to: component_xxx, e.g. 
+  - process_callbacks/process_callback_chain to process_callbacks/component_process_callbacks
+  - ... to backtrack_state/component_backtrack_state
+  - render/render_chain to render/component_render  
+
+* callback -> core, how is the callback registry best done?
+
+* Context.... reduce
+
+* root_for -> script style etc.
+
+* Application == Dispatcher... collection of Session classes (or RequestHandlers)
+
+* file-comments != class-comments... remove them
+
+application.template_manager = {
+  My => {'html' => RDocTemplate.new('view/html/file.tmpl'), 'wap' => RDocTemplate.new('view/wap/file.tmpl')}
+}
+
+either this way, or reversed: flavour/style => template-manager
+
+class My < TemplatedComponent
+  def action_blah
+  end
+  def action_blub
+  end
+
+  attr_accessor :blah
+
+  # run-time 
+  def template_flavour
+    session.property['style'] || 'html'
+  end
+end
+
+view/html/filt.tmpl:
+
+  <form action="__action_blah">
+    <input name="__input__blah">
+  </form>
+
+__action and __input get replaced
+
+* unify RequestHandler/Session
+
+* Wee = Web Engineering made Easy
+
+callback.rb -> core
+context -> core?
+
+Wee::Callback: abstract
+* values -> default_values
+Wee::BlockCallback
+* invoke -> call/[]
+
+overthink CallbackStream
+CallbackStream abstracts from the Request.
+use only blocks as callbacks.
+
+* different models:
+
+  M = Model, V = View, C = Controller
+
+  M: e.g. use ActiveRecord as model
+  V: use external templates 
+  C: Wee::Component
+
+  MC: Wee::Component
+  V: external template
+
+  MVC: Wee::Component
+
+* callbacks.create_callback_stream -> create_stream
+
+* better webrick
+
+* AbstractSession: 
+  
+  last_access: time of last access
+
+  expires_after: expires after n seconds of inactivity (Time.now - last_access > expires_after) if expires_after.not_nil?
+  expires_after = n_seconds
+
+  max_lifetime: how long may this session run in total?  nil == infinity
+  max_lifetime = 
+
+  Session#terminate: quits a session 
+
+    Application.remove_session(self.session_id)
+
+  Session#session_id
+  Session#application
+
+Application also stores other RequestHandlers. Session is one RequestHandler.
+
+  class RequestHandler
+    attr_reader :application
+
+    attr_reader :last_access
+    attr_accessor :expires_after, :max_lifetime
+
+    def alive?
+      returns true if it should not be terminated
+    end
+  end
+
+* Decoration#owner: use a ValueHolder, too. and register it for being backtracked.
+
+* mark_objects_for_backtracking() instead of state-registry (snapshot_objects)
+
+* improve error messages

data/benchmark/Centrino1300/result.2000.counter.action

@@ -0,0 +1,45 @@
+This is ApacheBench, Version 2.0.40-dev <$Revision: 1.121.2.8 $> apache-2.0
+Copyright (c) 1996 Adam Twiss, Zeus Technology Ltd, http://www.zeustech.net/
+Copyright (c) 1998-2002 The Apache Software Foundation, http://www.apache.org/
+
+Benchmarking localhost (be patient)
+
+
+Server Software:        WEBrick/1.3.1
+Server Hostname:        localhost
+Server Port:            2000
+
+Document Path:          /counter/s:1/p:0/h:1
+Document Length:        62 bytes
+
+Concurrency Level:      1
+Time taken for tests:   12.63163 seconds
+Complete requests:      2000
+Failed requests:        1991
+   (Connect: 0, Length: 1991, Exceptions: 0)
+Write errors:           0
+Non-2xx responses:      2000
+Total transferred:      552679 bytes
+HTML transferred:       133786 bytes
+Requests per second:    165.79 [#/sec] (mean)
+Time per request:       6.032 [ms] (mean)
+Time per request:       6.032 [ms] (mean, across all concurrent requests)
+Transfer rate:          44.68 [Kbytes/sec] received
+
+Connection Times (ms)
+              min  mean[+/-sd] median   max
+Connect:        0    0   0.4      0       9
+Processing:     3    5   3.8      4      69
+Waiting:        0    2   3.9      1      69
+Total:          3    5   3.9      4      72
+
+Percentage of the requests served within a certain time (ms)
+  50%      4
+  66%      4
+  75%      4
+  80%      5
+  90%      6
+  95%     15
+  98%     16
+  99%     18
+ 100%     72 (longest request)