Apache Rivet 3.0

The Rivet Team

The Apache Software Foundation


Table of Contents

Introduction to Apache Rivet version 3.0
Apache Rivet 3.0 Installation
Building Rivet 3.0 with CMake
CMake build procedure and examples
Apache Rivet 3.0 Configuration
Apache Rivet Configuration lines
Configuration Directives
Apache Rivet HTTP Request Processing
Tcl Scripts Processing
Example: basic OO Rivet Application
Apache Child Processes Lifecycle and Request Processing
Rivet Tcl Commands and Variables
<?= ... ?> — Shorthand construct for single strings output
abort_code — Returns the code passed to abort_page earlier during the request processing
abort_page — Stops outputting data to web page, similar in purpose to PHP's die command.
apache_log_error — log messages to the Apache error log
apache_table — access and manipulate Apache tables in the request structure.
catch — wraps core command catch
clock_to_rfc850_gmt — create a rfc850 time from [clock seconds].
cookie — get, set and delete cookies.
debug — A command to print strings, arrays and the values of variables as specified by the arguments.
env — Loads a single "environmental variable" into a Tcl variable.
escape_sgml_chars — escape special SGML characters in a string.
escape_shell_command — escape shell metacharacters in a string.
escape_string — convert a string into escaped characters.
exit — terminate execution and child process
headers — set and parse HTTP headers.
html — construct html tagged text.
http_accept — Parse HTTP Accept header lines
import_keyvalue_pairs — Import an argument list into the named array
include — includes a file into the output stream without modification.
incr0 — increment a variable or set it to 1 if nonexistent.
inspect — Introspection command for Rivet configuration
lassign_array — Assign a list of values to array variables
lempty — Returns 1 if <list> is empty or 0 if it has any elements. This command emulates the TclX lempty command.
lmatch — Look for elements in <list> that match <pattern>
load_cookies — get any cookie variables sent by the client.
load_env — get the request's environment variables.
load_headers — get client request's headers.
load_response — load form variables into an array.
lremove — remove from a list elements matching one or more patterns
makeurl — construct url's based on hostname, port.
no_body — Prevents Rivet from sending any content.
parray — Tcl's parray with html formatting.
parse — parses a Rivet template file.
raw_post — get the unmodified body of a POST request sent by the client.
redirect — Interrupt processing and divert to a new URL
read_file — Read the entire contents of a file and return it as a string.
try — Catch error and exception conditions
unescape_string — unescape escaped characters in a string.
upload — handle a file uploaded by a client.
url_script — get the code of the URL referenced Tcl script or Rivet template
var — get the value of a form variable.
wrap — Split a string on newlines.
wrapline — Split the line into multiple lines by splitting on space characters
xml — XML Fragments creation
Examples and Usage
Rivet Tcl Packages
DIO - Database Interface Objects
DIO — Database Interface Objects
DIODisplay - Database Interface Objects Display Class
DIODisplay — Database Interface Objects Display Class
Session Package
Preparing To Use It
Example Usage
Using Sessions From Your Code
Session Configuration Options
Session Methods
Getting Additional Randomness From The Entropy File
Form: An HTML Form Fields Generation Utility
form — a Tcl command object for creating HTML forms
Calendar Package
Calendar — Utility class the builds and prints a calendar table
XmlCalendar — Prints XML formatted calendar tables
HtmlCalendar — Concrete class derived from XmlCalendar
encode — encode a string replacing every occurrence of characters for which an SGML entity exists
decode — decode an SGML encoded string replacing every entity with the corresponding character
toGlyphs — print large ASCII glyphs
The Form Broker
FormBroker — Form broker object creator
Resources - How to Get Help
Mailing Lists
Web Sites
Bug Tracking System
Editing Rivet Template Files
Rivet Internals
Rivet approach to Apache Multiprocessing Models
mod_rivet MPM Bridge callbacks
Server Initialization and MPM Bridge
The global Command
Page Parsing, Execution and Caching
Extending Rivet by developing C code procedures
Debugging Rivet and Apache
Example: the Lazy bridge
The rationale of threaded bridges
Lazy bridge data structures
Handling Tcl's exit core command
HTTP request processing with the lazy bridge

List of Examples

1. Hello World
2. Generate a Colorful Table
3. Variable Access
4. File Upload
5. File Download
6. XML Messages and Ajax
7. A Calendar Utility

This manual was generated on Monday 2018-11-05 01:05:53+01:00.

Introduction to Apache Rivet version 3.0

Apache Rivet is a system for creating dynamic web content by integrating the Tcl programming language within the Apache Web Server. It is designed to be fast, powerful and extensible, consume few system resources, be easy to learn, and to provide the user with a platform that can also be used for other programming tasks outside the web (GUI's, system administration tasks, text processing, database manipulation, XML, and so on).

In this manual, we aim to help get you started, and then writing productive code as quickly as possible, as well as giving you ideas on how to best take advantage of Rivet's architecture to create different styles of web site.

This documentation is focused on the current version of Rivet, but still a work in progress, and, like everything else about Apache Rivet, it is Free Software. If you see something that needs improving, and have ideas or suggestions, don't hesitate to let us know. If you want to contribute directly, better yet!

Apache MPM and Rivet Bridge Modules

Rivet 3.0 is a major rewriting of mod_rivet, the Apache HTTP Websever module at the core of Rivet. Unlike in previous versions of mod_rivet which only supported the prefork MPM (Multiprocessing Module), starting with 3.0 we attained full support of different MPM for the Apache framework.

Threaded MPM integration was achieved by making mod_rivet multithreaded and modular itself, introducing the MPM-module bridge concept. We developed a set of loadable modules which are supposed not only to overcome the issues related to threading but also to offer the best possible MPM mod_rivet integration. As a side effect of this modular design mod_rivet is not only able to integrate with its environment but also to work as a framework for writing more MPM bridges designed along different multi-threading schemes and workload management models. See the internals section of this manual for further reading. MPM bridges are loaded accordingly to a heuristics of rules based on the Apache introspection calls but they can be determined in the configuration. Only a bridge can be loaded at a time.

Request Processing

Request processing was performed in mod_rivet version 2.x by chaining together 3 scripts

  • BeforeScript, if defined in the configuration
  • The URI referenced Tcl script or rvt template dermined with respect to the DocumentRoot and following other resource determination methods such the ones offered by mod_alias and by mod_rewrite.
  • AfterScript, if defined in the configuration

Errors and exceptions (raised by the ::rivet::abort_page command) are handled by the ErrorScript and AbortScript (ErrorScript has a default implementation if undefined in the configuration)

Rivet 3.0 implements a new request processing scheme entirely based on Tcl. By default rivet 3.0 provides compatiblity with the version 2.x scheme to handle a request but this can be entirely overridden by the developer replacing the central request handling procedure. See the request processing page for further reading


This version of Rivet received substantial contributions from George Petasis who solved several problems with the threaded code, improved the code in several ways and made the CMake based build scripts