[Search] [txt|pdf|bibtex] [Tracker] [WG] [Email] [Nits]

Versions: 00 01 02 03 04 05 06 07 rfc2371                               
Network Working Group                                            J. Lyon
Internet-Draft                                                 Microsoft
<draft-lyon-itp-nodes-00.txt>                           November 4, 1996
Expires in 6 months

                     Transaction Internet Protocol


Status of this Memo

   This document is an Internet-Draft.  Internet-Drafts are working
   documents of the Internet Engineering Task Force (IETF), its areas,
   and its working groups.  Note that other groups may also distribute
   working documents as Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   To learn the current status of any Internet-Draft, please check the
   "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
   Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
   munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
   ftp.isi.edu (US West Coast).

   Distribution of this document is unlimited. Please send comments to
   the author at <JimLyon@Microsoft.Com>.


Abstract

   In many applications where different nodes cooperate on some work,
   there is a need to guarantee that the work happens atomically.  that
   is, each node must reach the same conclusion as to whether the work
   is to be completed, even in the face of failures.  This document
   proposes a simple, easily-implemented protocol for achieving this
   end.

Introduction

   The standard method for achieving atomic committment is the two-phase
   commit protocol; see [1] for an introduction to atomic commitment and
   two-phase commit protocols.

   Numerous two-phase commit protocols have been implemented over the
   years.  However, none of them has become widely used in the Internet,
   due mainly to their complexity.  Most of that complexity comes from
   the fact that the two-phase commit protocol is bundled together with
   a specific program-to-program communication protocol, and that
   protocol lives on top of a very large infrastructure.

   This memo proposes a very simple two-phase commit protocol.  It
   achieves its simplicity by specifying only how different nodes agree
   on the outcome of a transaction; it allows (even requires) that the
   subject matter on which the nodes are agreeing be communicated via

Lyon                                                           [Page 1]


Internet-Draft      Transaction Internet Protocol      November 4, 1996

   other protocols.  By doing so, we avoid all of the issues related to
   application communication semantics, data representation, and
   security (to name just a few).

   It is envisioned that this protocol will be used mainly for a
   transaction manager on one Internet node to communicate with a
   transaction manager on another node.  While it is possible to use
   this protocol for application programs and/or resource managers to
   speak to transaction managers, this communication is usually
   intra-node, and most transaction managers already have more-than-
   adequate interfaces for the task.

   While we do not expect this protocol to replace existing ones, we do
   expect that it will be relatively easy for many existing
   heterogeneous transaction managers to implement this protocol for
   communication with each other.

   This protocol is layered on top of TCP.  It uses a different TCP
   connection for each simultaneous transaction that is shared between
   two nodes; however, after a transaction has ended, the TCP connection
   can be reused for a different transaction.


Transaction Identifiers

   Unfortunately, there is no globally-accepted standard for the format
   of a transaction identifier; various transaction managers have their
   own proprietary formats.  Therefore, for the purposes of this
   protocol, a transaction identifier is any sequence of printable
   ASCII characters (octets with values in the range 33 through 126,
   inclusive). A transaction manager may map its internal transaction
   identifiers into this printable sequence in any manner it sees fit.
   Furthermore, each party in a superior/subordinate relationship gets
   to assign its own identifier to the transaction; these identifiers
   are exchanged when the relationship is first established.  Thus, a
   transaction manager gets to use its own format of transaction
   identifier internally, but it must remember a foreign transaction
   identifier for each superior/subordinate relationship in which it is
   involved.


Pushing vs. Pulling Transactions

   Suppose that some program on node "A" has created a transaction, and
   wants some program on node "B" to do some work as part of the
   transaction.  There are two classical ways that he does this,
   referred to as the "push" model and the "pull" model.

   In the "push" model, the program on A first asks his transaction
   manager to export the transaction to node B.  A's transaction manager
   sends a message to B's TM asking it to instantiate the transaction as
   a subordinate of A, and return its name for the transaction.  The
   program on A then sends a message to its counterpart on B on the
   order of "Do some work, and make it part of the transaction that your

Lyon                                                           [Page 2]


Internet-Draft      Transaction Internet Protocol      November 4, 1996

   transaction manager already knows of by the name ...".  Because A's
   TM knows that it sent the transaction to B's TM, A's TM knows to
   involve B's TM in the two-phase commit process.

   In the "pull" model, the program on A merely sends a message to B on
   the order of "Do some work, and make it part of the transaction that
   my TM knows by the name ...".  The program on B asks its TM to enlist
   in the transaction.  At that time, B's TM will "pull" the transaction
   over from A.  As a result of this pull, A's TM knows to involve B's
   TM in the two-phase commit process.

   The protocol proposed here supports both the "push" and "pull"
   models.


Endpoint Identification

   In certain cases after TCP connection failures, one of the parties to
   the connection may have a responsibility to re-establish a connection
   to the other party in order to complete the two-phase-commit
   protocol.  If the party that initiated the original connection needs
   to re-establish it, the job is easy: he merely establishes a
   connection in the same way that he originally did it.  However, if
   the other party needs to re-establish the connection, he needs to
   know how to contact the initiator of the original connection.  He
   gets this information in one of two ways:

1. If he had never received an IDENTIFY command on the original
   connection, he will use the IP address from the original connection,
   and the standard transaction manager port number.  [UNDONE:  This
   standard port number is not yet assigned; we are temporarily using
   port 6789.]

2. If he had received a valid IDENTIFY command on the original
   connection, he will use the IP address and port number specified (or
   implied) in that command.

   An <endpoint identifier> as used in the IDENTIFY (and a few other)
   commands has one of the following formats:
      <dns name>
      <ip address>
      <dns name>:<port number>
      <ip address>:<port number>

   A <dns name> is a standard name, acceptable to the domain name
   service. It must be sufficiently qualified to be useful to the
   receiver of the command.

   An <ip address> is an Internet address, in the usual form: four
   decimal numbers separated by period characters.

   The <port number> is a decimal number specifying the port at which
   the transaction manager is listening for requests to establish TCP
   sessions.  If the port number is omitted from the endpoint

Lyon                                                           [Page 3]


Internet-Draft      Transaction Internet Protocol      November 4, 1996

   identifier, the standard transaction service port number is assumed.


States of a connection

   At any instant, only one party on the connection is allowed to send
   commands, while the other party is only allowed to respond to
   commands that he receives.  Throughout this document, the party that
   is allowed to send commands is called "primary"; the other party is
   called "secondary".  Initially, the party that initiated the
   connection is primary; however, a few commands cause the roles to
   switch.

   At any instant, a connection is in one of the following states.
   From the point of view of the secondary party, the state changes when
   he sends a reply; from the point of view of the primary party, the
   state changes when he receives a reply.

   Initial:  a newly created connection starts out in this state.  A
      connection also returns to this state when its previous work is
          completed.  Upon entry to this state, the party that initiated the
          connection becomes primary, and the other party becomes secondary.
          There is no transaction associated with the connection in this
          state.  From this state, the primary can send any of the following
           commands:  IDENTIFY, BEGIN, PUSH, PULL, PULLFROM, QUERY and
      RECONNECT.

   Begun:  In this state, the connection is associated with an active
      transaction, which can only be completed by a one-phase protocol.
          A BEGUN response to a BEGIN command places the connection into
          this state.  Failure of the connection in Begun state implies that
          the transaction will be aborted.  From this state, the primary can
          send an ABORT, COMMIT or PUSHTO command.

   Enlisted: In this state, the connection is associated with an active
      transaction, which can only be completed by a two-phase protocol.
          A PUSHED response to a PUSH command, a PULLED response to a PULL
      command, or a PULLEDAS response to a PULLFROM command places the
          connection into this state.  Failure of the connection in Enlisted
          state implies that the transaction will be aborted.  From this
          state, the primary can send an ABORT, PREPARE or PUSHTO command.

   Prepared: In this state, the connection is associated with a
      transaction that has been prepared. A PREPARED response to a
          PREPARE command, or a RECONNECTED response to a RECONNECT command
          places the connection into this state.  Unlike other states,
          failure of the connection in this state does not cause the
          transaction to automatically abort.

   Error: In this state, a protocol error has occurred, and the
      connection is no longer useful.



Lyon                                                           [Page 4]


Internet-Draft      Transaction Internet Protocol      November 4, 1996

Protocol Versioning

   This document describes version 1 of the protocol. In order to
   accommodate future versions, both parties in the conversation can
   exchange the highest version number that each understands.  After
   such an exchange, communication can occur using the smaller of the
   highest version numbers (i.e., the highest version number that both
   understand).  This exchange is optional, and occurs using the
   IDENTIFY command (and IDENTIFIED response).  In the absence of such
   an exchange, communcation is assumed to be using version 1 of the
   protocol.

   If the highest version supported by one party is considered obsolete
   and no longer supported by the other party, no useful communication
   can occur.  In this case, the newer party should merely drop the
   connection.


Commands and Responses

   All commands and responses consist of one line of ASCII text, using
   only octets with values in the range 32 through 127 inclusive,
   followed by either a CR (an octect with value 13) or an LR (an octet
   with value 10).  Each line can be split up into one or more "words",
   where each word is successive words are separated by one or more
   space octets (value 32).

   Arbitrary numbers of spaces at the beginning and/or end of each line
   are allowed, and ignored.

   Lines that are empty, or consist entirely of spaces are ignored.
   (One implication of this is that you can terminate lines with both a
   CR and an LF if desired; the LF will be treated as terminating an
   empty line, and ignored.)

   In all cases, the first word of each line indicates the type of
   command or response; all defined commands and responses consist of
   upper-case letters only.

   For some commands and responses, subsequent words convey parameters
   for the command or response; each command and response takes a fixed
   number of parameters.

   All words on a command or response line after the last defined word
   are totally ignored.  These can be used to pass human-readable
   information for debugging or other purposes.

   Following is a list of all valid commands, and all possible
   responses to each:

   ABORT

      This command is valid in the Begun, Enlisted, and Prepared states.
          It informs the secondary that the current transaction of the

Lyon                                                           [Page 5]


Internet-Draft      Transaction Internet Protocol      November 4, 1996

          connection will abort.  Possible responses are:

      ABORTED
         The transaction has aborted; the connection enters Initial
                 state, and the initiator of the connection becomes primary.

      ERROR
         The command was issued in the wrong state, or was malformed.
                 The connection enters the Error state.

   BEGIN

      This command is valid only in the Initial state. It asks the
          secondary to create a new transaction, which will be completed
          with a one-phase protocol.  Possible responses are:

      BEGUN  <transaction identifier>
         A new transaction has been successfully begun, and that
                 transaction is now the current transaction of the connection.
                 The connection enters Begun state.

      NOTBEGUN
         A new transaction could not be begun; the connection remains in
                 Initial state.

      ERROR
         The command was issued in the wrong state, or was malformed.
                 The connection enters the Error state.


   COMMIT

      This command is valid in the Begun or Prepared states.  In the
          Begun state, it asks the secondary to attempt to commit the
          transaction; in the Prepared state, it informs the secondary that
          the transaction has committed.  Possible responses are:

      ABORTED
         This response is possible only from the Begun state.  It
                 indicates that some party has vetoed the commitment of the
                 transaction, so it has been aborted instead of committing.  The
         connection enters the Initial state.

      COMMITTED
         This response indicates that the transaction has been
                 committed, and that the primary no longer has any
                 responsibilities to the secondary with respect to the
                 transaction.  The connection enters the Initial state.

      ERROR
         The command was issued in the wrong state, or was malformed.
                 The connection enters the Error state.


Lyon                                                           [Page 6]


Internet-Draft      Transaction Internet Protocol      November 4, 1996

   ERROR

      This command is valid in any state; it informs the secondary that
          a previous response was not recognized or was badly formed.  A
          secondary should not respond to this command.  The connection
          enters Error state.

   IDENTIFY <protocol version> <primary's endpoint identifier>

      This commend is valid only in the Initial state; it informs the
          secondary party of the highest protocol version supported by the
          primary, and of an address at which the primary can be reached
          should the secondary ever need to initiate a connection.  Possible
           responses are:

      IDENTIFIED <protocol version>
         The secondary has saved the identification.  The response
                 contains the highest protocol version supported by the
                 secondary.  All future communication is assumed to take place
                 using the smaller of the protocol versions in the IDENTIFY
         command and the IDENTIFIED response.  The connection remains in
                 Initial state.

      ERROR
         The command was issued in the wrong state, or was malformed.
                 The connection enters Error state.

   PREPARE

      This command is valid only in the Enlisted state; it requests the
          secondary to prepare the transaction for commitment (phase one of
          two-phase commit).  Possible responses are:

      PREPARED
         The subordinate has prepared the transaction; the connection
                 enters PREPARED state.

      ABORTED
         The subordinate has vetoed committing the transaction.  The
                 connection enters the Initial state, and the connection
                 initiator becomes primary.  After this response, the superior
                 has no responsibilities to the subordinate with respect to the
                 transaction.

      READONLY
         The subordinate no longer cares whether the transaction commits
                 or aborts.  The connection  enters the Initial state, and the
                 connection initiator becomes primary.  After this response, the
                 superior has no responsibilities to the subordinate with
                 respect to the transaction.

      ERROR
         The command was issued in the wrong state, or was malformed.
                 The connection enters the Error state.

Lyon                                                           [Page 7]


Internet-Draft      Transaction Internet Protocol      November 4, 1996

   PULL  <superior's transaction identifier>
         <subordinate's transaction identifier>

      This command is only valid in Initial state.  This command seeks
          to establish a superior/subordinate relationship in a transaction,
          with the primary party of the connection as the subordinate (i.e.,
          he is pulling a transaction from the secondary party).  Possible
          responses are:

      PULLED
         The relationship has been established.  Upon receipt of this
                 response, the specified transaction becomes the current
                 transaction of the connection, and the connection enters
         Enlisted state.  Additionally, the roles of primary and
                 secondary become reversed.  (That is, the superior becomes the
                 primary for the connection.)

      NOTPULLED
         The relationship has not been established (possibly, because
                 the secondary party no longer has the requested transaction).
                 The connection remains in Initial state.

      ERROR
         The command was issued in the wrong state, or was malformed.
                 The connection enters the Error state.

   PULLFROM  <meta-superior's endpoint identifier>
             <meta-superior's transaction identifier>
             <subordinate's transaction identifier>

      This command is valid only in Initial state.  It seeks to
          establish a superior/subordinate relationship in a transaction,
          with the primary party of the connection as the subordinate.  If
          the secondary party does not already know about the transaction,
          he is requested PULL the transaction from the specified
          meta-superior, then establish the relationship.  Possible
          responses are:

      PULLEDAS  <superior's transaction identifier>
         The relationship has been established, and the superior is
                 returning the identifier by which he knows the transaction
                 (this may or may not be the same as the meta-superior's
                 identifier).  The transaction becomes the current transaction
         of the connection, the connection enters Enlisted state, and
                 the superior becomes primary on the connection.

      NOTPULLED
         The relationship could not be established.  The connection
                 remains in Initial state.

      ERROR
         The command was issued in the wrong state, or was malformed.
                 The connection enters the Error state.


Lyon                                                           [Page 8]


Internet-Draft      Transaction Internet Protocol      November 4, 1996

   PUSH  <superior's transaction>

      This command is valid only in Initial state.  It seeks to
          establish a superior/subordinate relationship in a transaction
          with the primary as the superior.  Possible responses are:

      PUSHED  <subordinate's transaction identifier>
         The relationship has been established, and identifier by which
                 the subordinate knows the transaction is returned.  The
                 transaction becomes current for the connection, and the
                 connection enters Enlisted state.

      ALREADYPUSHED  <subordinate's transaction>
         The relationship has been established, and the identifier by
                 which the subordinate knows the transaction is returned.
                 However, the subordinate already knows about the transaction,
         and is expecting the two-phase commit protocol to arrive via a
                 different connection.  In this case, the connection remains in
                 Initial state.

      NOTPUSHED
         The relationship could not be established.  The connection
                 remains in Initial state.

      ERROR
         The command was issued in the wrong state, or was malformed.
                 The connection enters Error state.

   PUSHTO  <meta-subordinate's endpoint identifier>

      This command is valid only in Begun and Enlisted states. It
          requests the secondary to establish a superior/subordinate
          relationship with the specified third party.  Possible responses
          are:

      PUSHEDAS <meta-subordinate's transaction identifier>
         The relationship has been established, and the identifier by
                 which the meta-subordinate knows the transaction is returned.
                 The connection remains in Begun or Enlisted state.

      NOTPUSHED
         The secondary was unable to establish the relationship.  The
                 connection remains in Begun or Enlisted state.

      ERROR
         The command was issued in the wrong state, or was malformed.
                 The connection enters ERROR state.

   QUERY  <superior's transaction identifier>

      This command is valid only in the Initial state.  A subordinate
          uses this command to determine whether a specific transaction
          still exists at the superior.  Possible responses are:


Lyon                                                           [Page 9]


Internet-Draft      Transaction Internet Protocol      November 4, 1996

      QUERIEDEXISTS
         The transaction still exists.  The connection remains in
                 Initial state.

      QUERIEDNOTFOUND
         The transaction no longer exists.  The connection remains in
                 Initial state.

      ERROR
         The command was issued in the wrong state, or was malformed.
                 The connection enters Error state.

   RECONNECT <subordinate's transaction identifier>

      This command is valid only in the Initial state.  A superior uses
          the command to re-establish a connection for a transaction, when
          the previous connection was lost during Prepared state.  Possible
      responses are:

      RECONNECTED
         The subordinate accepts the reconnection.  The conversation
                 enters Prepared state.

      NOTRECONNECTED
         The subordinate no longer knows about the transaction.  The
                 conversation remains in Initial state.

      ERROR
         The command was issued in the wrong state, or was malformed.
                 The connection enters Error state.


Error Handling

   If either party receives a line that it cannot understand (either a
   command or a response), it should respond with a line starting with
   the word "ERROR"; if either party receives a line starting with
   "ERROR", it should not send anything more, but should close the
   connection.  Receipt of an ERROR line indicates that the other party
   believes that you have not properly implemented the protocol.
   Regardless of which side is at fault, further communication is
   impossible.


Connection Failure

   Depending on the state of the connection, transaction managers will
   need to take various actions when the connection fails.

   If the connection fails in Initial state, the connection does not
   refer to a transaction.  No action is necessary.

   If the connection fails in Begun or Enlisted state, each party will
   abort the transaction.

Lyon                                                          [Page 10]


Internet-Draft      Transaction Internet Protocol      November 4, 1996


   If the connection fails in Prepared state, then the appropriate
   action is different for the superior and subordinate in the
   transaction.

   If the superior determines that the transaction commits, then it
   must eventually establish a new    connection to the subordinate, and
   send a RECONNECT command for the transaction.  If it receives a
   NOTRECONNECTED response, it need do nothing else.  However, if it
   receives a RECONNECTED response, it must send a COMMIT request and
   receive a COMMITTED response.


   If the superior determines that the transaction aborts, it is allowed
   to (but not required to) establish a new session and send a RECONNECT
   command for the transaction.  If it receives a RECONNECTED response,
   it should send an ABORT command.

   The above definition allows the superior to reestablish the
   connection before it knows the outcome of the transaction, if it
   finds that convenient.  Having succeeded in a RECONNECT command, the
   connection is back in Prepared state, and the superior can send a
   COMMIT or ABORT command as appropriate when it knows the transaction
   outcome.

   If a subordinate notices a connection failure in Prepared state, then
   it should periodically attempt to create a new connection to the
   superior and send a QUERY command for the transaction.  It should
   continue doing this until one of the following two events occurs:

   1. It receives a QUERIEDNOTFOUND response from the superior.  In this
      case, the subordinate should abort the transaction.

   2. The superior, on some connection that it initiated, sends a
      RECONNECT command for the transaction to the subordinate.  In this
          case, the subordinate can expect to learn the outcome of the
          transaction on this new connection.  If this new connection should
      fail before the subordinate learns the outcome of the transaction,
          it should again start sending QUERY commands.


References

   [1]  Gray, J. and A. Reuter (1993), Transaction Processing: Concepts
        and Techniques.  San Francisco, CA: Morgan Kaufmann Publishers.
                ISBN 1-55860-190-2.


Security Considerations

   If a system implements this protocol, it is in essence allowing any
   other system to attempt to reach an atomic agreement about some piece
   of work.  However, since this protocol itself does not cause the work
   to occur, the security implications are minimal.  In particular, they

Lyon                                                          [Page 11]


Internet-Draft      Transaction Internet Protocol      November 4, 1996

   fall into the following two categories:

   1. Someone PUSHED a new transaction to us that we don't want.
      Depending on his correctness or intentions, he may or may not ever
          complete it.  Thus, an arbitrary computer may cause us to save a
          little bit of state.  An implementation concerned about this will
          probably drop any connection that has not been completed within a
          small time.

   2. Someone PULLED a transaction from us when we didn't want him to.
      In this case, he will become involved in the atomic committment
          protocol.  At worst, he may cause a transaction to abort that
          otherwise would have committed.  Since transaction managers
          traditionally reserve the right to abort any transaction for any
          reason they see fit, this does not represent a disaster to the
          applications.  However, if done frequently, it may represent a
      denial-of-service attack.  Implementations that are concerned
          about this can use cryptographic techniques to generate hard-to-
          guess transaction identifiers.  (If an interloper cannot guess a
      transaction identifier, he can't join the transaction.)


Author's Address

   Jim Lyon
   Microsoft Corporation
   One Microsoft Way
   Redmond, WA  98052-6399, USA

   Phone: +1 (206) 936 0867
   Fax:   +1 (206) 936 7329
   Email: JimLyon@Microsoft.Com























Lyon                                                          [Page 12]