AISL Handbook

This document describes main concepts and API of AISL library v.1.0.x.

Last update: 2019-06-16

Table of Contents

• AISL Overview
  • Features
  • Installation
  • Getting started — Hello World
  • Getting advanced
• API Reference
  • Class AislInstance
    • Methods:
      • aisl_new
      • aisl_free
      • aisl_run_cycle
      • aisl_sleep
  • Class AislServer
    • Methods:
      • aisl_server_get_instance
      • aisl_server_get_address
      • aisl_server_get_ssl
  • Class AislClient
    • Methods:
      • aisl_client_get_server
      • aisl_client_get_address
      • aisl_client_get_http_version
      • aisl_client_disconnect
      • aisl_client_is_secure
      • aisl_client_is_online
  • Class AislStream
    • Properties access methods:
      • aisl_is_secure
      • aisl_get_server
      • aisl_get_client
      • aisl_get_instance
      • aisl_get_http_version
      • aisl_set_context
      • aisl_get_context
      • aisl_set_output_event
      • aisl_get_output_event
    • Response methods:
      • aisl_response
      • aisl_header
      • aisl_header_printf
      • aisl_header_vprintf
      • aisl_printf
      • aisl_vprintf
      • aisl_write
      • aisl_puts
      • aisl_flush
      • aisl_reject
  • Enumeration AislStatus
    • Functions:
      • aisl_status_to_string
  • Enumeration AislEvent — AISL event model
    • Values:
      • AISL_EVENT_SERVER_READY
      • AISL_EVENT_SERVER_ERROR
      • AISL_EVENT_CLIENT_CONNECT
      • AISL_EVENT_CLIENT_DISCONNECT
      • AISL_EVENT_STREAM_OPEN
      • AISL_EVENT_STREAM_HEADER
      • AISL_EVENT_STREAM_INPUT
      • AISL_EVENT_STREAM_REQUEST
      • AISL_EVENT_STREAM_OUTPUT
      • AISL_EVENT_STREAM_CLOSE
      • AISL_EVENT_STREAM_ERROR
    • Callback:
      • AislCallback — AISL event callback prototype
    • Payloads:
      • struct aisl_evt — Common event payload
      • struct aisl_evt_open — Event specific payload
      • struct aisl_evt_header — Event specific payload
      • struct aisl_evt_input — Event specific payload
    • Functions:
      • aisl_event_to_string
  • Enumeration AislHttpVersion
    • Functions:
      • aisl_http_version_to_string
  • Enumeration AislHttpMethod
    • Functions:
      • aisl_http_method_to_string
  • Enumeration AislHttpResponse
    • Functions:
      • aisl_http_response_to_string
  • Configuration Structures
  • struct aisl_cfg — Engine configuration
  • struct aisl_cfg_ssl — SSL configuration
  • struct aisl_cfg_srv — HTTP Server configuration

AISL Overview

If you are reading this, either you are somehow already familiar with web applications and web servers and you probably used to count them as an independent entities. Indeed, most of the existing web technologies are based on standalone web server and HTTP parser that together provide some programming interface to work with cached in memory and on a hard disk HTTP request. It is not that efficient and sometimes even vulnerable in sence of DDoS attacks.

AISL works differently. Using AISL you can create web application that is a web server. It means that developer can keep under control all the workflow of an HTTP stream, by appropriate reactoin on triggered by AISL programmable events, which is a great performance and security advantage. For example, application may want to already start some routines to prepare response, when just first line of the HTTP request like GET /index.html HTTP/1.1 was received. Or it may also want to ignore some of the HTTP headers or even full body content to preserve resources and CPU time, if they are unnecessary or even unwelcome.

Features

• Asynchronous event-based engine
• Lightweight solution: size of the shared C library is just about 38 Kbytes.
• HTTP 1.x support (support of HTTP 2.0 is planned).
• HTTPS support (using openssl).
• Free software with open source code.
• CC BY-ND 4.0 License.

Installation

One can get AISL sources from GitHub at any time. Master branch is always stable. To get the Library follow these steps:

1. Clone GIT repositroy$ git clone https://github.com/lowenware/aisl.git
2. Navigate to cloned folder$ cd aisl
3. Compile the library$ make PREFIX=/usr/local LIB_DIR=lib Set PREFIX to preffered installation path and LIB_DIR to your system related name of library directory (lib, lib32 or lib64).
4. Install the library$ sudo make install
5. Optionaly advanced users may want to build library with one or more options: AISL_WITH_SSL=0 - disable HTTPS support, AISL_WITH_STRINGIFIERS=0 - disable several optional *_to_string functions to preserve library sizea, AISL_WITH_DEBUG=1 - enable library debug output.
6. You may also want to edit (if you have changed PREFIX or LIB_DIR) and copy libaisl.pc.example file to /usr/lib/pkgconfig, so pkgconfig could be used to simplify future linking.

Getting started - Hello World

If you have AISL installed, it is time to try it out with simple `Hello World!` application. Full source code could be found on a GitHub and the most important steps are highlighted bellow.

Include AISL meta-header file to add necessary declarations to you code file. You should never include other AISL header files in to your projects.

In this example we create one HTTP server without encryption, that will listen to port 8080 on all available network interfaces.

To initialize configuration structure we use default values.

An address of the defined servers configuration and their number must be also stored in the structure.

Event handler is a core function of the web application. It should match AislCallback prototype and its address also must be stored in the configuration structure before library initialization.

When configuration is ready, it is time to allocate and initialize our AislInstance and start application loop.

Function aisl_run_cycle being called within a loop does all the core routines of our HTTP server and triggers event callback defined in configuration structure. To avoid unnecessary CPU loading we also execute aisl_sleep on idle cycles. To release allocated by AISL resources on a runtime we are using aisl_sleep.

And finally it is time to define the event handler matching AislCallback prototype.

The function is being called by AISL engine on every event, but proceeds only if AISL_EVENT_STREAM_REQUEST is received. It starts an HTML response stored in html constant. Make sure you use sizeof (htmk)-1 for content length, to avoid unwanted write of last NULL terminating character of html string constant.

To compile the example using GCC and pkgconfig run:

Or specify paths to installed header files and library manualy:

Now execute compiled hello_world binary and open http://localhost:8080 in your browser. If you get any symbol lookup error on execution attempt, try to specify the path to the library in the environment variable:

The result should look like this:

Getting advanced

Right after this chapter you will find full AISL API Reference that guides through all the types and functions. The most significant of them you may already know from the Hello World example. To become an advanced AISL developer, you will need to understand events model and stream concept. The rest of library components carry more auxiliary function.

API Reference

AISL library API has object oriented model. Although C has no objects, it still allows to use transparent data structures to represent classes and functions as methods.

Each AISL component has a library specific prefix:

• Aisl* - for data types (typedefs)
• aisl_* - for functions and structures names
• AISL_* - for constants and macro definitions

Functions, related to some data type (methods), include name of the type in their names, i.e. AislServer - aisl_server_get_address(). There are two exceptions from this rule though introduced for simplicity and shorter names for the functions being used most often: AislInstance and AislStream.

Class AislInstance

This class represents library engine, that could be dynamically allocated in memory. It means that you can have several library instances in one application, though you may never meet a real use case for this.

Every instance may handle several independent HTTP servers running on different network sockets and manages SSL certificates and communication with clients.

Each instance must be configured with proper parameters stored in aisl_cfg data structure with at least one HTTP server and event handler matching AislCallback prototype.

Methods

aisl_new