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

Network and socket handling

net.adns
asynchronous DNS resolution
net.connect
API for outgoing connections
net.dns
stub DNS resolver
net.http
HTTP client library
net.http.codes
HTTP status code registry
net.http.files
Serve static files from HTTP
net.http.parser
HTTP stream parser
net.http.server
HTTP server
net.resolvers
Implementations of connection strategies
net.server
Socket handling
net.websocket
WebSocket client library
net.websocket.frames
WebSocket wire protocol library

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 library1
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

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


  1. Actually provided by util.hashes↩︎