Skip to content

Embedded modules API

Jump to bottom
Pavel Kraynyukhov edited this page Jul 28, 2019 · 18 revisions

All bellow modules are embedded into LAppS and will be pre-loaded into your service conditionally or in two cases unconditionally.

One module will be pre-loaded unconditionally into your service:

  • nljson

This module is available to both kind of services (Standalone and Reactive).

For the Standalone services a global function "boolean must_stop()" is pre-loaded unconditionally as well (see bellow).

For the Reactive services a ws module will be pre-loaded unconditionally.

All other modules are conditionally pre-loaded into service, whenever it is configured in a service descriptor in lapps.json or in the deployment archive descriptor with preload attribute (an array of strings).

nljson

nljson - is a module for encoding/decoding JSON objects to/from a string representation. It does not decode JSON-strings into native Lua tables, instead, it decodes it into userdata objects of nljson type. It is capable of encoding Lua tables into nljson objects. The nljson objects can be easily and very efficiently converted to/from CBOR vectors. It acts as a replacement for Lua native tables giving the Lua applications the possibility to overcome the 1GB memory limit.

Hereafter any object of nljson type (a lua userdata), will be noted as nljson_object

Basic access to elements of nljson_object is the same as in lua-tables (using [] and dot-walking).

functions

  • nljson_object nljson.decode(string) - decodes a string and returns an nljson_object
  • nljson_object nljson.decode_file(filename) - decodes a file, with the given filename and returns an nljson_object
  • string nljson.encode(nljson_object) - encodes an nljson_object and returns string
  • string nljson.to_cbor(nljson_object) - encodes a given nljson_object and returns the CBOR vector (lua native string)
  • nljson_object nljson.from_cbor(string) - encodes given CBOR vector represented by string and returns the nljson_object
  • value_type nljson.find(nljson_object,string) - finds a key within nljson_object represented by string and returns a value. This may be a value of an integer, nil, double, string or the nljson_object type. If no item with given key was found a nil is returned.
  • void nljson.foreach(nljson_object,callback) - calling the callback function for each pair in the nljson_object tree.
  • void nljson.traverse(nljson_object,callback) - traversing through the nljson_object tree and calling a callback with 2 arguments for each item, - the key and its value. The difference with nljson.foreach is that traverse iterates through all the elements recursively.
  • string nljson.encode_pretty(nljson_object,[indent]) - encode native nljson_object as a JSON-string with optional indentation (default 2)
  • boolean nljson.empty(nljson_object) - returns true if provided nljson_object is empty, false otherwise.
  • string nljson.typename(nljson_object) - returns name of the type for given nljson_object. Returns a string value: "null", "boolean","string","number","object","array".

ws

ws is the server side mapping to LAppS WebSockets server API. It is a Lua pre-loaded module which has only two methods: send and close. The interface of the methods depends on the type of protocol an application is using.

  • Interface for raw protocol
    • boolean,[string] ws:send(handler,opcode,string) - on success only true is returned, on fail the false and the error message are returned.
      • handler - integer value received as an argument of onMessage method of your application.
      • opcode - WebSocket's opcode. The valid opcode-s are the 1 (TEXT) and 2 (BINARY). Any other opcodes will result in a failure as result of the call to this method.
      • string - is the message you would like to send to the client. NOTE: Lua strings are capable of containing binary data.
    • boolean,[string] ws:close(handler, close_code[,string]) - on success only true is returned, on fail the false and an error message are returned.
      • handler - integer value received as an argument of onMessage method of your application.
      • close_code - a valid WebSocket's close code as defined in RFC 6455.
      • string - is an optional error message for close frame.
  • Interface for LAppS protocol
    • boolean,[string] ws:send(handler,nljson_object) - on success only true is returned, on fail false and the error message are returned.
      • handler - integer value received as an argument of onMessage method of your application.
      • nljson - an nljson object with the message as defined in LAppS protocol specification 1.0. This method validates the message you would like to send. Invalid messages will result in an error upon execution of this method. The application might be shutdown for the reason of violating LAppS protocol.
    • boolean,[string] ws:close(handler, close_code[,string]) - on success only true is returned, on fail false and an error message are returned. This method behaves exactly the same for LAppS protocol as for raw protocol.

cws

cws is the client WebSockets module, which has following public methods:

  • int [,string] cws:new(URI,callbacks) - create new connection to WebSockets URI, and use the callbacks table to look for WebAPI methods. Return values are: an integer file descriptor, or nil. If file descriptor is nil, then error message is returned as well. Here is an example of usage:
    local sock, err_msg=cws:new(benchmark.target,
    {
      onopen=function(handler)
        local result, errstr=cws:send(handler,benchmark.message,2);
        if(not result)
        then
          print("Error on websocket send at handler "..handler..": "..errstr);
        end
      end,
      onmessage=function(handler,message,opcode)
        benchmark.meter();
        cws:send(handler,message,opcode);
      end,
      onerror=function(handler, message)
        print("Client WebSocket connection is failed for socketfd "..handler..". Error: "..message);
      end,
      onclose=function(handler)
        print("Connection is closed for socketfd "..handler);
      end
    });
  • boolean [,string] cws:send(file_descriptor, data, opcode)
    • file_descriptor is an integer received upon cws:new completion or provided by the callback onmessage method.
    • data - is a string
    • **opcode - 1 or 2 (1 - TEXT, 2 - BINARY)
  • cws::eventLoop() - blocking method to call periodically to poll the event queues. Usage:
  while not must_stop()
  do
    cws:eventLoop();
  end

bcast

The bcast pre-loaded module is available only for LAppS protocol and Standalone services. This module serves a purpose of broadcasting messages to the clients.

  • boolean[,string] bcast:create(channel_id) - create channel with provided channel id. On success returns true. If channel already exists, then this method returns false. Optionally a string with an error message is returned, whenever the usage of this method is incorrect.
  • boolean[,string] bcast:subscribe(channel_id, handler) - subscribes a client specified by IO-handler, to specified broadcast channel. Returns true on success. Returns false if the channel does not exist. Optionally returns an error message, if the usage of this method is incorrect.
  • boolean[,string] bcast:unsubscribe(channel_id, handler) - unsubscribes a client specified by IO-handler, from specified broadcast channel. Returns true on success. Returns false if the channel does not exist. Optionally returns an error message, if the usage of this method is incorrect.
  • boolean[,string] bcast:send(channel_id, message) - queues a broadcast message to specified channel. The `message' must be an nljson OON object. Sending to CCH is forbidden. Returns true if the message is a valid OON object, with cid not equal 0 and the channel is exists, otherwise returns false. Optionally returns an error message on incorrect usage of this method.

nap

Module nap provides sleep methods

  • nap_object nap:new() - creates new instance of a nap object

  • *nap_object:usleep(microseconds) - makes application to wait/sleep for amount of microseconds

  • *nap_object:nsleep(nanoseconds) - makes application to wait/sleep for amount of nanoseconds

  • *nap_object:sleep(seconds) - makes application to wait/sleep for amount of seconds

    • microseconds, nanoseconds, seconds - must be a positive (unsigned) integer

murmur

Is a MURMUR hash module (just a binding to C++ std::hash). It provides two methods:

  1. integer hashnum(value) returns integer hash calculated from value, where value is a string or an integer.
  2. string hashstr(value) returns a 16 characters long string representation of a hex decimal number calculated from value, where value is a string or an integer.

pam_auth

A PAM authentication module which has only one method:

  • boolean,[string] pam_auth:login(service, username, password), authenticate user with name stored in username with given password against service, where all 3 arguments are strings, and service is one of system-wide available (configured) authentication services, like passwd, system-login, openldap, whatever service you find configured in /etc/pam.d.

time

This module consists only one function time.now() which returns UNIX time since epoch begins until now in milliseconds.

mqr

Module for inter-services communications within one server process. This module provides you with the possibility to create and operate low latency message queues, available for all services running on one LAppS node. If you need to send/receive messages between LAppS nodes, then use available bindings to MQ Brokers like RabbitMQ or mosquitto. This module provides the following functions and methods:

Functions

  • mqr_object mqr.create(string) - creates an mqr_object handler for sending/receiving messages, tagged with string value, this method always returns an mqr_object even if called subsequently. If queue with supplied name is already exists then it will not be create instead mqr_object of this queue will be returned. The only available type of messages for create queues are the nljson_objects.

Members

  • boolean, [string] mqr_object:post(nljson_object) - returns true if nljson_object was successfully put into queue, otherwise false and the string with error message.
  • nljson_object mqr_object:recv() - blocking receive of the nljson_object, or nil if error happens (like server goes down).
  • nljson_onject mqr_object:try_recv() - non-blocking attempt to receive a message from queue. On success returns an nljson_object, on fail or empty queue returns nil

Global Functions

must_stop()

  • bool must_stop() - this method is available only for Standalone services. It returns true if LAppS wants to shut down or stop the application. It is better to obey the wish of LAppS and do all necessary steps to shut down the application. Otherwise, LAppS will be unable to stop.
Clone this wiki locally