NAWA is a framework for web applications written in C++(17). It aims to make writing native web apps nearly as easy as writing them in specialized scripting languages (such as PHP). It provides the necessary features, such as sessions, request filters (for providing static elements such as images), and accessing and controlling all aspects of requests and responses (GET, POST, cookies, ...). Scroll on for a list of features.
NAWA communicates with the web server via FastCGI and currently uses the fastcgi++ lite library for efficient request handling.
It also comes with an integrated development web server (HTTP Request Handler) which can serve your application without depending on dedicated web server software (still somehow experimental and unfit for production use).
New in v0.9
Sessions can now be used without cookies by manually passing the session ID when starting
the session. A new overload of nawa::Session::start() has been added for this purpose.
New in v0.8
The configuration can now be reloaded without restarting and apps (and request handling
functions) can be hot-swapped. This allows you to update your app without interrupting
request handling. Reloading can be done via systemd or by sending a SIGHUP signal to
nawarun. If you are using NAWA as a library, take a look at
nawa::RequestHandler::reconfigure().
Almost all data members of classes have become methods, therefore, it is necessary to update existing apps before upgrading. Please note that the project has been extensively restructured, therefore it might also be necessary to correct the includes of existing apps.
Additionally, this release adds support for macOS.
The following example is the complete C++ source code of a NAWA app that answers every request with the "Hello World!". It's that simple.
#include <nawa/application.h>
using namespace nawa;
int init(AppInit &appInit) {
return 0;
}
int handleRequest(Connection &connection) {
connection.responseStream() << "Hello World!";
return 0;
}You want to learn more? Read the full introduction tutorial.
If you don't like the IoC-style approach, you can also use NAWA as a library. An introduction can be found here.
This project is still in an early state (version 0.9!). It might, of course, still contain bugs. Use it at your own risk.
If you use it, please report any bugs and wishes, so that this project might reach a higher version number at some point :)
Also, the ABI and API can still change at any time, making modifications to your apps (or, at least, recompilation) necessary. When such changes happen, the version number will be increased, and nawarun will refuse to load apps compiled against an older version.
- Request Handling Backends (learn more)
- FastCGI (serve requests through web server software)
- HTTP (development web server, not production-ready yet)
- Access to request data (learn more)
- GET, POST, COOKIE variables
- Request headers
- Request details (document root, request method, client IP, ...)
- Environment information (server software, server IP, ...)
- Defining the response (learn more)
- Set response body directly or using a stream
- Set response headers
- Set cookies
- Default options for cookie security
- Flush response prematurely
- Respond with files from disk (incl. automatic setting of relevant response headers)
- Automatically generate and send error pages
- Sessions (learn more)
- Full-featured session management
- Session security options
- Start sessions automatically (optional)
- Set and get session variables of arbitrary types
- Request Filters (learn more)
- Filter requests based on path, file extensions, or regular expressions
- Serve filtered requests with files from disk (forward filter)
- Block filtered requests with error pages
- Require HTTP authentication for filtered requests
- Email (learn more)
- Create emails with headers
- MIME email and attachment support
- Automatic quoted-printable or base64 encoding (if desired)
- Q-encoding for subjects
- Replacement rules for personalizing mass emails
- Sending emails via SMTP
- Cryptographic functions
- Password hashing (bcrypt, Argon2)
- Classic hashing (SHA-1, SHA-2, MD5)
- Encoding and decoding functions
- HTML entities
- URL encoding
- Base64, quoted-printable, Q-encoding, encoded-word
- Punycode for internationalized domain names
- Utility functions
- Regular expressions with callback
- Convert strings to uppercase and lowercase
- Generate error pages
- Deduct content types
- HTTP and SMTP time formatting
- String and UNIX path splitting and merging
- Line ending conversion
- Load files into strings
- Parse headers and cookies from raw HTTP
- Core features
- Multi-threaded request handling (configurable)
- Hot-swapping of apps and request handling functions
- Reload configuration without interrupting request handling
A NAWA app consists of:
- A simple config file with properties concerning the behavior of the application, and
- A shared object file containing the application itself.
You can find an introduction containing a simple "Hello World!" NAWA app here: Getting started.
The path to the object file is included in the config file, and NAWA will take care of setting everything up and starting the app. You can run it like this:
nawarun /path/to/config.ini (or just nawarun if the file is named
config.ini and located in the current working directory).
Run nawarun -h or nawarun --help for information on command line
options (config overrides, starting without config file).
If systemd is present on your system, a systemd service file will also be installed on your system. You can start an app as a daemon using the path to its ini file (/path/to/config.ini):
sudo systemctl start [email protected]
For automatically starting an app on boot, use systemctl enable.
NAWA has been tested especially on Linux, but also runs fine on macOS (both as a library and using nawarun) (1). It will probably also run on other BSD derivates, but this has not been tested.
Windows is not supported and never will be.
Please note: All commands in the following instructions should be
run as an unprivileged user. Commands which must run as root are
prepended with sudo.
(1) Please note that due to a bug in Apple Clang, building will only
succeed with gcc, which can be installed using homebrew. Other dependencies
may also be installed using homebrew. Compiling with Apple Clang works fine
on macOS 12, dependencies still have to be installed from homebrew.
For running NAWA apps via nawarun / applications using libnawa:
- OpenSSL >= 1.1.1
- libcurl4 >= 7.58.0
- libboost-system >= 1.62.0
- libboost-thread >= 1.62.0
- libargon2 >= 0~20161029-1.1 (only if built with Argon2 support)
For building (additionally):
- libssl (OpenSSL) development files >= 1.1.1
- (lib)boost, (lib)boost-system, (lib)boost-thread development files >= 1.62
- libcurl4 development files >= 7.58.0
- libargon2 development files >= 0~20161029-1.1 (only if building with Argon2 support)
- git
- cmake >= 3.13
- gcc-c++/g++ or clang compiler with C++17 support
For building the docs, doxygen must be installed. However, you can also access the docs online.
To build nawarun, pull the source code, open a terminal, and switch to the NAWA directory. If you haven't pulled the source code yet, do it:
git clone https://github.com/jatofg/nawa.git nawa
cd nawa
First, create a directory for the build files:
mkdir build
cd build
Create the build configuration:
cmake -DCMAKE_BUILD_TYPE=RELEASE ..
Note: You can pass some arguments to cmake to influence the build configuration:
- Build the tests as well:
-DBuildTests=ON - Build NAWA as shared library:
-DBuildSharedLib=ON - Build the nawa_static static library:
-DBuildStaticLib=ON - Do not build nawarun:
-DBuildNawarun=OFF - Disable building the examples:
-DBuildExamples=OFF - Disable building docs:
-DBuildDocs=OFF(disabled automatically if doxygen is not installed) - Disable Argon2 support:
-DEnableArgon2=OFF
Build NAWA (nawarun and the shared library, tests, examples, and docs, depending on your cmake arguments):
make
And last, install it to the target directories so that the apps can find it (this will also install the headers needed for app development):
sudo make install
In the build directory, run:
sudo xargs rm < install_manifest.txt
Uninstalling before installing a new version is recommended to avoid ancient relics remaining on your system.
Binary packages are not available yet, just build it yourself :)
This project includes the following libraries (in the libs directory) with different (less strict) licenses:
- base64: see
libs/base64/LICENSEfor details - inih: New BSD License, see
libs/inih/LICENSE.txtfor details - libbcrypt: CC0, see
libs/libbcrypt/COPYINGfor details - punycode: MIT License, see
libs/punycode/LICENSEfor details
It automatically downloads the following libraries during build configuration:
- fastcgilite (also LGPL-licensed)
- cpp-netlib (Boost Software License)