Extension:EventBus

MediaWiki extensions manual
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.1 (2015-11-19)
Compatibility policy Snapshots releases along with MediaWiki. Master is not backward compatible.
MediaWiki 1.27+
PHP 5.4+
Database changes No
License GNU General Public License 2.0 or later
Download
  • $wgEnableEventBus
  • $wgEventBusMaxBatchByteSize
  • $wgEventBusStreamNamesMap
  • $wgEventBusEnableRunJobAPI
  • $wgEventServiceDefault
  • $wgEventServices
Quarterly downloads 10 (Ranked 160th)
Public wikis using 947 (Ranked 264th)
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.

Download / InstallEdit

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

  • Browse code
  • Some extensions have tags for stable releases.
  • 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).

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

State eventsEdit

Known issuesEdit

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.)

ConfigurationEdit

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 eventsEdit

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 APIEdit

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

Site configurationEdit

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 jobEdit

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
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
/**
 * Enable the Run Job REST API
 *
 * @see https://www.mediawiki.org/wiki/Extension:EventBus#Run_Job_REST_API
 */
$wgEventBusEnableRunJobAPI = true;

Known issuesEdit

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

ReferencesEdit