All methods operate as a sub process of a main controlling parent. 3 FD's are
opened for use by the method allowing two way communication and emergency error
reporting. The FD's correspond to the well known unix FD's, stdin, stdout and
stderr.
Through operation of the method communication is done via http style plain
text. Specifically RFC-822 (like the Package file) fields are used to describe
items and a numeric-like header is used to indicate what is happening. Each of
these distinct communication messages should be sent quickly and without pause.
In some instances APT may pre-invoke a method to allow things like file URI's
to determine how many files are available locally.
The first line of each message is called the message header. The first 3
digits (called the Status Code) have the usual meaning found in the http
protocol. 1xx is informational, 2xx is successful and 4xx is failure. The 6xx
series is used to specify things sent to the method. After the status code is
an informational string provided for visual debugging.
100 Capabilities - Method capabilities
101 Log - General Logging
102 Status - Inter-URI status reporting (login progress)
200 URI Start - URI is starting acquire
201 URI Done - URI is finished acquire
400 URI Failure - URI has failed to acquire
401 General Failure - Method did not like something sent to it
402 Authorization Required - Method requires authorization to access the URI.
Authorization is User/Pass
403 Media Failure - Method requires a media change
600 URI Acquire - Request a URI be acquired
601 Configuration - Sends the configuration space
602 Authorization Credentials - Response to the 402 message
603 Media Changed - Response to the 403 message
Only the 6xx series of status codes is sent TO the method. Furthermore the
method may not emit status codes in the 6xx range. The Codes 402 and 403
require that the method continue reading all other 6xx codes until the proper
602/603 code is received. This means the method must be capable of handling an
unlimited number of 600 messages.
The flow of messages starts with the method sending out a 100
Capabilities and APT sending out a 601 Configuration. After that
APT begins sending 600 URI Acquire and the method sends out 200
URI Start, 201 URI Done or 400 URI Failure. No
synchronization is performed, it is expected that APT will send 600 URI
Acquire messages at -any- time and that the method should queue the
messages. This allows methods like http to pipeline requests to the remote
server. It should be noted however that APT will buffer messages so it is not
necessary for the method to be constantly ready to receive them.
The following is a short index of the header fields that are supported
URI
URI being described by the message
Filename
Location in the filesystem
Last-Modified
A time stamp in RFC1123 notation for use by IMS checks
IMS-Hit
The already existing item is valid
Size
Size of the file in bytes
Resume-Point
Location that transfer was started
MD5-Hash
Computed MD5 hash for the file
Message
String indicating some displayable message
Media
String indicating the media name required
Site
String indicating the site authorization is required for
User
Username for authorization
Password
Password for authorization
Fail
Operation failed
Drive
Drive the media should be placed in
Config-Item
A string of the form item=value derived from the APT
configuration space. These may include method specific values and general
values not related to the method. It is up to the method to filter out the
ones it wants.
Single-Instance
Requires that only one instance of the method be run This is a yes/no value.
Pipeline
The method is capable of pipelining.
Local
The method only returns Filename: fields.
Send-Config
Send configuration to the method.
Needs-Cleanup
The process is kept around while the files it returned are being used. This is
primarily intended for CDROM and File URIs that need to unmount filesystems.
Version
Version string for the method
This is a list of which headers each status code can use
100 Capabilities
Displays the capabilities of the method. Methods should set the pipeline bit
if their underlying protocol supports pipelining. The only known method that
does support pipelining is http. Fields: Version, Single-Instance, Pre-Scan,
Pipeline, Send-Config, Needs-Cleanup
101 Log
A log message may be printed to the screen if debugging is enabled. This is
only for debugging the method. Fields: Message
102 Status
Message gives a progress indication for the method. It can be used to show
pre-transfer status for Internet type methods. Fields: Message
200 URI Start
Indicates the URI is starting to be transfered. The URI is specified along
with stats about the file itself. Fields: URI, Size, Last-Modified,
Resume-Point
201 URI Done
Indicates that a URI has completed being transfered. It is possible to specify
a 201 URI Done without a URI Start which would mean no data
was transfered but the file is now available. A Filename field is specified
when the URI is directly available in the local pathname space. APT will
either directly use that file or copy it into another location. It is possible
to return Alt-* fields to indicate that another possibility for the URI has
been found in the local pathname space. This is done if a decompressed version
of a .gz file is found. Fields: URI, Size, Last-Modified, Filename, MD5-Hash
400 URI Failure
Indicates a fatal URI failure. The URI is not retrievable from this source.
As with 201 URI Done200 URI Start is not required to precede
this message Fields: URI, Message
401 General Failure
Indicates that some unspecific failure has occurred and the method is unable to
continue. The method should terminate after sending this message. It is
intended to check for invalid configuration options or other severe conditions.
Fields: Message
402 Authorization Required
The method requires a Username and Password pair to continue. After sending
this message the method will expect APT to send a 602 Authorization
Credentials message with the required information. It is possible for a
method to send this multiple times. Fields: Site
403 Media Failure
A method that deals with multiple media requires that a new media be inserted.
The Media field contains the name of the media to be inserted. Fields: Media,
Drive
600 URI Acquire
APT is requesting that a new URI be added to the acquire list. Last-Modified
has the time stamp of the currently cache file if applicable. Filename is the
name of the file that the acquired URI should be written to. Fields: URI,
Filename Last-Modified
601 Configuration
APT is sending the configuration space to the method. A series of Config-Item
fields will be part of this message, each containing an entry from the
configuration space. Fields: Config-Item.
602 Authorization Credentials
This is sent in response to a 402 Authorization Required message. It
contains the entered username and password. Fields: Site, User, Password
603 Media Changed
This is sent in response to a 403 Media Failure message. It indicates
that the user has changed media and it is safe to proceed. Fields: Media, Fail
copy - (internal) For copying files around the filesystem
file - For local files
gzip - (internal) For decompression
http - For HTTP servers
The two internal methods, copy and gzip, are used by the acquire code to
parallize and simplify the automatic decompression of package files as well as
copying package files around the file system. Both methods can be seen to act
the same except that one decompresses on the fly. APT uses them by generating
a copy URI that is formed identically to a file URI. The destination file is
send as normal. The method then takes the file specified by the URI and writes
it to the destination file. A typical set of operations may be:
http://foo.com/Packages.gz -> /bar/Packages.gz
gzip:/bar/Packages.gz -> /bar/Packages.decomp
rename Packages.decomp to /final/Packages
The http method implements a fully featured HTTP/1.1 client that supports deep
pipelining and reget. It works best when coupled with an apache 1.3 server.
The file method simply generates failures or success responses with the
filename field set to the proper location. The cdrom method acts the same
except that it checks that the mount point has a valid cdrom in it. It does
this by (effectively) computing a md5 hash of 'ls -l' on the mountpoint.