h2. Building and deployment

h3. Q: How does Wt organize sessions in processes and threads ?

Wt makes a distinction in the conceptual organization (which is reflected in the API of WApplication)
and the way the application is actually deployed.

Conceptually, every user session is completely isolated from each other. For each new session, Wt
calls the function that is supplied to WRun(), to create a WApplication object for that session.
As a programmer, you should program for the general case where different WApplication objects
are in different processes, and thus if you wish to communicate between different session, you
have the following options: (in increasing order of flexibility traded for convenience):

• A database to which every session connects.
• A dedicated server daemon, with socket based communication.
• A combination of both, with possible peer-to-peer communication between different sessions.

Physically, Wt offers several choices for deployment, each of them with different trade-offs.
If an application sticks strictly to the previous rules, you can freely change between different
deployment options at deployment time.

The options that are available are:

• Dedicated-process mode: mapping one session to one process. Advantages are:
  ** Kernel-level isolation between processes (security and reliability!).
  ** Kernel-based sharing of read-only memory segments (simply UNIX feature).
  ** Development friendly: a new session uses the latest deployed binary, and valgrind may be used to
  debug one particular session, by modifying the URL request.

• Shared-process mode: mapping multiple sessions in a fixed number of processes. Advantages are:
  ** No process and stack overhead per session.

Wt is capable of using multi-threading to improve performance for both situations. Threads are
used for simultaneous handling of requests. Even in dedicated-process mode, several requests
may be handled simultaneously, for example concurrent streaming of different WResource's. The
multi-threading feature however is more important for shared-process mode, for handling concurrent
requests for different sessions. In the latter case, however, the number of threads must not
equal the number of active sessions: threads are reused after every request is handled.

The shared-process mode has the notable disadvantage, inherent to C++, that memory corruption
may occur and can take down all sessions. It is however well suited for 'open' applications on
the Internet (and the Wt homepage and all examples are deployed this way). If you design a
restricted access application, or possibly a security sensitive application, or deploy the
application on a private intranet, the dedicated process mode may be more suitable.

h3. Q: How does it compare to Java servlets ?

Differences with Java Servlets are mostly due to the Java Virtual Machine. Java has the benefit
of automating pointer manipulation, and therefore eliminating unwanted interference between
different sessions because of pointer bugs. On the other hand, because of the high costs (both
run-time start up as well as memory usage) associated with a Java Virtual Machine instance,
Java cannot afford kernel-level isolation between different Java sessions. If not programmed properly,
two sessions can still interfere through for example the use of class static variables.
Unfortunately, some servlet based frameworks, like the often-used struts framework, actually encourage
sharing of for example form objects between different sessions for run-time efficiency reasons,
making session cross talk readily an issue.

Similarities between Wt and Java Servlets are the use of a thread pool to serve concurrent
requests, and the abstraction of actual deployment details from the API, allowing easy
scalability.

h3. Q: How do I build my newly written "Hello World!" application?

A:
Wt itself, and the examples, use "CMake":http://www.cmake.org, but that is entirely a
personal choice. You can use any build environment, like qmake, where
you:

• specify the library directory (Wt defaults to installing in /usr/local/lib)
• specify the link libraries: -lwt and one of -lwtfcgi or -lwthttp
• specfiy the include directory (Wt defaults to installing in /usr/local/include)

Unlike Qt, there is no need for special features such as moc for
starting a Wt project.

If you decide to use CMake, and have installed Wt in its default
location (within /usr/local), this CMakeLists.txt file should do it:

ADD_EXECUTABLE(myprog.wt
MyProg1.C
OtherFile.C
AndEvenMoreCode.C
)

For FastCGI deployment:¶

TARGET_LINK_LIBRARIES(myprog.wt
wtfcgi wt someotherlib
)

Or, for built-in httpd deployment:¶

TARGET_LINK_LIBRARIES(myprog.wt¶

wthttp wt someotherlib¶

)¶

INCLUDE_DIRECTORIES(/usr/local/wt/include)

The examples use a CMakeLists.txt which is customized for using the
current build of Wt, and not that one that is already installed some
place (with make install). Therefore, it is not really the recommended
way to bootstrap your own Wt project. Also, the ./deploy scripts are
very primitive, and are a bit specific for the examples. Deploying is
nothing more than copying the files to some directory in your html
root.

The other methods are:

To handle many sourcefiles, dependencies... you need a makefile. Obviously, the way Wt is designed, you should have quickly many files for the many classes that will compose your app. Wt uses cmake (cmake.org for details) to make makefiles and that is probably a good choice. Just like many others, I switched to cmake (from hand-written makefiles) because of wt and I am pretty happy with it.
make should produce the executable. At this point, you probably need to move the output of make to a directory available to your webserver; in practice you therefore need a script that is going to deploy the file. When you name the app, be sure the extension is recognized by the webserver. Also, you may need to kill active processes of your app and maybe copy the css and some other files (icons...) to the directory available to the webserver.
In the end, I bundled all that in a deploy file located in the build directory (the one that is usually created for cmake). After I have have finished changing the source files, I just type ./deploy on the command line and I can refresh my web page.

make
target_app=app.wt
target_path=httpdocs
ps -A | grep app.wt | awk '{print $1}' | xargs kill
rm -f "~/${target_path}/${target_app}"
cp "${target_app}" ~/${target_path}/
cp ../app.css ~/${target_path}/

OR

You can use install command instead of cp, more or less like this:

install -m 0755 astariand.wt /var/www/game
install -m 0644 messages.xml /var/www/game
install -m 0644 astariand.css /var/www/game
install -m 0644 login.php /var/www/game
install -m 0644 includes.php /var/www/game
install -m 0755 -d /var/www/game/media
install -m 0755 -d /var/www/game/media/icons
install -m 0644 media/icons/* /var/www/game/media/icons
install -m 0755 -d /var/www/game/media/images
install -m 0644 media/images/* /var/www/game/media/images

Using install has two advantages. First, it allows you to set permissions
on the fly (just as user and group, but I don't use this). Second, with
dedicated process session management you don't need to kill all processes
beforehand - old connections will keep using the old binary and new
connections will use the new one, until all old connections "die from
natural reasons".

h3. Q: My browser shows a window with a message like 'Wt internal error: ReferenceError: Ext is not defined, code: undefined, description: undefined'. How do I resolve it?

A:
Check your log for 404 messages regarding ExtJs. Download Ext 2.0.1 or 2.0.2 from the ExtJs homepage and install it as described "here":http://www.webtoolkit.eu/wt/doc/reference/html/group__ext.html. ExtJs 2.0.2 is available for download "here":http://gwt-ext.com/download/.

You will receive similar error messages when you use a WTextEdit and TinyMCE is not properly deployed. Download TinyMCE from the "TinyMCE homepage":http://tinymce.moxiecode.com/.

ExtJS and TinyMCE need to be available in the document root of your web server. By default, Wt expects ext-related files to be found in 'ext/' (relative to your application deployment location), and TinyMCE in 'resources/tiny_mce/'.

For example (Wt 2.2.1), to run the widgetgallery example (which needs both ExtJS and TinyMCE) from within its source directory, you need the following organisation of auxiliary files:

$ pwd
/home/.../wt/examples/widgetgallery
$ ls ext/
ext-all.js ext-base.js resources
$ ls resources/
collapse.gif items-ok.gif nav-minus.gif nav-plus-line-middle.gif sort-arrow-down.gif tab_l.gif
expand.gif line-last.gif nav-minus-line-last.gif orbited.js sort-arrow-none.gif tab_r.gif
iframe.js line-middle.gif nav-minus-line-middle.gif orbited_LICENSE.txt sort-arrow-up.gif tiny_mce
items.gif line-trunk.gif nav-plus.gif slider-thumb-h.gif stripes tv-line-last.gif
items-not-ok.gif loading.png nav-plus-line-last.gif slider-thumb-v.gif tab_b.gif
$ ls resources/tiny_mce/
langs license.txt plugins themes tiny_mce.js tiny_mce.js.gz tiny_mce_popup.js tiny_mce_src.js utils

and then you can run the example using the following command line:

$ ../../build/examples/widgetgallery/widgetgallery.wt --http-address=0.0.0.0 --http-port=8080 --docroot .

h2. API

h3. Q: How do I deal with look and layout ? Does Wt support CSS ?

Wt uses CSS for layout, and CSS may be either specified in CSS style sheets, or
manipulated programmatorically. Tomasz Mazurek contributed a tutorial about
it.

h3. Q: How do I pass an additional argument from a signal to a slot ?

Frequently, you may want to connect many different signals to a single slot, and identify the original sender in the slot.

For example:

void Test::createWidgets()
{
// create text1, text2, text3 widgets

text1->clicked.connect(SLOT(this, Test::onClick));
text2->clicked.connect(SLOT(this, Test::onClick));
text3->clicked.connect(SLOT(this, Test::onClick));
}

void Test::onClick()
{
// How to know which widget?
}

The solution is to use a "WSignalMapper":http://www.webtoolkit.eu/wt/doc/reference/html/classWt_1_1WSignalMapper.html like this:

void Test::createWidgets()
{
Wt::WSignalMapperWt::WText myMap = new Wt::WSignalMapper<Wt::WText>(this);

myMap->mapped.connect(SLOT(this, Test::onClick));
myMap->mapConnect(text1->clicked, text1);
myMap->mapConnect(text2->clicked, text2);
myMap->mapConnect(text3->clicked, text3);
}

void Test::onClick(Wt::WText* source)
{
// source is where it is coming from
// ...
}

The additional argument can be of any type, since WSignalMapper is a template class. It could for example be the button text, or some other information specific to the widget that is activated.

h2. Security

h3. Q: Building web applications in a low-level language like C? Have you never heard of buffer overruns??

We are well aware of the hostile environment that is the Internet. We believe that Wt provides some unique benefits compared to other solutions to handle the most common attacks:

Cross-Site scripting attacks (XSS): an attacker forces the display of some script by letting the application render it to the browser of a victim that is also using the web application.

Unlike other web technologies, Wt does not require any effort from the programmer to avoid XSS attacks. Instead, any 'rich' XHTML text that needs to be displayed (for example in a WText using XHTMLFormatting) is filtered by a built-in XML parser for any potentially malicious tags or attributes (which is anything that may execute some JavaScript code). Unlike other (low-level) frameworks, Wt provide this protection because there is no raw 'print' command. Instead, Wt generates all HTML/JavaScript from widgets and therefore it knows that rich text should only be "passive" rich text and not contain any "active" content.

Cross-site request forgery attacks (CSRF): an attacker tricks a user into sending a request to a trusted website passing its credentials in a cookie.

This kind of attack is eliminated since Wt uses a secure random number generator for the session ID (on platforms that provide this kernel-level service, such as Linux and Win32 platforms), and even when using cookies for session tracking, the session ID is always sent within the request as well, and verified within Wt (since Wt 2.2.0).

Attacks against the application logic: an attacker issues a request to some page or service that is only accessible after authorization.

Wt protects the application logic because all incoming requests are interpreted in one central, well-tested routine. The request is parsed and only exposed event signals may be triggered. Exposed event signals are attached to widgets that are currently rendered on the screen. For example, a button click on a button that is currently shown on the screen. In this way, the logic of the application (such as for example: you need to first log
in, and then only you may request for a payment) is automatically validated: only code in slots connected to exposed signals can be invoked by the user.

Session cross-talk: sensitive data from one session spills in another session because of a programming error, where data is shared.

Wt is the only solution which may eliminate any cross-talk between sessions by deploying each session in a dedicated process, and thus using kernel-level protection (Dedicated Process mode of deployment). In the case of a bug, data from other sessions cannot be accessed and this is guaranteed by the kernel. This feature is especially valuable in sensitive areas such as financial transactions.

In other web application frameworks, such as Python/PHP/Java solutions, cross-talk between sessions is always a risk since sessions run within the same process for performance reasons since virtual machines and byte interpreters take their time to load. Cross-talk can be the consequence of a programming mistake where data structures are shared between sessions. In fact, many popular Java servlet-based frameworks encourage sharing of data structures, again for performance reasons, to avoid (expensive) object creation. For example, in struts form beans should be shared, and be reused by reinitialization rather than reconstruction.

Buffer over-runs: A low-level C programming mistake is abused by an attacker to exucute arbitrary code.

While it is true that C applications may suffer this problem, this is no longer a valid concern for modern C++ code. The main source of these programming mistakes was string manipulation in C, relying on careful memory management of the string buffers. In C++, std::string avoids this issues entirely by automated memory management and buffer sizing. Furthermore, Wt is developed using the highest standards for code clarity, and is thoroughly checked for memory-related problems by running it through memory checking tools such as valgrind.

All these attacks (except for the last one) are commonly exploited against current-day web applications which are vulnerable by the simple fact that too many web-related details are in the hands and responsibility of the developer. In contrast, Wt actively helps in avoiding programming mistakes which may lead to these exploits.

h3. Q: How do I use the built-in HTTPS server in wthttpd ?

You will need a private server key that is signed by a certificate authority, and a temporary file containing random Diffie-Hellman parameters. If you are simply experimenting with the feature, then you can create and sign a key yourself, or use the one that comes with the OpenSSL distribution (server.pem, which has the password 'test'). The file with Diffie-Hellman parameters can be created using the command:

$ openssl dhparam -check -text -5 512 -out dh512.pem

Then start Wt using:

$ ./app.wt --https-address=0.0.0.0 --ssl-certificate=server.pem --ssl-private-key=server.pem --ssl-tmp-dh=dh512.pem

Provide the password at the prompt.

h2. Trouble shooting

h3. Q: My application crashes, and my apache error log shows no information.

There is a known problem with mod_fcgid: STDERR (including everything printed to std::cerr) is not
saved to the apache error log.

Wt uses STDERR by default for all error reporting. You can use a different log file in your wt_config.xml file ().

You may also consider using mod_fastcgi or the built-in web server (wthttpd) during development. The latter is especially convenient for development as it allows you to start from within a debugger, or diagnose memory-related problems with valgrind.