User:GLavagetto (WMF)/ExternalServicesRfC

This document is an attempt to formalize the output of the "Architecting Core: Standalone Services" session from the 2018 Wikimedia Technical Conference.

=Proposal= The following proposals aim to set architectural principles and standards for when, how and why to to extend MediaWiki via an external service.

Definition
//Standalone services// are applications that extended MediaWiki in some way, but that are operationally distinct in some meaningful way. The mechanism of extension is not specified, beyond saying that it's necessarily interprocess as opposed to intraprocess; queues, API calls and other types of RPC mechanisms, XHR from a client, are all valid examples. It is very likely that one or more MediaWiki extensions will be involved in integration; the important point is that business logic is implemented outside of the MediaWiki extension.

Selection Criteria: Deciding whether an external service is appropriate
The properties listed here are intended to be a guide as to whether a given feature can be provided externally to MediaWiki or not. They are intended to be necessary, but not. If a proposed feature has one or more properties that appear in the left column, but no properties that appear in the right column, then that feature could be implemented as a standalone service. If the proposed feature has one or more properties that appear in the right column, then a wide consensus must be reached before implementing it as a standalone service.

If any of the following are true, then the feature absolutely should be implemented as an external service, with appropriate architectural changes made elsewhere to eliminate disqualifying properties.

Architectural and Implementation Guidelines for external services
All features implemented as standalone services must have the following properties:
 * Actually do something
 * Minimize data collection
 * Provide for compliance with GDPR or other data privacy/data ownership frameworks
 * Implement privacy controls that are at least equivalent to those of any calling service. For example, if the privacy controls of the calling service specify that IP addresses will not be stored for more than 90 days, the external service may not store IP addresses for longer than that time.
 * Be licensed under an OSI-approved license
 * Avoid needlessly duplicating features or functionality provided in other services

If the standalone service is intended to be distributed for general use, it must have the properties above, and in addition must
 * Have a documented installation process
 * Have a documented uninstallation process
 * Have a documented upgrade process
 * Be versioned using semver
 * Indicate versions of MediaWiki with which it's compatible
 * Provide a configuration mechanism that does not involve changing the distributed code
 * Provide a mechanism by which support (community or otherwise) can be requested
 * Provide a mechanism by which patches can be proposed
 * Provide a mechanism by which public security advisories are issued

If the standalone service is intended to be used in the Wikimedia production environment, it should comply with the guidelines above, and in addition must
 * Have SLIs and SLOs
 * Have WMF-compatible monitoring
 * Have a privacy policy and privacy practices that are compatible with the WMF/Wikimedia properties
 * Use Wikimedia deployment tooling
 * Have passed review by WMF Security
 * Use a language and toolset that have been approved by TechCom
 * Have an owner, and a plan for ongoing maintenance
 * Have a runbook
 * Have WMF-compatible structured logging
 * Be architected such that it can run in multiple data centers simultaneously
 * Be tolerant to faults, including network partitions or other datacenter level issues
 * Have pinned/pinnable dependencies
 * Have trusted upstream asset chains
 * Have backups if the service stores any data
 * Perform sufficiently for very high request or data volumes
 * Have users, or a plan to acquire users