(II) Download Service to a Download Manager

Overview:

There are 2 basic steps to integrate the Download service to a Download Manager (or other application) and start using DNA to deliver content through the DNA peer network:

1. Check that the existing distribution infrastructure conforms to the Basic DNA Integration Requirements
2. Configure your Download Manager to send correctly-formed URLs to DNA through the "DNA Proxy API"

1. Check Basic DNA Integration Requirements

Integration of the DNA service relies on some basic requirements from your existing distribution infrastructure.   

You can check whether your content servers meet these requirements by using the DNA URL Requirements Tester Tool.  The Tester tool is a simple text box into which you can type the fully qualified URL of a piece of your content on one of your content servers. It will return advice on whether servers conform to ideal DNA requirements.  In cases where your distribution infrastructure does not conform to these requirements, the Tester Tool will provide an error message as to the issue, and the infrastructure should be reconfigured accordingly.  For a list of potential error messages and corresponding solutions see DNA URL Requirements Tester Tool. For any additional assistance use BitTorrent DNA support.

The following is the list of requirements for your distribution infrastructure to conform to ideal DNA requirements:

Web-servers:

• You must have access to web servers and have permissions to host a DNA JavaScript file to be provided by BitTorrent Inc.
• You must have permissions to adjust HTML on your website to load the DNA JavaScript file on each relevant page and be able to modify content URLs on the page to invoke functions that the DNA JavaScript file provides.

Content-servers and Content:

• Your content servers must support “range requests” and should support “persistent” or “keep-alive” connections of at least 2 seconds duration.
• You must have exclusive use of the domain or domains from which the content is served.
• You must know the fully qualified URL or URLs for each piece of content to be DNA-enabled.
• The fully qualified URL or URLs for each piece of content must be persistent over time.
• The actual files to which the fully qualified URL or URLs point must remain unchanged over time.
• Content servers must not require any form of authentication to enable downloads. BitTorrent DNA only supports HTTP (HTTPS is not yet supported).
• All popular content servers are supported with the exception of Microsoft IIS v5.1 (which does not support range requests).

2. Connect to DNA through the "DNA Proxy API"

A Download Manager (or any other type of application that can communicate via HTTP) may connect with DNA through the DNA Proxy API by passing specially-formed URLs (which conform to the DNA Proxy API) to the DNA port on localhost.

Calls using the URL-based DNA Proxy API obey the following syntax, where key-value pairs can be provided in any order:

http://localhost:btdna_proxy_port/proxy?
    url=origin_url
        &service=service_name&service_parameter_1=value_1
        &service_parameter_N=value_N  

Specify the port over which the DNA proxy is active:

The btdna_proxy_port must be specified. It is the port on which the DNA localhost proxy is active and is represented by an integer discovered using a platform-specific mechanism. In Windows, the platform-specific mechanism is the Windows registry – the port is stored as a DWORD value under HKEY_CURRENT_USER\Software\BitTorrent\engine\port. Check Advanced Integration section for more details on how to discover the port.

Specify the URL (or URLs) of the Origin Content:

Each piece of content passed to the DNA Proxy API must be identified by an origin_url. Every such origin_url must be “URL-encoded” (sometimes called “percent-encoded”) meaning that some “reserved characters” must be input using a special convention. This function is done automatically if using the DNA JavaScript or DNA ActionScript APIs. However, if addressing the DNA Proxy API directly, this additional step is important. The type of URL-encoding required is equivalent to that performed by the standard JavaScript function encodeURIComponent().

An origin_url is any valid URL that references an object on a server that communicates using HTTP 1.1 supporting range requests and persistent (“keep alive”) connections.  The domain name may refer to a web server or CDN.  DNA does not currently support SSL.

In cases where the same content is available from several different sources (e.g. more than one server or CDN), then multiple origin_urls may be added as follows:

url=origin_url_1
     &url=another_url_for_the_same_thing
         &url=origin_url_N 

This will join the URLs together in an equivalence class.

(NOTE: in case DNA parameters are set for each individual URL and if there are conflicting parameter settings on individual URLs that are then grouped with no value explicitly specified for the class as a whole, the value from the last listed URL with an explicitly specified value becomes the value for the class as a whole.)

Specify the Name of the DNA Service to be Used:

The service_name should select either the DNA downloads (min_rate_data) service or the progressive download/HTTP streaming service (streaming) and should be specified as either:

min_rate_data

                or

streaming

(NOTE: in case the ‘service=’ parameter is not specified, DNA will default to download the file using the standard DNA Download service unless the MIME type or file extension suggests that it is a stream-able file, in which case the DNA Streaming service will be used.)

Specify the Quality of Service parameter for the Download service:

For the DNA Download service the qos parameter must be set. Quality of service is defined as the minimum acceptable download speed for downloads – it does not guarantee a quality of service from the peer network, but rather indicates a delivery speed which DNA will attempt to achieve from the peer network but will fall back to the web server to maintain in case the peer network is not sufficient. The ability to actually meet this quality of service is ultimately determined by the origin servers, not by DNA. The qos parameter is specified in bytes-per-second. (NOTE – this is not bits per second – there are 8 bits for every byte, and 1024 bytes in a kilobyte etc.).

Setting a quality of service of 1 byte-per-second will result in the maximum possible bytes being pulled from the peer network. DNA will pull everything it can from the peer network and will only pull from the HTTP server to ensure that it can maintain a minimum data rate of (in this case) 1 byte-per-second. In this scenario, if there are no peers available, the download may take a long time. This may not matter if the end-user is not expected to be actively watching a download (e.g. in the case of background downloads.)

Setting a quality of service at a higher value (e.g. 100,000 bytes-per-second (i.e. 800 kilobits-per-second)) will cause DNA to pull everything it can from the peer network but fall back on the HTTP server if necessary to maintain a minimum data rate of 100,000 bytes-per-second. This type of setting may be important if the end-user is expected to be actively watching a download (e.g. in the case of foreground or user-visible downloads).

Setting a quality of service at 0 is a special setting which is essentially the same as setting it to an infinitely large amount. The behavior of DNA in this scenario is to pull data from the server and from peers as quickly as possible in unison. In practice the “offload” (peer-network-delivered bytes) will usually be lower in this scenario although DNA will always retain a small amount of bandwidth for attempting to obtain data from the peer network. In cases where peers can deliver faster than a server, those peers will be preferred over the server.

In the case that no quality of service value is specified, DNA will apply a qos value of 0 (which will eliminate any expected impact to the end-user experience but may reduce the level of offload).

Additional DNA Proxy API Parameters:

Additional DNA parameters can be passed using the DNA Proxy API to tune the service. A full list is presented in the Advanced Integration section.

EXAMPLE:

As an example, the following is the URL that a Download Manager app should pass through the DNA Proxy API where DNA is listening on port 4096 and is required to download a piece of content from http://downloads.mysite.com/my/own/file.ext using the min_rate_data service with a minimum QOS of 50000 bytes per second. (Note the URL-encoding which results in the character “:” being replaced by “%3A” and the character “/” being replaced by “%2F”) :

http://localhost:4096/proxy?url=http%3A%2F%2Fdownloads.mysite.com%2Fmy%2Fown%2Ffile.ext&service=min_rate_data&qos=50000

In the case that the download fails you may wish to design the Download Manager or other app to fetch the content from the original URL without making use of DNA. This will preserve the end users ability to reach content in the case that DNA service is interrupted either by design (domains or torrents are suspended) or through outage (e.g. scheduled maintenance windows or unforeseen service issues.)