Developer Documentation

Welcome to the prime page for developer documentation on Prosody.

To get started with writing a module, begin with our introduction to developing Prosody modules. And have a look at the Module API.

Also useful to you, whether writing a module or working on core Prosody code, will be our Utility APIs.

We also have documentation on the various common data structures that Prosody uses internally.

If after reading this you are still clueless, or can’t find what you were looking for, you are strongly encouraged to contact us! We also welcome anyone wanting to contribute to the project itself or the documentation.

Project layout

Most of the code resides in a few different directories.

prosody: Main executable
prosodyctl: Management tool
core/: Core logic
net/: Network and socket handling
util/: Utilities
util-src/: More utilities, but implemented in C
plugins/: Almost all functionality is in plugins
tools/: Tools for migrating data
spec/: Tests using the Busted framework

Core

The Core is a set of modules providing core functionality for the server.

core.certmanager: Manages TLS configuration, certificates etc.
core.configmanager: Handles reading, parsing and accessing the configuration.
core.hostmanager: Manages initialization of virtual hosts.
core.loggingmanager: Deals with setting up log output.
core.moduleapi: Implements the Module API.
core.modulemanager: Handles loading, un- and reloading of plugins.
core.portmanager: Handles setting up TCP port listeners
core.rostermanager: API for managing users contact lists.
core.s2smanager: Manages server-to-server connections.
core.sessionmanager: Managing user sessions.
core.stanza_router: Routes stanzas to the right host and fires the correct events.
core.statsmanager: Statistics collection and reporting API.
core.storagemanager: Manages on-demand loading of storage plugins and the storage API.
core.usermanager: Core API for user account management

Utility APIs

These modules are designed to provide a unified API for both core and module developers. They help with common tasks, and provide useful data structures.

util.adhoc: Convenience library for writing Ad-hoc commands
util.adminstream: Module to manage a local unix domain socket for admin functionality
util.argparse: Parse command line arguments
util.array: Convenience methods for working with Lua tables as arrays
util.async: Library to provide support around coroutine-based non-blocking functions
util.bit53: Compatibility module for bitwise operations (Lua 5.3+)
util.bitcompat: Compatibility module for bitwise operations
util.cache: Ordered key-value least recently used pairs
util.caps: Utility for calculating XEP-0115: Entity Capabilities hashes
util.crand: Binding to native platform RNG
util.dataforms: Utility for handling XEP-0004: Data Forms
util.datamanager: Allows persistent storage and retrieval of data
util.datamapper: Transform data to and from XML using a schema
util.datetime: Retrieve the current or specified time in various XMPP formats
util.dbuffer: Dynamic string buffer library
util.debug: A verbose debug library
util.dependencies: Utility containing Prosodys dependencies
util.dns: Library for decoding DNS records
util.encodings: Encode/decode data using algorithms such as base64, IDNA, stringprep
util.envload: Lua version agnostic library for loading code into an environment
util.error: Library implementing an error or exception object.
util.events: Library to abstract the firing and handling of named events
util.filters: Describe me
util.format: More liberal string formatting
util.gc: Module for configuring the Lua garbage collector
util.hashes: Calculate hashes of input data using MD5, SHA1, SHA256, etc.
util.hashring: Describe me
util.helpers: Library to aid with debugging, etc.
util.hex: Base 16 / hexadecimal encoding and decoding
util.hmac: HMAC functions compat library¹
util.http: Common functions for dealing with HTTP requests
util.human.io: Human interface library
util.human.units: Human-friendly unit formatting
util.id: Generates compact strings suitable for use as identifiers
util.import: Combined require() and unpacking
util.indexedbheap: A priority queue implementation with a reverse index with no per-entry memory allocation.
util.interpolation: A string templating engine
util.ip: Deal with IP address
util.iterators: Iterator library
util.jid: Common functions for splitting and prepping JIDs
util.json: A JSON library
util.jsonschema: JSON Schema validator
util.jwt: JSON Web Token library
util.logger: An interface to Prosody’s logging system
util.mercurial: Small library for identifying Mercturial repositories
util.multitable: A multitable is a handy tree-like data structure, a table allowing multiple keys
util.net: Deals with IP addresses and their representations
util.openmetrics: Library for OpenMetrics-compatible metrics in Prosody
util.openssl: A library for dealing with OpenSSL and certificate configuration
util.paths: File system path handling
util.pluginloader: Library responsible for locating and loading Prosody plugins
util.poll: library for watching file descriptors
util.pposix: A POSIX library
util.presence: Presence priority calculation library
util.promise: ES6-like API for promises
util.prosodyctl: Support functions for the prosodyctl tool
util.pubsub: Abstract Publish-Subscribe library
util.queue: A library for first-in, first-out queues
util.random: Produce pseudorandom byte strings
util.rfc6724: Library for doing address selection per RFC6724
util.ringbuffer: A ringbuffer for binary data
util.rsm: XEP-0059: Result Set Management library
util.sasl_cyrus: SASL logic used by mod_auth_cyrus
util.sasl: Abstract SASL middleware library
util.serialization: Convert objects into a format suitable to save to disk or send across the network
util.session: Common session methods
util.set: A Set library
util.signal: Send and handle process signals (SIGKILL etc)
util.sql: SQL abstraction library
util.sslconfig: Abstraction over LuaSec SSL context configuration
util.stanza: Create and manipulate stanzas and other XML objects
util.startup: Prosodys startup logic
util.statistics: Provider for in-memory buffered metrics
util.statsd: Provider for pushing metrics to a statsd server
util.strbitop: Perform bit-wise operations on strings
util.table: Small library to complement Luas built-in table module
util.template: XML stanza template library
util.termcolours: Library for producing ANSI colour codes
util.throttle: Token bucket implementation
util.time: Low-level time functions
util.timer: Set callbacks to be called after a specified delay
util.uuid: Generate unique string identifiers
util.vcard: Abstract vCard library
util.watchdog: Watchdog timer library
util.windows: Windows OS support functions
util.x509: Functions for X.509 certificate identity matching
util.xml: Simple XML parsing library
util.xmppstream: Streaming XML parsing library
util.xpcall: Compat library providing protected Lua function calls with error handler
util.xtemplate: Another template language for mapping stanzas to text or HTML.

Specific Modules

These are prosody modules that have an API that can be used from other modules, or manage data in a format that needs documentation.

Ad-Hoc Commands: Provides functionality to easily add new Ad-Hoc commands
mod_storage_sql developer notes: Describes the used SQL format
HTTP: Developing a HTTP-capable module for Prosody
Network services: Opening ports from modules
Telnet console: Extending the telnet console with new commands

Common data structures

The ‘session’ object

Actually provided by util.hashes↩︎