Extension:EventBus
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 | |
|
|
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 a RESTful event service, providing consumers of the service with the means of tracking changes to MediaWiki content.
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.)
Download / InstallEdit
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 APIEdit
This section is currently a draft. Material may not yet be complete, information may presently be omitted, and certain parts of the content may be subject to radical, rapid alteration. More information pertaining to this may be available on the talk page. |
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 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 |
---|---|
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 |
ConfigurationEdit
Note: For this extension to be useful, you need to be running an event intake 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 configurationEdit
This section is currently a draft. Material may not yet be complete, information may presently be omitted, and certain parts of the content may be subject to radical, rapid alteration. More information pertaining to this may be available on the talk page. |
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;
ReferencesEdit
- T84923: Reliable publish / subscribe event bus
- T116786: Integrate eventbus-based event production into MediaWiki
- T120242: Reliable (atomic) MediaWiki event production
This extension is being used on one or more Wikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia's CommonSettings.php and InitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki's Special:Version page. |