User:Peter17/Reasonably efficient interwiki transclusion

This is a draft for my GSoC-2010 project, reasonably efficient interwiki transclusion, written after discussing with my mentor User:Catrope and updated several times during the project.

Initial state
Currently, some functions ( and   in  ) allow interwiki transclusion of distant templates.

The interwiki table contains the known interwiki prefixes. For each of them, the value  can be set to 1 to allow (or 0 to disallow) transclusion from that wiki.

If  is set to true, when a transclusion call refers to an article of another wiki and if transclusion from that wiki is allowed by , then:
 * checks whether the template has been cached less that 1h (by default) ago
 * if yes, then, the cached template is used
 * if not, then, a GET request is made to retrieve the content from the distant wiki

There are two different possible formats to retrieve (and cache) the content:  and.

The default with this system is that the data is cached for an arbitrary time, which means:
 * When a template is almost never modified, the cache is still updated whereas it is useless, so, we lose some performance.
 * When a template is actually modified, in the worst case, the cache will have to wait 1h before being updated and the users of the local wiki will not see the changes made to the template during that time.

So, the cache should be updated if and only if necessary.

I made some tests on May 10th.

Good points

 * It is working. I mean I can transclude my userpage from this wiki (mediawiki.org) to a wiki hosted on my computer using the syntax !
 * The links become full links: /Reasonably efficient interwiki transclusion becomes http://www.mediawiki.org/wiki/User:Peter17/Reasonably_efficient_interwiki_transclusion
 * If the wanted page calls some templates or parser functions, then, they are used to render the content, which is good!

Issues

 * When transcluding, what is transcluded is just the content of the page templateName of the distant wiki, which means:
 * The parameters are totally ignored.
 * The instructions, behave as if it was not a transclusion which is the opposite of the expected behavior...
 * The transcluded content is actually cached for 1h, which means even purging the cache will not update it...
 * The fact that links point to the distant pages might not the expected behavior...
 * All the parsing is done by the distant wiki, which is expensive for it. If foreign wikis want our templates, they could at least parse them by themselves...

Proposed approach
After a discussion on wikitech-l, some people, notably Chad and Aryeh Gregor, have suggested to use a similar approach as FileRepo does (see Manual:$wgForeignFileRepos). FileRepo is a class meant to allow the inclusion of distant files. It uses different backends in different cases, described below (see "Done work").

Create a globaltransclusionlinks table
Inside a wiki farm, it's quite easy to automagically purge the pages that use a distant template when this template is edited. We want to:
 * track the use of each template (know which distant pages are using it and update when pages are edited, deleted or moved)
 * when a template (or a subtemplate of this template!) is edited or deleted, invalidate the cache of those pages (how?)

The approach proposed below needs to be discussed.

Inside a wiki farm, the transclusion links between the local pages and the distant pages would be stored in the distant DB, so that the distant wiki always knows which other wikis of the farm are using its templates. The "calling" wikis could write in a "globaltransclusionlinks table" on the distant wikis to inform it of their usage of the templates. When a distant template is edited, the distant wiki will look in its  table to see who is transcluding the template.

Then, it will access the DB of the calling wiki and invalidate the cache of the concerned pages. The disadvantage of this approach is that the distant wiki (home of the template) needs to have, in its  table, the   of all the wikis allowed to transclude its templates (in order to access their DBs).


 * Proposed structure for the globaltransclusionlinks table

As in the  table, from designates the page that calls the link and to the page pointed by the link.

We also need to store the wiki ID of the calling page, plus its page ID for cache invalidation and its full title for display.

++--+--+-+-+---+ ++--+--+-+-+---+ ++--+--+-+-+---+
 * Field             | Type         | Null | Key | Default | Extra |
 * gtl_from_iwprefix | char(32)     | NO   |     |         |       |
 * gtl_from_pageid   | int(10)      | NO   |     |         |       |
 * gtl_from_fulltitle | varchar(255) | NO  |     |         |       |
 * gtl_to_ns         | int(11)      | NO   |     |         |       |
 * gtl_to_title      | varchar(255) | NO   |     |         |       | # or gtl_to_pageid


 * Questions and remarks
 * The question of broken links should be discussed: should we store the links that point to non-existing templates? If yes, we need to store the title and namespace of the pointed pages. If no, we can just store their page ID.

Questions and remarks

 * Is it possible to rely on  to obtain the list of all templates called by a page? If A calls B and B calls C, then: if B is modified and calls D instead of C, will this be taken immediately into account in the list of A template links?
 * It will be taken into account, yes, although possibly not immediately (deferred through job queue). --Catrope
 * The requested wikitext might itself call distant templates which might themselves call other distant templates. Some infinite loops might appear. This could be resolved by checking whether we already have retrieved a template before requesting it.
 * Seems not to be a problem with the current approach:
 * API-retrieved templates are cached if not already done
 * DB-retrieved templates work the same as local templates
 * It should be possible to transclude only a sections of an article, as Extension:Labeled Section Transclusion does. When using the API, there is a way to do this, using API:Parsing wikitext and defining the  argument.
 * When a template is used by several distant wikis, it would be great to display an alert that would incite the administrators to protect this template, so that it is not modified too often
 * The distant messages are not retrieved
 * The retrieved templates look ugly when they use a specific style from Common.css

Add fields to the interwiki table
The former structure of the interwiki table was this one: +---++--+-+-+---+ +---++--+-+-+---+ +---++--+-+-+---+
 * Field    | Type       | Null | Key | Default | Extra |
 * iw_prefix | char(32)  | NO   | PRI |         |       |
 * iw_url   | blob       | NO   |     |         |       |
 * iw_local | bool       | NO   |     |         |       |
 * iw_trans | tinyint(1) | NO   |     | 0       |       |

Here is the new structure I proposed for the interwiki table: +---++--+-+-+---+ +---++--+-+-+---+ +---++--+-+-+---+
 * Field    | Type       | Null | Key | Default | Extra |
 * iw_prefix | char(32)  | NO   | PRI |         |       |
 * iw_url   | blob       | NO   |     |         |       |
 * iw_api   | blob       | NO   |     |         |       |
 * iw_wikiid | char(64)  | NO   |     |         |       |
 * iw_local | bool       | NO   |     |         |       |
 * iw_trans | tinyint(1) | NO   |     | 0       |       |

So, my changes consisted in adding two optional fields:
 * the URL of  of that wiki
 * the ID of that wiki (used in wfGetDb(DB_SLAVE, array, $wikiID);)

Currently,   allows the administrator to decide whether the templates from a particular wiki can be transcluded in the current wiki.
 * Explanations:
 * 0 will forbid this
 * 1 will allow this

With this structure, the software can allow transclusions in two different ways (using the API or using a direct DB access). When   is set to 1, the presence of   will indicate whether to use the DB access ( set) or the API (  not set).

Retrieve and cache the distant templates through the API
As explained before, the address of  of a foreign wiki can be stored in the   table.

For a given interwiki prefix, if no  is given if an API address is defined, a transclusion call will retrieve the wanted wikitext through an API call, cache it in   and return it to the parser. The key is

Moreover, if the wanted page is returned, the software will retrieve the list of all templates called by this wikitext (subtemplates). He will then determine which of them are not in the cache and cache them in, making API requests by groups of 50 (at most) templates.

This way, on the next loop of the parser, the subtemplates will be found in the cache and will not be requested.

Retrieve and cache the distant templates through DB access
This is the case of the wiki farms. The  table contains the   of the foreign wiki.

In this case, the most efficient solution is accessing directly the wanted wikitext by reading in the database of the foreign wiki. The software can access the DB inside the wiki farm with: $dbr = wfGetDb( DB_SLAVE, array, $wikiID );

When a distant template is called, the software retrieves the corresponding wikitext.

Accessing the distant DB is just as expensive as accessing the local one, so, no caching is needed, except a  table, to invalidate the cache of the pages that call a template, when this template is edited.

Final behavior
No parsing is done by the foreign wiki, all by the local wiki.

This way, the behavior of the interwiki transclusion is quite simple:
 * everything is parsed locally, exactly like the local templates
 * except that the templates and their subtemplates are the distant ones
 * the parameters of those templates are interpreted as on the local wiki, which means that the local templates will be used if they are present in the arguments of the distant templates
 * the links are interpreted as local links, pointing to local pages

On the local wiki, Template:Foo contains "Hello world!".
 * Example

On the foreign wiki, Template:Bar contains " Hi!"

Then, an article of the local wiki calling will produce "Hello world! Hi!"