The Passthrough Frontend
========================

The Passthrough frontend basically replays the ConfModule protocol over a 
Unix domain socket so that other programs can "listen" in and actually
implement the user interface. With some minor additions, the protocol is
designed to mirror the ConfModule protocol as closely as feasible.

A typical session goes like this: (time moves downwards)
In this diagram, and in the rest of this document, "Passthrough" denotes 
the Debconf passthrough frontend, Frontend represents a user-supplied
program that understands this interface.


Confmodule              Passthrough             Frontend
---------------         --------------          ----------------------
CAPB backup      ->
                        CAPB backup        ->
                                           <-   0 backup
                 <-     CAPB backup
INPUT foo/bar    ->     (stored)
                 <-     0 question will be asked
INPUT foo/baz    ->     (stored)
                 <-     0 question will be asked
GO               ->
                        DATA foo/bar type boolean ->
                                           <-   0 OK
                        DATA foo/bar description some description ->
			                   <-   0 OK
			DATA foo/bar extended_description etc ->
			                   <-   0 OK
			INPUT medium foo/bar ->
			                   <-   0 OK
                        DATA foo/baz description some description ->
			                   <-   0 OK
			DATA foo/baz extended_description etc ->
			                   <-   0 OK
			INPUT low foo/baz ->
			                   <-   0 OK
			GO                 ->
			                   <-   0 OK (or 30 GOBACK)
                        GET foo/bar        ->
			(stored)           <-   0 true
                        GET foo/baz        ->
			(stored)           <-   0 my input
	         <-     0 OK
GET foo/bar      ->
                 <-     true
GET foo/baz      ->
                 <-     my input
STOP



Each request from Passthrough will block until it receives a reply from
the Frontend.

Communications
~~~~~~~~~~~~~~
Communication between the Passthrough module and the Frontend takes place
over a Unix domain socket connection. The DEBCONF_PIPE environment variable
must be set to the filename to use for the socket.

When the Passthrough module starts up, it expects the socket to already
exist. The Frontend is responsible for creating the socket and be ready
to listen on it prior to invoking Debconf with the Passthrough module.

The socket should be created with mode 0400, and owned by root:root
It should be removed when the Frontend exits.

All communication between the Passthrough module and the Frontend is defined
to be encoded in UTF-8. Both sides are responsible for recoding between
UTF-8 and whatever their internal character encoding may be.

DATA/INPUT/GO/GET mechanism
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unlike existing Debconf frontends, the Frontend does not have access
to the template information directly. In order for it to have that
information, the Passthrough module is responsible for sending it
the information. This is done via the DATA mechanism, by sending
commands like this:

	DATA <tag> <item> <value>

   where: 
	<tag> is the name of the template, e.g. debconf/frontend
	<item> is one of {"type", "description", "extended_description", "choices"}
	<value> is the value of the <item>, with all newlines converted to 
	        "\\n" (i.e. 0x2F 0x6E)

All DATA information will be sent to the Frontend prior to sending any
INPUT commands with the same tag.

After DATA commands for a <tag> is sent, a corresponding SET command may
be sent to set the default value for that question, if a default was
defined, viz:

	SET <tag> <value>
  where:
  	<tag> is the name of the template
	<value> is the default value of the question

If any substitution variables were set, corresponding SUBST commands may be
sent:

	SUBST <tag> <key> <value>
  where:
	<tag> is the name of the template
	<key> is the name of the variable to substitute
	<value> is the value to substitute in place of the named variable

Finally, a corresponding INPUT command will be sent as:

	INPUT <priority> <tag>
  where:
  	<priority> is the priority of the question
	<tag> is the name of the template

An INPUT command will be issued to the Frontend for each INPUT command
received by the Passthrough module prior to a GO command. After all INPUT
commands have been sent to the Frontend, a GO will be sent. At this point
the Frontend should query the user for information, and return either:
	0 OK		if everything is ok
  or:
	30 GOBACK	if the user requested to go back to a previous question

If a GOBACK request was received and the ConfModule supports the backup 
capability, the previous set of questions will be asked again, with all
DATA commands reissued.

Otherwise, if an OK condition was returned, the Passthrough module will issue
the same number of GET commands as previously sent INPUT commands, in the 
form of:

	GET <tag>

to which the Frontend should reply with:

	0 <value>
  where:
	<value> was the answer to the question of the given <tag>

Shutdown
~~~~~~~~
Whether the ConfModule explicitly requests a STOP, or when the ConfModule ends,
the passthrough module will send a STOP command to the Frontend to inform it
that the current configuration session has been completed.

Error Handling
~~~~~~~~~~~~~~
At any point in time, the Frontend may indicate an error condition by sending
a response such as:
	100 <error message>

This signals the Passthrough module that something is wrong. At the time of 
this writing, unfortunately, the Passthrough module does not handle errors 
very gracefully.

Implementation Details/Hints for the Frontend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The frontend needs to be careful about storing information across multiple
DATA/INPUT/GO/GET requests. After any GET requests, the next DATA/INPUT
request should cause any pending question/answer information at the Frontend 
side to be discarded. Similarly, when a Frontend sends back a "30 GOBACK" 
response to a GO command, it should take care to clear out previous 
question/answer information.