[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

New Method Spec

Here is the first just mostly finished draft of the new method interface..

                           APT Method Interface 
                     Jason Gunthorpe <jgg@debian.org>
           $Id: method.sgml,v 1.1 1998/10/04 04:49:17 jgg Exp $

0.1 Abstract

     This document describes the interface that APT uses to the archive
     access methods.

0.2 Contents

     1.        Introduction
     1.1.      General 
     1.2.      Terms 

     2.        Specification
     2.1.      Overview 
     2.2.      Message Overview 
     2.3.      Header Fields 
     2.4.      Examples 

0.3 Copyright Notice

     Copyright © Jason Gunthorpe, 1998.

     "APT" and this document are free software; you can redistribute them
     and/or modify them under the terms of the GNU General Public License
     as published by the Free Software Foundation; either version 2 of the
     License, or (at your option) any later version. 

     For more details, on Debian GNU/Linux systems, see the file
     /usr/doc/copyright/GPL for the full license.


1. Introduction

1.1. General 

     The APT method interface allows APT to aquire archive files (.deb),
     index files (Packages, Revision, Mirrors) and source files (.tar.gz,
     .diff). It is a general, extensible system designed to satisfy all of
     these requirements: 

     1.   Remote methods that download files from a distant site

     2.   Resume of aborted downloads

     3.   Progress reporting

     4.   If-Modified-Since (IMS) checking for index files

     5.   In-Line MD5 generation

     6.   No-copy in-filesystem methods

     7.   Multi-media methods (like CD's)

     8.   Dynamic source selection for failure recovery

     9.   User interaction for user/password requests and media swaps

     10.  Global configuration

     Initial releases of APT (0.1.x) used a completely different method
     interface that only supported the first 6 items. This new interface
     deals with the remainder.

1.2. Terms 

     Several terms are used through out the document, they have specific
     meanings which may not be immediately evident. To clarify they are
     summarized here. 

          Refers to an item in source list. More specifically it is the
          broken down item, that is each source maps to exactly one index
          file. Archive sources map to Package files and Source Code
          sources map to Source files. 

     archive file
          Refers to a binary package archive (.deb, .rpm, etc). 

     source file
          Refers to one of the files making up the source code of a
          package. In debian it is one of .diff.gz, .dsc. or .tar.gz. 

          Universal Resource Identifier (URI) is a super-set of the
          familiar URL syntax used by web browsers. It consists of an
          access specification followed by a specific location in that
          access space. The form is <access>:<location>. Network addresses
          are given with the form
          <access>://[<user>:<pas>>@]hostname[:port]/<location>. Some
               cdrom:Debian 2.0r1 Disk 1/

          There is a one to one mapping of URI access specifiers to
          methods. A method is a program that knows how to handle a URI
          access type and operates according to the specifications in this

     method instance
          A specific running method. There can be more than one instance of
          each method as APT is capable of concurrent method handling. 

          A series of lines terminated by a blank line sent down one of the
          communication lines. The first line should have the form xxx TAG
          where xxx are digits forming the status code and TAG is an
          informational string 

          The act of bring a URI into the local pathname space. This may
          simply be verifiying the existance of the URI or actually
          downloading it from a remote site. 


2. Specification

2.1. Overview 

     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 corrispond to the well known
     unix FD's, stdin, stdout and stderr. 

     The basic startup sequence depends on how the method is invoked. If
     any command line arguments are passed then the method should start in
     automatic mode. This facility is provided soley to make the methods
     easier to test and perhaps use outside of APT. Upon startup the method
     will print out a header describing its capabilities and requirements.
     After that it either begins processing the command line arugments and
     exits when done or waits for commands to be fed to it. 

     Throught 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.

2.2. Message Overview 

     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 successfull 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

        * 100 Capabilities - Method capabilities

        * 101 Log - General Logging

        * 102 Status - Inter-URI status reporting (login progress)

        * 200 URI Start - URI is starting aquire

        * 201 URI Done - URI is finished aquire

        * 400 URI Failure - URI has failed to aquire

        * 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 Aquire - Request a URI be aquired

        * 601 Configuration - Sends the configuration space

        * 602 Authorization Credentials - Response to the 402 message

        * 603 Media Changed - Response to the 403 message

        * 605 Shutdown - Exit

     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 recieved. 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 Aquire* and the method sends out *200 URI
     Start*, *201 URI Done* or *400 URI Failure*. No syncronization is
     performed, it is expected that APT will send *600 URI Aquire* 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
     neccessary for the method to be constantly ready to recieve them.

2.3. Header Fields 

     The following is a short index of the header fields that are supported

          URI being described by the message

          Location in the filesystem

          A time stamp in RFC1123 notation for use by IMS checks

          Size of the file in bytes

          Location that transfer was started

          Computed MD5 hash for the file

          String indicating some displayable message

          String indicating the media name required

          String indicating the site authorization is required for

          Username for authorization

          Password for authorization

          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.

          Requires that only one instance of the method be run This is a
          yes/no value.

          Method can detect if archives are already available. This is a
          yes/no value.

          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. Fields: Version,
          Single-Interface, Pre-Scan 

     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. 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 Done* *200 URI Start* is not
          required to preceed this message Fields: URI, Message 

     401 General Failure
          Indicates that some unspecific failure has occured 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 

     600 URI Aquire
          APT is requesting that a new URI be added to the aquire list.
          Last-Modified has the time stamp of the currently cache file if
          applicable. Filename is the name of the file that the aquired 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 

     605 Shutdown
          APT sends this to signal the shutdown of the method. The method
          should terminate immidiately. Fields: None

2.4. Examples 


     APT Method Interface 
     Jason Gunthorpe <jgg@debian.org> - $Id: method.sgml,v 1.1 1998/10/04
     04:49:17 jgg Exp $

Reply to: