Extension:EventBus

MediaWiki extensions manual

EventBus Release status: beta
Implementation	Data extraction
Description	Propagation of change events to a RESTful service
Author(s)	EEvans (WMF)talk
Latest version	0.1 (2015-11-19)
MediaWiki	1.27+
PHP	5.4+
Database changes	No
License	GNU General Public License 2.0 or later
Download	Download extension Git [?]: Download Git master browse repository (GitHub) commit history code review
Parameters $wgEventBusEnableRunJobAPI $wgEnableEventBus $wgEventServiceStreamConfig $wgEventServices
Hooks used ArticleDeleteComplete ArticleProtectComplete ArticlePurge ArticleRevisionVisibilitySet ArticleUndelete BlockIpComplete CentralNoticeCampaignChange ChangeTagsAfterUpdateTags LinksUpdateComplete PageContentInsertComplete PageContentSaveComplete TitleMoveComplete
Translate the EventBus extension if it is available at translatewiki.net
Check usage and version matrix.
Issues	Open tasks · Report a bug

The EventBus extension propagates state changes (edit, move, delete, revision visibility, etc) to a RESTful event service, providing consumers of the service with the means of tracking changes to MediaWiki content.

Known Issues

Ideally, this sort of change propagation would be atomic, that is to say, if one of the tracked changes is committed in MediaWiki, the corresponding event is guaranteed to be delivered (even if by eventual consistency). As this extension is hook-based, that is not currently the case; Truly reliable event delivery will likely require something bound to the corresponding database transaction. (tracked in task T120242.)

Download / Install

The extension can be retrieved directly from Git ^[?]:

• Browse code
• Some extensions have tags for stable releases.
  • Browse tags
  • Select the tag
  • Click "snapshot"
• Each branch is associated with a past MediaWiki release. There is also a "master" branch containing the latest alpha version (might require an alpha version of MediaWiki).
  • Browse branches
  • Select a branch name
  • Click "Continue"

Extract the snapshot and place it in the extensions/EventBus/ directory of your MediaWiki installation.

If you are familiar with git and have shell access to your server, you can also obtain the extension as follows:

cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/EventBus.git

• To enable, add the following code to the bottom of your LocalSettings.php:

wfLoadExtension( 'EventBus' );

•  Done; Navigate to 'Special:Version' on your wiki, and verify the extension is successfully installed

Run Job REST API

The Run Job REST API allows you to execute a job using a REST API endpoint. To enable the Run Job REST API on your wiki, configure LocalSettings.php with the $wgEnableRestAPI and $wgEventBusEnableRunJobAPI settings. The Run Job REST API is compatible with MediaWiki 1.34 and later.

Run job

Route: /eventbus/v0/internal/job/execute

Method: POST

Content-Type: application/json

Submits a job for execution by the event service. This endpoint is released under v0/internal; it should be considered unstable and may change in backwards incompatible ways without notice.

Request example

# Runs the job described in filename.json
curl -X POST -d @filename.json http:/examplewiki.org/w/rest.php/eventbus/v0/internal/job/execute --header "Content-Type:application/json"

Request parameters

Here are the minimum parameters required by the endpoint. The full schema of a job can be found in the mediawiki-event-schemas directory.

parameter	required	example	description
database	required	enwiki	Name of the wiki database
type	required	deleteJob	Type of job
params	required	{ "namespace": 0, "title": "testing", "wikiPageId": 34, "reason": "testing delete job", "suppress": false, "tags": [], "logsubtype": "delete" }	Parameters that are specific to the job
mediawiki_signature	required	d8c84b3d6c810c2db6bf1cb74400c25d4bc02d65	The cryptographic signature of the event based on the MediaWiki SecretKey

Responses

200	Success
400	Invalid event received
400	Failed creating job from description
403	Missing MediaWiki signature
403	Invalid MediaWiki signature
415	Unsupported Content-Type
423	Wiki is in read-only mode
500	Could not decode the event
500	Internal Server Error
501	Set $wgEventBusEnableRunJobAPI to true

Response schema

key	type	description
status required	boolean	Whether the job succeeded
error required	string	A string of the error or empty if there was no error specified
caught required	array	List of FQCNs (fully-qualified class names) corresponding to any exceptions caught
timeMS required	float	Job execution time in milliseconds

Configuration

Note: For this extension to be useful, you need to be running an event service.

To configure the event service, add the following to your LocalSettings.php, (setting the event service name and URL value according to your environment.

$wgEventServices = [
    'eventbus'  => ['url' => 'http://hostname:8888/v1/events', 'timeout' => 10],
    'eventgate' => ['url' => 'http://hostname:8192/v1/events'],
    // ...
];

API configuration

To enable the Run Job REST API, add the following to your LocalSettings.php.

/**
 * Enable the MediaWiki REST API
 *
 * @see https://www.mediawiki.org/wiki/API:REST_API
 */
$wgEnableRestAPI = true;

/**
 * Enable the Run Job REST API
 *
 * @see https://www.mediawiki.org/wiki/Extension:EventBus#Run_Job_REST_API
 */
$wgEventBusEnableRunJobAPI = true;

References

• T84923: Reliable publish / subscribe event bus
• T116786: Integrate eventbus-based event production into MediaWiki
• T120242: Reliable (atomic) MediaWiki event production