Parsoid

Parsoid is a service that parses converts between wikitext and HTML. The HTML contains additional metadata that allows it to be converted back ("round-tripped") to wikitext. VisualEditor fetches the HTML for a given page from Parsoid, edits it, then delivers the modified HTML to Parsoid, which converts it back to wikitext. Parsoid is a stateless HTTP server running on port 8000.

Deploying changes

Parsoid and its configuration are deployed (separately) using git-deploy. Doing deployments with git-deploy is very easy. You run git deploy start, make whichever changes you need to make to the git clone (such as pulling, changing branches, committing live hacks, etc.), then run git deploy sync. The sync command pushes the new state to all backends and restarts them.

Deploying the latest version of Parsoid

catrope@fenari$ ssh tin
catrope@tin$ cd /srv/deployment/parsoid/Parsoid
catrope@tin$ git deploy start
catrope@tin$ git pull
catrope@tin$ git deploy sync

Changing the Parsoid configuration

catrope@fenari$ ssh tin
catrope@tin$ cd /srv/deployment/parsoid/config
catrope@tin$ git deploy start
catrope@tin$ vim localsettings.js
[make your changes]
catrope@tin$ git commit -a
catrope@tin$ git deploy sync

Misc stuff

• To revert either Parsoid or its config to a previously deployed version, cd to the appropriate directory on tin and run git deploy revert .
• To abort a deployment after running git deploy start but before git deploy sync , run git deploy abort .
• There is a lock file preventing multiple deployments on the same code base from being active at the same time. If git deploy start complains about this lock, you can run git deploy abort to make it go away (if you know this isn't a legitimate warning due to someone else actively deploying).
• If the sync step complains you didn't change anything, you can run git deploy --force sync (note order of arguments!) to make it sync anyway.

Data flow

Parsoid runs entirely on an internal subnet, so requests to it are proxied through the ve-parsoid API module. This module is implemented in extensions/VisualEditor/ApiVisualEditor.php and is invoked with a POST request to /w/api.php?action=ve-parsoid. The API module then sends a request to Parsoid, either GET /$prefix/$pagename to get the HTML for a page, or POST /$prefix/$pagename to submit HTML and get wikitext back. Parsoid itself also issues requests to /w/api.php to get the wikitext of the requested page and to do template expansion.

Once the ve-parsoid API module receives a response from Parsoid, it either relays it back to the client (when requesting HTML), or saves the returned wikitext to the page (when submitting HTML).

                (POST /w/api.php?action=ve-parsoid)              (GET /en/Barack_Obama)                (requests for page content and template expansions)
Client browser ------------------------------------------> API ---------------------------->  Parsoid -----------------------------------------------------> API
    ^                                                      | ^                                 |   ^                                                          |
    |                  (response)                          | |      (HTML)                     |   |                   (responses)                            |
    +------------------------------------------------------+ +---------------------------------+   +----------------------------------------------------------+


                (POST /w/api.php?action=ve-parsoid)              (POST /en/Barack_Obama)
Client browser ------------------------------------------> API ---------------------------->  Parsoid
                                                           | ^                                 |
                                               (save page) | |      (wikitext)                 |
                                                           | +---------------------------------+
                                                           |
                                                        Database

Caching and load balancing

Parsoid is load balanced using LVS. The assigned service IPs are:

• parsoid.svc.pmtpa.wmnet = 10.2.1.28 served by lvs3/lvs4, list of backends
• parsoid.svc.eqiad.wmnet = 10.2.2.28 served by lvs1003/lvs1006, list of backends

In pmtpa, there is also a Varnish machine (celsus) in front of the LVS group. MediaWiki is configured to access Parsoid through celsus. celsus also runs Parsoid, but it's depooled to allow Varnish to use the system's resources. It's set up this way so we can quickly change celsus from a caching proxy to a backend if we decide we need more CPU resources in the pool.

         celsus:6081            10.2.1.28:8000                    $selected_backend:8000
MW API  -------------> Varnish ----------------> LVS (lvs3/lvs4) ------------------------> Parsoid

MediaWiki and Parsoid collaborate to make caching work in the face of changing content. MediaWiki sends ?cache=1 in the query string of its GET requests to Parsoid, which cause Parsoid to set Cache-Control: s-maxage=2592000 in its responses. MediaWiki also includes the revision ID of the page in the URL (as ?oldid=123). Furthermore, for cache busting when the page is purged (e.g. due to a template edit), MediaWiki also includes the page_touched timestamp of the page in the URL (as ?touched=20121211231047).