~mna/tulip-wiki

tulip-wiki/pkg.pubsub.md -rw-r--r-- 2.4 KiB
3ebfbd28Martin Angers Update to reflect Request:validate_body 1 year, 11 months ago

The tulip.pkg.pubsub module exports the pubsub package.

#Dependencies

  • tulip.pkg.database

#Configuration

  • allowed_channels: array of string = if set, only those channels will be allowed.
  • get_connection: function = if set, used to get the long-running connection used to listen for notifications (and re-connect if connection is lost). Defaults to App:db().
  • error_handler: function = if set, called whenever an error occurs in the background coroutine that dispatches notifications. It is called with the current xpgsql connection, a number that increments with each failure (first call is 1), a (possibly nil) error message and the get_connection function. If the function returns nil, the coroutine is terminated and pubsub notifications will stop being emitted. Otherwise, it can return a connection and an optional integer, and if so the connection will be used instead of the old connection, and the number will be used as new value for the failure count (e.g. return 0 to reset). By default, a function that calls get_connection to get a new connection, and fails permanently (i.e. returns nil) after 3 calls.
  • listeners: table = if set, key is the channel and value is an array of functions to register as listeners for that channel.

#API Extensions

Registering this package provides the following method and field extensions.

#ok, err = App:pubsub(chan, fconn[, msg])

Publishes a notification on a channel if msg is provided, or subscribes to notifications on a channel.

Args:

  • chan: string = the pubsub channel
  • fconn: function|connection|nil = either a function to register as handler for that channel, or an optional database connection to use to publish msg. The handler function receives a Notification object as argument with a channel and payload field. It also has a terminate method to terminate the pubsub notification coroutine, mostly for tests.
  • msg: table|nil = the payload of the notification to publish.

Returns:

  • ok: boolean = true on success
  • err: Error|nil = error message if ok is falsy

#true = Notification:terminate()

Terminates the subscription to the channel that generated this Notification.

Returns:

  • true = always returns true

#Notification.channel: string

The name of the channel that received this Notification.

#Notification.payload: table

The JSON-decoded payload that was sent with the Notification.

Back to index