idnits 2.17.1 draft-lyon-itp-nodes-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-19) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 126 instances of lines with control characters in the document. ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 362 has weird spacing: '...nection enter...' == Line 537 has weird spacing: '...h a new con...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 4, 1996) is 10028 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. '1' Summary: 9 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group J. Lyon 2 Internet-Draft Microsoft 3 November 4, 1996 4 Expires in 6 months 6 Transaction Internet Protocol 8 Status of this Memo 10 This document is an Internet-Draft. Internet-Drafts are working 11 documents of the Internet Engineering Task Force (IETF), its areas, 12 and its working groups. Note that other groups may also distribute 13 working documents as Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six months 16 and may be updated, replaced, or obsoleted by other documents at any 17 time. It is inappropriate to use Internet-Drafts as reference 18 material or to cite them other than as "work in progress." 20 To learn the current status of any Internet-Draft, please check the 21 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 22 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 23 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 24 ftp.isi.edu (US West Coast). 26 Distribution of this document is unlimited. Please send comments to 27 the author at . 29 Abstract 31 In many applications where different nodes cooperate on some work, 32 there is a need to guarantee that the work happens atomically. that 33 is, each node must reach the same conclusion as to whether the work 34 is to be completed, even in the face of failures. This document 35 proposes a simple, easily-implemented protocol for achieving this 36 end. 38 Introduction 40 The standard method for achieving atomic committment is the two-phase 41 commit protocol; see [1] for an introduction to atomic commitment and 42 two-phase commit protocols. 44 Numerous two-phase commit protocols have been implemented over the 45 years. However, none of them has become widely used in the Internet, 46 due mainly to their complexity. Most of that complexity comes from 47 the fact that the two-phase commit protocol is bundled together with 48 a specific program-to-program communication protocol, and that 49 protocol lives on top of a very large infrastructure. 51 This memo proposes a very simple two-phase commit protocol. It 52 achieves its simplicity by specifying only how different nodes agree 53 on the outcome of a transaction; it allows (even requires) that the 54 subject matter on which the nodes are agreeing be communicated via 55 other protocols. By doing so, we avoid all of the issues related to 56 application communication semantics, data representation, and 57 security (to name just a few). 59 It is envisioned that this protocol will be used mainly for a 60 transaction manager on one Internet node to communicate with a 61 transaction manager on another node. While it is possible to use 62 this protocol for application programs and/or resource managers to 63 speak to transaction managers, this communication is usually 64 intra-node, and most transaction managers already have more-than- 65 adequate interfaces for the task. 67 While we do not expect this protocol to replace existing ones, we do 68 expect that it will be relatively easy for many existing 69 heterogeneous transaction managers to implement this protocol for 70 communication with each other. 72 This protocol is layered on top of TCP. It uses a different TCP 73 connection for each simultaneous transaction that is shared between 74 two nodes; however, after a transaction has ended, the TCP connection 75 can be reused for a different transaction. 77 Transaction Identifiers 79 Unfortunately, there is no globally-accepted standard for the format 80 of a transaction identifier; various transaction managers have their 81 own proprietary formats. Therefore, for the purposes of this 82 protocol, a transaction identifier is any sequence of printable 83 ASCII characters (octets with values in the range 33 through 126, 84 inclusive). A transaction manager may map its internal transaction 85 identifiers into this printable sequence in any manner it sees fit. 86 Furthermore, each party in a superior/subordinate relationship gets 87 to assign its own identifier to the transaction; these identifiers 88 are exchanged when the relationship is first established. Thus, a 89 transaction manager gets to use its own format of transaction 90 identifier internally, but it must remember a foreign transaction 91 identifier for each superior/subordinate relationship in which it is 92 involved. 94 Pushing vs. Pulling Transactions 96 Suppose that some program on node "A" has created a transaction, and 97 wants some program on node "B" to do some work as part of the 98 transaction. There are two classical ways that he does this, 99 referred to as the "push" model and the "pull" model. 101 In the "push" model, the program on A first asks his transaction 102 manager to export the transaction to node B. A's transaction manager 103 sends a message to B's TM asking it to instantiate the transaction as 104 a subordinate of A, and return its name for the transaction. The 105 program on A then sends a message to its counterpart on B on the 106 order of "Do some work, and make it part of the transaction that your 107 transaction manager already knows of by the name ...". Because A's 108 TM knows that it sent the transaction to B's TM, A's TM knows to 109 involve B's TM in the two-phase commit process. 111 In the "pull" model, the program on A merely sends a message to B on 112 the order of "Do some work, and make it part of the transaction that 113 my TM knows by the name ...". The program on B asks its TM to enlist 114 in the transaction. At that time, B's TM will "pull" the transaction 115 over from A. As a result of this pull, A's TM knows to involve B's 116 TM in the two-phase commit process. 118 The protocol proposed here supports both the "push" and "pull" 119 models. 121 Endpoint Identification 123 In certain cases after TCP connection failures, one of the parties to 124 the connection may have a responsibility to re-establish a connection 125 to the other party in order to complete the two-phase-commit 126 protocol. If the party that initiated the original connection needs 127 to re-establish it, the job is easy: he merely establishes a 128 connection in the same way that he originally did it. However, if 129 the other party needs to re-establish the connection, he needs to 130 know how to contact the initiator of the original connection. He 131 gets this information in one of two ways: 133 1. If he had never received an IDENTIFY command on the original 134 connection, he will use the IP address from the original connection, 135 and the standard transaction manager port number. [UNDONE: This 136 standard port number is not yet assigned; we are temporarily using 137 port 6789.] 139 2. If he had received a valid IDENTIFY command on the original 140 connection, he will use the IP address and port number specified (or 141 implied) in that command. 143 An as used in the IDENTIFY (and a few other) 144 commands has one of the following formats: 145 146 147 : 148 : 150 A is a standard name, acceptable to the domain name 151 service. It must be sufficiently qualified to be useful to the 152 receiver of the command. 154 An is an Internet address, in the usual form: four 155 decimal numbers separated by period characters. 157 The is a decimal number specifying the port at which 158 the transaction manager is listening for requests to establish TCP 159 sessions. If the port number is omitted from the endpoint 160 identifier, the standard transaction service port number is assumed. 162 States of a connection 164 At any instant, only one party on the connection is allowed to send 165 commands, while the other party is only allowed to respond to 166 commands that he receives. Throughout this document, the party that 167 is allowed to send commands is called "primary"; the other party is 168 called "secondary". Initially, the party that initiated the 169 connection is primary; however, a few commands cause the roles to 170 switch. 172 At any instant, a connection is in one of the following states. 173 From the point of view of the secondary party, the state changes when 174 he sends a reply; from the point of view of the primary party, the 175 state changes when he receives a reply. 177 Initial: a newly created connection starts out in this state. A 178 connection also returns to this state when its previous work is 179 completed. Upon entry to this state, the party that initiated the 180 connection becomes primary, and the other party becomes secondary. 181 There is no transaction associated with the connection in this 182 state. From this state, the primary can send any of the following 183 commands: IDENTIFY, BEGIN, PUSH, PULL, PULLFROM, QUERY and 184 RECONNECT. 186 Begun: In this state, the connection is associated with an active 187 transaction, which can only be completed by a one-phase protocol. 188 A BEGUN response to a BEGIN command places the connection into 189 this state. Failure of the connection in Begun state implies that 190 the transaction will be aborted. From this state, the primary can 191 send an ABORT, COMMIT or PUSHTO command. 193 Enlisted: In this state, the connection is associated with an active 194 transaction, which can only be completed by a two-phase protocol. 195 A PUSHED response to a PUSH command, a PULLED response to a PULL 196 command, or a PULLEDAS response to a PULLFROM command places the 197 connection into this state. Failure of the connection in Enlisted 198 state implies that the transaction will be aborted. From this 199 state, the primary can send an ABORT, PREPARE or PUSHTO command. 201 Prepared: In this state, the connection is associated with a 202 transaction that has been prepared. A PREPARED response to a 203 PREPARE command, or a RECONNECTED response to a RECONNECT command 204 places the connection into this state. Unlike other states, 205 failure of the connection in this state does not cause the 206 transaction to automatically abort. 208 Error: In this state, a protocol error has occurred, and the 209 connection is no longer useful. 211 Protocol Versioning 213 This document describes version 1 of the protocol. In order to 214 accommodate future versions, both parties in the conversation can 215 exchange the highest version number that each understands. After 216 such an exchange, communication can occur using the smaller of the 217 highest version numbers (i.e., the highest version number that both 218 understand). This exchange is optional, and occurs using the 219 IDENTIFY command (and IDENTIFIED response). In the absence of such 220 an exchange, communcation is assumed to be using version 1 of the 221 protocol. 223 If the highest version supported by one party is considered obsolete 224 and no longer supported by the other party, no useful communication 225 can occur. In this case, the newer party should merely drop the 226 connection. 228 Commands and Responses 230 All commands and responses consist of one line of ASCII text, using 231 only octets with values in the range 32 through 127 inclusive, 232 followed by either a CR (an octect with value 13) or an LR (an octet 233 with value 10). Each line can be split up into one or more "words", 234 where each word is successive words are separated by one or more 235 space octets (value 32). 237 Arbitrary numbers of spaces at the beginning and/or end of each line 238 are allowed, and ignored. 240 Lines that are empty, or consist entirely of spaces are ignored. 241 (One implication of this is that you can terminate lines with both a 242 CR and an LF if desired; the LF will be treated as terminating an 243 empty line, and ignored.) 245 In all cases, the first word of each line indicates the type of 246 command or response; all defined commands and responses consist of 247 upper-case letters only. 249 For some commands and responses, subsequent words convey parameters 250 for the command or response; each command and response takes a fixed 251 number of parameters. 253 All words on a command or response line after the last defined word 254 are totally ignored. These can be used to pass human-readable 255 information for debugging or other purposes. 257 Following is a list of all valid commands, and all possible 258 responses to each: 260 ABORT 262 This command is valid in the Begun, Enlisted, and Prepared states. 263 It informs the secondary that the current transaction of the 264 connection will abort. Possible responses are: 266 ABORTED 267 The transaction has aborted; the connection enters Initial 268 state, and the initiator of the connection becomes primary. 270 ERROR 271 The command was issued in the wrong state, or was malformed. 272 The connection enters the Error state. 274 BEGIN 276 This command is valid only in the Initial state. It asks the 277 secondary to create a new transaction, which will be completed 278 with a one-phase protocol. Possible responses are: 280 BEGUN 281 A new transaction has been successfully begun, and that 282 transaction is now the current transaction of the connection. 283 The connection enters Begun state. 285 NOTBEGUN 286 A new transaction could not be begun; the connection remains in 287 Initial state. 289 ERROR 290 The command was issued in the wrong state, or was malformed. 291 The connection enters the Error state. 293 COMMIT 295 This command is valid in the Begun or Prepared states. In the 296 Begun state, it asks the secondary to attempt to commit the 297 transaction; in the Prepared state, it informs the secondary that 298 the transaction has committed. Possible responses are: 300 ABORTED 301 This response is possible only from the Begun state. It 302 indicates that some party has vetoed the commitment of the 303 transaction, so it has been aborted instead of committing. The 304 connection enters the Initial state. 306 COMMITTED 307 This response indicates that the transaction has been 308 committed, and that the primary no longer has any 309 responsibilities to the secondary with respect to the 310 transaction. The connection enters the Initial state. 312 ERROR 313 The command was issued in the wrong state, or was malformed. 314 The connection enters the Error state. 316 ERROR 318 This command is valid in any state; it informs the secondary that 319 a previous response was not recognized or was badly formed. A 320 secondary should not respond to this command. The connection 321 enters Error state. 323 IDENTIFY 325 This commend is valid only in the Initial state; it informs the 326 secondary party of the highest protocol version supported by the 327 primary, and of an address at which the primary can be reached 328 should the secondary ever need to initiate a connection. Possible 329 responses are: 331 IDENTIFIED 332 The secondary has saved the identification. The response 333 contains the highest protocol version supported by the 334 secondary. All future communication is assumed to take place 335 using the smaller of the protocol versions in the IDENTIFY 336 command and the IDENTIFIED response. The connection remains in 337 Initial state. 339 ERROR 340 The command was issued in the wrong state, or was malformed. 341 The connection enters Error state. 343 PREPARE 345 This command is valid only in the Enlisted state; it requests the 346 secondary to prepare the transaction for commitment (phase one of 347 two-phase commit). Possible responses are: 349 PREPARED 350 The subordinate has prepared the transaction; the connection 351 enters PREPARED state. 353 ABORTED 354 The subordinate has vetoed committing the transaction. The 355 connection enters the Initial state, and the connection 356 initiator becomes primary. After this response, the superior 357 has no responsibilities to the subordinate with respect to the 358 transaction. 360 READONLY 361 The subordinate no longer cares whether the transaction commits 362 or aborts. The connection enters the Initial state, and the 363 connection initiator becomes primary. After this response, the 364 superior has no responsibilities to the subordinate with 365 respect to the transaction. 367 ERROR 368 The command was issued in the wrong state, or was malformed. 369 The connection enters the Error state. 371 PULL 372 374 This command is only valid in Initial state. This command seeks 375 to establish a superior/subordinate relationship in a transaction, 376 with the primary party of the connection as the subordinate (i.e., 377 he is pulling a transaction from the secondary party). Possible 378 responses are: 380 PULLED 381 The relationship has been established. Upon receipt of this 382 response, the specified transaction becomes the current 383 transaction of the connection, and the connection enters 384 Enlisted state. Additionally, the roles of primary and 385 secondary become reversed. (That is, the superior becomes the 386 primary for the connection.) 388 NOTPULLED 389 The relationship has not been established (possibly, because 390 the secondary party no longer has the requested transaction). 391 The connection remains in Initial state. 393 ERROR 394 The command was issued in the wrong state, or was malformed. 395 The connection enters the Error state. 397 PULLFROM 398 399 401 This command is valid only in Initial state. It seeks to 402 establish a superior/subordinate relationship in a transaction, 403 with the primary party of the connection as the subordinate. If 404 the secondary party does not already know about the transaction, 405 he is requested PULL the transaction from the specified 406 meta-superior, then establish the relationship. Possible 407 responses are: 409 PULLEDAS 410 The relationship has been established, and the superior is 411 returning the identifier by which he knows the transaction 412 (this may or may not be the same as the meta-superior's 413 identifier). The transaction becomes the current transaction 414 of the connection, the connection enters Enlisted state, and 415 the superior becomes primary on the connection. 417 NOTPULLED 418 The relationship could not be established. The connection 419 remains in Initial state. 421 ERROR 422 The command was issued in the wrong state, or was malformed. 423 The connection enters the Error state. 425 PUSH 427 This command is valid only in Initial state. It seeks to 428 establish a superior/subordinate relationship in a transaction 429 with the primary as the superior. Possible responses are: 431 PUSHED 432 The relationship has been established, and identifier by which 433 the subordinate knows the transaction is returned. The 434 transaction becomes current for the connection, and the 435 connection enters Enlisted state. 437 ALREADYPUSHED 438 The relationship has been established, and the identifier by 439 which the subordinate knows the transaction is returned. 440 However, the subordinate already knows about the transaction, 441 and is expecting the two-phase commit protocol to arrive via a 442 different connection. In this case, the connection remains in 443 Initial state. 445 NOTPUSHED 446 The relationship could not be established. The connection 447 remains in Initial state. 449 ERROR 450 The command was issued in the wrong state, or was malformed. 451 The connection enters Error state. 453 PUSHTO 455 This command is valid only in Begun and Enlisted states. It 456 requests the secondary to establish a superior/subordinate 457 relationship with the specified third party. Possible responses 458 are: 460 PUSHEDAS 461 The relationship has been established, and the identifier by 462 which the meta-subordinate knows the transaction is returned. 463 The connection remains in Begun or Enlisted state. 465 NOTPUSHED 466 The secondary was unable to establish the relationship. The 467 connection remains in Begun or Enlisted state. 469 ERROR 470 The command was issued in the wrong state, or was malformed. 471 The connection enters ERROR state. 473 QUERY 475 This command is valid only in the Initial state. A subordinate 476 uses this command to determine whether a specific transaction 477 still exists at the superior. Possible responses are: 479 QUERIEDEXISTS 480 The transaction still exists. The connection remains in 481 Initial state. 483 QUERIEDNOTFOUND 484 The transaction no longer exists. The connection remains in 485 Initial state. 487 ERROR 488 The command was issued in the wrong state, or was malformed. 489 The connection enters Error state. 491 RECONNECT 493 This command is valid only in the Initial state. A superior uses 494 the command to re-establish a connection for a transaction, when 495 the previous connection was lost during Prepared state. Possible 496 responses are: 498 RECONNECTED 499 The subordinate accepts the reconnection. The conversation 500 enters Prepared state. 502 NOTRECONNECTED 503 The subordinate no longer knows about the transaction. The 504 conversation remains in Initial state. 506 ERROR 507 The command was issued in the wrong state, or was malformed. 508 The connection enters Error state. 510 Error Handling 512 If either party receives a line that it cannot understand (either a 513 command or a response), it should respond with a line starting with 514 the word "ERROR"; if either party receives a line starting with 515 "ERROR", it should not send anything more, but should close the 516 connection. Receipt of an ERROR line indicates that the other party 517 believes that you have not properly implemented the protocol. 518 Regardless of which side is at fault, further communication is 519 impossible. 521 Connection Failure 523 Depending on the state of the connection, transaction managers will 524 need to take various actions when the connection fails. 526 If the connection fails in Initial state, the connection does not 527 refer to a transaction. No action is necessary. 529 If the connection fails in Begun or Enlisted state, each party will 530 abort the transaction. 532 If the connection fails in Prepared state, then the appropriate 533 action is different for the superior and subordinate in the 534 transaction. 536 If the superior determines that the transaction commits, then it 537 must eventually establish a new connection to the subordinate, and 538 send a RECONNECT command for the transaction. If it receives a 539 NOTRECONNECTED response, it need do nothing else. However, if it 540 receives a RECONNECTED response, it must send a COMMIT request and 541 receive a COMMITTED response. 543 If the superior determines that the transaction aborts, it is allowed 544 to (but not required to) establish a new session and send a RECONNECT 545 command for the transaction. If it receives a RECONNECTED response, 546 it should send an ABORT command. 548 The above definition allows the superior to reestablish the 549 connection before it knows the outcome of the transaction, if it 550 finds that convenient. Having succeeded in a RECONNECT command, the 551 connection is back in Prepared state, and the superior can send a 552 COMMIT or ABORT command as appropriate when it knows the transaction 553 outcome. 555 If a subordinate notices a connection failure in Prepared state, then 556 it should periodically attempt to create a new connection to the 557 superior and send a QUERY command for the transaction. It should 558 continue doing this until one of the following two events occurs: 560 1. It receives a QUERIEDNOTFOUND response from the superior. In this 561 case, the subordinate should abort the transaction. 563 2. The superior, on some connection that it initiated, sends a 564 RECONNECT command for the transaction to the subordinate. In this 565 case, the subordinate can expect to learn the outcome of the 566 transaction on this new connection. If this new connection should 567 fail before the subordinate learns the outcome of the transaction, 568 it should again start sending QUERY commands. 570 References 572 [1] Gray, J. and A. Reuter (1993), Transaction Processing: Concepts 573 and Techniques. San Francisco, CA: Morgan Kaufmann Publishers. 574 ISBN 1-55860-190-2. 576 Security Considerations 578 If a system implements this protocol, it is in essence allowing any 579 other system to attempt to reach an atomic agreement about some piece 580 of work. However, since this protocol itself does not cause the work 581 to occur, the security implications are minimal. In particular, they 582 fall into the following two categories: 584 1. Someone PUSHED a new transaction to us that we don't want. 585 Depending on his correctness or intentions, he may or may not ever 586 complete it. Thus, an arbitrary computer may cause us to save a 587 little bit of state. An implementation concerned about this will 588 probably drop any connection that has not been completed within a 589 small time. 591 2. Someone PULLED a transaction from us when we didn't want him to. 592 In this case, he will become involved in the atomic committment 593 protocol. At worst, he may cause a transaction to abort that 594 otherwise would have committed. Since transaction managers 595 traditionally reserve the right to abort any transaction for any 596 reason they see fit, this does not represent a disaster to the 597 applications. However, if done frequently, it may represent a 598 denial-of-service attack. Implementations that are concerned 599 about this can use cryptographic techniques to generate hard-to- 600 guess transaction identifiers. (If an interloper cannot guess a 601 transaction identifier, he can't join the transaction.) 603 Author's Address 605 Jim Lyon 606 Microsoft Corporation 607 One Microsoft Way 608 Redmond, WA 98052-6399, USA 610 Phone: +1 (206) 936 0867 611 Fax: +1 (206) 936 7329 612 Email: JimLyon@Microsoft.Com