MAM API

Metronome’s MAM processing and validation API library.

Processing and Initialization

Below I’ll describe the API functions to perform archive processing or storage initialization contained into the MAM library (mam/mam.lib.lua), firstly by giving a preamble on how Metronome handles archives. The server never operates on the database directly but instead loads and caches the user archive in memory saving it as an object in the user’s bare session (sharing it for all online resources) and performs operation on that, re-stashing the archive on defined windows. While this may have a definite impact on scaling, it’s for sure beneficial performance wise since it avoids hitting disk or the database too often and is the best course of action for the current server backend architecture.

This is a list of public functions and their parameters:

• initialize_storage (none): this initializes the global MAM storage, returns the storage objects
• save_stores (none): saves all currently loaded MAM stores (use with caution as it’s resource/IO intensive and server may block)
• get_prefs (store): get preferences for an archive, returns the stanza object containing preferences.
  • 1) the archive store object to get preferences from
• set_prefs (stanza, store): set preferences for an archive, returns the stanza reply object containing new preferences.
  • 1) the stanza of the request
  • 2) the archive store object
• fields_handler (event): handler for when MAM query dataform fields are requested
  • 1) the generating event of the request
• generate_stanzas (store, start, fin, with, max, after, before, index, qid): the function to generate archive results, returns the result set stanzas, and the query stanza reply
  • 1) the archive object
  • 2) starting time threshold of entries
  • 3) ending time threshold of entries
  • 4) max amount of archive results
  • 5) RSM page entries forward from given entry UUID
  • 6) RSM page entries backward from given entry UUID, or last page
  • 7) Specify index for paging back/forward from
  • 8) Calling query id
• process_message (event, outbound): processes an user message for archive storing
  • 1) the generating event of the message
  • 2) boolean, if set it specifies the message was sent from the user
• purge_messages (archive, id, jid, start, fin): this handles purging requests done by Metronome’s “mam-purge” protocol
  • 1) the user archive object
  • 2) the id of the message
  • 3) the jid of the relevant messages to purge
  • 4) a starting time threshold of entries to purge
  • 5) a ending time threshold of entries to purge

Validation

Validation before processing of a stanza is done via the validate_query API function available from the MAM validation library (mam/validate.lib.lua):

• validate_query (stanza, query, qid):
  pre-validates a query before feeding it to processing functions,
  returns true and parameters of the query if a query is valid, returns
  false, plus error stanza if the query is not valid
  • 1) the generating original stanza of the query.
  • 2) the query element of the stanza
  • 3) the query id