P2P:Protocol:Specifications:Magnet

From Depthstrike Entertainment
Jump to: navigation, search

Document Status

Magnet Specification originally created 2002-06-12

Previous Revisions include 2002-06-17.

This specification is still draft as of this writing.

Due to the modular design of magnets, portions of this document may change without notice.

Original document by Gordon Mohr gojomo@bitzi.com

This version by Harold Feit dreadwingknight@gmail.com / dwknight@depthstrike.com


Abstract

This document describes the primary syntax and usage of magnet links and their general uses in computer programs.

The Magnet URI was originally designed to be an application nonspecific version of the Freenet's freenet: and eDonkey/eMule's ed2k: peer to peer file identifier links.


Introduction

This document is based primarily on RFC 1738 and RFC 2396.

The decision to use the word Magnet was not based on any acronym, but rather the concept of bringing multiple dissimilar applications and groups together on common concepts.

Magnets are processed client-side and not server side. The typical intention is to have a preprocessor loaded on a system that gives users a list of supporting programs and the option to load the magnet into one of them. This document only handles what common values are used, not what individual applications do once they have them.

URI Construction

The Magnet URI starts with "magnet:?" as its prefix. No "//" is present at this point because the URI's namespace is not hierarchial.

Application-specific paramaters should be prefixed with x. so their implementations do not interfere with official paramaters.

Application-specific values of official paramaters that are not recognized by an application should be ignored.

Official Paramaters

This section describes the official paramaters present in a magnet link.

When an application is passed a paramater, it is up to that application to either support it or ignore it.

x.* paramaters are used for application-specific extensions.

Numbered suffixes on paramater names are used to reference multiple different topics in the same URI. Each number is a different topic.

The xt, dn, xl, xs and as paramaters group by numbered suffix.

xt - eXact Topic

This paramater specifies the exact topic to be displayed. Multiple xt= paramaters are permitted. When a numbered siffix is not present, most applications typically assume that all the xt= paramaters reference the same topic. This is generally accepted behavior.

Currently in-use xt= paramater value prefixes (not sorted):

   * urn:sha1:<SHA1 Base32>
   * urn:ed2k:<ED2K Hexadecimal>
   * urn:ed2khash:<ED2K Hexadecimal>
   * urn:bitprint:<SHA1 Base32>.<TigerTree Root Base32>
   * urn:md5:<MD5 Hexadecimal>
   * urn:tree:tiger:<TigerTree Root Base32>
   * urn:tree:tiger/:<TigerTree Root Base32>
   * urn:tree:tiger/1024:<TigerTree Root Base32>
   * urn:kzhash:<KaZaA Hexadecimal>
   * urn:btih:<Torrent SHA1 InfoHash Base32> 

The xt= paramater may, in some cases, be another URI such as a http:// or ftp:// link.

kt - Keyword Topic

This paramater specifies keywords to locate the sought after topic. The typical use of this paramater is to pre-populate a search box in a given application.

dn - Display Name

This paramater is typically used in conjunction with the xt= paramater to give a friendly name for a user.

xs/as - eXact Source/Acceptable Source

These paramaters are used to give known locations for obtaining files referenced using the xt= paramater. In general use, these paramaters are interchangable, although some applications only recognize xs, and others preference xs sources.

When both xs= and as= sources are used in the same magnet, xs= sources are typically used to reference a file by a hash (usually one referenced in an xt= paramater), and as= sources are used for traditional links such as a sourceforge mirror.

The value for these paramaters can be any URI that directly references a file, including http:// ftp:// ed2kftp://

mt - Manifest Topic

This paramater is used to reference a metafile that has definitions for multiple topics in it.

xl - eXact Length

(Pending approval for official status)

This paramater is used to specify the length in bytes of the file referenced by a given xt= paramater.

Implementation

Implementation of magnets has been migrating from javascript site-based implementation to application client-based implementation.

Current specifications permit for both.

Pre-Parsers on the client side populate a list of magnet supporting applications, and when passed a magnet, they prompt the user if more than one supporting application is present.

JavaScript Implementation

It is usually possible to have these URIs work by having javascript in the originating page capture clicks on such URIs -- without any prior browser/platform-specific installation. Local apps just have to listen for local requests to provide options.

Specifically, each local app that wants to be given the chance to offer up options for MAGNET URIs should open a mini-HTTP-listener on the lowest available port, in the range 45100-45199. If not in the first 5 positions (45100-45104), they should also periodically check to see if higher positions open up, and if so, move downward with their MAGNET-listening service.

Such MAGNET-listening services should only accept inbound connections from the local machine.

The common Javascript and HTML templates which capture clicks on "magnet:" URIs -- or the "magnet:" URI handling code installed in the browser- and platform- specific manner -- discovers all local options via GETs against local URLs including:

http://127.0.0.1:451XX/magnet10/badge.img http://127.0.0.1:451XX/magnet10/canHandle.img(?params) http://127.0.0.1:451XX/magnet10/options.js(?params) http://127.0.0.1:451XX/magnet10/default.js(?params) http://127.0.0.1:451XX/magnet10/closeNotify(?port) http://127.0.0.1:451XX/magnet10/pause

/magnet10/badge.img

Return a gif/jpeg/png image, 90x30, representing your program. Any server not returning such a valid logo will be considered to be something other than a MAGNET-compliant server. Web pages can poll for these images to see if services are available, and peer MAGNET services can poll for these images to find their port-neighbors (or see when they go away).

/magnet10/canHandle.img

/magnet10/canHandle.img(?params)

Given the params -- which are the same as the contents of a "magnet:" URI, after the '?' -- if your program can offer any operations for those parameters, return a 90x30 image. If you cannot offer any useful options for those paramters, return a NOT-FOUND or other error. The test of whether or not the program can handle the params should not take excessively long or trigger signficant CPU/network traffic.

/magnet10/options.js

/magnet10/options.js(?params)

Given the params, lifted from a "magnet:" URI, display identifying info about your program and any relevant links/forms/etc. showing what is possible for those parameters. You have total control over what is rendered, via Javascript document.write() commands, but keep in mind the program's options may be rendered in a page in line with other programs' options as well. The assembly of available options and relevant graphics should not trigger significant CPU/network traffic or take a long time; such costly actions should only be undertaken after an intentional user choice.

The variable 'magnetCurrentSlot' will be set to the relative port (eg 0-99) this code came from, before it is run. The variables 'magnetOptionsPreamble' and 'magnetOptionsPostamble' will contain strings the options code should emit before and after its custom HTML. If successful in rendering any information at all, the variable 'magnetOptionsPollSuccesses' should be incremented by 1.

/magnet10/default.js

/magnet10/default.js(?params)

Given the params, lifted from a "magnet:" URI, perform the programs' "default" action and return javascript which renders an indication this has occurred, and perhaps offers other options. The default action should not be excessively taxing on the local machine or the network, at least not beyond common user expectations. (For example, it is acceptable for a Gnutella servent to initiate a regular search as its default action.) If no default action makes sense, just return the same javascript as for options.js.

/magnet10/closeNotify

/magnet10/closeNotify(?port)

Parameter port will be a port number lower than the port this request is delivered to. It indicates that the server on that port is going through an orderly shutdown. Server may report any success (2xx) code to indicate that it plans to relocate up to the given port, or any failure code (4xx/5xx) if it plans to stay put.

/magnet10/pause

MAGNET service should keep the requestor waiting for 250ms, then return an error/empty content-body. (Javascript has no truly idle wait -- but making an inline request for a resource from a socket that doesn't answer, or only answers after a delay, is almost as good.)

Magnet Service Shutdowns

A MAGNET service going through an orderly shutdown should generate closeNotify requests to each port number higher than itself, one at a time in sequence, until it either gets back a success code or receives 5 "unable to connects" (eg no listener).

Other Implementations

Other implementations of magnet link handling include client-side C++ and an in-progress VB.Net/C# implementation.

The priorities when developing such an implementation should be to intelligently parse known supporting programs, provide accurate lists of programs that support a given magnet, and pass the magnet to that application cleanly.

Pre-processing of the magnet (Such as xs/as sub-URI replacement) is permitted so long as specifications are followed.