Project Etiquette Quick Start Guide

Table of Contents

Introduction

The project's goal is to build a framework for rapid design of network
communication code. Etiquette interaction protocols will capture
communication occurring in networked applications along with
error-handling and security monitoring code. Etiquette provides
debugging facilities (tracing and single-stepping the protocols, with
fine-grained control over the reported details).
Features implemented:

First-class interaction protocols

Support for legacy protocols

Basic error handling

Debugging facilities

Iteration syntax

TCP/IP communication transport

HTTP subset protocol

Etiquette is a developing project, and a number of other important
features is expected to be added in near future.

Etiquette is implemented in Common Lisp, and is distributed under
the terms of FSF General Public License (if you feel that this license
is too strict for your needs, please contact the author). The latest
version of Etiquette can be obtained from its SourceForge project
page.

Concepts and terminology

The project aids to abstract the communication processes occuring
in distributed and networked systems.

We will use the following terms in the document:

Phase. An elementary unit of protocol, capturing a single logical
act of communication.

Interaction protocol, or protocol. The sequence of phases along
with control constructs that describes valid information exchange
flows between two agents.

Agent. An entity that can be involved in protocol in one or
both roles.

Role. The function of an agent in the given protocol. Can be
either :INITIATOR, or :RESPONDENT. :INITIATOR always starts the protocol,
while :RESPONDENT always expects the protocol to be initiated.

Technically, a protocol is a state machine. For it to run, the
protocol should be instantiated and started by both parties involved.

Etiquette Syntax

Etiquette defines a handful of syntactic constructions that can be
used to define interaction protocols.

Here, NAME specifies the protocol name, and a sequence of BODY-FORM
forms constitutes the protocol's control flow description. The
protocol can be passed a TRANSPORT layer it will use for
communication, a list of SUBPROTOCOLS it can execute, and
ERROR-HANDLING-POLICIES. All forms in protocol body are executed
sequentially.

TRANSFER defines an unconditional transfer phase from agent in role
FROM to agent in role TO. NAME defines the phase name.

TRANSFER-IF defines a conditional transfer phase from agent in
role FROM to agent in role TO. NAME defines the phase name. If the
condition denoted by PREDICATE is true on FROM agent side, the
CONSEQUENCE is executed, otherwise ALTERNATIVE is executed.

TRANSFER-CASE implements a selector construct. CASE-FORM is a list
of match and consequence. The result of SELECTOR invocation is
compared via EQ with matches of case-forms, and in case of success,
the appropriate consequence is invoked.

TRANSFER-WHILE defines an iterating phase. The ITERATED-FORM is
performed while the PREDICATE at the FROM side holds true. As soon as
the loop terminates, the mandatory EXIT-FORM is executed and control
is passed to a next phase. The EXIT-FORM is mandatory for
communication consistency reasons: consider that the protocol code is
simultaneously executed by two different agents, in different roles.

TRANSFER-FORM, ITERATED-FORM, EXIT-FORM, CONSEQUENCE and
ALTERNATIVE can be either symbols naming corresponding agent methods,
or subprotocol invocation forms. The latter has the following
syntax:

(subprotocol protocol-name)

where PROTOCOL-NAME is a symbolic name of the protocol to be
invoked.

Running Etiquette

Prerequisites

To run Etiquette you will need the following items installed on your
computer:

A recent CMU CL or SBCL compiler

DB-SOCKETS library if you run CMU CL

ASDF system definition facility

Running a protocol

Etiquette distribution includes a sample code of echo protocol
implementation.

To run the server-side agent:

Run the lisp compiler in Etiquette source directory

Enter (asdf:oos 'asdf:load-op 'etiquette)

Enter (asdf:oos 'asdf:load-op 'etiquette-samples)

Enter (in-package #:simple-echo)

Enter (run-agent (make-instance 'echo-server))

To run the client-side agent:

Run the lisp compiler in Etiquette source directory

Enter (asdf:oos 'asdf:load-op 'etiquette)

Enter (asdf:oos 'asdf:load-op 'etiquette-samples)

Enter (in-package #:simple-echo)

Enter (run-agent (make-instance 'echo-client))

Notice that there are also examples of an HTTP subset, file
retrieval protocol and non-conformant SMTP subset included.

When echo client starts, it should connect to the server. Both
client and server ask you for protocol termination at each
iteration. If you choose to terminate a protocol, the subportocol QUIT
is invoked.

Step-by-step example

Let's examine how the above mentioned echoing protocol and
associated agents were defined.

We defined a wrapping protocol that invokes FANCY-ECHO in a
loop. The TRANSFER-WHILE form will execute FANCY-ECHO while the
initiator maintains PROCEED conditional true. When iteration is done,
the subprotocol QUIT is invoked.

Now, what should we do if the server is bored with echo requests
and wants to terminate the session?

We have just modified the RESPONSE-PHASE clause to be
conditional. When this phase is executed, respondent agent's TERMINATE
method is invoked, and if it evaluates to NIL, the response is
transferred. Otherwise, the QUIT subprotocol is invoked.

Now, how all these QUERY, RESPONSE and PROCEED things are actually
handled? We should provide an implementation for methods returning a
value on :INITIATOR side, and methods that accept the received data on
RESPONDENT side. Currently both sending and receiving methods have
same signature, and sender methods just ignore the optional DATA
argument.

Predicates shall return NIL or non-NIL value based on the agent's
internal state.