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 (replaces tests/ in trunk)

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.array
Array library
util.async
Library to provide support around coroutine-based non-blocking functions
util.cache
Ordered key-value least recently used pairs
util.datamanager
Allows persistent storage and retrieval of data
util.datetime
Retrieve the current or specified time in various XMPP formats
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.events
Library to abstract the firing and handling of named events
util.hashes
Calculate hashes of input data using MD5, SHA1, SHA256, etc.
util.id
Generates compact strings suitable for use as identifiers
util.interpolation
A string templating engine
util.jid
Common functions for splitting and prepping JIDs
util.json
A JSON 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.openssl
A library for dealing with OpenSSL and certificate configuration
util.pposix
A POSIX library
util.pubsub
Abstract Publish-Subscribe library
util.queue
A library for first-in, first-out queues
util.random
Produce pseudorandom byte strings
util.ringbuffer
A ringbuffer for binary data
util.serialization
Convert objects into a format suitable to save to disk or send across the network
util.timer
Set callbacks to be called after a specified delay
util.set
A Set library
util.stanza
Create and manipulate stanzas and other XML objects
util.statistics
Library for statistical calculations
util.table
Small library to complement Luas built-in table module
util.termcolours
Library for producing ANSI colour codes
util.throttle
Token bucket implementation
util.uuid
Generate unique string identifiers

The complete list of utils, some not yet documented

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