NAME
Mirror::YAML - Mirror Configuration and Auto-Discovery
DESCRIPTION
A mirror.yml file is used to allow a repository client to reliably and robustly locate, identify, validate and age a repository.
It contains a timestamp for when the repository was last updated, the URI for the master repository, and a list of all the current mirrors at the time the repository was last updated.
Mirror::YAML contains all the functionality requires to both create and read the mirror.yml files, and the logic to select one or more mirrors entirely automatically.
It currently scales cleanly for a dozen or so mirrors, but may be slow when used with very large repositories with a hundred or more mirrors.
Methodology
A variety of simple individual mechanisms are combined to provide a completely robust discovery and validation system.
URI Validation
The mirror.yml file should exist in a standard location, typically at the root of the repository. The file is very small (no more than a few kilobytes at most) so the overhead of fetching one (or several) of them is negligable.
The file is pulled via FTP or HTTP. Once pulled, the first three characters are examined to validate it is a YAML file and not a login page for a "captured hotspot" such as at hotels and airports.
The shorter ".yml" is used in the file name to allow for Mirror::YAML to be used even in the rare situation of mirrors that must work on operating systems with (now relatively rare) 8.3 filesystems.
Responsiveness
Because the mirror.yml file is small (in simple cases only one or two packets) the download time can be used to measure the responsiveness of that mirror.
By pulling the files from several mirrors, the comparative download times can be used as part of the process of selecting the fastest mirror.
Timestamp
The mirror.yml file contains a timestamp that records the last update time for the repository. This timestamp should be updated every repository update cycle, even if there are no actual changes to the repository.
Once a mirror.yml file has been fetched correctly, the timestamp can then be used to verify the age of the mirror. Whereas a perfectly up to date mirror will show an age of less than an hour (assuming that the repository master updates every hour) a repository that has stopped updating will show an age that is greater than the longest mirror rate plus the update cycle time.
Thus, any mirror that as "gone stale" can be filter out of the potential mirrors to use.
For portability, the timestamp is recording in ISO format Zulu time.
Master Repository URI
The mirror.yml file contains a link to the master repository.
If the Mirror::YAML client has an out-of-date current state at some point, it will use the master repository URI in the current state to pull a fresh mirror.yml from the master repository.
This solves the most-simple case, but other cases require a little more complexity (which we'll address later).
Mirror URI List
The mirror.yml file contains a simple list of all mirror URIs.
Apart from filtering the list to try and find the best mirror to use, the mirror list allows the Mirror::YAML client to have backup options for locating the master repository if it moves, or the bootstrap mirror.yml file has gotten old.
If the client can't find the master repository (because it has moved) the client will scan the list of mirrors to try to find the location of the updated repository.
The Bootstrap mirror.yml
To bootstrap the client, it should come with a default bootstrap mirror.yml file built into it. When the client starts up for the first time, it will attempt to fetch an updated mirror.yml from the master repository, and if that doesn't exist will pull from the default list of mirrors until it can find more than one up to date mirror that agrees on the real location of the master server.
Anti-Hijacking Functionality
On top of the straight forward mirror discovery functionality, the client algorithm contains additional logic to deal with either a mirror or the master server goes bad. While likely not 100% secure it heads off several attack scenarios to prevent anyone trying them, and provides as much as can be expected without resorting to cryto and certificates.
SUPPORT
Bugs should be reported via the CPAN bug tracker at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Mirror-URI
For other issues, or commercial enhancement or support, contact the author.
AUTHOR
Adam Kennedy <adamk@cpan.org>
SEE ALSO
Mirror::JSON, Mirror::CPAN, YAML::Tiny
COPYRIGHT
Copyright 2007 - 2009 Adam Kennedy.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.