Extension:EventBus - MediaWiki

Extension:EventBus - MediaWiki
Jump to content
From mediawiki.org
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.5.0
Compatibility policy
Snapshots releases along with MediaWiki. Master is not backward compatible.
Database changes
No
Parameters
$wgEventServices
$wgEventBusMaxBatchByteSize
$wgEventBusStreamNamesMap
$wgEventBusEnableRunJobAPI
$wgEventServiceDefault
$wgEnableEventBus
Hooks used
ArticleProtectComplete
ArticlePurge
ArticleRevisionVisibilitySet
BlockIpComplete
CentralNoticeCampaignChange
ChangeTagsAfterUpdateTags
LinksUpdateComplete
PageDelete
PageDeleteComplete
PageMoveComplete
PageSaveComplete
PageUndeleteComplete
RevisionRecordInserted
Licence
GNU General Public License 2.0
or later
Download extension
Git
Browse repository
GitHub
Gerrit code review
Git commit log
Download source tarball
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
edit
and move the extracted
EventBus
folder to your
extensions/
directory.
Developers and code contributors should install the extension
from Git
instead, using:
cd
extensions/
git
clone
Add the following code at the bottom of your
LocalSettings.php
file:
wfLoadExtension
'EventBus'
);
Done
– Navigate to
Special:Version
on your wiki to verify that the extension is successfully installed.
State events
edit
Known issues
edit
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
T120242
.)
Configuration
edit
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
edit
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
edit
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 RunJob REST API allows you to execute a job using a
REST API
endpoint.
Site configuration
edit
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
edit
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"
"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
Known issues
edit
In Windows environments this extension causes critical performance problems if registered endpoint is not available.
References
edit
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.
This extension is included in the following wiki farms/hosts and/or packages:
BlueSpice
Miraheze
Retrieved from "
Categories
Beta status extensions
Data extraction extensions
ArticleProtectComplete extensions
ArticlePurge extensions
ArticleRevisionVisibilitySet extensions
BlockIpComplete extensions
CentralNoticeCampaignChange extensions
ChangeTagsAfterUpdateTags extensions
LinksUpdateComplete extensions
PageDelete extensions
PageDeleteComplete extensions
PageMoveComplete extensions
PageSaveComplete extensions
PageUndeleteComplete extensions
RevisionRecordInserted extensions
GPL licensed extensions
Extensions in Wikimedia version control
All extensions
Analytics extensions
Extensions used on Wikimedia
Extensions included in BlueSpice
Extensions included in Miraheze
Hidden categories:
Extensions without an image
Extensions with release branches compatibility policy
Drafts
Extension
EventBus
Add topic