This extension is used in the implementation of the Wikipedia Zero initiative:
<https://wikimediafoundation.org/wiki/Wikipedia_Zero>

Wikipedia Zero is an ongoing partnership with various mobile carriers to make
Wikipedia and sister projects available to users without data charges. In some
cases this is limited to a special subdomain or a no-images configuration.

Fore more general and user-facing information, see the page linked above.

== Technical overview ==

  +---------------------+
  |     Mobile phone    |   connects to zero.wikipedia.org or m.wikipedia.org
  +---------------------+
  |        Carrier      |   routes traffic from known IP blocks
  +---------------------+
             |
             |              the interwebs
             |
  +---------------------+
  | Varnish<->netmapper |   Web proxy and netmapper detect carrier IP, add X-CS header
  +---------------------+
  |     App servers     |   LAMP stack!
  +---------------------+
  |      MediaWiki      |   PHP code...
  +---------------------+
  |      ZeroBanner     |   detects X-CS HTTP header, modifies HTML
  +---------------------+

The ZeroBanner extension to MediaWiki detects a carrier based on an
"X-CS" and "X-Subdomain" HTTP header injected by our Varnish proxy servers.
Th X-CS header is injected in Varnish with netmapper for performance.


== Varnish configuration ==

Carrier detection by source IP block is done with netmapper by Varnish configuration.
The configuration for Wikimedia servers can be found in Wikimedia's 'puppet' git
repository, which holds most Wikimedia server configuration files as managed by the
'puppet' tool.

Visit the puppet.git repository and navigate to templates/varnish and start from
mobile-frontend.inc.vcl.erb
<https://git.wikimedia.org/tree/operations%2Fpuppet.git>

If you're curious about netmapper, see its repo.

<https://gerrit.wikimedia.org/r/#/admin/projects/operations/software/varnish/libvmod-netmapper>


An X-CS header with the carrier MCC/MNC code and an X-Analytics header key/value pair
with the same value (eg X-Analytics: zero=502-13) are set. Additionally, the X-Subdomain
header is set - an "mdot" subdomain is one such as en.m.wikipedia.org and a "zerodot"
one ru.zero.wikipedia.org - the X-Subdomain value is either "M" or "ZERO".


== ZeroBanner configuration ==

ZeroBanner normally enables itself only if the MediaWiki site configuration
lists the site as 'wikipedia'; as of 23-December-2013, other Wikimedia sites do not
have banners and URL rewriting turned on for the Wikipedia Zero program.

To test on your own vagrant instance, enable "zero" role:
  $ vagrant enable-role zero
  $ vagrant provision

This extension uses the EventLogging extension for capturing the sent-once-per-cellular
session X-MCCMNC header (in 2014 rebooted iOS and Android apps, for example) via an API hook.
To support this EventLogging usage under MediaWiki Vagrant:

  1. Run the following:
      $ vagrant enable-role eventlogging
      $ vagrant provision
  2. Add the following lines to LocalSettings.php (or in Vagrant settings.d/<##>-<whatever>.php)
      $mwLogDir = __DIR__ . '/../logs';
      $wgDebugLogGroups['mccmnc'] = "$mwLogDir/mccmnc.log";


== Testing ==

As noted above, on a local test wiki you will need to enable several settings.

You will want to manually add X-CS headers via browser addons such as:
* 'Modify Headers' add-on for Firefox
* 'ModHeaders' extension for Chrome

Be sure to set the following headers when testing against your local instance:

* X-CS (should match an article name in the Zero: namespace; e.g., "-TEST")
* X-Subdomain (set to "M" or "ZERO" to spoof whether you're on "mdot" or "zerodot")


You can change your User-Agent string via browser addons such as:
* 'Modify Headers' add-on for Firefox
* 'Default User Agent' add-on for Firefox
* 'ModHeaders' extension for Chrome

Set your User-Agent to a value like "android" so that mobile detection works.

Note that if testing in production, most custom headers will be overwritten by the
Varnish server if you're coming from an IP block that's recognized for Wikipedia Zero -- this
includes the Wikimedia San Francisco office. D'oh! This shouldn't happen with a local test
server, though

== Local Configuration Blobs ==

For people not interested in editing configurations, just use the API URL supplied
above. But if you want to be able to edit configurations locally for testing purposes,
you will need to create a Zero:-namespaced configuration entry to match the X-CS header
that you add using 'Modify Headers'.

For example, go to http://127.0.0.1:8080/w/index.php?title=Zero:999-88&action=edit
and populate the article with the data from https://meta.wikimedia.org/wiki/Zero:-TEST.

== Testing specific modes ==

To test the landing page, go to /wiki/Special:ZeroRatedMobileAccess

To test the Main Page, go to /wiki/Main_Page
