Extension:EventBus

MediaWiki extensions manual

File:OOjs UI icon advanced.svg EventBus Release status: beta
Implementation	Data extraction
Description	Propagation of change events to a RESTful service
Author(s)	EEvans (WMF)talk
Latest version	0.5.0
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
MediaWiki	>= 1.42
Database changes	No
License	GNU General Public License 2.0 or later
Download	<translate> Download extension</translate> <translate> Git</translate> [?]: <translate> Download Git master</translate> <translate> browse repository</translate> (Phabricator · GitHub) <translate> commit history</translate> <translate> repository contributors (GitHub)</translate> <translate> code review</translate>
Parameters $wgEnableEventBus $wgEventBusMaxBatchByteSize $wgEventBusStreamNamesMap $wgEventBusEnableRunJobAPI $wgEventServiceDefault $wgEventServices
Hooks used ArticleProtectComplete ArticlePurge ArticleRevisionVisibilitySet BlockIpComplete CentralNoticeCampaignChange ChangeTagsAfterUpdateTags LinksUpdateComplete PageDelete PageDeleteComplete PageMoveComplete PageSaveComplete PageUndeleteComplete RevisionRecordInserted
Quarterly downloads
Public wikis using
Translate the EventBus extension if it is available at translatewiki.net
Issues	Open tasks · Report a bug

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

Install

• <translate> [[<tvar name=2>Special:ExtensionDistributor/EventBus</tvar>|Download]] and move the extracted <tvar name=name>EventBus</tvar> folder to your <tvar name=ext>extensions/</tvar> directory.</translate>
  <translate> Developers and code contributors should install the extension [[<tvar name=git>Special:MyLanguage/Download from Git</tvar>|from Git]] instead, using:</translate>cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/EventBus
• <translate> Add the following code at the bottom of your <tvar name=1>LocalSettings.php </tvar> file:</translate>

  wfLoadExtension( 'EventBus' );
  

• File:OOjs UI icon check-constructive.svg <translate> Done</translate> – <translate> Navigate to <tvar name=special>Special:Version</tvar> on your wiki to verify that the extension is successfully installed.</translate>

State events

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 <translate> task <tvar name=1>T120242</tvar></translate>.)

Configuration

Note: For this extension to be useful, you need to have Kafka installed with EventGate as the event-intake service.

To enable the sending of state events, add the following to your LocalSettings.php, with the event service name and URLs set according to your environment.

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

Purge events

MediaWiki core provides CDN purges to its EventRelayer, which is null by default. To enable sending CDN purges to EventGate/Kafka as well, use the EventBus adapter for EventRelayer as follows.

$wgEventRelayerConfig = [
    'cdn-url-purges' => [
        'class' => \MediaWiki\Extension\EventBus\Adapters\EventRelayer\CdnPurgeEventRelayer::class,
        'stream' => 'resource-purge',
    ],
    'default' => [
        'class' => EventRelayerNull::class,
    ],
];

RunJob REST API

The RunJob REST API allows you to execute a job using a REST API endpoint.

Site configuration

To enable the RunJob REST API on your wiki, set $wgEventBusEnableRunJobAPI in LocalSettings.php. The RunJob REST API is compatible with MediaWiki 1.34 and later.

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

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	<translate> Required</translate>	enwiki	Name of the wiki database
type	<translate> Required</translate>	deleteJob	Type of job
params	<translate> Required</translate>	{ "namespace": 0, "title": "testing", "wikiPageId": 34, "reason": "testing delete job", "suppress": false, "tags": [], "logsubtype": "delete" }	Parameters that are specific to the job
mediawiki_signature	<translate> Required</translate>	d8c84b3d6c810c2db6bf1cb74400c25d4bc02d65	The cryptographic signature of the event based on the MediaWiki SecretKey

Responses

200	Success Response example { "status": true, "error": null, "caught": [], "timeMs": 525 }
400	Invalid event received Response example { "message": "Invalid event received", "missing_params": [ "database", "type", "params" ], "httpCode": 400, "httpReason": "Bad Request" }
400	Failed creating job from description Response example { "message": "Failed creating job from description", "error": "Error Message", "httpCode": 400, "httpReason": "Bad Request" }
403	Missing MediaWiki signature Response example { "message": "Missing mediawiki signature", "httpCode": 403, "httpReason": "Forbidden" }
403	Invalid MediaWiki signature Response example { "message": "Invalid mediawiki signature", "httpCode": 403, "httpReason": "Forbidden" }
415	Unsupported Content-Type Response example { "message": "Unsupported Content-Type", "httpCode": 415, "httpReason": "Unsupported Media Type", "content_type": "text/plain" }
423	Wiki is in read-only mode Response example { "message": "Wiki is in read-only mode", "httpCode": 423, "httpReason": "Locked" }
500	Could not decode the event Response example { "message": "Could not decode the event", "httpCode": 500, "httpReason": "Internal Server Error", "error": "Error message" }
500	Internal Server Error Response example { "message": "Internal Server Error", "httpCode": 500, "httpReason": "Internal Server Error", "error": "Error message" }
501	Set $wgEventBusEnableRunJobAPI to true Response example { "message": "Set $wgEventBusEnableRunJobAPI to true to enable the internal EventBus API", "httpCode": 501, "httpReason": "Not Implemented", }

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

Known issues

In Windows environments this extension causes critical performance problems if registered endpoint is not available.

References

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