gd32450i-eval/app/goahead-5.1.0/doc/contents/ref/architecture.html

{
    title:  "Architecture",
    crumbs: [
        { 'Reference Guide': '../ref/' },
    ],
}
            <h1>GoAhead Architecture</h1>
            <p>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.</p>
           
            <p>GoAhead has an strong feature set including:</p>
            <ul>
                <li>HTTP/1.1</li>
                <li>IPv4 and IPv6</li>
                <li>TLS/SSL</li>
                <li>32 and 64-bit support</li>
                <li>HTTP Keep-Alive</li>
                <li>Transfer chunk encoding</li>
                <li>Server-side Javascript</li>
                <li>Basic, Digest and Form-based Authentication</li>
                <li>Session state storage</li>
                <li>URI routing and rewriting</li>
                <li>Logging</li>
                <li>Security sandboxing</li>
            </ul>
            
            <p>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.</p> 
            
            <a id="components"></a>
            <h2 >Core Components</h2>
            <p>GoAhead has a modular architecture and clean source code. The key components of GoAhead are:</p>
            <table title="Components" class="ui table segment">
                <thead>
                    <tr>
                        <th class="four wide">Component</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                <tr>
                    <td>GoAhead HTTP Core</td>
                    <td>Core HTTP server. Includes services for HTTP protocol handling, socket connection 
                        management and logging.</td>
                </tr>
                <tr>
                    <td class="nowrap">Request Router</td>
                    <td>The request router directs client requests to the appropriate request handler. It 
                        enforces user authentication and general redirection and URI rewriting instructions.</td>
                </tr>
                <tr>
                    <td class="nowrap">Portable Runtime</td>
                    <td>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.</td>
                </tr>
                <tr>
                    <td>Authentication Framework</td>
                    <td>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.</td>
                </tr>
                <tr>
                    <td>Session State</td>
                    <td>Session state storage. This stores per-user state and cookie management.</td>
                </tr>
                <tr>
                    <td>Action Handler</td>
                    <td>The Action handler binds URIs to C functions for simple, easy access to C-language code.</td>
                </tr>
                <tr>
                    <td>File Handler</td>
                    <td>The File handler serves static content such as HTML pages, images and PDF files.</td>
                </tr>
                <tr>
                    <td>Javascript Handler</td>
                    <td>The Javascript web framework is supports embedded server-side javascript.</td>
                </tr>
                <tr>
                    <td>CGI Handler</td>
                    <td>Common Gateway Interface handler for serving pages by running external CGI programs.</td>
                </tr>
                <tr>
                    <td>Secure Sockets Layer (SSL)</td>
                    <td>Secure Socket Layer protocol stack. This is a virtual interface that can selectively support a
                    variety of SSL providers including: the MbedTLS and OpenSSL stacks.</td>
                </tr>
                </tbody>
            </table>
            
            <a id="core"></a>
            <h2>HTTP Core</h2>
            <p>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.</p>
            <p>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.</p>
            
            <a id="router"></a>
            <h2>Request Router</h2>
            <p>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 <i>route.txt</i> 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.</p>
            <p>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.</p>
            
            <p>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.</p>
            
            <a id="runtime"></a>
            <h2>Portable Runtime</h2>
            <p>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.</p>
            <p>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.</p> <p>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.</p>
            <p>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.</p>
            <p>The runtime includes an optional high performance memory allocator. 
            This allocator is useful when the native operating system allocator suffers from memory fragmentation.</p>
            <a id="dynamic"></a>
            <h2 >Dynamic Content</h2>
            <a id="cgi"></a>
            <h3>CGI</h3>
            <p>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.</p>
            <p>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 <a href="../users/cgi.html">CGI</a> for more details.</p>
            <a id="goactions"></a>
            <h3>GoActions</h3>
            <p>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&trade; that is a more
            suitable solution for embedded systems that demand compact and efficient solutions.</p>
            <p>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.</p>
            <p>GoActions are bound to URIs that begin with <i>/action/</i>. 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 <a href="../users/goactions.html">GoActions</a> for more details.</p>
            <a id="jst"></a>
            <h3>Javascript Templates</h3>
            <p>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.</p>
            <p>JST allows the binding of C functions to Javascript functions, so that a JST web page can 
            easily access device or system data.</p>
            <p>See <a href="../users/jst.html">Javascript Templates</a> for more details.</p>
            <a id="security"></a>
            <h2 >Security</h2>
            <p>GoAhead provides a suite of measures designed to increase the security of your web server:</p>
            <ul>
                <li>Secure Sockets Layer</li>
                <li>Authorization directives</li>
                <li>Sandbox directives</li>
                <li>Secure portable runtime</li>
            </ul>
            <h3>Secure Sockets</h3>
            <p>GoAhead supports the MbedTLS and OpenSSL stacks. You can configure both server and/or client
            authentication of certificates. SSL and TLS are supported. Other 3rd party SSL stacks are also available
            via the <a href="https://embedthis.com/catalog/">Pak online catalog</a></p>

            <h3>Authentication</h3>GoAhead provides Basic, Digest and Web-Form based authentication mechanisms. It
            supports both file and PAM-based password backends.
            <h3>Sandboxing</h3>
            <p>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.</p>
            
            <a name="apis"></a>
            <h2 >Embedding APIs</h2>
            <p>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 <a href=
            "../ref/api/goahead.html">GoAhead API</a> for full details.</p>
            <a id="dirs"></a>
            <h2 >GoAhead Directories</h2>
            <p>Here is the list of top level directories in the GoAhead source code distribution.</p>
            <table title="dirs" class="ui table segment">
                <thead><tr><th class="three wide">Name</th><th>Purpose</th></tr></thead>
                <tbody>
                <tr><td>doc</td><td>Documentation</td></tr>
                <tr><td>package</td><td>Packaging scripts</td></tr>
                <tr><td>projects</td><td>IDE and Makefile projects</td></tr>
                <tr><td>releases</td><td>Release packages</td></tr>
                <tr><td>test</td><td>Unit test directory</td></tr>
                <tr><td>test/web</td><td>Unit test web documents</td></tr>
                <tr><td>utils</td><td>Utility programs</td></tr>
                <tr><td>web</td><td>Web documents directory</td></tr>
                <tr><td>*/inc</td><td>Master include directory</td></tr>
                <tr><td>*/bin</td><td>Output for binaries</td></tr>
                <tr><td>*/obj</td><td>Output directory for objects</td></tr>
                </tbody>
            </table>
            <a id="files"></a>
            <h2 >GoAhead Files</h2>
            <p>Here is a list of the major files in the GoAhead source code distribution.</p>
            <table title="files" class="ui table segment">
                <thead><tr><th class="three wide">Name</th><th>Purpose</th></tr></thead>
                <tbody>
                <tr><td>auth.c</td><td>Authorization management</td></tr>
                <tr><td>cgi.c</td><td>CGI handler</td></tr>
                <tr><td>crypt.c</td><td>Crypto routines</td></tr>
                <tr><td>file.c</td><td>File handler for static documents</td></tr>
                <tr><td>galloc.c</td><td>Optional fast memory allocator</td></tr>
                <tr><td>goahead.c</td><td>GoAhead server main program</td></tr>
                <tr><td>goahead.h</td><td>GoAhead master include header</td></tr>
                <tr><td>http.c</td><td>HTTP core engine</td></tr>
                <tr><td>js.c</td><td>GoAhead Javascript language</td></tr>
                <tr><td>js.h</td><td>Javascript header</td></tr>
                <tr><td>jst.c</td><td>Javascript Templates handler</td></tr>
                <tr><td>options.c</td><td>Options and Trace method handlers</td></tr>
                <tr><td>rom-documents.c</td><td>Compiled web pages into C code</td></tr>
                <tr><td>rom.c</td><td>ROM file system</td></tr>
                <tr><td>route.c</td><td>Request router</td></tr>
                <tr><td>route.txt</td><td>Route configuration</td></tr>
                <tr><td>runtime.c</td><td>Portable runtime layer</td></tr>
                <tr><td>socket.c</td><td>Socket management</td></tr>
                <tr><td>upload.c</td><td>File upload handler</td></tr>
                </tbody>
            </table>
            <a id="additional"></a>
            <h3 >GoAhead Additional Files</h3>
            <table title="additional" class="ui table segment">
                <thead><tr><th class="three wide">Name</th><th>Purpose</th></tr></thead>
                <tbody>
                <tr><td>configure</td><td>Configuration script</td></tr>
                <tr><td>Makefile</td><td>Top-level Makefile</td></tr>
                <tr><td>main.me</td><td>Primary MakeMe configuration</td></tr>
                <tr><td>*/inc/me.h</td><td>Generated MakeMe include header</td></tr>
                <tr><td>build/OS-ARCH-PROFILE/platform.me</td><td>Generated MakeMe configuration file</td></tr>
                <tr><td>server.key.pem</td><td>Test SSL private key</td></tr>
                <tr><td>server.crt</td><td>Test SSL certificate</td></tr>
                </tbody>
            </table>