&_.name;
&_.contents:none;

Release notes for Roxen 2.2

User level changes

'content boxes' added in the config interface (the first page) If you want to write your own boxes, see the files in config_interface/boxes.

Added memory to the toplevel tabs in the configuration interface When you click on a toplevel tab, you return to the page you last visited below that tab, just like in Roxen 1.3, click again to go to toplevel

The configuration interface now works with more browsers. Some HTML changes were made so that the configuration interface works better with the Mozilla and Opera browsers.

The ports tab has been merged into the site tabs. The old (overview) ports tab is available under the globals tab.

Two new themes added; Square orange, and the new default theme (old default now known as '2.0 and 2.1 theme'). Roxen WebServer now comes bundled with MySQL, and the database is used for various things inside Roxen Webserver. Also, there is a new database administration interface available inside the configuration interface. The user-database and authentication module API has been redesigned.

You can now have multiple user database and multiple authentication modules, and the modules only has to implement one of the two services.

Two example authentication modules are included, one that uses cookies and one that use the normal 'Basic' authentication system.

Two user database modules are currently available (unless you count the htaccess module), the system user database and the ldap user database. The system database uses getpwent on to access the normal system users. The module level security patterns and the htaccess files now include many new options, and are compiled for quicker execution.

The htaccess module now also acts as a user-database, so you can use <if user=username> in your RXML pages (and, if you feel like it, your module level security patterns) with users and groups authenticated from the htaccess module, even if the page does not otherwise use the htaccess permission system.

Gopher and fhttp removed
The gopher and fhttp protocols has been removed. The former because it has not worked for three years, and nobody noticed, and the latter because it did only offer benchmark performance, it was not all that useful for real life applications. However:

The HTTP protocol module has some C-optimizations
Parts of the normal HTTP protocol module has been rewritten in C, and some other optimizations has been done. Overall, the HTTP parsing is now about twice as fast as it was in Roxen 2.1.

The HTTP protocol auto-encodes unicode
Unicode characters in text data is now recoded to useable output charset. This includes recoding of unsupported characters to entities (as an example, when a $(B6b(B character is encountered and the output charset is iso-8859-1, or å and the output charset is iso-8859-9)
  • The URLs for the images in the image cache are now encrypted before they are sent to the client.
  • The user ID is now saved for the images, no authenticated user can get an image rendered for another authenticated user.
  • span-width and span-height. Like max-width and max-height, but if the image is smaller, it's padded to the specified size.

  • crop=guides-cross guides-index=x,y: Crop around the point specified by the intersection of the two guides. Useful with max-width=... and max-height=..., primary for thumbnail generation.

  • crop=guides-region [guides-index=x1,y1[-x2,y2]] Crop to the specified region before doing any scales. Also useful with max-width=... and max-height=... for thumbnail generation. If guides-index is x1,y1, the guides x1,y1 and x1+1,y1+1 will be used, counting from the left and the top, respectively. If both the ending and starting indexes (x2,y2) are specified, thoose guides will be used.
There is a new configuration variable "Compatibility level" for each site. This variable is queried by different modules to control minor compatibility issues in their behavior.

The variable is set to the latest version for every newly created site, but is then never changed automatically during upgrade. It's set to "2.1" for sites that are imported from earlier Roxen versions.

The intention with this variable is to make it easier to do small changes that aren't strictly compatible, but still avoid jeopardizing the compatibility when upgrading older sites. FreeType 2 support added. Roxen can now render text using TrueType and PostScript Type1 fronts using FreeType 2.

There are now more CIF (Compact Image Font) generation and unpacking programs available in the bin directory. The option --strip-backslash has been added. This causes all \ in the URL to be transformed to /. Useful for NT-compatibility reasons on Unix, this behaviour has been the default on NT since Roxen 2.0. The NT service is now built-in to the ordinary roxen binary. Minimum bandwidth - new method to detect and dispose of hung clients. This saves valuable resources in form of file descriptors and memory. /internal-roxen-pixel-colorname generates a pixel with the color colorname. colorname can be either a symbolic name like "darkgreen" or a precise value in the RGB color space like "0000ff". For example /internal-roxen-pixel-red or /internal-roxen-pixel-ff0000 will give you a 1x1pixel red image. Added support for RFC 2428 (EPRT & EPSV). Some caches has been rewritten for better speed and to avoid overcaching. Throttling support has been changed and optimzed to make it useful for sites with a lot of traffic.

RXML changes

The RXML parser has been optimized, mainly with the introduction of p-code. RXML is now compiled to p-code the first time it is run, then evaluated directly from this form on subsequent accesses to the same file. This means that the RXML does not have to be reparsed from the source code for each access, and the internal memory structures are reused.

The introduction of p-code also allows more advanced features in the <cache> tag, which now is powerful enough to allow you to tune RXML pages for substantial performance gains. Entity variables holding complex data types (lists of values etc) can now be indexed using the &scope.variable.index; syntax. As an example, if the page requested has two form variables with the name 'file', you can access them one at a time as &form.file.1; and &form.file.2;, respectively. The <cache> tag now handles nested <cache> and <nocache> tags correctly by mixing evaluated and unevaluated RXML code in the cached entries. This allows caching to be used around complex RXML code while still keeping some part of it dynamic (such as the name of the visitor or an access counter).

The cache also handles variable assignments. You can e.g. do a costly sql query and assign the result to a variable inside a <cache>, and then use that cached value outside the <cache> tag to format it dynamically depending on a user set theme. Emit now supports more filtering and sorting options. Set and append can now act as container tags, with the value inside them. As an example, to set the variable var.foo to bar, you can use <set variable=foo>bar</set> A new argument has been added to <insert> and <use>: locate=filename. This will attempt to locate the specified file in the directory the current file recides and all directories above that directory, up to the root of the virtual filesystem. The expr argument (expression evaluation) can now handle much more complex expressions. As an example, it can do type conversions, and use complex datatypes. New entities such as &unique-id; and &client.session; helps you make session driven applications with little effort. See also the Session tag module under New modules.

New modules

There is a new image generating module available, the GXML module. It renders images from a XML language, and is quite easily extended with new tags and operations (Roxen modules can add tags to GXML).

See the following examples for some more information A module for creating and sending mails.

  • Mail is sent by SMTP protocol to the remote or local SMTP server.
  • Multiple headers.
  • MIME compliant.
  • Attachments.
A module that allows the creation of files from normal RXML using the <writefile> tag. Contributed by Stephen R. van den Berg. Generates a robots.txt on demand from various information. Highlights the words stored in the form variable highlight in HTML pages, mostly useful for searchengines. This module removes redundant whitespace from HTML pages. This module provides the <page-size> tag that calculates the size of a page, including inline images, HTTP headers etc, and gives an estimates of the time it will take to download the page over various connections.

You can also use the size prestate to trigger the sizing process. Another helping module for HTML-writers. This one allows you to toggle the viewing of table and image borders using a prestate. Automatically <use> a package before parsing files.

Useful for creating template files whose tags and variables are automatically included before any RXML parsing is done of the content files.

The tags defined in such templates also benefits from the p-code speedups. This module provides some tags to support javascript development (as an example, Javascript popup menus) A simple mpeg streaming server has been added, mostly for example purposes. Provides support for session handling in form of the <session> and <force-session-id> tags. Handles clients with cookie support turned off transparently for the RXML programmer and uses unguessable session ID's.

User level compatibility issues

The start script now makes a PID file earlier to be better at avoiding duplicate server processes, and to work better together init.d scripts. The global variable "PID file" is no longer consulted, due to the "chicken-and-egg" problem that would occur then.

If you depend on the PID file location specified by the "PID file" variable, you need to move that setting to the start script, either by adding a --pid-file argument or by setting the environment variable ROXEN_PID_FILE. Previously the start script added the MODULE_DEBUG define when neither --with-debug nor --without-debug was given to it. That define turns on some extra debug checks which are useful when developing new Roxen modules, but wasteful in production use. It's now turned off by default to get maximum performance in production use. To turn it on, you now need to either add the new --module-debug argument, or run with --once.

News for developers

A Hilfe (interactive pike evaluator) protocol has been added. You can use this to evaluate Pike expressions inside your running Roxen Server. When Roxen starts, it search for protocol modules in the 'protocols' directory, there is no longer any hard-coded list of known protocols. Two new APIs are available to module programmers. For more information, see the Roxen Community article Roxen now has a built-in testsuite to verify that no regression occurs. It is started by supplying the argument --self-test to the start script.
  • Added cookies, prestates and time to the request object.
  • Added cache() method.
  • Allow module loading from paths beginning with ../
It's possible to use Pike modules (.pmod files and directories) in Roxen modules in a convenient way. Roxen now adds all directories called "pike-modules" that are found in the Roxen module search path to the Pike module path. So you can simply put your Pike modules in a directory called "pike-modules" near your Roxen module, and its contents will be available when the Roxen module is loaded. The <cache> tag works by caching the result after evaluating its contents. It also caches any variable changes made with RXML.set_var, RXML.Context.set_var, RXML.Context.add_scope etc.

Changes directly in id->misc and RXML_CONTEXT->misc (aka id->misc->defines) is however not known by the cache system and therefore not saved in the cache entries. This can be a problem when tags uses either of those two mappings to pass state between each other. A (rather silly) example to illustrate:

<my-set value="foo"/>    <!-- Does id->misc->my_value = "foo" -->
...
<my-get/>                <!-- Returns id->misc->my_value -->

Now, if <my-set> is surrounded by a <cache> tag, there's a problem:

<cache>
  <my-set value="foo"/>  <!-- Does id->misc->my_value = "foo" -->
</cache>
...
<my-get/>                <!-- Returns id->misc->my_value -->

When the <cache> tag is evaluated the second time, it won't redo the assignment id->misc->my_value = "foo", since it doesn't know it has happened. Therefore <my-get/> will not return the same thing.

There are two ways to solve this:

  • Use RXML.set_var and similar functions to set values instead, e.g:
    <cache>
      <my-set value="foo"/>  <!-- Does set_var("my_value", "foo", "var") -->
    </cache>
    ...
    <my-get/>                <!-- Returns get_var("my_value", "var") -->
    

    The set_var call is intercepted by the cache, so it will be redone when the cached value is reused. The downside of this approach is that the variable will be user accessible (with &var.my_value; in this example).

  • Use RXML_CONTEXT->set_misc to set the values, e.g:
    <cache>
      <my-set value="foo"/>  <!-- Does RXML_CONTEXT->set_misc("my_value", "foo") -->
    </cache>
    ...
    <my-get/>                <!-- Returns RXML_CONTEXT->misc->my_value -->
    

    This is very similar to the approach above, except that the variable won't be user accessible. The function set_misc simply sets a value in RXML_CONTEXT->misc but also records the setting for the cache.

Developer level compatibility issues

The function module_identifier in Roxen modules has been changed to return a string on the same format as Roxen.get_modname. The old format was bulkier and not guaranteed to be unique for the module. The responsibility to do type conversion for values from RXML.Value and RXML.Scope objects has been moved from the caller to the callee (i.e. RXML.Value.rxml_var_eval and RXML.Scope.`[]). It is therefore an error to ignore the fourth RXML.Type argument to these functions. The inline doc for RXML.Value.rxml_var_eval contains motivation and further discussion of this. The way to create new RXML tag sets has changed slightly due to encoding issues when p-code is dumped to disk. It's however fairly simple to update the create call. Previously, tag sets were typically created with something like this:
RXML.TagSet internal = RXML.TagSet("TagFoldlist.internal", ({ TagFT(), TagFD() }) );

The first argument should earlier be a string that uniquely identifies the tag set in the whole server (which the one in the example above from the foldlist module clearly doesn't). Now, one instead gives the own module as the first argument and a string that only should identify the tag set uniquely within the module (the empty string is reserved for the main module tag set). The example above thus becomes:

RXML.TagSet internal = RXML.TagSet(this_module(), "foldlist", ({ TagFT(), TagFD() }) );

For tag sets that are used for local or additional tags inside a container tag, it's typically a good idea to use the name of the container tag as the unique identifier, hence "foldlist" above. (Note that these identifier strings are stored in the dumped p-code, so it's a good idea to keep them fairly short.) This is to avoid a name conflict with Debug.pmod that comes with Pike.

Pike changes since Pike 7.0