Prosody module API

API

Module

module:get_name()

An API method for the forgetful.

module:get_host()

Returns the host this module is loaded on. It returns '*' for global modules, which is not a real host. You may also directly read the current host from 'module.host'. Since a module never moves between hosts it is safe to cache this value in a local variable if you use it a lot.

module:get_host_type()

Returns the type of the current host. Possible values map to different types of host defined in the config file. It returns "local" for a normal VirtualHost, and "component" for one defined as a Component.

The main different between a VirtualHost and a Component is that users log into one but not the other. A global module is not associated with a host, and this method will return nil for such a module.

module:set_global()

This sets a module as global. A global module is not associated with any particular host (module.host will be set to '*').

If you have a module that needs to mix per-host activities (e.g. events) with some global things (such as a listening port) then you should read up on shared modules.

module:get_directory()

Returns the filesystem directory that this module was loaded from. If you want to load files from this directory, see module:load_resource().

module:load_resource(path, mode)

Opens a resource file and returns the Lua file handle, or nil and an error message. path is the path to the file, if it is not absolute then it is treated as relative to the module's main file, so that module:load_resource('data.json') will open a file data.json from the same directory as the module's .lua file.

Configuration

module:get_option(option_name, default_value)

This retrieves a value from the config file, defaulting to the value specified for the current host if any. Otherwise it looks for the value in the global section of the config. Finally it returns default_value if that is specified.

There are a number of variants of this method that should be used for specific data types. These all have the same syntax as module:get_option(), but are accessed as module:get_option_type() (replacing type by the name of the type you expect). They automatically convert between types where applicable, and warn the user if the value in the config file is incorrect. Available types are:

  • string
  • number
  • boolean
  • array (see util.array)
  • set (see util.set)
  • inherited_set (see explanation below)

module:get_option_inherited_set() differs from the set variant in that it returns the union of the global and host-specific options, if both exists.

module:get_option_path() behaves similar to string but takes the additional step of resolving a relative file path into an absolute one. It takes a third argument parent in addition to option_name and default_value, which specifies the parent directory if the configuration option is a relative filename. If left empty, it will be relative to the module directory. Other options are:

  • "config" – the configuration directory
  • "data" – the data directory
  • "source" – the path prosody was installed into
  • or any directory name

Events

module:fire_event(event_name, data)

Fires the specified event on the current host (or a global event if the current module is global). If data is given it is passed to event handlers. If any handler returns a value (that isn't nil) then processing will halt and that value will be returned.

module:hook(event_name, handler, priority)

Add a handler for the specified event on the current host, with the current priority. The priority defaults to zero, but may be any number (including negative and floating-point). Handlers with a higher priority are executed first.

Returning any value other than nil will halt processing of the event, and return that value to the code that fired the event.

Standard event names are documented in our events reference.

module:hook_global(event_name, handler, priority)

The same as module:hook(), but hooks a global (server-wide) event.

For global modules this method is exactly equivalent to module:hook().

This method was added in Prosody 0.9.

module:hook_object_event(event_name, handler, priority)

Less-commonly needed, this variant allows you to add a hook to any util.events object. That is, any object with compatible add_handler() and remove_handler() functions.

It is better to use this method than manually adding a handler to an events object with events.add_handler() so that the handler will be correctly removed when the module is unloaded.

This method was added in Prosody 0.9.

module:hook_tag(xmlns, name, handler, priority)

A convenience function to build the correct event string to hook a stream-level element, such as those used in negotiation of stream features. The 'xmlns' and 'name' parameters specify the namespace and tag name of the element. The 'handler' and 'priority' parameters are equivalent to module:hook()'s.

module:unhook(event_name, handler)

Remove a handler for a given event, that was previously added by one of the module:hook() methods.

This method was added in Prosody 0.10.

Communication

module:send(stanza)

Sends a stanza from the current host. Must have valid 'to' and 'from' addresses. Uses stanza_router.core_post_stanza() internally.

This method was added in Prosody 0.9.

Timers

module:add_timer(delay, callback)

Triggers callback after the specified delay (in seconds, but may be contain a fraction part). If the callback returns a number, this is used as a new delay, and the timer repeats.

The timer is removed when the module is unloaded.

This method was added in Prosody 0.9.

Sharing code and data

module:require(lib_name)

Loads a plugin library, "lib_name.lib.lua", using the same search paths as for normal modules. The library is loaded into the current module's environment, giving it access to this module API and any other global variables in the module.

module:depends(module_name)

Ensures that another module is loaded before this one. If it is not loaded, loads it.

This method was added in Prosody 0.9.

module:shared(...)

Creates one or more shared tables with the specified names. All shared tables are at virtual paths of the form:

  /host/module/name

However you may specify paths relative to the current host and module. Some examples:

-- Get a shared table called 'sessions' for this module on this host:
local sessions = module:shared("sessions") -- shared at "/current_host/current_module/sessions"
-- Get a shared table called 'sessions' for a module named 'xmpp' on this host:
local sessions = module:shared("xmpp/sessions");
-- Get a table called 'sessions' shared by a global module called 'notify':
local sessions = module:shared("/*/notify/sessions");

There is no way to set a shared table, an empty table is created automatically for the first module to access it. Shared tables are automatically released when no loaded modules are using them.

This method was added in Prosody 0.9.

module:context(host)

Produces a fake API context for a given host (or global). E.g. module:context("*"):get_option("foo") to get global options.

This method was added in Prosody 0.9.

Service discovery

module:add_feature(var)

Adds a XEP-0030: Service Discovery feature to the current host.

This is to signal to a client that Prosody supports a certain XMPP extension, for example. These features are usually given in the "Discovering support" section of the relavent XEPs. A full list of all official features in specs published by the XSF can be found at XSF Registrar: Service Discovery Features.

If making your own extension, use a URL of a site that you own. e.g. for Prosody we use URLs of the form http://prosody.im/protocol/* .

module:add_identity(category, type, name)

Adds a XEP-0030: Service Discovery identity to the current host. Identities are similar to features, but rather than telling clients what the host supports it says what the host is. XEPs inform you when a host needs to have a certain identity. A full list of all official identities published by the XSF can be found at XSF Registrar: Service Discovery Categories.

module:add_extension(data)

Adds a XEP-0128: Service Discovery Extensions object to the current host. This must be a util.stanza object in the correct format. See the XEP for further details.

This method was added in Prosody 0.9.

Publishing items

module:add_item(array_name, item)

Every host supports generic arrays of different kinds, to allow modules to add things like disco features and other data. Added items are automatically removed from the array on unload.

This method adds 'item' to the array with the given 'array_name' and fires "item-added/<key>" on the current host.

module:remove_item(array_name, value)

Remove the given value from the array and fires "item-removed/<key>" on the current host.

module:handle_items(array_name, add_handler, remove_handler, handle_existing)

A convenience function for modules that want to watch for item adds and removes on a host.

Simply specify a handler to receive the item-added event, and one to received the item-removed. event. By default the 'add_handler' will also be called for any items that were added prior to this function being called. Set 'handle_existing' to false to ignore existing items in the array and only receive notifications of future adds and removes.

This method was added in Prosody 0.9.

module:get_host_items(array_name)

Returns an array of all items added to the host array with the specified name. This includes items added by global modules.

module:provides(name, item)

This related function is a high-level wrapper around add_item(). The item is added to the array '<name>-provider' (e.g. 'auth-provider' for module:provides('auth', …)).

Also item.name is set to the name of the current module if it is not set already. If the module name is prefixed by 'name' (e.g. mod_auth_foo and name == "auth") then that prefix is first stripped (so that item.name ends up as "foo").

This method was added in Prosody 0.9.

Storage

module:open_store(store, type)

Opens a data store through the Prosody storage API.

  • store: the name of the store to open (modules can create their own stores).
  • type: The type of the store. Common values are:
    • keyval: Simple key-value storage, most commonly supported by storage modules and the default.
    • map: Similar to keyval but with two level keys.
    • archive: Ordered key-value list storage.

The return value is an object that is used to read and write to the store. Available methods depend on the store type and what is implemented by the storage module providing it.

keyval store methods

The key field is usually an username, but this is not required.

  • :get(username): Returns the data stored under this username/key, nil if the store is empty or nil, "error message on errors.
  • :set(username, value): Stores the value data under the specified key. Returns true on success or nil, "error message".
  • :users(): Returns an iterator over all available keys, if implemented. Not provided by all modules.

map store methods

  • :get(key, subkey)
  • :set(key, subkey, value)
  • :set_keys(key, { key = value })

archive store methods

  • :append(username, key, value, when, with): Store a value, which can be an util.stanza object.
    • key is the id of the value, which must be unique in the archive.
    • value is the value, which may be an util.stanza object.
    • when is a timestamp attached to the value
    • with is a metadata string
  • :find(username, query): Find items matching the query, a table with the following possible fields:
    • start and end: Matches items on the with field, inclusive.
    • with: Matches the with field given to :append().
    • before and after: Specifies a range of items by key field, not inclusive.
    • total: Request that a count of the total number of matching items be returned. Not guaranteed to be supported
    • limit: Maximum number of items to return. Use before or after to page.
    • reverse: Boolean true to get items in reverse chronological order.

Metrics

Methods for reporting metrics from modules. For more information see Statistics. Prosody 0.10+ required.

module:measure(type, name)

This function allows you to report useful metrics from your module. The type parameter should be one of:

type Description Examples
amount Report the number of something that varies over time Current memory used
counter Similar to 'amount', but used when the number always goes up and down in steps The number of connected users
rate Count the number of times something happened, when the total is not tracked Stanzas per second
times Time how long something takes (in seconds) Time taken to execute a function, time before a HTTP request is responded to
sizes Measure the size (in bytes) of an item being processed Size of a stanza, or size of a HTTP response
distribution Measure the distribution of any series of values Number of connected resources a user has

The name parameter should be a name for the metric, which begins with a letter and has only letters, numbers or underscores ('_') following that.

This method was added in Prosody 0.10.

module:measure("amount", name, initial)

Creates an 'amount' metric, optionally set to an initial value.

Returns a function that you can call to update the metric value.

Example:

   local measure_memory = module:measure("amount", "memory_used");
 
   -- Example, get the current memory usage
   local memory_used = get_current_memory_usage();
 
   -- Update the metric with the current memory usage
   measure_memory(memory_used);

module:measure("counter", name, initial)

Creates a 'counter' metric (similar to 'amount'), optionally set to an initial value.

Returns a function that you can call to increase or decrease the metric.

Example:

   local measure_connections = module:measure("amount", "connections");
 
   -- Increase the number of connections by 1
   measure_connections(1);
 
   -- Decrease the number of connections by 1
   measure_connections(-1);

module:measure("rate", name)

Creates a 'rate' metric.

Returns a function that you call when the event that you want to count happens

Example:

   -- Create a metric to measure the request rate (requests per second)
   local measure_request_rate = module:measure("rate", "requests");
 
   function handle_request()
       -- Update our metric to indicate a new request was received
       measure_request_rate();
       -- Handle the request
   end

module:measure("times", name)

Creates a 'times' metric.

Returns a function that you can call to start timing something. That function returns another function that you must call to stop timing. If the second function is never called, the time is not recorded in the metric.

Example:

   local measure_request_time = module:measure("times", "request_time");
 
   local mark_request_completed = measure_request_time(); -- Start timing here, and save the 'stop' function
   do_request("https://example.com/", function ()
       -- Request completed!
       mark_request_completed(); -- Stop timing and record the result in the metric
   end);

module:measure("sizes", name)

Creates a 'sizes' metric.

Returns a function that you can call to measure the size of an item in a series of items.

Example:

   local measure_stanza_size = module:measure("sizes", "stanza_sizes");
 
   function handle_stanza(stanza)
       measure_stanza_size(#stanza); -- Record the size (in bytes) of this stanza
   end

module:measure("distribution", name, units)

Creates a 'distribution' metric. The optional units can be specified to be used for display purposes.

Returns a function that you can call to measure a value in a series of values.

Example:

   local measure_resources = module:measure("distribution", "resources", "resources");
 
   -- Record how many connected resources a user has
   measure_resources(#user_info.resources);
 
doc/developers/moduleapi.txt · Last modified: 2017/03/22 15:29 by Kim Alvefur