{ title: "Architecture", crumbs: [ { 'Reference Guide': 'index.html' }, ], }

# GoAhead Architecture

The GoAhead web server is the worlds most popular embedded web server and has been embedded in hundreds of different products and hundreds of millions of devices. GoAhead is a compact and efficient webserver with simple clean code and APIs.

GoAhead has an strong feature set including:

- HTTP/1.1
- IPv4 and IPv6
- TLS/SSL
- 32 and 64-bit support
- HTTP Keep-Alive
- Transfer chunk encoding
- Server-side Javascript
- Basic, Digest and Form-based Authentication
- Session state storage
- URI routing and rewriting
- Logging
- Security sandboxing

GoAhead is extremely efficient. It runs as a single-threaded, event driven, non-blocking process. GoAhead is very small (from 600K) and very fast. On a PC class system, it will serve over 10,000 requests per second.

## Core Components

GoAhead has a modular architecture and clean source code. The key components of GoAhead are:

Component | Description
--- | ---
GoAhead HTTP Core | Core HTTP server. Includes services for HTTP protocol handling, socket connection management and logging.
Request Router | The request router directs client requests to the appropriate request handler. It enforces user authentication and general redirection and URI rewriting instructions.
Portable Runtime | Cross-platform, single-threaded, non-blocking event-based portable runtime. Includes services for memory allocation, safe string handling, lists, hashing, command execution, socket communications, events, timers, debug trace and logging.
Authentication Framework | Pluggable authentication. Supports Basic, Digest and Web Form-based authentication schemes. This includes a Role-based authorization scheme to access to resources can be controlled on a granular basis.
Session State | Session state storage. This stores per-user state and cookie management.
Action Handler | The Action handler binds URIs to C functions for simple, easy access to C-language code.
File Handler | The File handler serves static content such as HTML pages, images and PDF files.
Javascript Handler | The Javascript web framework is supports embedded server-side javascript.
CGI Handler | Common Gateway Interface handler for serving pages by running external CGI programs.
Secure Sockets Layer (SSL) | Secure Socket Layer protocol stack. This is a virtual interface that can selectively support a variety of SSL providers including: the MatrixSSL and OpenSSL stacks.

## HTTP Core

The GoAhead HTTP core is responsible for parsing client HTTP requests and directing how the request will be processed. The HTTP core reads client requests and parses the request headers. It then invokes the GoAhead request router to process the request.

The HTTP core includes services for: the main HTTP processing, socket communications, and logging. The HTTP core server also manages and enforces the sandbox resource limits that have been defined at build time. These limits enable GoAhead to be more deterministic in its use of system resources and to be a good system citizen.

## Request Router

GoAhead includes a powerful request router that manages how client HTTP requests are processed. The router is configured with a set of routes from the route.txt configuration. When a request is received, the router tests various routes and selects the best route to handle the request. In the process, routes may redirect or rewrite the request as required.

A GoAhead configuration will typically have many routes. The configured routes are tested in-order by matching the route URI pattern against the request URL. A route may require that further preconditions be met before it is suitable to process the request. If the required conditions are not met, the next route in the configuration will be tested. There is always a catch-all route that will process the request if all prior routes fail to qualify.

Once a route is selected, the specified request handler is invoked to service the request. GoAhead has handlers for CGI, Javascript and static file data.

## Portable Runtime

GoAhead is built upon a portable runtime layer that insulates the rest of the product from the underlying platform and allows it to be highly portable to new operating systems or hardware.

The GoAhead runtime provides a suite of services that facilitate the creation of secure, embedded applications including: events, networking, safe string handling, timers, hashing, lists and logging.

The runtime also provides a safer environment in which to program as it replaces 'C' APIs that are prone to buffer overflows and other similar security exploits. The runtime includes a high performance, safe string library that supports a secure programming style.

The runtime's event processing can be easily integrated into existing applications. It supports single and multi-threaded architectures, polled or async event notification. This flexibility means that GoAhead can be easily integrated into most C/C++ applications.

The runtime includes an optional high performance memory allocator. This allocator is useful when the native operating system allocator suffers from memory fragmentation.

## Dynamic Content

### CGI

The Common Gateway Interface (CGI) is a standard for interfacing external applications with web servers. CGI was originally developed as part of the NCSA HTTP server and is an old standard for interfacing external applications with HTTP servers. It still enjoys considerable use.

CGI scripts are written in any language that can read from the standard-input, write to the standard-output, and access environment variables. This means that virtually any programming language can be used, including C, Perl, or even Unix shell scripting. See CGI for more details.

### GoActions

CGI is a slow technique for creating dynamic web pages as it creates a new process for every request. This is slow and cumbersome. GoAhead provides a high-performance replacement called GoActions™ that is a more suitable solution for embedded systems that demand compact and efficient solutions.

GoActions are "C" language functions that are bound directly to specific URIs. They respond to client requests without creating a new process for each request. By sharing the address space with GoAhead, GoActions can directly access the full request context and device/application specific data.

GoActions are bound to URIs that begin with /action/. When a client requests a URI beginning with /action, the action handler looks for a defined GoAction of the correct name. Then the bound C function is invoked to service the request. See GoActions for more details.

### Javascript Templates

Javascript Templates (JST) use Javascript code directly embedded in HTML web pages. The Javascript is run on the server and the result when the code executes is substituted back into the web page before it is sent to the client.

JST allows the binding of C functions to Javascript functions, so that a JST web page can easily access device or system data.

See Javascript Templates for more details.

## Security

GoAhead provides a suite of measures designed to increase the security of your web server:

- Secure Sockets Layer
- Authorization directives
- Sandbox directives
- Secure portable runtime

### Secure Sockets

GoAhead supports the OpenSSL and MatrixSSL SSL stacks. You can configure both server and/or client authentication of certificates. SSL and TLS are supported.

### Authentication

GoAhead provides Basic, Digest and Web-Form based authentication mechanisms. It supports both file and PAM-based password backends.

### Sandboxing

Sandboxing is the term applied to running GoAhead in a confined environment. GoAhead has a set of build-time directives that define a sandbox which limits the resources that GoAhead may used.

## Embedding APIs

GoAhead also provides a detailed API so you can create an embedded web server instance and control virtual hosts, port binding, directory and location blocks and every other part of GoAhead. See the GoAhead API for full details.

## GoAhead Directories

Here is the list of top level directories in the GoAhead source code distribution.

Name | Purpose
--- | ---
doc | Documentation
package | Packaging scripts
projects | IDE and Makefile projects
releases | Release packages
test | Unit test directory
test/web | Unit test web documents
utils | Utility programs
web | Web documents directory
*/inc | Master include directory
*/bin | Output for binaries
*/obj | Output directory for objects

## GoAhead Files

Here is a list of the major files in the GoAhead source code distribution.

Name | Purpose
--- | ---
auth.c | Authorization management
cgi.c | CGI handler
crypt.c | Crypto routines
file.c | File handler for static documents
galloc.c | Optional fast memory allocator
goahead.c | GoAhead server main program
goahead.h | GoAhead master include header
http.c | HTTP core engine
js.c | GoAhead Javascript language
js.h | Javascript header
jst.c | Javascript Templates handler
openssl.c | OpenSSL interface
options.c | Options and Trace method handlers
rom-documents.c | Compiled web pages into C code
rom.c | ROM file system
route.c | Request router
route.txt | Route configuration
runtime.c | Portable runtime layer
socket.c | Socket management
upload.c | File upload handler

### GoAhead Additional Files

Name | Purpose
--- | ---
configure | Configuration script
Makefile | Top-level Makefile
main.me | Primary MakeMe configuration
*/inc/me.h | Generated MakeMe include header
build/OS-ARCH-PROFILE/platform.me | Generated MakeMe configuration file
server.key.pem | Test SSL private key
server.crt | Test SSL certificate