Mailing-List: contact commits-help@maven.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@maven.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1126849 -
 /maven/maven-3/branches/mirror-group-routing/README.md
Date: Tue, 24 May 2011 03:26:45 -0000
To: commits@maven.apache.org
From: jdcasey@apache.org
Message-Id: <20110524032645.B7D0C23889BF@eris.apache.org>

Author: jdcasey
Date: Tue May 24 03:26:45 2011
New Revision: 1126849

URL: http://svn.apache.org/viewvc?rev=1126849&view=rev
Log:
Adding proposal to README.md

Modified:
    maven/maven-3/branches/mirror-group-routing/README.md

Modified: maven/maven-3/branches/mirror-group-routing/README.md
URL: http://svn.apache.org/viewvc/maven/maven-3/branches/mirror-group-routing/README.md?rev=1126849&r1=1126848&r2=1126849&view=diff
==============================================================================
--- maven/maven-3/branches/mirror-group-routing/README.md (original)
+++ maven/maven-3/branches/mirror-group-routing/README.md Tue May 24 03:26:45 2011
@@ -1,3 +1,44 @@
+[PROPOSAL] Route-M Auto-Mirror Configuration for Maven 3
+=======================================================
+
+Introduction
+------------
+
+Currently, configuring Maven to use mirrors is an extremely manual process. The opportunities for human error involved in this configuration severely limit our practical ability to build a decentralized, distributed server infrastructure for serving Maven repositories. Moreover, this manual configuration problem makes the use of in-house repository managers unnecessarily difficult and error-prone.
+
+In addition to the configuration difficulties related to using mirrors, Maven's centralized repository structure is very difficult to serve. Maven has achieved a level of popularity such that the central repository requires incredibly high bandwidth to avoid network errors when users resolve dependencies for their projects. This problem is exacerbated by the usage design in tools like m2eclipse, that seems to encourage users to re-resolve the central repository's indexes very frequently. We've reached a point in the evolution of Maven where it's not feasible to host the central repository on donated infrastructure. The central repository is therefore unscalable, and therefore the design for resolving artifacts needs to be revisited.
+
+As part of this redesign, an automatic mirror-selection algorithm built directly into Maven would allow the use of a distributed network of Maven repositories. This would transform the scalability of Maven's repository infrastructure at a stroke. At the same time, an automatic mirror-selector would eliminate many of the configuration errors and confusion common to new users working in customized environments, as in the presence of a corporate repository manager.
+
+This proposal involves using a lightweight, centralized - but distributable - "routing table" document that describes the available mirrors, which is used by Maven to automatically select a mirror for a given repository. The routing table in question is meant to support various metrics that will allow Maven to give preference to the most appropriate mirrors, say those with better performance characteristics, closer geographical locations, etc. Once Maven makes a selection for a given repository, it will store that selection in a separate configuration file within $HOME/.m2 to avoid incurring the same selection cost next time around. Finally, Maven will support configuration of this auto-selection logic, to supply a different URL for the routing table, select which routing table URL discovery strategies should be used, and provide authentication for accessing the routing table URL.
+
+
+Backward Compatibility
+----------------------
+
+While this new auto-mirroring feature will transform the user experience and allow better scaling for the repository infrastructure, it's also critical not to interfere with configurations that are already working. Therefore, the auto-mirroring logic will defer to any mirrors configured in the Maven settings.xml. This allows the auto-mirror selector to remain in the background, dormant, until it's used without a specific mirror configuration in the settings.
+
+
+The Routing Table Model
+-----------------------
+
+The anatomy of a routing table document is fairly simple. This is a JSON document that consists of an array of mirror entries. Each mirror entry contains its own URL, id, enabled flag, and list of canonical repository URLs it mirrors. Additionally, it currently contains a simple weight integer, which allows Maven to favor selection of mirrors with a higher weight than others. Eventually, it may make sense to extend the mirror specification to include geolocation attributes like latitude and longitude, or other advanced selection data. For now, a simple weight rating will allow Maven to make a weighted-random selection to help spread load effectively over all available mirrors.
+
+
+Discovering the Routing Table
+-----------------------------
+
+For the most bare-bones use case, Maven should be configured by default to load a routing table document hosted on http://repository.apache.org. This location will be the fall-back URL even for users whose environment and configuration reference other routing-table URLs.
+
+In addition to the default routing table, it will also be possible to retrieve the routing table in two other ways. First, if the user has configured a property called 'router-url' in the $HOME/.m2/conf/automirror.properties file. If this property is available, Maven will attempt a HTTP GET to retrieve the routing table from that URL. If supplied, the 'router-user' and 'router-password' properties can be used to configure authentication for this request. 
+
+If there is no router-url property or the configuration file doesn't exist, Maven will automatically attempt to locate a routing table URL using DNS. It will determine your localhost's DNS domain and attempt to retrieve a TXT record for the entry '_maven.domain.org'. If it finds a TXT record by this name, it will attempt a HTTP GET to retrieve the routing table JSON document. Once again, the 'router-user' and 'router-password' properties can be used to authenticate this request. If neither of these discovery attempts work, Maven will fall back to the canonical routing table URL. If the user configures the 'discovery-strategies' property to 'none', this DNS discovery step will be skipped.
+
+While it would be possible to host the default routing table on the main maven.apache.org site, using repository.apache.org offers the flexibility to store or generate the routing table. For instance, we could store mirror records in a CouchDB instance, or generate them based on the contents and configuration of a repository manager. Using a more dynamic source for the canonical routing table gives us the opportunity to write a UI for maintaining the mirror entries. For example, it would be relatively straightforward to write a Javascript- and CouchDB-based application to support simple operations like enabling or disabling a mirror, updating a mirror's weight, or adding and removing mirrors.
+
+[ORIGINAL README FOLLOWS]
+=========================
+
 Homepage
 ========
 <http://maven.apache.org/>